maestro-flow 0.5.3 → 0.5.31

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

@@ -7,71 +7,71 @@ allowed-tools:
   - run_command
   - view_file
 ---
-<purpose>
-Load relevant specs filtered by scope, category (file-level) and/or keyword (entry-level).
-Category-based loading: loads the category's primary doc in full + matching entries from other files.
-By default, loads from both global (~/.maestro/specs/) and project (.workflow/specs/) layers.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-load.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags and keyword
-
-**Flags:**
-- `--scope <scope>` — Load scope (default: global + project merged):
-  - `project`: project baseline only (.workflow/specs/)
-  - `global`: global + project merged (~/.maestro/specs/ + .workflow/specs/)
-  - `team`: project + team shared (.workflow/collab/specs/)
-  - `personal`: project + team + personal (requires uid)
-- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, learning, ui.
-- `--keyword <word>` — Filter by keyword within entries
-
-**File → Primary Category mapping:**
-| File | Category |
-|------|----------|
-| coding-conventions.md | coding |
-| architecture-constraints.md | arch |
-| test-conventions.md | test |
-| review-standards.md | review |
-| debug-notes.md | debug |
-| ui-conventions.md | ui |
-| quality-rules.md | review |
-| learnings.md | learning |
-
-**Examples:**
-```
-/spec-load --category coding            # coding全文 + 跨文件coding条目 (global + project)
-/spec-load --scope global --category arch  # 明确包含全局 arch 规范
-/spec-load --category review            # review-standards + quality-rules + 跨文件review条目
-/spec-load --category coding --keyword auth
-/spec-load --keyword auth
-```
-
-**Ref entries:**
-When loading entries with `ref` attribute, only the summary is shown with a load command:
-  → Detail: maestro wiki load <knowhow-id>
-Use the load command to read the full referenced document.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-load.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | warning | `.workflow/specs/` not initialized -- run `/spec-setup` first (global specs still available) | 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>
+<purpose>
+Load relevant specs filtered by scope, category (file-level) and/or keyword (entry-level).
+Category-based loading: loads the category's primary doc in full + matching entries from other files.
+By default, loads from both global (~/.maestro/specs/) and project (.workflow/specs/) layers.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-load.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags and keyword
+
+**Flags:**
+- `--scope <scope>` — Load scope (default: global + project merged):
+  - `project`: project baseline only (.workflow/specs/)
+  - `global`: global + project merged (~/.maestro/specs/ + .workflow/specs/)
+  - `team`: project + team shared (.workflow/collab/specs/)
+  - `personal`: project + team + personal (requires uid)
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, learning, ui.
+- `--keyword <word>` — Filter by keyword within entries
+
+**File → Primary Category mapping:**
+| File | Category |
+|------|----------|
+| coding-conventions.md | coding |
+| architecture-constraints.md | arch |
+| test-conventions.md | test |
+| review-standards.md | review |
+| debug-notes.md | debug |
+| ui-conventions.md | ui |
+| quality-rules.md | review |
+| learnings.md | learning |
+
+**Examples:**
+```
+/spec-load --category coding            # coding全文 + 跨文件coding条目 (global + project)
+/spec-load --scope global --category arch  # 明确包含全局 arch 规范
+/spec-load --category review            # review-standards + quality-rules + 跨文件review条目
+/spec-load --category coding --keyword auth
+/spec-load --keyword auth
+```
+
+**Ref entries:**
+When loading entries with `ref` attribute, only the summary is shown with a load command:
+  → Detail: maestro wiki load <knowhow-id>
+Use the load command to read the full referenced document.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-load.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | warning | `.workflow/specs/` not initialized -- run `/spec-setup` first (global specs still available) | 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/.agy/skills/spec-remove/SKILL.md

@@ -10,45 +10,45 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<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.
-
-**Flags:**
-- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
-</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
-- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
-- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
-</success_criteria>
+<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.
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
+</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
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
+</success_criteria>

package/.agy/skills/spec-setup/SKILL.md

