claudecode-omc 5.6.2 → 5.6.4

package/.local/skills/conductor-distill/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: conductor-distill
+description: Distill methodology from superpowers and BMAD-METHOD docs into the active conductor track's spec.md / plan.md / review.md as intent-layer overlays. Use when user asks to "distill superpowers into conductor", "把 superpowers/bmad 提炼到 conductor", "import method docs to track", "seed conductor with brainstorming/TDD/verification gates", or "feed BMAD PRD/architecture/story/QA principles into the track". Writes only inside marker blocks so it never competes with code-derived facts and re-runs cleanly. DO NOT use for general superpowers invocation, code refactors, or to summarize this codebase.
+argument-hint: "[--track <slug>] [--source superpowers|bmad|both] [--target spec|plan|review|all] [--dry-run] [--refresh]"
+disable-model-invocation: false
+user-invocable: true
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Edit
+  - Write
+  - AskUserQuestion
+model: sonnet
+---
+
+# Conductor Distill
+
+<Purpose>
+Pull intent-layer content from external methodology docs (Anthropic superpowers, BMAD-METHOD) into the active conductor track artifacts. The skill seeds `spec.md`, `plan.md`, and `review.md` with phase gates, principles, and checklists drawn from those upstream sources, while staying out of the fact layer the code itself owns.
+</Purpose>
+
+<Use_When>
+- User asks to distill / 提炼 / import superpowers into a conductor track
+- User asks to fold BMAD agent prompts (analyst, PM, architect, dev, QA) into a track
+- A new conductor track was created and lacks methodology scaffolding
+- An existing track is drifting from the agreed gates and needs re-seeding
+</Use_When>
+
+<Do_Not_Use_When>
+- No conductor track exists yet — run `conductor setup` and `conductor track <title>` first
+- User wants to actually invoke superpowers / write code — go to those skills directly
+- User wants to summarize the local codebase or extract facts from source — that is the fact layer; this skill stays out of it
+- The conductor artifacts already contain the same blocks and the user did not ask for `--refresh`
+</Do_Not_Use_When>
+
+<Core_Invariant>
+**Conductor's intent layer is document-driven and does not compete with code for the fact layer.**
+
+This means:
+- Distilled blocks contain *methodology* (principles, gates, checklists, prompts, role expectations).
+- Distilled blocks must NOT contain claims about the local code: file names, line numbers, function bodies, test counts, config values, or any observed runtime state.
+- If a fact about the code belongs anywhere, it goes in the human-authored sections of `spec.md` / `plan.md`, not inside distilled blocks.
+- Distilled blocks are clearly fenced with markers so reviewers can tell methodology from project-specific content at a glance.
+
+If a distillation candidate would only make sense by referencing this repo's code, drop it. The intent layer is the wrong place for it.
+</Core_Invariant>
+
+<Distillation_Block_Format>
+Every distilled section is wrapped in HTML-style markers so it is idempotent and machine-replaceable:
+
+```markdown
+<!-- conductor:distilled BEGIN source=<source-id> target=<artifact> layer=intent version=YYYY-MM-DD -->
+> Source: <human-readable origin>. This block is intent-layer guidance distilled from upstream methodology and contains no claims about the local code.
+
+<distilled content here>
+
+<!-- conductor:distilled END source=<source-id> -->
+```
+
+Rules:
+- `<source-id>` is stable: e.g. `superpowers/brainstorming`, `superpowers/test-driven-development`, `bmad/agent-architect`, `bmad/template-prd`.
+- One block per source per artifact. Re-running with `--refresh` replaces the block matched by `source=` and `target=`.
+- Never nest blocks. Never split one source across multiple blocks in the same artifact.
+- Outside the markers is human / conductor / code territory and must be preserved verbatim on re-runs.
+
+See `references/distillation-blocks.md` for the full template per target artifact and the intent-only checklist used before writing each block.
+</Distillation_Block_Format>
+
+<Inputs>
+Sources (read-only, scanned at runtime):
+- `bundled/upstream/superpowers/skills/<skill>/SKILL.md` — primary superpowers source in this repo.
+- `.upstream/superpowers/skills/<skill>/SKILL.md` — fallback if the bundled copy is missing.
+- BMAD-METHOD: not vendored in this repo. Either (a) read a user-supplied local clone path, or (b) fetch via Context7 (`mcp__plugin_context7_context7__query-docs` with library `bmad-code-org/bmad-method`). Prefer (a) when available.
+
+Targets (read-write, one per active track):
+- `.omc/conductor/tracks/<slug>/spec.md`
+- `.omc/conductor/tracks/<slug>/plan.md`
+- `.omc/conductor/tracks/<slug>/review.md` (create if missing — start from a methodology-only template)
+
+Track resolution:
+- If `--track <slug>` is provided, use it.
+- Else read `.omc/conductor/conductor-state.json:activeTrack`.
+- If no active track, stop and tell the user to run conductor setup first.
+</Inputs>
+
+<Workflow>
+1. **Resolve track.** Locate active track from `conductor-state.json`. Verify `tracks/<slug>/metadata.json` exists. If not, stop with a clear "no active track" message.
+
+2. **Decide sources.** From `--source` and conversation context, pick `superpowers`, `bmad`, or `both`. If `bmad` is requested but no local clone path is known, ask the user once whether to (a) point to a clone, (b) fetch via Context7, or (c) skip BMAD this run.
+
+3. **Decide targets.** From `--target`, pick the artifacts to update. Default `all` means `spec.md`, `plan.md`, and `review.md`.
+
+4. **Load mappings.** Read `references/superpowers-mapping.md` and/or `references/bmad-mapping.md` to know which source maps to which target and what the intent-only summary should look like. If a requested source does not appear in either mapping file, skip it and report `unsupported-source: <name>` in the per-file summary rather than silently omitting it.
+
+5. **Read sources.** For each mapped source, read the upstream doc and extract only the intent-layer signal (principles, gates, checklists, role prompts, plan/spec/review structure). Apply the intent-only checklist from `references/distillation-blocks.md`. If a candidate item leaks fact-layer content, drop or rephrase it.
+
+6. **Plan writes.** For each `(source, target)` pair, build the distilled block. Compose the full block text including markers and the boilerplate `> Source:` line.
+
+7. **Dry run or apply.**
+   - If `--dry-run` (or the user did not yet authorize writes): print the per-file plan with proposed block headers and a 5-10 line preview of each block, then ask the user to confirm via `AskUserQuestion`.
+   - Otherwise apply writes.
+
+8. **Apply writes idempotently.**
+   - For each target file:
+     - If the file is missing and the target is `review.md`, create it from the review template in `references/distillation-blocks.md`.
+     - For each block to write, search for an existing `<!-- conductor:distilled BEGIN source=<source-id> target=<artifact> ... -->...<!-- conductor:distilled END source=<source-id> -->` region.
+       - If absent: append the block at the bottom under a `## Distilled Methodology` heading (create the heading if missing).
+       - If present and `--refresh` is set: replace the region in place.
+       - If present and `--refresh` is not set: skip it and report `unchanged`.
+   - Never modify content outside marker blocks.
+   - Never delete user content.
+
+9. **Report.** Output a per-file summary: which blocks were added, refreshed, skipped, or dropped (with reason). Include a final reminder that distilled blocks are intent-layer only.
+
+10. **Post-conditions.** Do not mutate `metadata.json`, `conductor-state.json`, or any code. The skill is purely a writer of methodology overlays into track artifacts.
+</Workflow>
+
+<Mapping_Summary>
+The complete tables live in `references/superpowers-mapping.md` and `references/bmad-mapping.md`. Headline routing:
+
+| Source | spec.md | plan.md | review.md |
+|--------|---------|---------|-----------|
+| superpowers/brainstorming | design-gate principles, "no implementation before approval" | — | — |
+| superpowers/writing-plans | — | plan header, file-structure section, bite-sized step granularity, header reminder | — |
+| superpowers/test-driven-development | — | red-green-refactor stages and "watch it fail" rule on each task | TDD checks |
+| superpowers/verification-before-completion | — | per-task verification command convention | evidence-before-claims checklist |
+| superpowers/systematic-debugging | — | debugging stage protocol when a phase fails | bug-bisection checklist |
+| superpowers/requesting-code-review | — | — | review-request shape |
+| superpowers/receiving-code-review | — | — | how to triage feedback before implementing |
+| superpowers/finishing-a-development-branch | — | — | branch-finish gate (merge / PR / cleanup) |
+| bmad/agent-analyst | analyst persona expectations for the spec | — | — |
+| bmad/agent-pm + bmad/template-prd | PRD section skeleton (problem, users, success metrics, non-goals) | — | — |
+| bmad/agent-architect + bmad/template-architecture | architectural-decision section skeleton, NFR prompts | — | — |
+| bmad/agent-sm + bmad/template-story | story-driven task decomposition principles | story-shaped task units | — |
+| bmad/agent-dev | dev-agent execution principles (one story at a time, evidence per change) | "per-task evidence" reminder | — |
+| bmad/agent-qa | — | — | NFR gate, risk profile, traceability checks |
+
+Each row maps to an intent-only block. None of them inject local file paths, code symbols, or test results.
+</Mapping_Summary>
+
+<Anti_Fact_Layer_Guardrails>
+Before writing each block, run the checklist in `references/distillation-blocks.md`. The short version:
+
+- The block must read as methodology even if the repo were empty.
+- The block must not name local files, symbols, branches, commits, or test counts.
+- The block must not assert the project's current behavior.
+- The block must not duplicate code that already lives in the repo.
+- If a candidate sentence fails any of the above, rewrite it as a principle or drop it.
+
+These guardrails enforce the user constraint: conductor's intent layer is document-driven and does not compete with code for the fact layer.
+</Anti_Fact_Layer_Guardrails>
+
+<Failure_Handling>
+- No conductor track: stop and tell the user to run `conductor setup` / `conductor track <title>` first.
+- Source missing (e.g., bundled superpowers absent and `.upstream/` also empty): report which source is unavailable and continue with the rest.
+- BMAD unavailable: ask once, then skip BMAD if the user declines a clone path or Context7 fetch.
+- Target file write fails: stop, report the path and error, and do not partially write.
+- Marker collision (a block with a different shape already uses the same `source=` id): refuse to write, ask the user how to resolve.
+- Detected fact-layer leakage during composition: drop the offending sentence and note it in the report rather than writing it.
+</Failure_Handling>
+
+<Examples>
+<Good>
+User: "distill superpowers into the active conductor track, dry run first"
+Action: resolve active track → plan blocks for spec/plan/review from the superpowers mapping → print preview → ask for approval before applying.
+</Good>
+
+<Good>
+User: "把 BMAD 的 PRD 和 architect 的部分塞进 spec.md，plan.md 不要动"
+Action: source=bmad, target=spec, write `bmad/agent-pm + bmad/template-prd` and `bmad/agent-architect + bmad/template-architecture` blocks into `spec.md` only.
+</Good>
+
+<Good>
+User: "refresh distilled blocks on payment-webhook-retry"
+Action: --track payment-webhook-retry --refresh, replace existing blocks in place by `source=` id, leave non-block content untouched.
+</Good>
+
+<Bad>
+User: "use superpowers TDD now to fix this bug"
+Why bad: the user wants to actually do TDD on the codebase. Route to the TDD skill, not this distiller.
+</Bad>
+
+<Bad>
+User: "summarize what our auth code does into spec.md"
+Why bad: that is fact-layer content. This skill writes methodology only. Decline and suggest a code-reading agent.
+</Bad>
+</Examples>
+
+<Final_Checklist>
+- [ ] Active conductor track resolved before any write
+- [ ] Sources confirmed available (superpowers and/or BMAD)
+- [ ] Each candidate block passed the intent-only checklist
+- [ ] Blocks fenced with the standard `conductor:distilled` markers
+- [ ] Existing blocks refreshed only when `--refresh` is set
+- [ ] No content outside markers was modified
+- [ ] No code-derived facts written into any block
+- [ ] Per-file summary printed for the user
+</Final_Checklist>

