dsh-ecc-skills 0.4.0

package/skills/nuxt4-patterns/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: nuxt4-patterns
+description: Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData. Use when building or reviewing a Nuxt 4 app, or debugging hydration mismatches and SSR-safe data fetching.
+metadata:
+  origin: ECC
+---
+
+# Nuxt 4 Patterns
+
+Use when building or debugging Nuxt 4 apps with SSR, hybrid rendering, route rules, or page-level data fetching.
+
+## When to Activate
+
+- Hydration mismatches between server HTML and client state
+- Route-level rendering decisions such as prerender, SWR, ISR, or client-only sections
+- Performance work around lazy loading, lazy hydration, or payload size
+- Page or component data fetching with `useFetch`, `useAsyncData`, or `$fetch`
+- Nuxt routing issues tied to route params, middleware, or SSR/client differences
+
+## Hydration Safety
+
+- Keep the first render deterministic. Do not put `Date.now()`, `Math.random()`, browser-only APIs, or storage reads directly into SSR-rendered template state.
+- Move browser-only logic behind `onMounted()`, `import.meta.client`, `ClientOnly`, or a `.client.vue` component when the server cannot produce the same markup.
+- Use Nuxt's `useRoute()` composable, not the one from `vue-router`.
+- Do not use `route.fullPath` to drive SSR-rendered markup. URL fragments are client-only, which can create hydration mismatches.
+- Treat `ssr: false` as an escape hatch for truly browser-only areas, not a default fix for mismatches.
+
+## Data Fetching
+
+- Prefer `await useFetch()` for SSR-safe API reads in pages and components. It forwards server-fetched data into the Nuxt payload and avoids a second fetch on hydration.
+- Use `useAsyncData()` when the fetcher is not a simple `$fetch()` call, when you need a custom key, or when you are composing multiple async sources.
+- Give `useAsyncData()` a stable key for cache reuse and predictable refresh behavior.
+- Keep `useAsyncData()` handlers side-effect free. They can run during SSR and hydration.
+- Use `$fetch()` for user-triggered writes or client-only actions, not top-level page data that should be hydrated from SSR.
+- Use `lazy: true`, `useLazyFetch()`, or `useLazyAsyncData()` for non-critical data that should not block navigation. Handle `status === 'pending'` in the UI.
+- Use `server: false` only for data that is not needed for SEO or the first paint.
+- Trim payload size with `pick` and prefer shallower payloads when deep reactivity is unnecessary.
+
+```ts
+const route = useRoute()
+
+const { data: article, status, error, refresh } = await useAsyncData(
+  () => `article:${route.params.slug}`,
+  () => $fetch(`/api/articles/${route.params.slug}`),
+)
+
+const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
+  lazy: true,
+  server: false,
+})
+```
+
+## Route Rules
+
+Prefer `routeRules` in `nuxt.config.ts` for rendering and caching strategy:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/': { prerender: true },
+    '/products/**': { swr: 3600 },
+    '/blog/**': { isr: true },
+    '/admin/**': { ssr: false },
+    '/api/**': { cache: { maxAge: 60 * 60 } },
+  },
+})
+```
+
+- `prerender`: static HTML at build time
+- `swr`: serve cached content and revalidate in the background
+- `isr`: incremental static regeneration on supported platforms
+- `ssr: false`: client-rendered route
+- `cache` or `redirect`: Nitro-level response behavior
+
+Pick route rules per route group, not globally. Marketing pages, catalogs, dashboards, and APIs usually need different strategies.
+
+## Lazy Loading and Performance
+
+- Nuxt already code-splits pages by route. Keep route boundaries meaningful before micro-optimizing component splits.
+- Use the `Lazy` prefix to dynamically import non-critical components.
+- Conditionally render lazy components with `v-if` so the chunk is not loaded until the UI actually needs it.
+- Use lazy hydration for below-the-fold or non-critical interactive UI.
+
+```vue
+<template>
+  <LazyRecommendations v-if="showRecommendations" />
+  <LazyProductGallery hydrate-on-visible />
+</template>
+```
+
+- For custom strategies, use `defineLazyHydrationComponent()` with a visibility or idle strategy.
+- Nuxt lazy hydration works on single-file components. Passing new props to a lazily hydrated component will trigger hydration immediately.
+- Use `NuxtLink` for internal navigation so Nuxt can prefetch route components and generated payloads.
+
+## Review Checklist
+
+- First SSR render and hydrated client render produce the same markup
+- Page data uses `useFetch` or `useAsyncData`, not top-level `$fetch`
+- Non-critical data is lazy and has explicit loading UI
+- Route rules match the page's SEO and freshness requirements
+- Heavy interactive islands are lazy-loaded or lazily hydrated

package/skills/opensource-pipeline/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: opensource-pipeline
+description: "Open-source pipeline: fork, sanitize, and package private projects for safe public release. Chains 3 agents (forker, sanitizer, packager). Triggers: '/opensource', 'open source this', 'make this public', 'prepare for open source'. Use when a private project must be forked, stripped of secrets, and packaged for public release."
+metadata:
+  origin: ECC
+---
+
+# Open-Source Pipeline Skill
+
+Safely open-source any project through a 3-stage pipeline: **Fork** (strip secrets) → **Sanitize** (verify clean) → **Package** (CLAUDE.md + setup.sh + README).
+
+## When to Activate
+
+- User says "open source this project" or "make this public"
+- User wants to prepare a private repo for public release
+- User needs to strip secrets before pushing to GitHub
+- User invokes `/opensource fork`, `/opensource verify`, or `/opensource package`
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/opensource fork PROJECT` | Full pipeline: fork + sanitize + package |
+| `/opensource verify PROJECT` | Run sanitizer on existing repo |
+| `/opensource package PROJECT` | Generate CLAUDE.md + setup.sh + README |
+| `/opensource list` | Show all staged projects |
+| `/opensource status PROJECT` | Show reports for a staged project |
+
+## Protocol
+
+### /opensource fork PROJECT
+
+**Full pipeline — the main workflow.**
+
+#### Step 1: Gather Parameters
+
+Resolve the project path. If PROJECT contains `/`, treat as a path (absolute or relative). Otherwise check: current working directory, `$HOME/PROJECT`, then ask the user.
+
+```
+SOURCE_PATH="<resolved absolute path>"
+STAGING_PATH="$HOME/opensource-staging/${PROJECT_NAME}"
+```
+
+Ask the user:
+1. "Which project?" (if not found)
+2. "License? (MIT / Apache-2.0 / GPL-3.0 / BSD-3-Clause)"
+3. "GitHub org or username?" (default: detect via `gh api user -q .login`)
+4. "GitHub repo name?" (default: project name)
+5. "Description for README?" (analyze project for suggestion)
+
+#### Step 2: Create Staging Directory
+
+```bash
+mkdir -p $HOME/opensource-staging/
+```
+
+#### Step 3: Run Forker Agent
+
+Spawn the `opensource-forker` agent:
+
+```
+Agent(
+  description="Fork {PROJECT} for open-source",
+  subagent_type="opensource-forker",
+  prompt="""
+Fork project for open-source release.
+
+Source: {SOURCE_PATH}
+Target: {STAGING_PATH}
+License: {chosen_license}
+
+Follow the full forking protocol:
+1. Copy files (exclude .git, node_modules, __pycache__, .venv)
+2. Strip all secrets and credentials
+3. Replace internal references with placeholders
+4. Generate .env.example
+5. Clean git history
+6. Generate FORK_REPORT.md in {STAGING_PATH}/FORK_REPORT.md
+"""
+)
+```
+
+Wait for completion. Read `{STAGING_PATH}/FORK_REPORT.md`.
+
+#### Step 4: Run Sanitizer Agent
+
+Spawn the `opensource-sanitizer` agent:
+
+```
+Agent(
+  description="Verify {PROJECT} sanitization",
+  subagent_type="opensource-sanitizer",
+  prompt="""
+Verify sanitization of open-source fork.
+
+Project: {STAGING_PATH}
+Source (for reference): {SOURCE_PATH}
+
+Run ALL scan categories:
+1. Secrets scan (CRITICAL)
+2. PII scan (CRITICAL)
+3. Internal references scan (CRITICAL)
+4. Dangerous files check (CRITICAL)
+5. Configuration completeness (WARNING)
+6. Git history audit
+
+Generate SANITIZATION_REPORT.md inside {STAGING_PATH}/ with PASS/FAIL verdict.
+"""
+)
+```
+
+Wait for completion. Read `{STAGING_PATH}/SANITIZATION_REPORT.md`.
+
+**If FAIL:** Show findings to user. Ask: "Fix these and re-scan, or abort?"
+- If fix: Apply fixes, re-run sanitizer (maximum 3 retry attempts — after 3 FAILs, present all findings and ask user to fix manually)
+- If abort: Clean up staging directory
+
+**If PASS or PASS WITH WARNINGS:** Continue to Step 5.
+
+#### Step 5: Run Packager Agent
+
+Spawn the `opensource-packager` agent:
+
+```
+Agent(
+  description="Package {PROJECT} for open-source",
+  subagent_type="opensource-packager",
+  prompt="""
+Generate open-source packaging for project.
+
+Project: {STAGING_PATH}
+License: {chosen_license}
+Project name: {PROJECT_NAME}
+Description: {description}
+GitHub repo: {github_repo}
+
+Generate:
+1. CLAUDE.md (commands, architecture, key files)
+2. setup.sh (one-command bootstrap, make executable)
+3. README.md (or enhance existing)
+4. LICENSE
+5. CONTRIBUTING.md
+6. .github/ISSUE_TEMPLATE/ (bug_report.md, feature_request.md)
+"""
+)
+```
+
+#### Step 6: Final Review
+
+Present to user:
+```
+Open-Source Fork Ready: {PROJECT_NAME}
+
+Location: {STAGING_PATH}
+License: {license}
+Files generated:
+  - CLAUDE.md
+  - setup.sh (executable)
+  - README.md
+  - LICENSE
+  - CONTRIBUTING.md
+  - .env.example ({N} variables)
+
+Sanitization: {sanitization_verdict}
+
+Next steps:
+  1. Review: cd {STAGING_PATH}
+  2. Create repo: gh repo create {github_org}/{github_repo} --public
+  3. Push: git remote add origin ... && git push -u origin main
+
+Proceed with GitHub creation? (yes/no/review first)
+```
+
+#### Step 7: GitHub Publish (on user approval)
+
+```bash
+cd "{STAGING_PATH}"
+gh repo create "{github_org}/{github_repo}" --public --source=. --push --description "{description}"
+```
+
+---
+
+### /opensource verify PROJECT
+
+Run sanitizer independently. Resolve path: if PROJECT contains `/`, treat as a path. Otherwise check `$HOME/opensource-staging/PROJECT`, then `$HOME/PROJECT`, then current directory.
+
+```
+Agent(
+  subagent_type="opensource-sanitizer",
+  prompt="Verify sanitization of: {resolved_path}. Run all 6 scan categories and generate SANITIZATION_REPORT.md."
+)
+```
+
+---
+
+### /opensource package PROJECT
+
+Run packager independently. Ask for "License?" and "Description?", then:
+
+```
+Agent(
+  subagent_type="opensource-packager",
+  prompt="Package: {resolved_path} ..."
+)
+```
+
+---
+
+### /opensource list
+
+```bash
+ls -d $HOME/opensource-staging/*/
+```
+
+Show each project with pipeline progress (FORK_REPORT.md, SANITIZATION_REPORT.md, CLAUDE.md presence).
+
+---
+
+### /opensource status PROJECT
+
+```bash
+cat $HOME/opensource-staging/${PROJECT}/SANITIZATION_REPORT.md
+cat $HOME/opensource-staging/${PROJECT}/FORK_REPORT.md
+```
+
+## Staging Layout
+
+```
+$HOME/opensource-staging/
+  my-project/
+    FORK_REPORT.md           # From forker agent
+    SANITIZATION_REPORT.md   # From sanitizer agent
+    CLAUDE.md                # From packager agent
+    setup.sh                 # From packager agent
+    README.md                # From packager agent
+    .env.example             # From forker agent
+    ...                      # Sanitized project files
+```
+
+## Anti-Patterns
+
+- **Never** push to GitHub without user approval
+- **Never** skip the sanitizer — it is the safety gate
+- **Never** proceed after a sanitizer FAIL without fixing all critical findings
+- **Never** leave `.env`, `*.pem`, or `credentials.json` in the staging directory
+
+## Best Practices
+
+- Always run the full pipeline (fork → sanitize → package) for new releases
+- The staging directory persists until explicitly cleaned up — use it for review
+- Re-run the sanitizer after any manual fixes before publishing
+- Parameterize secrets rather than deleting them — preserve project functionality
+
+## Related Skills
+
+See `security-review` for secret detection patterns used by the sanitizer.

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

