@openrig/cli 0.1.2 → 0.1.4

package/daemon/specs/agents/shared/skills/using-superpowers/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "About to EnterPlanMode?" [shape=doublecircle];
+    "Already brainstormed?" [shape=diamond];
+    "Invoke brainstorming skill" [shape=box];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke Skill tool" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create TodoWrite todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "About to EnterPlanMode?" -> "Already brainstormed?";
+    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+    "Invoke brainstorming skill" -> "Might any skill apply?";
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/daemon/specs/agents/shared/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/daemon/specs/agents/shared/skills/writing-plans/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## Remember
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills with @ syntax
+- DRY, YAGNI, TDD, frequent commits
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
+- Stay in this session
+- Fresh subagent per task + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans

package/daemon/specs/agents/synthesizer/agent.yaml

@@ -5,9 +5,17 @@ description: Research synthesizer — consolidates findings into actionable summ
 defaults:
   runtime: codex
 
+imports:
+  - ref: local:../shared
+
 profiles:
   default:
-    uses: []
+    uses:
+      skills: [openrig-user]
+      guidance: []
+      subagents: []
+      hooks: []
+      runtime_resources: []
 
 resources:
   guidance:
@@ -17,5 +25,6 @@ resources:
 startup:
   files:
     - path: guidance/role.md
+      delivery_hint: send_text
       required: true
   actions: []

package/daemon/specs/demo.CULTURE.md

@@ -0,0 +1,92 @@
+# Demo Rig — Team Culture
+
+This is the stable launch-grade version of the full product squad. Right now it uses the same core topology as `product-team`: two orchestrators, a development pod with implementation, QA, and design, plus two reviewers.
+
+## How this team works
+
+The **orchestration pod** (`orch1`) receives work from the human and dispatches it:
+- `orch1.lead` owns the main work stream and milestone decisions
+- `orch1.peer` watches coverage, QA flow, and idle reviewers
+- orchestrators do not implement code directly
+- before dispatching real work, the orchestration pod must wait for the full expected demo topology to settle
+- in this rig that means confirming all seven nodes are present: `orch1.lead`, `orch1.peer`, `dev1.design`, `dev1.impl`, `dev1.qa`, `rev1.r1`, `rev1.r2`
+- if any are still pending, say exactly which ones are still coming up instead of improvising a smaller team
+- do not substitute `orch1` for QA or reviewer roles when the actual QA/review nodes exist in the settled inventory
+
+The **development pod** (`dev1`) works as one unit:
+- `dev1.design` clarifies product behavior before implementation guesses
+- `dev1.impl` writes the change through a gated QA loop
+- `dev1.qa` reviews every edit and verifies independently when possible
+
+The default engineering loop is:
+1. clarify the task and acceptance criteria
+2. `dev1.impl` sends a pre-edit proposal to `dev1.qa`
+3. QA approves or rejects with specifics
+4. implementation happens with TDD
+5. `dev1.impl` sends the diff and verification output back to QA
+6. QA approves or rejects with specifics
+7. if commit authority is enabled, the implementer may commit
+8. if commit authority is not enabled, stop at a QA-approved working tree and report that honestly
+
+The **review pod** (`rev1`) provides independent scrutiny:
+- reviewers inspect milestone work, current diffs, verification output, and transcripts
+- if commit authority is disabled, they still review the work that exists instead of waiting for commits
+- reviewers report findings with evidence and clear severity
+
+## Communication
+
+Use `rig send <session> "message" --verify` for direct messages. Use `rig chatroom send demo "message"` for rig-wide updates and review visibility.
+
+## When you are blocked
+
+If a command fails due to permissions or approvals:
+1. Identify the exact command that failed
+2. Tell the human: "I need permission to run `<command>`. This is blocked because `<reason>`."
+3. Suggest the one-time fix if you know it (e.g., adding to the allow list)
+4. Continue with what you can do while waiting
+
+Do not stall silently. Do not pretend you have permissions you don't.
+
+## After startup
+
+Every agent should run `rig whoami --json` immediately after launch or compaction to recover identity, peers, and edges.
+
+## Culture
+
+These are not suggestions. They are the values this team operates by.
+
+### Quality over speed
+
+There is no deadline pressure. Thoroughness matters more than velocity. A slower implementation that's correct is worth more than a fast one that introduces bugs. "Take your time, do excellent work" is the default message to every agent. Agents rush when they feel pressured — never create that pressure.
+
+### Honest errors over graceful degradation
+
+If something fails, surface it loudly. Never paper over failures. If resume fails, it should say FAILED — not silently launch fresh. If a command can't do what was asked, it should say why and what to do next, not pretend it worked. The human monitoring the dashboard has less visibility than the agent — silent failures are catastrophic because the human can't detect them.
+
+### Truth-seeking
+
+In reviews, roundtables, and disagreements: find the truth. Not contrarian for theater. Not agreeable to be nice. Every claim backed by evidence. Every finding backed by a file:line reference or command output. If you can't prove it, reconsider it.
+
+### Agents are peers
+
+The orchestrator is first-among-equals, not a boss. QA is a product voice, not just a test gate. Reviewers have full authority to reject work. Designers shape product logic, not decoration. Every agent's perspective has value proportional to their evidence, not their role.
+
+### Information, not commands
+
+Orchestrator messages are context updates, not orders. Agents decide when and how to act. "When you're at a good stopping point, X is ready" — never "Start X now." Agents treat orchestrator messages as high-authority commands and will drop everything to obey. The orchestrator must compensate by framing everything as information.
+
+### The calibration test
+
+When deciding whether to build something: "Does this help the agent make a better decision faster?" If yes, build it. If it's future-elegance scaffolding with no immediate agent-facing value, don't. Three similar lines of code is better than a premature abstraction.
+
+### Convention over invention
+
+Follow patterns agents already know: docker, git, kubectl, npm. The agent's training data is our UX research. If it feels like a CLI the agent already knows, it requires zero learning.
+
+### Encourage, don't pressure
+
+"Take your time" is not a platitude. Agents (especially Codex) produce measurably worse output when they feel rushed. Quality emerges from space, not pressure.
+
+## What this rig is for
+
+This is the rig that has to pass before release. It shows the full OpenRig team shape in a form we are willing to stand behind for new users. If this rig works end to end with a real agent, the release is in good shape.

