maestro-flow 0.4.19 → 0.4.21

package/workflows/grill.md

@@ -0,0 +1,513 @@
+# Workflow: Grill
+
+Socratic stress-testing of a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time, challenges vague terminology against existing code, probes edge cases with concrete scenarios, and produces a verified context package for downstream brainstorm/analyze/roadmap consumption.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│                /maestro-grill                    │
+│        Entry Point + Interactive Routing          │
+└───────────────────────┬──────────────────────────┘
+                        │
+  Step 1: Parse & Route (mode, depth, upstream)
+  Step 2: Discovery (docs + codebase scan)
+  Step 3: Terminology Alignment (code vs proposal)
+  Step 4: Branch Walking (Socratic grilling loop)
+  Step 5: Synthesis (report + terminology)
+  Step 6: Context Package (context-package.json)
+  Step 7: Register Artifact + finish-work
+```
+
+## Input
+
+- `$ARGUMENTS`: topic/plan text, or `--from <source>` for upstream input
+- All output goes to `.workflow/scratch/{YYYYMMDD}-grill-{slug}/`
+- Registers artifact (type=grill) in state.json on completion
+- **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only.
+
+### Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--yes`, `-y` | Auto mode — use code exploration instead of human answers | - |
+| `--depth` | Grilling depth: `shallow` (3 branches), `standard` (5), `deep` (8) | `standard` |
+| `--from <source>` | Load upstream material: `blueprint:ID`, `@file`, or path | - |
+| `--session ID` | Resume existing grill session | - |
+| `-c`, `--continue` | Continue from last grill session | - |
+
+### Produced Files
+
+| File | Description |
+|------|-------------|
+| `grill-report.md` | Main output — all grilling branches with decisions, evidence, risks |
+| `terminology.md` | Glossary crystallized during grilling, cross-referenced with code |
+| `context-package.json` | Standardized context package for downstream consumption |
+
+---
+
+## Step 1: Parse & Route
+
+Parse $ARGUMENTS to determine execution mode:
+
+**Mode Detection (ordered by priority)**:
+1. `-c` / `--continue` → **Resume Mode** (find latest grill session, continue from last branch)
+2. `--session ID` → **Resume Mode** (specific session)
+3. `--yes` / `-y` → **Auto Mode** (code exploration replaces human answers)
+4. Text provided → **Interactive Mode** (default, full Socratic grilling)
+5. No args → error E001
+
+**Parameter Parsing**:
+- `--depth shallow|standard|deep`: branch count 3/5/8, default `standard` (5)
+- `--from <source>`: upstream material to grill against
+- Missing/empty args without `--from` or `--continue` = error E001
+
+**Session Detection**:
+- Check `.workflow/scratch/*-grill-*/` for existing sessions
+- Resume: load `grill-report.md` → find last completed branch → continue from next
+- New: create `.workflow/scratch/{YYYYMMDD}-grill-{slug}/`
+
+**Output Directory Resolution**:
+```
+output_dir = .workflow/scratch/{YYYYMMDD}-grill-{slug}/
+```
+
+---
+
+## Step 2: Discovery
+
+Scan project documentation and codebase to build a grilling context. This grounds all subsequent questions in code reality.
+
+### 2.1: Load Project State
+
+```
+1. Read .workflow/project.md (if exists) → tech_stack, validated_requirements, active_requirements
+2. Read .workflow/state.json (if exists) → accumulated_context, artifacts[]
+3. Read .workflow/roadmap.md (if exists) → phase structure
+4. specs_content = maestro spec load --category arch
+5. wiki_hits = maestro wiki search "{topic keywords}"
+```
+
+### 2.2: Load Upstream Material
+
+If `--from` specified:
+- `--from blueprint:ID` → `state.json.artifacts[type=blueprint, id=ID]` → load spec package
+- `--from @file` → read file directly as proposal text
+- `--from path/` → read `path/` directory for markdown files
+
+Store as `upstream_material` (in-memory).
+
+### 2.3: Codebase Scan
+
+Spawn `Agent(subagent_type: Explore)` to map the codebase surface relevant to the topic:
+
+```
+Agent(
+  subagent_type="Explore",
+  prompt="""
+  Search breadth: medium
+  Find code relevant to: {topic}
+  Report:
+  1. Existing modules/files that overlap with this topic
+  2. Naming conventions used (variable names, function names, types)
+  3. Patterns already established (error handling, data flow, API style)
+  4. Dependencies and integration points
+  Return structured findings — file paths, symbol names, pattern descriptions.
+  """,
+  description="Codebase scan for grill context"
+)
+```
+
+Store as `codebase_context`.
+
+If scan fails (W001): `codebase_context = null`, continue without code grounding.
+
+### 2.4: Initialize Report
+
+Write `{output_dir}/grill-report.md` with header:
+
+```markdown
+# Grill Report: {topic}
+
+**Session**: {session_id}
+**Depth**: {depth} ({branch_count} branches)
+**Date**: {ISO-8601}
+**Upstream**: {source or "none"}
+
+## Discovery Summary
+
+### Project Context
+{summary from Step 2.1}
+
+### Codebase Surface
+{summary from Step 2.3}
+
+### Upstream Material
+{summary from Step 2.2 or "N/A"}
+
+---
+
+## Branch Log
+
+| # | Branch | Status | Decisions | Open Questions |
+|---|--------|--------|-----------|----------------|
+
+---
+```
+
+---
+
+## Step 3: Terminology Alignment
+
+Extract terminology from the proposal/topic and cross-reference with codebase naming.
+
+### 3.1: Extract Candidate Terms
+
+From topic text + upstream material, identify 5-15 candidate domain terms:
+- Nouns that appear as entities, concepts, or roles
+- Verbs that describe key operations
+- Adjectives that qualify system properties
+
+### 3.2: Code Name Collision Check
+
+For each candidate term, search the codebase:
+```
+Grep(pattern="{term}", output_mode="files_with_matches")
+```
+
+Build a collision table:
+
+| Proposed Term | Code Usage | Conflict? | Resolution |
+|---------------|------------|-----------|------------|
+| "account" | `UserAccount` class (auth module) | Yes — ambiguous | Propose: "Organization" for billing, "UserAccount" for auth |
+
+### 3.3: Challenge Vague Terms
+
+For each term with conflict or ambiguity, challenge the user via AskUserQuestion:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "You said '{term}' — but the codebase uses '{code_name}' for {code_meaning}. Which do you mean?",
+    header: "Terminology",
+    options: [
+      { label: "Use '{code_name}'", description: "Align with existing codebase naming" },
+      { label: "New term: '{proposed}'", description: "Introduce new concept distinct from {code_name}" },
+      { label: "Rename existing", description: "The existing code should adopt the new term" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Auto mode (`-y`)**: Use CLI exploration to resolve — prefer existing code naming unless semantically wrong.
+
+### 3.4: Write Terminology File
+
+Write `{output_dir}/terminology.md`:
+
+```markdown
+# Terminology
+
+| Term | Definition | Code Reference | Status |
+|------|------------|----------------|--------|
+| {term} | {definition} | `{file:symbol}` or "new" | locked/open |
+```
+
+---
+
+## Step 4: Branch Walking (Core Grilling Loop)
+
+The heart of the grill. Walk the decision tree one branch at a time, one question per turn. Each branch is fully explored before moving to the next.
+
+### Branch Categories
+
+Select branches based on `--depth`:
+
+| Priority | Branch | Shallow | Standard | Deep |
+|----------|--------|---------|----------|------|
+| 1 | Scope & Boundaries | ✓ | ✓ | ✓ |
+| 2 | Data Model & State | ✓ | ✓ | ✓ |
+| 3 | Edge Cases & Failure Modes | ✓ | ✓ | ✓ |
+| 4 | Integration & Dependencies | | ✓ | ✓ |
+| 5 | Scale & Performance | | ✓ | ✓ |
+| 6 | Security & Access Control | | | ✓ |
+| 7 | Observability & Operations | | | ✓ |
+| 8 | Migration & Rollback | | | ✓ |
+
+### Branch Walking Protocol
+
+For EACH selected branch:
+
+**4.1: Open the Branch**
+
+Append to `grill-report.md`:
+```markdown
+## Branch {N}: {branch_name}
+
+**Status**: 🔴 In Progress
+**Questions asked**: 0
+**Decisions locked**: 0
+```
+
+**4.2: Generate Probing Questions**
+
+Based on the topic + codebase_context + terminology + prior branch decisions, generate 3-5 probing questions for this branch. Questions MUST:
+- Reference specific code findings from Step 2.3 when available
+- Use concrete scenarios, not abstract hypotheticals
+- Challenge assumptions ("You said X, but the code shows Y — how do you reconcile?")
+- Escalate from basic to adversarial
+
+Question generation pattern per branch:
+
+**Scope & Boundaries**:
+- "What is the smallest version of this that delivers value?"
+- "You mentioned {feature} — does it need {sub-feature}, or is that a separate concern?"
+- "The codebase already has {existing_module} — where does your proposal's boundary end and {existing_module} begin?"
+
+**Data Model & State**:
+- "What are the core entities? Walk me through their lifecycle."
+- "The code uses {existing_model} — does your {proposed_entity} extend it, replace it, or coexist?"
+- "What happens to {entity} when {related_entity} is deleted?"
+
+**Edge Cases & Failure Modes**:
+- "What happens when {operation} is called with {extreme_input}?"
+- "If {dependency} is unavailable, what does the user see?"
+- "Two users do {action} simultaneously — what wins?"
+
+**Integration & Dependencies**:
+- "Which existing modules does this touch? Show me the call chain."
+- "What contract does this establish with {consumer}? What can they NOT assume?"
+- "If {upstream_service} changes its API, how much of this breaks?"
+
+**Scale & Performance**:
+- "At 10x current load, which part breaks first?"
+- "This query touches {table} — how many rows at steady state? At peak?"
+- "What's the cache invalidation strategy? What goes stale?"
+
+**Security & Access Control**:
+- "Who can perform {action}? Who explicitly cannot?"
+- "What happens if an authenticated user sends a crafted {input}?"
+- "Where does PII flow? Where is it stored? Who can access it?"
+
+**Observability & Operations**:
+- "How do you know this is working correctly in production?"
+- "What alert fires first when this breaks? What's the runbook?"
+- "How do you debug a user report of '{symptom}'?"
+
+**Migration & Rollback**:
+- "How do you deploy this without downtime?"
+- "If this fails in production, what's the rollback procedure?"
+- "What data migration is needed? Is it reversible?"
+
+**4.3: Ask One Question at a Time**
+
+For each question in the branch:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "{probing_question}",
+    header: "{branch_name}",
+    options: [
+      { label: "{option_a}", description: "{implication_a}" },
+      { label: "{option_b}", description: "{implication_b}" },
+      { label: "Not applicable", description: "This concern doesn't apply to this proposal" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Auto mode**: Instead of asking the user, use code exploration to answer:
+```
+maestro delegate "PURPOSE: Answer '{question}' for the proposal '{topic}'
+TASK: Search codebase for evidence | Analyze existing patterns | Determine most likely answer
+MODE: analysis
+CONTEXT: @**/* | Proposal: {topic_summary}
+EXPECTED: Direct answer with code evidence (file:line references)
+CONSTRAINTS: Answer based on code evidence only, flag uncertainty" --role analyze --mode analysis
+```
+
+**4.4: Validate Answer Against Code**
+
+After each answer, verify against codebase when possible:
+- If user says "We'll use X pattern" → Grep for existing X usage, confirm consistency
+- If user says "This won't affect Y" → Explore call chains to verify isolation
+- If contradiction found → immediately challenge:
+
+```
+"You said {answer}, but I found {code_evidence} at {file:line}. 
+This suggests {contradiction}. How do you reconcile?"
+```
+
+**4.5: Record Decision**
+
+After each question is settled, immediately append to `grill-report.md`:
+
+```markdown
+### Q{N}.{M}: {question_summary}
+
+**Answer**: {user_answer_or_auto_answer}
+**Evidence**: {code_references_or_reasoning}
+**Decision**: {locked|open|deferred}
+**Constraint**: {if locked, the RFC 2119 statement — e.g., "MUST use event sourcing for audit trail"}
+```
+
+Update the branch header: increment questions/decisions counts.
+
+**4.6: Branch Completion**
+
+When all questions in a branch are asked (or user signals "enough"):
+- Update branch status to ✅ Completed
+- Update Branch Log table in report header
+- Move to next branch
+
+---
+
+## Step 5: Synthesis
+
+After all branches are walked (or max rounds reached):
+
+### 5.1: Decision Summary
+
+Read all branch decisions from `grill-report.md`. Classify:
+
+| Classification | Criteria | Downstream Use |
+|----------------|----------|----------------|
+| **Locked** | User confirmed + code-verified | → `constraints[]` in context-package |
+| **Open** | User answered but unverified or uncertain | → `open_questions[]` in context-package |
+| **Deferred** | Explicitly postponed or "not applicable" | → `non_goals[]` or future work |
+
+### 5.2: Risk Register
+
+Extract unresolved tensions, contradictions found during grilling, and branches not fully explored:
+
+```markdown
+## Risk Register
+
+| # | Risk | Branch | Severity | Mitigation |
+|---|------|--------|----------|------------|
+```
+
+### 5.3: Finalize Report
+
+Append to `grill-report.md`:
+
+```markdown
+## Synthesis
+
+### Decision Summary
+| # | Decision | Status | Branch | RFC 2119 |
+|---|----------|--------|--------|----------|
+
+### Verified Constraints
+{locked decisions with code evidence}
+
+### Open Questions
+{decisions needing further exploration}
+
+### Risk Register
+{from 5.2}
+
+### Recommended Next Step
+{routing based on findings}
+```
+
+### 5.4: Finalize Terminology
+
+Update `{output_dir}/terminology.md` — mark all terms as locked/open based on grilling outcomes. Add any new terms surfaced during branch walking.
+
+---
+
+## Step 6: Generate Context Package
+
+Write `{output_dir}/context-package.json`:
+
+```jsonc
+{
+  "$schema": "context-package/1.0",
+  "source": {
+    "type": "grill",
+    "artifact_id": "{artifact_id}",
+    "session_path": "{output_dir relative to .workflow/}",
+    "generated_at": "{ISO-8601}"
+  },
+  "requirements": [],
+  "constraints": [],
+  "domain": {
+    "problem_statement": "",
+    "terminology": [],
+    "audience": "",
+    "industry": ""
+  },
+  "non_goals": [],
+  "insights": [],
+  "open_questions": [],
+  "references": []
+}
+```
+
+**Extraction mapping**:
+- `requirements[]`: locked scope decisions from Branch 1 → `{ id: "R-{NNN}", title, description, priority: "must|should|may", ref: "grill-report.md#Branch-1" }`
+- `constraints[]`: all locked decisions with RFC 2119 keywords → `{ id: "C-{NNN}", area, constraint, rationale, status: "locked", ref: "grill-report.md#Q{N}.{M}" }`
+- `domain.problem_statement`: from topic + synthesis
+- `domain.terminology[]`: from `terminology.md` → `{ term, definition, code_ref, status: "locked|open" }`
+- `non_goals[]`: deferred decisions + explicit exclusions → `{ title, rationale, ref }`
+- `insights[]`: code findings that contradicted or enriched the proposal → `{ area, summary, evidence, ref }`
+- `open_questions[]`: open decisions needing brainstorm/analyze exploration → `{ area, question, options[], ref }`
+- `references[]`: `{ type: "grill-report", path: "grill-report.md" }`, `{ type: "terminology", path: "terminology.md" }`
+
+---
+
+## Step 7: Register Artifact
+
+### 7.1: Register in state.json
+
+```jsonc
+{
+  "id": "GRL-{NNN}",
+  "type": "grill",
+  "scope": "standalone",
+  "path": "{output_dir relative to .workflow/}",
+  "status": "completed",
+  "context_package": "{output_dir}/context-package.json",
+  "created_at": "{ISO-8601}",
+  "metadata": {
+    "topic": "{topic}",
+    "depth": "{depth}",
+    "branches_completed": {N},
+    "decisions_locked": {N},
+    "decisions_open": {N},
+    "terms_defined": {N}
+  }
+}
+```
+
+### 7.2: Completion Report
+
+```
+Grill session {artifact_id} completed.
+- Branches walked: {N}/{total}
+- Decisions locked: {N}
+- Open questions: {N}
+- Terms defined: {N}
+- Risk items: {N}
+
+Next steps:
+  /maestro-brainstorm "{topic}" --from grill:{artifact_id}   — Multi-role brainstorm with grilled context
+  /maestro-analyze "{topic}" --from grill:{artifact_id}      — Deep analysis with grilled constraints
+  /maestro-roadmap --from grill:{artifact_id}                — Direct to roadmap (if scope is clear)
+```
+
+---
+
+## Quality Criteria
+
+- grill-report.md has at least `{depth_branch_count}` completed branches
+- Each branch has ≥ 2 question-answer pairs with evidence
+- terminology.md has ≥ 5 terms with code references where applicable
+- context-package.json passes schema validation (all required fields present)
+- No locked decision lacks evidence (code reference or explicit user confirmation)
+- Risk register captures all unresolved contradictions found during grilling
+- Branch Log table in report header is fully populated with final status

package/workflows/plan.md

@@ -231,11 +231,14 @@ When `--tdd` is active:
 
 **Purpose:** Generate the execution plan.
 
-**Rule:** Main flow MUST NOT create/modify TASK files. All planning delegated to planner agent. Upstream analyze results (conclusions.json / implementation_scope) MUST be passed into planner spawn as `explorationContext` in the same step.
+**Rules:**
+- Main flow **MUST** spawn a planner agent (Agent tool) for P3 — inline planning is FORBIDDEN
+- Agent produces both `plan.json` and `.task/TASK-{NNN}.json` — main flow MUST NOT create/modify these files
+- Upstream analyze results (conclusions.json / implementation_scope) MUST be passed into planner spawn as `explorationContext` in the same step
 
 ### Standard Mode (default)
 
-Spawn `workflow-planner` agent with: context.md, spec-ref, doc-index.json, explorationContext (incl. implementationScope from P1 Step 5), clarificationContext, phase goal + success_criteria, templates (plan.json, task.json).
+MUST spawn `workflow-planner` agent with: context.md, spec-ref, doc-index.json, explorationContext (incl. implementationScope from P1 Step 5), clarificationContext, phase goal + success_criteria, templates (plan.json, task.json).
 
 **Task count guard**: Before spawning, assess scope complexity:
 - Single feature / simple change → expect **1-2 tasks** max
@@ -293,12 +296,12 @@ Every TASK-*.json MUST include these fields — they are NOT optional:
 
 - Pre-allocate TASK ID ranges per planner (2-5 planners based on scope): TASK-001..010, TASK-011..020, etc.
 - Create `plan-note.md` for coordination (shared context, ID ranges, no-overlap rules)
-- Spawn N `workflow-collab-planner` agents in parallel, each writing `.task/TASK-{NNN}.json` within assigned range
+- MUST spawn N `workflow-collab-planner` agents in parallel, each writing `.task/TASK-{NNN}.json` within assigned range
 - Merge: collect all task files, build unified plan.json with merged waves, resolve cross-planner dependencies
 
 ### Gap Mode (`--gaps`)
 
-Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 7), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
+MUST spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 7), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
 
 Planner: for each gap emit one task — `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue"); assign IDs and waves; build plan.json.
 

package/workflows/specs-setup.md

@@ -209,10 +209,106 @@ Auto-generated from project analysis. Update manually as patterns evolve.
 
 These are NOT created during setup. They are created on demand when `spec-add debug` or `spec-add review` is first used.
 
-### Step 6: Summary
+### Step 6: Generate Workflow Knowhow Recipes (when signals detected)
 
-Display list of created files with categories. Note that `debug-notes.md` and `review-standards.md` are created on demand via `/spec-add`.
+Spec files in Step 4-5 capture *conventions*. This step captures *operational workflows* — "how to do X in this project" — as **recipe-type knowhow** so future agents can discover them via `maestro wiki search` and `maestro knowhow list --type recipe`.
+
+Output directory: `.workflow/knowhow/` (knowhow store, NOT `.workflow/specs/`).
+Schema: matches `recipe` type defined in `~/.maestro/workflows/knowhow.md` Part B.
+
+**Detection → recipe matrix:**
+
+| Recipe slug | Trigger signals | Step extraction source |
+|-------------|----------------|------------------------|
+| `test-workflow` | Test framework detected in Step 5b (jest/vitest/pytest/mocha/go test/cargo test) | `package.json` `scripts.test*`, `pytest.ini`/`pyproject.toml [tool.pytest]`, `go test ./...`, test layout from Step 5b |
+| `debug-workflow` | `.vscode/launch.json` OR logging lib import (pino/winston/loguru/zap/log) OR error tracker SDK (sentry/bugsnag/rollbar) OR `DEBUG=` env usage in code | launch.json entries, `--inspect` flags in scripts, logger config files, observed `log.debug(...)` / `logger.info(...)` patterns |
+| `build-workflow` | `scripts.build` in package.json OR Makefile `build:` target OR `cargo build` OR `gradle build` OR `go build` | Verbatim script chain; multi-step pipelines noted explicitly |
+| `dev-workflow` | `scripts.dev`/`scripts.start` OR `manage.py runserver` OR `air`/`reflex` config OR docker-compose dev override | Dev command + detected port from config + hot-reload flag |
+| `lint-workflow` | Linter+formatter pair detected: eslint+prettier / ruff+black / golangci-lint+gofmt / rustfmt+clippy | Configured commands, pre-commit hooks from `.pre-commit-config.yaml` or `husky/`, CI lint job |
+
+**Skip rule:** If signals are missing, skip the recipe — do NOT generate placeholders.
+
+**Idempotency rule:** Before writing, glob `.workflow/knowhow/RCP-*-{slug}.md`. If a file matching the slug exists, do NOT overwrite — write `.workflow/knowhow/RCP-{YYYYMMDD-HHMM}-{slug}.proposed.md` instead and mention it in Step 7 summary so the user can diff and merge manually.
+
+**Filename:** `.workflow/knowhow/RCP-{YYYYMMDD-HHMM}-{slug}.md` (timestamp aligns with rest of knowhow store, slug disambiguates).
+
+**Tags rule:** Match content language (English codebase → English tags). Always include `workflow`, the slug, and the detected framework (e.g. `vitest`, `pytest`). Add `auto-generated` so users can identify spec-setup output for later pruning.
+
+**Recipe template** (one file per detected workflow):
+
+```markdown
+---
+title: "{Project name} — {Workflow name}"
+type: recipe
+tags: [workflow, {slug}, {framework}, auto-generated]
+created: {ISO timestamp}
+source: spec-setup
+---
+
+# {title}
+
+## Goal
+{One sentence stating the operational outcome — "Run the test suite locally and in CI", "Reproduce and inspect a runtime bug with full stack context", etc.}
+
+## Prerequisites
+- {Required runtime/version from manifest, e.g. "Node.js >= 18"}
+- {Required env vars detected in .env.example or code}
+- {Required services if docker-compose detected}
+
+## Steps
+1. {Copy-paste-ready command 1 — derived from detected scripts}
+2. {Command 2}
+3. ...
+
+## Expected Outcome
+{Concrete success signal — "All tests green, coverage report at coverage/index.html" / "Dev server reachable at http://localhost:PORT with HMR active"}
+
+## Common Pitfalls
+- {Inferred from detected patterns — e.g. "Vitest watch mode locks DB if integration suite is selected"}
+- {Generic gotchas: port conflicts, missing env, stale dist/}
+
+## Related
+- [[test-conventions]] / [[architecture-constraints]] — convention specs (link when they exist)
+```
+
+**Per-recipe extraction guides:**
+
+- **`test-workflow`** — Steps must list: (a) install command if first run, (b) full-suite command, (c) watch/filter command, (d) coverage command. For pytest, include marker selection if `pytest.ini` declares markers. For Go, document `-race` and `-tags` flags if used in CI.
+- **`debug-workflow`** — Steps must cover: (a) attach/launch via debugger (cite the exact `launch.json` configuration name), (b) increase log verbosity (cite the env var or config flag actually used in code), (c) reproduce-and-capture pattern (point at the project's logging entry pattern with one file:line example). Mention error-tracker DSN env if Sentry/Bugsnag SDK is wired.
+- **`build-workflow`** — Reproduce the `scripts.build` chain verbatim; if it spans multiple commands, number them. Note the output directory (`dist/`, `build/`, `target/`) and any required `prepublishOnly`/`postbuild` side effects.
+- **`dev-workflow`** — Dev server command, detected default port, hot-reload flag, and any companion process (e.g. `npm run dev` + `npm run mcp` if both are typically run together — detect this when both appear under `scripts` and one is `dev`).
+- **`lint-workflow`** — Linter command, formatter command, fix command (`--fix` / `--write`), pre-commit hook trigger if `husky/_/pre-commit` or `.pre-commit-config.yaml` exists.
+
+**Quality bar:** Every generated recipe must contain at least one runnable command. If signals are present but no concrete command can be extracted with confidence, do NOT write the file — emit `W002: <slug> signals detected but commands ambiguous, skipped` and continue.
+
+**Wiki indexing:** Files in `.workflow/knowhow/` are auto-indexed by WikiIndexer (`type=knowhow`). No separate index step required — they appear in `maestro wiki list --type knowhow` after the next index pass.
+
+### Step 7: Summary
+
+Display list of all created files grouped by destination:
+
+```
+## Specs (.workflow/specs/)
+- coding-conventions.md
+- architecture-constraints.md
+- learnings.md
+- {optional spec files created}
+
+## Workflow Recipes (.workflow/knowhow/)
+- RCP-{ts}-test-workflow.md       (vitest detected)
+- RCP-{ts}-debug-workflow.md      (pino + .vscode/launch.json detected)
+- {other recipes}
+
+## Skipped (signals missing)
+- build-workflow — no build script detected
+- {other skips}
+
+## Deferred (created on demand)
+- debug-notes.md, review-standards.md — use /spec-add when needed
+```
+
+Note that `debug-notes.md` and `review-standards.md` are created on demand via `/spec-add`, and any `.proposed.md` files indicate an existing recipe was not overwritten — review and merge manually.
 
 ## Output
 
-All files listed above under `.workflow/`.
+All files listed above under `.workflow/specs/` and `.workflow/knowhow/`.