maestro-flow 0.3.12 → 0.3.13

package/.claude/commands/manage-learn.md

@@ -49,7 +49,7 @@ Arguments: $ARGUMENTS
 
 **Storage:**
 - `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with `quality-retrospective` output)
-- `.workflow/learning/learning-index.json` — searchable index (mirrors `memory-index.json` schema)
+- `.workflow/learning/learning-index.json` — searchable index
 
 **Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 </context>
@@ -58,8 +58,8 @@ Arguments: $ARGUMENTS
 Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 
 1. **No agent or CLI calls** — this is a pure file operation: parse → infer → append → confirm. Category inference is keyword-based, not LLM-based.
-2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and resolve the matching directory slug. `--phase 0` forces no link.
-3. **Match memory-index pattern** — `learning-index.json` schema mirrors `memory-index.json` from `workflows/memory.md` (entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, phase, phase_slug, confidence, routed_to, routed_id).
+2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and derive phase context from artifact registry (`state.json.artifacts[]`). `--phase 0` forces no link.
+3. **Index schema** — `learning-index.json` entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, confidence, routed_to, routed_id.
 4. **Stable INS ids** — `INS-{8 lowercase hex}` from `hash(insight_text + category + phase)`. Deterministic: same content in same context always produces the same ID.
 5. **Append-only lessons.jsonl** — never rewrite existing rows; duplicate detection is the user's job at search time.
 6. **Bootstrap on demand** — create `.workflow/learning/`, `lessons.jsonl`, `learning-index.json` on first use; do not require them to exist upfront.
@@ -73,7 +73,7 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
 | E004 | error | Insight id not found in lessons.jsonl | show |
-| W001 | warning | Auto-phase detection found a current_phase but no matching directory; phase set to null | capture |
+| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
 | W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
 </error_codes>
 
@@ -81,7 +81,7 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 - [ ] Mode correctly routed (capture / list / search / show)
 - [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
 - [ ] Capture: `learning-index.json` updated with matching entry
-- [ ] Capture: phase auto-link resolves correctly when `state.json` has `current_phase`
+- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match

package/.claude/commands/manage-memory-capture.md

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Capture session working memory into `.workflow/memory/` for cross-session recovery. Compact mode only: full session compression for recovery. Maintains a `memory-index.json` for search and retrieval. Invoked when saving session state before context loss.
+Capture session working memory into `.workflow/memory/` for cross-session recovery. Compact mode only: full session compression for recovery. Entries are created via `maestro wiki create --type memory` and automatically indexed in `.workflow/wiki-index.json`. Invoked when saving session state before context loss.
 
 **Note:** Quick tips/notes have been moved to `manage-learn tip <text>`. Use that command for atomic knowledge capture.
 </purpose>
@@ -29,8 +29,8 @@ Arguments: $ARGUMENTS
 - No arguments — Defaults to compact mode
 
 **Storage:**
-- `.workflow/memory/` — Memory entries directory
-- `.workflow/memory/memory-index.json` — Searchable index of all entries
+- `.workflow/memory/` — Memory entries directory (via `maestro wiki create --type memory`)
+- `.workflow/wiki-index.json` — Unified wiki index (auto-updated on create)
 </context>
 
 <execution>
@@ -49,7 +49,7 @@ Follow '~/.maestro/workflows/memory.md' Part B (Memory Capture) completely.
 <success_criteria>
 - [ ] Compact mode executed
 - [ ] Entry markdown file written to `.workflow/memory/`
-- [ ] `memory-index.json` updated with new entry metadata
+- [ ] `wiki-index.json` auto-updated via wiki create
 - [ ] All session fields populated (objective, files, decisions, plan)
 - [ ] Execution plan preserved VERBATIM (not summarized)
 - [ ] All file paths are ABSOLUTE

package/.claude/commands/manage-memory.md

@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 
 | Store | Path | Format | Index |
 |-------|------|--------|-------|
-| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` (legacy only — new tips go to `manage-learn tip`) | `memory-index.json` |
+| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` (legacy only — new tips go to `manage-learn tip`) | `.workflow/wiki-index.json` (unified) |
 | `system` | `~/.claude/projects/{project}/memory/` | `MEMORY.md` + topic `.md` files | None (flat files) |
 
 **System memory path detection:**

package/.claude/commands/manage-wiki.md

@@ -0,0 +1,62 @@
+---
+name: manage-wiki
+description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
+
+Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
+| No args | Same as `health` |
+
+**Flags:**
+- `--type <type>` — Filter by wiki type: spec, memory, note, lesson, issue
+- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--json` — Output in JSON format
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | fatal | No wiki entries found — create content first | load |
+| E003 | error | Invalid subcommand | parse_input |
+| W001 | warning | Health score below 50 — graph needs attention | health |
+| W002 | warning | Orphan cleanup had partial failures | cleanup |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] Next-step suggestions provided
+</success_criteria>