@@ -0,0 +1,45 @@
+---
+name: orch-add-feature
+description: Orchestrate building a brand-new feature end to end — research, plan, TDD implementation, review, and gated commit — by delegating each phase to the matching ECC agent. Use when adding a capability that does not exist yet.
+metadata:
+  origin: ECC
+---
+
+# orch-add-feature
+
+Actor · action · target: **orch · add · feature**. Thin wrapper over the shared
+engine in [`orch-pipeline`](../orch-pipeline/SKILL.md).
+
+## When to Use
+
+- The user wants a capability that does **not exist yet** ("add", "build",
+  "implement", "support …").
+- It is net-new behavior — not a correction (`orch-fix-defect`) and not an
+  alteration of existing behavior (`orch-change-feature`).
+
+## Operation settings
+
+- **Default size floor:** standard — run Research + Plan unless clearly small.
+- **Phase mask:** 0 → 1 → 2 → 4 → 5 → 6 (skip 3 Scaffold; that is MVP-only).
+- **First move (phase 4):** write *new* failing tests for the new behavior, then
+  implement to green.
+
+## How It Works
+
+1. Run the `orch-pipeline` engine with the settings above.
+2. Classify size first; small / trivial features collapse toward 4 → 5 → 6.
+3. Stop at **Gate 1** (plan approval) and **Gate 2** (pre-commit).
+4. Add `security-reviewer` if the feature touches a security trigger.
+
+> Related: `/feature-dev` is a standalone version of this flow. `orch-add-feature`
+> differs by sharing the `orch-pipeline` engine — the size classifier and the two
+> gates — with the rest of the family, so it right-sizes trivial features to 4 → 5 → 6.
+
+## Example
+
+```
+orch-add-feature: add OAuth2 login to nws-poller
+→ research existing auth libs → plan task_list  [GATE 1: approve]
+→ TDD each task → code-review (+ security-reviewer: auth path)
+→ commit  [GATE 2: confirm]
+```

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

@@ -0,0 +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. Use when a design or spec document must become a running MVP through planned vertical slices.
+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

@@ -0,0 +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]
+```

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

@@ -0,0 +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:)
+```

package/skills/orch-pipeline/SKILL.md

@@ -0,0 +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. Not usually invoked directly; it applies when an orch-* skill delegates its gated Research-Plan-TDD-Review-Commit pipeline.
+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`