opc

Category: Tools & Productivity | Uploader: iamtouchskyer | Downloads: 0 | Version: v1.0（Latest）

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...]

Changelog: Source: GitHub https://github.com/iamtouchskyer/opc

Directory Structure

Current level: tree/main/

📁 .harness-ext/
- 📁 nodes/
  - 📁 build/
    
    📁 run_1/
    
    📄 handshake.json 672 B
    
    📁 run_3/
    
    📄 handshake.json 372 B
📁 bin/
- 📁 lib/
  - 📄 bypass-args.mjs 1.0 KB
  - 📄 bypass-args.test.mjs 2.0 KB
  - 📄 config-layering.mjs 10.6 KB
  - 📄 config-layering.test.mjs 18.1 KB
  - 📄 criteria-lint.mjs 9.7 KB
  - 📄 eval-commands.mjs 18.7 KB
  - 📄 eval-parser.mjs 10.2 KB
  - 📄 eval-report.mjs 4.9 KB
  - 📄 ext-commands.mjs 22.0 KB
  - 📄 extensions.mjs 46.6 KB
  - 📄 extensions.test.mjs 136.1 KB
  - 📄 file-lock.mjs 3.8 KB
  - 📄 flow-core.mjs 18.4 KB
  - 📄 flow-escape.mjs 11.3 KB
  - 📄 flow-templates.mjs 20.4 KB
  - 📄 flow-transition.mjs 20.8 KB
  - 📄 loop-advance.mjs 14.8 KB
  - 📄 loop-helpers.mjs 3.9 KB
  - 📄 loop-init.mjs 7.0 KB
  - 📄 loop-reinit.mjs 6.9 KB
  - 📄 loop-tick.mjs 19.5 KB
  - 📄 runbook-commands.mjs 7.1 KB
  - 📄 runbooks.mjs 14.9 KB
  - 📄 runbooks.test.mjs 19.2 KB
  - 📄 tier-baselines.mjs 19.2 KB
  - 📄 util.mjs 1.8 KB
  - 📄 ux-verdict.mjs 16.0 KB
  - 📄 viz-commands.mjs 5.1 KB
- 📄 opc-harness.mjs 8.2 KB
- 📄 opc-report.mjs 18.4 KB
- 📄 opc.mjs 4.4 KB
- 📄 replay-open.sh 1.9 KB
- 📄 replay-viewer.html 29.2 KB
📁 docs/
- 📁 history/
  - 📄 run3-findings-for-run5.md 8.3 KB
- 📁 specs/
  - 📄 2026-04-16-opc-extension-system-design.md 30.0 KB
- 📄 blog-post.md 6.0 KB
- 📄 extension-authoring.md 63.2 KB
- 📄 linkedin-post.txt 1.0 KB
- 📄 runbooks.md 10.9 KB
- 📄 twitter-thread.txt 1.5 KB
📁 examples/
- 📁 dw-integration/
  - 📄 dw-flow.json 870 B
- 📁 extensions/
  - 📁 _starter/
    
    📄 ext.json 174 B
    
    📄 hook.mjs 5.0 KB
    
    📄 README.md 8.3 KB
  - 📄 README.md 1.8 KB
- 📁 runbooks/
  - 📄 add-feature-replay.md 7.0 KB
  - 📄 add-feature.md 4.1 KB
📁 pipeline/
- 📄 context-brief.md 1.5 KB
- 📄 criteria-lint.md 7.7 KB
- 📄 discussion-protocol.md 3.0 KB
- 📄 evaluator-prompt.md 9.2 KB
- 📄 executor-protocol.md 6.7 KB
- 📄 gate-protocol.md 4.2 KB
- 📄 handoff-template.md 1.7 KB
- 📄 implementer-prompt.md 4.7 KB
- 📄 loop-protocol.md 22.3 KB
- 📄 quality-tiers.md 5.5 KB
- 📄 report-format.md 6.8 KB
- 📄 role-evaluator-prompt.md 8.6 KB
- 📄 test-design-protocol.md 5.9 KB
- 📄 ux-observer-protocol.md 12.8 KB
- 📄 ux-simulation-protocol.md 13.9 KB
📁 roles/
- 📄 a11y.md 3.2 KB
- 📄 active-user.md 5.0 KB
- 📄 architect.md 2.0 KB
- 📄 backend.md 2.1 KB
- 📄 churned-user.md 5.9 KB
- 📄 compliance.md 2.1 KB
- 📄 dd-engineer.md 5.0 KB
- 📄 designer.md 3.1 KB
- 📄 devil-advocate.md 5.9 KB
- 📄 devops.md 2.1 KB
- 📄 engineer.md 1.9 KB
- 📄 frontend.md 2.3 KB
- 📄 investor.md 4.9 KB
- 📄 mobile.md 2.6 KB
- 📄 new-user.md 4.5 KB
- 📄 planner.md 1.7 KB
- 📄 pm.md 1.8 KB
- 📄 security.md 2.1 KB
- 📄 tester.md 2.4 KB
- 📄 user-simulator.md 2.2 KB
📁 scripts/
- 📄 postinstall.mjs 493 B
- 📄 verify_devil_advocate.py 11.5 KB
📁 test/
- 📁 fixtures/
  - 📁 run2-ext/
    
    📁 ok-ext/
    
    📄 ext.json 216 B
    
    📄 hook.mjs 1.1 KB
    
    📁 slow-ext/
    
    📄 ext.json 231 B
    
    📄 hook.mjs 1.2 KB
    
    📁 throw-ext/
    
    📄 ext.json 222 B
    
    📄 hook.mjs 582 B
