@chief-clancy/plan 0.1.0 → 0.3.0

package/src/workflows/plan.md

@@ -2,12 +2,18 @@
 
 ## Overview
 
-Fetch backlog tickets from the board, explore the codebase, and generate structured implementation plans. Plans are posted as comments on the ticket for human review. Does not implement anything — planning only. In **terminal mode**, use `/clancy:approve-plan` to promote plans. In **standalone mode** or **standalone+board mode**, install the full pipeline (`npx chief-clancy`) to promote plans.
+Fetch backlog tickets from the board, explore the codebase, and generate structured implementation plans. In board mode, plans are posted as comments on the ticket for human review. With `--from`, plans from local brief files are saved to `.clancy/plans/`, with an optional board comment when credentials are available. Does not implement anything — planning only. In **terminal mode**, use `/clancy:approve-plan` to promote plans. In **standalone mode** or **standalone+board mode**, install the full pipeline (`npx chief-clancy`) to promote plans.
 
 ---
 
 ## Step 1 — Preflight checks
 
+### 0. Short-circuit on `--list`
+
+If the `--list` flag is present in the arguments, skip the rest of Step 1 entirely (no installation detection, no `git fetch`, no docs check, no branch freshness prompt) and jump straight to Step 8 (Plan inventory). The inventory is filesystem-only and never needs board credentials, network access, or a clean working tree.
+
+`--list` always wins over other flags: if `--list` is combined with `--from`, `--fresh`, a ticket key, or a batch number, the inventory is displayed and the other flags are ignored for this run.
+
 ### 1. Detect installation context
 
 Check for `.clancy/.env`:
@@ -74,6 +80,11 @@ If the user declines, stop. If they confirm, continue without docs context.
 
 Parse the arguments passed to the command:
 
+- **`--from {path} [N]`** — From local brief file mode. Read a Clancy brief file and plan from its content. A bare integer after the path selects row N from the decomposition table (e.g. `--from brief.md 3` selects row 3). Without a number, defaults to the first unplanned row. Cannot be combined with a ticket reference (`Cannot use both a ticket reference and --from. Use one or the other.`). Cannot be combined with a batch number (`Cannot use batch mode with --from. Use --from with a brief file path.`). Validate the file:
+  - File does not exist: `File not found: {path}` Stop.
+  - File is empty: `File is empty: {path}` Stop.
+  - File > 50KB: Warn `Large file ({size}KB). Clancy will use the first ~50KB for context.` Truncate internally, continue.
+  - File is not a Clancy brief: must contain `## Problem Statement` or `## Ticket Decomposition`. If neither found: `File does not appear to be a Clancy brief. Use /clancy:brief to generate one, or /clancy:brief --from {path} to brief from a raw file.` Stop.
 - **No argument:** plan 1 ticket from the queue
 - **Numeric argument** (e.g. `/clancy:plan 3`): plan up to N tickets from the queue, cap at 10
 - **Specific ticket key:** plan a single ticket by key, with per-platform validation:
@@ -86,8 +97,13 @@ Parse the arguments passed to the command:
     [2] Plan 10 tickets (max batch)
     ```
 - **`--fresh`:** discard any existing plan and start over from scratch. This is NOT re-plan with feedback — it ignores existing plans entirely.
+- **`--list`:** display the plan inventory (all files in `.clancy/plans/`) and stop. No plan is generated, no board API calls are made.
 - Arguments can appear in any order (e.g. `/clancy:plan --fresh PROJ-123` or `/clancy:plan PROJ-123 --fresh`)
 
+### --list flag handling
+
+If `--list` is present, jump to Step 8 (Plan inventory) and stop — the short-circuit at the top of Step 1 also handles this case for runs that never reached Step 2. The flag works in any installation mode (standalone, standalone+board, terminal) — `--list` is filesystem-only and never touches the board. When combined with `--from`, `--fresh`, a ticket key, or a batch number, `--list` wins and the other arguments are ignored.
+
 If N > 10: `Maximum batch size is 10. Planning 10 tickets.`
 
 If N >= 5: display a confirmation (skip in AFK mode — `--afk` flag or `CLANCY_MODE=afk`):
@@ -98,12 +114,19 @@ Planning {N} tickets — each requires codebase exploration. Continue? [Y/n]
 
 ### Standalone board-ticket guard
 
+Skip this guard entirely if `--list` was passed — the inventory step is filesystem-only and runs in any installation mode (the Step 1 short-circuit normally handles this, but state it here too so the guard never blocks `--list`).
+
+**`--from` mode** bypasses the standalone board-ticket guard entirely — no board credentials are needed for local brief planning. `--list` bypasses the guard for the same reason: the inventory reads only `.clancy/plans/`. The guard evaluates the resolved input mode (ticket/batch/no-arg), not flags like `--afk`.
+
 If running in **standalone mode** (Step 1 detected no `.clancy/.env`) and the resolved input mode is **board ticket**, **batch mode**, or **no argument** (which defaults to queue fetch):
 
 ```
 Board credentials not found. To plan from board tickets:
   /clancy:board-setup    — configure board credentials (standalone)
   npx chief-clancy       — install the full pipeline
