Skip to content
Back to search

opc

OPC — One Person Company. A full team in a single Claude Code skill. Adaptive agent orchestrator with 21 built-in roles, 6 flow templates, and adversarial quality control.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/iamtouchskyer--opc/badge.svg)](/listings/iamtouchskyer--opc)

HTML

<a href="/listings/iamtouchskyer--opc"><img src="/api/listings/iamtouchskyer--opc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

npm install -g @touchskyer/opc

Skill files are automatically copied to `~/.claude/skills/opc/`.

Recent npm versions block install scripts by default — if the copy is skipped (check: `opc --version` prints but `~/.claude/skills/opc/SKILL.md` is missing), rerun with `npm install -g --allow-scripts=@touchskyer/opc`, or just run `opc install` once afterwards.

Manual install (no npm)

git clone https://github.com/iamtouchskyer/opc.git
cp -r opc ~/.claude/skills/opc

Use it

# Review — dispatches 2-5 role agents in parallel
/opc review the auth changes

# Build — implements + independent review + gate
/opc implement user authentication with email/password

# Autonomous loop — decomposes, schedules cron, runs unattended
/opc loop build features F1-F4 from PLAN.md

# Interactive mode — asks clarifying questions first
/opc -i redesign the onboarding flow

# Explicit roles
/opc security devil-advocate