- 📄 run-all.sh 1.0 KB
- 📄 test-backlog.sh 10.8 KB
- 📄 test-bypass-chain.sh 4.9 KB
- 📄 test-compound-defense.sh 30.4 KB
- 📄 test-comprehensive.sh 15.3 KB
- 📄 test-coverage.sh 36.1 KB
- 📄 test-criteria-lint.sh 10.0 KB
- 📄 test-enforcement.sh 15.3 KB
- 📄 test-extensions.sh 674 B
- 📄 test-flow.sh 29.1 KB
- 📄 test-gaps.sh 54.4 KB
- 📄 test-gaps2.sh 46.7 KB
- 📄 test-gaps3.sh 30.6 KB
- 📄 test-gaps4.sh 32.7 KB
- 📄 test-gaps5.sh 27.7 KB
- 📄 test-gaps6.sh 18.7 KB
- 📄 test-harness.sh 15.8 KB
- 📄 test-helpers.sh 997 B
- 📄 test-multiflow.sh 8.9 KB
- 📄 test-reinit.sh 12.5 KB
- 📄 test-review-independence.sh 6.5 KB
- 📄 test-run2-bypass.sh 16.3 KB
- 📄 test-run2-e2e.sh 13.5 KB
- 📄 test-run2-failure-merge.sh 9.6 KB
- 📄 test-run2-strict.sh 10.2 KB
- 📄 test-schema-strict.sh 16.1 KB
- 📄 test-thin-eval.sh 10.8 KB
- 📄 test-tier.sh 26.4 KB
- 📄 test-ux-verdict.sh 23.8 KB
📄 .gitignore 97 B
📄 CHANGELOG.md 18.2 KB
📄 CONTRACTS.md 15.0 KB
📄 CONTRIBUTING.md 5.5 KB
📄 INTEGRATION.md 13.1 KB
📄 LICENSE 1.0 KB
📄 package.json 921 B
📄 README.md 9.5 KB
📄 replay.md 2.8 KB
📄 skill.md 29.2 KB

SKILL.md

---
name: opc
version: 0.10.0
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 .harness/ 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 | build |
| "brainstorm", "explore options", "what are the approaches", "有什么方案" | build-verify | build |
| "plan", "decompose", "break this down", "scope", "estimate", "拆一下" | build-verify | build |
| "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 | build (if ∈ template) |
| An implementation plan | build (if ∈ template) |
| 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 |
|------|------|--------|----------|
| 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.*

### 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 |
| 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. If `.harness/flow-state.json` exists → resume from recorded state. Run `opc-harness validate-chain --dir .harness` first. Show user what was saved and confirm before continuing.
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:

```bash
opc-harness init --flow {TEMPLATE} --entry {ENTRY_NODE} --dir .harness
```

**Show flow graph** — immediately after init, run `opc-harness viz --flow {TEMPLATE} --dir .harness` 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.

### 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 `.harness/acceptance-criteria.md`. 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 `.harness/acceptance-criteria.md` and include them in every subagent prompt.

**Criteria Lint — Mandatory Gate:** After writing `acceptance-criteria.md`, run `opc-harness criteria-lint .harness/acceptance-criteria.md`. 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 14 mechanical checks. Init is gated — `opc-harness init` refuses to start if criteria-lint hasn't passed.

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

- 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 `.harness/nodes/{nodeId}/dynamic-role-{name}.md`. Max 5 dynamic roles per flow run.

Show role selection:
```
📋 Agents:
- frontend — <specific scope>
- security — <specific scope>
...

Launching {N} agents...
```

---

## Node Execution

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} --dir .harness
   - **Show flow viz**: run `opc-harness viz --flow {template} --dir .harness` 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. 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. Dispatch implementer subagent.
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`.

### Node Type: review

Follow `./pipeline/role-evaluator-prompt.md`.

1. Select roles per Role Selection rules.
2. Dispatch evaluators — parallel if no dependencies, serial with context injection if dependencies exist.
3. Each agent writes `eval-{role}.md` to `.harness/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 .harness --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} --dir .harness` → 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

```
.harness/
├── 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
- `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.5",
  "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: 0.9.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. |
| `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 in project (scans `.harness*` directories). |

### Eval Commands

| Command | Usage | Description |
|---------|-------|-------------|
| `verify` | `<file>` | Parse evaluation markdown → JSON (severity counts, verdict, findings). |
| `synthesize` | `<dir> --node <id> [--run N]` | Merge all evaluations for a node → aggregate verdict (PASS/ITERATE/FAIL/BLOCKED). |
| `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 running low:** Write current state to `.harness/flow-state.json` (already maintained by transition commands). The flow-state.json + handshake files carry all state needed to resume. Tell user to re-invoke — orchestrator will detect flow-state.json and resume.

**State recovery:** On resume, run `opc-harness validate-chain --dir .harness`. If inconsistent → surface to user, do not auto-repair.

**Legacy detection:** If `.harness/` 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} --dir .harness`
2. Show summary: total steps, nodes visited, any loopbacks
3. **Generate HTML report:**
   ```bash
   node "$OPC_HARNESS/../opc-report.mjs" --dir .harness --output .harness/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: .harness/report.html
   Want to see the replay? Run: /opc replay
   ```

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

opc

Directory Structure

SKILL.md

Report

Notice