@leeovery/claude-technical-workflows 2.1.10 → 2.1.12

package/README.md

@@ -44,18 +44,11 @@ Research → Discussion → Specification → Planning → Implementation → Re
 
 ### Quick Install
 
-**Marketplace** (cached globally):
-```
-/plugin marketplace add leeovery/claude-plugins-marketplace
-/plugin install claude-technical-workflows@claude-plugins-marketplace
-```
-
-**npm** (copied to your repo):
 ```bash
 npm install -D @leeovery/claude-technical-workflows
 ```
 
-See [Installation](#installation) for details and trade-offs.
+See [Installation](#installation) for details.
 
 ## How do I use it?
 
@@ -122,21 +115,11 @@ Run the skill directly or ask Claude to run it. Each gathers context from previo
 
 ## Installation
 
-| Method          | Where files live                    | Best for                                        |
-|-----------------|-------------------------------------|-------------------------------------------------|
-| **Marketplace** | `~/.claude/plugins/` (global cache) | Quick setup, don't need files in repo           |
-| **npm**         | `.claude/` in your project          | Ownership, version control, Claude Code for Web |
-
-### Option 1: Claude Marketplace
-
-```
-/plugin marketplace add leeovery/claude-plugins-marketplace
-/plugin install claude-technical-workflows@claude-plugins-marketplace
-```
-
-Skills are cached globally. They won't be available in Claude Code for Web since files aren't in your repository.
+| Method  | Where files live           | Best for                                        |
+|---------|----------------------------|-------------------------------------------------|
+| **npm** | `.claude/` in your project | Ownership, version control, Claude Code for Web |
 
-### Option 2: npm
+### npm
 
 ```bash
 npm install -D @leeovery/claude-technical-workflows

package/agents/implementation-analysis-architecture.md

@@ -0,0 +1,80 @@
+---
+name: implementation-analysis-architecture
+description: Analyzes implementation for API surface quality, module structure, integration gaps, and seam quality. Invoked by technical-implementation skill during analysis cycle.
+tools: Read, Write, Glob, Grep, Bash
+model: opus
+---
+
+# Implementation Analysis: Architecture
+
+You are reviewing the completed implementation as an architect who didn't write it. Each task executor made locally sound decisions — but nobody has evaluated whether those decisions compose well across the whole implementation. That's your job.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Implementation files** — list of files changed during implementation
+2. **Specification path** — the validated specification for design context
+3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
+4. **code-quality.md path** — quality standards
+5. **Topic name** — the implementation topic
+
+## Your Focus
+
+- API surface quality — are public interfaces clean, consistent, and well-scoped?
+- Package/module structure — is code organized logically? Are boundaries in the right places?
+- Integration test gaps — are cross-task workflows tested end-to-end?
+- Seam quality between task boundaries — do the pieces fit together cleanly?
+- Over/under-engineering — are abstractions justified by usage? Is raw code crying out for structure?
+
+## Your Process
+
+1. **Read code-quality.md** — understand quality standards
+2. **Read project skills** — understand framework conventions and architecture patterns
+3. **Read specification** — understand design intent and boundaries
+4. **Read all implementation files** — understand the full picture
+5. **Analyze architecture** — evaluate how the pieces compose as a whole
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-architecture.md`
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **No git writes** — do not commit or stage. Writing the output file is your only file write.
+2. **One concern only** — architectural quality. Do not flag duplication or spec drift.
+3. **Plan scope only** — only analyze what this implementation built. Do not flag missing features belonging to other plans.
+4. **Proportional** — focus on high-impact structural issues. Minor preferences are not worth flagging.
+5. **No new features** — only improve what exists. Never suggest adding functionality beyond what was planned.
+
+## Output File Format
+
+Write to `docs/workflow/implementation/{topic}/analysis-architecture.md`:
+
+```
+AGENT: architecture
+FINDINGS:
+- FINDING: {title}
+  SEVERITY: high | medium | low
+  FILES: {file:line, file:line}
+  DESCRIPTION: {what's wrong architecturally and why it matters}
+  RECOMMENDATION: {what to restructure/improve}
+SUMMARY: {1-3 sentences}
+```
+
+If no architectural issues found:
+
+```
+AGENT: architecture
+FINDINGS: none
+SUMMARY: Implementation architecture is sound — clean boundaries, appropriate abstractions, good seam quality.
+```
+
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: findings | clean
+FINDINGS_COUNT: {N}
+SUMMARY: {1 sentence}
+```

package/agents/implementation-analysis-duplication.md

@@ -0,0 +1,79 @@
+---
+name: implementation-analysis-duplication
+description: Analyzes implementation for cross-file duplication, near-duplicate logic, and extraction candidates. Invoked by technical-implementation skill during analysis cycle.
+tools: Read, Write, Glob, Grep, Bash
+model: opus
+---
+
+# Implementation Analysis: Duplication
+
+You are hunting for code that was independently written by separate task executors and accidentally duplicated. Each executor implemented their task in isolation — they couldn't see what other executors wrote. Your job is to find the patterns that emerged independently and now need consolidation.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Implementation files** — list of files changed during implementation
+2. **Specification path** — the validated specification for design context
+3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
+4. **code-quality.md path** — quality standards
+5. **Topic name** — the implementation topic
+
+## Your Focus
+
+- Cross-file repeated patterns (same logic in multiple files)
+- Near-duplicate logic (slightly different implementations of the same concept)
+- Helper/utility extraction candidates (inline code that belongs in a shared module)
+- Copy-paste drift across task boundaries (same pattern diverging over time)
+
+## Your Process
+
+1. **Read code-quality.md** — understand quality standards
+2. **Read project skills** — understand framework conventions and existing patterns
+3. **Read specification** — understand design intent
+4. **Read all implementation files** — build a mental map of the full codebase
+5. **Analyze for duplication** — compare patterns across files, identify extraction candidates
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-duplication.md`
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **No git writes** — do not commit or stage. Writing the output file is your only file write.
+2. **One concern only** — duplication analysis. Do not flag architecture issues, spec drift, or style problems.
+3. **Plan scope only** — only analyze files from the implementation. Do not flag duplication in pre-existing code.
+4. **Proportional** — focus on high-impact duplication. Three similar lines is not worth extracting. Three similar 20-line blocks is.
+5. **No new features** — recommend extracting/consolidating existing code only. Never suggest adding functionality.
+
+## Output File Format
+
+Write to `docs/workflow/implementation/{topic}/analysis-duplication.md`:
+
+```
+AGENT: duplication
+FINDINGS:
+- FINDING: {title}
+  SEVERITY: high | medium | low
+  FILES: {file:line, file:line}
+  DESCRIPTION: {what's duplicated and why it matters}
+  RECOMMENDATION: {what to extract/consolidate and where}
+SUMMARY: {1-3 sentences}
+```
+
+If no duplication found:
+
+```
+AGENT: duplication
+FINDINGS: none
+SUMMARY: No significant duplication detected across implementation files.
+```
+
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: findings | clean
+FINDINGS_COUNT: {N}
+SUMMARY: {1 sentence}
+```

package/agents/implementation-analysis-standards.md

@@ -0,0 +1,79 @@
+---
+name: implementation-analysis-standards
+description: Analyzes implementation for specification conformance and project convention compliance. Invoked by technical-implementation skill during analysis cycle.
+tools: Read, Write, Glob, Grep, Bash
+model: opus
+---
+
+# Implementation Analysis: Standards
+
+You are the specification's advocate. Find where the implementation drifts from what was decided. Each task executor saw only their slice of the spec — you see the whole picture and can spot where individual interpretations diverged from the collective intent.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Implementation files** — list of files changed during implementation
+2. **Specification path** — the validated specification for design context
+3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
+4. **code-quality.md path** — quality standards
+5. **Topic name** — the implementation topic
+
+## Your Focus
+
+- Spec conformance — does the implementation match what the specification decided?
+- Project skill MUST DO / MUST NOT DO compliance
+- Spec-vs-convention conflicts — when the spec conflicts with a language idiom or project convention, which won? Was the right choice made?
+- Missing validations or constraints from the spec
+
+## Your Process
+
+1. **Read specification thoroughly** — absorb all decisions, constraints, and rationale
+2. **Read project skills** — understand MUST DO / MUST NOT DO rules
+3. **Read code-quality.md** — understand quality standards
+4. **Read all implementation files** — map each file back to its spec requirements
+5. **Compare implementation against spec** — check every decision point
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-standards.md`
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **No git writes** — do not commit or stage. Writing the output file is your only file write.
+2. **One concern only** — spec and standards conformance. Do not flag duplication or architecture issues.
+3. **Plan scope only** — only analyze files from the implementation against the current spec.
+4. **Proportional** — focus on high-impact drift. A minor naming preference is not worth flagging. A missing validation from the spec is.
+5. **No new features** — only flag where existing code diverges from what was specified. Never suggest adding unspecified functionality.
+
+## Output File Format
+
+Write to `docs/workflow/implementation/{topic}/analysis-standards.md`:
+
+```
+AGENT: standards
+FINDINGS:
+- FINDING: {title}
+  SEVERITY: high | medium | low
+  FILES: {file:line, file:line}
+  DESCRIPTION: {what drifted from spec or conventions and why it matters}
+  RECOMMENDATION: {what to change to align with spec/conventions}
+SUMMARY: {1-3 sentences}
+```
+
+If no standards drift found:
+
+```
+AGENT: standards
+FINDINGS: none
+SUMMARY: Implementation conforms to specification and project conventions.
+```
+
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: findings | clean
+FINDINGS_COUNT: {N}
+SUMMARY: {1 sentence}
+```

package/agents/implementation-analysis-synthesizer.md

@@ -0,0 +1,104 @@
+---
+name: implementation-analysis-synthesizer
+description: Synthesizes analysis findings into normalized tasks. Reads findings files, deduplicates, groups, normalizes using task template, and writes a staging file for orchestrator approval. Invoked by technical-implementation skill after analysis agents complete.
+tools: Read, Write, Glob, Grep
+model: opus
+---
+
+# Implementation Analysis: Synthesizer
+
+You locate the analysis findings files written by the analysis agents using the topic name, then read them, deduplicate and group findings, normalize into tasks, and write a staging file for user approval.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Task normalization reference path** — canonical task template
+2. **Topic name** — the implementation topic
+3. **Cycle number** — which analysis cycle this is
+4. **Specification path** — the validated specification
+
+## Your Process
+
+1. **Read all findings files** from `docs/workflow/implementation/{topic}/` — look for `analysis-duplication.md`, `analysis-standards.md`, and `analysis-architecture.md`
+2. **Deduplicate** — same issue found by multiple agents → one finding, note all sources
+3. **Group related findings** — multiple findings about the same pattern become one task (e.g., 3 duplication findings about the same helper pattern = 1 "extract helper" task)
+4. **Filter** — discard low-severity findings unless they cluster into a pattern. Never discard high-severity.
+5. **Normalize** — convert each group into a task using the canonical task template (Problem / Solution / Outcome / Do / Acceptance Criteria / Tests)
+6. **Write report** — output to `docs/workflow/implementation/{topic}/analysis-report.md`
+7. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/analysis-tasks.md` with `status: pending` for each task
+
+## Report Format
+
+Write the report file with this structure:
+
+```markdown
+---
+topic: {topic}
+cycle: {N}
+total_findings: {N}
+deduplicated_findings: {N}
+proposed_tasks: {N}
+---
+# Analysis Report: {Topic} (Cycle {N})
+
+## Summary
+{2-3 sentence overview of findings}
+
+## Discarded Findings
+- {title} — {reason for discarding}
+```
+
+## Staging File Format
+
+Write the staging file with this structure:
+
+```markdown
+---
+topic: {topic}
+cycle: {N}
+total_proposed: {N}
+---
+# Analysis Tasks: {Topic} (Cycle {N})
+
+## Task 1: {title}
+status: pending
+severity: high
+sources: duplication, architecture
+
+**Problem**: {what's wrong}
+**Solution**: {what to do}
+**Outcome**: {what success looks like}
+**Do**: {step-by-step implementation instructions}
+**Acceptance Criteria**:
+- {criterion}
+**Tests**:
+- {test description}
+
+## Task 2: {title}
+status: pending
+...
+```
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **No new features** — only improve existing implementation. Every proposed task must address something that already exists.
+2. **Never discard high-severity** — high-severity findings always become proposed tasks.
+3. **Self-contained tasks** — every proposed task must be independently executable. No task should depend on another proposed task.
+4. **Faithful synthesis** — do not invent findings. Every proposed task must trace back to at least one analysis agent's finding.
+5. **No git writes** — do not commit or stage. Writing the report and staging files are your only file writes.
+
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: tasks_proposed | clean
+TASKS_PROPOSED: {N}
+SUMMARY: {1-2 sentences}
+```
+
+- `tasks_proposed`: tasks written to staging file — orchestrator should present for approval
+- `clean`: no actionable findings — orchestrator should proceed to completion

package/agents/implementation-analysis-task-writer.md

@@ -0,0 +1,48 @@
+---
+name: implementation-analysis-task-writer
+description: Creates plan tasks from approved analysis findings. Reads the staging file, extracts approved tasks, and creates them in the plan using the format's authoring adapter. Invoked by technical-implementation skill after user approves analysis tasks.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: opus
+---
+
+# Implementation Analysis: Task Writer
+
+You receive the path to a staging file containing approved analysis tasks. Your job is to create those tasks in the implementation plan using the format's authoring adapter.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Topic name** — the implementation topic (used to scope tasks to the correct plan)
+2. **Staging file path** — path to the staging file with approved tasks
+3. **Plan path** — the implementation plan path
+4. **Plan format reading adapter path** — how to read tasks from the plan (for determining next phase number)
+5. **Plan format authoring adapter path** — how to create tasks in the plan
+
+## Your Process
+
+1. **Read the staging file** — extract all tasks with `status: approved`
+2. **Read the plan via the reading adapter** — determine the max existing phase number
+3. **Calculate next phase number** — max existing phase + 1
+4. **Read the authoring adapter** — understand how to create tasks in this format
+5. **Create tasks in the plan** — follow the authoring adapter's instructions for each approved task, using the topic name to scope tasks to this plan (e.g., directory paths, task ID prefixes, project association)
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **Approved only** — only create tasks with `status: approved`. Never create tasks that are `pending` or `skipped`.
+2. **No content modifications** — create tasks exactly as they appear in the staging file. Do not rewrite, reorder, or embellish.
+3. **No git writes** — do not commit or stage. Writing plan task files/entries are your only writes.
+4. **Authoring adapter is authoritative** — follow its instructions for task file structure, naming, and format.
+
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: complete
+TASKS_CREATED: {N}
+PHASE: {N}
+SUMMARY: {1 sentence}
+```

package/agents/implementation-task-executor.md

@@ -1,6 +1,6 @@
 ---
 name: implementation-task-executor
-description: Implements a single plan task via strict TDD. Invoked by technical-implementation skill for each task.
+description: Implements a single task via strict TDD. Invoked by technical-implementation skill for each task.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: opus
 ---
@@ -18,10 +18,11 @@ You receive file paths and context via the orchestrator's prompt:
 3. **Specification path** — For context when rationale is unclear
 4. **Project skill paths** — Relevant `.claude/skills/` paths for framework conventions
 5. **Task content** — Task ID, phase, and all instructional content: goal, implementation steps, acceptance criteria, tests, edge cases, context, notes. This is your scope.
+6. **Linter commands** (if configured) — linter commands to run after refactoring
 
 On **re-invocation after review feedback**, you receive all of the above, plus:
-6. **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
-7. **Specific issues to address**
+7. **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
+8. **Specific issues to address**
 
 You are stateless — each invocation starts fresh. The full task content is always provided so you can see what was asked, what was done, and what needs fixing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.10",
+  "version": "2.1.12",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/migrate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: migrate
 description: "Run migrations to keep workflow files in sync with the current system design. This skill is mandatory before running any workflow skill."
-allowed-tools: Bash(./scripts/migrate.sh)
+allowed-tools: Bash(.claude/skills/migrate/scripts/migrate.sh)
 ---
 
 # Migrate
@@ -13,7 +13,7 @@ Keeps your workflow files up to date with how the system is designed to work. Ru
 Run the migration script:
 
 ```bash
-./scripts/migrate.sh
+.claude/skills/migrate/scripts/migrate.sh
 ```
 
 ### If files were updated

package/skills/start-discussion/SKILL.md

@@ -2,7 +2,7 @@
 name: start-discussion
 description: "Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill."
 disable-model-invocation: true
-allowed-tools: Bash(./scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
+allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-discussion/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-./scripts/discovery.sh
+.claude/skills/start-discussion/scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `research` section:**
 - `exists` - whether research files exist

package/skills/start-implementation/SKILL.md

@@ -2,7 +2,7 @@
 name: start-implementation
 description: "Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill."
 disable-model-invocation: true
-allowed-tools: Bash(./scripts/discovery.sh)
+allowed-tools: Bash(.claude/skills/start-implementation/scripts/discovery.sh)
 ---
 
 Invoke the **technical-implementation** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-implementation/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-./scripts/discovery.sh
+.claude/skills/start-implementation/scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist

package/skills/start-planning/SKILL.md

@@ -2,7 +2,7 @@
 name: start-planning
 description: "Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill."
 disable-model-invocation: true
-allowed-tools: Bash(./scripts/discovery.sh)
+allowed-tools: Bash(.claude/skills/start-planning/scripts/discovery.sh)
 ---
 
 Invoke the **technical-planning** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-planning/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-./scripts/discovery.sh
+.claude/skills/start-planning/scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `specifications` section:**
 - `exists` - whether any specifications exist

package/skills/start-review/SKILL.md

@@ -2,7 +2,7 @@
 name: start-review
 description: "Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill."
 disable-model-invocation: true
-allowed-tools: Bash(./scripts/discovery.sh)
+allowed-tools: Bash(.claude/skills/start-review/scripts/discovery.sh)
 ---
 
 Invoke the **technical-review** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-review/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-./scripts/discovery.sh
+.claude/skills/start-review/scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist

package/skills/start-specification/SKILL.md

@@ -2,7 +2,7 @@
 name: start-specification
 description: "Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
 disable-model-invocation: true
-allowed-tools: Bash(./scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
+allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
 ---
 
 Invoke the **technical-specification** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-specification/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-./scripts/discovery.sh
+.claude/skills/start-specification/scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `discussions` array:**
 - Each discussion's name, status, and whether it has an individual specification