maestro-flow 0.3.9 → 0.3.11

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

@@ -1,131 +1,131 @@
----
-name: manage-harvest
-description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
-argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
-
-Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
-
-**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, manage-issue-plan).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/harvest.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
-- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected):**
-- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
-- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
-- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
-
-**Flags:**
-- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
-- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
-- `--recent N` — Only artifacts updated within last N days (default: 30)
-- `--dry-run` — Preview extraction and routing without writing
-- `-y` / `--yes` — Skip confirmation prompts
-- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
-
-**Source registry (scan paths):**
-| Source Type | Scan Path | Key Files |
-|-------------|-----------|-----------|
-| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
-| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
-| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
-| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
-| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
-| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
-| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
-
-**Storage written:**
-- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
-- `.workflow/harvest/harvest-report-{date}.md` — per-run report
-- Wiki entries via `maestro wiki create`
-- Spec entries via `Skill({ skill: "spec-add" })`
-- Issue entries appended to `.workflow/issues/issues.jsonl`
-
-**Storage read (never modified):**
-- All artifact source files (read-only until routing stage)
-- `.workflow/harvest/harvest-log.jsonl` (dedup check)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
-
-1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
-2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
-4. **Reuse existing routing infrastructure**:
-   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
-   - Spec: `Skill({ skill: "spec-add", args: "<type> <content>" })`
-   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
-5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
-6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
-7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
-
-**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
-
-**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
-
-**Next-step routing on completion:**
-- Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `/wiki-connect --fix`
-- Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --category general`
-- Full retrospective → `/quality-retrospective`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
-| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
-| E003 | error | Invalid `--source` type | Display valid source types from registry |
-| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
-| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
-| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
-| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
-| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
-| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
-| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly resolved (scan / session / path)
-- [ ] Source artifacts discovered and listed with metadata
-- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
-- [ ] All files in selected artifacts loaded and parsed
-- [ ] Knowledge fragments extracted with category, confidence, tags
-- [ ] Fragments filtered by `--min-confidence`
-- [ ] Routing classification applied (auto or forced by `--to`)
-- [ ] Dedup check passed against harvest-log.jsonl and existing stores
-- [ ] If `--dry-run`: preview displayed, no files written
-- [ ] If not dry-run: all routed items written to target stores
-- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
-- [ ] Spec entries added via `spec-add` mechanism
-- [ ] Issue entries appended to `issues.jsonl` with canonical schema
-- [ ] `harvest-log.jsonl` updated with provenance for each routed item
-- [ ] `harvest-report-{date}.md` written with full summary
-- [ ] No source artifacts modified
-- [ ] Summary displayed with counts and next-step routing
-</success_criteria>
+---
+name: manage-harvest
+description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
+
+Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
+
+**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected):**
+- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
+- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
+- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
+
+**Flags:**
+- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
+- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
+- `--recent N` — Only artifacts updated within last N days (default: 30)
+- `--dry-run` — Preview extraction and routing without writing
+- `-y` / `--yes` — Skip confirmation prompts
+- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
+
+**Source registry (scan paths):**
+| Source Type | Scan Path | Key Files |
+|-------------|-----------|-----------|
+| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
+| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
+| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
+| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
+| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
+| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
+| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
+| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
+
+**Storage written:**
+- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
+- `.workflow/harvest/harvest-report-{date}.md` — per-run report
+- Wiki entries via `maestro wiki create`
+- Spec entries via `Skill({ skill: "spec-add" })`
+- Issue entries appended to `.workflow/issues/issues.jsonl`
+
+**Storage read (never modified):**
+- All artifact source files (read-only until routing stage)
+- `.workflow/harvest/harvest-log.jsonl` (dedup check)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
+
+1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
+2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
+3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
+4. **Reuse existing routing infrastructure**:
+   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+   - Spec: `Skill({ skill: "spec-add", args: "<category> <content>" })`
+   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
+5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
+6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
+7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
+
+**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
+
+**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
+
+**Next-step routing on completion:**
+- Review wiki entries → `maestro wiki list --type note`
+- Connect wiki graph → `/wiki-connect --fix`
+- Triage issues → `/manage-issue list --source harvest`
+- View specs → `/spec-load --category learning`
+- Full retrospective → `/quality-retrospective`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
+| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
+| E003 | error | Invalid `--source` type | Display valid source types from registry |
+| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
+| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
+| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
+| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
+| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
+| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / session / path)
+- [ ] Source artifacts discovered and listed with metadata
+- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
+- [ ] All files in selected artifacts loaded and parsed
+- [ ] Knowledge fragments extracted with category, confidence, tags
+- [ ] Fragments filtered by `--min-confidence`
+- [ ] Routing classification applied (auto or forced by `--to`)
+- [ ] Dedup check passed against harvest-log.jsonl and existing stores
+- [ ] If `--dry-run`: preview displayed, no files written
+- [ ] If not dry-run: all routed items written to target stores
+- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
+- [ ] Spec entries added via `spec-add` mechanism
+- [ ] Issue entries appended to `issues.jsonl` with canonical schema
+- [ ] `harvest-log.jsonl` updated with provenance for each routed item
+- [ ] `harvest-report-{date}.md` written with full summary
+- [ ] No source artifacts modified
+- [ ] Summary displayed with counts and next-step routing
+</success_criteria>

package/.claude/commands/manage-issue-discover.md

@@ -20,7 +20,7 @@ Automated issue discovery via multi-perspective codebase analysis (8 perspective
 
 For CRUD operations (create, list, update, close, link), use `/manage-issue`.
 
-After discovery, use `/manage-issue-analyze <ISS-ID>` to perform root cause analysis on individual findings.
+After discovery, use `/maestro-analyze --gaps <ISS-ID>` to perform root cause analysis on individual findings.
 </purpose>
 
 <required_reading>
@@ -73,5 +73,5 @@ Follow '~/.maestro/workflows/issue-discover.md' completely.
 - [ ] Findings deduplicated before issue creation
 - [ ] Issues appended to issues.jsonl with correct schema
 - [ ] Discovery session fully traceable via session directory
-- [ ] Next step routing: `/manage-issue-analyze <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
+- [ ] Next step routing: `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
 </success_criteria>

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

@@ -16,7 +16,7 @@ Issue lifecycle management for the project issue tracker. Supports create, list,
 
 For automated issue discovery, use `/manage-issue-discover`.
 
-**Closed-loop workflow**: After creating an issue, use `/manage-issue-analyze` for root cause analysis, `/manage-issue-plan` for solution planning, and `/manage-issue-execute` for execution.
+**Closed-loop workflow**: After creating an issue, use `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, `/maestro-plan --gaps` for solution planning, and `/maestro-execute` for execution.
 </purpose>
 
 <required_reading>
