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.
Badge for your README
Markdown
[](/listings/iamtouchskyer--opc)HTML
<a href="/listings/iamtouchskyer--opc"><img src="/api/listings/iamtouchskyer--opc/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- ---
- name: opc
- version: 0.10.2
- 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...]"
- ---
- # OPC — One Person Company
- One principle: **the agent that does the work never evaluates it.**
- 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.
- ## Invocation
- **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:
- ```bash
- OPC_HARNESS="$HOME/.claude/skills/opc/bin/opc-harness.mjs"
- ```
- All `opc-harness` references below mean `node "$OPC_HARNESS"`. Set this as a shell variable and reuse it throughout the session.
- ```
- /opc <task> # auto mode — infer flow and roles from the task
- /opc -i <task> # interactive mode — ask questions before dispatch
- /opc <role> [role...] # explicit roles — skip role selection, dispatch directly
- /opc loop <task> # autonomous loop — decompose, schedule cron, run 24h unattended
- /opc skip # skip current node, advance via PASS edge
- /opc pass # force-pass current gate
- /opc stop # terminate flow, preserve session state
- /opc goto <nodeId> # manual jump to a node (cycle limits still enforced)
- ```
- ## Task Inference + Flow Selection
- The orchestrator reads the task, selects a flow template, and determines the entry point.
- | Task says... | Flow template | Default entry |
- |---|---|---|
- | "review", "audit", "check", "before we merge", "找问题", "开源前看看" | review | review |
- | "analyze", "diagnose", "what's wrong with", "分析" | review | review |
- | "build", "implement", "create", "fix bug", "帮我实现", "重构成..." | build-verify | brief |
- | "quick fix", "small change", "one-liner", "patch", "trivial fix", "快速修复", "小改动" | quick | build |
- | "brainstorm", "explore options", "what are the approaches", "有什么方案" | build-verify | brief |
- | "plan", "decompose", "break this down", "scope", "estimate", "拆一下" | build-verify | brief |
- | "verify", "test", "QA", "check before release", "发布前验收" | pre-release | acceptance |
- | "post-release", "user test", "onboarding check", "用户验收" | pre-release | acceptance |
- | Complex, vague, or multi-keyword request | full-stack | discuss |
- | `/opc loop` or multi-unit feature backlog | **loop-protocol** | plan decomposition |
- **Entry override** — user context can shift the entry point (only if target ∈ template nodes):
- | User has... | Entry override |
- |---|---|
- | A vague idea or brief | First node in template |
- | A spec or design doc | brief (if ∈ template), else build |
- | An implementation plan | brief (if ∈ template), else build |
- | A qualified build-brief.md from prior run | build (skip brief if lint passes) |
- | Code/artifact that needs evaluation | review, code-review, or test-design (if ∈ template) |
- | Everything done, needs acceptance | acceptance (if ∈ template) |
- **Priority rules:**
- - `/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.
- - `/opc <role> [role...]` without a task = review of current codebase using review flow with named roles.
- - `/opc` with no arguments = prompt user to describe their task.
- - If task matches multiple rows, prefer the flow that includes build — code changes must precede review.
- Show triage result:
- ```
- 📌 Flow: {flow template name}
- 📍 Entry: {entry node}
- ⚡ Interaction: auto / interactive
- Rationale: {1 sentence}
- ```
- **Override:** If user explicitly names a task type, respect that. Users can adjust after seeing triage.
- ## Flow Templates
- 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**.
- Each template below describes which agents to dispatch at each node and which protocol to use.
- ### legacy-linear
- Equivalent to v0.4.x behavior. Used as internal fallback only.
- | Node | Type | Agents | Protocol |
- |------|------|--------|----------|
- | design | discussion | [planner] | design exploration |
- | plan | build | [planner] | task decomposition |
- | build | build | [implementer] | implementer-prompt.md |
- | evaluate | review | [selected roles] | role-evaluator-prompt.md |
- | deliver | build | — | commit + report |
- ### review
- | Node | Type | Agents | Protocol |
- |------|------|--------|----------|
- | review | review | [selected roles] | role-evaluator-prompt.md |
- | gate | gate | — | gate-protocol.md |
- 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.
- ### build-verify
- | Node | Type | Agents | Protocol |
- |------|------|--------|----------|
- | brief | brief | [architect] | brief-protocol.md |
- | build | build | [implementer] | implementer-prompt.md |
- | code-review | review | [selected roles] | role-evaluator-prompt.md |
- | test-design | review | [tester, + user/domain roles] | test-design-protocol.md |
- | test-execute | execute | [orchestrator] | executor-protocol.md |
- | gate | gate | — | gate-protocol.md |
- **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.*
- ### quick
- | Node | Type | Agents | Protocol |
- |------|------|--------|----------|
- | build | build | [implementer] | implementer-prompt.md |
- | review | review | [selected roles] | role-evaluator-prompt.md |
- | test-design | review | [tester, + user/domain roles] | test-design-protocol.md |
- | test-execute | execute | [orchestrator] | executor-protocol.md |
- | gate | gate | — | gate-protocol.md |
- **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.
- ### full-stack
- The complete flow with discussion, multi-stage gates, and E2E verification.
- | Node | Type | Agents | Protocol |
- |------|------|--------|----------|
- | discuss | discussion | [architect, engineer, tester] | discussion-protocol.md |
- | brief | brief | [architect] | brief-protocol.md |
- | build | build | [implementer] | implementer-prompt.md |
- | code-review | review | [frontend, backend] | role-evaluator-prompt.md |
- | test-design | review | [tester, + user/domain roles] | test-design-protocol.md |
- | test-execute | execute | [orchestrator] | executor-protocol.md |
- | gate-test | gate | — | gate-protocol.md |
- | acceptance | review | [pm, designer] | role-evaluator-prompt.md |
- | gate-acceptance | gate | — | gate-protocol.md |
- | audit | review | [security, compliance, a11y] | role-evaluator-prompt.md |
- | gate-audit | gate | — | gate-protocol.md |
- | e2e-user | execute | [new-user, active-user, churned-user] | executor-protocol.md |
- | gate-e2e | gate | — | gate-protocol.md |
- | ux-simulation | execute | [new-user, active-user, churned-user] | ux-simulation-protocol.md + ux-observer-protocol.md |
- | gate-final | gate | — | gate-protocol.md |
- ### pre-release
- | Node | Type | Agents | Protocol |
- |------|------|--------|----------|
- | acceptance | review | [pm, designer] | role-evaluator-prompt.md |
- | gate-acceptance | gate | — | gate-protocol.md |
- | audit | review | [security, compliance, a11y] | role-evaluator-prompt.md |
- | gate-audit | gate | — | gate-protocol.md |
- | e2e-user | execute | [new-user, active-user, churned-user] | executor-protocol.md |
- | gate-e2e | gate | — | gate-protocol.md |
- ---
- ## Getting Started
- **Before task inference**, check for existing state:
- 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.
- 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.
- 3. Otherwise → fresh start.
- After flow selection, initialize with the matching interaction mode:
- ```bash
- opc-harness init --auto --claude-session-id "${CLAUDE_SESSION_ID}" --flow {TEMPLATE} --entry {ENTRY_NODE}
- opc-harness init --flow {TEMPLATE} --entry {ENTRY_NODE} # interactive (`/opc -i`) only
- ```
- 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.
- 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:
- ```bash
- opc-harness route --node review --verdict PASS --flow {TEMPLATE}
- opc-harness transition --from review --to gate --verdict PASS --flow {TEMPLATE}
- opc-harness viz --flow {TEMPLATE}
- ```
- **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.
- **Backward compat:** Pass `--dir .harness` to init for a project-local harness dir.
- **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.
- Before starting, extract **acceptance criteria** — 3-7 concrete, testable bullet points. Evaluators grade against these.
- ### Agent Model Routing — Mandatory Pre-Flight
- Flow topology and model tier are independent. Keep every selected node, round, and role, but before each Agent call run:
- ```bash
- opc-harness model-route --node {NODE_ID} --node-type {NODE_TYPE} [--role {ROLE}] --dir {PROJECT_ROOT}
- ```
- 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.
- ### Quality Tier Selection — Mandatory Pre-Flight
- Before the Definition of Done questions, the orchestrator MUST select a **quality tier**. See `./pipeline/quality-tiers.md` for full definitions.
- | Tier | When | Baseline |
- |------|------|----------|
- | `functional` | CLI, API, backend, library, infra | No UI craft requirements |
- | `polished` | UI, frontend, website, dashboard, docs | Dark/light, responsive, loading/error/empty states, favicon, focus styles |
- | `delightful` | Showcase, demo, pitch, consumer product | All of polished + transitions, animations, micro-interactions, onboarding |
- **Selection rules:**
- 1. User explicitly specifies tier → use it
- 2. Task involves UI/frontend → default `polished`
- 3. Task is CLI/API/backend → default `functional`
- 4. Task includes "showcase", "demo", "pitch", "delightful", "beautiful" → `delightful`
- 5. Interactive mode → ask the user
- Show tier selection:
- ```
- 🎯 Quality Tier: {tier}
- Baseline: {N items from tier checklist}
- ```
- 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.
- ### Definition of Done — Mandatory Pre-Flight (all modes)
- 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).
- **Three questions that must have answers before the first node executes:**
- 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."
- 2. **How will we verify it?** — Map each outcome to a verification method:
- - Code change → which tests? (`npm test`, specific test file, new test to write?)
- - UI change → which page/component to screenshot? What should be visible?
- - API change → which endpoint to curl? What response shape?
- - Refactor → which existing tests must still pass?
- 3. **How will we evaluate quality?** — What should reviewers look for beyond "it works"?
- - Performance constraints? ("page load < 2s")
- - Security concerns? ("no PII in logs")
- - Compatibility? ("works in Safari")
- - Edge cases? ("handles empty input, 10k items, unicode")
- **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.
- **In interactive mode (`-i`)**: ask directly, grouped with role-specific questions.
- **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.
- Write the finalized acceptance criteria to `acceptance-criteria.md` (in the session dir) and include them in every subagent prompt.
- **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:
- 1. **Detect reference image** — user provides a path (e.g., `/Users/.../ref.jpg`). Confirm the file exists.
- 2. **Extract design spec** — run `analyze_reference.py` to generate a structured spec:
- ```bash
- python3 ~/.claude/skills/image-x/scripts/analyze_reference.py <ref_image> --output <session_dir>/spec.json
- ```
- 3. **Write `## Reference` section** in `acceptance-criteria.md`:
- ```markdown
- ## Reference
- - reference_image: /absolute/path/to/ref.jpg
- - design_spec: /absolute/path/to/session/spec.json
- ```
- 4. **Set quality baseline** for design reproduction:
- ```markdown
- ## Quality Baseline (polished)
- - design-diff overall ≥ 4.0
- - zero major diffs
- ```
- 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.
- **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.
- ### Task Scope — Mandatory for Loop Mode
- In loop mode, every `plan.md` MUST include a `## Task Scope` section listing the user's original requirements:
- ```markdown
- ## Task Scope
- - SCOPE-1: Backend API for user auth
- - SCOPE-2: Frontend login page with form validation
- - SCOPE-3: Browser E2E tests covering login flow
- - SCOPE-4: Unit tests with 100% coverage on new code
- ```
- The harness enforces this mechanically:
- - **init-loop** refuses to start if `## Task Scope` is missing (bypass: `--skip-scope`)
- - **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`)
- - **next-tick** termination output includes `uncovered_scope` if any items lack coverage
- This prevents the #1 failure mode: LLM decomposition misses part of the original task, pipeline declares "complete" while major scope items are untouched.
- ### Interactive Mode Details (with `-i`)
- 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.
- - Engineering roles usually read code directly — no extra context needed.
- - Product and user roles benefit most: "Who are your target users?", "What's the product stage?"
- - Security and Compliance may need: "Do you handle PII?", "Target markets?"
- **Persona construction** for user roles: In auto mode, infer from project context. In interactive mode, ask directly.
- ### Project Context
- 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.
- ### Superpowers Integration
- If `superpowers` skills are available, use them: brainstorming for design, plan writing, subagent-driven development for build, and branch delivery.
- ---
- ## Built-in Roles
- ```
- Product: pm, designer
- User Lens: new-user, active-user, churned-user
- Engineering: frontend, backend, devops, architect, engineer
- Quality: security, tester, compliance, a11y
- Specialist: planner, user-simulator, devil-advocate
- ```
- Role definitions live in `roles/<name>.md`. Add a `.md` file to `roles/` to create a custom role.
- ### Role Discovery
- The orchestrator searches for role definitions in this order (later sources override earlier ones with the same filename):
- 1. **Built-in roles** — `roles/<name>.md` in OPC's install directory
- 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.
- 3. **Dynamic roles** — created on-the-fly during execution (see below)
- **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.
- **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/`.
- ### Role Selection
- 1. **Tag filter** — from the flow template, you know the node type. Map to stage tags:
- | Node type | Stage tags |
- |-----------|-----------|
- | review | review |
- | build | build |
- | execute | execute, post-release, verification |
- | discussion | brainstorm, plan, discussion |
- | gate | (no roles dispatched) |
- Read the `tags:` front matter from each `roles/<name>.md`. Keep only roles whose tags include at least one matching stage tag.
- 2. **Select from filtered pool** — pick 2-5 roles with distinct angles. Read each candidate's "When to Include" section to decide relevance.
- - **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`.
- - Each dispatched agent must have a DISTINCT angle. If two would produce 80%+ overlapping output, pick one.
- - Not every task needs every role. A CSS fix doesn't need Security.
- - **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.
- - If user specified roles explicitly, use those — skip tag filtering entirely.
- **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.
- Show role selection:
- ```
- 📋 Agents:
- - frontend [standard/sonnet] — <specific scope>
- - tester [economy/haiku] — <specific scope>
- ...
- Launching {N} agents...
- ```
- ---
- ## Node Execution
- **Auto mode is bounded.** Continue without confirmation only while node and repair-edge budgets remain. Normal graph limits and validation failures still apply.
- 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.
- The orchestrator uses **cursor-based execution** — `flow-state.json.currentNode` is the single pointer. No topological sort.
- ### Execution Loop
- ```
- 1. Read flow-state.json → currentNode
- 2. Look up currentNode in the flow template table above → get type, agents, protocol
- 3. Execute based on node type (see below)
- 4. After execution:
- - opc-harness validate → check handshake.json
- - Update progress.md with narrative line
- - opc-harness route --node {current} --verdict PASS --flow {template} → get next
- - opc-harness transition --from {current} --to {next} --verdict PASS --flow {template}
- - **Show flow viz**: run `opc-harness viz --flow {template}` and display to user
- - Loop back to step 1
- 5. When route returns next=null → flow complete → Deliver → **Prompt replay** (see below)
- ```
- ### Node Type: discussion
- Follow `./pipeline/discussion-protocol.md`.
- 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.
- 2. **Orchestrator writes handshake.json** after collecting all artifacts (agents don't write it).
- 3. Discussion nodes produce no verdict — the decision artifact feeds downstream.
- ### Node Type: build
- Follow `./pipeline/implementer-prompt.md` in Build/Fix/Polish mode.
- 1. Resolve the implementer's model route and dispatch it with the returned explicit model.
- 2. **Single agent** → agent writes its own handshake.json.
- 3. **Multiple agents** (parallel, with `isolation: "worktree"`) → orchestrator merges artifacts and writes handshake.json.
- 4. With superpowers: invoke `superpowers:subagent-driven-development`.
- 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.
- ### Node Type: review
- Follow `./pipeline/role-evaluator-prompt.md`.
- 1. Select roles per Role Selection rules.
- 2. Resolve a model route for each selected role, then dispatch evaluators — parallel if no dependencies, serial with context injection if dependencies exist.
- 3. Each agent writes `eval-{role}.md` to `$SESSION_DIR/nodes/{NODE_ID}/run_{RUN}/`.
- 4. **Orchestrator writes handshake.json** after all agents return, merging all eval files into artifacts[].
- 5. Before dispatching, build context brief using `./pipeline/context-brief.md` (for review/analysis tasks).
- **Critical — Review Independence:**
- - Review MUST use independent subagents (Agent tool), never the orchestrator reviewing its own build output.
- - In loop mode, review MUST be a separate tick/unit from implementation. Never combine build + review in one tick.
- - The orchestrator MUST NOT filter, downgrade, or dismiss findings before writing the handshake. All findings pass through to the gate.
- ### Node Type: execute
- Follow `./pipeline/executor-protocol.md`.
- **Executor nodes are executed by the orchestrator directly — not as a subagent.** This is because executors need full tool access (Bash, Playwright, Skills).
- 1. Smoke test tool availability.
- 2. Execute acceptance criteria scenarios.
- 3. Capture evidence (CLI output, screenshots).
- 4. **Orchestrator writes handshake.json** with evidence artifacts.
- 5. Handshake validation enforces: execute nodes must have evidence artifacts.
- ### Node Type: gate
- Follow `./pipeline/gate-protocol.md`.
- **Gate nodes are executed by the orchestrator directly — no subagent dispatch.**
- 1. `opc-harness synthesize --node {upstream}` → get verdict.
- 2. Mechanical validation (severity emojis, file refs, fix suggestions).
- 3. `opc-harness route --node {gate} --verdict {V} --flow {template}` → get next node.
- 4. `opc-harness transition --from {gate} --to {next} --verdict {V} --flow {template}` → validates edge, writes gate handshake, updates state.
- 5. Notify user: pass/loopback/done/blocked.
- ---
- ## Verdict & Loopback
- Gate nodes produce verdicts via `opc-harness synthesize` (code, not LLM judgment):
- - Any 🔴 → FAIL
- - Any 🟡 → ITERATE
- - All 🔵/LGTM → PASS
- - Any BLOCKED → BLOCKED
- **Code enforces all limits:**
- - `maxLoopsPerEdge` = 3 (same edge can't be traversed more than 3 times)
- - `maxTotalSteps` = 20-30 (depending on flow template)
- - `maxNodeReentry` = 5 (same node can't be entered more than 5 times)
- **Oscillation detection:** After a loopback, run `opc-harness diff` on consecutive evaluations. If `oscillation: true`, surface to user.
- **Escape hatches:**
- - `/opc skip` — skip current node, advance via PASS edge
- - `/opc pass` — force gate to PASS
- - `/opc stop` — terminate flow, preserve state
- - `/opc goto <nodeId>` — manual jump (cycle limits still enforced via `transition`)
- When transition returns `allowed: false` → show the user why (which limit hit) and offer escape options. Never continue without user consent.
- ---
- ## File-Based State
- ```
- $SESSION_DIR/ # ~/.opc/sessions/{hash}/{id}/ or .harness/ if --dir used
- ├── flow-state.json # Current node, execution history, edge counts, limits
- ├── progress.md # Human-readable narrative log
- └── nodes/
- └── {nodeId}/
- ├── handshake.json # Machine-readable envelope (summary + verdict + artifact paths)
- └── run_{N}/
- ├── eval.md # Single evaluator output (detailed findings)
- ├── eval-{role}.md # Per-role evaluator output (multi-role)
- ├── round-1-{role}.md # Discussion round 1
- ├── round-2-{role}.md # Discussion round 2 (diffs only)
- ├── decision.md # Discussion facilitator decision
- ├── screenshot-{N}.png # Executor GUI evidence
- └── command-output-{N}.txt # Executor CLI evidence
- ```
- **Relationships:**
- - `handshake.json` = envelope. Its `artifacts[]` points to detailed files (eval.md, screenshots, etc.)
- - `flow-state.json` = sole source of truth for execution position and history
- - `eval.md` / `eval-{role}.md` = human-readable findings (read by `synthesize` to compute verdict)
- - `progress.md` = narrative projection of flow execution (for humans)
- ---
- ## Prompt Templates
- All templates live in `./pipeline/`:
- - `evaluator-prompt.md` — Single generic evaluator
- - `role-evaluator-prompt.md` — Role-specific evaluator (review, analysis, brainstorm outputs)
- - `implementer-prompt.md` — Implementer (Build / Fix / Polish modes)
- - `discussion-protocol.md` — Multi-agent discussion (round-robin, 3 rounds, facilitator)
- - `gate-protocol.md` — Verdict aggregation + code-based routing + transition + **findings disposition**
- - `executor-protocol.md` — CLI/GUI execution with evidence requirements
- - `test-design-protocol.md` — **Test case design** (review node, multi-role test planning before execution)
- - `loop-protocol.md` — **Autonomous multi-unit execution** (plan decomposition → cron loop → auto-terminate)
- - `handoff-template.md` — Handshake.json specification
- - `context-brief.md` — Design context brief procedure
- - `model-routing.md` — Explicit per-node/per-role model selection and premium approval
- - `report-format.md` — Presentation templates + JSON schema + replay
- - `quality-tiers.md` — Tier definitions + baseline checklists + severity calibration
- - `ux-simulation-protocol.md` — **UX simulation gate** (red flag detection, delta comparison, ordinal tier fit)
- - `ux-observer-protocol.md` — **UX observer dispatch** (persona-based pattern observation, closed enum red flags)
- - `criteria-lint.md` — **DoD mechanical lint** (single-pass structure + content checks, pre-init gate)
- ---
- ## External Flow Templates
- 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).
- **JSON schema:**
- ```json
- {
- "nodes": ["discover", "build", "review", "gate"],
- "edges": {
- "discover": { "PASS": "build" },
- "build": { "PASS": "review" },
- "review": { "PASS": "gate" },
- "gate": { "PASS": null, "FAIL": "build", "ITERATE": "build" }
- },
- "limits": { "maxLoopsPerEdge": 3, "maxTotalSteps": 20, "maxNodeReentry": 5 },
- "nodeTypes": {
- "discover": "discussion", "build": "build",
- "review": "review", "gate": "gate"
- },
- "softEvidence": true,
- "opc_compat": ">=0.10",
- "contextSchema": {
- "build": {
- "required": ["task"],
- "rules": { "task": "non-empty-string" }
- }
- }
- }
- ```
- **Validation rules:**
- - `nodes`, `edges`, `limits` are required
- - All edge sources and targets must be in `nodes`
- - `nodeTypes` values must be: `discussion`, `build`, `review`, `execute`, `gate`
- - `opc_compat` uses `>=X.Y` semver range (current harness compatibility: 0.10.0)
- - Prototype pollution names (`__proto__`, `constructor`, `prototype`) are rejected
- **Optional fields:**
- - `softEvidence: true` — downgrades missing-evidence errors to warnings for execute nodes
- - `contextSchema` — per-node validation rules for `flow-context.json`
- - `opc_compat` — minimum harness version required
- **contextSchema rules:**
- - `non-empty-string` — must be a non-empty string
- - `non-empty-array` — must be a non-empty array
- - `non-empty-object` — must be a non-empty plain object (not array)
- - `positive-integer` — must be a positive integer > 0
- ---
- ## Harness Command Reference
- All commands output JSON to stdout. Errors go to stderr. All output is machine-parseable.
- ### Flow Commands
- | Command | Usage | Description |
- |---------|-------|-------------|
- | `init` | `--flow <tpl> [--entry <node>] [--dir <p>]` | Initialize flow state. Creates `flow-state.json` and node directories. Seeds `baseSha` (git floor) and empty `producedCommits`. |
- | `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. |
- | `route` | `--node <id> --verdict <V> --flow <tpl>` | Get next node from graph edges. Returns `{next, allowed}`. |
- | `transition` | `--from <n> --to <n> --verdict <V> --flow <tpl> --dir <p>` | Execute state transition. Validates edge, checks limits, writes gate handshake, enforces backlog. |
- | `validate` | `<handshake.json>` | Validate handshake schema (required fields, evidence check for execute nodes). |
- | `validate-chain` | `[--dir <p>]` | Validate entire execution path — checks all handshakes match history. |
- | `validate-context` | `--flow <tpl> --node <id> [--dir <p>]` | Validate `flow-context.json` against contextSchema rules. |
- | `finalize` | `[--dir <p>] [--strict]` | Finalize terminal node. Marks flow as completed. |
- | `viz` | `--flow <tpl> [--dir <p>] [--json]` | Visualize flow graph (ASCII or JSON). Shows ▶ current, ✅ visited, ○ pending. |
- | `replay` | `[--dir <p>]` | Export full replay data as JSON (flow state + handshakes + run artifacts). |
- ### Escape Hatches
- | Command | Usage | Description |
- |---------|-------|-------------|
- | `skip` | `[--dir <p>] [--flow <tpl>]` | Skip current node, advance via PASS edge. Writes skip handshake. |
- | `pass` | `[--dir <p>]` | Force-pass current gate node. Only works on gate-type nodes. |
- | `stop` | `[--dir <p>]` | Terminate flow, preserve state. Sets status to "stopped". |
- | `goto` | `<nodeId> [--dir <p>]` | Manual jump to any node. Cycle limits still enforced. |
- | `ls` | `[--base <p>]` | List all active flows (scans `~/.opc/sessions/` and project-local `.harness*` directories). |
- ### Eval Commands
- | Command | Usage | Description |
- |---------|-------|-------------|
- | `verify` | `<file>` | Parse evaluation markdown → JSON (severity counts, verdict, findings). |
- | `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. |
- | `report` | `<dir> --mode <m> --task <t>` | Generate full report JSON with presentation data. |
- | `diff` | `<file1> <file2>` | Compare two evaluation rounds. Detects oscillation. |
- ### Loop Commands (Layer 2 — Zero Trust)
- | Command | Usage | Description |
- |---------|-------|-------------|
- | `init-loop` | `[--plan <file>] [--dir <p>]` | Initialize loop state from plan.md. Validates plan structure, detects test/lint scripts. |
- | `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. |
- | `next-tick` | `[--dir <p>]` | Get next unit. Checks stall/oscillation, returns `{ready, unit, terminate}`. |
- ### Transition Details
- The `transition` command enforces:
- - **Edge validation** — only declared edges are allowed
- - **Cycle limits** — `maxLoopsPerEdge`, `maxTotalSteps`, `maxNodeReentry`
- - **Idempotency** — repeated identical transitions are silently accepted
- - **Gate detection** — uses `nodeTypes[from] === "gate"` (not name prefix)
- - **Pre-transition validation** — upstream handshake must exist and be valid
- - **Backlog enforcement** — if upstream has warnings, `backlog.md` must exist for FAIL/ITERATE transitions
- ---
- ## Resilience
- **Agent spawn failures:** Retry once. If it fails again, surface to user.
- **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:
- 1. **PreCompact** writes a resume brief to `$SESSION_DIR/resume-brief.md`
- 2. **PostCompact** injects the brief as `additionalContext` into the new context
- 3. The orchestrator sees the injection and resumes the flow automatically
- 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).
- **State recovery:** On resume, run `opc-harness validate-chain`. If inconsistent → surface to user, do not auto-repair.
- **Legacy detection:** If `.harness/` in project root has `wave-*` files but no `flow-state.json` → refuse to run. Print migration instructions.
- **Fresh context per agent.** Always spawn new subagents. Files carry state; agents bring fresh capacity.
- ---
- ## Flow Completion & Replay
- When the flow completes (route returns `next=null`):
- 1. Show final viz: `opc-harness viz --flow {template}`
- 2. Show summary: total steps, nodes visited, any loopbacks, and dispatched agent counts by model tier
- 3. **Generate HTML report** (use the session dir from init output, or find it via `opc-harness ls`):
- ```bash
- node "$OPC_HARNESS/../opc-report.mjs" --dir <session-dir> --output <session-dir>/report.html --title "{task summary}"
- ```
- 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.
- 4. **Prompt the user:**
- ```
- ✅ Flow complete! Report: $SESSION_DIR/report.html
- Want to see the replay? Run: /opc replay
- ```
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)
- # OPC — One Person Company
- > A full team in a single Claude Code skill. You're the CEO — OPC is everyone else.
- 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.
- [English](#english) | [中文](#中文)
- ---
- ## English
- ### What you can build
- 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.
- **▶ [Browse the live lookbook →](https://www.touchskyer.me/projects/opc/lookbook)**
- <table>
- <tr>
- <td width="50%" valign="top">
- <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>
- <br><b>Pulse</b> · SaaS analytics dashboard<br><sub>Dark UI · data-viz</sub>
- </td>
- <td width="50%" valign="top">
- <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>
- <br><b>Studio Kura</b> · Creative agency portfolio<br><sub>Brutalist · editorial · motion</sub>
- </td>
- </tr>
- <tr>
- <td width="50%" valign="top">
- <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>
- <br><b>Cumulus</b> · Project-management dashboard<br><sub>Claymorphism · pastel</sub>
- </td>
- <td width="50%" valign="top">
- <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>
- <br><b>Conduit Docs</b> · Developer documentation<br><sub>Docs · code · developer</sub>
- </td>
- </tr>
- <tr>
- <td width="50%" valign="top">
- <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>
- <br><b>Maison Terre</b> · DTC skincare e-commerce<br><sub>Brand · editorial</sub>
- </td>
- <td width="50%" valign="top">
- <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>
- <br><b>Yuzuki 柚月</b> · Local dining platform<br><sub>Booking · bilingual · mobile</sub>
- </td>
- </tr>
- </table>
- > 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"...`
- **OPC isn't only for UIs.** The same zero-trust pipeline also handles:
- - **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.
- - **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.
- - **Full-stack features** — `/opc implement user auth with email/password` runs build → independent review → test-design → test-execute → gate.
- - **Pre-release audits** — `/opc verify before release` runs acceptance + audit + e2e gates before you ship.
- ### How It Works
- One principle: **the agent that does the work never evaluates it.**
- ```
- Task → Flow Selection → Node Execution → Gate Verdict → Route Next
- ↑ ↓
- └──────── ITERATE/FAIL ────────┘
- ```
- 1. **Task inference** — reads your request, picks a flow template (quick, review, build-verify, full-stack, pre-release), and enters at the right node.
- 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.
- 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."
- 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.
- #### Quality Architecture
- 
- The system is built on a zero-trust axiom: **every critical output must have an independent verification path.** Four layers:
- - **L0 — Zero Trust**: Decision axiom — not code, not prompt. Every critical output needs an independent verification path.
- - **L1 — Shape Single Agent**: Intervene during token generation — persona setting, anti-pattern tables, mandatory output structure, scope anchoring, quality gates.
- - **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).
- - **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).
- #### Model-aware dispatch
- 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:
- | Tier | Claude Code default | Typical work |
- |---|---|---|
- | economy | `haiku` | test design, user/UX observers |
- | standard | `sonnet` | discussion, implementation, semantic review |
- | premium | `inherit` | explicit escalation only |
- `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:
- ```json
- {
- "agentRouting": {
- "models": {
- "economy": "your-fast-model-id",
- "standard": "your-value-model-id",
- "premium": "your-premium-model-id"
- }
- }
- }
- ```
- See [`pipeline/model-routing.md`](pipeline/model-routing.md) for node/role overrides and the resolver contract.
- ### Quick Start
- #### Install
- ```bash
- 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)
- ```bash
- git clone https://github.com/iamtouchskyer/opc.git
- cp -r opc ~/.claude/skills/opc
- ```
- #### Use it
- ```bash
- # 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
- ```
- ### Autonomous Loop
- ```bash
- /opc loop build the math tutoring app features F1-F4
- ```
- What happens:
- 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).
- 2. **Decompose** (runbook miss only) — breaks task into atomic units (spec, implement, review, fix, e2e)
- 3. **Definition of done** — establishes verify/eval criteria per unit before any work starts
- 4. **Schedule** — durable cron (survives process restart) fires every 10 min
- 5. **Execute** — each tick runs one unit through the appropriate OPC flow
- 6. **Guard** — `opc-harness` enforces: git commit required, ≥2 independent reviewers, no plan tampering, no state forgery, artifact freshness, tick limits
- 7. **Terminate** — auto-stops when plan complete, tick limit hit, or wall-clock deadline reached
- For well-scoped tasks, the system runs **10+ hours continuously** without intervention.
- #### Guardrails (code-enforced, not prompt-level)
- | Guard | Enforcement |
- |-------|-------------|
- | Write nonce | Random SHA256 at init; state written by harness only |
- | Atomic writes | write → rename (POSIX atomic); no truncated JSON on crash |
- | Plan integrity | SHA256 hash at init; verified every tick |
- | Review independence | ≥2 eval files, identical content rejected, line overlap warned |
- | Git commit required | HEAD must change for implement/fix units |
- | Screenshot required | UI units must produce .png/.jpg artifact |
- | Tick limits | maxTotalTicks (units×3) + 24h wall-clock deadline |
- | Oscillation detection | A↔B pattern over 4-6 ticks = warning/hard stop |
- | Concurrent tick mutex | in_progress status blocks overlapping cron fires |
- | JSON crash recovery | try/catch on all JSON.parse; structured errors, not crashes |
- | External validators | Pre-commit hooks, test suites detected at init and leveraged |
- ### Flow Templates
- | Template | Nodes | When |
- |----------|-------|------|
- | **quick** | build → review → gate | "quick fix", "small change", one-liner, ≤3 files, **non-UI, no logic branches** |
- | **review** | code-review → gate | PR review, audit, "find problems" |
- | **build-verify** | brief → build → code-review → test-design → test-execute; ITERATE → hotfix → test-execute; PASS → gate | "implement X", "fix bug Y" |
- | **full-stack** | discuss → build → review → test → acceptance → audit → e2e → gates | Complex/vague requests |
- | **pre-release** | acceptance → audit → e2e → gates | "verify before release" |
- **`quick` vs `build-verify`** — `quick` drops the structured `brief` node and the
- `test-design`/`test-execute` split, halving nodes and evaluator dispatches. It keeps
- the core quality gate (independent `review` + `gate` verdict). Use it only for true
- one-liners / single-file, non-UI, no-logic-branch changes. Anything with logic
- branches, multiple files, or UI → use `build-verify`, where `test-design`'s enforced
- L1–L5 coverage check earns its keep.
- The **`brief`** node (entry of `build-verify`) produces a structured build brief —
- resolved design tokens, file plan, component inventory, constraints — that the
- `build` node follows. It measurably lifts first-pass build fidelity, but the brief
- describes *intended* behavior: downstream `test-design` must test the **actual built
- code**, not the brief's ideal, or it will assert behavior the build never implemented.
- ### Extensions
- OPC has a capability-routed extension surface. Extensions live in
- `~/.claude/skills/opc-extension/<name>/` — each with `ext.json` (capability
- declarations) + `hook.mjs` exporting any of `promptAppend` / `verdictAppend`
- / `executeRun` / `artifactEmit` hooks. No fork, no rebuild. Hooks are
- sandboxed via per-extension timeouts + circuit breakers, so a broken
- third-party extension can't take down the harness.
- `ext.json.version` is recorded in `flow-state.json → extensionVersions` during
- `init`, so protocol reports can distinguish "extension loaded" from "unknown
- version". Executable hook metadata from `hook.mjs` still wins for runtime
- capability behavior.
- 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`.
- Full authoring guide: **[docs/extension-authoring.md](docs/extension-authoring.md)** — zero-OPC-context
- quickstart + reference, plus a starter template at `examples/extensions/_starter/`.
- ### Built-in Roles
- ```
- Product: pm, designer
- User Lens: new-user, active-user, churned-user, user-simulator
- Engineering: frontend, backend, devops, architect, engineer, mobile
- Quality: security, tester, compliance, a11y, skeptic-owner
- Specialist: planner, investor, dd-engineer, devil-advocate
- ```
- **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.
- #### Custom Roles
- Add a `.md` file to `roles/`:
- ```markdown
- ---
- tags: [review, build]
- ---
- # Role Name
- ## Identity
- One sentence: who you are and what you care about.
- ## Expertise
- - **Area** — what you know about it
- ## When to Include
- - Condition that triggers this role
- ```
- Available immediately, no configuration needed.
- ### Testing
- ```bash
- bash test/run-all.sh
- ```
- 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.
- ### Requirements
- - [Claude Code](https://claude.ai/code) (CLI, desktop app, or IDE extension)
- - Node.js >= 18
- - Core runtime has no npm dependencies, no MCP server, no build step
- - `opc install-hooks` always installs the Node-based auto-flow guard; optional `jq` additionally enables context-compaction hooks
- ### Works better with memex (optional)
- 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.
- ```bash
- npm install -g @touchskyer/memex
- ```
- ### What's New
- See [CHANGELOG.md](CHANGELOG.md) for version history.
- ### Community
- 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).
- ### License
- MIT
- ---
- ## 中文
- ### 你能用它造什么
- 从**一句话需求**出发,OPC 的 `build-verify` 流程就能交付一个完整、生产级的产品——设计令牌(design token)由 [design-intelligence](docs/extension-authoring.md) 扩展注入、视觉质量由它验证。下面每一张截图都是**真实可点击的站点**(不是设计稿),由同一套 21 角色流水线构建。同一套系统,六种完全不同的设计语言。
- **▶ [浏览在线作品集 →](https://www.touchskyer.me/projects/opc/lookbook)**
- <table>
- <tr>
- <td width="50%" valign="top">
- <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>
- <br><b>Pulse</b> · SaaS 分析仪表盘<br><sub>暗色 UI · 数据可视化</sub>
- </td>
- <td width="50%" valign="top">
- <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>
- <br><b>Studio Kura</b> · 创意工作室作品集<br><sub>粗野主义 · 编辑风 · 动效</sub>
- </td>
- </tr>
- <tr>
- <td width="50%" valign="top">
- <a href="https://www.touchskyer.me/projects/opc/lookbook/cumulus/index.html"><img src="docs/assets/showcase/cumulus.png" alt="Cumulus —— OPC 生成的项目管理仪表盘"></a>
- <br><b>Cumulus</b> · 项目管理仪表盘<br><sub>黏土拟态 · 柔和色彩</sub>
- </td>
- <td width="50%" valign="top">
- <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>
- <br><b>Conduit Docs</b> · 开发者文档站<br><sub>文档 · 代码 · 开发者</sub>
- </td>
- </tr>
- <tr>
- <td width="50%" valign="top">
- <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>
- <br><b>Maison Terre</b> · 护肤品 DTC 电商<br><sub>品牌 · 编辑风</sub>
- </td>
- <td width="50%" valign="top">
- <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>
- <br><b>Yuzuki 柚月</b> · 本地餐饮平台<br><sub>预订 · 双语 · 移动端</sub>
- </td>
- </tr>
- </table>
- > [作品集](https://www.touchskyer.me/projects/opc/lookbook)里每张卡片悬停时会翻面,露出**生成它的原始 prompt**——比如 Pulse 就来自一句话:`/opc build a production-quality SaaS analytics dashboard called "Pulse"...`
- **OPC 不只是用来做 UI。** 同一套零信任流水线还能:
- - **无人值守造完整产品** —— `/opc loop build features F1–F4 from PLAN.md` 拆解任务、调度持久 cron,**连续运行 10+ 小时**无需干预。
- - **代码审查** —— `/opc review the auth changes` 并行派发 2–5 个独立角色 agent(security、backend、a11y、devil's advocate),用代码计算裁决。
- - **全栈功能** —— `/opc implement user auth with email/password` 跑 build → 独立 review → test-design → test-execute → gate。
- - **发布前审计** —— `/opc verify before release` 在上线前跑 acceptance + audit + e2e 门禁。
- ### 工作原理
- 一条原则:**做事的 agent 永远不评判自己的工作。**
- ```
- Task → Flow Selection → Node Execution → Gate Verdict → Route Next
- ↑ ↓
- └──────── ITERATE/FAIL ────────┘
- ```
- 1. **任务推断** —— 读取你的请求,选一个 flow 模板(quick、review、build-verify、full-stack、pre-release),从正确的节点进入。
- 2. **类型化节点** —— 每个节点有类型(discussion、build、review、execute、gate)和特定协议。build 节点产出 commit;review 节点派发并行 subagent;gate 节点用代码而非 LLM 判断计算裁决。
- 3. **机械门禁** —— 裁决由 `opc-harness synthesize` 计算:任意 red = FAIL,任意 yellow = ITERATE,全 green = PASS。没有任何 LLM 能决定某个发现"是否足够重要"。
- 4. **循环上限** —— 每条边最多 3 次循环,每个节点最多 5 次重入,按 flow 总步数 20-30。震荡检测捕获 A↔B 循环。
- #### 质量架构
- 
- 系统建立在一条零信任公理上:**每个关键输出都必须有独立的验证路径。** 四层:
- - **L0 —— 零信任**:决策公理——不是代码,不是 prompt。每个关键输出都需要独立的验证路径。
- - **L1 —— 塑造单个 agent**:在 token 生成过程中干预——人格设定、反模式表、强制输出结构、范围锚定、质量门禁。
- - **L2 —— 设计 agent 流**:多 agent 协同——关注点分离、流拓扑(并行 review / 串行 build)、上下文隔离(基于文件的交接、全新 agent、不复用 session)。
- - **L3 —— 确定性强制**:唯一不需要 LLM 配合的一层——机械操作(严重度计数、裁决规则、震荡 diff)和加固验证(找文件证据检查、模糊措辞扫描、引用校验)。
- #### 模型感知派发
- OPC 保留完整的多 agent 拓扑,同时避免顶级模型被意外放大到所有子 agent。每次调用 Agent 前,`opc-harness model-route` 都会从分层配置中解析一个明确的宿主原生模型:
- | 层级 | Claude Code 默认值 | 典型工作 |
- |---|---|---|
- | economy | `haiku` | 测试设计、用户/UX observer |
- | standard | `sonnet` | 讨论、实现、语义审查 |
- | premium | `inherit` | 仅显式升级 |
- `inherit` 和 `opus` 需要显式批准。Claude Code 的 `CLAUDE_CODE_SUBAGENT_MODEL` 环境变量覆盖会被检测并展示。其他宿主可以在 `agentRouting.models` 中替换成自己的模型 ID,而无需修改 OPC 的 flow。
- 完整的节点/角色覆盖规则见 [`pipeline/model-routing.md`](pipeline/model-routing.md)。
- ### 快速开始
- #### 安装
- ```bash
- npm install -g @touchskyer/opc
- ```
- Skill 文件会自动复制到 `~/.claude/skills/opc/`。
- 较新版本的 npm 默认拦截 install 脚本——如果复制被跳过(判断方法:`opc --version` 有输出但 `~/.claude/skills/opc/SKILL.md` 不存在),改用 `npm install -g --allow-scripts=@touchskyer/opc` 重装,或在装完后手动跑一次 `opc install`。
- ##### 手动安装(不用 npm)
- ```bash
- git clone https://github.com/iamtouchskyer/opc.git
- cp -r opc ~/.claude/skills/opc
- ```
- #### 使用
- ```bash
- # 审查 —— 并行派发 2-5 个角色 agent
- /opc review the auth changes
- # 构建 —— 实现 + 独立 review + gate
- /opc implement user authentication with email/password
- # 自主循环 —— 拆解、调度 cron、无人值守运行
- /opc loop build features F1-F4 from PLAN.md
- # 交互模式 —— 先问清楚需求
- /opc -i redesign the onboarding flow
- # 显式指定角色
- /opc security devil-advocate
- # 流程控制
- /opc skip # 跳过当前节点
- /opc pass # 强制通过 gate
- /opc stop # 终止,保留状态
- /opc goto build # 跳转到指定节点
- ```
- ### 自主循环
- ```bash
- /opc loop build the math tutoring app features F1-F4
- ```
- 会发生什么:
- 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)。
- 2. **拆解**(仅 runbook miss)—— 把任务拆成原子单元(spec、implement、review、fix、e2e)
- 3. **完成定义** —— 任何工作开始前,为每个单元建立 verify/eval 标准
- 4. **调度** —— 持久 cron(进程重启后存活)每 10 分钟触发
- 5. **执行** —— 每个 tick 跑一个单元,走对应的 OPC flow
- 6. **守卫** —— `opc-harness` 强制:必须 git commit、≥2 个独立审查者、不可篡改 plan、不可伪造 state、artifact 新鲜度、tick 上限
- 7. **终止** —— plan 完成、tick 上限、或墙钟截止时自动停止
- 对于范围明确的任务,系统可**连续运行 10+ 小时**无需干预。
- #### 守卫(代码强制,非 prompt 层)
- | 守卫 | 强制方式 |
- |------|---------|
- | Write nonce | init 时生成随机 SHA256;state 只能由 harness 写入 |
- | 原子写入 | write → rename(POSIX 原子);崩溃时不留半截 JSON |
- | Plan 完整性 | init 时算 SHA256 哈希;每个 tick 校验 |
- | 审查独立性 | ≥2 个 eval 文件,内容雷同则拒绝,行重叠则告警 |
- | 必须 git commit | implement/fix 单元的 HEAD 必须变化 |
- | 必须截图 | UI 单元必须产出 .png/.jpg artifact |
- | Tick 上限 | maxTotalTicks(units×3)+ 24h 墙钟截止 |
- | 震荡检测 | 4-6 个 tick 内出现 A↔B 模式 = 告警/硬停 |
- | 并发 tick 互斥 | in_progress 状态阻止重叠的 cron 触发 |
- | JSON 崩溃恢复 | 所有 JSON.parse 加 try/catch;结构化报错而非崩溃 |
- | 外部校验器 | init 时检测并利用 pre-commit hook、测试套件 |
- ### 流模板
- | 模板 | 节点 | 何时用 |
- |------|------|--------|
- | **quick** | build → review → gate | "快速修复"、"小改动"、一行改动、≤3 文件,**非 UI、无逻辑分支** |
- | **review** | code-review → gate | PR 审查、审计、"找问题" |
- | **build-verify** | brief → build → code-review → test-design → test-execute;ITERATE → hotfix → test-execute;PASS → gate | "实现 X"、"修复 bug Y" |
- | **full-stack** | discuss → build → review → test → acceptance → audit → e2e → gates | 复杂/模糊的请求 |
- | **pre-release** | acceptance → audit → e2e → gates | "发布前验证" |
- **`quick` vs `build-verify`** —— `quick` 砍掉结构化的 `brief` 节点和 `test-design`/`test-execute` 拆分,节点数和评估器派发减半。它保留了核心质量门禁(独立 `review` + `gate` 裁决)。只在真正的一行改动 / 单文件、非 UI、无逻辑分支时用。任何带逻辑分支、多文件或 UI 的 → 用 `build-verify`,那里 `test-design` 强制的 L1–L5 覆盖检查才物有所值。
- **`brief`** 节点(`build-verify` 的入口)产出一份结构化构建简报——解析后的设计令牌、文件计划、组件清单、约束——供 `build` 节点遵循。它能可量化地提升首次构建保真度,但简报描述的是*预期*行为:下游 `test-design` 必须测**实际构建出来的代码**,而非简报里的理想,否则它会断言构建从未实现的行为。
- ### 扩展
- OPC 有一个能力路由(capability-routed)的扩展面。扩展位于 `~/.claude/skills/opc-extension/<name>/`——每个带一个 `ext.json`(能力声明)+ 一个 `hook.mjs`,导出 `promptAppend` / `verdictAppend` / `executeRun` / `artifactEmit` 中的任意 hook。不用 fork、不用重新构建。Hook 通过每扩展超时 + 熔断器沙箱化,所以一个坏掉的第三方扩展无法拖垮 harness。
- `ext.json.version` 在 `init` 时记录到 `flow-state.json → extensionVersions`,所以协议报告能区分"扩展已加载"和"未知版本"。运行时能力行为仍以 `hook.mjs` 的可执行 hook 元数据为准。
- 配套仓库 **opc-extensions**(私有)提供 6 个扩展:`design-intelligence`(主题注入 + 设计覆盖 + VLM 视觉评估)、`dataviz-x`、`git-changeset-review`、`memex-recall`、`perf-budget`、`quality-reality`。
- 完整编写指南:**[docs/extension-authoring.md](docs/extension-authoring.md)**——零 OPC 上下文的快速上手 + 参考,外加 `examples/extensions/_starter/` 里的起步模板。
- ### 内置角色
- ```
- Product: pm, designer
- User Lens: new-user, active-user, churned-user, user-simulator
- Engineering: frontend, backend, devops, architect, engineer, mobile
- Quality: security, tester, compliance, a11y, skeptic-owner
- Specialist: planner, investor, dd-engineer, devil-advocate
- ```
- **Devil's Advocate** 在共识近乎一致、或决策不可逆时自动加入。配有一个自动验证脚本,检查它自己的发现。
- #### 自定义角色
- 在 `roles/` 里加一个 `.md` 文件:
- ```markdown
- ---
- tags: [review, build]
- ---
- # Role Name
- ## Identity
- One sentence: who you are and what you care about.
- ## Expertise
- - **Area** — what you know about it
- ## When to Include
- - Condition that triggers this role
- ```
- 即刻可用,无需配置。
- ### 测试
- ```bash
- bash test/run-all.sh
- ```
- 100+ 测试文件,覆盖 init-loop、complete-tick、next-tick、审查独立性、JSON 崩溃恢复、复合防御、scope registry、criteria lint、pipeline E2E lint、D2 校准、发布打包,以及编排器层级的 E2E 流程测试。
- ### 环境要求
- - [Claude Code](https://claude.ai/code)(CLI、桌面应用或 IDE 扩展)
- - Node.js >= 18
- - 核心运行时无 npm 依赖、无 MCP server、无构建步骤
- - `opc install-hooks` 始终安装 Node 实现的 auto-flow guard;可选的 `jq` 额外启用上下文压缩 hook
- ### 搭配 memex 更好(可选)
- OPC 可独立使用——搭配 [memex](https://github.com/iamtouchskyer/memex) 获得跨会话记忆。Memex 记住哪些角色有用、哪些发现是误报,以及你项目特定的上下文。
- ```bash
- npm install -g @touchskyer/memex
- ```
- ### 更新日志
- 版本历史见 [CHANGELOG.md](CHANGELOG.md)。
- ### 社区
- 在用 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)。
- ### 许可
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.