# Flow control
/opc skip          # skip current node
/opc pass          # force-pass gate
/opc stop          # terminate, preserve state
/opc goto build    # jump to node

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 681 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: opc
  3. version: 0.10.2
  4. description: "OPC — One Person Company. Digraph-based task pipeline with independent multi-role evaluation. Builds, reviews, analyzes, and brainstorms with specialist agents. Every path ends with evaluation. /opc <task>, /opc -i <task>, /opc <role> [role...]"
  5. ---
  6. # OPC — One Person Company
  7. One principle: **the agent that does the work never evaluates it.**
  8. A full team in a single skill. The digraph engine handles any task — building code, reviewing code, analyzing problems, brainstorming designs. It infers which flow and entry point to use from the task itself, and every path ends with independent evaluation.
  9. ## Invocation
  10. **Harness path:** The `opc-harness` binary lives at `bin/opc-harness.mjs` relative to this skill's install directory. Resolve it once at session start:
  11. ```bash
  12. OPC_HARNESS="$HOME/.claude/skills/opc/bin/opc-harness.mjs"
  13. ```
  14. All `opc-harness` references below mean `node "$OPC_HARNESS"`. Set this as a shell variable and reuse it throughout the session.
  15. ```
  16. /opc <task> # auto mode — infer flow and roles from the task
  17. /opc -i <task> # interactive mode — ask questions before dispatch
  18. /opc <role> [role...] # explicit roles — skip role selection, dispatch directly
  19. /opc loop <task> # autonomous loop — decompose, schedule cron, run 24h unattended
  20. /opc skip # skip current node, advance via PASS edge
  21. /opc pass # force-pass current gate
  22. /opc stop # terminate flow, preserve session state
  23. /opc goto <nodeId> # manual jump to a node (cycle limits still enforced)
  24. ```
  25. ## Task Inference + Flow Selection
  26. The orchestrator reads the task, selects a flow template, and determines the entry point.
  27. | Task says... | Flow template | Default entry |
  28. |---|---|---|
  29. | "review", "audit", "check", "before we merge", "找问题", "开源前看看" | review | review |
  30. | "analyze", "diagnose", "what's wrong with", "分析" | review | review |
  31. | "build", "implement", "create", "fix bug", "帮我实现", "重构成..." | build-verify | brief |
  32. | "quick fix", "small change", "one-liner", "patch", "trivial fix", "快速修复", "小改动" | quick | build |
  33. | "brainstorm", "explore options", "what are the approaches", "有什么方案" | build-verify | brief |
  34. | "plan", "decompose", "break this down", "scope", "estimate", "拆一下" | build-verify | brief |
  35. | "verify", "test", "QA", "check before release", "发布前验收" | pre-release | acceptance |
  36. | "post-release", "user test", "onboarding check", "用户验收" | pre-release | acceptance |
  37. | Complex, vague, or multi-keyword request | full-stack | discuss |
  38. | `/opc loop` or multi-unit feature backlog | **loop-protocol** | plan decomposition |
  39. **Entry override** — user context can shift the entry point (only if target ∈ template nodes):
  40. | User has... | Entry override |
  41. |---|---|
  42. | A vague idea or brief | First node in template |
  43. | A spec or design doc | brief (if ∈ template), else build |
  44. | An implementation plan | brief (if ∈ template), else build |
  45. | A qualified build-brief.md from prior run | build (skip brief if lint passes) |
  46. | Code/artifact that needs evaluation | review, code-review, or test-design (if ∈ template) |
  47. | Everything done, needs acceptance | acceptance (if ∈ template) |
  48. **Priority rules:**
  49. - `/opc loop <task>` = enter autonomous loop mode. Follow `./pipeline/loop-protocol.md`: first check `.opc/runbooks/` for a matching runbook, otherwise decompose task into units. Initialize loop state, start cron, execute ticks. Each tick runs the appropriate OPC flow for that unit type.
  50. - `/opc <role> [role...]` without a task = review of current codebase using review flow with named roles.
  51. - `/opc` with no arguments = prompt user to describe their task.
  52. - If task matches multiple rows, prefer the flow that includes build — code changes must precede review.
  53. Show triage result:
  54. ```
  55. 📌 Flow: {flow template name}
  56. 📍 Entry: {entry node}
  57. ⚡ Interaction: auto / interactive
  58. Rationale: {1 sentence}
  59. ```
  60. **Override:** If user explicitly names a task type, respect that. Users can adjust after seeing triage.
  61. ## Flow Templates
  62. Flow graph structures (nodes, edges, limits) are defined in `opc-harness` code. The orchestrator uses `opc-harness route` to determine next nodes — **do not look up edges yourself**.
  63. Each template below describes which agents to dispatch at each node and which protocol to use.
  64. ### legacy-linear
  65. Equivalent to v0.4.x behavior. Used as internal fallback only.
  66. | Node | Type | Agents | Protocol |
  67. |------|------|--------|----------|
  68. | design | discussion | [planner] | design exploration |
  69. | plan | build | [planner] | task decomposition |
  70. | build | build | [implementer] | implementer-prompt.md |
  71. | evaluate | review | [selected roles] | role-evaluator-prompt.md |
  72. | deliver | build | — | commit + report |
  73. ### review
  74. | Node | Type | Agents | Protocol |
  75. |------|------|--------|----------|
  76. | review | review | [selected roles] | role-evaluator-prompt.md |
  77. | gate | gate | — | gate-protocol.md |
  78. Gate loopback: FAIL/ITERATE → review (multi-round with prior findings as context). Review is not limited to code — it evaluates any artifact: architecture proposals, documents, strategies, products.
  79. ### build-verify
  80. | Node | Type | Agents | Protocol |
  81. |------|------|--------|----------|
  82. | brief | brief | [architect] | brief-protocol.md |
  83. | build | build | [implementer] | implementer-prompt.md |
  84. | code-review | review | [selected roles] | role-evaluator-prompt.md |
  85. | test-design | review | [tester, + user/domain roles] | test-design-protocol.md |
  86. | test-execute | execute | [orchestrator] | executor-protocol.md |
  87. | gate | gate | — | gate-protocol.md |
  88. **test-design** is a review node where multiple roles design test cases (API tests, E2E UI tests, edge cases) without executing them. **test-execute** runs the designed test plan and captures evidence. Principle: *the person who decides what to test must not be the person who runs the tests.*
  89. ### quick
  90. | Node | Type | Agents | Protocol |
  91. |------|------|--------|----------|
  92. | build | build | [implementer] | implementer-prompt.md |
  93. | review | review | [selected roles] | role-evaluator-prompt.md |
  94. | test-design | review | [tester, + user/domain roles] | test-design-protocol.md |
  95. | test-execute | execute | [orchestrator] | executor-protocol.md |
  96. | gate | gate | — | gate-protocol.md |
  97. **Scope**: Non-UI, single-file or ≤3 file changes, low risk. If task involves UI/design, multi-module refactoring, or security-related changes → use build-verify instead. Gate loops back to build (no brief node), and quick still requires OPC-generated testCommand evidence before final PASS.
  98. ### full-stack
  99. The complete flow with discussion, multi-stage gates, and E2E verification.
  100. | Node | Type | Agents | Protocol |
  101. |------|------|--------|----------|
  102. | discuss | discussion | [architect, engineer, tester] | discussion-protocol.md |
  103. | brief | brief | [architect] | brief-protocol.md |
  104. | build | build | [implementer] | implementer-prompt.md |
  105. | code-review | review | [frontend, backend] | role-evaluator-prompt.md |
  106. | test-design | review | [tester, + user/domain roles] | test-design-protocol.md |
  107. | test-execute | execute | [orchestrator] | executor-protocol.md |
  108. | gate-test | gate | — | gate-protocol.md |
  109. | acceptance | review | [pm, designer] | role-evaluator-prompt.md |
  110. | gate-acceptance | gate | — | gate-protocol.md |
  111. | audit | review | [security, compliance, a11y] | role-evaluator-prompt.md |
  112. | gate-audit | gate | — | gate-protocol.md |
  113. | e2e-user | execute | [new-user, active-user, churned-user] | executor-protocol.md |
  114. | gate-e2e | gate | — | gate-protocol.md |
  115. | ux-simulation | execute | [new-user, active-user, churned-user] | ux-simulation-protocol.md + ux-observer-protocol.md |
  116. | gate-final | gate | — | gate-protocol.md |
  117. ### pre-release
  118. | Node | Type | Agents | Protocol |
  119. |------|------|--------|----------|
  120. | acceptance | review | [pm, designer] | role-evaluator-prompt.md |
  121. | gate-acceptance | gate | — | gate-protocol.md |
  122. | audit | review | [security, compliance, a11y] | role-evaluator-prompt.md |
  123. | gate-audit | gate | — | gate-protocol.md |
  124. | e2e-user | execute | [new-user, active-user, churned-user] | executor-protocol.md |
  125. | gate-e2e | gate | — | gate-protocol.md |
  126. ---
  127. ## Getting Started
  128. **Before task inference**, check for existing state:
  129. 1. Run `opc-harness ls` to discover active flows. If any exist for the current project, show them and ask whether to resume or start fresh.
  130. 2. If `.harness/` has `wave-*` files but no `flow-state.json` → **legacy v0.4.x format detected**. Print: "Detected v0.4.x .harness/ format. Please delete .harness/ and re-run, or manually migrate." Do not proceed.
  131. 3. Otherwise → fresh start.
  132. After flow selection, initialize with the matching interaction mode:
  133. ```bash
  134. opc-harness init --auto --claude-session-id "${CLAUDE_SESSION_ID}" --flow {TEMPLATE} --entry {ENTRY_NODE}
  135. opc-harness init --flow {TEMPLATE} --entry {ENTRY_NODE} # interactive (`/opc -i`) only
  136. ```
  137. Auto init requires the installed OPC `PreToolUse` hook. Interactive init does not create a Claude session registry and is not subject to the node or repair-edge circuit breaker.
  138. Init auto-creates `~/.opc/sessions/{project-hash}/{session-id}/` and updates the `latest` symlink. **All subsequent harness commands automatically resolve to the latest session dir** — you do NOT need to pass `--dir` or capture the output. Just run commands normally:
  139. ```bash
  140. opc-harness route --node review --verdict PASS --flow {TEMPLATE}
  141. opc-harness transition --from review --to gate --verdict PASS --flow {TEMPLATE}
  142. opc-harness viz --flow {TEMPLATE}
  143. ```
  144. **Multi-window safety:** Each `init` creates a new session dir. If multiple OPC windows run on the same project, the last one to `init` becomes `latest`. To pin a specific session, pass `--dir <path>` explicitly.
  145. **Backward compat:** Pass `--dir .harness` to init for a project-local harness dir.
  146. **Show flow graph** — immediately after init, run `opc-harness viz --flow {TEMPLATE}` and display the ASCII output to the user. This gives them a visual map of the entire flow before execution begins.
  147. Before starting, extract **acceptance criteria** — 3-7 concrete, testable bullet points. Evaluators grade against these.
  148. ### Agent Model Routing — Mandatory Pre-Flight
  149. Flow topology and model tier are independent. Keep every selected node, round, and role, but before each Agent call run:
  150. ```bash
  151. opc-harness model-route --node {NODE_ID} --node-type {NODE_TYPE} [--role {ROLE}] --dir {PROJECT_ROOT}
  152. ```
  153. Pass the returned `model` through the host's per-dispatch selector. `dispatch: false` means no Agent. On an error or unsupported selector, stop instead of silently inheriting the root model. Re-run with `--allow-premium` only after explicit user approval. Show `💰 Model route: {tier} → {model} ({source})` before launch. Read `./pipeline/model-routing.md` only for configuration or troubleshooting.
  154. ### Quality Tier Selection — Mandatory Pre-Flight
  155. Before the Definition of Done questions, the orchestrator MUST select a **quality tier**. See `./pipeline/quality-tiers.md` for full definitions.
  156. | Tier | When | Baseline |
  157. |------|------|----------|
  158. | `functional` | CLI, API, backend, library, infra | No UI craft requirements |
  159. | `polished` | UI, frontend, website, dashboard, docs | Dark/light, responsive, loading/error/empty states, favicon, focus styles |
  160. | `delightful` | Showcase, demo, pitch, consumer product | All of polished + transitions, animations, micro-interactions, onboarding |
  161. **Selection rules:**
  162. 1. User explicitly specifies tier → use it
  163. 2. Task involves UI/frontend → default `polished`
  164. 3. Task is CLI/API/backend → default `functional`
  165. 4. Task includes "showcase", "demo", "pitch", "delightful", "beautiful" → `delightful`
  166. 5. Interactive mode → ask the user
  167. Show tier selection:
  168. ```
  169. 🎯 Quality Tier: {tier}
  170. Baseline: {N items from tier checklist}
  171. ```
  172. The tier's baseline checklist items are **automatically appended** to acceptance criteria under a "## Quality Baseline ({tier})" section in `acceptance-criteria.md` (in the session dir). The implementer and evaluator both receive the tier as context.
  173. ### Definition of Done — Mandatory Pre-Flight (all modes)
  174. Before dispatching ANY work, the orchestrator MUST establish a clear definition of done. This applies to **both auto and interactive modes** — the only difference is how the answers are obtained (inferred vs asked).
  175. **Three questions that must have answers before the first node executes:**
  176. 1. **What does "done" look like?** — Concrete, observable outcomes. Not "implement auth" but "user can log in with email/password, session persists across refresh, logout clears session."
  177. 2. **How will we verify it?** — Map each outcome to a verification method:
  178. - Code change → which tests? (`npm test`, specific test file, new test to write?)
  179. - UI change → which page/component to screenshot? What should be visible?
  180. - API change → which endpoint to curl? What response shape?
  181. - Refactor → which existing tests must still pass?
  182. 3. **How will we evaluate quality?** — What should reviewers look for beyond "it works"?
  183. - Performance constraints? ("page load < 2s")
  184. - Security concerns? ("no PII in logs")
  185. - Compatibility? ("works in Safari")
  186. - Edge cases? ("handles empty input, 10k items, unicode")
  187. **In auto mode**: infer answers from the task description + codebase context (package.json scripts, existing tests, CLAUDE.md rules). Show inferred answers to user for confirmation. If task is too vague to infer concrete verification methods → **ask, even in auto mode.** A vague task is worse than a 30-second clarification.
  188. **In interactive mode (`-i`)**: ask directly, grouped with role-specific questions.
  189. **In loop mode (`/opc loop`)**: these answers go into `plan.md` per unit, so every tick knows how to verify itself even after context compaction.
  190. Write the finalized acceptance criteria to `acceptance-criteria.md` (in the session dir) and include them in every subagent prompt.
  191. **Design Reproduction Pre-Flight:** When the task involves reproducing/replicating a visual design from a reference image (keywords: 复刻, replicate, reproduce, reference image, 参考图, design reproduction), the orchestrator MUST run these additional init steps:
  192. 1. **Detect reference image** — user provides a path (e.g., `/Users/.../ref.jpg`). Confirm the file exists.
  193. 2. **Extract design spec** — run `analyze_reference.py` to generate a structured spec:
  194. ```bash
  195. python3 ~/.claude/skills/image-x/scripts/analyze_reference.py <ref_image> --output <session_dir>/spec.json
  196. ```
  197. 3. **Write `## Reference` section** in `acceptance-criteria.md`:
  198. ```markdown
  199. ## Reference
  200. - reference_image: /absolute/path/to/ref.jpg
  201. - design_spec: /absolute/path/to/session/spec.json
  202. ```
  203. 4. **Set quality baseline** for design reproduction:
  204. ```markdown
  205. ## Quality Baseline (polished)
  206. - design-diff overall ≥ 4.0
  207. - zero major diffs
  208. ```
  209. This enables the full automated loop: build reads spec.json → implementer produces HTML → test-execute screenshots + VLM design-diff → gate reads diffs → ITERATE feeds diffs back to build. See `./pipeline/executor-protocol.md` § "Design Reproduction Mode" for test-execute details.
  210. **Criteria Lint — Mandatory Gate:** After writing `acceptance-criteria.md`, run `opc-harness criteria-lint acceptance-criteria.md` (use the session dir path). If it fails, revise and re-run (max 3 auto-fix attempts in auto mode, user-driven in interactive mode). See `./pipeline/criteria-lint.md` for the mechanical checks. Init is gated — `opc-harness init` refuses to start if criteria-lint hasn't passed.
  211. ### Task Scope — Mandatory for Loop Mode
  212. In loop mode, every `plan.md` MUST include a `## Task Scope` section listing the user's original requirements:
  213. ```markdown
  214. ## Task Scope
  215. - SCOPE-1: Backend API for user auth
  216. - SCOPE-2: Frontend login page with form validation
  217. - SCOPE-3: Browser E2E tests covering login flow
  218. - SCOPE-4: Unit tests with 100% coverage on new code
  219. ```
  220. The harness enforces this mechanically:
  221. - **init-loop** refuses to start if `## Task Scope` is missing (bypass: `--skip-scope`)
  222. - **complete-tick** on the final tick checks that every SCOPE-N item was covered by at least one completed unit (keyword overlap or explicit reference). Uncovered items = hard error, pipeline cannot complete (bypass: `--skip-scope-check`)
  223. - **next-tick** termination output includes `uncovered_scope` if any items lack coverage
  224. This prevents the #1 failure mode: LLM decomposition misses part of the original task, pipeline declares "complete" while major scope items are untouched.
  225. ### Interactive Mode Details (with `-i`)
  226. Ask targeted questions derived from selected roles — what does each role need that can't be inferred from the codebase? Aim for 3-5 grouped questions, merged with the Definition of Done questions above.
  227. - Engineering roles usually read code directly — no extra context needed.
  228. - Product and user roles benefit most: "Who are your target users?", "What's the product stage?"
  229. - Security and Compliance may need: "Do you handle PII?", "Target markets?"
  230. **Persona construction** for user roles: In auto mode, infer from project context. In interactive mode, ask directly.
  231. ### Project Context
  232. Subagents don't inherit CLAUDE.md or project instructions automatically. When dispatching any subagent, **forward relevant project context**: dev workflow rules, precommit checks, coding conventions, test commands. Include this in every subagent prompt.
  233. ### Superpowers Integration
  234. If `superpowers` skills are available, use them: brainstorming for design, plan writing, subagent-driven development for build, and branch delivery.
  235. ---
  236. ## Built-in Roles
  237. ```
  238. Product: pm, designer
  239. User Lens: new-user, active-user, churned-user
  240. Engineering: frontend, backend, devops, architect, engineer
  241. Quality: security, tester, compliance, a11y
  242. Specialist: planner, user-simulator, devil-advocate
  243. ```
  244. Role definitions live in `roles/<name>.md`. Add a `.md` file to `roles/` to create a custom role.
  245. ### Role Discovery
  246. The orchestrator searches for role definitions in this order (later sources override earlier ones with the same filename):
  247. 1. **Built-in roles** — `roles/<name>.md` in OPC's install directory
  248. 2. **Flow template roles** — if the active flow template specifies `rolesDir`, scan `_resolvedRolesDir/<name>.md`. Custom roles with the same name as a built-in one take precedence for this flow.
  249. 3. **Dynamic roles** — created on-the-fly during execution (see below)
  250. **How to check for custom roles:** After `opc-harness init`, if the flow template was loaded from `~/.claude/flows/`, check `FLOW_TEMPLATES[template]._resolvedRolesDir`. If it exists and is a directory, scan it for `.md` files and merge into the role pool.
  251. **Protocol discovery** works the same way: if the flow template specifies `protocolDir`, protocols in `_resolvedProtocolDir/<name>.md` supplement or override built-in protocols in `pipeline/`.
  252. ### Role Selection
  253. 1. **Tag filter** — from the flow template, you know the node type. Map to stage tags:
  254. | Node type | Stage tags |
  255. |-----------|-----------|
  256. | review | review |
  257. | build | build |
  258. | execute | execute, post-release, verification |
  259. | discussion | brainstorm, plan, discussion |
  260. | gate | (no roles dispatched) |
  261. Read the `tags:` front matter from each `roles/<name>.md`. Keep only roles whose tags include at least one matching stage tag.
  262. 2. **Select from filtered pool** — pick 2-5 roles with distinct angles. Read each candidate's "When to Include" section to decide relevance.
  263. - **Mandatory roles always included** — roles with `mandatory: true` in front matter are auto-included in every review node. The orchestrator cannot remove them. Currently: `skeptic-owner`.
  264. - Each dispatched agent must have a DISTINCT angle. If two would produce 80%+ overlapping output, pick one.
  265. - Not every task needs every role. A CSS fix doesn't need Security.
  266. - **Devil's Advocate auto-inclusion:** When a discussion node reaches Round 2 with near-unanimous agreement (all agents converge on the same approach), the orchestrator SHOULD include devil-advocate in a subsequent review pass. Consensus is a signal to challenge, not to proceed. For irreversible decisions (data deletion, public API contracts, destructive migrations), devil-advocate is MANDATORY.
  267. - If user specified roles explicitly, use those — skip tag filtering entirely.
  268. **Dynamic Role Creation:** If the task requires expertise not covered by any candidate, create a role on-the-fly following the same format (Identity + Expertise + When to Include + Anti-Patterns). Write to `$SESSION_DIR/nodes/{nodeId}/dynamic-role-{name}.md`. Max 5 dynamic roles per flow run.
  269. Show role selection:
  270. ```
  271. 📋 Agents:
  272. - frontend [standard/sonnet] — <specific scope>
  273. - tester [economy/haiku] — <specific scope>
  274. ...
  275. Launching {N} agents...
  276. ```
  277. ---
  278. ## Node Execution
  279. **Auto mode is bounded.** Continue without confirmation only while node and repair-edge budgets remain. Normal graph limits and validation failures still apply.
  280. When the circuit breaker trips, stop and report immediately. Do not retry or attempt recovery from the current Claude session. Recovery requires the user to run an existing `opc-harness stop`, `goto`, `skip`, or `pass` command from an external terminal.
  281. The orchestrator uses **cursor-based execution** — `flow-state.json.currentNode` is the single pointer. No topological sort.
  282. ### Execution Loop
  283. ```
  284. 1. Read flow-state.json → currentNode
  285. 2. Look up currentNode in the flow template table above → get type, agents, protocol
  286. 3. Execute based on node type (see below)
  287. 4. After execution:
  288. - opc-harness validate → check handshake.json
  289. - Update progress.md with narrative line
  290. - opc-harness route --node {current} --verdict PASS --flow {template} → get next
  291. - opc-harness transition --from {current} --to {next} --verdict PASS --flow {template}
  292. - **Show flow viz**: run `opc-harness viz --flow {template}` and display to user
  293. - Loop back to step 1
  294. 5. When route returns next=null → flow complete → Deliver → **Prompt replay** (see below)
  295. ```
  296. ### Node Type: discussion
  297. Follow `./pipeline/discussion-protocol.md`.
  298. 1. Resolve a model route for every participant, then dispatch agents for 3 rounds. **Round 1: parallel** (agents are independent — no reason to serialize). Round 2: serial with context injection (each agent sees Round 1 outputs, writes diffs only). Round 3: facilitator convergence.
  299. 2. **Orchestrator writes handshake.json** after collecting all artifacts (agents don't write it).
  300. 3. Discussion nodes produce no verdict — the decision artifact feeds downstream.
  301. ### Node Type: build
  302. Follow `./pipeline/implementer-prompt.md` in Build/Fix/Polish mode.
  303. 1. Resolve the implementer's model route and dispatch it with the returned explicit model.
  304. 2. **Single agent** → agent writes its own handshake.json.
  305. 3. **Multiple agents** (parallel, with `isolation: "worktree"`) → orchestrator merges artifacts and writes handshake.json.
  306. 4. With superpowers: invoke `superpowers:subagent-driven-development`.
  307. 5. **After committing delivered code**, run `opc-harness record-commit --sha <sha>` (or bare, defaulting to HEAD) so the terminal gate's changeScopeCoverage layer scopes to what this flow produced instead of a blind `HEAD~1` diff. Skip only if the build committed nothing.
  308. ### Node Type: review
  309. Follow `./pipeline/role-evaluator-prompt.md`.
  310. 1. Select roles per Role Selection rules.
  311. 2. Resolve a model route for each selected role, then dispatch evaluators — parallel if no dependencies, serial with context injection if dependencies exist.
  312. 3. Each agent writes `eval-{role}.md` to `$SESSION_DIR/nodes/{NODE_ID}/run_{RUN}/`.
  313. 4. **Orchestrator writes handshake.json** after all agents return, merging all eval files into artifacts[].
  314. 5. Before dispatching, build context brief using `./pipeline/context-brief.md` (for review/analysis tasks).
  315. **Critical — Review Independence:**
  316. - Review MUST use independent subagents (Agent tool), never the orchestrator reviewing its own build output.
  317. - In loop mode, review MUST be a separate tick/unit from implementation. Never combine build + review in one tick.
  318. - The orchestrator MUST NOT filter, downgrade, or dismiss findings before writing the handshake. All findings pass through to the gate.
  319. ### Node Type: execute
  320. Follow `./pipeline/executor-protocol.md`.
  321. **Executor nodes are executed by the orchestrator directly — not as a subagent.** This is because executors need full tool access (Bash, Playwright, Skills).
  322. 1. Smoke test tool availability.
  323. 2. Execute acceptance criteria scenarios.
  324. 3. Capture evidence (CLI output, screenshots).
  325. 4. **Orchestrator writes handshake.json** with evidence artifacts.
  326. 5. Handshake validation enforces: execute nodes must have evidence artifacts.
  327. ### Node Type: gate
  328. Follow `./pipeline/gate-protocol.md`.
  329. **Gate nodes are executed by the orchestrator directly — no subagent dispatch.**
  330. 1. `opc-harness synthesize --node {upstream}` → get verdict.
  331. 2. Mechanical validation (severity emojis, file refs, fix suggestions).
  332. 3. `opc-harness route --node {gate} --verdict {V} --flow {template}` → get next node.
  333. 4. `opc-harness transition --from {gate} --to {next} --verdict {V} --flow {template}` → validates edge, writes gate handshake, updates state.
  334. 5. Notify user: pass/loopback/done/blocked.
  335. ---
  336. ## Verdict & Loopback
  337. Gate nodes produce verdicts via `opc-harness synthesize` (code, not LLM judgment):
  338. - Any 🔴 → FAIL
  339. - Any 🟡 → ITERATE
  340. - All 🔵/LGTM → PASS
  341. - Any BLOCKED → BLOCKED
  342. **Code enforces all limits:**
  343. - `maxLoopsPerEdge` = 3 (same edge can't be traversed more than 3 times)
  344. - `maxTotalSteps` = 20-30 (depending on flow template)
  345. - `maxNodeReentry` = 5 (same node can't be entered more than 5 times)
  346. **Oscillation detection:** After a loopback, run `opc-harness diff` on consecutive evaluations. If `oscillation: true`, surface to user.
  347. **Escape hatches:**
  348. - `/opc skip` — skip current node, advance via PASS edge
  349. - `/opc pass` — force gate to PASS
  350. - `/opc stop` — terminate flow, preserve state
  351. - `/opc goto <nodeId>` — manual jump (cycle limits still enforced via `transition`)
  352. When transition returns `allowed: false` → show the user why (which limit hit) and offer escape options. Never continue without user consent.
  353. ---
  354. ## File-Based State
  355. ```
  356. $SESSION_DIR/ # ~/.opc/sessions/{hash}/{id}/ or .harness/ if --dir used
  357. ├── flow-state.json # Current node, execution history, edge counts, limits
  358. ├── progress.md # Human-readable narrative log
  359. └── nodes/
  360. └── {nodeId}/
  361. ├── handshake.json # Machine-readable envelope (summary + verdict + artifact paths)
  362. └── run_{N}/
  363. ├── eval.md # Single evaluator output (detailed findings)
  364. ├── eval-{role}.md # Per-role evaluator output (multi-role)
  365. ├── round-1-{role}.md # Discussion round 1
  366. ├── round-2-{role}.md # Discussion round 2 (diffs only)
  367. ├── decision.md # Discussion facilitator decision
  368. ├── screenshot-{N}.png # Executor GUI evidence
  369. └── command-output-{N}.txt # Executor CLI evidence
  370. ```
  371. **Relationships:**
  372. - `handshake.json` = envelope. Its `artifacts[]` points to detailed files (eval.md, screenshots, etc.)
  373. - `flow-state.json` = sole source of truth for execution position and history
  374. - `eval.md` / `eval-{role}.md` = human-readable findings (read by `synthesize` to compute verdict)
  375. - `progress.md` = narrative projection of flow execution (for humans)
  376. ---
  377. ## Prompt Templates
  378. All templates live in `./pipeline/`:
  379. - `evaluator-prompt.md` — Single generic evaluator
  380. - `role-evaluator-prompt.md` — Role-specific evaluator (review, analysis, brainstorm outputs)
  381. - `implementer-prompt.md` — Implementer (Build / Fix / Polish modes)
  382. - `discussion-protocol.md` — Multi-agent discussion (round-robin, 3 rounds, facilitator)
  383. - `gate-protocol.md` — Verdict aggregation + code-based routing + transition + **findings disposition**
  384. - `executor-protocol.md` — CLI/GUI execution with evidence requirements
  385. - `test-design-protocol.md` — **Test case design** (review node, multi-role test planning before execution)
  386. - `loop-protocol.md` — **Autonomous multi-unit execution** (plan decomposition → cron loop → auto-terminate)
  387. - `handoff-template.md` — Handshake.json specification
  388. - `context-brief.md` — Design context brief procedure
  389. - `model-routing.md` — Explicit per-node/per-role model selection and premium approval
  390. - `report-format.md` — Presentation templates + JSON schema + replay
  391. - `quality-tiers.md` — Tier definitions + baseline checklists + severity calibration
  392. - `ux-simulation-protocol.md` — **UX simulation gate** (red flag detection, delta comparison, ordinal tier fit)
  393. - `ux-observer-protocol.md` — **UX observer dispatch** (persona-based pattern observation, closed enum red flags)
  394. - `criteria-lint.md` — **DoD mechanical lint** (single-pass structure + content checks, pre-init gate)
  395. ---
  396. ## External Flow Templates
  397. Custom flows can be defined as JSON files in `~/.claude/flows/`. The harness loads them at startup and merges them into the template registry. Built-in templates take precedence (external cannot override).
  398. **JSON schema:**
  399. ```json
  400. {
  401. "nodes": ["discover", "build", "review", "gate"],
  402. "edges": {
  403. "discover": { "PASS": "build" },
  404. "build": { "PASS": "review" },
  405. "review": { "PASS": "gate" },
  406. "gate": { "PASS": null, "FAIL": "build", "ITERATE": "build" }
  407. },
  408. "limits": { "maxLoopsPerEdge": 3, "maxTotalSteps": 20, "maxNodeReentry": 5 },
  409. "nodeTypes": {
  410. "discover": "discussion", "build": "build",
  411. "review": "review", "gate": "gate"
  412. },
  413. "softEvidence": true,
  414. "opc_compat": ">=0.10",
  415. "contextSchema": {
  416. "build": {
  417. "required": ["task"],
  418. "rules": { "task": "non-empty-string" }
  419. }
  420. }
  421. }
  422. ```
  423. **Validation rules:**
  424. - `nodes`, `edges`, `limits` are required
  425. - All edge sources and targets must be in `nodes`
  426. - `nodeTypes` values must be: `discussion`, `build`, `review`, `execute`, `gate`
  427. - `opc_compat` uses `>=X.Y` semver range (current harness compatibility: 0.10.0)
  428. - Prototype pollution names (`__proto__`, `constructor`, `prototype`) are rejected
  429. **Optional fields:**
  430. - `softEvidence: true` — downgrades missing-evidence errors to warnings for execute nodes
  431. - `contextSchema` — per-node validation rules for `flow-context.json`
  432. - `opc_compat` — minimum harness version required
  433. **contextSchema rules:**
  434. - `non-empty-string` — must be a non-empty string
  435. - `non-empty-array` — must be a non-empty array
  436. - `non-empty-object` — must be a non-empty plain object (not array)
  437. - `positive-integer` — must be a positive integer > 0
  438. ---
  439. ## Harness Command Reference
  440. All commands output JSON to stdout. Errors go to stderr. All output is machine-parseable.
  441. ### Flow Commands
  442. | Command | Usage | Description |
  443. |---------|-------|-------------|
  444. | `init` | `--flow <tpl> [--entry <node>] [--dir <p>]` | Initialize flow state. Creates `flow-state.json` and node directories. Seeds `baseSha` (git floor) and empty `producedCommits`. |
  445. | `record-commit` | `[--sha <sha>] [--dir <p>]` | Record a commit the flow produced into `flow-state.producedCommits`. Defaults to HEAD; dedups; fail-closed on invalid sha. The gate's changeScopeCoverage layer scopes to these commits. |
  446. | `route` | `--node <id> --verdict <V> --flow <tpl>` | Get next node from graph edges. Returns `{next, allowed}`. |
  447. | `transition` | `--from <n> --to <n> --verdict <V> --flow <tpl> --dir <p>` | Execute state transition. Validates edge, checks limits, writes gate handshake, enforces backlog. |
  448. | `validate` | `<handshake.json>` | Validate handshake schema (required fields, evidence check for execute nodes). |
  449. | `validate-chain` | `[--dir <p>]` | Validate entire execution path — checks all handshakes match history. |
  450. | `validate-context` | `--flow <tpl> --node <id> [--dir <p>]` | Validate `flow-context.json` against contextSchema rules. |
  451. | `finalize` | `[--dir <p>] [--strict]` | Finalize terminal node. Marks flow as completed. |
  452. | `viz` | `--flow <tpl> [--dir <p>] [--json]` | Visualize flow graph (ASCII or JSON). Shows ▶ current, ✅ visited, ○ pending. |
  453. | `replay` | `[--dir <p>]` | Export full replay data as JSON (flow state + handshakes + run artifacts). |
  454. ### Escape Hatches
  455. | Command | Usage | Description |
  456. |---------|-------|-------------|
  457. | `skip` | `[--dir <p>] [--flow <tpl>]` | Skip current node, advance via PASS edge. Writes skip handshake. |
  458. | `pass` | `[--dir <p>]` | Force-pass current gate node. Only works on gate-type nodes. |
  459. | `stop` | `[--dir <p>]` | Terminate flow, preserve state. Sets status to "stopped". |
  460. | `goto` | `<nodeId> [--dir <p>]` | Manual jump to any node. Cycle limits still enforced. |
  461. | `ls` | `[--base <p>]` | List all active flows (scans `~/.opc/sessions/` and project-local `.harness*` directories). |
  462. ### Eval Commands
  463. | Command | Usage | Description |
  464. |---------|-------|-------------|
  465. | `verify` | `<file>` | Parse evaluation markdown → JSON (severity counts, verdict, findings). |
  466. | `synthesize` | `<dir> --node <id> [--run N] [--base <dir>] [--no-strict] [--iteration N]` | Merge all evaluations for a node → aggregate verdict. D2 compound gate enforced by default (≥3 layers → FAIL); `--no-strict` for shadow mode. `--base` validates file:line refs. |
  467. | `report` | `<dir> --mode <m> --task <t>` | Generate full report JSON with presentation data. |
  468. | `diff` | `<file1> <file2>` | Compare two evaluation rounds. Detects oscillation. |
  469. ### Loop Commands (Layer 2 — Zero Trust)
  470. | Command | Usage | Description |
  471. |---------|-------|-------------|
  472. | `init-loop` | `[--plan <file>] [--dir <p>]` | Initialize loop state from plan.md. Validates plan structure, detects test/lint scripts. |
  473. | `complete-tick` | `--unit <id> --artifacts <a,b> [--description <text>] [--dir <p>]` | Complete tick with evidence. Validates artifacts per unit type, checks plan hash, overlap detection. |
  474. | `next-tick` | `[--dir <p>]` | Get next unit. Checks stall/oscillation, returns `{ready, unit, terminate}`. |
  475. ### Transition Details
  476. The `transition` command enforces:
  477. - **Edge validation** — only declared edges are allowed
  478. - **Cycle limits** — `maxLoopsPerEdge`, `maxTotalSteps`, `maxNodeReentry`
  479. - **Idempotency** — repeated identical transitions are silently accepted
  480. - **Gate detection** — uses `nodeTypes[from] === "gate"` (not name prefix)
  481. - **Pre-transition validation** — upstream handshake must exist and be valid
  482. - **Backlog enforcement** — if upstream has warnings, `backlog.md` must exist for FAIL/ITERATE transitions
  483. ---
  484. ## Resilience
  485. **Agent spawn failures:** Retry once. If it fails again, surface to user.
  486. **Context compaction resilience:** `opc install-hooks` always registers the Node-based `PreToolUse` guard required by auto flows. When `jq` is available, it also registers optional PreCompact/PostCompact shell hooks that snapshot state and inject resume context after compaction. When auto-compact fires:
  487. 1. **PreCompact** writes a resume brief to `$SESSION_DIR/resume-brief.md`
  488. 2. **PostCompact** injects the brief as `additionalContext` into the new context
  489. 3. The orchestrator sees the injection and resumes the flow automatically
  490. If the optional compaction hooks are unavailable, flow-state.json still persists on disk, but the orchestrator must be manually re-invoked via `/opc` (which runs `opc-harness ls` to discover active flows).
  491. **State recovery:** On resume, run `opc-harness validate-chain`. If inconsistent → surface to user, do not auto-repair.
  492. **Legacy detection:** If `.harness/` in project root has `wave-*` files but no `flow-state.json` → refuse to run. Print migration instructions.
  493. **Fresh context per agent.** Always spawn new subagents. Files carry state; agents bring fresh capacity.
  494. ---
  495. ## Flow Completion & Replay
  496. When the flow completes (route returns `next=null`):
  497. 1. Show final viz: `opc-harness viz --flow {template}`
  498. 2. Show summary: total steps, nodes visited, any loopbacks, and dispatched agent counts by model tier
  499. 3. **Generate HTML report** (use the session dir from init output, or find it via `opc-harness ls`):
  500. ```bash
  501. node "$OPC_HARNESS/../opc-report.mjs" --dir <session-dir> --output <session-dir>/report.html --title "{task summary}"
  502. ```
  503. This produces a self-contained dark-theme HTML report with mechanically parsed stats, pipeline visualization, findings tables, and R2 fix tracking. Open it for the user.
  504. 4. **Prompt the user:**
  505. ```
  506. ✅ Flow complete! Report: $SESSION_DIR/report.html
  507. Want to see the replay? Run: /opc replay
  508. ```
README.md · README · 567 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OPC — One Person Company
  2. > A full team in a single Claude Code skill. You're the CEO — OPC is everyone else.
  3. 21 built-in roles (PM, Designer, Security, Devil's Advocate, and more) that build, review, and evaluate your code through a digraph-based pipeline with code-enforced quality gates.
  4. [English](#english) | [中文](#中文)
  5. ---
  6. ## English
  7. ### What you can build
  8. From a **single one-line brief**, OPC's `build-verify` flow ships a complete, production-quality product — design tokens injected and visual quality validated by the [design-intelligence](docs/extension-authoring.md) extension. Every screenshot below is a **real, clickable site** (not a mockup), built by the same 21-role pipeline. Same system, six completely different design languages.
  9. **▶ [Browse the live lookbook →](https://www.touchskyer.me/projects/opc/lookbook)**
  10. <table>
  11. <tr>
  12. <td width="50%" valign="top">
  13. <a href="https://www.touchskyer.me/projects/opc/lookbook/saas-dashboard/index.html"><img src="docs/assets/showcase/saas-dashboard.png" alt="Pulse — a SaaS analytics dashboard generated by OPC"></a>
  14. <br><b>Pulse</b> · SaaS analytics dashboard<br><sub>Dark UI · data-viz</sub>
  15. </td>
  16. <td width="50%" valign="top">
  17. <a href="https://www.touchskyer.me/projects/opc/lookbook/creative-portfolio/index.html"><img src="docs/assets/showcase/creative-portfolio.png" alt="Studio Kura — a creative agency portfolio generated by OPC"></a>
  18. <br><b>Studio Kura</b> · Creative agency portfolio<br><sub>Brutalist · editorial · motion</sub>
  19. </td>
  20. </tr>
  21. <tr>
  22. <td width="50%" valign="top">
  23. <a href="https://www.touchskyer.me/projects/opc/lookbook/cumulus/index.html"><img src="docs/assets/showcase/cumulus.png" alt="Cumulus — a SaaS project-management dashboard generated by OPC"></a>
  24. <br><b>Cumulus</b> · Project-management dashboard<br><sub>Claymorphism · pastel</sub>
  25. </td>
  26. <td width="50%" valign="top">
  27. <a href="https://www.touchskyer.me/projects/opc/lookbook/devtool-docs/index.html"><img src="docs/assets/showcase/devtool-docs.png" alt="Conduit Docs — a developer documentation site generated by OPC"></a>
  28. <br><b>Conduit Docs</b> · Developer documentation<br><sub>Docs · code · developer</sub>
  29. </td>
  30. </tr>
  31. <tr>
  32. <td width="50%" valign="top">
  33. <a href="https://www.touchskyer.me/projects/opc/lookbook/dtc-brand/index.html"><img src="docs/assets/showcase/dtc-brand.png" alt="Maison Terre — a DTC skincare e-commerce site generated by OPC"></a>
  34. <br><b>Maison Terre</b> · DTC skincare e-commerce<br><sub>Brand · editorial</sub>
  35. </td>
  36. <td width="50%" valign="top">
  37. <a href="https://www.touchskyer.me/projects/opc/lookbook/local-booking/index.html"><img src="docs/assets/showcase/local-booking.png" alt="Yuzuki — a local dining platform generated by OPC"></a>
  38. <br><b>Yuzuki 柚月</b> · Local dining platform<br><sub>Booking · bilingual · mobile</sub>
  39. </td>
  40. </tr>
  41. </table>
  42. > Each card in the [lookbook](https://www.touchskyer.me/projects/opc/lookbook) flips on hover to reveal the **exact prompt** that built it — e.g. Pulse came from one line: `/opc build a production-quality SaaS analytics dashboard called "Pulse"...`
  43. **OPC isn't only for UIs.** The same zero-trust pipeline also handles:
  44. - **Whole products, unattended** — `/opc loop build features F1–F4 from PLAN.md` decomposes the work, schedules a durable cron, and runs **10+ hours** without you.
  45. - **Code review** — `/opc review the auth changes` dispatches 2–5 independent role agents (security, backend, a11y, devil's advocate) in parallel and computes a mechanical verdict.
  46. - **Full-stack features** — `/opc implement user auth with email/password` runs build → independent review → test-design → test-execute → gate.
  47. - **Pre-release audits** — `/opc verify before release` runs acceptance + audit + e2e gates before you ship.
  48. ### How It Works
  49. One principle: **the agent that does the work never evaluates it.**
  50. ```
  51. Task → Flow Selection → Node Execution → Gate Verdict → Route Next
  52. ↑ ↓
  53. └──────── ITERATE/FAIL ────────┘
  54. ```
  55. 1. **Task inference** — reads your request, picks a flow template (quick, review, build-verify, full-stack, pre-release), and enters at the right node.
  56. 2. **Typed nodes** — each node has a type (discussion, build, review, execute, gate) with specific protocols. Build nodes produce commits. Review nodes dispatch parallel subagents. Gate nodes compute verdicts from code, not LLM judgment.
  57. 3. **Mechanical gates** — verdicts are computed by `opc-harness synthesize`: any red = FAIL, any yellow = ITERATE, all green = PASS. No LLM gets to decide if a finding is "important enough."
  58. 4. **Cycle limits** — max 3 loops per edge, 5 re-entries per node, 20-30 total steps depending on flow. Oscillation detection catches A↔B loops.
  59. #### Quality Architecture
  60. ![Zero-Trust Quality Architecture](docs/assets/design_philosophy.png)
  61. The system is built on a zero-trust axiom: **every critical output must have an independent verification path.** Four layers:
  62. - **L0 — Zero Trust**: Decision axiom — not code, not prompt. Every critical output needs an independent verification path.
  63. - **L1 — Shape Single Agent**: Intervene during token generation — persona setting, anti-pattern tables, mandatory output structure, scope anchoring, quality gates.
  64. - **L2 — Design Agent Flow**: Multi-agent coordination — separation of concerns, flow topology (parallel review / sequential build), context isolation (file-based handoff, fresh agents, no session reuse).
  65. - **L3 — Deterministic Enforcement**: The only layer that doesn't need LLM compliance — mechanical ops (severity counting, verdict rules, oscillation diff) and hardened verification (file-finding evidence checks, hedging scans, ref validation).
  66. #### Model-aware dispatch
  67. OPC preserves its full multi-agent topology while avoiding accidental premium-model fan-out. Before every Agent call, `opc-harness model-route` resolves an explicit host-native model from layered configuration:
  68. | Tier | Claude Code default | Typical work |
  69. |---|---|---|
  70. | economy | `haiku` | test design, user/UX observers |
  71. | standard | `sonnet` | discussion, implementation, semantic review |
  72. | premium | `inherit` | explicit escalation only |
  73. `inherit` and `opus` require explicit premium approval. Claude Code's `CLAUDE_CODE_SUBAGENT_MODEL` environment override is detected and reported. Other hosts can replace the tier values with their own model IDs:
  74. ```json
  75. {
  76. "agentRouting": {
  77. "models": {
  78. "economy": "your-fast-model-id",
  79. "standard": "your-value-model-id",
  80. "premium": "your-premium-model-id"
  81. }
  82. }
  83. }
  84. ```
  85. See [`pipeline/model-routing.md`](pipeline/model-routing.md) for node/role overrides and the resolver contract.
  86. ### Quick Start
  87. #### Install
  88. ```bash
  89. npm install -g @touchskyer/opc
  90. ```
  91. Skill files are automatically copied to `~/.claude/skills/opc/`.
  92. Recent npm versions block install scripts by default — if the copy is skipped (check: `opc --version` prints but `~/.claude/skills/opc/SKILL.md` is missing), rerun with `npm install -g --allow-scripts=@touchskyer/opc`, or just run `opc install` once afterwards.
  93. ##### Manual install (no npm)
  94. ```bash
  95. git clone https://github.com/iamtouchskyer/opc.git
  96. cp -r opc ~/.claude/skills/opc
  97. ```
  98. #### Use it
  99. ```bash
  100. # Review — dispatches 2-5 role agents in parallel
  101. /opc review the auth changes
  102. # Build — implements + independent review + gate
  103. /opc implement user authentication with email/password
  104. # Autonomous loop — decomposes, schedules cron, runs unattended
  105. /opc loop build features F1-F4 from PLAN.md
  106. # Interactive mode — asks clarifying questions first
  107. /opc -i redesign the onboarding flow
  108. # Explicit roles
  109. /opc security devil-advocate
  110. # Flow control
  111. /opc skip # skip current node
  112. /opc pass # force-pass gate
  113. /opc stop # terminate, preserve state
  114. /opc goto build # jump to node
  115. ```
  116. ### Autonomous Loop
  117. ```bash
  118. /opc loop build the math tutoring app features F1-F4
  119. ```
  120. What happens:
  121. 1. **Runbook lookup** — `opc-harness runbook match "<task>"` checks `--dir` flag → `OPC_RUNBOOKS_DIR` → `~/.opc/runbooks/` for a matching recipe. If one hits, its `units` / `flow` / `tier` become the plan; otherwise fall through to step 2. Disable per-invocation with `OPC_DISABLE_RUNBOOKS=1`. See [docs/runbooks.md](docs/runbooks.md) and [examples/runbooks/add-feature.md](examples/runbooks/add-feature.md).
  122. 2. **Decompose** (runbook miss only) — breaks task into atomic units (spec, implement, review, fix, e2e)
  123. 3. **Definition of done** — establishes verify/eval criteria per unit before any work starts
  124. 4. **Schedule** — durable cron (survives process restart) fires every 10 min
  125. 5. **Execute** — each tick runs one unit through the appropriate OPC flow
  126. 6. **Guard** — `opc-harness` enforces: git commit required, ≥2 independent reviewers, no plan tampering, no state forgery, artifact freshness, tick limits
  127. 7. **Terminate** — auto-stops when plan complete, tick limit hit, or wall-clock deadline reached
  128. For well-scoped tasks, the system runs **10+ hours continuously** without intervention.
  129. #### Guardrails (code-enforced, not prompt-level)
  130. | Guard | Enforcement |
  131. |-------|-------------|
  132. | Write nonce | Random SHA256 at init; state written by harness only |
  133. | Atomic writes | write → rename (POSIX atomic); no truncated JSON on crash |
  134. | Plan integrity | SHA256 hash at init; verified every tick |
  135. | Review independence | ≥2 eval files, identical content rejected, line overlap warned |
  136. | Git commit required | HEAD must change for implement/fix units |
  137. | Screenshot required | UI units must produce .png/.jpg artifact |
  138. | Tick limits | maxTotalTicks (units×3) + 24h wall-clock deadline |
  139. | Oscillation detection | A↔B pattern over 4-6 ticks = warning/hard stop |
  140. | Concurrent tick mutex | in_progress status blocks overlapping cron fires |
  141. | JSON crash recovery | try/catch on all JSON.parse; structured errors, not crashes |
  142. | External validators | Pre-commit hooks, test suites detected at init and leveraged |
  143. ### Flow Templates
  144. | Template | Nodes | When |
  145. |----------|-------|------|
  146. | **quick** | build → review → gate | "quick fix", "small change", one-liner, ≤3 files, **non-UI, no logic branches** |
  147. | **review** | code-review → gate | PR review, audit, "find problems" |
  148. | **build-verify** | brief → build → code-review → test-design → test-execute; ITERATE → hotfix → test-execute; PASS → gate | "implement X", "fix bug Y" |
  149. | **full-stack** | discuss → build → review → test → acceptance → audit → e2e → gates | Complex/vague requests |
  150. | **pre-release** | acceptance → audit → e2e → gates | "verify before release" |
  151. **`quick` vs `build-verify`** — `quick` drops the structured `brief` node and the
  152. `test-design`/`test-execute` split, halving nodes and evaluator dispatches. It keeps
  153. the core quality gate (independent `review` + `gate` verdict). Use it only for true
  154. one-liners / single-file, non-UI, no-logic-branch changes. Anything with logic
  155. branches, multiple files, or UI → use `build-verify`, where `test-design`'s enforced
  156. L1–L5 coverage check earns its keep.
  157. The **`brief`** node (entry of `build-verify`) produces a structured build brief —
  158. resolved design tokens, file plan, component inventory, constraints — that the
  159. `build` node follows. It measurably lifts first-pass build fidelity, but the brief
  160. describes *intended* behavior: downstream `test-design` must test the **actual built
  161. code**, not the brief's ideal, or it will assert behavior the build never implemented.
  162. ### Extensions
  163. OPC has a capability-routed extension surface. Extensions live in
  164. `~/.claude/skills/opc-extension/<name>/` — each with `ext.json` (capability
  165. declarations) + `hook.mjs` exporting any of `promptAppend` / `verdictAppend`
  166. / `executeRun` / `artifactEmit` hooks. No fork, no rebuild. Hooks are
  167. sandboxed via per-extension timeouts + circuit breakers, so a broken
  168. third-party extension can't take down the harness.
  169. `ext.json.version` is recorded in `flow-state.json → extensionVersions` during
  170. `init`, so protocol reports can distinguish "extension loaded" from "unknown
  171. version". Executable hook metadata from `hook.mjs` still wins for runtime
  172. capability behavior.
  173. The companion repo **opc-extensions** (private) ships 6 extensions: `design-intelligence` (theme injection + design coverage + VLM visual eval), `dataviz-x`, `git-changeset-review`, `memex-recall`, `perf-budget`, and `quality-reality`.
  174. Full authoring guide: **[docs/extension-authoring.md](docs/extension-authoring.md)** — zero-OPC-context
  175. quickstart + reference, plus a starter template at `examples/extensions/_starter/`.
  176. ### Built-in Roles
  177. ```
  178. Product: pm, designer
  179. User Lens: new-user, active-user, churned-user, user-simulator
  180. Engineering: frontend, backend, devops, architect, engineer, mobile
  181. Quality: security, tester, compliance, a11y, skeptic-owner
  182. Specialist: planner, investor, dd-engineer, devil-advocate
  183. ```
  184. **Devil's Advocate** is auto-included when consensus is near-unanimous or decisions are irreversible. Comes with an automated verification script that checks its own findings.
  185. #### Custom Roles
  186. Add a `.md` file to `roles/`:
  187. ```markdown
  188. ---
  189. tags: [review, build]
  190. ---
  191. # Role Name
  192. ## Identity
  193. One sentence: who you are and what you care about.
  194. ## Expertise
  195. - **Area** — what you know about it
  196. ## When to Include
  197. - Condition that triggers this role
  198. ```
  199. Available immediately, no configuration needed.
  200. ### Testing
  201. ```bash
  202. bash test/run-all.sh
  203. ```
  204. 100+ test files covering init-loop, complete-tick, next-tick, review independence, JSON crash recovery, compound defense, scope registry, criteria lint, pipeline E2E lint, D2 calibration, release packaging, and orchestrator-level E2E flow tests.
  205. ### Requirements
  206. - [Claude Code](https://claude.ai/code) (CLI, desktop app, or IDE extension)
  207. - Node.js >= 18
  208. - Core runtime has no npm dependencies, no MCP server, no build step
  209. - `opc install-hooks` always installs the Node-based auto-flow guard; optional `jq` additionally enables context-compaction hooks
  210. ### Works better with memex (optional)
  211. OPC works standalone — pair it with [memex](https://github.com/iamtouchskyer/memex) for cross-session memory. Memex remembers which roles were useful, which findings were false positives, and your project-specific context.
  212. ```bash
  213. npm install -g @touchskyer/memex
  214. ```
  215. ### What's New
  216. See [CHANGELOG.md](CHANGELOG.md) for version history.
  217. ### Community
  218. Using OPC? Share your setup in [Discussions → Show and tell](https://github.com/iamtouchskyer/opc/discussions/categories/show-and-tell). Questions go in [Q&A](https://github.com/iamtouchskyer/opc/discussions/categories/q-a). Feature ideas in [Ideas](https://github.com/iamtouchskyer/opc/discussions/categories/ideas).
  219. ### License
  220. MIT
  221. ---
  222. ## 中文
  223. ### 你能用它造什么
  224. 从**一句话需求**出发,OPC 的 `build-verify` 流程就能交付一个完整、生产级的产品——设计令牌(design token)由 [design-intelligence](docs/extension-authoring.md) 扩展注入、视觉质量由它验证。下面每一张截图都是**真实可点击的站点**(不是设计稿),由同一套 21 角色流水线构建。同一套系统,六种完全不同的设计语言。
  225. **▶ [浏览在线作品集 →](https://www.touchskyer.me/projects/opc/lookbook)**
  226. <table>
  227. <tr>
  228. <td width="50%" valign="top">
  229. <a href="https://www.touchskyer.me/projects/opc/lookbook/saas-dashboard/index.html"><img src="docs/assets/showcase/saas-dashboard.png" alt="Pulse —— OPC 生成的 SaaS 分析仪表盘"></a>
  230. <br><b>Pulse</b> · SaaS 分析仪表盘<br><sub>暗色 UI · 数据可视化</sub>
  231. </td>
  232. <td width="50%" valign="top">
  233. <a href="https://www.touchskyer.me/projects/opc/lookbook/creative-portfolio/index.html"><img src="docs/assets/showcase/creative-portfolio.png" alt="Studio Kura —— OPC 生成的创意工作室作品集"></a>
  234. <br><b>Studio Kura</b> · 创意工作室作品集<br><sub>粗野主义 · 编辑风 · 动效</sub>
  235. </td>
  236. </tr>
  237. <tr>
  238. <td width="50%" valign="top">
  239. <a href="https://www.touchskyer.me/projects/opc/lookbook/cumulus/index.html"><img src="docs/assets/showcase/cumulus.png" alt="Cumulus —— OPC 生成的项目管理仪表盘"></a>
  240. <br><b>Cumulus</b> · 项目管理仪表盘<br><sub>黏土拟态 · 柔和色彩</sub>
  241. </td>
  242. <td width="50%" valign="top">
  243. <a href="https://www.touchskyer.me/projects/opc/lookbook/devtool-docs/index.html"><img src="docs/assets/showcase/devtool-docs.png" alt="Conduit Docs —— OPC 生成的开发者文档站"></a>
  244. <br><b>Conduit Docs</b> · 开发者文档站<br><sub>文档 · 代码 · 开发者</sub>
  245. </td>
  246. </tr>
  247. <tr>
  248. <td width="50%" valign="top">
  249. <a href="https://www.touchskyer.me/projects/opc/lookbook/dtc-brand/index.html"><img src="docs/assets/showcase/dtc-brand.png" alt="Maison Terre —— OPC 生成的护肤品 DTC 电商站"></a>
  250. <br><b>Maison Terre</b> · 护肤品 DTC 电商<br><sub>品牌 · 编辑风</sub>
  251. </td>
  252. <td width="50%" valign="top">
  253. <a href="https://www.touchskyer.me/projects/opc/lookbook/local-booking/index.html"><img src="docs/assets/showcase/local-booking.png" alt="Yuzuki 柚月 —— OPC 生成的本地餐饮平台"></a>
  254. <br><b>Yuzuki 柚月</b> · 本地餐饮平台<br><sub>预订 · 双语 · 移动端</sub>
  255. </td>
  256. </tr>
  257. </table>
  258. > [作品集](https://www.touchskyer.me/projects/opc/lookbook)里每张卡片悬停时会翻面,露出**生成它的原始 prompt**——比如 Pulse 就来自一句话:`/opc build a production-quality SaaS analytics dashboard called "Pulse"...`
  259. **OPC 不只是用来做 UI。** 同一套零信任流水线还能:
  260. - **无人值守造完整产品** —— `/opc loop build features F1–F4 from PLAN.md` 拆解任务、调度持久 cron,**连续运行 10+ 小时**无需干预。
  261. - **代码审查** —— `/opc review the auth changes` 并行派发 2–5 个独立角色 agent(security、backend、a11y、devil's advocate),用代码计算裁决。
  262. - **全栈功能** —— `/opc implement user auth with email/password` 跑 build → 独立 review → test-design → test-execute → gate。
  263. - **发布前审计** —— `/opc verify before release` 在上线前跑 acceptance + audit + e2e 门禁。
  264. ### 工作原理
  265. 一条原则:**做事的 agent 永远不评判自己的工作。**
  266. ```
  267. Task → Flow Selection → Node Execution → Gate Verdict → Route Next
  268. ↑ ↓
  269. └──────── ITERATE/FAIL ────────┘
  270. ```
  271. 1. **任务推断** —— 读取你的请求,选一个 flow 模板(quick、review、build-verify、full-stack、pre-release),从正确的节点进入。
  272. 2. **类型化节点** —— 每个节点有类型(discussion、build、review、execute、gate)和特定协议。build 节点产出 commit;review 节点派发并行 subagent;gate 节点用代码而非 LLM 判断计算裁决。
  273. 3. **机械门禁** —— 裁决由 `opc-harness synthesize` 计算:任意 red = FAIL,任意 yellow = ITERATE,全 green = PASS。没有任何 LLM 能决定某个发现"是否足够重要"。
  274. 4. **循环上限** —— 每条边最多 3 次循环,每个节点最多 5 次重入,按 flow 总步数 20-30。震荡检测捕获 A↔B 循环。
  275. #### 质量架构
  276. ![零信任质量架构](docs/assets/design_philosophy.png)
  277. 系统建立在一条零信任公理上:**每个关键输出都必须有独立的验证路径。** 四层:
  278. - **L0 —— 零信任**:决策公理——不是代码,不是 prompt。每个关键输出都需要独立的验证路径。
  279. - **L1 —— 塑造单个 agent**:在 token 生成过程中干预——人格设定、反模式表、强制输出结构、范围锚定、质量门禁。
  280. - **L2 —— 设计 agent 流**:多 agent 协同——关注点分离、流拓扑(并行 review / 串行 build)、上下文隔离(基于文件的交接、全新 agent、不复用 session)。
  281. - **L3 —— 确定性强制**:唯一不需要 LLM 配合的一层——机械操作(严重度计数、裁决规则、震荡 diff)和加固验证(找文件证据检查、模糊措辞扫描、引用校验)。
  282. #### 模型感知派发
  283. OPC 保留完整的多 agent 拓扑,同时避免顶级模型被意外放大到所有子 agent。每次调用 Agent 前,`opc-harness model-route` 都会从分层配置中解析一个明确的宿主原生模型:
  284. | 层级 | Claude Code 默认值 | 典型工作 |
  285. |---|---|---|
  286. | economy | `haiku` | 测试设计、用户/UX observer |
  287. | standard | `sonnet` | 讨论、实现、语义审查 |
  288. | premium | `inherit` | 仅显式升级 |
  289. `inherit` 和 `opus` 需要显式批准。Claude Code 的 `CLAUDE_CODE_SUBAGENT_MODEL` 环境变量覆盖会被检测并展示。其他宿主可以在 `agentRouting.models` 中替换成自己的模型 ID,而无需修改 OPC 的 flow。
  290. 完整的节点/角色覆盖规则见 [`pipeline/model-routing.md`](pipeline/model-routing.md)。
  291. ### 快速开始
  292. #### 安装
  293. ```bash
  294. npm install -g @touchskyer/opc
  295. ```
  296. Skill 文件会自动复制到 `~/.claude/skills/opc/`。
  297. 较新版本的 npm 默认拦截 install 脚本——如果复制被跳过(判断方法:`opc --version` 有输出但 `~/.claude/skills/opc/SKILL.md` 不存在),改用 `npm install -g --allow-scripts=@touchskyer/opc` 重装,或在装完后手动跑一次 `opc install`。
  298. ##### 手动安装(不用 npm)
  299. ```bash
  300. git clone https://github.com/iamtouchskyer/opc.git
  301. cp -r opc ~/.claude/skills/opc
  302. ```
  303. #### 使用
  304. ```bash
  305. # 审查 —— 并行派发 2-5 个角色 agent
  306. /opc review the auth changes
  307. # 构建 —— 实现 + 独立 review + gate
  308. /opc implement user authentication with email/password
  309. # 自主循环 —— 拆解、调度 cron、无人值守运行
  310. /opc loop build features F1-F4 from PLAN.md
  311. # 交互模式 —— 先问清楚需求
  312. /opc -i redesign the onboarding flow
  313. # 显式指定角色
  314. /opc security devil-advocate
  315. # 流程控制
  316. /opc skip # 跳过当前节点
  317. /opc pass # 强制通过 gate
  318. /opc stop # 终止,保留状态
  319. /opc goto build # 跳转到指定节点
  320. ```
  321. ### 自主循环
  322. ```bash
  323. /opc loop build the math tutoring app features F1-F4
  324. ```
  325. 会发生什么:
  326. 1. **Runbook 查找** —— `opc-harness runbook match "<task>"` 按 `--dir` flag → `OPC_RUNBOOKS_DIR` → `~/.opc/runbooks/` 顺序查找匹配的配方。命中则用它的 `units` / `flow` / `tier` 作为 plan;否则进入第 2 步。可用 `OPC_DISABLE_RUNBOOKS=1` 按次禁用。见 [docs/runbooks.md](docs/runbooks.md) 和 [examples/runbooks/add-feature.md](examples/runbooks/add-feature.md)。
  327. 2. **拆解**(仅 runbook miss)—— 把任务拆成原子单元(spec、implement、review、fix、e2e)
  328. 3. **完成定义** —— 任何工作开始前,为每个单元建立 verify/eval 标准
  329. 4. **调度** —— 持久 cron(进程重启后存活)每 10 分钟触发
  330. 5. **执行** —— 每个 tick 跑一个单元,走对应的 OPC flow
  331. 6. **守卫** —— `opc-harness` 强制:必须 git commit、≥2 个独立审查者、不可篡改 plan、不可伪造 state、artifact 新鲜度、tick 上限
  332. 7. **终止** —— plan 完成、tick 上限、或墙钟截止时自动停止
  333. 对于范围明确的任务,系统可**连续运行 10+ 小时**无需干预。
  334. #### 守卫(代码强制,非 prompt 层)
  335. | 守卫 | 强制方式 |
  336. |------|---------|
  337. | Write nonce | init 时生成随机 SHA256;state 只能由 harness 写入 |
  338. | 原子写入 | write → rename(POSIX 原子);崩溃时不留半截 JSON |
  339. | Plan 完整性 | init 时算 SHA256 哈希;每个 tick 校验 |
  340. | 审查独立性 | ≥2 个 eval 文件,内容雷同则拒绝,行重叠则告警 |
  341. | 必须 git commit | implement/fix 单元的 HEAD 必须变化 |
  342. | 必须截图 | UI 单元必须产出 .png/.jpg artifact |
  343. | Tick 上限 | maxTotalTicks(units×3)+ 24h 墙钟截止 |
  344. | 震荡检测 | 4-6 个 tick 内出现 A↔B 模式 = 告警/硬停 |
  345. | 并发 tick 互斥 | in_progress 状态阻止重叠的 cron 触发 |
  346. | JSON 崩溃恢复 | 所有 JSON.parse 加 try/catch;结构化报错而非崩溃 |
  347. | 外部校验器 | init 时检测并利用 pre-commit hook、测试套件 |
  348. ### 流模板
  349. | 模板 | 节点 | 何时用 |
  350. |------|------|--------|
  351. | **quick** | build → review → gate | "快速修复"、"小改动"、一行改动、≤3 文件,**非 UI、无逻辑分支** |
  352. | **review** | code-review → gate | PR 审查、审计、"找问题" |
  353. | **build-verify** | brief → build → code-review → test-design → test-execute;ITERATE → hotfix → test-execute;PASS → gate | "实现 X"、"修复 bug Y" |
  354. | **full-stack** | discuss → build → review → test → acceptance → audit → e2e → gates | 复杂/模糊的请求 |
  355. | **pre-release** | acceptance → audit → e2e → gates | "发布前验证" |
  356. **`quick` vs `build-verify`** —— `quick` 砍掉结构化的 `brief` 节点和 `test-design`/`test-execute` 拆分,节点数和评估器派发减半。它保留了核心质量门禁(独立 `review` + `gate` 裁决)。只在真正的一行改动 / 单文件、非 UI、无逻辑分支时用。任何带逻辑分支、多文件或 UI 的 → 用 `build-verify`,那里 `test-design` 强制的 L1–L5 覆盖检查才物有所值。
  357. **`brief`** 节点(`build-verify` 的入口)产出一份结构化构建简报——解析后的设计令牌、文件计划、组件清单、约束——供 `build` 节点遵循。它能可量化地提升首次构建保真度,但简报描述的是*预期*行为:下游 `test-design` 必须测**实际构建出来的代码**,而非简报里的理想,否则它会断言构建从未实现的行为。
  358. ### 扩展
  359. OPC 有一个能力路由(capability-routed)的扩展面。扩展位于 `~/.claude/skills/opc-extension/<name>/`——每个带一个 `ext.json`(能力声明)+ 一个 `hook.mjs`,导出 `promptAppend` / `verdictAppend` / `executeRun` / `artifactEmit` 中的任意 hook。不用 fork、不用重新构建。Hook 通过每扩展超时 + 熔断器沙箱化,所以一个坏掉的第三方扩展无法拖垮 harness。
  360. `ext.json.version` 在 `init` 时记录到 `flow-state.json → extensionVersions`,所以协议报告能区分"扩展已加载"和"未知版本"。运行时能力行为仍以 `hook.mjs` 的可执行 hook 元数据为准。
  361. 配套仓库 **opc-extensions**(私有)提供 6 个扩展:`design-intelligence`(主题注入 + 设计覆盖 + VLM 视觉评估)、`dataviz-x`、`git-changeset-review`、`memex-recall`、`perf-budget`、`quality-reality`。
  362. 完整编写指南:**[docs/extension-authoring.md](docs/extension-authoring.md)**——零 OPC 上下文的快速上手 + 参考,外加 `examples/extensions/_starter/` 里的起步模板。
  363. ### 内置角色
  364. ```
  365. Product: pm, designer
  366. User Lens: new-user, active-user, churned-user, user-simulator
  367. Engineering: frontend, backend, devops, architect, engineer, mobile
  368. Quality: security, tester, compliance, a11y, skeptic-owner
  369. Specialist: planner, investor, dd-engineer, devil-advocate
  370. ```
  371. **Devil's Advocate** 在共识近乎一致、或决策不可逆时自动加入。配有一个自动验证脚本,检查它自己的发现。
  372. #### 自定义角色
  373. 在 `roles/` 里加一个 `.md` 文件:
  374. ```markdown
  375. ---
  376. tags: [review, build]
  377. ---
  378. # Role Name
  379. ## Identity
  380. One sentence: who you are and what you care about.
  381. ## Expertise
  382. - **Area** — what you know about it
  383. ## When to Include
  384. - Condition that triggers this role
  385. ```
  386. 即刻可用,无需配置。
  387. ### 测试
  388. ```bash
  389. bash test/run-all.sh
  390. ```
  391. 100+ 测试文件,覆盖 init-loop、complete-tick、next-tick、审查独立性、JSON 崩溃恢复、复合防御、scope registry、criteria lint、pipeline E2E lint、D2 校准、发布打包,以及编排器层级的 E2E 流程测试。
  392. ### 环境要求
  393. - [Claude Code](https://claude.ai/code)(CLI、桌面应用或 IDE 扩展)
  394. - Node.js >= 18
  395. - 核心运行时无 npm 依赖、无 MCP server、无构建步骤
  396. - `opc install-hooks` 始终安装 Node 实现的 auto-flow guard;可选的 `jq` 额外启用上下文压缩 hook
  397. ### 搭配 memex 更好(可选)
  398. OPC 可独立使用——搭配 [memex](https://github.com/iamtouchskyer/memex) 获得跨会话记忆。Memex 记住哪些角色有用、哪些发现是误报,以及你项目特定的上下文。
  399. ```bash
  400. npm install -g @touchskyer/memex
  401. ```
  402. ### 更新日志
  403. 版本历史见 [CHANGELOG.md](CHANGELOG.md)。
  404. ### 社区
  405. 在用 OPC?到 [Discussions → Show and tell](https://github.com/iamtouchskyer/opc/discussions/categories/show-and-tell) 分享你的玩法。问题发 [Q&A](https://github.com/iamtouchskyer/opc/discussions/categories/q-a),功能想法发 [Ideas](https://github.com/iamtouchskyer/opc/discussions/categories/ideas)。
  406. ### 许可
  407. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.