@@ -8,44 +8,41 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Core files (coding, arch, learnings) are always created. Optional spec files (quality, test, ui) are created only when relevant signals are detected.
-Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro search`.
-Spec output lands in `.workflow/specs/`; recipe output lands in `.workflow/knowhow/`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-setup.md
-</required_reading>
-
-<context>
-$ARGUMENTS (no arguments expected)
-
-**Preconditions:**
-- `.workflow/` directory must exist (created by `/maestro-init`)  # (see code: E001)
-- Project must contain source files to scan  # (see code: E002)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-setup.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
-| E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
-| W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
-| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
-| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
-</error_codes>
-
-<success_criteria>
-- [ ] `.workflow/specs/` directory created
-- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
-- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
-- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
-- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
-</success_criteria>
-</output>
+<purpose>
+Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-setup.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments expected)
+
+**Preconditions:**
+- `.workflow/` directory must exist (created by `/maestro-init`)  # (see code: E001)
+- Project must contain source files to scan  # (see code: E002)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-setup.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
+| E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
+| W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
+| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
+| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory created
+- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
+- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
+- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
+</success_criteria>
+</output>

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

@@ -1,127 +1,127 @@
----
-name: learn-follow
-description: Guided reading of code or wiki to extract patterns
-argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional flags.
-
-**Target resolution** (auto-detected):
-| Input | Resolution |
-|-------|-----------|
-| File path (contains `/` or `\`) | Read source file |
-| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
-| Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |
-
-**Flags**:
-- `--depth shallow` (default): key patterns and structure only
-- `--depth deep`: every function, every branch, every assumption
-- `--save-wiki`: create wiki note entry with reading notes
-
-**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
-</context>
-
-<state_machine>
-
-<states>
-S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
-S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
-S_ORDER        — 确定阅读顺序                                PERSIST: —
-S_READ         — 逐节应用 forcing questions                   PERSIST: —
-S_EXTRACT      — 提取 patterns、cross-ref conventions         PERSIST: —
-S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowhow files
-</states>
-
-<transitions>
-
-S_RESOLVE:
-  → S_CONTEXT     WHEN: target resolved
-  → S_RESOLVE     WHEN: unresolvable                       DO: AskUserQuestion with suggestions
-
-S_CONTEXT:
-  → S_ORDER       DO: A_BUILD_CONTEXT_WEB
-
-S_ORDER:
-  → S_READ        DO: A_BUILD_READING_ORDER
-
-S_READ:
-  → S_EXTRACT     DO: A_GUIDED_READ (apply 4 forcing questions per section)
-
-S_EXTRACT:
-  → S_PERSIST     DO: A_EXTRACT_PATTERNS
-
-S_PERSIST:
-  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
-
-</transitions>
-
-<actions>
-
-### A_BUILD_CONTEXT_WEB
-
-| Target type | Context |
-|-------------|---------|
-| Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related |
-| Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) |
-| Directory | List files, identify entry points → build reading order: entry → core → utils → tests |
-
-### A_BUILD_READING_ORDER
-
-- Single file: split by function/class/export boundaries
-- Wiki entry: split by markdown headings
-- Directory: order by dependency (entry points first, leaf last)
-- `--depth shallow`: top-level structure only; `--depth deep`: every body and branch
-
-### A_GUIDED_READ
-
-For each section, apply 4 forcing questions:
-
-| # | Question | Extracts |
-|---|----------|----------|
-| 1 | "What pattern is being used here?" | Design patterns, idioms, conventions |
-| 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options |
-| 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering |
-| 4 | "What would break if this changed?" | Fragility, downstream effects |
-
-### A_EXTRACT_PATTERNS
-
-Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
-Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for spec-add".
-
-Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections.
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| W002 | coding-conventions.md not found | All patterns marked "unknown status" |
-| W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
-</error_codes>
-
-<success_criteria>
-- [ ] 4 forcing questions applied per section
-- [ ] Patterns extracted with file:line anchors and convention cross-ref
-- [ ] Understanding map + spec-entry blocks written
-</success_criteria>
-
-<next_step_routing>
-- Deep pattern dive → `/learn-decompose <path>`
-- Add to specs → `/spec-add coding <description>`
-- Second opinion → `/learn-second-opinion <file>`
-</next_step_routing>
+---
+name: learn-follow
+description: Guided reading of code or wiki to extract patterns
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path (contains `/` or `\`) | Read source file |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |
+
+**Flags**:
+- `--depth shallow` (default): key patterns and structure only
+- `--depth deep`: every function, every branch, every assumption
+- `--save-wiki`: create wiki note entry with reading notes
+
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
+</context>
+
+<state_machine>
+
+<states>
+S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
+S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
+S_ORDER        — 确定阅读顺序                                PERSIST: —
+S_READ         — 逐节应用 forcing questions                   PERSIST: —
+S_EXTRACT      — 提取 patterns、cross-ref conventions         PERSIST: —
+S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved
+  → S_RESOLVE     WHEN: unresolvable                       DO: AskUserQuestion with suggestions
+
+S_CONTEXT:
+  → S_ORDER       DO: A_BUILD_CONTEXT_WEB
+
+S_ORDER:
+  → S_READ        DO: A_BUILD_READING_ORDER
+
+S_READ:
+  → S_EXTRACT     DO: A_GUIDED_READ (apply 4 forcing questions per section)
+
+S_EXTRACT:
+  → S_PERSIST     DO: A_EXTRACT_PATTERNS
+
+S_PERSIST:
+  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
+
+</transitions>
+
+<actions>
+
+### A_BUILD_CONTEXT_WEB
+
+| Target type | Context |
+|-------------|---------|
+| Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related |
+| Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) |
+| Directory | List files, identify entry points → build reading order: entry → core → utils → tests |
+
+### A_BUILD_READING_ORDER
+
+- Single file: split by function/class/export boundaries
+- Wiki entry: split by markdown headings
+- Directory: order by dependency (entry points first, leaf last)
+- `--depth shallow`: top-level structure only; `--depth deep`: every body and branch
+
+### A_GUIDED_READ
+
+For each section, apply 4 forcing questions:
+
+| # | Question | Extracts |
+|---|----------|----------|
+| 1 | "What pattern is being used here?" | Design patterns, idioms, conventions |
+| 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options |
+| 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering |
+| 4 | "What would break if this changed?" | Fragility, downstream effects |
+
+### A_EXTRACT_PATTERNS
+
+Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for spec-add".
+
+Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| W002 | coding-conventions.md not found | All patterns marked "unknown status" |
+| W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
+</error_codes>
+
+<success_criteria>
+- [ ] 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors and convention cross-ref
+- [ ] Understanding map + spec-entry blocks written
+</success_criteria>
+
+<next_step_routing>
+- Deep pattern dive → `/learn-decompose <path>`
+- Add to specs → `/spec-add coding <description>`
+- Second opinion → `/learn-second-opinion <file>`
+</next_step_routing>