package/.local/skills/conductor-distill/references/bmad-mapping.md

@@ -0,0 +1,131 @@
+# BMAD-METHOD → Conductor Mapping
+
+Reference for `conductor-distill` when `--source bmad` (or `both`) is selected. BMAD-METHOD is not vendored in this repo, so the runtime acquires it via one of two paths:
+
+1. **Local clone** (preferred). User points to a clone of `https://github.com/bmad-code-org/BMAD-METHOD`. The skill reads files directly from disk.
+2. **Context7 fetch**. Use `mcp__plugin_context7_context7__query-docs` with library `bmad-code-org/bmad-method` to fetch the relevant agent or template, narrowed by topic.
+
+If neither is available, skip BMAD entirely and report it.
+
+All blocks produced from this file MUST satisfy the intent-only checklist in `distillation-blocks.md`. If a candidate sentence would only make sense by referencing this repo's code, drop it.
+
+---
+
+## Why BMAD maps cleanly into conductor
+
+BMAD organizes work as a sequence of agent personas (analyst → PM → architect → SM → dev → QA) plus per-stage templates. That is methodology, not facts. It maps almost 1-to-1 onto conductor's `spec → plan → implement → review` arc.
+
+Conductor's invariant — *intent layer is document-driven and does not compete with code for the fact layer* — fits BMAD because BMAD's templates are structural (sections, headings, prompts) rather than code-derived.
+
+---
+
+## bmad/agent-analyst
+
+- `source=bmad/agent-analyst`
+- targets: `spec.md`
+- extract:
+  - the analyst persona expectations: clarify problem, surface constraints, define users and success criteria before solutioning
+  - the discipline of "elicit, don't assume"
+- drop:
+  - any specific BMAD CLI invocation strings
+  - any references to BMAD's own file paths
+- output shape:
+  - "Analyst lens" prompt block: questions the spec must answer before being approved
+
+---
+
+## bmad/agent-pm + bmad/template-prd
+
+- `source=bmad/agent-pm`
+- targets: `spec.md`
+- extract from the PRD template:
+  - section skeleton: Problem, Users, Goals, Non-Goals, Success Metrics, Constraints, Risks, Open Questions
+  - the rule that every section header should have content or be explicitly marked "n/a"
+- drop:
+  - sample text from the BMAD template that names other projects
+- output shape:
+  - "PRD section skeleton" block — a header list, not pre-filled content
+
+The user fills the headers with project facts. Those facts live *outside* the distilled block. The block contains only the skeleton.
+
+---
+
+## bmad/agent-architect + bmad/template-architecture
+
+- `source=bmad/agent-architect`
+- targets: `spec.md`
+- extract:
+  - architectural-thinking prompts: boundaries, data flow, failure modes, scaling shape
+  - NFR prompts: performance, reliability, security, observability, cost
+  - "decide and record" — every architectural decision gets a one-paragraph note (problem, options considered, decision, consequences)
+- output shape:
+  - "Architecture lens" prompts list
+  - "ADR-lite shape" block
+
+Do not pre-fill ADRs with this codebase's actual decisions. The block is the prompt; the answers are human-authored outside the markers.
+
+---
+
+## bmad/agent-sm + bmad/template-story
+
+- `source=bmad/agent-sm`
+- targets: `spec.md`, `plan.md`
+- extract for `spec.md`:
+  - story-format expectations: "As a … I want … so that …"
+  - acceptance-criteria style: testable, behavior-shaped, no implementation detail
+- extract for `plan.md`:
+  - story-shaped task units: each plan task is the size of one story, with acceptance criteria attached
+  - one story in flight at a time per executor
+- output shape:
+  - `spec.md`: "Story shape" block
+  - `plan.md`: "Story-sized tasks" reminder, complementing the existing conductor `<Plan_Format>`
+
+---
+
+## bmad/agent-dev
+
+- `source=bmad/agent-dev`
+- targets: `spec.md`, `plan.md`
+- extract:
+  - dev-agent execution principles: take one story at a time, verify per change, do not silently expand scope
+  - "evidence per change" — every implementation step records what was run and what was observed
+- output shape:
+  - `spec.md`: "Implementation discipline" reminder
+  - `plan.md`: "Per-task evidence" reminder (overlaps verification-before-completion; that is fine — both come from the same principle)
+
+---
+
+## bmad/agent-qa
+
+- `source=bmad/agent-qa`
+- targets: `review.md`
+- extract:
+  - NFR gate: explicit pass/fail per non-functional requirement
+  - risk profile: what could go wrong post-merge, with mitigations
+  - traceability: each acceptance criterion ties to a check that was actually run
+- output shape:
+  - "NFR gate" table skeleton
+  - "Risk profile" prompt list
+  - "Traceability" rule
+
+---
+
+## What NOT to import from BMAD
+
+- BMAD's specific orchestration commands (e.g., its own slash commands or shell entries).
+- BMAD's example projects and sample artifacts.
+- BMAD's runtime tool definitions — they belong to BMAD's harness, not to a conductor track.
+- Any BMAD content that asserts product behavior of the local repository.
+
+If the user wants BMAD's full agent runtime, they should run BMAD itself. This skill only borrows the document-shaped methodology.
+
+---
+
+## When BMAD docs are ambiguous
+
+BMAD evolves. If a piece of upstream content can be read in two ways, prefer:
+- the *prompt-shaped* interpretation over the *automation-shaped* interpretation,
+- the *role discipline* interpretation over the *workflow plumbing* interpretation,
+- the *generalizable* interpretation over the *BMAD-internal* interpretation.
+
+When in doubt, drop it. A smaller, cleaner intent overlay beats a larger, leakier one.