+
+To plan from a local brief file:
+  /clancy:plan --from .clancy/briefs/{slug}.md
 ```
 
 Stop.
@@ -112,6 +135,105 @@ In **standalone+board mode**, board ticket and batch modes proceed normally —
 
 ---
 
+## Step 3a — Gather from local brief (--from mode only)
+
+If `--from {path}` was set in Step 2, run this step **instead of** Steps 3, 3b, and 3c (all board-mode ticket fetching, existing plan detection via comments, and feedback loop). Skip all of them entirely — Step 3a handles its own existing plan check below.
+
+### Read and parse the brief file
+
+Read the file at `{path}`. Extract the following sections:
+
+- **Source** field (`**Source:**` line) — the source value (e.g. `[#50] Redesign settings page`, `"Add dark mode"`, `docs/rfcs/auth-rework.md`). Used for the plan header and display identifier.
+- `## Problem Statement` — used as the ticket description equivalent for plan context. Optional — if missing, use the brief's overall content as context instead.
+- `## Goals` — used alongside Problem Statement for plan context. Optional.
+- `## Ticket Decomposition` — the decomposition table. Parse the table rows for row-level planning.
+
+### Parse decomposition table rows
+
+Parse the `## Ticket Decomposition` table to extract plannable rows. A valid row must have at minimum a row number (column 1) and a title (column 2). Rows are 1-indexed, corresponding to the order of data rows in the decomposition table (excluding header and separator rows).
+
+**Missing table:** If `## Ticket Decomposition` is missing or has no data rows, treat the entire brief as a single planning unit (row 1). Warn: `No decomposition table found in {path}. Planning the brief as a single item.`
+
+**Malformed rows:** Skip malformed rows with a warning: `Skipping malformed row {line}`. If ALL rows are malformed, treat as missing table (single planning unit).
+
+### Row selection
+
+Check for an existing `<!-- planned:1,2,3 -->` marker comment in the brief file. If no marker exists, no rows have been planned.
+
+**Row validation:** If `--from path N` was specified, validate N:
+
+- N must be a positive integer. If N <= 0 or not an integer: `Row number must be a positive integer.` Stop.
+- N must exist in the decomposition table. If N > total rows: `Row {N} not found. The brief has {max} decomposition rows.` Stop.
+
+When `--from` is present, a bare integer is always interpreted as a row number, never as a batch count.
+
+**Row targeting:**
+
+- If `--from path N` was specified in Step 2, select row N specifically. If row N is already in the planned marker, do not stop here — defer the "already planned" decision to the later "Existing local plan check," after the plan slug/path is known and the workflow can inspect the existing plan file for `## Feedback` and apply `--fresh` rules.
+- Without a number, select the first unplanned row — the first row whose number is NOT in the planned set.
+- If no number was specified and all rows are planned: `All decomposition rows have been planned. Use --fresh to re-plan a specific row.` Stop.
+
+**`--fresh` with row selection:** When `--fresh` is used to re-plan a specific row, the row's existing plan file is overwritten. The planned marker is not modified — the row was already in the marker and stays there (no remove-and-re-add cycle needed).
+
+**`--fresh` + `--afk`:** Re-plans all rows from scratch. Deletes all existing plan files for this brief, clears the planned marker entirely, then plans all rows sequentially.
+
+**Multi-row mode:** `--from` with `--afk` plans all unplanned rows sequentially — loop through each unplanned row, running Steps 4-5a for each one. Without `--afk`, plan exactly one row (first unplanned, or the specified row) then stop.
+
+### Update planned marker
+
+After planning each row, update the `<!-- planned:N -->` marker in the brief file:
+
+- If no marker exists, append `<!-- planned:{row} -->` to the file. If the last `---` line in the file is a brief footer (trailing `---`), insert before it. Otherwise append at EOF.
+- If a marker exists, update it: `<!-- planned:1,2,3 -->` → `<!-- planned:1,2,3,4 -->`.
+
+**Concurrency note:** The planned marker is file-based and not concurrency-safe. Running multiple `--from` commands against the same brief simultaneously may produce duplicate plans.
+
+Pass the selected row's context (title, description, size, dependencies) along with the brief's Problem Statement, Goals, and Source to Step 4 as the ticket context.
+
+### --from mode Step 4 adaptations
+
+When running in `--from` mode, Steps 4a-4f have these adaptations:
+
+- **Display identifier:** Use the slug (derived from brief filename) wherever board mode uses `{KEY}`. Progress display shows `[{slug}#{row}] {row title}` instead of `[{KEY}] {Title}`.
+- **Step 4a (feasibility scan):** Run the scan normally (the brief content replaces the ticket description). If infeasible, skip — but do NOT post a "Clancy skipped" comment to any board (no board ticket). Use the canonical Step 6 log format, with `{slug}` in place of `{KEY}` for the identifier.
+- **Step 4b (QA return detection):** Skip entirely in `--from` mode — there is no implementation history to check.
+- **Step 4c-4e:** Run normally — codebase context, Figma, and exploration work the same regardless of input source.
+- **Step 4f (generate plan):** Use the local plan header format (Source/Brief fields) instead of the board header format (Ticket field). See Step 5a for the header template.
+
+### Existing local plan check
+
+Before planning each row, check for an existing plan file at `.clancy/plans/{slug}-{row-number}.md` where the slug is derived from the brief filename:
+
+**Slug generation:** strip the `YYYY-MM-DD-` date prefix (pattern: 4 digits, dash, 2 digits, dash, 2 digits, dash) if present, then strip the `.md` extension. If no date prefix matches, use the full filename minus extension.
+
+If an existing plan file is found, scan it for a `## Feedback` section. Match `## Feedback` as a heading at the start of a line (not inside code fences or backtick spans). The feedback section is appended by the user to request revisions.
+
+| Condition                                  | Behaviour                                                                                                                                          |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No existing plan                           | Proceed to Step 4                                                                                                                                  |
+| Existing plan + `--fresh`                  | Delete and overwrite the existing plan file. `--fresh` takes precedence over feedback — any `## Feedback` section is discarded. Proceed to Step 4. |
+| Existing plan + `## Feedback` section      | Revise: read existing plan + feedback, generate revised plan with `### Changes From Previous Plan` section                                         |
+| Existing plan + no feedback + no `--fresh` | Stop: `Already planned. Add a ## Feedback section to revise, or use --fresh to start over.`                                                        |
+
+### Read feedback for revision
+
+When revising from feedback (auto-detected from a real `## Feedback` heading in the local plan file), read the entire `## Feedback` section content — from that heading until the next real `##` heading at the start of a line, outside fenced code blocks and inline backtick spans, or EOF. If multiple `## Feedback` sections exist (the user added more after a previous revision), concatenate all sections in order.
+
+Pass this feedback to the plan generation step (Step 4f) as additional context, alongside the brief's Problem Statement, Goals, and the row context. The `## Feedback` section is the user's revision request — typically natural language describing what to change, what was missing, or what went wrong.
+
+**Revision procedure:** When revising, the planner SHOULD:
+
+- Skip Step 4a (feasibility scan) — the previous plan already passed feasibility
+- Skip Step 4b (QA return detection) — N/A in `--from` mode
+- Re-run Step 4c-4e (codebase context, Figma, exploration) only if the feedback explicitly references new files, components, or areas not covered by the previous plan. Otherwise reuse the existing exploration.
+- Run Step 4f to regenerate the plan, addressing the feedback while preserving acceptance criteria and affected files that the feedback does not touch
+
+**Feedback lifecycle:** The revised plan file overwrites the existing plan file completely. The `## Feedback` section is NOT carried forward into the new file — it is consumed by the revision and the audit trail lives in the `### Changes From Previous Plan` section (which quotes or summarises the feedback that was addressed).
+
+**Row selection with feedback:** When selecting rows to plan in `--afk` multi-row mode, also include rows whose plan files contain a `## Feedback` section. The selection set is: (unplanned rows) ∪ (rows with feedback). For default row selection (no row N, no `--afk`), the first row needing attention is: first row with feedback if any, otherwise first unplanned row.
+
+---
+
 ## Step 3 — Fetch backlog tickets
 
 Detect board from `.clancy/.env` and fetch tickets from the **planning queue** (different from the implementation queue used by `/clancy:implement`).
@@ -733,9 +855,48 @@ _Generated by [Clancy](https://github.com/Pushedskydiver/chief-clancy). To reque
 
 ---
 
-## Step 5 — Post plan as comment
+## Step 5 — Save / post plan
+
+### 5a. Local plan output (--from mode)
+
+If planning from a local brief (`--from`), save the plan to a local file instead of posting to the board.
+
+**Output path:** `.clancy/plans/{slug}-{row-number}.md`
+
+Create `.clancy/plans/` directory if it does not exist.
+
+The slug is the same one computed in Step 3a (brief filename minus date prefix and extension). The row number is the 1-indexed decomposition row being planned.
+
+**Local plan header:** The plan uses the same `## Clancy Implementation Plan` template from Step 4f, but with local-specific header fields:
+
+```markdown
+## Clancy Implementation Plan
+
+**Source:** {brief source field value}
+**Brief:** {brief filename}
+**Row:** #{row number} — {row title}
+**Planned:** {YYYY-MM-DD}
+```
+
+Replace the `**Ticket:** [{KEY}] {Title}` line from the board template with `**Source:**` and `**Brief:**` lines.
+
+**Revision header (when revising from feedback):** If this is a revision (existing plan had `## Feedback`), insert `### Changes From Previous Plan` immediately after the local header block (after `**Planned:**`) and before `### Summary`. Same structure as the board template's revision section.
+
+**Local plan footer:** Replace the board-specific footer with:
+
+```
+_Generated by [Clancy](https://github.com/Pushedskydiver/chief-clancy). To request changes: add a ## Feedback section to this file, then re-run `/clancy:plan --from {path}` to revise. To start over: `/clancy:plan --fresh --from {path}`. To approve: install the full pipeline — npx chief-clancy._
+```
+
+**Re-planning:** If `--fresh` was used, the existing plan file is overwritten (same slug + row number = same filename).
 
-**Guard:** Only run Step 5 when board credentials are available (terminal mode or standalone+board mode). In standalone mode (no `.clancy/.env`), skip this step entirely — the plan is still generated and printed to stdout in Step 4.
+**Board comment offer:** If board credentials ARE available (terminal mode or standalone+board mode), after saving the local file, offer to also post the plan as a comment on the source ticket (if the brief's Source field contains a ticket key). This is optional — the local file is the primary output.
+
+After saving, skip to Step 6 (log). Do not run Step 5b (board posting) for `--from` plans unless the user opts in above.
+
+### 5b. Post plan as comment (board mode)
+
+**Guard:** Only run Step 5b when board credentials are available (terminal mode or standalone+board mode). In standalone mode (no `.clancy/.env`), skip this step entirely — the plan is still generated and printed to stdout in Step 4.
 
 ### Jira — POST comment
 
@@ -851,6 +1012,8 @@ curl -s \
 
 For each planned ticket, append to `.clancy/progress.txt` using the appropriate variant:
 
+### Board mode log entries
+
 | Outcome                         | Log entry                                              |
 | ------------------------------- | ------------------------------------------------------ |
 | Normal                          | `YYYY-MM-DD HH:MM \| {KEY} \| PLAN \| {S/M/L}`         |
@@ -858,12 +1021,28 @@ For each planned ticket, append to `.clancy/progress.txt` using the appropriate
 | Comment post failed             | `YYYY-MM-DD HH:MM \| {KEY} \| POST_FAILED \| {reason}` |
 | Skipped (infeasible)            | `YYYY-MM-DD HH:MM \| {KEY} \| SKIPPED \| {reason}`     |
 
+### --from mode log entries
+
+Use the slug as the identifier instead of a ticket key:
+
+| Outcome                         | Log entry                                                      |
+| ------------------------------- | -------------------------------------------------------------- |
+| Normal                          | `YYYY-MM-DD HH:MM \| {slug}#{row} \| LOCAL_PLAN \| {S/M/L}`    |
+| Revised (re-plan with feedback) | `YYYY-MM-DD HH:MM \| {slug}#{row} \| LOCAL_REVISED \| {S/M/L}` |
+| Skipped (infeasible)            | `YYYY-MM-DD HH:MM \| {slug}#{row} \| SKIPPED \| {reason}`      |
+
+### --list mode
+
+`--list` display is not logged to `.clancy/progress.txt` — the inventory is read-only and does not change project state.
+
 ---
 
 ## Step 7 — Summary
 
 After all tickets are processed, display:
 
+### Board mode summary
+
 ```
 Planned {N} ticket(s):
 
@@ -879,6 +1058,82 @@ Plans written to your board. After review:
 "Let me dust this for prints..."
 ```
 
+### --from mode summary
+
+Single row:
+
+```
+🚨 Clancy — Plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ✅ Saved to .clancy/plans/{slug}-{row-number}.md
+
+  To approve: install the full pipeline — npx chief-clancy
+
+"Let me dust this for prints..."
+```
+
+Multi-row (`--afk`):
+
+```
+🚨 Clancy — Plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ✅ Row 1: {title} — Saved to .clancy/plans/{slug}-1.md
+  ✅ Row 2: {title} — Saved to .clancy/plans/{slug}-2.md
+  ⏭️  Row 3: {title} — already planned
+
+  To approve: install the full pipeline — npx chief-clancy
+
+"Let me dust this for prints..."
+```
+
+---
+
+## Step 8 — Plan inventory (`--list`)
+
+If `--list` was passed (detected at the top of Step 1), display the local plan inventory and stop. This step is filesystem-only — no API calls, no board access, no `.clancy/.env` required.
+
+Scan `.clancy/plans/` for all `.md` files. For each file, parse the local plan header (the block at the top of the file written by Step 5a) and capture these fields:
+
+- **Plan ID** — the plan filename minus the `.md` extension (e.g. `add-dark-mode-2`). This is `{slug}-{row}` as written by Step 5a, where `{slug}` is the brief slug from Step 3a and `{row}` is the decomposition row number. Always present (it is the filename).
+- **Brief** — value of the `**Brief:**` line. The brief filename the plan was generated from. Display the literal `?` if the line is absent or empty after the colon.
+- **Row** — value of the `**Row:**` line (e.g. `#2 — Add toggle component`). Display `?` if absent or empty.
+- **Source** — value of the `**Source:**` line (the brief's Source field). Display `?` if absent or empty.
+- **Planned** — value of the `**Planned:**` line (the YYYY-MM-DD planned date). Display `?` if absent or unparseable as a date.
+- **Status** — for now this is always `Planned`. Reserved for `/clancy:approve-plan` (a future PR) which will write a sibling `.approved` marker file (e.g. `.clancy/plans/add-dark-mode-2.approved`). When that marker exists for a given plan, Status becomes `Approved`. The column is included in the listing today so the format will not change when approval markers ship.
+
+A field is considered missing if the line is absent or its value is empty after the colon. Plans missing all expected fields are still listed (with `?` placeholders) so the user can find and clean them up.
+
+**Sort:** by `**Planned**` date, newest first. Tie-break on same date by Plan ID, alphabetical ascending. Files with a missing or unparseable date sort last (after all dated plans), and tie-break among themselves by Plan ID alphabetical ascending. The sort must be deterministic across runs.
+
+Display:
+
+```
+Clancy — Plans
+================================================================
+
+  [1] add-dark-mode-2          2026-04-08  Planned  Row #2 — Add toggle component  Brief: 2026-04-01-add-dark-mode.md  Source: #50
+  [2] add-dark-mode-1          2026-04-07  Planned  Row #1 — Wire theme context    Brief: 2026-04-01-add-dark-mode.md  Source: #50
+  [3] customer-portal-3        2026-04-05  Planned  Row #3 — Billing page          Brief: 2026-03-28-customer-portal.md  Source: PROJ-200
+
+3 local plan(s).
+
+To revise: add a `## Feedback` section to the plan file, then re-run /clancy:plan --from <brief>.
+To start over: /clancy:plan --fresh --from <brief>.
+To approve: install the full pipeline — npx chief-clancy.
+```
+
+The first column in the listing is the Plan ID (filename without `.md`), not the brief slug.
+
+If `.clancy/plans/` does not exist or contains no `.md` files:
+
+```
+No plans found. Run /clancy:plan --from .clancy/briefs/<brief>.md to create one.
+```
+
+Stop after display. The `--list` step never logs to `.clancy/progress.txt` and never modifies any file — it is purely a read-only inventory view of the local plans directory.
+
 ---
 
 ## Notes
@@ -891,3 +1146,6 @@ Plans written to your board. After review:
 - All board API calls are best-effort — if a comment fails to post, print the plan to stdout as fallback
 - When exploring the codebase, use Glob and Read for small tickets, parallel Explore subagents for larger ones
 - The `## Clancy Implementation Plan` marker in comments is used by both `/clancy:plan` (to detect existing plans) and `/clancy:approve-plan` (to find the plan to promote)
+- `--from` mode is fully offline — no board credentials needed. Plans saved to `.clancy/plans/` as the source of truth
+- `--from` requires a Clancy brief (structured format with `## Problem Statement` or `## Ticket Decomposition`). For raw files, use `/clancy:brief --from {path}` first to generate a brief
+- `--list` is filesystem-only and short-circuits at the top of Step 1 — no installation context, network, board, or git checks run before the inventory displays