maestro-flow-one 0.2.4 → 0.2.5

package/maestro-flow/commands/lifecycle/execute.md

@@ -36,7 +36,8 @@ Scope routing, flags, resolution logic, output directory format, artifact regist
 
 1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
 2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
-3. Both are optional — proceed without if unavailable (log warning).
+3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
+4. All are optional — proceed without if unavailable (log warning).
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:

package/maestro-flow/commands/lifecycle/tools-register.md

@@ -17,7 +17,7 @@ Codify reusable business processes as knowhow documents with `tool: true` in `.w
 
 When to register: during planning to standardize a business process (e.g. payment reconciliation, OAuth integration steps); after execution to capture a validated procedure (e.g. database migration rollback); before testing to register verification methods for test agents (e.g. E2E checkout flow, API idempotency verification); during retrospective/harvest to extract reusable process knowledge from artifacts.
 
-Three modes: Extract (from code/docs), Generate (from description), Optimize (improve existing).
+Four modes: Extract (from code/docs), Generate (from description), Optimize (improve existing), Promote (existing knowhow → tool in place).
 Short processes (<10 steps) inline; long processes (>=10 steps) use ref mode with knowhow detail doc.
 </purpose>
 
@@ -34,6 +34,8 @@ $ARGUMENTS — Intent description
 /maestro-tools-register generate Stripe webhook idempotency verification
 /maestro-tools-register generate E2E checkout flow with payment gateway mock setup
 /maestro-tools-register optimize e2e-checkout tool
+/maestro-tools-register promote RCP-db-migration-rollback as test tool
+/maestro-tools-register promote knowhow-auth-api to coding tool
 ```
 </context>
 
@@ -44,6 +46,7 @@ $ARGUMENTS — Intent description
 Parse $ARGUMENTS to determine mode:
 - Contains "extract" → extract mode
 - Contains "optimize/improve" → optimize mode
+- Contains "promote" or references existing knowhow doc (path/ID) → promote mode
 - Other → generate mode
 - Empty → ask user with AskUserQuestion
 