package/.local/skills/conductor-distill/references/distillation-blocks.md

@@ -0,0 +1,181 @@
+# Distillation Blocks
+
+Reference for `conductor-distill`. This file defines:
+
+1. The exact marker format used to fence distilled methodology blocks.
+2. The intent-only checklist run before writing each block.
+3. The starter templates for each conductor target artifact when content is missing.
+
+---
+
+## 1. Marker format
+
+Every distilled section uses paired HTML comments so Markdown renderers ignore them and humans can spot them:
+
+```markdown
+<!-- conductor:distilled BEGIN source=<source-id> target=<artifact> layer=intent version=YYYY-MM-DD -->
+> Source: <human-readable origin>. Intent-layer guidance distilled from upstream methodology. No claims about local code.
+
+<distilled content>
+
+<!-- conductor:distilled END source=<source-id> -->
+```
+
+Field contract:
+
+- `source=` is stable across runs. Examples: `superpowers/brainstorming`, `superpowers/test-driven-development`, `bmad/agent-architect`, `bmad/template-prd`.
+- `target=` is one of `spec`, `plan`, `review`.
+- `layer=intent` is fixed. Future fact-layer overlays (if ever introduced) would use a different layer tag and a different skill.
+- `version=` is the date the block was last written/refreshed by this skill, in `YYYY-MM-DD` form.
+
+Idempotency rule:
+- One block per `(source, target)` pair per file.
+- A `--refresh` run replaces the region between matching BEGIN/END markers with the same `source=` id.
+- A non-refresh run leaves an existing block alone and reports it as `unchanged`.
+
+Boundary rule:
+- Anything outside the markers belongs to humans, conductor, or other tools. Never edit content outside markers.
+- If a project author wants to comment on a distilled block, they should do it in the surrounding human section, not inside the markers.
+
+---
+
+## 2. Intent-only checklist
+
+Run this checklist on every candidate block before writing it. If any answer is "yes" for the disqualifying questions, rewrite as a principle or drop the candidate.
+
+Disqualify if any of these are true:
+
+- The block names a file path inside this repo.
+- The block names a function, class, module, or symbol from this repo.
+- The block names a branch, commit SHA, PR number, or other VCS-specific identifier from this repo.
+- The block reports a count of tests, files, lines, or any number that came from running tools against this repo.
+- The block asserts current behavior of the local product ("our login does X").
+- The block embeds output from a command run against this repo.
+- The block could only be true for this codebase. (If you replaced the repo with an empty one, would the block still read sensibly as guidance? If no, drop it.)
+- The block duplicates code that lives in this repo.
+
+- The block pastes long verbatim passages from an upstream SKILL.md or template. Distilled blocks must paraphrase upstream guidance into principle-shaped sentences; literal copy-paste is not distillation even if the text contains no local facts. Rewrite as principles or compress to checklist bullets.
+
+Soft-flag (rewrite, do not necessarily drop):
+
+- The block uses upstream-specific paths like `docs/superpowers/...`. Generalize to `docs/specs/` or omit the path.
+- The block names upstream-specific tools by trade name where a general phrase would do. Prefer the principle.
+- The block contains DOT graphs or other heavy ASCII art. Compress to prose unless the user asked to keep it.
+
+Encourage:
+
+- Principle-shaped sentences ("X must happen before Y").
+- Checklists framed as questions ("Did you observe the failure before claiming a fix?").
+- Role expectations ("The reviewer focuses on …").
+- Section-skeletons (header lists, NFR prompts, ADR shape).
+- Phase-gate rules ("Spec is approved before plan is written").
+
+A good distilled block survives "would this still make sense for a totally different project?" with a yes.
+
+---
+
+## 3. Target artifact templates
+
+The skill writes blocks under a single `## Distilled Methodology` heading per file. If the heading is missing, create it before adding the first block.
+
+### 3.1 `spec.md`
+
+Append distilled blocks under:
+
+```markdown
+## Distilled Methodology
+
+<!-- conductor:distilled BEGIN ... -->
+...
+<!-- conductor:distilled END ... -->
+```
+
+Order of blocks (when multiple sources are written):
+1. `superpowers/brainstorming` (approval gate, design self-review)
+2. `bmad/agent-analyst` (analyst lens)
+3. `bmad/agent-pm` (PRD section skeleton)
+4. `bmad/agent-architect` (architecture lens, ADR-lite shape)
+5. `bmad/agent-sm` (story shape)
+6. `bmad/agent-dev` (implementation discipline)
+
+### 3.2 `plan.md`
+
+Append distilled blocks under:
+
+```markdown
+## Distilled Methodology
+
+<!-- conductor:distilled BEGIN ... -->
+...
+<!-- conductor:distilled END ... -->
+```
+
+Order:
+1. `superpowers/writing-plans` (header, file mapping, granularity)
+2. `superpowers/test-driven-development` (per-task TDD)
+3. `superpowers/verification-before-completion` (per-task verification)
+4. `superpowers/systematic-debugging` (failure-recovery protocol)
+5. `bmad/agent-sm` (story-sized task reminder)
+6. `bmad/agent-dev` (per-task evidence)
+
+The conductor `<Plan_Format>` defines the *phase* skeleton. Distilled blocks add discipline that applies *inside* each task. Do not rewrite the phase skeleton from the distilled side.
+
+### 3.3 `review.md`
+
+Creation policy: conductor itself initializes `review.md` at the review phase. To avoid stomping on conductor's structure:
+- If `review.md` **already exists**: append a `## Distilled Methodology` heading at the bottom (if not present) and add blocks under it. Never touch content above the heading.
+- If `review.md` **does not exist and the track phase is pre-review**: create it from the minimal template below, then add blocks.
+- If `review.md` **does not exist but track phase is already at review or later**: stop, report the missing file, and ask the user whether to create it rather than silently creating a stub that could conflict with conductor's own initialization.
+
+Minimal template (used only when creating from scratch):
+
+```markdown
+# Review
+
+> Verdict and evidence for this conductor track. Distilled methodology lives below; project-specific review notes live above the methodology heading.
+
+## Verdict
+
+_Pending._
+
+## Evidence
+
+_None yet._
+
+## Distilled Methodology
+
+<!-- distilled blocks go here -->
+```
+
+Order of blocks:
+1. `superpowers/test-driven-development` (TDD checks)
+2. `superpowers/verification-before-completion` (evidence-before-claims)
+3. `superpowers/requesting-code-review` (request shape)
+4. `superpowers/receiving-code-review` (triage feedback)
+5. `superpowers/systematic-debugging` (bisection trail, when relevant)
+6. `superpowers/finishing-a-development-branch` (branch finish gate)
+7. `bmad/agent-qa` (NFR gate, risk profile, traceability)
+
+---
+
+## 4. Block content style
+
+- Lead with one sentence stating what the block governs.
+- Use short bullets or short numbered lists. Avoid long paragraphs.
+- Prefer imperative voice ("Reproduce before forming a hypothesis.").
+- Keep each block under ~30 lines. If a source needs more, split by sub-topic only if both halves still pass the intent-only checklist; otherwise pick the higher-leverage half.
+- Always end the block with the closing marker. Always.
+
+A reader scanning the file should be able to tell, from the markers and the boilerplate `> Source:` line alone, which sentences are methodology overlay and which are project-specific.
+
+---
+
+## 5. Failure modes to refuse
+
+The skill must refuse to write a block when:
+
+- The same `source=` id already exists in the target file with a different shape and `--refresh` is not set.
+- A candidate block, after passing the intent-only checklist, would be empty.
+- The user explicitly asked for content that is fact-layer in nature (e.g., "summarize this repo's architecture into spec.md"). The skill is the wrong tool for that; recommend a code-reading agent instead.
+
+In all refusal cases, report the reason in the per-file summary and continue with the remaining writes.