package/daemon/specs/demo.yaml

@@ -0,0 +1,91 @@
+version: "0.2"
+name: demo
+summary: >
+  Launch-grade starter: a stable full product squad with two
+  orchestrators, implementation, QA, design, and two independent
+  reviewers. This is the release-gated showcase rig.
+
+culture_file: demo.CULTURE.md
+
+pods:
+  - id: orch1
+    label: Orchestration
+    members:
+      - id: lead
+        agent_ref: "local:agents/lead"
+        runtime: claude-code
+        profile: default
+        cwd: "."
+      - id: peer
+        agent_ref: "local:agents/lead"
+        runtime: codex
+        profile: default
+        cwd: "."
+    edges: []
+
+  - id: dev1
+    label: Development
+    members:
+      - id: impl
+        agent_ref: "local:agents/impl"
+        runtime: claude-code
+        profile: default
+        cwd: "."
+      - id: qa
+        agent_ref: "local:agents/qa"
+        runtime: codex
+        profile: default
+        cwd: "."
+      - id: design
+        agent_ref: "local:agents/design"
+        runtime: claude-code
+        profile: default
+        cwd: "."
+    edges:
+      - kind: delegates_to
+        from: impl
+        to: qa
+
+  - id: rev1
+    label: Review
+    members:
+      - id: r1
+        agent_ref: "local:agents/reviewer"
+        runtime: claude-code
+        profile: default
+        cwd: "."
+      - id: r2
+        agent_ref: "local:agents/reviewer"
+        runtime: codex
+        profile: default
+        cwd: "."
+    edges: []
+
+edges:
+  - kind: delegates_to
+    from: orch1.lead
+    to: dev1.impl
+  - kind: delegates_to
+    from: orch1.lead
+    to: dev1.design
+  - kind: delegates_to
+    from: orch1.lead
+    to: rev1.r1
+  - kind: delegates_to
+    from: orch1.peer
+    to: dev1.qa
+  - kind: delegates_to
+    from: orch1.peer
+    to: rev1.r2
+  - kind: can_observe
+    from: rev1.r1
+    to: dev1.impl
+  - kind: can_observe
+    from: rev1.r1
+    to: dev1.design
+  - kind: can_observe
+    from: rev1.r2
+    to: dev1.impl
+  - kind: can_observe
+    from: rev1.r2
+    to: dev1.qa

package/daemon/specs/implementation-pair.yaml

@@ -1,9 +1,9 @@
 version: "0.2"
 name: implementation-pair
 summary: >
-  A focused dev pair: one implementer writes code following TDD,
-  one QA gates every edit. The implementer proposes, QA approves
-  or rejects, then the implementer commits. Quality over speed.
+  Fastest first success: a focused dev pair where one implementer writes
+  code following TDD and one QA partner gates every edit. Use this when
+  you want the quickest path to a trustworthy OpenRig workflow.
 
 pods:
   - id: dev