maestro-flow 0.3.18 → 0.3.20

package/.claude/commands/maestro-milestone-complete.md

@@ -1,75 +1,75 @@
----
-name: maestro-milestone-complete
-description: Archive completed milestone and prepare for next
-argument-hint: "[<milestone>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final learnings, and advances to the next milestone.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-complete.md
-</required_reading>
-
-<context>
-Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
-
-**Requires:** `/maestro-milestone-audit` should have passed.
-
-**State files:**
-- `.workflow/state.json` — artifacts[], milestones[], current_milestone, milestone_history[]
-- `.workflow/roadmap.md` — milestone structure
-- `.workflow/milestones/{milestone}/audit-report.md` — audit results
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-complete.md' completely.
-
-Archive flow steps (validation, directory archival, artifact history, learning extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
-
-### Knowledge Promotion Inquiry
-
-After learning extraction (step 4), scan `learnings.md` for promotion candidates:
-
-1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
-   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
-
-2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
-   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
-
-3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
-
-If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
-
-**Next-step routing on completion:**
-- Cut a release → `/maestro-milestone-release`
-- Next milestone → `/maestro-analyze` or `/maestro-plan 1`
-- View state → `/manage-status`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone identifier required | Check arguments |
-| E002 | error | Audit not passed | Run maestro-milestone-audit first |
-| E003 | error | Incomplete artifacts remain | Complete remaining work first |
-</error_codes>
-
-<success_criteria>
-- [ ] Audit report verified as PASS
-- [ ] Scratch artifacts moved to milestones/{M}/artifacts/
-- [ ] Artifact entries archived to milestone_history
-- [ ] Learnings extracted to specs/learnings.md
-- [ ] state.json updated: next milestone as current, artifacts[] cleared
-- [ ] Roadmap snapshot saved
-- [ ] project.md Context updated with milestone summary
-</success_criteria>
+---
+name: maestro-milestone-complete
+description: Archive completed milestone and prepare for next
+argument-hint: "[<milestone>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final learnings, and advances to the next milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-complete.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** `/maestro-milestone-audit` should have passed.
+
+**State files:**
+- `.workflow/state.json` — artifacts[], milestones[], current_milestone, milestone_history[]
+- `.workflow/roadmap.md` — milestone structure
+- `.workflow/milestones/{milestone}/audit-report.md` — audit results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-complete.md' completely.
+
+Archive flow steps (validation, directory archival, artifact history, learning extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
+
+### Knowledge Promotion Inquiry
+
+After learning extraction (step 4), scan `learnings.md` for promotion candidates:
+
+1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+
+2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
+   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
+
+If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+
+**Next-step routing on completion:**
+- Cut a release → `/maestro-milestone-release`
+- Next milestone → `/maestro-analyze` or `/maestro-plan 1`
+- View state → `/manage-status`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments |
+| E002 | error | Audit not passed | Run maestro-milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete remaining work first |
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report verified as PASS
+- [ ] Scratch artifacts moved to milestones/{M}/artifacts/
+- [ ] Artifact entries archived to milestone_history
+- [ ] Learnings extracted to specs/learnings.md
+- [ ] state.json updated: next milestone as current, artifacts[] cleared
+- [ ] Roadmap snapshot saved
+- [ ] project.md Context updated with milestone summary
+</success_criteria>

package/.claude/commands/maestro-milestone-release.md

@@ -1,96 +1,96 @@
----
-name: maestro-milestone-release
-description: Version bump, changelog generation, and git tag for a completed milestone
-argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-release.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional explicit version string and flags.
-
-**Flags:**
-- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
-- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
-- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
-- `--no-tag` -- skip git tag creation (version bump + changelog only)
-- `--no-push` -- skip `git push --follow-tags` after tagging
-
-**State files:**
-- `.workflow/state.json` -- current_milestone, previous release version
-- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
-- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
-- `CHANGELOG.md` -- release notes file (created if missing)
-- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
-
-**Preconditions:**
-- Current milestone must be completed (audit PASS + `/maestro-milestone-complete` run)
-- Working tree must be clean (no uncommitted changes) unless `--dry-run`
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/release.md' completely.
-
-**High-level flow:**
-1. Validate preconditions (milestone completed, clean tree, audit PASS)
-2. Resolve target version from `<version>` or `--bump` against current manifest
-3. Collect changes since last release tag: milestone summary + phase summaries + git log between tags
-4. Generate `CHANGELOG.md` entry (grouped by phase / change type)
-5. Write version to manifest file(s) + commit with message `chore(release): v{version}`
-6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
-7. Push commit + tag to remote (unless `--no-push`)
-
-**Report format on completion:**
-```
-=== RELEASE COMPLETE ===
-Version:   v{previous} → v{new}
-Milestone: {milestone_name}
-Tag:       v{new} {pushed|local-only}
-Changelog: {N} entries written to CHANGELOG.md
-Manifest:  {file_path} updated
-
-Next steps:
-  /maestro-plan {next_phase}   -- Start next milestone's first phase
-  /manage-status               -- View project dashboard
-```
-
-For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Current milestone not completed (no milestone-complete run) | Run `/maestro-milestone-complete` first |
-| E002 | error | Audit verdict not PASS | Re-run `/maestro-milestone-audit` and resolve findings |
-| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
-| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
-| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
-| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
-| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
-</error_codes>
-
-<success_criteria>
-- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
-- [ ] Target version computed and greater than previous
-- [ ] Version manifest(s) updated with new version
-- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
-- [ ] Release commit created with conventional message
-- [ ] Annotated git tag created (unless `--no-tag`)
-- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
-- [ ] state.json updated with last_release_version + last_release_at timestamp
-</success_criteria>
+---
+name: maestro-milestone-release
+description: Version bump, changelog generation, and git tag for a completed milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional explicit version string and flags.
+
+**Flags:**
+- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
+- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
+- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
+- `--no-tag` -- skip git tag creation (version bump + changelog only)
+- `--no-push` -- skip `git push --follow-tags` after tagging
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, previous release version
+- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
+- `CHANGELOG.md` -- release notes file (created if missing)
+- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
+
+**Preconditions:**
+- Current milestone must be completed (audit PASS + `/maestro-milestone-complete` run)
+- Working tree must be clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/release.md' completely.
+
+**High-level flow:**
+1. Validate preconditions (milestone completed, clean tree, audit PASS)
+2. Resolve target version from `<version>` or `--bump` against current manifest
+3. Collect changes since last release tag: milestone summary + phase summaries + git log between tags
+4. Generate `CHANGELOG.md` entry (grouped by phase / change type)
+5. Write version to manifest file(s) + commit with message `chore(release): v{version}`
+6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
+7. Push commit + tag to remote (unless `--no-push`)
+
+**Report format on completion:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {milestone_name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries written to CHANGELOG.md
+Manifest:  {file_path} updated
+
+Next steps:
+  /maestro-plan {next_phase}   -- Start next milestone's first phase
+  /manage-status               -- View project dashboard
+```
+
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Current milestone not completed (no milestone-complete run) | Run `/maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `/maestro-milestone-audit` and resolve findings |
+| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
+| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
+| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
+| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
+| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated with new version
+- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
+- [ ] Release commit created with conventional message
+- [ ] Annotated git tag created (unless `--no-tag`)
+- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
+- [ ] state.json updated with last_release_version + last_release_at timestamp
+</success_criteria>

package/.claude/commands/maestro-plan.md

@@ -1,138 +1,138 @@
----
-name: maestro-plan
-description: Explore, clarify, plan, check, and confirm a phase execution plan
-argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
-
-Supports three modes:
-- **Create** (default): Build plan from analysis context or phase requirements
-- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
-- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
-
-All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/plan.md
-</required_reading>
-
-<deferred_reading>
-- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
-- [task.json](~/.maestro/templates/task.json) — read when generating task files
-- [state.json](~/.maestro/templates/state.json) — read when registering artifact
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
-
-Scope routing, base flags (`--collab`, `--spec`, `--auto`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
-
-**Command-level flags** (extensions beyond workflow base):
-- `--revise [instructions]` -- See workflow plan.md § Revise Mode
-- `--check <plan-dir>` -- See workflow plan.md § Check Mode
-
-**Upstream context:**
-- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
-- Reads `conclusions.json` if available (implementation_scope seeds task generation)
-</context>
-
-<execution>
-### Pre-flight: team conflict check
-
-Before starting the plan pipeline, run:
-```
-Bash("maestro collab preflight --phase <phase-number>")
-```
-If exit code is 1, present warnings and ask whether to proceed.
-
-Follow '~/.maestro/workflows/plan.md' completely.
-
-### Wiki Knowledge Search (P1 addition)
-
-During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
-
-```
-phase_keywords = extract key terms from goal/title (2-5 terms)
-wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
-
-IF wiki_result exit code != 0 OR empty:
-  display "W003: Wiki search unavailable, continuing without prior knowledge"
-ELSE:
-  entries = JSON.parse(wiki_result).entries (limit to first 10)
-  wiki_context = structured block for downstream stages
-```
-
-### Issue Linkback (--gaps mode)
-
-After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:
-
-```
-For each created TASK-{NNN}.json that has issue_id:
-  Update corresponding issue in .workflow/issues/issues.jsonl:
-    task_refs: append TASK-{NNN} to array
-    task_plan_dir: relative path to .task/ directory
-    status: "planned"
-    updated_at: now()
-  Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
-```
-
-This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
-
-**Report format on completion:**
-
-```
-=== PLAN READY ===
-Phase: {phase_name}
-Tasks: {task_count} tasks in {wave_count} waves
-Check: {checker_status} (iteration {check_count}/{max_checks})
-Collision: {collision_status}
-
-Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
-Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
-
-Next steps:
-  /maestro-execute              -- Execute the plan
-  /maestro-execute --dir {dir}  -- Execute specific plan
-  /maestro-plan {phase}         -- Re-plan with modifications
-```
-
-### Mode: Revise / Check
-
-Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
-| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
-| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
-| E005 | error | Plan directory not found (--check) | Check path, use --dir |
-| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
-| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
-| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
-| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
-</error_codes>
-
-<success_criteria>
-- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
-- [ ] .task/TASK-*.json files created for each task
-- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
-- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
-- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
-- [ ] Collision detection executed against same-milestone plans (non-blocking)
-- [ ] Plan-checker passed (or minor issues acknowledged)
-- [ ] User confirmation captured (execute/modify/cancel)
-- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
-</success_criteria>
+---
+name: maestro-plan
+description: Explore, clarify, plan, check, and confirm a phase execution plan
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+
+Supports three modes:
+- **Create** (default): Build plan from analysis context or phase requirements
+- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
+- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
+
+All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+
+Scope routing, base flags (`--collab`, `--spec`, `--auto`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
+
+**Command-level flags** (extensions beyond workflow base):
+- `--revise [instructions]` -- See workflow plan.md § Revise Mode
+- `--check <plan-dir>` -- See workflow plan.md § Check Mode
+
+**Upstream context:**
+- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
+- Reads `conclusions.json` if available (implementation_scope seeds task generation)
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before starting the plan pipeline, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/plan.md' completely.
+
+### Wiki Knowledge Search (P1 addition)
+
+During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
+
+```
+phase_keywords = extract key terms from goal/title (2-5 terms)
+wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
+
+IF wiki_result exit code != 0 OR empty:
+  display "W003: Wiki search unavailable, continuing without prior knowledge"
+ELSE:
+  entries = JSON.parse(wiki_result).entries (limit to first 10)
+  wiki_context = structured block for downstream stages
+```
+
+### Issue Linkback (--gaps mode)
+
+After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:
+
+```
+For each created TASK-{NNN}.json that has issue_id:
+  Update corresponding issue in .workflow/issues/issues.jsonl:
+    task_refs: append TASK-{NNN} to array
+    task_plan_dir: relative path to .task/ directory
+    status: "planned"
+    updated_at: now()
+  Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
+```
+
+This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
+
+**Report format on completion:**
+
+```
+=== PLAN READY ===
+Phase: {phase_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+Collision: {collision_status}
+
+Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
+Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
+
+Next steps:
+  /maestro-execute              -- Execute the plan
+  /maestro-execute --dir {dir}  -- Execute specific plan
+  /maestro-plan {phase}         -- Re-plan with modifications
+```
+
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
+| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
+| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
+| E005 | error | Plan directory not found (--check) | Check path, use --dir |
+| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
+| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
+| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
+| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel)
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>