plan-task

name	plan-task
description	Generate a principles-aware work plan for an issue. Saves to `.agent/work-plans/` in the repo that owns the issue and commits as the first step on the feature branch.

Plan Task

Usage

/plan-task <issue-number> [--no-pr]

• --no-pr — skip draft PR creation (step 8). The plan is still committed locally. Useful when working offline or when a PR isn't needed yet.

Overview

Generate a work plan for an issue with principles and ADR awareness. This complements EnterPlanMode — it adds the governance lens, not a competing planning system. Use EnterPlanMode for general codebase exploration and approach design; use this skill to ensure the plan accounts for workspace principles, ADR compliance, and downstream consequences.

Lifecycle position: review-issue → plan-task → review-plan → implement → review-code

Steps

1. Read the issue and any review comments

Try git-bug first for offline-capable issue reading, then fall back to gh:

# git-bug first (offline-capable) — provides title, body, and status
# Look up by GitHub URL metadata (git-bug human_id != GitHub issue number)
ISSUE_TITLE=""
ISSUE_BODY=""
if command -v git-bug &>/dev/null && command -v jq &>/dev/null; then
    _REPO_SLUG="<owner/repo>"  # resolve from git remote
    _GITHUB_URL="https://github.com/${_REPO_SLUG}/issues/<N>"
    _LIST_JSON=$(git bug bug -m "github-url=${_GITHUB_URL}" --format json 2>/dev/null || echo "")
    _BUG_ID=$(echo "$_LIST_JSON" | jq -r '.[0].human_id // empty' 2>/dev/null)
    if [ -n "$_BUG_ID" ]; then
        _SHOW_JSON=$(git bug bug show "$_BUG_ID" --format json 2>/dev/null || echo "")
        ISSUE_TITLE=$(echo "$_SHOW_JSON" | jq -r '.title // empty')
        ISSUE_BODY=$(echo "$_SHOW_JSON" | jq -r '.comments[0].message // empty')
    fi
    # Sync-on-miss: if not found, pull from GitHub and retry
    if [ -z "$ISSUE_TITLE" ]; then
        git bug bridge pull github &>/dev/null || true
        _LIST_JSON=$(git bug bug -m "github-url=${_GITHUB_URL}" --format json 2>/dev/null || echo "")
        _BUG_ID=$(echo "$_LIST_JSON" | jq -r '.[0].human_id // empty' 2>/dev/null)
        if [ -n "$_BUG_ID" ]; then
            _SHOW_JSON=$(git bug bug show "$_BUG_ID" --format json 2>/dev/null || echo "")
            ISSUE_TITLE=$(echo "$_SHOW_JSON" | jq -r '.title // empty')
            ISSUE_BODY=$(echo "$_SHOW_JSON" | jq -r '.comments[0].message // empty')
        fi
    fi
fi

# Fall back to gh if git-bug didn't provide the data
if [ -z "$ISSUE_TITLE" ] || [ -z "$ISSUE_BODY" ]; then
    _GH_JSON=$(gh issue view <N> --json title,body,labels,comments,url 2>/dev/null || echo "")
    if [ -n "$_GH_JSON" ]; then
        [ -z "$ISSUE_TITLE" ] && ISSUE_TITLE=$(echo "$_GH_JSON" | jq -r '.title')
        [ -z "$ISSUE_BODY" ] && ISSUE_BODY=$(echo "$_GH_JSON" | jq -r '.body')
    fi
fi

If neither source is available, stop and inform the user: "Cannot read issue # — git-bug has no cached data and gh is unavailable."

Check for review-issue comments — they contain scope assessment, principle flags, and ADR notes that should inform the plan. Comments are available from gh output (.comments[]) or from git-bug JSON (.comments[1:] — index 0 is the issue body).

2. Load governance context

