maestro-flow 0.5.2 → 0.5.31

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

@@ -1,78 +1,78 @@
----
-name: spec-load
-description: Load specs and lessons for current context
-argument-hint: "[--scope <scope>] [--category <category>] [--keyword <word>]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-<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>
+---
+name: spec-load
+description: Load specs and lessons for current context
+argument-hint: "[--scope <scope>] [--category <category>] [--keyword <word>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<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/.claude/commands/spec-remove.md

@@ -1,55 +1,55 @@
----
-name: spec-remove
-description: Remove spec entry by ID
-argument-hint: "<entry-id> [--cascade]"
-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.
-
-**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>
+---
+name: spec-remove
+description: Remove spec entry by ID
+argument-hint: "<entry-id> [--cascade]"
+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.
+
+**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/.claude/commands/spec-setup.md

@@ -1,52 +1,49 @@
----
-name: spec-setup
-description: Initialize specs from project structure
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
----
-<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>
+---
+name: spec-setup
+description: Initialize specs from project structure
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<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/skills/insight-challenge/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: insight-challenge
+description: "Adversarial review of code quality findings. Challenges insights with counter-evidence, verifies claims against source code, and produces structured verdicts. Triggers on 'insight-challenge', 'challenge finding', '审查发现'."
+allowed-tools: Read(*), Glob(*), Grep(*), Bash(*), Write(*)
+---
+
+# Insight Challenge
+
+Adversarial review of code quality findings. Challenges insights with counter-evidence, verifies claims against source code, and produces structured verdicts.
+
+**适用场景**: 当需要对代码审查、质量分析、或架构评估中的发现进行对抗性验证时使用。
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Insight Challenge (SKILL.md) — Adversarial Review          │
+│  → Parse finding → Read source → Challenge → Verdict        │
+└─────────────────────────────────────────────────────────────┘
+                           │
+    ┌──────────┬───────────┼───────────┬──────────┐
+    ↓          ↓           ↓           ↓          │
+┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │
+│Phase 1 │ │Phase 2 │ │Phase 3 │ │Phase 4 │      │
+│ Parse  │ │ Source │ │Challenge│ │Verdict │      │
+│Finding │ │ Review │ │Analysis │ │Report  │      │
+└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘      │
+    │          │          │          │             │
+ finding    source     counter-   structured      │
+ parsed     code       evidence   verdict         │
+```
+
+## Key Design Principles
+
+1. **Adversarial by Default**: Assume findings may be incorrect; seek counter-evidence first
+2. **Source-Code Anchored**: All claims must be verified against actual code, not assumptions
+3. **Structured Output**: Verdicts follow a fixed schema for downstream consumption
+4. **Fair Challenge**: If evidence supports the finding, confirm it; don't manufacture doubt
+5. **Transparent Reasoning**: Show the chain of evidence and reasoning
+
+## Finding Input Format
+
+Findings can be provided as JSON or structured text:
+
+```json
+{
+  "id": "HIGH-01",
+  "title": "知识边类型 resolves/documents 未在 types.ts 声明",
+  "severity": "high",
+  "file": "src/graph/kg/db/types.ts",
+  "line": 58,
+  "description": "issue-extractor 使用 'resolves' 边类型...",
+  "evidence": "types.ts KnowledgeEdgeKind: defines, constrains...",
+  "suggestion": "补齐缺失的边类型声明",
+  "design_ref": "Gap 2 — 12 CodeEdgeKind + 9 KnowledgeEdgeKind"
+}
+```
+
+Or structured text:
+```
+HIGH-01: 知识边类型 resolves/documents 未在 types.ts 声明
+Severity: high
+File: src/graph/kg/db/types.ts:58
+Claim: issue-extractor 使用 'resolves' 边类型但未在类型系统中声明
+Evidence: types.ts KnowledgeEdgeKind 列表中缺少 'resolves'
+```
+
+## Execution Flow
+
+### Phase 1: Parse Finding
+
+1. Extract finding ID, title, severity, file reference, and claims
+2. Identify all verifiable assertions:
+   - File existence claims
+   - Code structure claims (types, functions, variables)
+   - Behavioral claims (usage patterns, dependencies)
+   - Design conformance claims
+3. Create verification checklist
+
+### Phase 2: Source Review
+
+1. Read the referenced file(s) at the specified lines
+2. Search for related code using Grep/Glob
+3. Document actual state of the code:
+   - What types/functions actually exist
+   - What values are actually declared
+   - What the actual implementation looks like
+4. Compare claims against reality
+
+### Phase 3: Challenge Analysis
+
+For each claim in the finding:
+
+1. **Seek confirming evidence**: Does the source code support this claim?
+2. **Seek disconfirming evidence**: Does the source code contradict this claim?
+3. **Check for misinterpretation**: Could the claim be based on outdated code or misunderstanding?
+4. **Verify design references**: Are cited design docs accurate?
+
+Challenge strategies:
+- **Direct contradiction**: Source code explicitly shows the opposite
+- **Context omission**: Finding omits relevant context that changes the interpretation
+- **Stale reference**: Finding references code that has been updated
+- **Miscounted**: Numeric claims (missing N types) are incorrect
+- **Scope error**: Finding applies wrong scope (e.g., confuses edge types with language types)
+
+### Phase 4: Verdict Report
+
+Produce structured output:
+
+```json
+{
+  "finding_id": "HIGH-01",
+  "challenge_result": "overturned|weakened|confirmed",
+  "confidence": 95,
+  "reasoning": "Detailed explanation of why the finding was challenged or confirmed",
+  "counter_evidence": [
+    "Source file line 64: 'resolves' IS declared in KnowledgeEdgeKind",
+    "Design doc specifies 20 edge types, not 28"
+  ],
+  "supporting_evidence": [],
+  "adjusted_severity": "none|high|medium|low",
+  "recommendation": "Dismiss this finding; the claimed gap does not exist"
+}
+```
+
+## Verdict Definitions
+
+| Verdict | Meaning | When to Use |
+|---------|---------|-------------|
+| **overturned** | Finding is factually incorrect | Source code directly contradicts the claim |
+| **weakened** | Finding is partially correct but overstated | Some evidence supports it, but severity/scope is wrong |
+| **confirmed** | Finding is accurate | Source code supports all claims |
+
+## Challenge Patterns
+
+### Pattern 1: Type Declaration Check
+```
+Claim: "Type X is not declared"
+Challenge: Read the type file → check if X exists in type union/enum
+Counter: "Line N shows X IS declared in the type definition"
+```
+
+### Pattern 2: Design Reference Verification
+```
+Claim: "Design requires N items, implementation has M"
+Challenge: Read design doc → verify the claimed requirement
+Counter: "Design doc actually specifies K items, not N"
+```
+
+### Pattern 3: Usage Verification
+```
+Claim: "Code uses type X but X is not defined"
+Challenge: Check both usage site AND definition site
+Counter: "X is defined at line N in file Y"
+```
+
+### Pattern 4: Scope Confusion
+```
+Claim: "Missing 7 edge types (total should be 28)"
+Challenge: Check what the "28" actually refers to
+Counter: "The 28 refers to language types, not edge types; edge types are 21"
+```
+
+## Output Format
+
+The challenge produces a markdown report:
+
+```markdown
+## Challenge Report: <finding_id>
+
+**Verdict**: <overturned|weakened|confirmed>
+**Confidence**: <0-100>%
+**Adjusted Severity**: <none|high|medium|low>
+
+### Original Finding
+<finding summary>
+
+### Counter-Evidence
+- <evidence point 1>
+- <evidence point 2>
+
+### Supporting Evidence
+- <evidence point 1> (if any)
+
+### Reasoning
+<detailed explanation>
+
+### Recommendation
+<action recommendation>
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Referenced file not found | Report file missing; verdict = weakened (potentially stale) |
+| Line number out of range | Search for the claimed content; adjust line reference |
+| Design doc not found | Skip design verification; note in report |
+| Ambiguous evidence | Present both sides; lower confidence score |
+| Multiple findings batch | Process each independently; produce per-finding verdicts |
+
+## Usage Examples
+
+### Single Finding Challenge
+```
+Skill(skill="insight-challenge", args='{"id":"HIGH-01","title":"...","file":"src/types.ts","line":58,...}')
+```
+
+### Batch Challenge
+```
+Skill(skill="insight-challenge", args='findings.json')
+```
+
+### Inline Challenge
+```
+Challenge this finding:
+Claim: Function X is not exported
+File: src/utils.ts:45
+Evidence: grep shows no export keyword
+```
+
+## Related Skills
+
+- **team-adversarial-swarm**: Multi-agent adversarial analysis
+- **team-quality-assurance**: QA pipeline with issue discovery
+- **codify-to-knowhow**: Capturing verified knowledge