codeply-cli 0.5.5 → 0.6.0

package/skills/orch-build-mvp/SKILL.md

@@ -1,49 +1,49 @@
----
-name: orch-build-mvp
-description: Orchestrate bootstrapping a working MVP from a design or spec document — ingest the doc, plan thin vertical slices, scaffold the first end-to-end slice, then TDD-implement, review, and gated commit. Use to turn an SDD/PRD into a running starting point.
-metadata:
-  origin: ECC
----
-
-# orch-build-mvp
-
-Actor · action · target: **orch · build · mvp**. Thin wrapper over the shared
-engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
-
-## When to Use
-
-- The user has a **design / spec document** (SDD, PRD, system_design) and wants a
-  working vertical slice bootstrapped from it.
-- Takes a doc path as its argument, e.g. `civicpulse/docs/SDD-v0.6.md`.
-
-## Operation settings
-
-- **Default size floor:** large — this is the full pipeline including Scaffold.
-- **Phase mask:** 0 (read the spec) → 1 → 2 (heavy) → 3 (scaffold) → 4 → 5 → 6.
-- **First move (phase 0 → 2):** read the doc; extract scope, locked decisions,
-  and the feature list; order it into **thin vertical slices** (one end-to-end
-  path first, not all-models-then-all-views). Phase 3 stands up that first slice.
-
-## How It Works
-
-1. Run the `orch-pipeline` engine with the settings above.
-2. **Reuse the existing GAN harness** instead of hand-rolling an iterate loop:
-   - Translate the SDD into `gan-harness/spec.md` + `gan-harness/eval-rubric.md`
-     (this stands in for what `gan-planner` would generate — you already have the spec).
-   - Drive the build with `/gan-build "<one-line brief>" --skip-planner`
-     (defaults: `--max-iterations 15`, `--pass-threshold 7.0`,
-     `--eval-mode playwright`; use `--eval-mode code-only` for non-UI slices).
-   - That command runs the `gan-generator` → `gan-evaluator` loop and writes
-     `gan-harness/feedback/feedback-NNN.md` until the score passes or plateaus.
-3. Stop at **Gate 1** (slice plan) and **Gate 2** (pre-commit). Commit the
-   scaffold and each slice as separate `feat:` commits.
-4. Add `security-reviewer` for any slice touching a security trigger.
-
-## Example
-
-```
-orch-build-mvp: civicpulse/docs/SDD-v0.6.md
-→ read SDD → slice list (vertical) → scaffold slice 1  [GATE 1: approve]
-→ /gan-build --skip-planner (generator → evaluator loop) scores vs spec → review
-→ commit feat:  [GATE 2: confirm] → next slice
-```
+---
+name: orch-build-mvp
+description: Orchestrate bootstrapping a working MVP from a design or spec document — ingest the doc, plan thin vertical slices, scaffold the first end-to-end slice, then TDD-implement, review, and gated commit. Use to turn an SDD/PRD into a running starting point.
+metadata:
+  origin: ECC
+---
+
+# orch-build-mvp
+
+Actor · action · target: **orch · build · mvp**. Thin wrapper over the shared
+engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
+
+## When to Use
+
+- The user has a **design / spec document** (SDD, PRD, system_design) and wants a
+  working vertical slice bootstrapped from it.
+- Takes a doc path as its argument, e.g. `civicpulse/docs/SDD-v0.6.md`.
+
+## Operation settings
+
+- **Default size floor:** large — this is the full pipeline including Scaffold.
+- **Phase mask:** 0 (read the spec) → 1 → 2 (heavy) → 3 (scaffold) → 4 → 5 → 6.
+- **First move (phase 0 → 2):** read the doc; extract scope, locked decisions,
+  and the feature list; order it into **thin vertical slices** (one end-to-end
+  path first, not all-models-then-all-views). Phase 3 stands up that first slice.
+
+## How It Works
+
+1. Run the `orch-pipeline` engine with the settings above.
+2. **Reuse the existing GAN harness** instead of hand-rolling an iterate loop:
+   - Translate the SDD into `gan-harness/spec.md` + `gan-harness/eval-rubric.md`
+     (this stands in for what `gan-planner` would generate — you already have the spec).
+   - Drive the build with `/gan-build "<one-line brief>" --skip-planner`
+     (defaults: `--max-iterations 15`, `--pass-threshold 7.0`,
+     `--eval-mode playwright`; use `--eval-mode code-only` for non-UI slices).
+   - That command runs the `gan-generator` → `gan-evaluator` loop and writes
+     `gan-harness/feedback/feedback-NNN.md` until the score passes or plateaus.
+3. Stop at **Gate 1** (slice plan) and **Gate 2** (pre-commit). Commit the
+   scaffold and each slice as separate `feat:` commits.
+4. Add `security-reviewer` for any slice touching a security trigger.
+
+## Example
+
+```
+orch-build-mvp: civicpulse/docs/SDD-v0.6.md
+→ read SDD → slice list (vertical) → scaffold slice 1  [GATE 1: approve]
+→ /gan-build --skip-planner (generator → evaluator loop) scores vs spec → review
+→ commit feat:  [GATE 2: confirm] → next slice
+```

