Plans

Let create-issue ingest plans and offer issue creation at plan completion

High completed
2026-07-13 agentics feature High effort
Objective

Add a plan source to the git-agent create-issue skill so a plan file (markdown spec or rendered HTML) can be turned into a GitHub/GitLab issue, and extend the plan-agent implementation-plan Step 8 menu with an optional "create a tracking issue" question that invokes it.

At a glance

Plans and issues only linked in one direction — an issue could seed a plan, but a finished plan could not become a tracked ticket. Now create-issue accepts a plan file as a source and implementation-plan offers issue creation at the end of every plan run.

Implement Read and implement all steps in the plan at docs/plans/add-plan-source-to-create-issue.md — Let create-issue ingest plans and offer issue creation at plan completion. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plan-source-to-create-issue.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Let create-issue ingest plans and offer issue creation at plan completion. The plan at docs/plans/add-plan-source-to-create-issue.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plan-source-to-create-issue.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/add-plan-source-to-create-issue.md — Let create-issue ingest plans and offer issue creation at plan completion. Brief subagents with the plan file at docs/plans/add-plan-source-to-create-issue.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plan-source-to-create-issue.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File add-plan-source-to-create-issue.html
Path docs/plans/add-plan-source-to-create-issue.html
Spec docs/plans/add-plan-source-to-create-issue.md
Definition of done 6 / 6 done

Context

The story behind this plan — what prompted the work and why it matters now.

implementation-plan already ingests issues (Step 0.5 maps an issue URL or #n into a plan and records it as an issue: frontmatter key), but the reverse path did not exist: a drafted plan could not become a tracked ticket without hand-writing one. create-issue supported four sources (bug, feature, selection, session) and its Step 8 counterpart in plan-agent ended without any issue hand-off. Wiring the two skills together closes the loop — the same issue: frontmatter key carries the link in both directions.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • kit/plugins/git-agent/skills/create-issue/SKILL.md modified plan source keyword + path implication, per-source mapping, template routing
  • kit/plugins/git-agent/skills/create-issue/references/plan-issue.md new plan-to-issue body skeleton
  • tests/plugins/test-create-issue-plan-source.sh new objective-verification smoke test
  • kit/plugins/git-agent/
    • README.md modified plan source documented with example
    • CHANGELOG.md modified v3.12.0 entry
  • kit/plugins/plan-agent/skills/implementation-plan/SKILL.md modified Step 8 batched tracking-issue question + handler
  • kit/plugins/plan-agent/CHANGELOG.md modified 2.22.0 entry
  • .claude-plugin/marketplace.json modified git-agent 3.11.1 → 3.12.0, plan-agent 2.21.0 → 2.22.0
  • CLAUDE.md modified plugin table rows for both plugins

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done Add the plan source to create-issue's SKILL.md: keyword parsing (a .md/.html token implies the source), resolution under the plans directory, and the mapping — plan title → issue title, Objective → Summary, Steps → - [ ] checklist, Acceptance Criteria carried over, type: frontmatter → label hint, plan path cited in the body.
Why
the skill's phases are the runtime contract; the mapping must be explicit so drafts are deterministic.
Verify
SKILL.md Phase 3 lists five sources and a plan per-source block; Phase 5 routes plan → plan-issue.md.
2
done Create references/plan-issue.md with the Objective / Plan / Steps / Acceptance Criteria / Additional Context body skeleton, title rule (plan title, no prefix), and label mapping.
Why
the other four sources each have a template; the plan shape (objective + checklists) fits none of them.
Verify
the file exists and the Reference Files list in SKILL.md names it.
3
done Extend implementation-plan Step 8 to batch a second AskUserQuestion — "Create a tracking issue for this plan?" — and on yes invoke Skill(skill: "git-agent:create-issue", args: "plan <spec path>"), record the returned issue URL as the spec's issue: frontmatter key, and re-render; if git-agent is not installed, note it and continue.
Why
the Step 8 menu already carries the AskUserQuestion 4-option maximum, so the issue choice must ride as a second batched question, and a missing cross-plugin dependency must never block the plan flow.
Verify
Step 8 shows two batched questions and a Yes — create an issue handler that names the fallback.
4
done Bump versions (git-agent 3.12.0, plan-agent 2.22.0) in marketplace.json, add CHANGELOG entries to both plugins, and update the README and CLAUDE.md plugin-table mentions.
Why
marketplace versioning is manual per repo rules (new skill capability = minor), and docs drift is a defect.
Verify
marketplace.json carries both new versions; both CHANGELOGs lead with the new entries; README and CLAUDE.md mention the plan source.

Tests

The tests that prove the change does what it promises.

Tier 2 — Steps edit skill markdown, templates, manifests, and docs only; no application source files change.
Objective: the two skills are wired together and versioned. File: tests/plugins/test-create-issue-plan-source.sh; Type: smoke test; Asserts: create-issue SKILL.md declares the plan source and routes it to references/plan-issue.md (which exists), implementation-plan SKILL.md invokes git-agent:create-issue with a plan argument in Step 8, and marketplace.json reports git-agent ≥ 3.12.0 and plan-agent ≥ 2.22.0; Run: bash tests/plugins/test-create-issue-plan-source.sh

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

Run bash tests/plugins/test-create-issue-plan-source.sh and confirm every check passes. Read create-issue SKILL.md end to end: the five-source flow is coherent from parsing (Phase 3) through template selection (Phase 5) to creation, and the confirmation gate still guards every path. Read implementation-plan Step 8: the batched question, the Yes handler, and the not-installed fallback are all present, and the existing four-option menus are unchanged. Confirm python3 -m json.tool .claude-plugin/marketplace.json parses and shows both bumped versions.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

End-to-end dry run of the plan source against a real plan

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, load the git-agent plugin (claude --plugin-dir
./kit/plugins/git-agent) and run /git-agent:create-issue plan
docs/plans/add-plan-source-to-create-issue.md against a scratch repo.
Confirm the drafted issue title matches the plan title, the body carries
the objective, step checklist, and acceptance criteria, and the
confirmation gate appears before any gh/glab call. Cancel at the gate —
do not create a real issue.
Offer the tracking-issue question in finalize-plan too

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, evaluate whether /plan-agent:finalize-plan should
also offer "create a tracking issue" for plans that finish without one
(no issue: frontmatter key). If yes, mirror the implementation-plan
Step 8 pattern — a batched AskUserQuestion invoking
git-agent:create-issue plan <spec path> with the not-installed fallback —
bump the plan-agent minor version, and add a CHANGELOG entry.