@chief-clancy/plan

Implementation planner for Claude Code.

npx @chief-clancy/plan

[!WARNING] Clancy is in early development. Expect breaking changes and rough edges.

Generate structured implementation plans for your codebase. Plan from board tickets (posted as ticket comments) or fully offline from local Clancy briefs (read from .clancy/briefs/, with plans saved to .clancy/plans/). No full pipeline required.

What it does

The /clancy:plan slash command explores your codebase, runs a feasibility scan, and produces a plan with:

• Summary and implementation approach
• Affected files table (file, change type, description)
• Test strategy (specific tests to write)
• Acceptance criteria (testable conditions)
• Dependencies and blockers
• Risks and considerations
• Size estimate (S/M/L)

How it works

1. Install: npx @chief-clancy/plan — choose global or local
2. Pick an input source:
   • Board tickets — run /clancy:board-setup to configure credentials, then /clancy:plan PROJ-123. Plans are posted as comments on the ticket.
   • Local briefs — point at a Clancy brief file with /clancy:plan --from .clancy/briefs/<brief>.md. Plans are saved to .clancy/plans/<slug>-<row>.md.
3. Review and revise: add a ## Feedback section to the plan (board comment or local file), then re-run /clancy:plan to revise.

Input modes

| Mode | Example | Board needed? | | --------------- | ----------------------------------------------------- | --------------------------- | | Local brief | /clancy:plan --from .clancy/briefs/add-dark-mode.md | No | | Specific ticket | /clancy:plan PROJ-123, /clancy:plan #42 | Yes (/clancy:board-setup) | | Batch | /clancy:plan 3 | Yes (/clancy:board-setup) | | Queue (default) | /clancy:plan | Yes (/clancy:board-setup) |