package/.claude/commands/quality-business-test.md

@@ -60,7 +60,7 @@ Context files:
 - `.workflow/.spec/SPEC-xxx/requirements/NFR-*.md` -- Non-functional requirements
 - `.workflow/.spec/SPEC-xxx/architecture/_index.md` -- API endpoints, data model, state machines
 - `.workflow/.spec/SPEC-xxx/epics/EPIC-*.md` -- User stories for E2E scenarios
-- Phase artifacts (resolve via `state.json.artifacts[]` → `.workflow/scratch/` paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+- Phase artifacts (resolve via `state.json.artifacts[]` → `.workflow/scratch/` paths):
   - plan.json -- Task overview (degraded mode)
   - verification.json -- Cross-reference for must_haves
   - .tests/business/ -- Previous business test artifacts
@@ -81,7 +81,7 @@ Follow '~/.maestro/workflows/business-test.md' completely.
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json or .workflow/phases/ |
+| E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json |
 | E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-spec-generate or maestro-plan first |
 | E004 | error | L1 critical failures block L2/L3 progression | Fix blockers first via quality-debug |
 | W001 | warning | Degraded mode (no spec package, using success_criteria) | Consider running maestro-spec-generate for full coverage |

package/.claude/commands/quality-debug.md

@@ -39,23 +39,69 @@ User's issue: $ARGUMENTS
 - `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
 - `--parallel` -- Spawn parallel debug agents (one per gap cluster)
 
-**State files:**
-- Phase UAT/debug artifacts (resolve via `state.json.artifacts[]` → scratch paths; fallback to `.workflow/phases/{NN}-{slug}/`):
-  - uat.md -- UAT gaps (if --from-uat)
-  - .debug/ -- Phase-scoped debug sessions
-- `.workflow/scratch/debug-*/` -- Standalone debug sessions
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/ (source of code changes)
+- **review** → review.json (findings guide hypothesis formation)
+- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
+- **test** → uat.md (--from-uat gap source), .tests/
+
+Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
+
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/debug.md' completely.
 
+**Output writes to DEBUG_DIR** (`scratch/{YYYYMMDD}-debug-P{N}-{slug}/`):
+- understanding.md, evidence.ndjson, diagnosis-summary.json
+
+**Register artifact on completion (phase-scoped only):**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "debug"),  // DBG-001
+  type: "debug",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",  // or {YYYYMMDD}-debug-{slug} for standalone
+  status: all_diagnosed ? "completed" : "failed",
+  depends_on: triggering_review_id || exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+### Post-debug Knowledge Inquiry
+
+After root cause is confirmed, evaluate inquiry triggers:
+
+1. **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
+   → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
+
+2. **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
+   → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
+
+3. **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
+   → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+
 **Next-step routing on completion:**
 - Root cause found, fix needed → `/maestro-plan {phase} --gaps`
 - Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
 - Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
 - Standalone fix already applied → `/maestro-verify {phase}`
-
-Note: Debug output (.debug/) is auto-loaded by maestro-plan --gaps.
 </execution>
 
 <error_codes>

package/.claude/commands/quality-retrospective.md

@@ -43,17 +43,17 @@ Arguments: $ARGUMENTS
 - `--auto-yes` — accept all routing recommendations without prompting
 
 **Storage written:**
-- Retrospective output (resolve via `state.json.artifacts[]` → `.workflow/scratch/` path; fallback to `.workflow/phases/{NN}-{slug}/`):
+- Retrospective output (resolve via `state.json.artifacts[]` → `.workflow/scratch/` path):
   - retrospective.md — human-readable record
   - retrospective.json — structured record
-- `.workflow/specs/SPEC-retro-*.md` — spec stubs (one per spec-routed insight)
+- `.workflow/specs/{category-file}.md` — `<spec-entry>` entries appended to matching category files (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` — appended issue rows (`source: "retrospective"`)
 - `.workflow/learning/lessons.jsonl` — tips routed via `manage-learn tip` (formerly manage-memory-capture)
 - `.workflow/learning/lessons.jsonl` — append-only insight log
 - `.workflow/learning/learning-index.json` — searchable index
 
 **Storage read (never modified):**
-- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths):
   - index.json, plan.json, verification.json, review.json, uat.md
   - .task/TASK-*.json, .summaries/TASK-*-summary.md
 - `.workflow/issues/issues.jsonl`, `.workflow/issues/issue-history.jsonl`