@@ -61,16 +64,34 @@ Parse $ARGUMENTS to determine mode:
 - Load existing tool: `maestro spec load --category coding --keyword <name>`
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
+**Promote mode** (existing knowhow → tool):
+- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Read document, verify it contains actionable steps (numbered list or ## Steps section)
+- If no actionable steps, suggest extract mode instead
+- Determine category (Step 3) and summary ("Use when ...")
+- Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
+- Do NOT recreate the document — modify in place
+
 **For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
 
 ### Step 3: Determine Category
 
-Infer applicable category from context, or ask user:
-- coding — execution tools (build, deploy, integrate)
-- test — testing tools (test flows, verification steps)
-- review — review tools (checklists, audit standards)
-- arch — planning tools (design flows, analysis steps)
-- debug — analysis tools (diagnostic flows, investigation steps)
+**Core principle**: `category` = **who consumes this tool** (which agent type discovers and uses it), not what the content is about.
+
+| Category | Consumer Agent | Decision Question | Signal Words |
+|---|---|---|---|
+| `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
+| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
+| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
+| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
+| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
+
+**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
+- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
+- API verification steps (how to test) → `category: test` (RCP-*, tool: true)
+- Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
+
+**Ambiguous cases**: Choose the **primary consumer** — the agent that would fail without this knowledge.
 
 ### Step 4: Decide Inline vs Ref
 

package/maestro-flow/commands/manage/knowhow-capture.md

@@ -34,6 +34,9 @@ Arguments: $ARGUMENTS
 | `reference` | REF- | External doc / API quick-ref | source URL, key points, scenarios |
 | `decision` | DCS- | Design decision record | context, alternatives, rationale, consequences |
 | `tip` | TIP- | Quick note / reminder | content, tags |
+| `asset` | AST- | Code asset (API contract, data model) | assetType, codePaths, category |
+| `blueprint` | BLP- | Architecture design with code paths | codePaths, category |
+| `document` | DOC- | General long-form (fallback) | — |
 
 No arguments: auto-detect type or ask user via AskUserQuestion.
 
@@ -42,6 +45,9 @@ No arguments: auto-detect type or ask user via AskUserQuestion.
 - `--source <url>` — Source URL for references
 - `--tag tag1,tag2` — Categorization tags
 - `--title <title>` — Explicit title (auto-generated if omitted)
+- `--asset-type <type>` — Asset subtype: api-contract, data-model, prompt, config, etc.
+- `--code-paths <paths>` — Related source paths for asset/blueprint (comma-separated)
+- `--category <cat>` — Spec category for agent discovery (coding, arch, test, debug, review, learning)
 </context>
 
 <execution>
@@ -58,8 +64,11 @@ Parse first token as type. If ambiguous, AskUserQuestion with options:
 | `reference`, `ref`, `参考`, `引用` | reference |
 | `decision`, `dcs`, `决策`, `adr` | decision |
 | `tip`, `note`, `记录`, `快速` | tip |
+| `asset`, `ast`, `资产`, `契约` | asset |
+| `blueprint`, `blp`, `蓝图` | blueprint |
+| `document`, `doc`, `文档` | document |
 | No match, short text, `--tag` present | tip |
-| No arguments | AskUserQuestion (6 options) |
+| No arguments | AskUserQuestion (9 options) |
 
 ### Step 2: Generate Content by Type
 

package/maestro-flow/commands/quality/debug.md

@@ -47,7 +47,8 @@ Extract conclusions from related artifacts that may affect this debug session
 
 1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load module boundaries to scope impact analysis and inform hypothesis formation.
 2. **Wiki prior knowledge**: Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`. If results found, check for prior investigations on similar issues to avoid re-investigation.
-3. Both are optional — proceed without if unavailable.
+3. **Debug specs + tools**: Run `maestro spec load --category debug --keyword "<symptom keywords>"`. If tools found, extract known issues, workarounds, and root-cause notes to inform hypotheses.
+4. All are optional — proceed without if unavailable.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:

package/maestro-flow/commands/quality/review.md

@@ -52,7 +52,8 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 
 1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load component boundaries and layer rules. Pass as `codebase_context` to reviewer agents (especially architecture dimension).
 2. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, pass as `wiki_context` to reviewer agents for evaluating code against documented decisions.
-3. Both are optional — proceed without if unavailable.
+3. **Review specs + tools**: Run `maestro spec load --category review` to load review standards, checklists, AND discoverable knowhow tools. Pass as `specs_content` to all reviewer agents.
+4. All are optional — proceed without if unavailable.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:

package/maestro-flow/commands/quality/test.md

@@ -40,6 +40,11 @@ Follow '~/.maestro/workflows/test.md' completely.
 
 **Command-specific extensions (not in workflow):**
 
+**Test tool discovery** (knowhow tools as scenario source):
+- Load registered test tools: `maestro spec load --category test --keyword <feature>`
+- If tools found, extract their steps as additional test scenarios marked `source: "tool"`
+- Each numbered step in a tool becomes a UAT test with its assertion as `expected` behavior
+
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"

package/maestro-flow/commands/lifecycle/link-coordinate.md

@@ -1,71 +0,0 @@
----
-name: maestro-link-coordinate
-description: Execute command chain nodes step by step
-argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
----
-<purpose>
-Step-mode workflow coordinator using `maestro coordinate` CLI subcommands (start/next/status).
-Walks chain graphs node by node — each command node executed via `maestro delegate` internally.
-Decision/gate/eval nodes auto-resolve between steps. Session persisted for resume.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/maestro-link-coordinate.md
-</required_reading>
-
-<context>
-$ARGUMENTS — user intent text, or flags.
-
-**Flags:**
-- `--list` — List all available chain graphs
-- `-c` / `--continue [sessionId]` — Resume step_paused session via `coordinate next`
-- `--chain <name>` — Force a specific chain graph
-- `--tool <tool>` — CLI tool override (default: claude)
-- `-y` / `--yes` — Auto mode
-
-**CLI endpoints used:**
-- `maestro coordinate list` — enumerate chains
-- `maestro coordinate start "intent" --chain X` — begin step-mode session
-- `maestro coordinate next [sessionId]` — advance one step
-- `maestro coordinate status [sessionId]` — query state
-- `maestro coordinate run "intent"` — autonomous full run
-- `maestro coordinate watch <sessionId> [--follow]` — read-only event tail (separate from driver loop)
-- `maestro coordinate report` — agent-invoked command-node result writer (authoritative result channel)
-
-**Internal walker capabilities (invisible to driver loop):**
-- Prompt assembly owned by the walker (main flow) for both command and decision nodes
-- Decision nodes auto-resolve via `strategy: 'expr'` (fast path) with LLM decider fallback when expr has no match and no default edge, or explicit `strategy: 'llm'`
-- Walker events published to a file/SQLite broker for `watch` observers
-- LLM decision in step mode is synchronous — avoid tight per-step deadlines
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/maestro-link-coordinate.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent and no --list/--chain | Suggest --list |
-| E002 | error | Chain graph not found | Show list output |
-| E003 | error | Step execution failed | Check status, retry next |
-| E004 | error | Resume session not found | List sessions |
-| E005 | error | CLI endpoint unavailable | Check maestro installation |
-</error_codes>
-
-<success_criteria>
-- [ ] Chain graph loaded via `maestro coordinate start`
-- [ ] Each step executed via `maestro coordinate next` loop
-- [ ] JSON output parsed for session tracking
-- [ ] Decision nodes auto-resolved between steps
-- [ ] Session persisted and resumable via `-c`
-- [ ] Completion summary displayed
-</success_criteria>