Plane Flow

Operate a local/self-hosted Plane workspace for product and project flow management. Use when the user wants to read or update Plane projects, issues, states...

Security Scan

The skill's code, instructions, and required environment variables are consistent with a self-hosted Plane integration and do not request unrelated credentials or install arbitrary remote artifacts.

Purpose & Capability

Name and description match the implemented behavior: bundled Python scripts talk to a Plane instance and perform read/write operations. Required binaries (python3) and env vars (PLANE_BASE_URL, PLANE_API_TOKEN, PLANE_WORKSPACE_ID) are appropriate for this purpose.

Instruction Scope

SKILL.md and the CLI scripts constrain runtime behavior to contacting the configured Plane instance and optionally reading files explicitly provided for attachment uploads. The instructions do not direct the agent to read unrelated system files or exfiltrate data to unexpected endpoints.

Install Mechanism

This is an instruction-only skill with bundled Python scripts; there is no high-risk download/install step. It relies on common Python packages (requests, optional PyYAML/markdown) which is proportionate to the task.

Credentials

The skill requires only the expected Plane-related env vars (base URL, API token, workspace ID). No other unrelated secrets or credentials are requested. An optional PLANE_CONFIG_FILE is clearly documented for local aliasing/mappings.

Persistence & Privilege

The skill does not request always:true and does not modify other skills' configurations. The only write behavior is an admin-only init helper that writes ~/.plane_config.yaml when intentionally run.

Assessment

This package appears to do what it says: connect to a self-hosted Plane instance and manage projects/issues. Before installing or enabling it for non-technical users, have an administrator: 1) provision a least-privileged PLANE_API_TOKEN and confirm the token scope, 2) set PLANE_BASE_URL to your internal Plane endpoint (network-restrict this endpoint if possible), 3) validate connectivity with python3 scripts/test_connection.py, and 4) only run scripts/init_config.py as an admin who understands it will write ~/.plane_config.yaml. Be cautious when uploading attachments (the skill reads files you explicitly provide). If you need stronger assurance, review the token scope and run the scripts in a controlled environment first.

Overview

Use this skill to work with a locally integrated Plane instance through the bundled scripts in scripts/. It supports safe PM operations first, then controlled writes: read projects/issues, summarize a project, create issues, update descriptions, move states, assign owners, set priority, and set labels.

Operating model

This skill is designed around two roles:

1. Administrator / technical owner

The administrator configures the Plane connection for the environment. That setup includes:

• PLANE_BASE_URL
• PLANE_API_TOKEN
• PLANE_WORKSPACE_ID
• optional PLANE_CONFIG_FILE

The administrator may also use bundled helper scripts in scripts/ for local setup or debugging.

2. Business user

Once the environment has been configured, business users should be able to use this skill conversationally for backlog, issue, sprint, and project workflow tasks. They should not need to deal with environment variables or CLI commands.

Runtime expectations

• Requires python3
• Requires Python package: requests
• Optional Python packages:
  • PyYAML (only if using PLANE_CONFIG_FILE)
  • markdown (used for markdown-to-HTML rendering)
• Requires administrator-provided environment variables:
  • PLANE_BASE_URL
  • PLANE_API_TOKEN
  • PLANE_WORKSPACE_ID
• Optional environment variable:
  • PLANE_CONFIG_FILE

Security / behavior notes

• This skill makes network requests only to the Plane instance configured through PLANE_BASE_URL.
• It uses PLANE_API_TOKEN to authenticate against that Plane instance.
• Attachment upload features can read local files that the operator explicitly chooses to upload.
• The optional init helper can write ~/.plane_config.yaml, but only when an administrator intentionally runs scripts/init_config.py.
• If the Plane connection has not been configured yet, prefer user-facing guidance that asks for administrator setup rather than exposing raw missing-env errors to business users.

Core Capabilities

1. Read Plane workspace data

Use this skill when the user wants to:

• list Plane projects
• inspect project issues
• read a specific issue
• list states, labels, or members
• summarize a project's current status

Prefer these commands:

• python3 scripts/plane_cli.py projects list
• python3 scripts/plane_cli.py issues list --project <project>
• python3 scripts/plane_cli.py issues get --project <project> --id <issue_id>
• python3 scripts/plane_cli.py projects summary --project <project>
• python3 scripts/plane_cli.py states list --project <project>
• python3 scripts/plane_cli.py labels list --project <project>
• python3 scripts/plane_cli.py members list

2. Create and enrich issues

Use this skill when the user wants to:

• create a requirement, task, or bug in Plane
• turn meeting notes into one or more Plane issues
• add more context to an existing issue
• attach images to issue descriptions or comments

