maestro-flow 0.3.15 → 0.3.17

package/.codex/skills/quality-review/SKILL.md

@@ -144,30 +144,16 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 
 ### Session Initialization
 
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const continueMode = $ARGUMENTS.includes('--continue')
-const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
-const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 6
-
-// Parse review-specific flags
-const levelMatch = $ARGUMENTS.match(/--level\s+(quick|standard|deep)/)
-const dimsMatch = $ARGUMENTS.match(/--dimensions\s+([\w,]+)/)
-
-// Clean phase text
-const phaseArg = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--level\s+\w+|--dimensions\s+[\w,]+/g, '')
-  .trim()
+Parse `$ARGUMENTS` to extract:
+- `AUTO_YES` from `--yes` / `-y`
+- `continueMode` from `--continue`
+- `maxConcurrency` from `--concurrency N` / `-c N` (default: 6)
+- `levelMatch` from `--level quick|standard|deep`
+- `dimsMatch` from `--dimensions <list>`
+- `phaseArg` = remaining text after stripping all flags
 
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `${dateStr}-review-P${phaseArg}-${phaseSlug}`  // phaseSlug from index.json or roadmap
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-
-Bash(`mkdir -p ${sessionFolder}`)
-```
+Session ID: `{YYYYMMDD}-review-P{phaseArg}-{phaseSlug}` (phaseSlug from index.json or roadmap)
+Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 
 ### Phase 1: Phase Resolution -> CSV
 
@@ -175,10 +161,10 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
-2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: execute → .summaries/.task/, review → review.json, debug → understanding.md, test → uat.md. Extract conclusions that may affect this review (prior verdicts, root causes, UAT gaps) and pass as prior quality context to reviewer agents.
-3. **File collection**: Read `.task/TASK-*.json` -> collect all `files[].path` where action != "read"
-3. **Level detection**:
+1. **Phase resolution**: Resolve `{phaseArg}` via `state.json` artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
+2. **Related session discovery**: Query `state.json.artifacts[]` for matching phase + milestone. Extract prior quality context (verdicts, root causes, UAT gaps) from artifact outputs by type (execute → .summaries/.task/, review → review.json, debug → understanding.md, test → uat.md)
+3. **File collection**: Read `.task/TASK-*.json` → collect `files[].path` where action != "read"
+4. **Level detection**:
 
 | Condition | Level |
 |-----------|-------|
@@ -187,7 +173,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 | 4-19 changed files | standard |
 | >=20 files OR phase marked critical | deep |
 
-4. **Dimension selection**:
+5. **Dimension selection**:
 
 | Level | Dimensions |
 |-------|------------|
@@ -197,9 +183,8 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 If `--dimensions` flag provided, override with explicit list.
 
-5. **Specs loading**: Read `.workflow/specs/` for project conventions (unless `--skip-specs`)
-
-6. **CSV generation**: One row per dimension + one aggregation row.
+6. **Specs loading**: Read `.workflow/specs/` for project conventions (unless `--skip-specs`)
+7. **CSV generation**: One row per dimension + one aggregation row
 
 **Wave computation**: Simple 2-wave -- all dimension tasks = wave 1, aggregation = wave 2.
 
@@ -211,11 +196,7 @@ If `--dimensions` flag provided, override with explicit list.
 
 #### Wave 1: Dimension Reviews (Parallel)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 1` AND `status == pending`
