maestro-flow-one 0.1.0

package/codex/maestro-flow/commands/lifecycle/execute.md

@@ -0,0 +1,318 @@
+---
+name: maestro-execute
+description: Wave-based parallel task execution via CSV wave pipeline. Reads plan.json to build CSV with pre-computed waves, executes tasks in parallel per wave with cross-wave context propagation. Core execution engine replacing maestro-execute command.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Wave-based parallel task execution using `spawn_agents_on_csv`. Reads plan.json to build a CSV where waves are pre-computed from the plan. Each wave runs tasks in parallel, with cross-wave context propagation via `prev_context`. This is the core execution engine of the maestro pipeline.
+
+**Core workflow**: Load Plan -> Build CSV from Tasks -> Wave-by-Wave Parallel Execution -> Aggregate Results
+
+**Topology**: Custom (waves inherited from plan.json -- no Kahn's algorithm needed)
+
+```
++---------------------------------------------------------------------------+
+|                    TASK EXECUTION CSV WAVE WORKFLOW                        |
++---------------------------------------------------------------------------+
+|                                                                           |
+|  Phase 1: Plan Resolution -> CSV                                          |
+|     +-- Resolve phase directory (or --dir path)                           |
+|     +-- Read plan.json + .task/TASK-*.json definitions                    |
+|     +-- Detect completed tasks (breakpoint resume)                        |
+|     +-- Build tasks.csv with one row per pending task                     |
+|     +-- Waves inherited from plan.json (pre-computed)                     |
+|     +-- Load project specs for executor context                           |
+|     +-- User validates task breakdown (skip if -y)                        |
+|                                                                           |
+|  Phase 2: Wave Execution Engine                                           |
+|     +-- For each wave (sequential):                                       |
+|     |   +-- Wave N: Task Execution (parallel within wave)                 |
+|     |   |   +-- Each agent implements one task                            |
+|     |   |   +-- Agent reads task definition + convergence criteria        |
+|     |   |   +-- Agent creates/modifies files per task.files               |
+|     |   |   +-- Agent verifies convergence.criteria (max 3 fix attempts)  |
+|     |   |   +-- Agent writes .summaries/TASK-{NNN}-summary.md             |
+|     |   |   +-- Atomic commit if --auto-commit                            |
+|     |   |   +-- Discoveries shared via board (patterns, blockers)         |
+|     |   +-- Merge wave results into master tasks.csv                      |
+|     |   +-- Build prev_context for next wave from completed findings      |
+|     |   +-- If blocked tasks: prompt user (skip if -y: auto-continue)     |
+|     +-- discoveries.ndjson shared across all waves (append-only)          |
+|                                                                           |
+|  Phase 3: Results Aggregation                                             |
+|     +-- Export results.csv                                                |
+|     +-- Update .task/TASK-*.json statuses                                 |
+|     +-- Update index.json execution progress                             |
+|     +-- Update state.json project progress                               |
+|     +-- Generate context.md with execution report                        |
+|     +-- Auto-sync codebase docs (if configured)                          |
+|     +-- Display summary with next steps                                  |
+|                                                                           |
++---------------------------------------------------------------------------+
+```
+</purpose>
+
+<context>
+```bash
+$maestro-execute "3"
+$maestro-execute -c 4 "3 --auto-commit"
+$maestro-execute -y "3 --method cli"
+$maestro-execute "3 --dir .workflow/scratch/quick-fix"
+$maestro-execute --continue "20260318-execute-P3-phase3"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 5)
+- `--continue`: Resume existing session
+
+**Inner flags** (passed inside quotes):
+- `--auto-commit`: Atomic git commit after each task completion
+- `--method agent|cli`: Override execution method (default: from config.json)
+- `--dir <path>`: Use arbitrary directory instead of phase resolution (scratch mode)
+
+When `--yes` or `-y`: Auto-confirm task breakdown, skip blocked-task prompts, auto-continue through all waves.
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
+</context>
+
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,scope,convergence_criteria,hints,execution_directives,deps,context_from,wave,status,findings,files_modified,tests_passed,error
+"TASK-001","Setup auth module","Create authentication module with JWT token generation and verification. Export verifyToken and generateToken functions.","src/auth/","auth.ts contains export function verifyToken(; auth.ts contains export function generateToken(","Reference existing middleware pattern in src/middleware/auth.ts","npm test -- --grep auth","","","1","","","","",""
+"TASK-002","Create user model","Define User interface and database schema with email, passwordHash, role fields. Use existing Result type pattern.","src/models/","user.ts contains export interface User; user.ts contains email: string","See src/models/session.ts for existing model pattern","npm test -- --grep user","","","1","","","","",""
+"TASK-003","Auth middleware","Create Express middleware that validates JWT from Authorization header. Use verifyToken from auth module. Return 401 on invalid token.","src/middleware/","auth-middleware.ts contains export function authMiddleware(; auth-middleware.ts contains verifyToken","Follows existing middleware pattern in src/middleware/logging.ts","npm test -- --grep middleware","TASK-001","TASK-001","2","","","","",""
+"TASK-004","Login endpoint","Implement POST /api/login endpoint. Validate credentials against user model, return JWT on success. Use generateToken from auth module.","src/routes/","login.ts contains router.post('/api/login'; login.ts contains generateToken(","Wire into existing Express app in src/app.ts","curl -X POST localhost:3000/api/login","TASK-001;TASK-002","TASK-001;TASK-002","2","","","","",""
+"TASK-005","Integration tests","Write integration tests for full auth flow: register, login, access protected route, token refresh.","tests/","tests/auth.test.ts exists; npm test exits with code 0","Use existing test setup in tests/setup.ts","npm test","TASK-003;TASK-004","TASK-003;TASK-004","3","","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Task ID (TASK-NNN format, from plan.json) |
+| `title` | Input | Short task title from task definition |
+| `description` | Input | Full task description from TASK-*.json |
+| `scope` | Input | Target file/directory glob from task.files |
+| `convergence_criteria` | Input | Grep-verifiable completion criteria (semicolon-separated) |
+| `hints` | Input | Implementation hints + reference files from task definition |
+| `execution_directives` | Input | Verification commands to run after implementation |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
+| `wave` | Computed | Wave number from plan.json wave assignment |
+| `status` | Output | `pending` -> `completed` / `failed` / `blocked` / `skipped` |
+| `findings` | Output | Implementation notes and observations (max 500 chars) |
+| `files_modified` | Output | Semicolon-separated list of created/modified files |
+| `tests_passed` | Output | Test pass/fail status from execution_directives |
+| `error` | Output | Error message if failed or blocked |
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates `wave-{N}.csv` with extra `prev_context` column populated from predecessor task findings.
+
+### Output Artifacts
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
+| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
+| `wave-{N}-results.csv` | Per-wave output | Created by spawn_agents_on_csv |
+| `results.csv` | Final export of all task results | Created in Phase 3 |
+| `discoveries.ndjson` | Shared exploration board | Append-only, carries across waves |
+| `context.md` | Human-readable execution report | Created in Phase 3 |
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-execute-P{N}-{slug}/
++-- tasks.csv
++-- results.csv
++-- discoveries.ndjson
++-- context.md
++-- config.json
++-- wave-{N}.csv (temporary)
++-- wave-{N}-results.csv (temporary)
+```
+</csv_schema>
+
+<invariants>
+1. **Start Immediately**: First action is session initialization, then Phase 1
+2. **Wave Order is Sacred**: Never execute wave N+1 before wave N completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all execution state
+4. **Context Propagation**: prev_context built from master CSV findings, not from memory
+5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
+6. **Cascading Skip on Failure**: If a task fails/blocks, all dependent tasks are skipped
+7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+8. **Max 3 Fix Attempts**: Per task, auto-fix convergence failures up to 3 times, then mark blocked
+9. **Breakpoint Resume**: Always detect completed tasks and skip them on re-run
+10. **DO NOT STOP**: Continuous execution until all waves complete or user explicitly stops
+</invariants>
+
+<execution>
+
+### Session Initialization
+
+```
+Parse from $ARGUMENTS:
+  AUTO_YES        ← --yes | -y
+  continueMode    ← --continue
+  maxConcurrency  ← --concurrency | -c N  (default: 5)
+  autoCommit      ← --auto-commit
+  executionMethod ← --method agent|cli  (default: from config.json)
+  scratchDir      ← --dir <path>  (default: null)
+  phaseArg        ← remaining text after flag removal
+
+Derive:
+  dateStr        ← UTC+8 YYYYMMDD
+  sessionId      ← scratchDir ? "{dateStr}-execute-scratch" : "{dateStr}-execute-P{phaseArg}-{phaseSlug}"
+  sessionFolder  ← ".workflow/.csv-wave/{sessionId}"
+
+mkdir -p {sessionFolder}
+```
+
+### Phase 1: Plan Resolution -> CSV
+
+**Objective**: Resolve phase, load plan + task definitions, detect resume point, generate tasks.csv.
+
+**Decomposition Rules**:
+
+1. **Plan resolution** (per scratch-milestone-architecture):
+
+| Input | Resolution |
+|-------|------------|
+| `--dir <path>` | Use path directly (scratch plan dir) |
+| No args | Find all pending plans for current milestone from state.json.artifacts[] |
+| Number (e.g., `3`) | Find pending plans for phase N from state.json.artifacts[] |
+
+   For multi-plan: execute sequentially. Each plan is a full CSV session.
+
+2. **Load plan**: Read `{PLAN_DIR}/plan.json` for wave structure and task assignments
+
+3. **Detect completed tasks (breakpoint resume)**: Read `.task/TASK-{NNN}.json` for each task; exclude completed ones from CSV. Log resume count.
+
+4. **Build tasks.csv**: For each pending task per wave, read `.task/TASK-{NNN}.json` and extract: title, description, scope (from files), convergence.criteria, hints, execution_directives. Set `deps` from task dependency, `context_from` = deps, `wave` from plan.json.
+
+5. **Load project specs**: Read `.workflow/specs/` for coding conventions and architecture constraints (passed to all agents)
+
+6. **User validation**: Display task/wave breakdown. Skip if AUTO_YES.
+
+### Phase 2: Wave Execution Engine
+
+**Objective**: Execute tasks wave-by-wave via spawn_agents_on_csv with cross-wave context propagation.
+
+#### Per-Wave Execution Loop
+
+For each wave N in ascending order:
+
+1. Extract wave N pending rows from master `tasks.csv` (skip wave if none)
+2. Build `prev_context` per task from completed predecessor findings
+3. Write `wave-{N}.csv` with `prev_context` column, then execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-${N}.csv`,
+  id_column: "id",
+  instruction: buildExecutorInstruction(sessionFolder, phaseDir, autoCommit, specsContent),
+  max_concurrency: maxConcurrency, max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
+  output_schema: { id, status: [completed|failed|blocked], findings, files_modified, tests_passed, error }
+})
+```
+
+4. Merge results into master `tasks.csv`, delete `wave-{N}.csv`
+
+#### Blocked Task Handling
+
+After each wave: if blocked tasks exist, prompt user to continue or stop (AUTO_YES: auto-continue). Skip tasks whose deps are blocked/failed.
+
+#### Cascading Skip
+
+Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with error "Dependency {dep_id} blocked/failed".
+
+### Phase 3: Results Aggregation
+
+**Objective**: Update all state files and generate execution report.
+
+1. Export final `tasks.csv` as `results.csv`
+
+2. **Update task files**: Write each task's status from CSV back to `.task/{id}.json`
+
+3. **Issue status sync**: For tasks with `issue_id`, update `.workflow/issues/issues.jsonl`:
+   - All task_refs completed -> `issue.status = "resolved"`; any failed -> `"in_progress"`
+   - Append history entry: `{ action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }`
+
+4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`
+
+5. **Extract incremental specs**: Read `.summaries/`, use `maestro spec add` CLI:
+   - Learnings/pitfalls → `maestro spec add learning "<title>" "<content>" --keywords ... --source execute:{PLAN_DIR}`
+   - Design rationale → `maestro spec add coding "<title>" "<content>" --keywords ...`
+   - Root cause/workaround → `maestro spec add debug "<title>" "<content>" --keywords ...`
+   Mark artifact `harvested: true`
+
+6. **Post-task Knowledge Inquiry**: Prompt user to capture knowledge when:
+   - Execution deviation detected (plan change) -> `/spec-add arch`
+   - Retry success (>=2 retries) -> `/spec-add debug`
+   - Implicit design rationale found -> `/spec-add learning`
+
+7. **Generate context.md**: Execution report with summary (tasks/blocked/waves/auto-commit), per-wave result table (task, status, files, tests), blocked tasks, discovery board summary, next steps.
+
+8. **Auto-sync** (if config.json.codebase.auto_sync_after_execute == true): detect changed files, trigger codebase doc update.
+
+9. **Display completion report**: Phase, completed/blocked counts, wave progress, paths to `.summaries/` and `.task/`, next step suggestions (`maestro-verify`, `manage-status`).
+
+### Shared Discovery Board Protocol
+
+#### Standard Discovery Types
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `code_pattern` | `data.name` | `{name, file, description}` | Reusable code pattern found during implementation |
+| `integration_point` | `data.file` | `{file, description, exports[]}` | Module connection point discovered |
+| `convention` | singleton | `{naming, imports, formatting}` | Project coding conventions observed |
+| `blocker` | `data.issue` | `{issue, severity, impact}` | Blocking issue encountered |
+| `tech_stack` | singleton | `{framework, language, tools[]}` | Technology stack detail confirmed |
+| `test_command` | `data.command` | `{command, scope, result}` | Working test command discovered |
+
+#### Protocol
+
+Read `discoveries.ndjson` before implementation. Append-only: dedup by type+key before writing, never modify/delete.
+
+```bash
+echo '{"ts":"<ISO>","worker":"TASK-001","type":"code_pattern","data":{"name":"Result type","file":"src/types/result.ts","description":"All functions return Result<T,E> for error handling"}}' >> {session_folder}/discoveries.ndjson
+```
+</execution>
+
+<error_codes>
+
+| Error | Resolution |
+|-------|------------|
+| Phase directory not found | Abort with error: "Phase {N} not found" |
+| plan.json not found | Abort with error: "No plan found -- run plan first" |
+| No pending tasks (all completed) | Abort with info: "All tasks already completed" |
+| Task file (.task/TASK-*.json) missing | Skip task, log error, mark as failed |
+| Agent spawn fails | Retry once, then mark task as blocked with checkpoint |
+| Convergence criteria not met after 3 attempts | Mark task as blocked, write checkpoint |
+| Git commit fails (--auto-commit) | Log warning, continue (task still marked completed) |
+| All tasks in wave blocked | Stop execution, report blocked wave |
+| CSV parse error | Validate format, show line number |
+| discoveries.ndjson corrupt | Ignore malformed lines, continue |
+| Continue mode: no session found | List available sessions |
+</error_codes>
+
+<success_criteria>
+- [ ] Session folder created with valid tasks.csv
+- [ ] All waves executed in order with cross-wave context propagation
+- [ ] Completed tasks have .summaries/TASK-{NNN}-summary.md
+- [ ] .task/TASK-*.json statuses updated to match execution results
+- [ ] state.json updated with EXC artifact
+- [ ] context.md produced with execution report
+- [ ] Blocked tasks have checkpoint info for resume
+- [ ] Cascading skip applied for dependent tasks
+- [ ] discoveries.ndjson append-only throughout
+</success_criteria>

package/codex/maestro-flow/commands/lifecycle/fork.md

@@ -0,0 +1,98 @@
+---
+name: maestro-fork
+description: Create git worktree for milestone-level parallel development, or sync existing worktree with main. Copies .workflow/ context and scratch artifacts into worktree since .workflow/ is gitignored.
+argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Create a git worktree for an entire milestone, enabling inter-milestone parallel development.
+The worktree scope is milestone-level — all scratch artifacts for that milestone are owned by
+the worktree. Since `.workflow/` is gitignored, this command explicitly copies project context
+and milestone scratch artifacts into the worktree.
+
+Also supports `--sync` mode to pull latest main into an active worktree.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/fork.md
+</required_reading>
+
+<context>
+$ARGUMENTS — milestone number and optional flags.
+
+**Modes:**
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Fork | `-m 2` or `2` | Create worktree for milestone 2 |
+| Sync | `-m 2 --sync` | Sync existing worktree with main |
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number
+- `--base <branch>`: Override base branch (default: HEAD)
+- `--sync`: Pull main into existing worktree, re-copy shared artifacts
+
+**Worktree layout:**
+```
+.worktrees/m{N}-{slug}/
+├── .workflow/
+│   ├── worktree-scope.json     (milestone scope marker)
+│   ├── state.json              (scoped — this milestone's artifacts only)
+│   ├── project.md, roadmap.md, config.json, specs/  (read-only copies)
+│   └── scratch/                (milestone's existing + new artifacts)
+└── <source code>
+```
+
+**Artifact scoping:**
+Fork copies scratch artifacts belonging to the target milestone (filtered from `state.json.artifacts[]` where `milestone == target`). New work creates scratch artifacts normally, registered in the worktree's local `state.json`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/fork.md' completely.
+
+**Fork flow:**
+1. Validate: initialized, roadmap exists, not inside worktree, milestone not forked
+2. Resolve milestone: `state.json.milestones[N-1]`
+3. Create worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
+4. Copy `.workflow/`: shared files + milestone scratch artifacts
+5. Write `worktree-scope.json` with milestone scope
+6. Write scoped `state.json` (this milestone's artifacts only)
+7. Update main: `worktrees.json` registry, mark milestone `"forked"`
+
+**Sync flow:**
+1. Find worktree from `worktrees.json`
+2. `cd worktree && git merge main`
+3. Re-copy shared files (project.md, roadmap.md, config.json, specs/)
+
+**Next steps:**
+- Fork → `cd {wt.path} && $maestro-analyze`
+- Sync → resume work in worktree
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Project not initialized | Run maestro-init |
+| E002 | error | No roadmap found | Run maestro-roadmap |
+| E003 | error | Running inside a worktree | Run from main worktree |
+| E004 | error | No milestone number | Provide `-m <N>` |
+| E006 | error | Milestone out of range | Check available milestones |
+| E008 | error | Milestone already has active worktree | Merge or cleanup first |
+</error_codes>
+
+<success_criteria>
+Fork mode:
+- [ ] Milestone resolved from state.json.milestones[]
+- [ ] Git worktree created with branch `milestone/{slug}`
+- [ ] Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/)
+- [ ] Milestone scratch artifacts copied (filtered from artifact registry)
+- [ ] `worktree-scope.json` written with milestone scope
+- [ ] Scoped `state.json` written (this milestone's artifacts only)
+- [ ] `worktrees.json` registry updated in main worktree
+- [ ] Milestone marked `"forked"` in main state.json
+
+Sync mode:
+- [ ] Git merge main into worktree branch
+- [ ] Shared artifacts re-copied
+- [ ] Conflicts reported if any
+</success_criteria>

package/codex/maestro-flow/commands/lifecycle/init.md

@@ -0,0 +1,134 @@
+---
+name: maestro-init
+description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
+argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
+
+When `-y`: After config questions, run research without further interaction. Expects idea document via @ reference.
+</purpose>
+
+<context>
+
+```bash
+$maestro-init ""
+$maestro-init "-y"
+$maestro-init "--from-brainstorm 20260318-brainstorm-auth"
+```
+
+**Flags**:
+- `-y`: Skip interactive questioning; extract from provided document
+- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+
+**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
+
+</context>
+
+<invariants>
+1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
+2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless -y)
+3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
+4. **Templates are source of truth** — always read templates before writing files
+5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)
+</invariants>
+
+<execution>
+
+### Step 1: Parse Arguments
+
+Extract flags from arguments:
+- `-y` flag presence
+- `--from-brainstorm SESSION-ID` value
+- Remaining text as project description
+
+### Step 2: Detect Project State
+
+Check for `.workflow/state.json` and common manifests (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`).
+
+Classify as:
+- **existing**: `.workflow/state.json` found — warn and exit (E002)
+- **code**: Source files present but no `.workflow/` — onboarding existing codebase
+- **empty**: Greenfield project
+
+### Step 3: Gather Project Information
+
+**If `--from-brainstorm`**:
+- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
+- Extract: vision, goals, constraints, terminology, tech decisions
+- Skip interactive questioning
+
+**If `-y`**:
+- Extract project info from provided document/@ reference
+- Minimal interactive questions (confirm core value only)
+
+**Otherwise (interactive)**:
+- Deep questioning flow:
+  1. What is the core value proposition?
+  2. Who are the target users?
+  3. What are the key requirements? (follow threads, don't rush)
+  4. What are known constraints/limitations?
+  5. What tech stack preferences exist?
+- Follow each thread with clarifying questions until satisfied
+
+### Step 4: Read Templates
+
+Read the following templates:
+- `~/.maestro/templates/project.md`
+- `~/.maestro/templates/state.json`
+- `~/.maestro/templates/config.json`
+
+### Step 5: Create .workflow/ Structure
+
+Create directories: `.workflow/specs`, `.workflow/scratch`, `.workflow/codebase`.
+
+### Step 6: Write project.md
+
+Populate template with: project name, core value proposition, requirements (Validated/Active/Out of Scope), key decisions, constraints, tech stack. Write to `.workflow/project.md`.
+
+### Step 7: Write state.json
+
+Initialize from template with `current_milestone: null`, `status: "initialized"`, empty `artifacts[]`. Write to `.workflow/state.json`.
+
+### Step 8: Write config.json
+
+Configuration questions (or defaults for -y): granularity (fine/medium/coarse), workflow agents (enable/disable), gate preferences. Write to `.workflow/config.json`.
+
+### Step 9: Initialize specs/
+
+Run `Bash("maestro spec init")` to create empty seed files in `.workflow/specs/`.
+
+If project state is **code** (existing source files detected):
+- Auto-trigger `Skill({ skill: "maestro-flow", args: "--cmd spec-setup" })` to scan codebase and populate specs with detected conventions.
+
+If project state is **empty** (greenfield):
+- Skip spec-setup. Specs are populated progressively by analyze, plan, and execute stages via `maestro spec add`.
+
+### Step 10: Completion Report
+
+Display created files and next steps: `$maestro-roadmap --mode full` (full spec), `$maestro-roadmap` (light), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No arguments when -y requires document | Ask user for document reference |
+| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
+| E003 | error | Brainstorm session not found | List available sessions |
+| W001 | warning | Could not detect tech stack | Continue with manual input |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Project state correctly detected (empty/code/existing)
+- [ ] `.workflow/` directory structure created
+- [ ] `project.md` populated with project information
+- [ ] `state.json` initialized with correct status
+- [ ] `config.json` written with configuration
+- [ ] `specs/` initialized with convention files
+- [ ] Completion report displayed with next steps
+</success_criteria>

package/codex/maestro-flow/commands/lifecycle/learn.md

@@ -0,0 +1,80 @@
+---
+name: maestro-learn
+description: Learning coordinator — route intent to learn commands, execute single or multi-step chains sequentially. Supports 7 chains from single-step (follow, investigate) to multi-step (deep-understand, pattern-catalog).
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain.
+Executes commands sequentially with session tracking.
+
+```
+Intent → Route to Chain → Execute Steps → Session Summary
+```
+</purpose>
+
+<context>
+$ARGUMENTS — learning intent text, or flags.
+
+**Flags:**
+- `-y, --yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force specific chain
+
+**Chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer "how/why" questions |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Session state:** `.workflow/learning/.maestro-learn/{session_id}/status.json`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+**Intent routing:**
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| read, follow, walk through, understand | `follow` |
+| why, how, what if, investigate | `investigate` |
+| pattern, decompose, catalog | `decompose` |
+| opinion, review, challenge, consult | `second-opinion` |
+| retro, git, commit, decision | `retro` |
+| thorough, deep | `deep-understand` |
+
+No match → present menu via AskUserQuestion. Max 1 clarification.
+
+### Step 2: Resolve Target & Build Args
+Map chain to skill invocations. Extract target and flags from arguments.
+
+### Step 3: Confirm & Execute
+- `--dry-run`: display chain and exit
+- Not `-y`: show plan, ask confirmation
+- Execute each step sequentially. On failure: retry/skip/abort
+- Write session `status.json`, display summary
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent provided | Provide learning goal or use --chain |
+| E002 | error | Cannot determine intent | Rephrase or use --chain |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous | Present options |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed
+- [ ] Session summary displayed with next-step routing
+</success_criteria>