package/skills/orch-change-feature/SKILL.md

@@ -1,43 +1,43 @@
----
-name: orch-change-feature
-description: Orchestrate altering an existing, working feature to new desired behavior — update its tests to the new spec, change the implementation to match, review, and gated commit. Use when behavior is not broken but should be different.
-metadata:
-  origin: ECC
----
-
-# orch-change-feature
-
-Actor · action · target: **orch · change · feature**. Thin wrapper over the
-shared engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
-
-## When to Use
-
-- An existing feature **works**, but the desired behavior is different ("change",
-  "adjust", "make it also …", "instead of X do Y").
-- Distinguish from siblings:
-  - **not** broken → not `orch-fix-defect` (no bug to reproduce).
-  - **not** new → not `orch-add-feature` (the capability already exists).
-
-## Operation settings
-
-- **Default size floor:** small — most tweaks are a function or two.
-- **Phase mask:** 0 → (1 only if the new behavior needs research) → light 2 →
-  4 → 5 → 6.
-- **First move (phase 4):** update the *existing* tests to express the new
-  desired behavior, then change the implementation until they pass. Changing the
-  tests first is what separates a tweak from a fix.
-
-## How It Works
-
-1. Run the `orch-pipeline` engine with the settings above.
-2. Keep the plan light — only `standard`+ size warrants the full `planner` pass.
-3. Stop at **Gate 1** (plan / changed-test approval) and **Gate 2** (pre-commit).
-4. Add `security-reviewer` if the change touches a security trigger.
-
-## Example
-
-```
-orch-change-feature: make nws-poller alert at 2 warnings instead of 3
-→ update threshold tests to new spec → change impl to green
-→ code-review → commit  [GATE 2: confirm]
-```
+---
+name: orch-change-feature
+description: Orchestrate altering an existing, working feature to new desired behavior — update its tests to the new spec, change the implementation to match, review, and gated commit. Use when behavior is not broken but should be different.
+metadata:
+  origin: ECC
+---
+
+# orch-change-feature
+
+Actor · action · target: **orch · change · feature**. Thin wrapper over the
+shared engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
+
+## When to Use
+
+- An existing feature **works**, but the desired behavior is different ("change",
+  "adjust", "make it also …", "instead of X do Y").
+- Distinguish from siblings:
+  - **not** broken → not `orch-fix-defect` (no bug to reproduce).
+  - **not** new → not `orch-add-feature` (the capability already exists).
+
+## Operation settings
+
+- **Default size floor:** small — most tweaks are a function or two.
+- **Phase mask:** 0 → (1 only if the new behavior needs research) → light 2 →
+  4 → 5 → 6.
+- **First move (phase 4):** update the *existing* tests to express the new
+  desired behavior, then change the implementation until they pass. Changing the
+  tests first is what separates a tweak from a fix.
+
+## How It Works
+
+1. Run the `orch-pipeline` engine with the settings above.
+2. Keep the plan light — only `standard`+ size warrants the full `planner` pass.
+3. Stop at **Gate 1** (plan / changed-test approval) and **Gate 2** (pre-commit).
+4. Add `security-reviewer` if the change touches a security trigger.
+
+## Example
+
+```
+orch-change-feature: make nws-poller alert at 2 warnings instead of 3
+→ update threshold tests to new spec → change impl to green
+→ code-review → commit  [GATE 2: confirm]
+```