-3. No prev_context needed (wave 1 has no predecessors)
-4. Write `wave-1.csv`
-5. Execute:
+Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-1.csv` (no prev_context needed).
 
 ```javascript
 spawn_agents_on_csv({
@@ -240,32 +221,20 @@ spawn_agents_on_csv({
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
+Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`.
 
 #### Wave 2: Aggregation + Deep-Dive
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 2` AND `status == pending`
-3. Check deps -- if all wave 1 tasks failed, skip aggregation
-4. Build `prev_context` from wave 1 findings:
-   ```
-   [Task 1: Correctness Review] Found 2 critical issues: null pointer in login handler...
-   [Task 2: Security Review] Found 1 high issue: SQL injection in query builder...
-   ...
-   ```
-5. Write `wave-2.csv` with `prev_context` column
-6. Execute `spawn_agents_on_csv` for aggregation agent
-7. Merge results into master `tasks.csv`
-8. Delete `wave-2.csv`
+Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation.
+
+Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task).
+Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` → merge results → delete `wave-2.csv`.
 
 ### Phase 3: Results Aggregation
 
 **Objective**: Generate final results and human-readable report.
 
-1. Read final master `tasks.csv`
-2. Export as `results.csv`
-3. Build `review.json`:
+Export master `tasks.csv` as `results.csv`. Build `review.json`:
 
 ```json
 {
@@ -282,7 +251,7 @@ spawn_agents_on_csv({
 }
 ```
 
-4. Generate `context.md`:
+Generate `context.md`:
 
 ```markdown
 # Code Review Report -- Phase {phase}
@@ -315,7 +284,7 @@ spawn_agents_on_csv({
 {list of created issue IDs}
 ```
 
-5. **Verdict determination**:
+**Verdict determination**:
 
 | Condition | Verdict |
 |-----------|---------|
@@ -325,7 +294,7 @@ spawn_agents_on_csv({
 | Medium findings > 5 | WARN |
 | Otherwise | PASS |
 
-6. **Issue creation**: Based on level thresholds:
+**Issue creation** by level threshold:
 
 | Level | Create Issues For |
 |-------|------------------|
@@ -333,11 +302,11 @@ spawn_agents_on_csv({
 | standard | critical + high |
 | deep | critical + high + medium |
 
-7. **Phase index update**: Update `{artifact_dir}/index.json` with review status.
+**Phase index update**: Update `{artifact_dir}/index.json` with review status.
 
-8. **Register artifact**: Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
+**Register artifact**: Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
 
-9. Display summary.
+Display summary.
 
 ### Shared Discovery Board Protocol
 
@@ -362,11 +331,7 @@ spawn_agents_on_csv({
 
 #### Protocol
 
-1. **Read** `{session_folder}/discoveries.ndjson` before own review
-2. **Skip covered**: If discovery of same type + dedup key exists, skip
-3. **Write immediately**: Append findings as found
-4. **Append-only**: Never modify or delete
-5. **Deduplicate**: Check before writing
+Read `{session_folder}/discoveries.ndjson` before own review. Deduplicate by type + dedup key before writing. Append-only — never modify or delete.
 
 ```bash
 echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"src/auth/login.ts:42","type":"sql_injection","severity":"critical","cwe":"CWE-89"}}' >> {session_folder}/discoveries.ndjson

package/.codex/skills/quality-sync/SKILL.md

@@ -30,9 +30,7 @@ $quality-sync "--since abc123 --dry-run"
 
 ### Step 1: Validate
 
-```bash
-test -d .workflow || exit 1  # E001: not initialized
-```
+Verify `.workflow/` directory exists — if missing, raise E001.
 
 ### Step 2: Detect Changes
 
@@ -72,14 +70,7 @@ Update `state.json`:
 
 Update affected `index.json` files in phase directories if task files were modified.
 
-Display summary:
-```
-=== SYNC COMPLETE ===
-Files changed: {N}
-Components affected: {C}
-Features affected: {F}
-Docs updated: {D}
-```
+Display summary: files changed, components affected, features affected, docs updated.
 
 </execution>
 

package/.codex/skills/quality-test/SKILL.md

@@ -55,10 +55,7 @@ No auto mode -- UAT is inherently interactive. `--auto-fix` only automates gap c
 
 ### Step 2: Check Active Sessions
 
-```bash
-find .workflow/scratch -name "uat.md" -type f 2>/dev/null | head -5
-find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
-```
+Scan `.workflow/scratch` and `.workflow/phases` for existing `uat.md` files.
 
 - If active sessions exist and no target specified: display session table, ask user to resume or start new
 - If `--session ID` specified: resume that session directly (skip to Step 9)
@@ -88,21 +85,7 @@ Write `{target_dir}/uat.md` with frontmatter (status, target, started), Current
 
 ### Step 7: Present Test (Interactive Loop)
 
-Present one test at a time:
-```
-------------------------------------------------------------
-  TEST {number}/{total}: {name}
-------------------------------------------------------------
-
-Expected behavior:
-{expected}
-
-------------------------------------------------------------
-> Type "pass" or describe what's wrong
-------------------------------------------------------------
-```
-
-Wait for user response (plain text).
+Present one test at a time: show `TEST {number}/{total}: {name}`, expected behavior, then prompt user to type "pass" or describe what is wrong. Wait for user response (plain text).
 
 ### Step 8: Process Response
 
@@ -142,18 +125,7 @@ Read `uat.md`, find first `result: [pending]` test, announce progress, continue
 
 ### Step 11: Auto-Diagnose
 
-Cluster related gaps by component/area. Spawn one debug Agent per cluster:
-
-```
-Agent({
-  subagent_type: "general-purpose",
-  description: "Diagnose UAT gap cluster: {cluster_name}",
-  prompt: "Investigate UAT failures. Gaps: {gap list}. Find root cause, fix direction, affected files, evidence (file:line).",
-  run_in_background: false
-})
-```
-
-Update `uat.md` gaps with diagnosis results (root_cause, fix_direction, affected_files).
+Cluster related gaps by component/area. Spawn one debug Agent per cluster to investigate UAT failures — find root cause, fix direction, affected files, evidence (file:line). Update `uat.md` gaps with diagnosis results.
 
 ### Step 12: Gap Closure Decision
 
@@ -169,20 +141,7 @@ Update issue lifecycle during gap-fix loop (registered -> planning -> executing
 
 ### Step 13: Report
 
-```
-=== UAT RESULTS ===
-Target:      {target}
-Smoke Tests: {smoke_count} run, {smoke_pass} passed
-UAT Tests:   {total} total
-  Passed:    {passed}
-  Issues:    {issues} ({blocker_count} blockers, {major_count} major)
-  Skipped:   {skipped}
-Diagnosis:   {diagnosed_count}/{issues} gaps diagnosed
-Auto-fix:    {fixed_count} gaps resolved
-
-Next steps:
-  {suggested_next_command}
-```
+Display summary: target, smoke test results, UAT counts (passed/issues/skipped with severity breakdown), diagnosis coverage, auto-fix results, and suggested next command.
 </execution>
 
 <error_codes>

package/.codex/skills/quality-test-gen/SKILL.md

@@ -139,29 +139,21 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column (empty for w
 
 ### Session Initialization
 
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const continueMode = $ARGUMENTS.includes('--continue')
-const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
-const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 6
-
-// Parse test-gen-specific flags
-const typeMatch = $ARGUMENTS.match(/--type\s+(unit|integration|e2e)/)
-const frameworkMatch = $ARGUMENTS.match(/--framework\s+([\w]+)/)
-
-// Clean phase text
-const phaseArg = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--type\s+\w+|--framework\s+[\w]+/g, '')
-  .trim()
-
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `${dateStr}-testgen-P${phaseArg}-${phaseSlug}`  // phaseSlug from index.json or roadmap
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-
-Bash(`mkdir -p ${sessionFolder}`)
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 6)
+  typeFilter     ← --type unit|integration|e2e  (default: all)
+  framework      ← --framework jest|vitest|...  (default: auto-detect)
+  phaseArg       ← remaining text after flag removal
+
+Derive:
+  dateStr        ← UTC+8 YYYYMMDD
+  sessionId      ← "{dateStr}-testgen-P{phaseArg}-{phaseSlug}"
+  sessionFolder  ← ".workflow/.csv-wave/{sessionId}"
+
+mkdir -p {sessionFolder}
 ```
 
 ### Phase 1: Gap Analysis -> CSV
@@ -172,14 +164,9 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
 
-2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: review → review.json (critical findings become focused test targets), debug → understanding.md (confirmed root causes become regression test targets), test → uat.md (UAT gaps inform which behaviors need tests). Extract conclusions that may affect test generation priorities.
+2. **Related session discovery**: Query `state.json.artifacts[]` for matching phase+milestone. Extract relevant outputs by type: review -> review.json (focused test targets), debug -> understanding.md (regression targets), test -> uat.md (behavior gaps).
 
-3. **Test infrastructure discovery**:
-   - Find config files: `jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`
-   - Find existing test files: `*.test.*`, `*.spec.*`, `test_*`
-   - Find test utilities: `test-utils.*`, `testHelper*`, `conftest.py`
-   - Read 2-3 existing tests to learn patterns (imports, assertions, mocking)
-   - If no framework detected: Error E003
+3. **Test infrastructure discovery**: Scan for config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`), existing test files (`*.test.*`, `*.spec.*`, `test_*`), and test utilities. Read 2-3 existing tests to learn patterns. Error E003 if no framework detected.
 
 3. **Gap identification**:
 
@@ -219,72 +206,35 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 #### Wave 1: Test Generation (Independent Parallel)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 1` AND `status == pending`
-3. No prev_context needed (single wave, no predecessors)
-4. Write `wave-1.csv`
-5. Execute:
+1. Extract wave 1 pending rows from master `tasks.csv` into `wave-1.csv` (no prev_context needed)
+2. Execute:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
   instruction: buildTestGenInstruction(sessionFolder),
-  max_concurrency: maxConcurrency,
-  max_runtime_seconds: 600,
+  max_concurrency: maxConcurrency, max_runtime_seconds: 600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      tests_created: { type: "string" },
-      coverage_delta: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
+  output_schema: { id, status: [completed|failed], findings, tests_created, coverage_delta, error }
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
-
-**Agent Instruction Template** (`buildTestGenInstruction`):
+3. Merge results into master `tasks.csv`, delete `wave-1.csv`
 
-Each agent receives:
-- Source file path and test type classification
-- Detected framework and existing test patterns
-- Gap references (requirement IDs, descriptions)
-- RED-GREEN methodology rules:
-  1. **RED**: Write test that fails if behavior is broken (not trivially passing)
-  2. **Verify RED**: Run test -- if passes, strengthen; if fails with expected error, good
-  3. **GREEN assessment**: If source satisfies, gap was missing test; if fails, record as bug discovery
-- Discovery board protocol for sharing test patterns and fixtures
-- Instruction to NOT fix source code -- failing tests are valuable bug documentation
+**Agent Instruction** (`buildTestGenInstruction`): Each agent receives source file path, test type, detected framework, existing patterns, gap references, and RED-GREEN methodology (RED: write failing test -> verify it fails -> GREEN: assess if source satisfies). Agents must NOT fix source code -- failing tests document bugs. Discovery board protocol included.
 
 ### Phase 3: Results Aggregation
 
 **Objective**: Run full suite, generate final results and human-readable report.
 
-1. Read final master `tasks.csv`
-2. Export as `results.csv`
+1. Export final `tasks.csv` as `results.csv`
 
-3. **Run full test suite** to verify no regressions:
-   ```bash
-   {test_run_command} 2>&1 | tail -50
-   ```
-   Categorize: new passing (gap filled), new failing (bug discovered), existing broken (regression).
+2. **Run full test suite**: Categorize results as new passing (gap filled), new failing (bug discovered), existing broken (regression).
 
-4. **Archive previous artifacts** before writing:
-   ```
-   IF file exists "{artifact_dir}/.tests/test-gen-report.json":
-     mkdir -p "{artifact_dir}/.history"
-     mv to "{artifact_dir}/.history/test-gen-report-{TIMESTAMP}.json"
-   ```
+3. **Archive previous artifacts**: Move existing `test-gen-report.json` to `.history/` with timestamp before overwriting.
 
-5. Build `test-gen-report.json`:
+4. Build `test-gen-report.json`:
 
 ```json
 {
@@ -324,49 +274,15 @@ Each agent receives:
 }
 ```
 
-6. Generate `context.md`:
-
-```markdown
-# Test Generation Report -- Phase {phase}
-
-## Summary
-- Framework: {framework}
-- Source files analyzed: {file_count}
-- Test type filter: {type_filter or "all"}
-
-## Classification
-| Category | Files |
-|----------|-------|
-| Unit | {N} |
-| Integration | {N} |
-| E2E | {N} |
-| Skipped | {N} |
-
-## Generation Results
-| # | Source File | Type | Tests | Status | Bugs |
-|---|-----------|------|-------|--------|------|
-| 1 | validate.ts | unit | 4 | passing | 0 |
-| 2 | ChatWindow.tsx | e2e | 3 | mixed | 1 |
-
-## Test Suite Verification
-- New tests passing: {N} (coverage gaps filled)
-- New tests failing: {N} (bugs discovered)
-- Existing tests broken: {N} (regressions)
-
-## Bugs Discovered
-{list of failing tests with descriptions -- NOT fixed, documented only}
-
-## Next Steps
-{suggested_next_command}
-```
+5. **Generate context.md**: Report with summary (framework, file count, type filter), classification table (unit/integration/e2e/skipped counts), generation results per file (source, type, tests, status, bugs), test suite verification (passing/failing/regression counts), discovered bugs, and next steps.
 
-7. Update `validation.json` gaps: change MISSING -> COVERED for gaps that now have tests.
+6. **Update validation.json**: Change MISSING -> COVERED for gaps that now have tests.
 
-8. Copy `test-gen-report.json` to phase `.tests/` directory.
+7. **Copy** `test-gen-report.json` to phase `.tests/` directory.
 
-9. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `path: "scratch/{YYYYMMDD}-testgen-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch.
+8. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `depends_on: exec_art.id`.
 
-10. Display summary.
+9. Display summary.
 
 **Next step routing**:
 
@@ -400,11 +316,7 @@ Each agent receives:
 
 #### Protocol
 
-1. **Read** `{session_folder}/discoveries.ndjson` before own test generation
-2. **Skip covered**: If discovery of same type + dedup key exists, skip
-3. **Write immediately**: Append findings as found
-4. **Append-only**: Never modify or delete
-5. **Deduplicate**: Check before writing
+Read `discoveries.ndjson` before test generation. Append-only: dedup by type+key before writing, never modify/delete.
 
 ```bash
 echo '{"ts":"<ISO>","worker":"{id}","type":"test_pattern","data":{"name":"api-endpoint-test","file":"src/api/__tests__/users.test.ts","framework":"vitest","description":"supertest + vitest pattern for REST endpoints"}}' >> {session_folder}/discoveries.ndjson

package/.codex/skills/spec-add/SKILL.md

@@ -50,9 +50,7 @@ Extract category (first token) and content (remainder) from arguments.
 
 ### Step 2: Validate Specs Directory
 
-```bash
-test -d .workflow/specs || exit 1  # E002: not initialized
-```
+Verify `.workflow/specs/` exists (E002).
 
 ### Step 3: Route to File
 
@@ -81,12 +79,7 @@ Append `<spec-entry>` closed-tag block to target file:
 
 ### Step 6: Confirm
 
-```
-Added [{category}] to {target_file}
-Keywords: {kw1}, {kw2}, {kw3}
-Verify: /spec-load --keyword {kw1}
-Remove: /spec-remove <entry-id>
-```
+Display: category, target file, extracted keywords, and commands for verify (`/spec-load`) and remove (`/spec-remove`).
 </execution>
 
 <error_codes>

package/.codex/skills/spec-load/SKILL.md

@@ -46,29 +46,19 @@ Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored i
 
 ### Step 1: Validate Specs Directory
 
-```bash
-test -d .workflow/specs || exit 1  # E001: not initialized
-```
+Verify `.workflow/specs/` exists (E001).
 
 ### Step 2: Parse Arguments
 
-Extract optional `--category` and `--keyword` flags from arguments.
+Extract optional `--category` and `--keyword` flags.
 
 ### Step 3: Load via CLI
 
-```bash
-maestro spec load [--category <cat>] [--keyword <word>]
-```
-
-If CLI unavailable, read files directly and apply keyword filter.
+Run `maestro spec load [--category <cat>] [--keyword <word>]`. If CLI unavailable, read files directly and apply keyword filter.
 
 ### Step 4: Display Results
 
-```
-=== SPECS: {category} {keyword ? "keyword=" + keyword : ""} ===
---- {filename} ({category}) ---
-{matched entry content (tags stripped)}
-```
+Show matched entries grouped by filename and category, with `<spec-entry>` tags stripped.
 </execution>
 
 <error_codes>

package/.codex/skills/spec-map/SKILL.md

@@ -98,52 +98,19 @@ id,title,description,focus_area,output_file,deps,context_from,wave,status,findin
 
 ### Session Initialization
 
-```javascript
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const focusArea = $ARGUMENTS.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '').trim() || 'full'
-const dateStr = new Date(Date.now() + 8*60*60*1000).toISOString().substring(0,10).replace(/-/g,'')
-const sessionId = `${dateStr}-map-${focusArea.substring(0,20)}`
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-
-Bash(`mkdir -p ${sessionFolder}`)
-Bash(`mkdir -p .workflow/codebase`)
-```
+Parse flags from `$ARGUMENTS` (`-y`, `-c N`, `--continue`). Extract focus area (default: "full"). Generate session ID: `{YYYYMMDD}-map-{focusArea}`. Create session folder at `.workflow/.csv-wave/{sessionId}/` and `.workflow/codebase/`.
 
 ### Phase 1: Generate tasks.csv
 
-Generate 4 mapper rows. If focus_area is specified, scope descriptions to that area.
+Generate 4 mapper rows. If focus area specified, scope descriptions to that area.
 
 ### Phase 2: Wave Execution
 
-Single wave — all 4 mappers run concurrently:
-
-```javascript
-spawn_agents_on_csv({
-  csv_path: `${sessionFolder}/wave-1.csv`,
-  id_column: "id",
-  instruction: buildMapperInstruction(sessionFolder, focusArea),
-  max_concurrency: 4,
-  max_runtime_seconds: 600,
-  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
-})
-```
+Single wave -- all 4 mappers via `spawn_agents_on_csv` (max_concurrency: 4, 600s timeout). Each agent returns: id, status (completed/failed), findings, error.
 
 ### Phase 3: Write Output Files
 
-1. Read each agent's findings from results
-2. Write to `.workflow/codebase/{output_file}`
-3. Generate context.md summary
-4. Display report
+Read each agent's findings, write to `.workflow/codebase/{output_file}`, generate `context.md` summary, display report.
 
 ### Shared Discovery Board Protocol
 

package/.codex/skills/spec-remove/SKILL.md

@@ -35,51 +35,19 @@ Extract entry ID from arguments.
 
 ### Step 2: Lookup Entry
 
-```bash
-maestro wiki get <entry-id> --json
-```
-
-- Validate entry exists (E003 if not found)
-- Validate entry is spec sub-node: `type` = "spec" and `parent` field set (E004 if not)
-- Extract: title, category, keywords, container path, body preview
+Run `maestro wiki get <entry-id> --json`. Validate: entry exists (E003), is spec sub-node with `type="spec"` and `parent` set (E004). Extract title, category, keywords, container path.
 
 ### Step 3: Confirm
 
 Display entry details. Ask user to confirm unless `-y` flag present.
 
-```
-== Spec Entry to Remove ==
-ID:        {entry-id}
-Title:     {title}
-Category:  {category}
-Keywords:  {keywords}
-Container: .workflow/specs/{filename}
-
-Remove this entry? [y/N]
-```
-
 ### Step 4: Remove
 
-```bash
-maestro wiki remove-entry <entry-id>
-```
-
-WikiIndexer auto-updates `.workflow/wiki-index.json`.
+Run `maestro wiki remove-entry <entry-id>`. WikiIndexer auto-updates `wiki-index.json`.
 
 ### Step 5: Verify & Report
 
-```bash
-maestro wiki get <entry-id>  # should return not-found
-```
-
-```
-== Entry Removed ==
-ID:        {entry-id}
-From:      .workflow/specs/{filename}
-
-To verify:  maestro wiki list --type spec --category {category}
-To re-add:  /spec-add {category} {content}
-```
+Confirm removal via `maestro wiki get <entry-id>` (should return not-found). Display removed ID, source file, and commands for verify/re-add.
 </execution>
 
 <error_codes>