package/.local/skills/conductor-distill/references/superpowers-mapping.md

@@ -0,0 +1,160 @@
+# Superpowers → Conductor Mapping
+
+Reference for `conductor-distill`. For each upstream superpowers skill listed here, this file tells the runtime:
+
+- which conductor artifact(s) it maps to
+- what to extract (intent-layer only)
+- what to drop
+- the canonical `source=` id used in distilled markers
+
+All blocks produced from this file MUST satisfy the intent-only checklist in `distillation-blocks.md`. If a candidate sentence would only make sense by referencing this repo's code, drop it.
+
+Source lookup order at runtime:
+1. `bundled/upstream/superpowers/skills/<skill>/SKILL.md`
+2. `.upstream/superpowers/skills/<skill>/SKILL.md`
+
+If neither path exists, skip the source and report it.
+
+---
+
+## brainstorming
+
+- `source=superpowers/brainstorming`
+- targets: `spec.md`
+- extract:
+  - the hard-gate rule: do not write code, scaffold, or invoke implementation skills before a design exists and the user approves it
+  - the "even simple projects need a design" anti-pattern, paraphrased as a principle
+  - the design-section approval pattern (present in sections, get approval per section)
+  - the spec self-review items: placeholders, contradictions, ambiguity, scope
+- drop:
+  - the file path `docs/superpowers/specs/...` (project-specific to upstream usage)
+  - any DOT graph (too verbose for the distilled block)
+  - mentions of specific tools by name unless they are universal
+- output shape:
+  - short "Approval gates" paragraph
+  - "Design self-review checklist" bullet list
+
+---
+
+## writing-plans
+
+- `source=superpowers/writing-plans`
+- targets: `plan.md`
+- extract:
+  - the plan-document header convention: Goal / Architecture / Tech Stack
+  - the bite-sized task granularity rule (one action per step, ~2-5 minutes)
+  - the "files map first, tasks second" principle
+  - the per-task structure: Files (Create/Modify/Test), then Steps with checkboxes
+- drop:
+  - the literal save path `docs/superpowers/plans/...`
+  - language about "agentic workers" or specific sub-skill names from upstream — generalize to "downstream executor"
+- output shape:
+  - "Plan header convention" block
+  - "File mapping before tasks" principle
+  - "Bite-sized step granularity" reminder
+
+The conductor `<Plan_Format>` already defines phased tasks with `[ ] / [~] / [x]` checkboxes. The distilled block adds the *granularity and header* discipline on top, it does not override the conductor phase structure.
+
+---
+
+## test-driven-development
+
+- `source=superpowers/test-driven-development`
+- targets: `plan.md`, `review.md`
+- extract for `plan.md`:
+  - red-green-refactor cycle as the default per-task implementation order
+  - the "watch it fail correctly" verification step
+  - the rule that production code without a failing test first is not allowed
+- extract for `review.md`:
+  - reviewer expectation: every behavior change should have a test that previously failed
+  - reviewer expectation: refactor commits should keep tests green
+- drop:
+  - the DOT cycle diagram (verbose)
+  - the "delete the code" rule worded as punishment — keep the rule but soften the framing
+- output shape:
+  - `plan.md`: "Per-task TDD order" bullet list
+  - `review.md`: "TDD checks" bullet list
+
+---
+
+## verification-before-completion
+
+- `source=superpowers/verification-before-completion`
+- targets: `plan.md`, `review.md`
+- extract:
+  - "evidence before assertions" — never claim done without a verifying command and its observed output
+  - the rule that running tests in your head does not count
+  - the rule that linters / type-checkers / test runners are the source of truth, not memory
+- output shape:
+  - `plan.md`: "Per-task verification command" reminder
+  - `review.md`: "Evidence-before-claims" checklist (ran what / observed what / where it lives)
+
+---
+
+## systematic-debugging
+
+- `source=superpowers/systematic-debugging`
+- targets: `plan.md`, `review.md`
+- extract:
+  - reproduce first, then form a hypothesis, then bisect
+  - one variable per experiment
+  - the rule that proposed fixes need a confirmed root cause, not a guess
+- output shape:
+  - `plan.md`: "If a phase fails verification" debug protocol
+  - `review.md`: "Bug bisection trail" checklist for review of bugfix tracks
+
+---
+
+## requesting-code-review
+
+- `source=superpowers/requesting-code-review`
+- targets: `review.md`
+- extract:
+  - the shape of a good review request: scope, what to focus on, what *not* to focus on, known caveats
+  - the expectation that the requester runs verification before asking for review
+- output shape:
+  - "Review request shape" section that the track owner fills in before asking for review
+
+---
+
+## receiving-code-review
+
+- `source=superpowers/receiving-code-review`
+- targets: `review.md`
+- extract:
+  - triage feedback before implementing — not every comment is a directive
+  - distinguish "questionable" from "wrong" — verify with evidence before pushing back
+  - the warning against performative agreement
+- output shape:
+  - "Receiving review feedback" checklist
+
+---
+
+## finishing-a-development-branch
+
+- `source=superpowers/finishing-a-development-branch`
+- targets: `review.md`
+- extract:
+  - the structured options at branch finish: merge / PR / cleanup
+  - the precondition: implementation complete and tests passing before deciding
+- output shape:
+  - "Branch finish gate" decision block
+
+---
+
+## subagent-driven-development / executing-plans / dispatching-parallel-agents / using-git-worktrees
+
+These are upstream *execution* skills. They are mostly fact-layer in nature (which agent runs which task) and overlap with conductor's own agent routing. Distill only when the user asks for them by name. Default behavior: skip.
+
+If asked, write a single intent-layer block summarizing:
+- "Plans drive execution; agents do not free-run"
+- "Independent tasks fan out; dependent tasks stay sequential"
+- "Use isolated worktrees when changes are large or risky"
+
+Do not list specific tools, commands, or worktree paths.
+
+---
+
+## using-superpowers / writing-skills / receiving-code-review (meta)
+
+`using-superpowers` and `writing-skills` are about authoring skills, not about doing project work. Skip by default.