package/skills/orch-fix-defect/SKILL.md

@@ -1,43 +1,43 @@
----
-name: orch-fix-defect
-description: Orchestrate fixing a bug — reproduce it as a failing regression test, fix to green, review, and gated commit — by delegating each phase to the matching ECC agent. Use when existing behavior is broken or wrong.
-metadata:
-  origin: ECC
----
-
-# orch-fix-defect
-
-Actor · action · target: **orch · fix · defect**. Thin wrapper over the shared
-engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
-
-## When to Use
-
-- Something is **broken**: wrong output, an error, a crash, a regression.
-- Distinguish from siblings:
-  - behavior is correct but you want it different → `orch-change-feature`.
-  - the capability does not exist yet → `orch-add-feature`.
-
-## Operation settings
-
-- **Default size floor:** small (often trivial).
-- **Phase mask:** 0 → (light 2 only if root cause is non-obvious or standard+) →
-  4 → 5 → 6. Research (1) is usually skipped.
-- **First move (phase 4):** reproduce the bug as a **new failing** test
-  (regression test), then fix until it goes green. Proving the bug exists first
-  is what separates a fix from a tweak.
-
-## How It Works
-
-1. Run the `orch-pipeline` engine with the settings above.
-2. If the root cause is unclear, scope it with `code-explorer` before the red
-   test; escalate build breaks to `build-error-resolver` / `/build-fix`.
-3. Stop at **Gate 1** (only if a plan was produced) and **Gate 2** (pre-commit).
-4. Add `security-reviewer` if the defect sits in a security-sensitive path.
-
-## Example
-
-```
-orch-fix-defect: poller crashes on empty NWS response
-→ write failing test reproducing the crash → fix to green
-→ code-review → commit  [GATE 2: confirm]   (commit: fix:)
-```
+---
+name: orch-fix-defect
+description: Orchestrate fixing a bug — reproduce it as a failing regression test, fix to green, review, and gated commit — by delegating each phase to the matching ECC agent. Use when existing behavior is broken or wrong.
+metadata:
+  origin: ECC
+---
+
+# orch-fix-defect
+
+Actor · action · target: **orch · fix · defect**. Thin wrapper over the shared
+engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
+
+## When to Use
+
+- Something is **broken**: wrong output, an error, a crash, a regression.
+- Distinguish from siblings:
+  - behavior is correct but you want it different → `orch-change-feature`.
+  - the capability does not exist yet → `orch-add-feature`.
+
+## Operation settings
+
+- **Default size floor:** small (often trivial).
+- **Phase mask:** 0 → (light 2 only if root cause is non-obvious or standard+) →
+  4 → 5 → 6. Research (1) is usually skipped.
+- **First move (phase 4):** reproduce the bug as a **new failing** test
+  (regression test), then fix until it goes green. Proving the bug exists first
+  is what separates a fix from a tweak.
+
+## How It Works
+
+1. Run the `orch-pipeline` engine with the settings above.
+2. If the root cause is unclear, scope it with `code-explorer` before the red
+   test; escalate build breaks to `build-error-resolver` / `/build-fix`.
+3. Stop at **Gate 1** (only if a plan was produced) and **Gate 2** (pre-commit).
+4. Add `security-reviewer` if the defect sits in a security-sensitive path.
+
+## Example
+
+```
+orch-fix-defect: poller crashes on empty NWS response
+→ write failing test reproducing the crash → fix to green
+→ code-review → commit  [GATE 2: confirm]   (commit: fix:)
+```

package/skills/orch-pipeline/SKILL.md

