Context

Source: Issue #205 — [FEATURE] Allow passing an issue URL or number to /plan-agent:planning

Developers maintain their backlog in GitHub and GitLab. When they start planning from a ticket, the current workflow is manual: open the issue, copy the title and body, paste it into /plan-agent:planning. This copy-paste step is friction every time and breaks the "issue-to-plan" loop that should feel seamless.

The planning skill already has access to the gh and glab CLIs (via the issue-agent plugin's established patterns). Adding argument detection and a new Step 0.5 — Issue Ingestion phase to SKILL.md lets the skill fetch issue data automatically whenever a URL or #n reference is detected in $ARGUMENTS, seeding the plan objective and context without any user copy-paste.

This change is purely additive to the planning skill: all existing flags and argument forms continue to work unchanged.

Objective

Ship native issue ingestion in /plan-agent:planning: when $ARGUMENTS contains a GitHub/GitLab issue URL or #n, automatically fetch the issue via gh/glab, seed the plan title from the issue title, inject the issue body as context, and record the issue URL in plan frontmatter — eliminating the copy-paste step from backlog to plan.

Steps

  1. done Update argument-hint frontmatter in SKILL.md

    Why: The argument-hint field is shown to users in autocomplete and help text. Adding <issue-url|#n> as the leading option communicates the new capability immediately without requiring users to read the full skill body.

    ✓ Verify
    Read the first 10 lines of kit/plugins/plan-agent/skills/planning/SKILL.md and confirm argument-hint now reads:
    "<issue-url|#n> | <objective> [--quick] [--no-clarify] [--no-align] [--no-interview] [--type feature|fix|refactor|docs|chore] [--template default] [--dir <path>] [--priority low|medium|high|critical]"
  2. done Add issue reference detection to the Invocation & Arguments section of SKILL.md

    Why: The skill needs clear, unambiguous detection rules so the model knows exactly which argument forms trigger issue ingestion versus plain text objectives. Three patterns cover the full surface: full GitHub URL, full GitLab URL, and bare #n/integer (with no other text present).

    ✓ Verify
    Read the Invocation & Arguments section and confirm all three patterns are documented:
    • https://github.com/<owner>/<repo>/issues/<n>
    • https://gitlab.com/<owner>/<repo>/-/issues/<n>
    • Bare #<n> or plain integer with no other text
    Also confirm the precedence rule is stated: caller-supplied extra text overrides the issue title as the objective while the issue body is still injected as context.
  3. done Insert Step 0.5 — Issue Ingestion into the Workflow section of SKILL.md

    Why: The ingestion logic must run after Step 0 (self-bootstrap / ExitPlanMode) but before Step 0b (Explore) so that when exploration runs, it already has the issue title and body available as planning inputs. Numbering it 0.5 inserts it into the existing sequence without renumbering Steps 1–8.

    ✓ Verify
    Read the Workflow section and confirm Step 0.5 is present between Step 0 and Step 0b, containing:
    • Conditional trigger: fires only when an issue reference is detected
    • GitHub branch: gh issue view <n> --repo <owner>/<repo> --json title,body,labels,assignees,milestone,url
    • GitLab branch: glab issue view <n> --repo <owner>/<repo> --output json
    • For bare #n: gh repo view --json owner,name to resolve owner/repo
    • Field mapping table: title → objective (unless caller supplied extra text), body → injected context block, labels → type hint, url → frontmatter plan-issue
    • Graceful fallback: on CLI error or non-existent issue, report the error and treat $ARGUMENTS as a plain objective string
  4. done Update Step 3 (Frontmatter) in SKILL.md to emit <meta name="plan-issue"> when an issue URL is present

    Why: Recording the source issue URL in the HTML <head> makes plans machine-readable and linkable back to their origin ticket. The plan-agent gallery index, hooks, and downstream tooling can then parse <meta name="plan-issue"> the same way they already parse plan-status and plan-type.

    ✓ Verify
    Read Step 3 of the Workflow section and confirm it now specifies: "If an issue URL was fetched in Step 0.5, add <meta name="plan-issue" content="<url>"> to the HTML <head>. Omit this tag when no issue reference was provided."
  5. done Add CHANGELOG.md entry and bump version to 0.15.0 in .claude-plugin/marketplace.json

    Why: Adding a new detection step and a new frontmatter field is a backward-compatible feature addition (minor version bump per the project's semver convention). The CHANGELOG entry records the intent so future contributors understand why the ingestion step exists.

    ✓ Verify
    Run grep -A3 '"name": "plan-agent"' .claude-plugin/marketplace.json and confirm "version": "0.15.0". Read the top of kit/plugins/plan-agent/CHANGELOG.md and confirm a ## v0.15.0 entry is present describing the issue ingestion feature.
File add-issue-ingestion-to-planning-skill.html
Path docs/plans/add-issue-ingestion-to-planning-skill.html

Acceptance Criteria

7 / 7 done

Verification

Run the following four invocations after implementation and confirm all behave as expected:

  1. /plan-agent:planning https://github.com/shawn-sandy/agentics/issues/205 --quick — confirm the generated plan title matches the issue title, the Context section includes the issue body, and grep plan-issue on the HTML file returns the issue URL.
  2. /plan-agent:planning #205 --quick — confirm the skill resolves the current repo via gh repo view and fetches the same issue as above.
  3. /plan-agent:planning https://github.com/shawn-sandy/agentics/issues/205 override-objective --quick — confirm the plan title is "override-objective" while the issue body is still injected as context.
  4. /plan-agent:planning #99999 --quick (non-existent issue) — confirm the skill prints an error, falls back to treating #99999 as a plain objective string, and proceeds without crashing.

Also confirm grep '"version"' .claude-plugin/marketplace.json returns "version": "0.15.0" for the plan-agent entry.

Next Steps

Surface issue link in the plans gallery index

Update plans-library and the gallery template to parse <meta name="plan-issue"> and render a linked badge on each plan card that has one.

Update kit/plugins/plan-agent/skills/plans-library/SKILL.md and the
plans-gallery.html template to parse <meta name="plan-issue"> from each
plan file and render a linked GitHub/GitLab badge on the gallery card when
that tag is present. The badge should link directly to the issue URL and
display a short label like "#205". No other changes to the gallery layout
or filtering logic.

Support Jira and Linear issue URLs

Extend the detection regex to recognise https://linear.app/*/issue/* and https://*.atlassian.net/browse/* URLs, fetching via their respective REST APIs.

Extend Step 0.5 in kit/plugins/plan-agent/skills/planning/SKILL.md to
detect Linear and Jira issue URLs in addition to GitHub/GitLab. For Linear:
use the Linear GraphQL API (requires LINEAR_API_KEY env var). For Jira: use
the Jira REST API v3 (requires JIRA_API_TOKEN and JIRA_BASE_URL env vars).
Map each to the same objective/context/label/url fields as GitHub. If the
required env var is missing, fall back to the plain-objective path and
display a one-line setup hint.
🔭 Wish List (speculative, not scheduled)
🔭 Wish List

Bi-directional sync: write plan URL back to the issue

After the plan is committed, post a comment on the originating issue linking to the plan file URL in the repository — closing the loop so the ticket references its plan.

After kit/plugins/plan-agent/skills/planning/SKILL.md commits a plan that
was seeded from an issue (i.e. plan-issue meta tag is present), add a Step
6.5 that posts a comment to the originating issue via
`gh issue comment <n> --repo <owner>/<repo> --body "Plan created: <url>"`.
Only run this step when the issue reference is a GitHub URL (skip for
GitLab until glab comment support is verified). Guard behind a
`--no-issue-comment` flag so users can opt out.