@@ -69,7 +69,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 4. **Reuse `manage-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-learn", args: "tip ..." })`.
 5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
 6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
-7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{phase_dir}/.history/` with a timestamp suffix first.
+7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{artifact_dir}/.history/` with a timestamp suffix first.
 </execution>
 
 <error_codes>
@@ -94,7 +94,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
 - [ ] Each insight has a stable `INS-{8hex}` id
 - [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
-- [ ] Spec stubs (if any) written to `.workflow/specs/SPEC-retro-*.md` with proper frontmatter
+- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
 - [ ] `lessons.jsonl` appended with one row per insight regardless of routing target

package/.claude/commands/quality-review.md

@@ -53,17 +53,49 @@ Phase: $ARGUMENTS (required — phase number or slug)
 - `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
 - `--skip-specs` — Skip loading project specs as review context
 
-Context files resolved via `state.json.artifacts[]` → scratch path (fallback: `.workflow/phases/{NN}-{slug}/`):
-- index.json (phase metadata, execution results)
-- plan.json (task overview)
-- .task/TASK-{NNN}.json (task definitions with file lists)
-- .summaries/TASK-{NNN}-summary.md (execution results)
-- verification.json (if exists — incorporate verification gaps as review context)
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/, verification.json, plan.json (source of files to review)
+- **review** → review.json (prior verdict, findings — for delta comparison)
+- **debug** → understanding.md, evidence.ndjson (confirmed root causes)
+- **test** → uat.md, .tests/ (user-observable gaps)
+
+Extract conclusions from related artifacts that may affect this review. Pass as prior quality context to reviewer agents — avoid redundant work, focus on gaps and regressions.
+
+**Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/review.md' completely.
 
+**Output writes to REVIEW_DIR** (not EXEC_DIR):
+- `REVIEW_DIR/review.json` — findings, severity distribution, verdict
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // REV-001
+  type: "review",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-review-P{N}-{slug}",    // relative to .workflow/
+  status: "completed",
+  depends_on: exec_art.id,                 // or prior debug/review if re-review
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
 **Report format on completion:**
 
 ```
@@ -87,7 +119,7 @@ Verdict: {PASS | WARN | BLOCK}
 Issues Created: {issue_count}
 
 Files:
-  {phase_dir}/review.json
+  {REVIEW_DIR}/review.json
 
 Next steps:
   {verdict_based_routing}

package/.claude/commands/quality-sync.md

@@ -47,5 +47,5 @@ Follow '~/.maestro/workflows/sync.md' completely.
 - [ ] Codebase docs refreshed for all affected components
 - [ ] doc-index.json reflects current file state
 - [ ] Changes tracked and logged
-- [ ] project-tech.json refreshed if dependency manifests changed
+- [ ] project.md Tech Stack section refreshed if dependency manifests changed
 </success_criteria>

package/.claude/commands/quality-test-gen.md

@@ -36,7 +36,7 @@ Phase: $ARGUMENTS (required -- phase number)
 - `--layer <unit|e2e|all>` -- Generate only specific test layer (default: all)
 
 Context files:
-- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths):
   - verification.json -- Nyquist gaps (MISSING/PARTIAL)
   - validation.json -- requirement-to-test mapping
   - .tests/coverage-report.json -- UAT coverage gaps

package/.claude/commands/quality-test.md

@@ -36,23 +36,56 @@ Phase or task: $ARGUMENTS (optional)
 - `--smoke` -- Run cold-start smoke tests before UAT (basic sanity: app starts, routes respond, no crash)
 - `--auto-fix` -- After diagnosis, auto-trigger gap-fix loop instead of asking user
 
