plan-tracking-issue

name	plan-tracking-issue
description	Open or preview a provider-aware GitHub or GitLab tracking issue for a docs/plans plan bundle, bootstrapping the source doc and plan first when the user has a converged feature discussion but no plan file yet.

Plan Tracking Issue

Create a lightweight provider issue for a plan bundle; when no plan exists, bootstrap the source doc and plan first.

Contract

Prereqs:

• Run inside the target git repository or pass a provider/repository override.
• Either a plan file already exists, usually docs/plans/<slug>/<slug>-plan.md, or the conversation has converged enough to create a discussion-to-implementation-doc source artifact and create-plan plan bundle.
• Existing plans have exactly one primary source artifact or a recorded plan-only waiver.
• Bootstrap-from-discussion mode has enough user-provided or locally verifiable context to separate facts, decisions, assumptions, scope, acceptance criteria, and open questions.
• Live provider issue creation requires committed local plan and source files. Staged, unstaged, or untracked plan/source files are not enough for live issue creation; use --dry-run while drafting, then commit the plan bundle before opening the issue.
• python3 is available on PATH.
• Live GitHub mode requires gh on PATH and gh auth status succeeds.
• Live GitLab mode requires glab on PATH and glab auth status succeeds.

Inputs:

• Existing plan path (--plan <path>) when available.
• For bootstrap-from-discussion mode: user request, converged discussion context, slug/title constraints if provided, and any relevant repo context needed by discussion-to-implementation-doc and create-plan.
• Optional primary source override (--source <path-or-url>). If omitted, the script reads the plan's Read First Primary source line.
• Optional execution-state path (--execution-state <path>). If omitted, infer docs/plans/<slug>/<slug>-execution-state.md from the plan filename when possible.
• Provider (--provider github|gitlab|auto, default auto).
• Optional repository override (--repo <owner/repo|group/project>).
• Optional metadata: --title, repeated --label, repeated --assignee, and --milestone.
• GitHub-only optional metadata: repeated --project.
• GitLab-only optional metadata: --due-date, --weight, and --confidential.
• Safety/output controls: --dry-run, --body-out <path>, and --issue-url-out <path>.

Outputs:

• In bootstrap-from-discussion mode: a source artifact, usually docs/plans/<slug>/<slug>-discussion-source.md, followed by a plan file at docs/plans/<slug>/<slug>-plan.md.
• A provider issue URL in live mode, or DRY-RUN-TRACKING-ISSUE-URL in dry-run mode.
• A normalized issue body that links the plan, primary source, inferred execution state, provider, and next action.
• For GitHub tracking issues intended for issue-backed execution, append-only source and plan snapshot comments with stable markers:
  • <!-- plan-tracking-issue:snapshot:v1 kind=source -->
  • <!-- plan-tracking-issue:snapshot:v1 kind=plan --> Long local snapshot content is collapsed by default with GitHub <details> blocks while marker lines and metadata stay outside the collapsed section for parser recovery.
• Optional body artifact written to --body-out.
• Optional URL artifact written to --issue-url-out.
• Existing-plan mode does not create another plan or mutate the plan file by default.
• No execution-state file is created merely for issue tracking. The issue records the inferred or explicit execution-state path as exists or expected; execute-from-plan creates or updates the ledger when execution starts.
• Live mode verifies that the local plan file and local primary source file are committed in HEAD and have no staged or unstaged changes before calling gh issue create or glab issue create. URL sources and explicit plan-only waivers are recorded without a local file commit check.

Exit codes:

• 0: success
• 1: runtime failure / provider command failure
• 2: usage error

Failure modes:

• Missing or unreadable plan path in existing-plan mode.
• Missing plan plus insufficient discussion/source context to create a useful source doc and plan.
• Source doc or plan creation is blocked by project preflight, missing repo context, or validation failure.
• Missing primary source and no plan-only waiver is present.
• Provider cannot be inferred from git remote and --provider auto was used.
• Provider-specific unsupported flags are supplied (--project with GitLab, --due-date/--weight/--confidential with GitHub).
• Live mode is requested while the plan file or local primary source file is untracked, staged but uncommitted, or modified after commit.
• Required provider CLI or auth is unavailable in live mode.
• gh issue create or glab issue create fails.

Modes

• Existing-plan mode: use when a plan path exists or the user points at an existing docs/plans/<slug>/<slug>-plan.md. Do not create a new source doc or plan; read the existing plan and create or preview the issue.
• Bootstrap-from-discussion mode: use when the user asks to preserve a converged feature/product/design discussion as a later plan and also wants a provider tracking issue. In this mode, run discussion-to-implementation-doc first, then create-plan, then create or preview the issue through this skill's script.

Scripts (only entrypoints)

• $AGENT_HOME/skills/workflows/plan/plan-tracking-issue/scripts/plan-tracking-issue.sh

The script is the deterministic provider-issue renderer/creator. It still requires --plan <path>. In bootstrap-from-discussion mode, the workflow creates the source doc and plan first, then calls the script with the saved plan path.

