maestro-flow-one 0.2.0 → 0.2.2

package/maestro-flow/commands/lifecycle/overlay.md

@@ -0,0 +1,178 @@
+---
+name: maestro-overlay
+description: Create or edit command overlays from natural language
+argument-hint: "<intent>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Turn a user's natural-language instruction into a command overlay — a JSON patch file that augments one or more `.claude/commands/*.md` files non-invasively. Overlays live at `~/.maestro/overlays/` and are auto-applied by every `maestro install` run, so injected steps survive reinstalls. Use this skill when the user says things like "always run CLI verification after `/maestro-execute`", "require reading doc X before `/maestro-plan`", or "add a `ccw cli` quality check at the end of every quality-review".
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+**Overlay model** — an overlay is a JSON file with a `name`, one or more `targets` (command names without `.md`), and a list of `patches`. Each patch targets an XML section (`execution`, `required_reading`, `context`, `success_criteria`, etc.), a mode (`append`, `prepend`, `replace`, `new-section`), and `content`. On apply, the patcher wraps the content in hashed HTML-comment markers so re-apply is idempotent and removal is surgical.
+
+**Where overlays live**
+- User overlays: `~/.maestro/overlays/*.json` — created by this skill
+- Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `@~/.maestro/overlays/docs/*.md` inside patch content
+- Shipped examples: `~/.maestro/overlays/_shipped/` — read-only, do not edit
+
+**Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
+
+**Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`.
+</context>
+
+<execution>
+### 1. Parse user intent
+
+Treat the argument as natural-language intent. If unclear, ask up to 2 questions with AskUserQuestion: (a) which command(s) to target, (b) where in the command flow the injection should happen.
+
+### 2. Identify targets, injection points, and visualize
+
+For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred — untouched by overlays) or fall back to `~/.claude/commands/<name>.md`. Inspect the XML sections and pick the right one:
+
+- **New step after execution** → `section: execution`, `mode: append`
+- **Required reading** → `section: required_reading`, `mode: append`
+- **Preconditions / gating** → `section: context`, `mode: append`
+- **Output quality gate** → `section: success_criteria`, `mode: append`
+
+If the user wants a whole new section, use `mode: new-section` with `afterSection: execution` (or whichever anchor makes sense).
+
+**Injection point preview** — after selecting section + mode, render the target command's section map showing existing overlays and the new injection point:
+
+```
+=== maestro-execute.md (1 overlay exists) ===
+
+  <purpose>
+  <required_reading>
+  <context>
+  <execution>
+     ├─ [existing] cli-verify #1  "CLI Verification step"
+     >>> NEW: append here (your overlay)
+  <success_criteria>
+```
+
+Use AskUserQuestion to confirm:
+- **"Confirm"** — proceed with this injection point
+- **"Pick different section"** — re-select section/mode
+- **"Cancel"** — abort
+
+### 2.5. Skill chain configuration
+
+After confirming the injection point, ask whether this overlay should chain to another skill upon completion. This enables the overlay's injected content to hand off to a skill via AskUserQuestion at runtime — similar to how `/maestro` chains commands via `Skill({ skill: "...", args: "..." })`.
+
+Use AskUserQuestion:
+- **"No chain"** — standard overlay, no skill handoff
+- **"Chain to skill"** → ask for the target skill name (e.g., `quality-review`, `maestro-verify`, `quality-test`)
+- **"Chain with alternatives"** → ask for primary skill + 1-2 alternative skills
+
+If chain is selected, record the skill name(s) for use in Step 3.
+
+### 3. Draft the overlay JSON
+
+Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary of what and why>",
+  "targets": ["maestro-execute"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## CLI Verification (overlay)\n\nAfter execution, run:\n```\nccw cli -p \"PURPOSE: ...\" --mode analysis --rule analysis-review-code-quality\n```"
+    }
+  ]
+}
+```
+
+**Content guidelines**
+- Lead the injected block with a heading that includes `(overlay)` so readers see it's machine-injected
+- Keep content concise — overlays should add a step, not rewrite the command
+- `@~/.maestro/...` references are encouraged for pointing at docs
+- Escape `\n` in JSON strings; use a HEREDOC via Bash if content is long
+
+**Skill chain content** — if a chain was configured in Step 2.5, append a Skill Handoff block at the end of the patch `content`. The handoff uses AskUserQuestion so the user controls whether to proceed:
+
+```markdown
+---
+
+**Skill Handoff** (overlay)
+
+After the above step completes, use AskUserQuestion:
+- "Proceed to /quality-review" — Hand off to quality review
+- "Skip" — Continue with current command flow
+- "Alternative: /maestro-verify" — Run verification instead
+
+On user selection:
+- Proceed → Skill({ skill: "quality-review", args: "{phase}" })
+- Alternative → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Skip → continue normally
+```
+
+Handoff rules:
+- Always include a **"Skip"** option — the user can always decline the chain
+- Use `Skill({ skill: "<name>", args: "..." })` syntax consistent with maestro.md chainMap
+- Mark handoff heading with `(overlay)` tag
+- Support runtime variable placeholders: `{phase}`, `{description}`, `{session_id}`
+- Keep handoff block under 10 lines of markdown
+
+### 4. Install via `maestro overlay add`
+
+Run:
+
+```bash
+maestro overlay add ~/.maestro/overlays/<slug>.json
+```
+
+This validates the overlay, copies it into place (idempotent), and applies it across all known install scopes. On validation failure, fix the JSON and re-run.
+
+### 5. Report
+
+Show the user:
+- Path of the saved overlay JSON
+- Which targets were patched and which were skipped (missing/disabled)
+- Skill chain info (if configured)
+- A reminder that `maestro install` will auto-reapply on every run
+- How to remove: `maestro overlay remove <slug>`
+
+**Report format**
+
+```
+=== OVERLAY INSTALLED ===
+Name:    <slug>
+Path:    ~/.maestro/overlays/<slug>.json
+Targets: maestro-execute (applied), maestro-plan (skipped: missing)
+Chain:   quality-review (via AskUserQuestion) | none
+Scopes:  [global]
+
+Re-apply: maestro overlay apply
+Remove:   maestro overlay remove <slug>
+Inspect:  maestro overlay list
+```
+
+After the report, remind the user they can run `maestro overlay list` for the interactive TUI showing section maps and overlay management.
+</execution>
+
+<success_criteria>
+- [ ] Overlay JSON written to `~/.maestro/overlays/<slug>.json` and validates
+- [ ] `maestro overlay add` exited successfully and applied to at least one scope
+- [ ] Target command file(s) contain `<!-- maestro-overlay:<slug>#N hash=... -->` markers
+- [ ] Re-running `maestro overlay apply` produces no file changes (idempotent)
+- [ ] User shown the report with target list and removal instructions
+- [ ] Injection point preview shown (with existing overlays + `>>>` marker) and confirmed before drafting
+- [ ] If chain configured, `content` includes Skill Handoff block with AskUserQuestion + Skip option + `Skill()` calls
+</success_criteria>

package/maestro-flow/commands/lifecycle/plan.md

@@ -0,0 +1,154 @@
+---
+name: maestro-plan
+description: Plan phase execution with exploration and verification
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--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`, `-y`, `--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.
+
+### Codebase Docs Loading (P1 addition)
+
+During P1 Context Collection, after loading context files, load codebase documentation if available:
+
+```
+IF exists(.workflow/codebase/doc-index.json):
+  codebase_ctx = Read(.workflow/codebase/ARCHITECTURE.md) + Read(.workflow/codebase/FEATURES.md)
+  Pass codebase_ctx to planner agent as structural context
+ELSE:
+  display "W004: Codebase docs unavailable, continuing with code exploration only"
+```
+
+### 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")
+- [ ] Plan confidence scored in P4 with 5-dimension factor model
+- [ ] Plan readiness gate checked before P4.5 collision detection
+- [ ] Pressure pass completed on highest-complexity task
+- [ ] plan.json includes confidence section (overall, dimensions, pressure_pass)
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel) with confidence displayed
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>