-Context files resolved from target directory:
-- verification.json (must_haves, gaps from maestro-verify)
-- validation.json (coverage, requirement mapping)
-- review.json (findings from quality-review, if exists)
-- index.json (success_criteria, execution results)
-- plan.json (task overview)
-- .summaries/TASK-*.md (execution summaries)
-- uat.md (existing session, if resuming)
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/, verification.json, plan.json (test target source)
+- **verify** → verification.json (must_haves, gaps)
+- **review** → review.json (findings become additional test scenarios)
+- **debug** → understanding.md (confirmed root causes become regression tests)
+- **test** → uat.md (existing session, resumable)
+
+Extract conclusions from related artifacts that may affect this test session — review findings generate additional scenarios, debug root causes generate regression tests.
+
+**Output**: `TEST_DIR = .workflow/scratch/{YYYYMMDD}-test-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/test.md' completely.
 
-**Review findings integration (when review.json exists):**
-- Extract critical/high findings from review.json.findings_by_dimension as additional test scenarios
-- These review-derived scenarios are prioritized and marked `source: "review_finding"`
-- When review.json verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop without user confirmation (Step 12 auto-fix condition)
+**Output writes to TEST_DIR** (`scratch/{YYYYMMDD}-test-P{N}-{slug}/`):
+- uat.md, test-plan.json, .tests/test-results.json, .tests/coverage-report.json
+
+**Review findings integration** (from related review artifacts):
+- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
+- When review verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop
+
+**Debug root cause integration** (from related debug artifacts):
+- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "test"),  // TST-001
+  type: "test",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-test-P{N}-{slug}",
+  status: issues == 0 ? "completed" : "failed",
+  depends_on: exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
 
 **Next-step routing on completion:**
 - All tests pass → `/maestro-phase-transition {phase}`

package/.claude/commands/spec-remove.md

@@ -0,0 +1,51 @@
+---
+name: spec-remove
+description: Remove a spec entry from a specs file by entry ID
+argument-hint: "<entry-id>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
+
+**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-remove.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
+| E003 | fatal | Entry ID not found in wiki index | lookup |
+| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, is sub-node)
+- [ ] User confirmed removal (unless -y flag)
+- [ ] Entry removed from container file via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] Confirmation displayed with removed entry details
+</success_criteria>

package/.claude/commands/spec-setup.md

@@ -12,7 +12,7 @@ allowed-tools:
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
 Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
-All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
+All output lands in `.workflow/specs/`.
 </purpose>
 
 <required_reading>
@@ -20,7 +20,6 @@ All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
 </required_reading>
 
 <deferred_reading>
-- [project-tech.json](~/.maestro/templates/project-tech.json) — read when generating project-tech configuration
 </deferred_reading>
 
 <context>
@@ -47,7 +46,6 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] `.workflow/specs/` directory created
 - [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
 - [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
-- [ ] `project-tech.json` written with detected tech stack
 - [ ] Report displayed with summary and next steps
 </success_criteria>
 </output>

package/.claude/commands/wiki-connect.md

@@ -11,6 +11,10 @@ allowed-tools:
   - Agent
   - AskUserQuestion
 ---
+<required_reading>
+@~/.maestro/workflows/wiki-connect.md
+</required_reading>
+
 <purpose>
 Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
 
@@ -21,7 +25,7 @@ Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, he
 Arguments: $ARGUMENTS
 
 **Flags:**
-- `--scope <type>` — Limit analysis to a wiki type (spec, phase, memory, note, lesson, issue). Default: all types.
+- `--scope <type>` — Limit analysis to a wiki type (spec, memory, note, lesson, issue). Default: all types.
 - `--min-similarity N` — Minimum similarity score threshold 0.0-1.0 (default: 0.3)
 - `--fix` — Auto-apply the top suggestions by updating wiki entries with new `related` links
 - `--max N` — Maximum number of suggestions to generate (default: 20)
@@ -66,13 +70,13 @@ For each entry, compute potential connections:
 For each orphan entry, search for related entries using:
 - `maestro wiki search "<orphan title>"` — BM25 match by title
 - Tag overlap: entries sharing 2+ tags with the orphan
-- Same phase: entries with matching `phaseRef`
+- Same category: entries with matching `category`
 
 **2b. Missing Bidirectional Links:**
 For entries that have forward links but no corresponding backlink (A links to B, but B doesn't link to A), suggest adding the reverse link.
 
 **2c. Transitive Closure:**
-If A → B and B → C, but A has no link to C, and A and C share tags or are in the same phase, suggest A → C.
+If A → B and B → C, but A has no link to C, and A and C share tags or category, suggest A → C.
 
 **2d. Type Bridge:**
 Entries of different types that reference the same concept (e.g., a `spec-auth` and a `lesson-auth-gotcha`) but aren't linked.
@@ -83,13 +87,13 @@ For each candidate connection (source → target), compute similarity:
 ```
 score = 0.4 × tag_overlap_ratio
       + 0.3 × title_bm25_similarity