Snapshot comments are workflow actions after the issue URL exists; they are not embedded in the issue body renderer.

Workflow

1. Classify the request:
   • If the user provides or clearly references an existing plan file, use existing-plan mode.
   • If no plan exists and the user asks to preserve a converged feature discussion as a plan plus provider issue, use bootstrap-from-discussion mode.
   • If the discussion is not converged enough for execution planning, ask the minimum blocking questions before writing docs.
   • If the user only wants to preserve conclusions without task sequencing or issue tracking, use discussion-to-implementation-doc directly instead of this skill.
2. In existing-plan mode:
   • Confirm the plan path exists.
   • Confirm the plan has exactly one primary source artifact or a recorded plan-only waiver.
   • Do not create another source doc or plan.
3. In bootstrap-from-discussion mode:
   • Follow project preflight for docs edits.
   • Use discussion-to-implementation-doc to save the implementation-readiness source artifact, usually as docs/plans/<slug>/<slug>-discussion-source.md.
   • Use create-plan to save docs/plans/<slug>/<slug>-plan.md with the source artifact under Read First.
   • Validate the plan through the create-plan workflow before creating or previewing the provider issue.
   • Do not create or update <slug>-execution-state.md unless the user also asks to start execution or project policy explicitly requires a pre-created execution ledger.
4. Resolve the provider:
   • Use an explicit --provider when the target platform is known.
   • Use --provider auto only when the repository remote clearly identifies GitHub or GitLab.
5. Resolve the primary source for the saved plan:
   • Prefer the explicit --source.
   • Otherwise parse the plan's Read First Primary source line.
   • Preserve plan-only waivers as a source value; do not invent a source document.
6. Render a concise issue body:
   • State that the plan remains the source of truth.
   • Link the primary source, plan, and execution state path.
   • Record the provider/repository and next action.
7. Run the script with --dry-run before live creation when provider/repo/metadata is uncertain.
8. Before live creation, verify persistence for local files:
   • Confirm the plan file is committed in HEAD.
   • If the primary source is a local file, confirm it is committed in HEAD.
   • Confirm both files have no staged or unstaged changes.
   • If this check fails, commit the plan bundle first or stay in --dry-run mode; do not open a live tracking issue that only references uncommitted local files.
9. In live mode, create exactly one issue through the selected provider CLI:
   • GitHub: gh issue create.
   • GitLab: glab issue create.
10. For GitHub issues that may later be executed through execute-from-tracking-issue:
    • Post a source snapshot comment with <!-- plan-tracking-issue:snapshot:v1 kind=source -->.
    • Post a plan snapshot comment with <!-- plan-tracking-issue:snapshot:v1 kind=plan -->.
    • Include content for local source and plan files as renderable GitHub Markdown. Do not wrap the comment body or local Markdown snapshot content in outer markdown / md code fences; issue preview readability is intentional.
    • Place long local source or plan Markdown inside a collapsed <details> block with a short <summary> label, leaving marker lines and snapshot metadata outside the collapsed section.
    • For URL or waiver sources, record the source value and why no local content was snapshotted.
    • Do not include secrets, credentials, private keys, or raw logs in snapshot comments.
11. Report the issue URL, snapshot comment status, and any body artifact path.

Relationship To Nearby Skills

• discussion-to-implementation-doc: in bootstrap-from-discussion mode, use it first to preserve converged feature/product/design conclusions as the plan's primary source artifact.
• create-plan: in bootstrap-from-discussion mode, use it after the source doc and before provider issue creation. Existing-plan mode skips it to avoid duplicate plans.
• create-dispatch-plan: use instead of create-plan inside bootstrap mode only when the user explicitly needs dispatch-ready sizing, scorecards, PR grouping, or subagent-reviewed execution modeling.
• issue-follow-up: use for generic issue timelines that are not tied to a plan bundle.
• Shared issue lifecycle tool (skills/workflows/issue/_shared/lib/manage_issue_lifecycle.sh): lower-level deterministic issue mutations, not as a separate workflow users should choose for ordinary follow-up.
• execute-from-tracking-issue: use when the GitHub issue-hosted source/plan snapshots should become the execution source of truth, especially after local docs/plans/ cleanup.
• deliver-dispatch-plan: use only for heavyweight GitHub execution orchestration where 1 plan = 1 issue and close gates require merged sprint/integration PRs.

Notes

• This skill is opt-in. create-plan still does not open live provider issues by default; issue creation happens only when this skill is explicitly selected or requested.
• The issue is a tracker, not a replacement source artifact. Keep detailed requirements, findings, and execution sequencing in the source doc and plan bundle.
• Once execute-from-tracking-issue starts from a GitHub tracking issue, the issue-hosted snapshots and execution comments become the durable execution record; local plan files can then be cleaned up after the usual reference checks.
• If a repository needs GitLab Issue lifecycle operations beyond creation and comments, add a GitLab-specific lifecycle tool or skill instead of stretching the GitHub shared issue lifecycle tool contract.
• Do not stretch generic issue lifecycle tooling into plan-tracking snapshot execution.