@@ -48,8 +48,8 @@ Parse subcommand from first token of $ARGUMENTS.
 Follow '~/.maestro/workflows/issue.md' completely.
 
 **Next-step routing on completion:**
-- create → `/manage-issue-analyze <ISS-ID>` or `/manage-issue-plan <ISS-ID>`
-- list → `/manage-issue-analyze <ISS-ID>` for any open issue
+- create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+- list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
 - close → `/manage-status`
 </execution>
 
@@ -67,7 +67,7 @@ Follow '~/.maestro/workflows/issue.md' completely.
 - [ ] Output displayed in appropriate format (table for list, detail for status)
 - [ ] Cross-references maintained (link creates bidirectional references)
 - [ ] Next step routing by subcommand:
-  - create → `/manage-issue-analyze <ISS-ID>` or `/manage-issue-plan <ISS-ID>`
-  - list → `/manage-issue-analyze <ISS-ID>` for any open issue
+  - create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+  - list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
   - close → `/manage-status`
 </success_criteria>

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

@@ -1,56 +1,67 @@
----
-name: spec-add
-description: Add a spec entry (bug, pattern, decision, or rule) to the appropriate specs file
-argument-hint: "<type> <content>"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Add a knowledge entry to the project specs system, routing it to the correct file by category.
-Each entry is timestamped and appended to learnings.md, then the relevant spec file is updated if the entry warrants a convention or rule change.
-Supports four categories: bug fixes, patterns, architectural decisions, and quality rules.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-add.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `<type> <content>` where type is one of: bug, pattern, decision, rule, debug, test, review, validation
-
-**Type-to-file mapping:**
-| Type | Primary file | Secondary update |
-|------|-------------|-----------------|
-| `bug` | `learnings.md` | -- |
-| `pattern` | `learnings.md` | `coding-conventions.md` |
-| `decision` | `learnings.md` | `architecture-constraints.md` |
-| `rule` | `learnings.md` | `quality-rules.md` |
-| `debug` | `learnings.md` | `debug-notes.md` |
-| `test` | `learnings.md` | `test-conventions.md` |
-| `review` | `learnings.md` | `review-standards.md` |
-| `validation` | `learnings.md` | `validation-rules.md` |
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-add.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | Category and content are both required -- usage: `<type> <content>` | parse_input |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: bug, pattern, decision, rule, debug, test, review, validation | parse_input |
-</error_codes>
-
-<success_criteria>
-- [ ] Category parsed and validated as bug/pattern/decision/rule
-- [ ] Entry appended to `.workflow/specs/learnings.md` with timestamp
-- [ ] Relevant spec file updated (if type is pattern/decision/rule)
-- [ ] Confirmation report displayed
-- [ ] Next step: `/spec-load --category {type}` to verify, or continue current task
-</success_criteria>
+---
+name: spec-add
+description: Add a spec entry to the appropriate specs file by category
+argument-hint: "<category> <content>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Add a knowledge entry to the project specs system using `<spec-entry>` closed-tag format.
+Each category maps 1:1 to a single target file — no dual-write.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<category> <content>`
+
+**Category-to-file mapping (1:1, same as spec-load):**
+| Category | Target file |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+
+**Entry format (closed-tag):**
+```markdown
+<spec-entry category="{category}" keywords="{auto-extracted}" date="{YYYY-MM-DD}">
+
+### {title}
+
+{content}
+
+</spec-entry>
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-add.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Category and content are both required -- usage: `<category> <content>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate_entry |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Category parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 relevant terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format
+- [ ] Entry appended to target file
+- [ ] Confirmation report displayed
+- [ ] Next step: `/spec-load --keyword {keyword}` to verify
+</success_criteria>
+</output>

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

@@ -1,64 +1,66 @@
----
-name: spec-load
-description: Load relevant specs and lessons for current context (used by agents before execution)
-argument-hint: "[--category <type>] [--with-lessons] [keyword]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Load and display relevant spec files for the current working context, optionally filtered by category.
-Designed for agents to call before execution to internalize project conventions, constraints, and learnings.
-Returns matched sections with file references ranked by relevance.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-load.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional `--category <type>` flag and/or keyword to filter specs
-
-**Category filter** (matches frontmatter `category` field):
-| Category | Files loaded |
-|----------|-------------|
-| `general` | `learnings.md` |
-| `exploration` | _(reserved)_ |
-| `planning` | `architecture-constraints.md` |
-| `execution` | `coding-conventions.md`, `quality-rules.md` |
-| `debug` | `debug-notes.md` |
-| `test` | `test-conventions.md` |
-| `review` | `review-standards.md` |
-| `validation` | `validation-rules.md` |
-| `all` (default) | All spec files |
-
-**Keyword:** If provided, search within loaded files for matching sections.
-If no arguments, loads all specs for the active phase/task context.
-
-**Flags:**
-- `--with-lessons` — Also search `.workflow/learning/lessons.jsonl` for entries with `category: "gotcha"`, `"antipattern"`, or `"pattern"` relevant to the keyword or current context. Appends matched lessons after spec output. This bridges the gap between specs (prescriptive rules) and lessons (discovered knowledge).
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-load.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | detect_context |
-| W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
-</error_codes>
-
-<success_criteria>
-- [ ] Category filter parsed correctly (or defaults to all)
-- [ ] Spec files resolved and read
-- [ ] Keyword filtering applied if provided
-- [ ] If `--with-lessons`: lessons.jsonl searched for gotcha/antipattern/pattern entries matching context
-- [ ] If `--with-lessons`: matched lessons displayed after specs (max 10, newest first)
-- [ ] Results displayed with file:line references
-- [ ] Relevant specs loaded into agent context
-- [ ] Next step: proceed with current task using loaded specs as context
-</success_criteria>
+---
+name: spec-load
+description: Load relevant specs and lessons for current context (used by agents before execution)
+argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Load and display relevant spec files for the current working context.
+Supports filtering by category (file-level) and keyword (entry-level via `<spec-entry>` tags).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-load.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags and keyword
+
+**Category-to-file mapping (1:1, same as spec-add):**
+| Category | File loaded |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+| `all` (default) | All spec files |
+
+**Flags:**
+- `--category <type>` — Filter by file category (loads one file)
+- `--keyword <word>` — Filter entries by keyword attribute in `<spec-entry>` tags. Searches across all files (or within category if combined)
+- `--with-lessons` — Also search `.workflow/learning/lessons.jsonl`
+
+**Examples:**
+```
+/spec-load --keyword auth
+/spec-load --category coding --keyword naming
+/spec-load --category arch
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-load.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | detect_context |
+| W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
+</error_codes>
+
+<success_criteria>
+- [ ] Category and/or keyword parsed from arguments
+- [ ] Spec files loaded per category mapping
+- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords attribute)
+- [ ] Legacy entries filtered by text grep fallback
+- [ ] Results displayed with file:category references
+</success_criteria>
+</output>

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

@@ -11,7 +11,7 @@ allowed-tools:
 ---
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Produces four spec files plus a tech profile JSON that downstream agents and commands consume for consistent coding.
+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`.
 </purpose>
 
@@ -45,13 +45,9 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 
 <success_criteria>
 - [ ] `.workflow/specs/` directory created
-- [ ] `coding-conventions.md` written with detected patterns
-- [ ] `architecture-constraints.md` written with structural rules
-- [ ] `quality-rules.md` written with auto-detected and manual sections
-- [ ] `learnings.md` initialized with format instructions
+- [ ] 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:
-  - Build codebase docs → `/manage-codebase-rebuild`
-  - Load specs for task → `/spec-load`
-  - Add new knowledge → `/spec-add <type> <content>`
+- [ ] Report displayed with summary and next steps
 </success_criteria>
+</output>