The local brief path can be any Clancy-format markdown file — --from is not tied to @chief-clancy/brief. You can hand-write a brief (just include a ## Problem Statement or ## Ticket Decomposition heading) and point at it from anywhere on disk. Briefs generated by @chief-clancy/brief happen to use a YYYY-MM-DD-slug.md naming convention, but the date prefix is optional — Step 3a strips it when present and uses the full filename otherwise.

Flags

| Flag | Description | | ------------------- | ----------------------------------------------------------------------- | | --from <path> [N] | Plan from a local Clancy brief file. Optional row number targets a row. | | --afk | Auto-confirm all prompts. With --from, plans every unplanned row. | | --fresh | Discard the existing plan and start over. | | --list | Show inventory of existing local plans in .clancy/plans/ and stop. |

Local planning workflow

The --from flag lets you go from idea to implementation plan without ever touching a board:

# 1. Generate a brief (uses @chief-clancy/brief)
/clancy:brief "Add dark mode support"
# Saved to .clancy/briefs/2026-04-08-add-dark-mode.md

# 2. Plan the first decomposition row
/clancy:plan --from .clancy/briefs/2026-04-08-add-dark-mode.md
# Saved to .clancy/plans/add-dark-mode-1.md

# 3. Plan a specific row
/clancy:plan --from .clancy/briefs/2026-04-08-add-dark-mode.md 3
# Saved to .clancy/plans/add-dark-mode-3.md

# 4. Or plan every unplanned row in one pass
/clancy:plan --afk --from .clancy/briefs/2026-04-08-add-dark-mode.md

# 5. Review what's been planned
/clancy:plan --list

# 6. Revise — edit the plan file and add a `## Feedback` section
/clancy:plan --from .clancy/briefs/2026-04-08-add-dark-mode.md 3
# Detects feedback, regenerates with a `### Changes From Previous Plan` section

Plans are tracked in the brief file itself via a <!-- planned:1,2,3 --> marker, so re-running advances to the next unplanned row automatically.

Approving plans

The plan package ships /clancy:approve-plan so the approval gate works without the full pipeline. The behaviour depends on the install mode.

Standalone (no board)

# Approve a specific local plan
/clancy:approve-plan add-dark-mode-2

# Or auto-select the oldest unapproved local plan
/clancy:approve-plan

The command writes a .clancy/plans/{stem}.approved marker file containing the full lowercase hex SHA-256 of the plan file and an ISO 8601 UTC approval timestamp:

sha256=d2c9f3a1b4e6c8f09123456789abcdef0123456789abcdef0123456789abcd
approved_at=2026-04-08T22:30:00Z

The full 64-character hex hash is what .approved actually stores. The --from implement flow uses the marker as an advisory approval signal — in single-file mode no approval check is performed, and in batch mode plans without a marker are skipped. SHA comparison is not currently performed at runtime.

Implementing approved plans: Install chief-clancy and run /clancy:implement --from .clancy/plans/add-dark-mode-2.md. The --from flag parses the plan, creates a synthetic ticket, and runs the full pipeline without board credentials. For batch execution, point --from at the plans directory with --afk: /clancy:implement --from .clancy/plans/ --afk.

Clancy also tries to update the brief file's <!-- planned:1,2 --> marker to <!-- approved:1 planned:1,2 --> so /clancy:plan --list knows which rows are approved, but that brief-marker update is best-effort and may warn-and-skip if the expected brief metadata or matching marker is missing.

Standalone+board (board credentials but no full pipeline)

The argument decides which path runs:

• Plan-file stem (e.g. add-dark-mode-2): writes the local marker, then optionally pushes the approved plan to the source board ticket as a comment. The push is interactive by default — /clancy:approve-plan add-dark-mode-2 prompts Push approved plan to {KEY} as a comment? [y/N] (default No, never surprise-write to a board). Use --push to skip the prompt and push immediately, --ticket KEY to override the auto-detected key from the plan file's **Source:** header, and --afk to combine with --push for unattended automation. If the push fails (HTTP error, network issue, key/board mismatch), the local marker stays in place and an exact retry command is printed
• Board ticket key (e.g. PROJ-123): runs the full board comment-to-description transport flow — fetches the plan comment, appends it to the ticket description, edits the plan comment with an approval note, swaps the ticket labels (CLANCY_LABEL_PLAN → CLANCY_LABEL_BUILD, both with sensible defaults), and — only if CLANCY_STATUS_PLANNED is configured — transitions the ticket status. Label swaps are mandatory; status transitions are opt-in via the CLANCY_STATUS_PLANNED env var

The plan-file lookup runs first, so plan stems win on collision (PROJ-123.md exists locally AND PROJ-123 is a valid ticket key → the local plan wins).

Terminal mode (full pipeline)

Existing behaviour, unchanged. Board ticket transport, queue transitions, and the implementation handoff all work as they did before.

Board ticket mode

To plan from board tickets without installing the full pipeline:

1. Run /clancy:board-setup in Claude Code
2. Follow the prompts to configure your board credentials
3. Run /clancy:plan PROJ-123 (or your board's ticket format)

Credentials are stored in .clancy/.env and are per-project (not global).

Supported boards: Jira, GitHub Issues, Linear, Shortcut, Notion, Azure DevOps.

Updating

Run /clancy:update-plan in Claude Code. It checks npm for the latest version, shows what's new from the GitHub release, and re-runs the installer to overwrite commands, workflows, and agents. Supports --afk to skip the confirmation prompt.

Uninstalling

Run /clancy:uninstall-plan in Claude Code. It removes plan-exclusive files (commands, workflows, VERSION marker), then checks for other installed Clancy packages before removing shared files (board-setup, scan agents, map-codebase, update-docs). Leaves .clancy/.env untouched.

Full pipeline

For the complete development pipeline (brief, plan, implement, deliver), install the full Clancy package:

npx chief-clancy

Also included

Installing @chief-clancy/plan also installs codebase scanning commands from @chief-clancy/scan:

• /clancy:map-codebase — scan your codebase with 5 parallel agents and generate .clancy/docs/
• /clancy:update-docs — incrementally refresh docs affected by recent changes

Running /clancy:map-codebase before planning gives the planner real codebase context for better plans.

Part of the Clancy monorepo

• chief-clancy — full pipeline (install, configure, implement, autopilot)
• @chief-clancy/core — board integrations, schemas, shared utilities
• @chief-clancy/terminal — installer, slash commands, hooks, runners
• @chief-clancy/dev — standalone ticket executor
• @chief-clancy/scan — codebase scanning agents and workflows
• @chief-clancy/brief — strategic brief generator

Credits

Built on the Ralph technique by Geoffrey Huntley. See CREDITS.md.

License

MIT — see LICENSE.