@@ -1,121 +1,121 @@
----
-name: orch-pipeline
-description: Shared orchestration engine for the orch-* skill family. Defines the gated Research-Plan-TDD-Review-Commit pipeline, the size classifier, the agent map, and the two human gates that the orch-* operation skills delegate to. Not usually invoked directly.
-metadata:
-  origin: ECC
----
-
-# Orchestrator Pipeline (shared engine)
-
-The `orch-*` skills are thin wrappers. They do not re-implement any work — they
-classify the request, choose which phases of *this* pipeline run, and delegate
-each phase to an existing ECC agent or command. This file is that pipeline.
-
-> Invoke an operation skill (`orch-add-feature`, `orch-fix-defect`, …) rather
-> than this engine directly. This file is the reference they point at.
-
-## When to Use
-
-- Loaded indirectly whenever an `orch-*` operation skill runs.
-- Read directly only when adding a new operation to the family or tuning the
-  shared phases, gates, or agent map.
-
-## The operation family
-
-| Skill | Operation | Trigger | First move |
-|-------|-----------|---------|------------|
-| `orch-add-feature` | feature | capability does not exist yet | research + plan a new slice |
-| `orch-change-feature` | tweak | works, but desired behavior differs | amend existing behavior *and its tests* |
-| `orch-fix-defect` | fix | broken; behavior is wrong | reproduce as a failing test, then fix |
-| `orch-refine-code` | refactor | behavior stays, structure improves | restructure while keeping tests green |
-| `orch-build-mvp` | mvp | bootstrap from a design/spec doc | ingest doc → vertical slices |
-
-> These wrappers **compose** existing ECC commands rather than replace them:
-> `/feature-dev`, `/plan`, `/code-review`, `/build-fix`, `/refactor-clean`, and
-> `/gan-build`, plus the `tdd-workflow` skill. The orch-* family adds the shared
-> size classifier and the two gates
-> on top of them, so one umbrella covers all five operations consistently.
-
-## Step 0 — Classify size (right-sizing)
-
-Ceremony scales to blast radius. Score the request on three signals, take the
-**highest** tier any signal reaches, and state the result in one line so the user
-can override:
-
-| Tier | Files touched | New dependency / contract | Design ambiguity | Phases that run |
-|------|---------------|---------------------------|------------------|-----------------|
-| trivial | 1, a few lines | none | none — the change is obvious | 4 → 5 → 6 |
-| small | 1 file / 1 function | none | clear once you read the code | (1 light) → 4 → 5 → 6 |
-| standard | 2–5 files | maybe a new internal module | one real choice to make | 1 → 2 → 4 → 5 → 6 |
-| large | many / cross-cutting | new external dep, public API, or a spec doc | multiple open questions | 1 → 2 → (3) → 4 → 5 → 6 |
-
-Phase 0 (Intake) always runs and is omitted from the mask column above. The
-tie-breaker: anything touching a security trigger (below) or a public API /
-contract is **at least** standard, regardless of file count.
-
-## The phases
-
-Each phase delegates — it does not do the work inline.
-
-- **0. Intake** — restate the request. For `orch-build-mvp`, read the spec/design
-  doc and extract scope, locked decisions, and a feature list.
-- **1. Research & Reuse** — per `rules/common/development-workflow.md`: `gh search repos` /
-  `gh search code`, then Context7 / vendor docs, then package registries, then
-  Exa. Prefer adopting a proven implementation over net-new code.
-- **2. Plan** — delegate to the `planner` agent (or `architect` /
-  `code-architect` for structural decisions). Output a `task_list` ordered as
-  thin vertical slices. → **GATE 1.**
-- **3. Scaffold** — `orch-build-mvp` only: stand up the first end-to-end slice.
-- **4. Implement (TDD)** — drive each task through the `tdd-guide` agent (or the `tdd-workflow` skill):
-  red → green → refactor. Honor the operation's first-move rule.
-- **5. Review** — `code-reviewer` agent / `/code-review`. Add `security-reviewer`
-  whenever the diff touches a security trigger (below).
-- **6. Commit** — conventional commits (`feat:` / `fix:` / `refactor:` / …), one
-  per logical chunk. → **GATE 2.**
-
-## The two gates
-
-This family is **gated, not autonomous**:
-
-1. **GATE 1 — after Plan.** Present the `task_list`; do not write implementation
-   code until the user approves.
-2. **GATE 2 — before Commit.** Present the diff summary and proposed messages;
-   do not commit until the user confirms.
-
-Everything between the gates flows without stopping.
-
-## Agent / command map
-
-| Phase | Primary | Fallback / escalation |
-|-------|---------|----------------------|
-| Intake / understand | `code-explorer` | trace existing paths before a tweak, fix, or refactor |
-| Plan | `planner` | `architect`, `code-architect` for structural calls |
-| Implement | `tdd-guide` (or `tdd-workflow` skill) | `build-error-resolver` / `/build-fix` on build breaks |
-| Review | `code-reviewer` / `/code-review` | language reviewer (`python-reviewer`, `typescript-reviewer`, …) |
-| Security | `security-reviewer` | — |
-| MVP inner loop | `/gan-build "<brief>" --skip-planner` | drives `gan-generator` → `gan-evaluator`; tune `--max-iterations` / `--pass-threshold` |
-
-Match the language reviewer to the repo (see the repo's own `CLAUDE.md`).
-
-## Security-review trigger
-
-Pull in `security-reviewer` when the diff touches any of: authentication or
-authorization, user-input handling, database queries, file-system paths,
-external API calls, cryptography, or secrets / credentials. (Per `rules/common/security.md`.)
-
-## Handoff artifacts
-
-The pipeline carries no hidden state — the planning docs *are* the handoff:
-
-- `task_list` (from Plan) drives the Implement loop.
-- Larger work may also emit PRD / architecture / system_design under the repo's
-  `docs/` per `rules/common/development-workflow.md`.
-- Review findings (CRITICAL / HIGH) must be resolved before Gate 2.
-
-## Verification
-
-- size tier was stated and matched the work
-- Gate 1 (plan) and Gate 2 (commit) were both honored
-- `security-reviewer` ran iff a security trigger was touched
-- commits are conventional and scoped to one logical change
-- new / changed behavior has tests; coverage ≥ 80% per `rules/common/testing.md`
+---
+name: orch-pipeline
+description: Shared orchestration engine for the orch-* skill family. Defines the gated Research-Plan-TDD-Review-Commit pipeline, the size classifier, the agent map, and the two human gates that the orch-* operation skills delegate to. Not usually invoked directly.
+metadata:
+  origin: ECC
+---
+
+# Orchestrator Pipeline (shared engine)
+
+The `orch-*` skills are thin wrappers. They do not re-implement any work — they
+classify the request, choose which phases of *this* pipeline run, and delegate
+each phase to an existing ECC agent or command. This file is that pipeline.
+
+> Invoke an operation skill (`orch-add-feature`, `orch-fix-defect`, …) rather
+> than this engine directly. This file is the reference they point at.
+
+## When to Use
+
+- Loaded indirectly whenever an `orch-*` operation skill runs.
+- Read directly only when adding a new operation to the family or tuning the
+  shared phases, gates, or agent map.
+
+## The operation family
+
+| Skill | Operation | Trigger | First move |
+|-------|-----------|---------|------------|
+| `orch-add-feature` | feature | capability does not exist yet | research + plan a new slice |
+| `orch-change-feature` | tweak | works, but desired behavior differs | amend existing behavior *and its tests* |
+| `orch-fix-defect` | fix | broken; behavior is wrong | reproduce as a failing test, then fix |
+| `orch-refine-code` | refactor | behavior stays, structure improves | restructure while keeping tests green |
+| `orch-build-mvp` | mvp | bootstrap from a design/spec doc | ingest doc → vertical slices |
+
+> These wrappers **compose** existing ECC commands rather than replace them:
+> `/feature-dev`, `/plan`, `/code-review`, `/build-fix`, `/refactor-clean`, and
+> `/gan-build`, plus the `tdd-workflow` skill. The orch-* family adds the shared
+> size classifier and the two gates
+> on top of them, so one umbrella covers all five operations consistently.
+
+## Step 0 — Classify size (right-sizing)
+
+Ceremony scales to blast radius. Score the request on three signals, take the
+**highest** tier any signal reaches, and state the result in one line so the user
+can override:
+
+| Tier | Files touched | New dependency / contract | Design ambiguity | Phases that run |
+|------|---------------|---------------------------|------------------|-----------------|
+| trivial | 1, a few lines | none | none — the change is obvious | 4 → 5 → 6 |
+| small | 1 file / 1 function | none | clear once you read the code | (1 light) → 4 → 5 → 6 |
+| standard | 2–5 files | maybe a new internal module | one real choice to make | 1 → 2 → 4 → 5 → 6 |
+| large | many / cross-cutting | new external dep, public API, or a spec doc | multiple open questions | 1 → 2 → (3) → 4 → 5 → 6 |
+
+Phase 0 (Intake) always runs and is omitted from the mask column above. The
+tie-breaker: anything touching a security trigger (below) or a public API /
+contract is **at least** standard, regardless of file count.
+
+## The phases
+
+Each phase delegates — it does not do the work inline.
+
+- **0. Intake** — restate the request. For `orch-build-mvp`, read the spec/design
+  doc and extract scope, locked decisions, and a feature list.
+- **1. Research & Reuse** — per `rules/common/development-workflow.md`: `gh search repos` /
+  `gh search code`, then Context7 / vendor docs, then package registries, then
+  Exa. Prefer adopting a proven implementation over net-new code.
+- **2. Plan** — delegate to the `planner` agent (or `architect` /
+  `code-architect` for structural decisions). Output a `task_list` ordered as
+  thin vertical slices. → **GATE 1.**
+- **3. Scaffold** — `orch-build-mvp` only: stand up the first end-to-end slice.
+- **4. Implement (TDD)** — drive each task through the `tdd-guide` agent (or the `tdd-workflow` skill):
+  red → green → refactor. Honor the operation's first-move rule.
+- **5. Review** — `code-reviewer` agent / `/code-review`. Add `security-reviewer`
+  whenever the diff touches a security trigger (below).
+- **6. Commit** — conventional commits (`feat:` / `fix:` / `refactor:` / …), one
+  per logical chunk. → **GATE 2.**
+
+## The two gates
+
+This family is **gated, not autonomous**:
+
+1. **GATE 1 — after Plan.** Present the `task_list`; do not write implementation
+   code until the user approves.
+2. **GATE 2 — before Commit.** Present the diff summary and proposed messages;
+   do not commit until the user confirms.
+
+Everything between the gates flows without stopping.
+
+## Agent / command map
+
+| Phase | Primary | Fallback / escalation |
+|-------|---------|----------------------|
+| Intake / understand | `code-explorer` | trace existing paths before a tweak, fix, or refactor |
+| Plan | `planner` | `architect`, `code-architect` for structural calls |
+| Implement | `tdd-guide` (or `tdd-workflow` skill) | `build-error-resolver` / `/build-fix` on build breaks |
+| Review | `code-reviewer` / `/code-review` | language reviewer (`python-reviewer`, `typescript-reviewer`, …) |
+| Security | `security-reviewer` | — |
+| MVP inner loop | `/gan-build "<brief>" --skip-planner` | drives `gan-generator` → `gan-evaluator`; tune `--max-iterations` / `--pass-threshold` |
+
+Match the language reviewer to the repo (see the repo's own `CLAUDE.md`).
+
+## Security-review trigger
+
+Pull in `security-reviewer` when the diff touches any of: authentication or
+authorization, user-input handling, database queries, file-system paths,
+external API calls, cryptography, or secrets / credentials. (Per `rules/common/security.md`.)
+
+## Handoff artifacts
+
+The pipeline carries no hidden state — the planning docs *are* the handoff:
+
+- `task_list` (from Plan) drives the Implement loop.
+- Larger work may also emit PRD / architecture / system_design under the repo's
+  `docs/` per `rules/common/development-workflow.md`.
+- Review findings (CRITICAL / HIGH) must be resolved before Gate 2.
+
+## Verification
+
+- size tier was stated and matched the work
+- Gate 1 (plan) and Gate 2 (commit) were both honored
+- `security-reviewer` ran iff a security trigger was touched
+- commits are conventional and scoped to one logical change
+- new / changed behavior has tests; coverage ≥ 80% per `rules/common/testing.md`

package/skills/orch-refine-code/SKILL.md

@@ -1,44 +1,44 @@
----
-name: orch-refine-code
-description: Orchestrate a behavior-preserving refactor — confirm tests are green, restructure without changing behavior, keep tests green, review, and gated commit. Use when the structure should improve but behavior must not change.
-metadata:
-  origin: ECC
----
-
-# orch-refine-code
-
-Actor · action · target: **orch · refine · code**. Thin wrapper over the shared
-engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
-
-## When to Use
-
-- Same behavior, **better structure**: extract modules, remove duplication, kill
-  dead code, reduce nesting, rename for clarity.
-- Distinguish from siblings: if behavior is meant to change at all, this is the
-  wrong skill (`orch-change-feature` / `orch-fix-defect`).
-
-## Operation settings
-
-- **Default size floor:** standard — restructures touch multiple files.
-- **Phase mask:** 0 → 2 (plan the restructure) → 4 (keep green) → 5 → 6. No new
-  behavior tests are written — the existing suite is the safety net.
-- **First move (phase 4):** confirm the relevant tests exist and are **green
-  before** touching code; if coverage is thin, add characterization tests first.
-  Then restructure in small steps, re-running tests after each.
-
-## How It Works
-
-1. Run the `orch-pipeline` engine with the settings above.
-2. For dead-code / duplication sweeps, delegate to the `refactor-cleaner` agent
-   (it runs knip / depcheck / ts-prune and removes safely).
-3. Stop at **Gate 1** (restructure plan) and **Gate 2** (pre-commit).
-4. Commit as `refactor:` — the diff must be behavior-neutral.
-
-## Example
-
-```
-orch-refine-code: extract the NWS HTTP client out of poller.py
-→ confirm tests green → plan extraction  [GATE 1: approve]
-→ move in small steps, tests green throughout → code-review
-→ commit refactor:  [GATE 2: confirm]
-```
+---
+name: orch-refine-code
+description: Orchestrate a behavior-preserving refactor — confirm tests are green, restructure without changing behavior, keep tests green, review, and gated commit. Use when the structure should improve but behavior must not change.
+metadata:
+  origin: ECC
+---
+
+# orch-refine-code
+
+Actor · action · target: **orch · refine · code**. Thin wrapper over the shared
+engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
+
+## When to Use
+
+- Same behavior, **better structure**: extract modules, remove duplication, kill
+  dead code, reduce nesting, rename for clarity.
+- Distinguish from siblings: if behavior is meant to change at all, this is the
+  wrong skill (`orch-change-feature` / `orch-fix-defect`).
+
+## Operation settings
+
+- **Default size floor:** standard — restructures touch multiple files.
+- **Phase mask:** 0 → 2 (plan the restructure) → 4 (keep green) → 5 → 6. No new
+  behavior tests are written — the existing suite is the safety net.
+- **First move (phase 4):** confirm the relevant tests exist and are **green
+  before** touching code; if coverage is thin, add characterization tests first.
+  Then restructure in small steps, re-running tests after each.
+
+## How It Works
+
+1. Run the `orch-pipeline` engine with the settings above.
+2. For dead-code / duplication sweeps, delegate to the `refactor-cleaner` agent
+   (it runs knip / depcheck / ts-prune and removes safely).
+3. Stop at **Gate 1** (restructure plan) and **Gate 2** (pre-commit).
+4. Commit as `refactor:` — the diff must be behavior-neutral.
+
+## Example
+
+```
+orch-refine-code: extract the NWS HTTP client out of poller.py
+→ confirm tests green → plan extraction  [GATE 1: approve]
+→ move in small steps, tests green throughout → code-review
+→ commit refactor:  [GATE 2: confirm]
+```