-      + 0.2 × same_phase_bonus
+      + 0.2 × same_category_bonus
       + 0.1 × type_bridge_bonus
 ```
 
 - `tag_overlap_ratio`: shared_tags / max(source_tags, target_tags)
 - `title_bm25_similarity`: normalized BM25 score from wiki search
-- `same_phase_bonus`: 1.0 if same phaseRef, else 0.0
+- `same_category_bonus`: 1.0 if same category, else 0.0
 - `type_bridge_bonus`: 1.0 if different types, else 0.0
 
 Filter by `--min-similarity`, rank descending, limit to `--max`.

package/.claude/commands/wiki-digest.md

@@ -17,6 +17,10 @@ Knowledge synthesis command that generates actionable digests from the wiki know
 Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
 </purpose>
 
+<required_reading>
+@~/.maestro/workflows/wiki-digest.md
+</required_reading>
+
 <deferred_reading>
 - @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
 </deferred_reading>
@@ -27,7 +31,7 @@ Arguments: $ARGUMENTS
 **Scope resolution (auto-detected):**
 - `<topic>` — Search wiki for entries matching the topic via `maestro wiki search`
 - `--recent N` — Entries updated in the last N days
-- `--type <type>` — Filter by wiki type (spec, phase, memory, note, lesson, issue)
+- `--type <type>` — Filter by wiki type (spec, memory, note, lesson, issue)
 - No arguments — digest of the entire wiki
 
 **Flags:**
@@ -101,7 +105,6 @@ Build a matrix showing knowledge density by type × theme:
 ```
               Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
 spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
-phase         ████░      ███░░      ░░░░░      █████      ██░░░
 memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
 lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
 issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
@@ -166,7 +169,7 @@ For each knowledge gap identified in Stage 5:
 1. Write digest file
 2. Append meta-insights to `lessons.jsonl`:
    - `source: "wiki-digest"`, `category: "technique"`
-   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Phase 2 has no decision entries"
+   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Security category has no decision entries"
 3. Update `learning-index.json`
 4. Display summary with key findings
 

package/.codex/skills/maestro/SKILL.md

@@ -63,7 +63,7 @@ After a barrier skill completes **in its spawned sub-agent**, coordinator reads
 | Skill | Artifacts to Read | Context Updates |
 |-------|------------------|-----------------|
 | `maestro-analyze` | `.workflow/.csv-wave/*/context.md`, `state.json` | `gaps`, `phase`, `analysis_dir` |
-| `maestro-plan` | `{phase_dir}/plan.json`, `{phase_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
+| `maestro-plan` | `{artifact_dir}/plan.json`, `{artifact_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
 | `maestro-brainstorm` | `.workflow/.csv-wave/*/.brainstorming/` | `brainstorm_dir`, `features` |
 | `maestro-spec-generate` | `.workflow/.csv-wave/*/specs/` | `spec_session_id` |
 | `maestro-execute` | `.workflow/.csv-wave/*/results.csv` | `exec_status`, `completed_tasks`, `failed_tasks` |
@@ -111,7 +111,7 @@ function analyzeBarrierArtifacts(step, result, ctx) {
 **`--continue`**: Glob `.workflow/.maestro-coordinate/MCC-*/state.json` sorted desc; load most recent; resume from first pending wave.
 
 **Fresh mode**:
-1. Read `.workflow/state.json` for project context (`current_phase`, `workflow_name`)
+1. Read `.workflow/state.json` for project context (derive current phase from artifact registry, `workflow_name`)
 2. If `--chain` given, use directly
 3. Otherwise classify intent via keyword heuristics (see chain_map)
 4. No match + not AUTO_YES → one clarifying question via `AskUserQuestion`

package/.codex/skills/maestro-analyze/SKILL.md

@@ -61,7 +61,7 @@ Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topol
 $maestro-analyze "3"
 $maestro-analyze -y "microservices vs monolith"
 $maestro-analyze -c 6 "3 -q"
-$maestro-analyze --continue "analyze-microservices-20260318"
+$maestro-analyze --continue "20260318-analyze-microservices"
 ```
 
 **Flags**:
@@ -132,7 +132,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/analyze-{slug}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -219,9 +219,9 @@ if (GAPS_MODE) {
 }
 
 const dateStr = getUtc8ISOString().substring(0, 10)
-const sessionId = `analyze-${slug}-${dateStr}`
+const sessionId = `${dateStr}-analyze-${slug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-const scratchDir = `.workflow/scratch/analyze-${slug}-${dateStr}`
+const scratchDir = `.workflow/scratch/${dateStr}-analyze-${slug}`
 
 Bash(`mkdir -p ${sessionFolder}`)
 Bash(`mkdir -p ${scratchDir}`)