Opc

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:

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.

Entry override — user context can shift the entry point (only if target ∈ template nodes):

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.

review

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

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

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.

pre-release

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:

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:

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:

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.

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:

   python3 ~/.claude/skills/image-x/scripts/analyze_reference.py <ref_image> --output <session_dir>/spec.json

3. Write ## Reference section in acceptance-criteria.md:

   ## Reference
   - reference_image: /absolute/path/to/ref.jpg
   - design_spec: /absolute/path/to/session/spec.json

4. Set quality baseline for design reproduction:

   ## 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:

## 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:

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.