diff --git a/AGENTS.md b/AGENTS.md index 1d02383..32b6baa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,3 +93,24 @@ artifact_host: https://linear-agent.blmapp.com - Never run `scripts/sync.sh` pointed at a consumer repo automatically - syncs land in consumers via their own `update-skills` PR flow. - Don't commit `./tmp/` or `.DS_Store`. + +## Completing changes + +For an implementation or PR request, continue through the scoped edits, +relevant verification, fixes, and requested PR handoff. Create a work branch or +isolated worktree as needed. A plan or first implementation is not completion. +Existing session authorization covers repeated in-scope local edits and checks; +merge, release, deployment, production actions, and consumer sync need their own +scope of authorization. + +Inspect the affected instructions, callers, and formats. Load other docs only +when their subject matters to the change. Validate Markdown routes and sync +behavior for skill changes; run daemon checks when daemon code or its contracts +change. The local dispatch-survival check uses disposable fixtures. Continue +its local repair/rerun cycle without asking again. Reuse passing checks until +a relevant input changes; read back pushes and PR state before reporting them. + +Keep discovery descriptions brief and specific. Put conditional procedures in +linked references with a clear read condition. Preserve model-independent role, +permission, output, and evidence contracts; avoid adding a gate solely because +a model once needed handholding. diff --git a/CLAUDE.md b/CLAUDE.md index 6e6db4a..25fd0e1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,26 +6,10 @@ artifacts go) is defined in `AGENTS.md` - the skills read it from there. ## Rules -- **You must verify after every mutation.** After a merge, push, PR - creation, file move, or any operation that changes state: read the - actual result back. Never trust command output alone - check that the - change landed where you expected it to. - -- **You must not solve discoverable problems.** If the agent can query it - at runtime (via MCP, the environment, or the repo), don't hardcode it. - Describe roles, boundaries, and rules - not configuration. - -- **Less is more.** Every line should earn its place. If removing a line - wouldn't change behavior, remove it. Overspecification leads to - configuration ceremony, leads to brittleness. When things are brittle, - they break. - -- **No feedback loops.** A step that mutates code after review invalidates - downstream work. The pipeline is linear. Refactoring and cold-read are - manual skills, never inline. - -- **You must never use em dashes.** Use commas, periods, colons, or - parentheses instead. +- Discover runtime configuration through the repo or tools; do not hardcode it. +- Fixes after review invalidate affected evidence. Keep final QA after the last + reviewed code change. Refactoring and cold-read remain manual skills. +- Do not use em dashes. ## Claude-specific notes diff --git a/README.md b/README.md index 430926d..a5e1e64 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ The system at a glance: _Source: [docs/workflow-map.excalidraw](docs/workflow-map.excalidraw)_ -And the story of how it got here - conducted by hand, then Orchestra running -itself, next the factory that feeds itself: +The evolution from manually coordinated stages to an autonomous pipeline, +with signal-driven intake as a direction for further automation: ![From workflow to software factory](docs/software-factory-story.png) @@ -28,12 +28,12 @@ _Source: [docs/software-factory-story.excalidraw](docs/software-factory-story.ex |---|---|---| | `claude/skills/` | Claude Code workflow skills (`/do`, `/create-brief`, `/discussion`, `/investigate`, `/prepare-pull-request`, `postmortem`, `postmortem-loop`, `sentry-loop`, `codex`, `excalidraw-pr-diagrams`, `cold-read`) | `.claude/skills/` | | `claude/agents/` | Claude sub-agent definitions (reviewers, researchers, verifiers, socrates) | `.claude/agents/` | -| `codex/skills/` | Codex role skills (implementer, verifiers, reviewers, researcher, investigator, refactor-simple/-deep) - thin pointers into `references/` | `.codex/skills/` | +| `codex/skills/` | Codex `/do` and `/investigate` workflows, plus role skills for implementation, verification, review, research, and refactoring | `.codex/skills/` | | `references/` | Shared skill-system documents: work-item formats, verification methods, rubrics, sub-agent role instructions and output formats | `.references/` | | `templates/` | Per-project scaffolding (`AGENTS.md`, `CLAUDE.md`) to copy into a new consumer repo and fill in | not synced - copied once by hand | | `daemon/` | Orchestra-only Linear agent webhook service (macOS/launchd behind a Cloudflare Tunnel, or Linux/systemd); each deployment's identity comes from a site config kept in the consumer repo | not synced | | `machines/` | Orchestra-only, versioned physical-machine setup and operations artifacts | not synced | -| `scripts/sync.sh` | The mirror logic (four `rsync --delete` targets) | - | +| `scripts/sync.sh` | Mirrors Orchestra-owned entries in four destinations; preserves consumer-only entries | - | ## The rules that keep this sane @@ -41,8 +41,8 @@ _Source: [docs/software-factory-story.excalidraw](docs/software-factory-story.ex carries an `update-skills` script (e.g. `pnpm update-skills` in bloomapi/bloom-mono) that fetches this repo's `main`, runs `scripts/sync.sh` against a temp worktree, and opens (or force-updates) - the consumer's `chore/orchestra-sync` PR. Run it after pushing a skill - change here. + the consumer's `chore/orchestra-sync` PR. Once the change is on `main`, + run that consumer flow when its sync is authorized. 2. **Repo-agnostic skills.** Nothing in the synced directories may name a specific codebase, database ID, or machine path. All paths are consumer-repo-relative (`.references/…`, `.claude/agents/…`). @@ -53,9 +53,11 @@ _Source: [docs/software-factory-story.excalidraw](docs/software-factory-story.ex wherever the consumer's `AGENTS.md` `Work-item tracking` section says (GitHub issues, Linear, anything the repo documents), and with no instructions there they stay local-only in `./tmp//`. -4. **Idempotent.** The sync is a full mirror (`rsync --delete`); running it - twice produces zero diff. Nothing in the synced dirs is written to at - runtime. +4. **Idempotent.** Each Orchestra-owned directory is an exact mirror + (`rsync --delete` within that entry); consumer-only entries remain. + Retired top-level names are removed by explicit lists in the scripts. + Running a sync twice produces zero diff. Runtime artifacts live outside + the synced instruction directories. 5. **Postmortems** are posted as comments on the run's work item and PR - never as separate tracker issues (local-only when no tracker/anchor exists); proposed system changes are applied here in orchestra. @@ -118,3 +120,17 @@ This repo supersedes the `tyler/` tree of `dcouple/skills`, which previously synced to `~/.claude`, `~/.codex`, and `~/.references` on each machine. Skills now travel with each consumer repo instead, so clones, CI, and cloud agents get them with no machine setup. + +## Reading and maintaining the workflows + +The Claude and Codex `/do` entrypoints route to stage-specific references: +load execution boundaries once, then the current stage. Research depth, +review lanes, and QA follow the work item's evidence requirements and the +selected harness. Existing authorization carries through scoped edits, +checks, fixes, and the requested PR handoff; merge and deployment have their +own authorization boundaries. + +Use [WORKFLOW.md](WORKFLOW.md) for the stage map and authoritative role links. +The [diagram index](docs/README.md) identifies each visual's scope and render +command. Update both the Excalidraw source and its PNG when a depicted +workflow changes. diff --git a/WORKFLOW.md b/WORKFLOW.md index e57dce8..fb2240a 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -1,141 +1,113 @@ # The workflow -A dual-harness development workflow. Claude Code is the orchestrating -harness: Fable makes the judgment calls and dispatches sub-agents; Codex -(GPT-5.6) runs the engineering-heavy roles. - -The whole system at a glance: +Orchestra captures a work item, executes its scoped outcome, and hands over a +reviewed PR with evidence. Claude Code and Codex have separate `/do` +entrypoints. They share artifacts and role contracts while retaining their +own dispatch, review-budget, and browser procedures. ![Orchestra workflow map](docs/workflow-map.png) _Source: [docs/workflow-map.excalidraw](docs/workflow-map.excalidraw)_ -The flow separates *clarity*, *capture*, and *execution*: - -1. **`/discussion`** - clarify, understand, figure out. General-purpose: it - dispatches the code-researcher / `web-researcher` for questions and the - investigator (with `frontend-verifier` for reproduction) when the topic is a - defect. It produces clarity plus a dated decision log - (`./tmp/discussions/`) that the `/create-brief` drafting step reads - never - deliverables. -2. **`/create-brief`** - the capture skill, invoked by the user or by the - model when a conversation converges. It turns what the conversation - established into a work item at `./tmp//brief.html` (a feature or bug - brief - single-outcome or multi-phase, phases being a property of the - item; raw sources and research sub-reports in `./tmp//refs/`) with a - Dependencies & mechanics inventory (verified vs assumed, explicit schema - delta, sequencing) and verification criteria. The brief page is both the - alignment surface the user reads in the browser and the contract `/do` - executes against - machine state lives in its `#orchestra-meta` head - block (`references/html-brief.md`). It then **publishes** wherever the - project's `AGENTS.md` `Work-item tracking` section says - with an - `artifact_host`, a lean tracker body pointing at the bundle; without - one, a markdown rendition of the brief as the issue body with the HTML - riding as marker comments; with no destination at all, the item stays - local in `./tmp//` and the skill says so. `/create-brief` runs - the investigator itself if the root cause isn't already established. - Before publish, every draft passes the **Socratic gate**: the `socrates` - sub-agent takes an adversarial position on the item's premise (needed at - all? root cause or symptom? simpler path? right shape? which dependency - is assumed rather than verified? the whole of it?) and the user's - answers - distilled into the brief's Justification section - travel with - the published item. Intensity is socrates' own calibration - (`claude/agents/socrates.md`). -3. **`/do `** - the autonomous pipeline: pull the work - item's artifacts into `./tmp//` (fetched per the project - `AGENTS.md`'s `Work-item tracking` instructions - e.g. harvested from a - GitHub issue's artifact comments - or read from `./tmp//` when the - repo configures no tracker) → - zone-derived dials (`references/zones.md`) → plan + review loop (full lane backed by - a research dossier, every plan under the evidence contract) → implement → - verify → build gate + deploy-notes scan + PR → post-PR review loop + QA - pass over the PR's manual tests → wrap-up, with the wrap-up posted as a - PR comment at the end. Deliberately high-level: - the Overseer applies the item's zone (escalating one notch at most), how much research a plan needs, and when - each review loop has converged. -4. **`/prepare-pull-request`** - the exit ramp for ad-hoc changes made in a - session *outside* `/do` (which handles its own PR prep). It retrofits - the pipeline's gates before anything goes up: the Overseer materializes - an `intent.md` + diff under `./tmp/pr-/`, Socrates challenges - the approach in PR mode (sunk cost is not a defense; diff-vs-intent - fidelity joins the attack lines), both code reviewers gate correctness - (union Must-Fix, cap 3 passes), then build gate → commit → PR in the - repo's documented format. -5. **`/postmortem`** - when a result falls short, root-cause it in *our - system* (skill/agent/template), not just the code. - -## Model routing - -This table is the single source of truth for model routing - the guides and -skills point here; update it first when routing changes, and update `/do`'s -**Sub-agents** paragraph in the same commit: this file is not synced to -consumer repos, so the skills' restatement is what actually executes. - -| Role | Runs on | Notes | +## Choose the entrypoint + +| Need | Entry | Result | +| --- | --- | --- | +| Clarify an idea or decision | [Claude `/discussion`](claude/skills/discussion/SKILL.md) | Clarity and a dated decision log under `./tmp/discussions/` | +| Reproduce and explain a defect | [Claude `/investigate`](claude/skills/investigate/SKILL.md) or [Codex `/investigate`](codex/skills/investigate/SKILL.md) | Root-cause evidence for the next decision | +| Capture a work item | [Claude `/create-brief`](claude/skills/create-brief/SKILL.md) | `brief.html`, acceptance criteria, justification, and supporting `refs/` | +| Execute a ready work item | [Claude `/do`](claude/skills/do/SKILL.md) or [Codex `/do`](codex/skills/do/SKILL.md) | Implementation, review, QA, PR, and wrap-up | +| Prepare ad-hoc changes for review | [Claude `/prepare-pull-request`](claude/skills/prepare-pull-request/SKILL.md) | Intent check, Socratic challenge, code review, build gate, and PR | +| Learn from a result that fell short | [Claude `/postmortem`](claude/skills/postmortem/SKILL.md) | System-level root cause and an improvement proposal | + +`/create-brief` runs the Socratic gate before publication and preserves its +alignment pause. Work items follow the consumer's `AGENTS.md` work-item +tracking configuration. An artifact host carries the complete bundle with a +lean tracker body; other configured destinations follow the +[publishing contract](references/publish-work-item.md). With no configured +destination, artifacts stay local under `./tmp//`. + +`/do` is user-invoked (`disable-model-invocation: true`). Invocation metadata +for other skills lives in their own frontmatter. + +## Execute by stage + +Read `references/execution-boundaries.md` once from the selected `/do` +directory, then load the current stage. Paths inside stage files resolve from +that skill directory. Shared `.references/` paths resolve from the consumer +repo, or from the rewritten user-level installation. + +| Stage | Contract file in each `/do/references/` | Work | +| --- | --- | --- | +| 0 | `preflight.md` | Load the ready item and its criteria; inspect relevant project instructions, tools, and working state | +| 1 | `plan.md` | Apply zone and explicit item settings; gather the required research and review the evidence-backed plan | +| 2 | `implement.md` | Implement the scoped change and integrate review fixes | +| 3 | `verify.md` | Prove command-shaped criteria; carry app-only criteria into final QA | +| 4 | `pull-request.md` | Build gate, deploy-notes scan, commit, push, and prepare the PR with its required evidence | +| 5 | `review-qa.md` | Review the PR, resolve material findings within budget, and perform the applicable final QA | +| 6 | `wrap-up.md` | Record actual results, unresolved evidence, run statistics, and the PR handoff | + +The stage routers are the [Claude `/do`](claude/skills/do/SKILL.md) and +[Codex `/do`](codex/skills/do/SKILL.md) roots. Their linked files contain the +full procedures, output formats, and harness-specific exceptions. Load +conditional references only when their subject applies. A docs-only change +does not require an app boot, and passing evidence remains usable until a +relevant input changes. + +Stages continue under existing authorization. Local branch/worktree creation, +scoped fixes, and relevant checks are part of execution. A planning-only +request still returns its plan, and a prepared PR does not authorize merge, +release, deployment, production changes, or broader scope. Missing evidence +is recorded as blocked or unverified. + +Multi-phase items persist phase state in `plan-.md` and chain phases +without a new permission prompt. Review accounting follows the selected +entrypoint; consult its phase and review-stage rules before dispatching. + +## Role and model routing + +Executable routing lives in the skills and agent definitions linked below. +This overview describes those contracts rather than duplicating model IDs +that can drift from dispatch code. + +| Role | Claude `/do` | Codex `/do` | | --- | --- | --- | -| Overseer (conducts `/do`, all judgment) | main session - Fable | | -| Web research | Claude `web-researcher` - Sonnet | | -| App-driving QA (one run, post-PR: UI ACs + Manual tests, journey captures) | Claude `frontend-verifier` - Sonnet | also reproduces failures for /discussion & /create-brief | -| Verify backend (tests/scripts) | **Codex** GPT-5.6 `low` | | -| Explore codebase | **Codex** GPT-5.6 `low` | Claude `code-researcher` (Sonnet) as backup | -| Reproduce & root-cause | **Codex** GPT-5.6 `low` | | -| Write the diff - all surfaces, one dispatch per vertical slice | **Codex** GPT-5.6 `medium` | fix rounds resume the same session; repo statically green after every dispatch | -| Challenge the draft work item (Socratic gate) | Claude `socrates` - Fable | always invoked by `/create-brief`; self-calibrates - fast-passes straightforward drafts, full challenge for multi-phase/unargued items | -| Review the plan | dual at zone 0 (Codex GPT-5.6 `low` + Claude `plan-reviewer` (Opus)); zones 1–3 Codex alone | Must-Fix gate = union of the lanes run | -| Review the diff + security | dual at zone 0 (Codex GPT-5.6 `low` + Claude `code-reviewer` (Opus)); zones 1–3 Codex alone | Must-Fix gate = union of the lanes run | - -Every Codex role is dispatched by the **`codex` skill** -(`claude/skills/codex/`), the one place that knows the `codex exec` -mechanics per role - model, effort, session mode (`--yolo` for every role; -reviewers/researchers ephemeral and no-edit by charter; implementer -persistent with `resume --last` across fix rounds), output capture, and -status-line parsing. - -Review loops exit when **no Must Fix remains from either reviewer** - a -Codex report tiered P0–P3 maps rather than reformats (P0/P1 ≡ Must Fix, -P2 ≡ Should Fix, P3 ≡ Nice to Have). Caps are ceilings, never quotas: a -zero-Must-Fix pass ends the loop even with Should Fixes open (the Overseer -applies those at its discretion, no re-review), and the only other trigger -for an extra pass is the two lanes sharply diverging. When reviewers disagree, -the Overseer adjudicates directly, using sub-agents to understand what is true -when needed. The Overseer flags anything left unresolved at a cap in the -wrap-up. Codex efforts are defaults - `medium` for the -implementer, `low` for every other role; the dispatcher may raise a -reviewer to `medium` or `high` rarely, when the zone warrants it (zone 0 -or a multi-phase item), with the reason stated in the dispatch - never above `high`. `/do` and -`/prepare-pull-request` are user-invoked only (`disable-model-invocation`). The -`/create-brief` capture skill is model-invocable at convergence, with publish still gated by -its alignment pause. - -## Where formats live (single copy each - no duplicates to drift) - -- **`references/`** (synced to `.references/` in each consumer repo - - harness-neutral) - anything referenced by more than - one skill, or by any agent: the shared blocks (`verification-criteria.md`, - `verification-methods.md`, `rubrics/` - per-surface verification rubrics, - `code-quality.md` - the reviewers' house-rules rubric, `qa-verification.md` - - the QA pass's external-evidence discipline, `system-analysis.md`, - `publish-work-item.md`, `html-brief.md` + - `brief-template.html` - the work-item page contract and skeleton, - `socratic-gate.md`) and every agent's output format - (`references/agents//…`). Agents are flat `.md` files by design - (Claude Code has no agent-folder format), so each agent's body carries a - pointer - "Read `.references/agents//.md`" - plus a few - non-negotiable lines as a safety net if the file is missing. -- **`claude/skills//references/`** - document formats produced by - exactly one skill (implementation-plan, wrap-up-report, postmortem). - -The five workflow skills above, plus two infrastructure skills the others -invoke - `codex` (dispatches Codex roles) and `excalidraw-pr-diagrams` (the -PR visual-overview standard `/do`'s PR step uses) - are the whole surface. Web research is the -`web-researcher` sub-agent, review lives inside `/do` (plan review before -implement, code review + QA after the PR opens), and all commit/PR prep -lives in `/do`'s PR step. - -## Keeping in sync - -See [README.md](README.md): skills are edited only in this repo and mirrored -one-way into each consumer repo by that repo's `update-skills` script -(`pnpm update-skills` in bloomapi/bloom-mono), which wraps `scripts/sync.sh`. -The old per-machine rsync to `~/.claude`, `~/.codex`, and `~/.references` is -retired. +| Overseer | Main session; configured Claude/Claudex runtime | Main Codex session | +| Implementation | Codex `implementer`, default effort `medium`, all surfaces | Codex `implementer`, default effort `low`, all surfaces | +| Code research, investigation, backend verification | Codex roles through the dispatcher | Matching Codex role skills | +| Plan and code review | Zone-derived lanes; dual Codex + Claude at zone 0 by default, Codex alone at zones 1–3; explicit item/runtime settings apply | Single Codex lane under this entrypoint | +| External research | Claude `web-researcher` | Codex `web-researcher` | +| App-driving final QA | Claude `frontend-verifier` | Codex `frontend-verifier`, local Playwright by default | + +The [Claude-to-Codex dispatcher](claude/skills/codex/SKILL.md) owns its +configured model, effort, session, timeout, and result collection rules. +Its [dispatch reference](claude/skills/codex/references/dispatch.md) loads +only for a launch, resume, or collection operation. Read-only role charters +and active harness permissions still apply to unattended CLI settings. + +Reviewers are independent of the implementer. A clean Must-Fix result ends +the applicable review pass; budgets are ceilings. The +[zones reference](references/zones.md) defines stakes and shared dials, while +the selected entrypoint and review stage specify its lane and budget rules. +Explicit item settings and documented runtime fallback remain visible in +the plan and wrap-up. Optional tools such as `arena` are used only when their +work would resolve material uncertainty and the tool is available. + +## Sources and supporting tools + +- [Shared references](references/README.md) hold work-item formats, + verification methods, rubrics, role instructions, and role output formats. +- Each skill's own `references/` directory holds its stage procedures and + private formats. Both `/do` roots link to the implementation-plan, PR-body, + and wrap-up formats they produce. +- [Claude skills](claude/skills/README.md), [Codex skills](codex/skills/README.md), + and [Claude agents](claude/agents/README.md) identify the current surface, + including the postmortem and Sentry loops, manual cold-read, refactoring + roles, and [Excalidraw diagrams](claude/skills/excalidraw-pr-diagrams/README.md). + +## Installation and visuals + +The [README](README.md) documents consumer-repo sync and the supported optional +user-level installer. Consumer changes go through their authorized sync PR +flow. [The visual index](docs/README.md) distinguishes the executable workflow +map from the broader software-factory direction and explains regeneration. diff --git a/claude/agents/README.md b/claude/agents/README.md index 00d29de..d20fd80 100644 --- a/claude/agents/README.md +++ b/claude/agents/README.md @@ -1,5 +1,13 @@ -# Synced from dcouple/orchestra - do not edit here +# Orchestra Claude agents This directory is a one-way mirror of `claude/agents/` in [dcouple/orchestra](https://github.com/dcouple/orchestra). Any edit made in a consumer repo is overwritten by the next sync PR. Change agents in orchestra. + +## Roles + +[`code-researcher`](code-researcher.md) [`code-reviewer`](code-reviewer.md) [`frontend-verifier`](frontend-verifier.md) [`plan-reviewer`](plan-reviewer.md) [`socrates`](socrates.md) [`web-researcher`](web-researcher.md) + +Read the selected agent definition and its linked shared instructions or output +format. Model pins live in agent frontmatter; dispatch topology belongs to the +calling workflow. Reviewers inspect evidence independently and do not edit. diff --git a/claude/agents/code-researcher.md b/claude/agents/code-researcher.md index 581ced7..484cbc1 100644 --- a/claude/agents/code-researcher.md +++ b/claude/agents/code-researcher.md @@ -1,6 +1,6 @@ --- name: code-researcher -description: Backup for the Codex code-researcher - codebase research normally runs via the codex skill. Explores the codebase and returns file:line findings. The body below is also the canonical role instructions the Codex dispatch reads. +description: "Locate repository facts with file and line evidence when dispatched for codebase research." tools: Read, Grep, Glob, LS model: sonnet color: blue diff --git a/claude/agents/code-reviewer.md b/claude/agents/code-reviewer.md index 3c127f2..aaed4ed 100644 --- a/claude/agents/code-reviewer.md +++ b/claude/agents/code-reviewer.md @@ -1,6 +1,6 @@ --- name: code-reviewer -description: The Claude lane of the diff reviewers - dispatched alongside the Codex code-reviewer at zone 0 in /do's post-PR review loop (zones 1–3 run Codex alone; .references/zones.md), or when review_lanes explicitly selects dual (including per-phase diff reviews on multi-phase items); the Must-Fix gate is the union of both reports. Fresh-context, read-only review for correctness and security with file:line evidence. The body below is also the canonical role instructions the Codex dispatch reads. +description: "Review an implementation diff for correctness and security when selected by the workflow review lane." tools: Glob, Grep, Read, Bash model: opus color: orange diff --git a/claude/agents/frontend-verifier.md b/claude/agents/frontend-verifier.md index acf55fc..55e5d0b 100644 --- a/claude/agents/frontend-verifier.md +++ b/claude/agents/frontend-verifier.md @@ -1,6 +1,6 @@ --- name: frontend-verifier -description: The app-driving QA agent - runs once per /do pipeline, post-PR: proves the run's UI acceptance criteria and executes the PR's Manual tests checklist in a single session with journey-mapped captures, or reproduces reported failures for /discussion and /create-brief. Uses browser automation. Backend criteria (tests/scripts) go to the Codex backend-verifier instead. Use when "done" (or "broken") must be demonstrated in the running app, not assumed. +description: "Drive browser or mobile QA to prove UI criteria and manual journeys, or reproduce a reported UI failure." tools: Bash, Read, Grep, Glob, LS, ToolSearch, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_fill_form, mcp__playwright__browser_tabs, mcp__playwright__browser_wait_for, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages, mcp__playwright__browser_network_requests, mcp__playwright__browser_start_tracing, mcp__playwright__browser_stop_tracing, mcp__playwright__browser_start_video, mcp__playwright__browser_stop_video, mcp__playwright__browser_evaluate, mcp__playwright__browser_close, mcp__xcodebuildmcp__session_set_defaults, mcp__xcodebuildmcp__session_show_defaults, mcp__xcodebuildmcp__list_sims, mcp__xcodebuildmcp__boot_sim, mcp__xcodebuildmcp__open_sim, mcp__xcodebuildmcp__build_sim, mcp__xcodebuildmcp__get_sim_app_path, mcp__xcodebuildmcp__install_app_sim, mcp__xcodebuildmcp__launch_app_sim, mcp__xcodebuildmcp__stop_app_sim, mcp__xcodebuildmcp__snapshot_ui, mcp__xcodebuildmcp__tap, mcp__xcodebuildmcp__long_press, mcp__xcodebuildmcp__swipe, mcp__xcodebuildmcp__drag, mcp__xcodebuildmcp__gesture, mcp__xcodebuildmcp__type_text, mcp__xcodebuildmcp__key_press, mcp__xcodebuildmcp__wait_for_ui, mcp__xcodebuildmcp__screenshot, mcp__xcodebuildmcp__record_sim_video model: sonnet color: purple diff --git a/claude/agents/plan-reviewer.md b/claude/agents/plan-reviewer.md index 0690110..27d608b 100644 --- a/claude/agents/plan-reviewer.md +++ b/claude/agents/plan-reviewer.md @@ -1,6 +1,6 @@ --- name: plan-reviewer -description: The Claude lane of the plan reviewers - dispatched alongside the Codex plan-reviewer at zone 0 (zones 1–3 run Codex alone; .references/zones.md), or when review_lanes explicitly selects dual; the Must-Fix gate is the union of both reports. Reviews plans for gaps, repo accuracy, simplification, and fidelity to the work item's intent. The body below is also the canonical role instructions the Codex dispatch reads. +description: "Review a plan against the work item and repository evidence when selected by the workflow review lane." tools: Glob, Grep, Read model: opus color: yellow diff --git a/claude/agents/socrates.md b/claude/agents/socrates.md index 05109c6..8993d89 100644 --- a/claude/agents/socrates.md +++ b/claude/agents/socrates.md @@ -1,6 +1,6 @@ --- name: socrates -description: The Socratic gate on a drafted artifact - a work item before publish (invoked by /create-brief), or a completed change before its PR (invoked by /prepare-pull-request). Takes an adversarial position on the artifact's premise - is it needed, is it the root cause, should it split, is there a simpler path, is this the whole of it - and judges the answers. Intensity scales with the stakes: a straightforward, well-justified draft gets a fast pass with zero to two questions; a multi-phase or unargued draft gets the full challenge. Do not invoke proactively - only when a skill's instructions or the user explicitly call for the Socrates gate; the dispatch names the artifact under review. +description: "Challenge a brief or PR premise when the user or workflow explicitly requests the Socratic gate." tools: Glob, Grep, Read model: fable color: magenta diff --git a/claude/agents/web-researcher.md b/claude/agents/web-researcher.md index 963534d..d5c004d 100644 --- a/claude/agents/web-researcher.md +++ b/claude/agents/web-researcher.md @@ -1,6 +1,6 @@ --- name: web-researcher -description: Researches external documentation, libraries, and best practices with cited findings. Used by /discussion and /do's plan stage when a question can't be answered from the codebase. Use for library choices, API behavior, version-sensitive facts, and prior art. +description: "Research external APIs, dependencies, or version-sensitive behavior that repository evidence cannot resolve." tools: WebSearch, WebFetch, Read, Grep, Glob model: sonnet color: green diff --git a/claude/skills/README.md b/claude/skills/README.md index 66d9cb8..c0ea32e 100644 --- a/claude/skills/README.md +++ b/claude/skills/README.md @@ -1,4 +1,4 @@ -# Synced from dcouple/orchestra - do not edit here +# Orchestra Claude Code skills This directory is a one-way mirror of `claude/skills/` in [dcouple/orchestra](https://github.com/dcouple/orchestra). Any edit made in a @@ -7,3 +7,12 @@ consumer repo is overwritten by the next sync PR. Change skills in orchestra. Repo-specific configuration (e.g. work-item tracking and where work-item artifacts go) belongs in this repo's `AGENTS.md` / `CLAUDE.md`, never in these files. + +## Entrypoints + +[`codex`](codex/SKILL.md) [`cold-read`](cold-read/SKILL.md) [`create-brief`](create-brief/SKILL.md) [`discussion`](discussion/SKILL.md) [`do`](do/SKILL.md) [`excalidraw-pr-diagrams`](excalidraw-pr-diagrams/SKILL.md) [`investigate`](investigate/SKILL.md) [`postmortem`](postmortem/SKILL.md) [`postmortem-loop`](postmortem-loop/SKILL.md) [`prepare-pull-request`](prepare-pull-request/SKILL.md) [`sentry-loop`](sentry-loop/SKILL.md) + +`do/SKILL.md` routes to stage contracts under `do/references/`. Load +execution boundaries once, then the current stage and its conditional references. +Skill frontmatter and role instructions define this harness's routing; the +Claude and Codex entrypoints retain their own dispatch and QA procedures. diff --git a/claude/skills/codex/SKILL.md b/claude/skills/codex/SKILL.md index 2f1fb47..1e7ab03 100644 --- a/claude/skills/codex/SKILL.md +++ b/claude/skills/codex/SKILL.md @@ -1,6 +1,6 @@ --- name: codex -description: Dispatches one Codex (GPT-5.6) sub-agent via `codex exec` - implementer, backend-verifier, plan-reviewer, code-reviewer, code-researcher, or investigator - and returns its report. Used by /do, /discussion, and /create-brief whenever one of these roles runs; not normally invoked by the user directly. Use when a pipeline stage needs its Codex sub-agent dispatched, resumed for a fix round, or re-run. +description: "Dispatch or resume one Codex role when a workflow needs an implementation, research, review, or verification report." argument-hint: "[role] [inputs: item/plan paths, question, pass number]" --- @@ -30,192 +30,19 @@ reason stated in the dispatch; never above `high`, never by default. The investi backend-verifier act on the environment (tests, scripts, app boots), but their charters forbid editing project files. -**Approvals must never gate a pipeline dispatch.** Every role runs with -`--yolo` (`--dangerously-bypass-approvals-and-sandbox`) - the run is -unattended, and an approval prompt or approval-layer refusal mid-flight burns -the dispatch. The operator authorizes this via the /do preflight harness -check. Reviewer/researcher dispatches are still no-edit by charter (see -Rules: one that edited files is a failed run) - the guarantee is the charter -plus a diff check. The `implementer` role covers -every surface - backend/ops and frontend web/mobile alike, one effort -(`medium`), one session per slice. +The table describes the configured unattended CLI deployment. Use `--yolo` +only where the operator and active harness permit it; a skill does not grant +permission to bypass a denial. Reviewers and researchers remain read-only by +charter, verified against the diff. The implementer owns the entire assigned +vertical slice and resumes the same session for fixes. -## Steps +## Dispatch procedure -### 1. Build the prompt -Every prompt names the role instructions and output format by absolute path - -Codex reads them itself: - -``` -You are acting as the in an automated software-development pipeline -conducted by the Overseer, a separate orchestrating agent. You are a -sub-agent - a leaf of this pipeline: never spawn further agents or invoke -agent CLIs (`codex exec`, `claude`, or any equivalent) - do the work in -this session yourself and print your report. Your report is -consumed by the Overseer, not by a human. - -First read these two files: -1. Your role instructions: . -2. Your output format: - your - final message must follow it exactly. - -Inputs for this run: -- work item: -- plan: -- question / defect report: -- review pass: / -- prior findings by ID: / fix instructions: - -Print the report as your final message, in exactly the specified format. -``` - -Role instructions: Codex-only roles (implementer, investigator, -backend-verifier, refactor-simple, refactor-deep) → `.references/agents//instructions.md` · roles -with a Claude twin (code-researcher, plan-reviewer, code-reviewer) → -`.claude/agents/.md` (tell Codex to follow the body and ignore the -YAML frontmatter - it applies to a different harness). - -Format files, under `.references/agents//`: implementer → -`implementation-result.md` · plan-reviewer / code-reviewer → -`review-report.md` · code-researcher → `codebase-findings.md` · -investigator → `root-cause-finding.md` · backend-verifier → -`../frontend-verifier/verification-result.md` (shared verifier format, -verify mode) · refactor-simple / refactor-deep → `refactor-report.md`. - -**Path resolution**: all paths are relative to the current repo root - -`.references/` and `.claude/agents/` are synced into every consumer repo -from `dcouple/orchestra`. Confirm both files exist before dispatching - a -role that can't read its instructions improvises instead of failing. - -**Success criteria**: prompt carries the role, both file paths (resolved -per the rule above, existence checked), and every input the role needs - -nothing assumed from this conversation. - -### 2. Execute -At every turn start, before launching new work, inspect -`.codex-dispatches/${ORCHESTRA_DISPATCH_OWNER:-local}/*.done`. Pick up each -completed report, then delete all files with that dispatch's basename after -consuming it. Delete-on-consume is load-bearing: markers otherwise persist and -the daemon deliberately enqueues at most one resume per marker. - -Delete with **literal paths only** - resolve the owner directory and the -dispatch name first, then write them out in full: - -```bash -rm -f .codex-dispatches/local/code-researcher-1756340000-4242-1.{prompt,sh,log,md,done} -``` - -Never `rm` a path built from a shell variable or a glob under one -(`rm -f "$dir/$name".*`): Claude Code's critical-path check prompts on that -form even in bypass mode, and the prompt halts an unattended run. - -Launch every dispatch fully detached from the harness, from the repo root. The -owner directory is `.codex-dispatches/$ORCHESTRA_DISPATCH_OWNER` when the daemon -sets that variable to the Linear session UUID, and `.codex-dispatches/local` -otherwise. Prepare it once per worktree: - -```bash -own="${ORCHESTRA_DISPATCH_OWNER:-local}"; dir=".codex-dispatches/$own" -mkdir -p "$dir" -exclude="$(git rev-parse --git-path info/exclude)" -grep -qxF '/.codex-dispatches/' "$exclude" 2>/dev/null || printf '/.codex-dispatches/\n' >> "$exclude" -``` - -For each launch choose -`=--$$-`, where the caller sequence is unique among -concurrent launches. Write the prompt to `.prompt` with a quoted heredoc, -then write this launcher as `.sh` (substitute the concrete paths and -arguments while writing it): - -```bash -#!/usr/bin/env bash -perl -e 'alarm shift; exec @ARGV or die "exec failed: $!"' \ - codex exec -m gpt-5.6-sol -c model_reasoning_effort="" --yolo \ - [--ephemeral] --skip-git-repo-check -C \ - -o /.md "$(cat /.prompt)" /.done.tmp && \ - mv /.done.tmp /.done -``` - -Use a 900-second `` for `--ephemeral` roles and 2700 for the implementer. -Redirect stdin as shown because Codex can hang on an open idle pipe. Detach the -launcher itself with Perl's portable `setsid` (macOS has no `setsid` binary): - -```bash -nohup perl -MPOSIX -e 'POSIX::setsid(); exec @ARGV or die "exec failed: $!"' \ - bash /.sh > /.log 2>&1 & disown -``` - -For an implementer fix round, use the same launcher and marker write, replacing -its command with the following so session context survives: - -```bash -perl -e 'alarm shift; exec @ARGV or die "exec failed: $!"' 2700 \ - codex exec resume --last --yolo -o /.md \ - "$(cat /.prompt)" /.done.tmp && \ - mv /.done.tmp /.done -``` - -A resume dispatch carries `--yolo` exactly like a fresh one - a resumed -session that loses it runs sandboxed and blocks the very tests the fix -round must run. `resume` takes no `-C`: it matches recorded sessions by -cwd, so launch it from the same repo root as the original dispatch. - -The marker convention is: `.md` is the final report, `.log` is -durable stdout/stderr including the `tokens used` summary, and `.done` -contains exactly the exit code. The `.done` file is written even for failures, -including watchdog exit 142. A tracked wait loop may poll only the marker for -in-turn pickup; its death at turn end is harmless because the detached Codex -process survives and turn-start pickup covers recovery. - -Parallel dispatches (e.g. several code-researchers, or a reviewer alongside a -Claude sub-agent) are launched together. A dual-lane review that does not issue -the detached launches together serializes the lanes and doubles wall-clock. - -**Success criteria**: `.done` exists, contains 0, and the sibling `.md` exists -and is non-empty. Exit 142 is the watchdog's SIGALRM reap signature: it is a -classified failure, not a success, and step 3 handles it. - -### 3. Return the report -Read the output file. Check the status line the format requires (reviewers: -`**Verdict:**` + `**Counts:**` with the Must Fix count - a reviewer report -that arrives tiered P0–P3 instead is a valid report, not a failed run: -P0/P1 ≡ Must Fix, P2 ≡ Should Fix, P3 ≡ Nice to Have; map the tiers, -synthesize the status line from the mapped counts yourself, and never -burn a retry or re-dispatch over format · implementer: -`**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` · -code-researcher: `**Bottom line:**` · investigator: `**Root cause:**` with a -confidence word · backend-verifier: `**Verdict:**` pass|fail). Capture the -token usage `codex exec` prints in its end-of-run summary from the dispatch's -sibling `.log` file (the line after `tokens used`); per-turn detail lives in -`~/.codex/sessions//rollout-*.jsonl` `token_count` events. `unknown` is -only legal after checking both. For a resumed session the printed figure is -**cumulative**: record the delta from the previous dispatch's figure as the -round's cost and the final figure as the role total. Return the -report verbatim to the caller, prefixed with one line: -`CODEX : · tokens ` - the Overseer sums -these per role into the wrap-up's run record. - -Exit 142 (a SIGALRM watchdog reap) classifies the dispatch as a hung run. Retry -a hung, errored, timed-out, or status-line-missing run once: make a fresh -dispatch for an ephemeral role, or use `resume --last` for the implementer so -its session context survives. A retry that is also reaped never gets a third -Codex dispatch - a workload that wedged twice stays wedged: reviewer, -researcher, and verifier work routes to a Claude sub-agent dispatch instead; -the implementer has no Claude counterpart, so a twice-reaped implementer -returns the error plus whatever output exists to the caller. Otherwise return -the error plus whatever output exists after the single retry. A report of `listen EPERM` (the sandbox denied loopback -binds) is a completed run, not a failure: accept the edits and run the blocked -check at the Overseer, or hand it to the next verifier dispatch, instead of -re-dispatching. - -**Success criteria**: caller received a well-formed report (or the error -after one retry). +Read [dispatch mechanics](references/dispatch.md) when launching, resuming, +or collecting a role. It owns prompt construction, literal-path cleanup +(including `.otel.json`), detached launch, timeout, and the single retry. +Only load the selected role's instructions and report format. Return the role's +report with its status and token usage; a launch acknowledgment is not completion. ## Rules diff --git a/claude/skills/codex/references/dispatch.md b/claude/skills/codex/references/dispatch.md new file mode 100644 index 0000000..05620c6 --- /dev/null +++ b/claude/skills/codex/references/dispatch.md @@ -0,0 +1,178 @@ +# Dispatch mechanics + +## Steps + +### 1. Build the prompt +Every prompt names the role instructions and output format by absolute path - +Codex reads them itself: + +``` +You are acting as the in an automated software-development pipeline +conducted by the Overseer, a separate orchestrating agent. You are a +sub-agent - a leaf of this pipeline: never spawn further agents or invoke +agent CLIs (`codex exec`, `claude`, or any equivalent) - do the work in +this session yourself and print your report. Your report is +consumed by the Overseer, not by a human. + +First read these two files: +1. Your role instructions: . +2. Your output format: - your + final message must follow it exactly. + +Inputs for this run: +- work item: +- plan: +- question / defect report: +- review pass: / +- prior findings by ID: / fix instructions: + +Print the report as your final message, in exactly the specified format. +``` + +Role instructions: Codex-only roles (implementer, investigator, +backend-verifier, refactor-simple, refactor-deep) → `.references/agents//instructions.md` · roles +with a Claude twin (code-researcher, plan-reviewer, code-reviewer) → +`.claude/agents/.md` (tell Codex to follow the body and ignore the +YAML frontmatter - it applies to a different harness). + +Format files, under `.references/agents//`: implementer → +`implementation-result.md` · plan-reviewer / code-reviewer → +`review-report.md` · code-researcher → `codebase-findings.md` · +investigator → `root-cause-finding.md` · backend-verifier → +`../frontend-verifier/verification-result.md` (shared verifier format, +verify mode) · refactor-simple / refactor-deep → `refactor-report.md`. + +**Path resolution**: all paths are relative to the current repo root - +`.references/` and `.claude/agents/` are synced into every consumer repo +from `dcouple/orchestra`. Confirm both files exist before dispatching - a +role that can't read its instructions improvises instead of failing. + +**Success criteria**: prompt carries the role, both file paths (resolved +per the rule above, existence checked), and every input the role needs - +nothing assumed from this conversation. + +### 2. Execute +At every turn start, before launching new work, inspect +`.codex-dispatches/${ORCHESTRA_DISPATCH_OWNER:-local}/*.done`. Pick up each +completed report, then delete all files with that dispatch's basename after +consuming it. Delete-on-consume is load-bearing: markers otherwise persist and +the daemon deliberately enqueues at most one resume per marker. + +Delete with **literal paths only** - resolve the owner directory and the +dispatch name first, then write them out in full: + +```bash +rm -f .codex-dispatches/local/code-researcher-1756340000-4242-1.{prompt,sh,log,md,done,otel.json} +``` + +Never `rm` a path built from a shell variable or a glob under one +(`rm -f "$dir/$name".*`): Claude Code's critical-path check prompts on that +form even in bypass mode, and the prompt halts an unattended run. + +Launch every dispatch fully detached from the harness, from the repo root. The +owner directory is `.codex-dispatches/$ORCHESTRA_DISPATCH_OWNER` when the daemon +sets that variable to the Linear session UUID, and `.codex-dispatches/local` +otherwise. Prepare it once per worktree: + +```bash +own="${ORCHESTRA_DISPATCH_OWNER:-local}"; dir=".codex-dispatches/$own" +mkdir -p "$dir" +exclude="$(git rev-parse --git-path info/exclude)" +grep -qxF '/.codex-dispatches/' "$exclude" 2>/dev/null || printf '/.codex-dispatches/\n' >> "$exclude" +``` + +For each launch choose +`=--$$-`, where the caller sequence is unique among +concurrent launches. Write the prompt to `.prompt` with a quoted heredoc, +then write this launcher as `.sh` (substitute the concrete paths and +arguments while writing it): + +```bash +#!/usr/bin/env bash +perl -e 'alarm shift; exec @ARGV or die "exec failed: $!"' \ + codex exec -m gpt-5.6-sol -c model_reasoning_effort="" --yolo \ + [--ephemeral] --skip-git-repo-check -C \ + -o /.md "$(cat /.prompt)" /.done.tmp && \ + mv /.done.tmp /.done +``` + +Use a 900-second `` for `--ephemeral` roles and 2700 for the implementer. +Redirect stdin as shown because Codex can hang on an open idle pipe. Detach the +launcher itself with Perl's portable `setsid` (macOS has no `setsid` binary): + +```bash +nohup perl -MPOSIX -e 'POSIX::setsid(); exec @ARGV or die "exec failed: $!"' \ + bash /.sh > /.log 2>&1 & disown +``` + +For an implementer fix round, use the same launcher and marker write, replacing +its command with the following so session context survives: + +```bash +perl -e 'alarm shift; exec @ARGV or die "exec failed: $!"' 2700 \ + codex exec resume --last --yolo -o /.md \ + "$(cat /.prompt)" /.done.tmp && \ + mv /.done.tmp /.done +``` + +A resume dispatch carries `--yolo` exactly like a fresh one - a resumed +session that loses it runs sandboxed and blocks the very tests the fix +round must run. `resume` takes no `-C`: it matches recorded sessions by +cwd, so launch it from the same repo root as the original dispatch. + +The marker convention is: `.md` is the final report, `.log` is +durable stdout/stderr including the `tokens used` summary, and `.done` +contains exactly the exit code. The `.done` file is written even for failures, +including watchdog exit 142. A tracked wait loop may poll only the marker for +in-turn pickup; its death at turn end is harmless because the detached Codex +process survives and turn-start pickup covers recovery. + +Parallel dispatches (e.g. several code-researchers, or a reviewer alongside a +Claude sub-agent) are launched together. A dual-lane review that does not issue +the detached launches together serializes the lanes and doubles wall-clock. + +**Success criteria**: `.done` exists, contains 0, and the sibling `.md` exists +and is non-empty. Exit 142 is the watchdog's SIGALRM reap signature: it is a +classified failure, not a success, and step 3 handles it. + +### 3. Return the report +Read the output file. Check the status line the format requires (reviewers: +`**Verdict:**` + `**Counts:**` with the Must Fix count - a reviewer report +that arrives tiered P0–P3 instead is a valid report, not a failed run: +P0/P1 ≡ Must Fix, P2 ≡ Should Fix, P3 ≡ Nice to Have; map the tiers, +synthesize the status line from the mapped counts yourself, and never +burn a retry or re-dispatch over format · implementer: +`**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` · +code-researcher: `**Bottom line:**` · investigator: `**Root cause:**` with a +confidence word · backend-verifier: `**Verdict:**` pass|fail). Capture the +token usage `codex exec` prints in its end-of-run summary from the dispatch's +sibling `.log` file (the line after `tokens used`); per-turn detail lives in +`~/.codex/sessions//rollout-*.jsonl` `token_count` events. `unknown` is +only legal after checking both. For a resumed session the printed figure is +**cumulative**: record the delta from the previous dispatch's figure as the +round's cost and the final figure as the role total. Return the +report verbatim to the caller, prefixed with one line: +`CODEX : · tokens ` - the Overseer sums +these per role into the wrap-up's run record. + +Exit 142 (a SIGALRM watchdog reap) classifies the dispatch as a hung run. Retry +a hung, errored, timed-out, or status-line-missing run once: make a fresh +dispatch for an ephemeral role, or use `resume --last` for the implementer so +its session context survives. A retry that is also reaped never gets a third +Codex dispatch - a workload that wedged twice stays wedged: reviewer, +researcher, and verifier work routes to a Claude sub-agent dispatch instead; +the implementer has no Claude counterpart, so a twice-reaped implementer +returns the error plus whatever output exists to the caller. Otherwise return +the error plus whatever output exists after the single retry. A report of `listen EPERM` (the sandbox denied loopback +binds) is a completed run, not a failure: accept the edits and run the blocked +check at the Overseer, or hand it to the next verifier dispatch, instead of +re-dispatching. + +**Success criteria**: caller received a well-formed report (or the error +after one retry). diff --git a/claude/skills/cold-read/SKILL.md b/claude/skills/cold-read/SKILL.md index b543f09..7fa7cc0 100644 --- a/claude/skills/cold-read/SKILL.md +++ b/claude/skills/cold-read/SKILL.md @@ -1,6 +1,6 @@ --- name: cold-read -description: Give a fresh agent something to walk through with zero context - a PR body, a landing page, a document, a process, instructions, code. It reports what's broken, confusing, or contradictory. A fresh perspective on something before it ships - especially useful on a PR you think is finished, or any user-facing artifact. Always dispatch as a fresh sub-agent with no conversation history - the zero context is the point. +description: "Inspect an artifact with a fresh reader when the user requests a cold read or a workflow explicitly calls for one." --- # Cold Read diff --git a/claude/skills/create-brief/SKILL.md b/claude/skills/create-brief/SKILL.md index 55f8362..ecc52c8 100644 --- a/claude/skills/create-brief/SKILL.md +++ b/claude/skills/create-brief/SKILL.md @@ -1,6 +1,6 @@ --- name: create-brief -description: Captures discussed work as a work item ready for /do - a feature brief for changes and additions (single-outcome or multi-phase), a bug brief for defects (running the investigator first if the root cause isn't established). Use when a conversation has converged on buildable work that has no work item yet - whether the user asks to capture it or convergence makes capture the obvious next step. Do not invoke for a passing idea, an unconverged thread, or work that already has an item. +description: "Capture agreed work as a feature or bug brief for /do. Use when buildable work needs a new work item." argument-hint: "[title or one-line summary]" --- diff --git a/claude/skills/discussion/SKILL.md b/claude/skills/discussion/SKILL.md index e8d02ab..12ec220 100644 --- a/claude/skills/discussion/SKILL.md +++ b/claude/skills/discussion/SKILL.md @@ -1,6 +1,6 @@ --- name: discussion -description: Interactive back-and-forth to clarify, understand, or figure something out - an idea, an approach, a tradeoff, or a suspected bug. Use when the user wants to think out loud or explore before committing to anything - e.g. "let's discuss X", "help me understand Y", "why is Z happening", "what should we do about W". Produces clarity plus a dated decision log, not deliverables; work items are created afterward with /create-brief. +description: "Explore an unresolved idea, tradeoff, or suspected bug when the user wants discussion before committing to work." argument-hint: "[idea, question, or topic]" --- diff --git a/claude/skills/do/SKILL.md b/claude/skills/do/SKILL.md index 4a8d683..63d32fa 100644 --- a/claude/skills/do/SKILL.md +++ b/claude/skills/do/SKILL.md @@ -1,6 +1,6 @@ --- name: do -description: Run the full autonomous pipeline against a work item - plan, implement, verify, PR, post-PR review + QA, wrap-up. Takes a work-item reference (issue #/URL in whatever tracker the repo's AGENTS.md configures) or a local ./tmp//brief.html produced by /create-brief. +description: "Execute a ready work item through implementation, review, QA, and a PR for human review." argument-hint: "[work-item # / URL, or path to ./tmp//brief.html]" disable-model-invocation: true --- @@ -26,700 +26,34 @@ every surface - backend/ops and frontend web/mobile alike. The Claude post-PR** (Step 5), never at the verify stage. web-researcher is a Claude sub-agent. -## Autonomy & safety (read first) - -This run is meant to finish unattended - started at night, reviewed in the -morning. These rules make that safe: - -- **A phase or step boundary is not a turn boundary, and neither is a - dispatch.** Chain straight into the next step while work is ready, and never - end a turn with work outstanding. Every dispatch - detached Codex `codex - exec` and Claude-lane Agent-tool sub-agents alike - is awaited inside the - turn that launched it: poll its completion marker until the report lands or - its deadline passes, then act on it. Codex dispatches still launch detached - (per the codex skill) so a lost harness process cannot orphan them, but - detaching is not licence to yield - **nothing resumes a turn that ends - itself.** If a turn dies for an external reason - budget ceiling, crash, - daemon restart - recovery comes from the run's durable state, not from a - scheduled wakeup: `plan-.md` and its `phase_complete` flag record where - you were, and the next turn picks up from there. Idle-waiting on a human - nudge is a pipeline bug. -- **A plain human message mid-run - "continue", "still running?", "does it - work?" - is genuine input, never a task notification.** Inspect the dispatch - markers and durable outputs, answer from them, and resume immediately. -- **Action tiers decide what you may do alone. When unsure which tier an - action is, it is red - always err toward caution.** - - **Green - do it unattended:** code, tests, docs, new files, and - **staging** schema changes that are *both* additive/nullable *and* - reversible (a new nullable column or new table you could drop with no data - loss) - anything self-undoing. Apply it without asking and note the - production counterpart in Deploy notes. - - **Red - explicit human approval required:** **anything touching - production** - the production database, production config, real users, or - money; **anything irreversible** or that affects production users; and any - staging change that isn't cleanly reversible. Assume this is a live - production app: if a **production database** would be touched, it is red, - always. Execute a red action only after the human explicitly approves the - exact action, target, and scope in the active session. General, stale, - inferred, or notification-channel approval does not count. Without - approval, capture the exact change under `./tmp//`, record it in Deploy - notes, notify the human, and continue independent work. -- **A red action that blocks *downstream work in this run* is a review gate.** - Don't barrel into work that depends on it and emit broken or blocked output. - Notify with full context, stop that dependent line of work, and carry on with - anything independent - the human reviews and clears it at the machine. A red - action that blocks *only itself* is captured, noted, and the run continues - past it. -- **Only fully stop for a red gate that blocks *everything*** (access the run - can't proceed without, a genuine ambiguity in intent). Notify, say exactly - what you need, and wait. - -**Notify** per `.references/notify.md` - **one-way**: inform the human, -don't wait for a phone reply. Target comes from repo config (default a per-operator -`ntfy.sh/-dcouple-orchestra`; silent no-op if unreachable), and -after each send you tell the user in chat where it went. Messages are plain -text - the app doesn't render Markdown - titled `[item] stage - why` so -concurrent runs stay legible. Fire at: a red gate (deferred or blocking), a -hard stop, and run completion - never on green-tier progress. - -## Step 0: Preflight, then Load - -**Preflight first - surface everything human-actionable up front,** so the -run doesn't discover a missing dependency at hour six and stall. Check what -this run will need end-to-end and, in **one** message to the human, list what -is missing or expired with the exact command to fix each: `gh` auth; the -artifact-provider tool the repo's `AGENTS.md` names (e.g. a Notion CLI) if -artifacts get published; the notify target (`.references/notify.md`); -and the credentials/tooling verification will need (DB, cloud, test-mode API -keys, a browser for computer-use); and the **harness permission modes** - -the orchestrator session runs under `claude --dangerously-skip-permissions` -and every codex dispatch uses `--yolo`; approvals must never gate an -unattended run. Not in bypass mode → preflight note with the exact relaunch -command. Prove each credential with a token-producing probe -(`gcloud auth print-access-token`, plus the application-default variant -when terraform is in play), never a listing, and note each token's expiry -horizon against the run's expected length. -Resolvable from config or a quick check → -just confirm it silently. If nothing is missing, say so in one line and -proceed. A missing green-tier dependency is a preflight note, not a -stop - the human clears it while you work; only a dependency the run truly -cannot start without stops Step 0. - -Make the worktree's environment ready - installing dependencies and running -the development app inside its own worktree are the pipeline's deliberate, -logged actions, whatever the platform. In every workspace that declares -dependencies, run the project's own idempotent install (a no-op when the -tree is already current), detecting the toolchain from the repo's -`AGENTS.md`/manifests rather than assuming one - always in the toolchain's -reproducible mode (locked versions) and with lifecycle scripts suppressed -where the toolchain supports it. Compare installed linter/build-tool -versions against the versions the repo's `AGENTS.md`/CI pin - a mismatch is -a preflight note, and the pinned install can start in the background before -implement. A missing toolchain or failed install -emits an **environment note** in the preflight message or run chat naming -the workspace and tool; continue per the action tiers and carry a -persistent note into the wrap-up/PR notes. If a later stage fails on an -artifact a suppressed install step would have produced, emit the same named -environment note for that package - never continue silently or improvise a -workaround. - -Then **Load:** - -Get everything about the work item into `./tmp//` before starting. -This mirrors the publish rule: the project's `AGENTS.md` `Work-item -tracking` section says where work items and their artifacts live - fetch -them per its instructions; with no instructions, the item exists only -locally, so expect it in `./tmp//`. The item is `brief.html`; its machine -state is the YAML in its `