From 90dfd9505dc860714cf3cc8216ad7bbb96d93365 Mon Sep 17 00:00:00 2001 From: David W Miller <138746825+dMillerus@users.noreply.github.com> Date: Sun, 7 Jun 2026 03:15:31 -0500 Subject: [PATCH] feat: add orch-* orchestrator skill family (#2153) * feat: add orch-* orchestrator skill family Lightweight wrappers that orchestrate existing ECC agents through a gated Research -> Plan -> TDD -> Review -> Commit pipeline, right-sized per task. - orch-pipeline: shared engine (phases, size classifier, two gates, agent map) - orch-add-feature/change-feature/fix-defect/refine-code/build-mvp: thin wrappers delegating to the engine * chore: register orch-* family in catalog, command registry, and agent.yaml (post-rebase onto green main) --------- Co-authored-by: ECC Test --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- AGENTS.md | 6 +- README.md | 12 +-- README.zh-CN.md | 2 +- agent.yaml | 5 ++ commands/orch-add-feature.md | 36 +++++++++ commands/orch-build-mvp.md | 36 +++++++++ commands/orch-change-feature.md | 38 +++++++++ commands/orch-fix-defect.md | 38 +++++++++ commands/orch-refine-code.md | 39 +++++++++ docs/COMMAND-REGISTRY.json | 89 +++++++++++++++++---- docs/zh-CN/AGENTS.md | 6 +- docs/zh-CN/README.md | 10 +-- skills/orch-add-feature/SKILL.md | 44 ++++++++++ skills/orch-build-mvp/SKILL.md | 48 +++++++++++ skills/orch-change-feature/SKILL.md | 42 ++++++++++ skills/orch-fix-defect/SKILL.md | 42 ++++++++++ skills/orch-pipeline/SKILL.md | 120 ++++++++++++++++++++++++++++ skills/orch-refine-code/SKILL.md | 43 ++++++++++ 20 files changed, 626 insertions(+), 34 deletions(-) create mode 100644 commands/orch-add-feature.md create mode 100644 commands/orch-build-mvp.md create mode 100644 commands/orch-change-feature.md create mode 100644 commands/orch-fix-defect.md create mode 100644 commands/orch-refine-code.md create mode 100644 skills/orch-add-feature/SKILL.md create mode 100644 skills/orch-build-mvp/SKILL.md create mode 100644 skills/orch-change-feature/SKILL.md create mode 100644 skills/orch-fix-defect/SKILL.md create mode 100644 skills/orch-pipeline/SKILL.md create mode 100644 skills/orch-refine-code/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c6738c34..a6210b24 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ { "name": "ecc", "source": "./", - "description": "Harness-native ECC operator layer - 64 agents, 255 skills, 79 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses", + "description": "Harness-native ECC operator layer - 64 agents, 261 skills, 84 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses", "version": "2.0.0-rc.1", "author": { "name": "Affaan Mustafa", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index de4583c4..be1a95cf 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ecc", "version": "2.0.0-rc.1", - "description": "Harness-native ECC plugin for engineering teams - 64 agents, 255 skills, 79 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses", + "description": "Harness-native ECC plugin for engineering teams - 64 agents, 261 skills, 84 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses", "author": { "name": "Affaan Mustafa", "url": "https://x.com/affaanmustafa" diff --git a/AGENTS.md b/AGENTS.md index 86b444d1..f791d13a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — Agent Instructions -This is a **production-ready AI coding plugin** providing 64 specialized agents, 255 skills, 79 commands, and automated hook workflows for software development. +This is a **production-ready AI coding plugin** providing 64 specialized agents, 261 skills, 84 commands, and automated hook workflows for software development. **Version:** 2.0.0-rc.1 @@ -150,8 +150,8 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat ``` agents/ — 64 specialized subagents -skills/ — 255 workflow skills and domain knowledge -commands/ — 79 slash commands +skills/ — 261 workflow skills and domain knowledge +commands/ — 84 slash commands hooks/ — Trigger-based automations rules/ — Always-follow guidelines (common + per-language) scripts/ — Cross-platform Node.js utilities diff --git a/README.md b/README.md index cd5c2a78..0b924a0f 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ This repo is the raw code only. The guides explain everything. ### v2.0.0-rc.1 — Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026) - **Dashboard GUI** — New Tkinter-based desktop application (`ecc_dashboard.py` or `npm run dashboard`) with dark/light theme toggle, font customization, and project logo in header and taskbar. -- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 64 agents, 255 skills, and 79 legacy command shims. +- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 64 agents, 261 skills, and 84 legacy command shims. - **Operator and outbound workflow expansion** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops`, and `workspace-surface-audit` round out the operator lane. - **Media and launch tooling** — `manim-video`, `remotion-video-creation`, and upgraded social publishing surfaces make technical explainers and launch content part of the same system. - **Framework and product surface growth** — `nestjs-patterns`, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond Claude Code alone. @@ -394,7 +394,7 @@ If you stacked methods, clean up in this order: /plugin list ecc@ecc ``` -**That's it!** You now have access to 64 agents, 255 skills, and 79 legacy command shims. +**That's it!** You now have access to 64 agents, 261 skills, and 84 legacy command shims. ### Dashboard GUI @@ -1472,8 +1472,8 @@ The configuration is automatically detected from `.opencode/opencode.json`. | Feature | Claude Code | OpenCode | Status | |---------|---------------------|----------|--------| | Agents | PASS: 64 agents | PASS: 12 agents | **Claude Code leads** | -| Commands | PASS: 79 commands | PASS: 35 commands | **Claude Code leads** | -| Skills | PASS: 255 skills | PASS: 37 skills | **Claude Code leads** | +| Commands | PASS: 84 commands | PASS: 35 commands | **Claude Code leads** | +| Skills | PASS: 261 skills | PASS: 37 skills | **Claude Code leads** | | Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** | | Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** | | MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** | @@ -1634,8 +1634,8 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e | Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode | GitHub Copilot | |---------|-----------------------|------------|-----------|----------|----------------| | **Agents** | 64 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | N/A | -| **Commands** | 79 | Shared | Instruction-based | 35 | 6 prompts | -| **Skills** | 255 | Shared | 10 (native format) | 37 | Via instructions | +| **Commands** | 84 | Shared | Instruction-based | 35 | 6 prompts | +| **Skills** | 261 | Shared | 10 (native format) | 37 | Via instructions | | **Hook Events** | 8 types | 15 types | None yet | 11 types | None | | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | N/A | | **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | 1 always-on file | diff --git a/README.zh-CN.md b/README.zh-CN.md index d0069de0..d532eb9b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/" /plugin list ecc@ecc ``` -**完成！** 你现在可以使用 64 个代理、255 个技能和 79 个命令。 +**完成！** 你现在可以使用 64 个代理、261 个技能和 84 个命令。 ### multi-* 命令需要额外配置 diff --git a/agent.yaml b/agent.yaml index 1a80f5c1..4759b9c4 100644 --- a/agent.yaml +++ b/agent.yaml @@ -201,6 +201,11 @@ commands: - multi-frontend - multi-plan - multi-workflow + - orch-add-feature + - orch-build-mvp + - orch-change-feature + - orch-fix-defect + - orch-refine-code - plan - plan-prd - pm2 diff --git a/commands/orch-add-feature.md b/commands/orch-add-feature.md new file mode 100644 index 00000000..57db622c --- /dev/null +++ b/commands/orch-add-feature.md @@ -0,0 +1,36 @@ +--- +description: Orchestrate building a brand-new feature end to end — research, plan, TDD, review, gated commit. Wrapper that kicks off the orch-add-feature skill. +--- + +# /orch-add-feature + +Manually launch the **orch-add-feature** orchestrator: a gated +Research → Plan → TDD → Review → Commit pipeline for net-new capability. + +## Usage + +``` +/orch-add-feature +``` + +Examples: + +``` +/orch-add-feature add OAuth2 login to nws-poller +/orch-add-feature support CSV export in the dashboard +``` + +## What It Does + +Invoke the `orch-add-feature` skill with `$ARGUMENTS` as the request. The skill +(via the shared `orch-pipeline` engine) will: + +1. Classify size and state the tier in one line. +2. Research existing libraries/patterns, then plan a `task_list`. → **GATE 1** (approve plan). +3. TDD each task (new failing tests → green), then `code-reviewer` + (+ `security-reviewer` if a security trigger is touched). +4. Commit as conventional `feat:` commits. → **GATE 2** (confirm before commit). + +Honor both gates — do not write implementation before Gate 1, do not commit before Gate 2. + +If `$ARGUMENTS` is empty, ask the user what capability to add. diff --git a/commands/orch-build-mvp.md b/commands/orch-build-mvp.md new file mode 100644 index 00000000..9ec4ae04 --- /dev/null +++ b/commands/orch-build-mvp.md @@ -0,0 +1,36 @@ +--- +description: Orchestrate bootstrapping a working MVP from a design/spec doc — ingest, slice, scaffold, TDD, review, gated commit (reuses the GAN harness). Wrapper for the orch-build-mvp skill. +--- + +# /orch-build-mvp + +Manually launch the **orch-build-mvp** orchestrator: turn an SDD/PRD/system-design +document into a running vertical slice. + +## Usage + +``` +/orch-build-mvp +``` + +Examples: + +``` +/orch-build-mvp civicpulse/docs/SDD-v0.6.md +``` + +## What It Does + +Invoke the `orch-build-mvp` skill with `$ARGUMENTS` as the doc path. The skill +(via the shared `orch-pipeline` engine, full pipeline incl. Scaffold) will: + +1. Read the spec; extract scope, locked decisions, and a feature list ordered as + **thin vertical slices** (one end-to-end path first). → **GATE 1** (approve slice plan). +2. Scaffold the first end-to-end slice. +3. Reuse the GAN harness: translate the SDD into `gan-harness/spec.md` + + `eval-rubric.md`, then drive `/gan-build "" --skip-planner` + (generator → evaluator loop) until the score passes or plateaus. +4. `code-reviewer` (+ `security-reviewer` on any security-trigger slice), then + commit the scaffold and each slice as separate `feat:` commits. → **GATE 2**. + +If `$ARGUMENTS` is empty, ask the user for the path to the design/spec doc. diff --git a/commands/orch-change-feature.md b/commands/orch-change-feature.md new file mode 100644 index 00000000..fe5ee0a5 --- /dev/null +++ b/commands/orch-change-feature.md @@ -0,0 +1,38 @@ +--- +description: Orchestrate altering an existing, working feature to new desired behavior — update tests to the new spec, change impl, review, gated commit. Wrapper for the orch-change-feature skill. +--- + +# /orch-change-feature + +Manually launch the **orch-change-feature** orchestrator: change behavior that +already works to a new desired spec, tests-first. + +## Usage + +``` +/orch-change-feature +``` + +Examples: + +``` +/orch-change-feature make nws-poller alert at 2 warnings instead of 3 +/orch-change-feature instead of sorting by date, sort by priority +``` + +## What It Does + +Invoke the `orch-change-feature` skill with `$ARGUMENTS` as the request. The skill +(via the shared `orch-pipeline` engine) will: + +1. Classify size (default floor: small) and state the tier. +2. Light plan only if the new behavior needs research. → **GATE 1** (approve changed-test plan). +3. **Update the existing tests** to express the new behavior, then change the + implementation until green. (Changing the tests first is what makes this a + tweak, not a fix.) +4. `code-reviewer` (+ `security-reviewer` on a security trigger), then commit. → **GATE 2**. + +Use this only when the feature **works** but should behave differently — not for +bugs (`/orch-fix-defect`) or net-new capability (`/orch-add-feature`). + +If `$ARGUMENTS` is empty, ask the user what behavior should change. diff --git a/commands/orch-fix-defect.md b/commands/orch-fix-defect.md new file mode 100644 index 00000000..e86b07a8 --- /dev/null +++ b/commands/orch-fix-defect.md @@ -0,0 +1,38 @@ +--- +description: Orchestrate fixing a bug — reproduce it as a failing regression test, fix to green, review, gated commit. Wrapper for the orch-fix-defect skill. +--- + +# /orch-fix-defect + +Manually launch the **orch-fix-defect** orchestrator: prove the bug with a red +test, then fix to green. + +## Usage + +``` +/orch-fix-defect +``` + +Examples: + +``` +/orch-fix-defect poller crashes on empty NWS response +/orch-fix-defect login returns 500 when email has a plus sign +``` + +## What It Does + +Invoke the `orch-fix-defect` skill with `$ARGUMENTS` as the request. The skill +(via the shared `orch-pipeline` engine) will: + +1. Classify size (default floor: small, often trivial); scope root cause with + `code-explorer` if unclear. +2. **Write a new failing regression test** reproducing the bug, then fix until + it goes green. (Proving the bug first is what makes this a fix, not a tweak.) +3. `code-reviewer` (+ `security-reviewer` if the defect sits in a sensitive path). +4. Commit as a conventional `fix:` commit. → **GATE 2** (confirm before commit). + +Use this only when behavior is **broken/wrong** — not for intentional changes +(`/orch-change-feature`) or new capability (`/orch-add-feature`). + +If `$ARGUMENTS` is empty, ask the user to describe the defect. diff --git a/commands/orch-refine-code.md b/commands/orch-refine-code.md new file mode 100644 index 00000000..522e93e9 --- /dev/null +++ b/commands/orch-refine-code.md @@ -0,0 +1,39 @@ +--- +description: Orchestrate a behavior-preserving refactor — confirm tests green, restructure without changing behavior, keep green, review, gated commit. Wrapper for the orch-refine-code skill. +--- + +# /orch-refine-code + +Manually launch the **orch-refine-code** orchestrator: improve structure while +behavior stays identical, with the existing test suite as the safety net. + +## Usage + +``` +/orch-refine-code +``` + +Examples: + +``` +/orch-refine-code extract the NWS HTTP client out of poller.py +/orch-refine-code remove dead code and duplication in the dashboard module +``` + +## What It Does + +Invoke the `orch-refine-code` skill with `$ARGUMENTS` as the request. The skill +(via the shared `orch-pipeline` engine) will: + +1. Classify size (default floor: standard — restructures touch multiple files). +2. Confirm the relevant tests exist and are **green before** touching code; add + characterization tests first if coverage is thin. Plan the restructure. → **GATE 1**. +3. Restructure in small steps, re-running tests after each (no new behavior + tests — the existing suite proves behavior is unchanged). Dead-code/dup sweeps + delegate to `refactor-cleaner`. +4. `code-reviewer`, then commit as `refactor:` (the diff must be behavior-neutral). → **GATE 2**. + +Use this only when behavior must **not** change. If behavior should change at +all, use `/orch-change-feature` or `/orch-fix-defect`. + +If `$ARGUMENTS` is empty, ask the user what to refine. diff --git a/docs/COMMAND-REGISTRY.json b/docs/COMMAND-REGISTRY.json index e25a2d78..2ac66a02 100644 --- a/docs/COMMAND-REGISTRY.json +++ b/docs/COMMAND-REGISTRY.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, - "totalCommands": 79, + "totalCommands": 84, "commands": [ { "command": "aside", @@ -490,6 +490,67 @@ "skills": [], "path": "commands/multi-workflow.md" }, + { + "command": "orch-add-feature", + "description": "Orchestrate building a brand-new feature end to end — research, plan, TDD, review, gated commit. Wrapper that kicks off the orch-add-feature skill.", + "type": "orchestration", + "primaryAgents": [], + "allAgents": [], + "skills": [ + "orch-add-feature" + ], + "path": "commands/orch-add-feature.md" + }, + { + "command": "orch-build-mvp", + "description": "Orchestrate bootstrapping a working MVP from a design/spec doc — ingest, slice, scaffold, TDD, review, gated commit (reuses the GAN harness). Wrapper for the orch-build-mvp skill.", + "type": "orchestration", + "primaryAgents": [], + "allAgents": [], + "skills": [ + "orch-build-mvp" + ], + "path": "commands/orch-build-mvp.md" + }, + { + "command": "orch-change-feature", + "description": "Orchestrate altering an existing, working feature to new desired behavior — update tests to the new spec, change impl, review, gated commit. Wrapper for the orch-change-feature skill.", + "type": "orchestration", + "primaryAgents": [], + "allAgents": [], + "skills": [ + "orch-add-feature", + "orch-change-feature", + "orch-fix-defect" + ], + "path": "commands/orch-change-feature.md" + }, + { + "command": "orch-fix-defect", + "description": "Orchestrate fixing a bug — reproduce it as a failing regression test, fix to green, review, gated commit. Wrapper for the orch-fix-defect skill.", + "type": "orchestration", + "primaryAgents": [], + "allAgents": [], + "skills": [ + "orch-add-feature", + "orch-change-feature", + "orch-fix-defect" + ], + "path": "commands/orch-fix-defect.md" + }, + { + "command": "orch-refine-code", + "description": "Orchestrate a behavior-preserving refactor — confirm tests green, restructure without changing behavior, keep green, review, gated commit. Wrapper for the orch-refine-code skill.", + "type": "orchestration", + "primaryAgents": [], + "allAgents": [], + "skills": [ + "orch-change-feature", + "orch-fix-defect", + "orch-refine-code" + ], + "path": "commands/orch-refine-code.md" + }, { "command": "plan-prd", "description": "Generate a lean, problem-first PRD and hand off to /plan for implementation planning.", @@ -864,7 +925,7 @@ "byType": { "build": 2, "general": 7, - "orchestration": 6, + "orchestration": 11, "planning": 2, "refactoring": 1, "review": 9, @@ -929,6 +990,18 @@ "skill": "flutter-dart-code-review", "count": 3 }, + { + "skill": "orch-add-feature", + "count": 3 + }, + { + "skill": "orch-change-feature", + "count": 3 + }, + { + "skill": "orch-fix-defect", + "count": 3 + }, { "skill": "rust-patterns", "count": 3 @@ -940,18 +1013,6 @@ { "skill": "cpp-testing", "count": 2 - }, - { - "skill": "ecc-guide", - "count": 2 - }, - { - "skill": "golang-patterns", - "count": 2 - }, - { - "skill": "golang-testing", - "count": 2 } ] } diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md index 241f675c..54f7f93b 100644 --- a/docs/zh-CN/AGENTS.md +++ b/docs/zh-CN/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — 智能体指令 -这是一个**生产就绪的 AI 编码插件**，提供 64 个专业代理、255 项技能、79 条命令以及自动化钩子工作流，用于软件开发。 +这是一个**生产就绪的 AI 编码插件**，提供 64 个专业代理、261 项技能、84 条命令以及自动化钩子工作流，用于软件开发。 **版本:** 2.0.0-rc.1 @@ -147,8 +147,8 @@ ``` agents/ — 64 个专业子代理 -skills/ — 255 个工作流技能和领域知识 -commands/ — 79 个斜杠命令 +skills/ — 261 个工作流技能和领域知识 +commands/ — 84 个斜杠命令 hooks/ — 基于触发的自动化 rules/ — 始终遵循的指导方针（通用 + 每种语言） scripts/ — 跨平台 Node.js 实用工具 diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 9cb11465..a0a3fcfa 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/" /plugin list ecc@ecc ``` -**搞定！** 你现在可以使用 64 个智能体、255 项技能和 79 个命令了。 +**搞定！** 你现在可以使用 64 个智能体、261 项技能和 84 个命令了。 *** @@ -1137,8 +1137,8 @@ opencode | 功能特性 | Claude Code | OpenCode | 状态 | |---------|---------------|----------|--------| | 智能体 | PASS: 64 个 | PASS: 12 个 | **Claude Code 领先** | -| 命令 | PASS: 79 个 | PASS: 35 个 | **Claude Code 领先** | -| 技能 | PASS: 255 项 | PASS: 37 项 | **Claude Code 领先** | +| 命令 | PASS: 84 个 | PASS: 35 个 | **Claude Code 领先** | +| 技能 | PASS: 261 项 | PASS: 37 项 | **Claude Code 领先** | | 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多！** | | 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** | | MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** | @@ -1245,8 +1245,8 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以 | 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode | |---------|-----------------------|------------|-----------|----------| | **智能体** | 64 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 | -| **命令** | 79 | 共享 | 基于指令 | 35 | -| **技能** | 255 | 共享 | 10 (原生格式) | 37 | +| **命令** | 84 | 共享 | 基于指令 | 35 | +| **技能** | 261 | 共享 | 10 (原生格式) | 37 | | **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 | | **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 | | **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 | diff --git a/skills/orch-add-feature/SKILL.md b/skills/orch-add-feature/SKILL.md new file mode 100644 index 00000000..fff711bb --- /dev/null +++ b/skills/orch-add-feature/SKILL.md @@ -0,0 +1,44 @@ +--- +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. +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] +``` diff --git a/skills/orch-build-mvp/SKILL.md b/skills/orch-build-mvp/SKILL.md new file mode 100644 index 00000000..db7e6175 --- /dev/null +++ b/skills/orch-build-mvp/SKILL.md @@ -0,0 +1,48 @@ +--- +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. +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 "" --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 +``` diff --git a/skills/orch-change-feature/SKILL.md b/skills/orch-change-feature/SKILL.md new file mode 100644 index 00000000..0f002008 --- /dev/null +++ b/skills/orch-change-feature/SKILL.md @@ -0,0 +1,42 @@ +--- +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. +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] +``` diff --git a/skills/orch-fix-defect/SKILL.md b/skills/orch-fix-defect/SKILL.md new file mode 100644 index 00000000..c1f5c6a3 --- /dev/null +++ b/skills/orch-fix-defect/SKILL.md @@ -0,0 +1,42 @@ +--- +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. +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:) +``` diff --git a/skills/orch-pipeline/SKILL.md b/skills/orch-pipeline/SKILL.md new file mode 100644 index 00000000..14b2e454 --- /dev/null +++ b/skills/orch-pipeline/SKILL.md @@ -0,0 +1,120 @@ +--- +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. +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 "" --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` diff --git a/skills/orch-refine-code/SKILL.md b/skills/orch-refine-code/SKILL.md new file mode 100644 index 00000000..1f8bbdfc --- /dev/null +++ b/skills/orch-refine-code/SKILL.md @@ -0,0 +1,43 @@ +--- +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. +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] +```