• .agent/knowledge/principles_review_guide.md — evaluation criteria
• docs/PRINCIPLES.md — workspace principles
• docs/decisions/*.md — ADR titles (read triggered ADRs in full)
• Project-level governance if the issue targets a project repo

3. Explore the codebase

Read relevant files to understand the current state:

• Files that will be modified
• Tests that exist for those files
• Documentation that references them
• Use the consequences map to identify what else may be affected

4. Ensure correct worktree (hard check)

Before writing or committing the plan, resolve the work-plans directory using the shared helper. It refuses to return a path when you're outside the matching worktree — this is deliberate (issue #147): silent writes into the main tree were stranding per-issue artifacts on no branch.

# shellcheck source=../../../.agent/scripts/_resolve_work_plans_dir.sh
source .agent/scripts/_resolve_work_plans_dir.sh
WORK_PLANS_DIR=$(resolve_work_plans_dir <N>) || {
    # Resolver printed remediation guidance to stderr — surface it to the
    # user and stop. Do not write plan.md / progress.md anywhere else.
    exit 1
}

If the resolver aborts, the message tells the user to create or enter the matching worktree. Typical remediation:

Workspace issues (changes to .agent/, docs/, configs, skills):

.agent/scripts/worktree_create.sh --issue <N> --type workspace
source .agent/scripts/worktree_enter.sh --issue <N> --type workspace

Project repo issues (changes to the managed project repo):

.agent/scripts/worktree_create.sh --issue <N> --type project
source .agent/scripts/worktree_enter.sh --issue <N> --type project

To determine the type, run gh issue view <N> --json url and compare against the workspace repo URL — use --type project when the issue is in a project repo. If a worktree for the issue already exists, just enter it.

Use $WORK_PLANS_DIR (from the resolver) as the base path in step 5 and step 7 — do not construct .agent/work-plans/issue-<N>/ by hand.

5. Generate the plan

Write a plan to ${WORK_PLANS_DIR}/plan.md (resolved in step 4). Create the directory if it doesn't exist — it also holds review artifacts (Gemini prompts/findings) alongside the plan:

# Plan: <issue-title>

## Issue

<issue URL — use `gh issue view <N> --json url --jq '.url'` if available, otherwise use the repo's GitHub URL pattern>

## Context

<Brief summary of current state and what needs to change>

## Approach

<Step-by-step implementation plan>

1. **<step>** — <what and why>
2. ...

## Files to Change

| File | Change |
|------|--------|
| `path/to/file` | Description of change |

## Principles Self-Check

| Principle | Consideration |
|---|---|
| <relevant principle> | How this plan accounts for it |

## ADR Compliance

| ADR | Triggered | How addressed |
|---|---|---|
| <relevant ADR> | Yes/No | <explanation> |

## Consequences

| If we change... | Also update... | Included in plan? |
|---|---|---|
| <item from consequences map> | <dependent item> | Yes / No — follow-up |

## Open Questions

- <anything that needs human input before implementation>

## Estimated Scope

<single PR / multiple PRs / needs breakdown>

6. Update progress.md

Before committing, append a "Plan" step entry to ${WORK_PLANS_DIR}/progress.md. If progress.md does not exist, create it with frontmatter (use the issue title from step 1):

---
issue: <N>
---

# Issue #<N> — <issue title>

Then append the step entry:

## Plan
**Status**: complete
**When**: <YYYY-MM-DD HH:MM>
**By**: <agent name> (<model>)

Plan file: `${WORK_PLANS_DIR}/plan.md`.

<1-2 sentence summary of the approach>

7. Commit the plan

Stage both files and commit together:

mkdir -p "$WORK_PLANS_DIR"
git add "$WORK_PLANS_DIR/plan.md" "$WORK_PLANS_DIR/progress.md"
git commit -m "Add work plan for #<N>

<one-line summary of the approach>"

8. Create or update a draft PR

Skip this step if:

• The user passed --no-pr, or
• gh is unavailable (command -v gh &>/dev/null && gh auth status &>/dev/null fails)

If skipped, note in the report: "Draft PR skipped (offline or --no-pr). The plan is committed locally on branch <branch-name>."

Otherwise, push the branch and create (or update) a draft PR with a [PLAN] title prefix and the plan as the body. The prefix prevents agents from confusing the PR number with the issue number.

# Push current branch (name may vary: feature/issue-<N> or feature/ISSUE-<N>-<desc>)
git push -u origin HEAD

# Use ISSUE_TITLE from step 1 (already resolved from git-bug or gh)
CURRENT_BRANCH=$(git branch --show-current)

# Check for existing PR on this branch
EXISTING_PR=$(gh pr list --head "$CURRENT_BRANCH" --json url --jq '.[0].url // ""' 2>/dev/null || echo "")

# Build PR body: prepend Closes reference, then plan content
BODY_FILE=$(mktemp /tmp/gh_body.XXXXXX.md)
printf 'Closes #<N>\n\n' > "$BODY_FILE"
cat "$WORK_PLANS_DIR/plan.md" >> "$BODY_FILE"

if [ -n "$EXISTING_PR" ]; then
    # Update existing PR title and body
    gh pr edit "$EXISTING_PR" --title "[PLAN] $ISSUE_TITLE" --body-file "$BODY_FILE"
else
    # Create new draft PR
    gh pr create --draft --title "[PLAN] $ISSUE_TITLE" --body-file "$BODY_FILE"
fi
rm -f "$BODY_FILE"

9. Report to user

Summarize:

• What the plan proposes
• Which principles and ADRs were considered
• Any open questions that need input
• Link to the draft PR (or note that PR creation was skipped)
• Pointer to the "During implementation" section below, so the implementer knows to keep the plan in sync with landed code

During implementation

The plan-task skill's primary artifact is the committed plan file created in steps 5–6; step 8 publishes that plan into a draft PR. Implementation then proceeds on the same branch — and typically deviates from the plan: types get refined, functions change signatures, a "pure logic" module picks up a dependency. Keep the plan in sync as this happens so the file stays usable reference material — for Copilot's plan-file review, for review-code, and for the next agent who picks up the work.

1. Inline edits are the default. When implementation diverges from the plan in any way — wording, method names, file paths, dependency choices, a test contract that tightened during coding — edit the plan inline to match the landed code. Git history preserves the original planning state; nobody benefits from stale text at the top of an otherwise-current plan.

2. Appended "Implementation Notes" only for rationale-bearing design pivots. If the deviation is a real design decision whose why is not obvious from the code diff alone (e.g. "switched from QGridLayout to a custom layout because QGridLayout can't express slack-to-outside with shared inner edges"), make the inline edit and add a one-liner to an ## Implementation Notes section at the bottom of the plan capturing the rationale. The section is for rationale only, not a changelog.

3. Never append-only. Leaving stale text at the top of the plan while listing "changes" in a section below misleads Copilot, human reviewers, and future onboarding agents — all of whom read the top first.

4. Commit discipline. Plan edits flow in commits alongside the code changes that triggered them (same commit when caught while coding; follow-up commit if caught later during review triage). Never amend a pushed commit just to update the plan.

This guidance is enforced at the instructions layer only. There is no local hook for "did you update the plan"; the enforcement signal is review feedback — Copilot's plan-drift flags and review-code catching misalignment between the plan and the PR. If drift becomes a recurring finding across multiple PRs, that's a signal the rule needs more teeth, not that the rule is wrong.

The plan path under this rule is .agent/work-plans/issue-<N>/plan.md (the local convention; upstream uses PLAN_ISSUE-<N>.md). review-plan already supports --issue / file-path forms, so it reads the live plan file rather than the snapshotted PR body — inline plan edits stay visible to plan review without further wiring.

Guidelines

• Generate, don't just evaluate — this skill produces a plan, not a review of an existing plan. For reviewing plans, use review-plan on the draft PR.
• Concrete, not generic — "Update tests" is not a plan step. "Add test for edge case X in test_foo.py" is.
• Flag conflicts early — if the plan would violate a principle or ADR, say so and propose an alternative.
• Include open questions — if the approach depends on a choice the user should make, list it. Don't guess.
• Keep it short — a plan should be 30-80 lines. If it's longer, the task may need to be broken down.