Prefer this flow:

1. Resolve the target project
2. If needed, inspect states / labels / members first
3. Create the issue
4. Optionally enrich it with description, labels, priority, assignee, or state

Prefer these commands:

• python3 scripts/plane_cli.py issues create --project <project> --title <title> --desc <desc>
• python3 scripts/plane_cli.py issues update-desc --project <project> --id <issue_id> --desc <desc>
• python3 scripts/plane_cli.py issues set-priority --project <project> --id <issue_id> --priority <priority>
• python3 scripts/plane_cli.py issues set-labels --project <project> --id <issue_id> --labels <comma-separated-labels>
• python3 scripts/plane_cli.py issues assign --project <project> --id <issue_id> --assignee <member>
• python3 scripts/plane_cli.py issues move --project <project> --id <issue_id> --state <state>

2b. Inline images in issue descriptions and comments

This skill supports uploading images and embedding them directly in issue descriptions or comments. Images are uploaded as Plane issue attachments, then embedded using Plane's native image-component nodes with alignment control.

Directive syntax (in --desc for issue descriptions)

Place [image: /path/to/image.png, <align>] anywhere in the description text:

[image: ./screenshot.png, center]   – centred block
[image: ./screenshot.png, left]     – left-aligned block
[image: ./screenshot.png, right]    – right-aligned block

Available alignments: center (default), left, right.

Examples:

# Create issue with a centred image in description
python3 scripts/plane_cli.py issues create \
  --project <project> \
  --title "Requirement with screenshot" \
  --desc "See diagram below:\n\n[image: ./diagram.png, center]"

# Create issue with left and right images
python3 scripts/plane_cli.py issues create \
  --project <project> \
  --title "Comparison" \
  --desc "Before:\n[image: ./before.png, left]\n\nAfter:\n[image: ./after.png, right]"

CLI flag syntax (for issue descriptions and comments)

Use --image <path> to attach images, with --image-align to set alignment:

# Issue with images (all same alignment)
python3 scripts/plane_cli.py issues create \
  --project <project> \
  --title "Report" \
  --desc "See attachments" \
  --image ./fig1.png \
  --image ./fig2.png \
  --image-align center

# Comment with a right-aligned image
python3 scripts/plane_cli.py comments create \
  --project <project> \
  --issue-id <issue_id> \
  --content "Screenshot:" \
  --image ./screen.png \
  --image-align right

Alignment applies to all --image flags in the same command. For mixed alignments in a single call, use the directive syntax inside --desc.

Behavior notes

• Images are uploaded as issue attachments in Plane, then embedded in description_html or comment_html using Plane's native <image-component> nodes.
• Alignment uses Plane's built-in alignment attribute (left, center, right).
• True text wrapping around floating images is not supported by Plane's editor — images are always block-level elements.
• If image embedding fails (e.g., no asset URL returned), the image is still saved as an attachment and a text note is added to the description/comment.

3. Turn PM inputs into structured Plane changes

Use this skill when the user provides:

• meeting notes
• feedback summaries
• requirement drafts
• PM action items
• triage instructions

Recommended approach:

1. Extract candidate issues from the source text
2. Group or deduplicate obvious overlaps
3. Draft issue titles and descriptions
4. Ask for confirmation only when needed for destructive or ambiguous writes
5. Create issues and enrich metadata

4. Summarize project flow

Use this skill when the user asks for:

• backlog overview
• project progress
• blocked/high-priority work
• issue status distribution
• PM-style progress summaries

Start with:

• python3 scripts/plane_cli.py projects summary --project <project>
• python3 scripts/plane_cli.py issues list --project <project>

Then transform the raw output into a concise PM summary.

Working Rules

• Always prefer the bundled Plane integration in scripts/ over inventing raw API calls unless debugging is required.
• For issue detail and issue updates, always include --project <project>; this Plane instance uses project-scoped issue detail/update routes.
• If a write fails, inspect current states / labels / members before retrying.
• Prefer single-issue updates over bulk mutation unless the user explicitly asks for batch changes.
• For ambiguous project names, resolve by listing projects first.
• For ambiguous assignees, resolve by listing members first.
• For ambiguous labels or states, resolve by listing labels/states first.
• When a description or comment includes images, prefer uploading them as issue attachments and embedding them inline using the [image: path, align] directive or --image / --image-align flags rather than linking to external URLs.

When to Inspect Raw Output

Use --raw when:

• debugging field mappings
• checking unfamiliar Plane response structures
• validating a new endpoint behavior
• confirming what IDs correspond to states, labels, or other metadata

References

• Read references/cli-usage.md for a compact command cookbook and practical examples.