Pneuma development workflow

This is the shared development procedure for Claude Code and Codex. Read root AGENTS.md, the relevant domain rules it routes to, and the acceptance criteria. Read docs/reference/project-guide.md for the affected contracts and their definition → instantiation → consumer chain. Paths here are repo-relative.

Engineering Judgment is the shared decision standard. Apply it through the questions below; keep its definitions in AGENTS.md rather than copying them into skills or harness adapters.

Choose the work shape

• A lookup or investigation uses explore.
• Architecture design or design review uses architect.
• A scoped implementation uses impl.
• Applying code-review findings uses amender.
• A new mode also uses the create-mode skill. A release uses bump.

These are role instructions, not a requirement to spawn agents. Work locally by default. Delegate only when the user or the active task's instructions request delegation and the harness provides it. Give each worker a bounded task, actual checkout path, baseline, acceptance criteria, and the relevant role file. Inherit the active harness's model choices; Claude model aliases are not Codex model IDs.

Development loop

1. Define the task. Identify the required behavior and invariants, affected contracts, state owners, test scope, and acceptance bar. Inspect existing implementations before choosing new abstractions or dependencies. Use existing user decisions; resolve routine implementation choices without asking again. Check the working tree and preserve unrelated edits. Isolate concurrent writers in separate worktrees.
2. Implement. Read the implementation role. For behavior changes, reproduce the defect or pin the new behavior, implement, and verify. Documentation, discovery metadata, and formatting do not need tests that merely repeat text. Keep the model sufficient for the actual task. When introducing a boundary, wrapper, or optimization, retain the reason and evidence for its cost.
3. Review. Inspect the actual diff against the requirements and domain rules. Trace each changed invariant through its consumers and boundary mappings. Check compatibility, ownership, lifecycle, and observable failure behavior. For external effects, check what retry, cancellation, recovery, or undo actually guarantees. Challenge layers and dependencies without a concrete role. For UI work, also inspect loading/empty/error states, interaction, design tokens, and browser evidence. Report concrete findings with location, impact, and severity; a missing review is not a passing review.
4. Verify. Run the relevant suite from .claude/rules/testing.md, plus bun run typecheck for code changes. Use bun run test for the routine repository gate and bun run test:release for releases; the selector enables relevant media/live tiers and falls back to full coverage when scope is unknown. bun run test:all --timeout 60000 remains the explicit full run. Inspect the contract boundaries: no React in manifests, no new hardcoded mode knowledge in server/CLI, and backend differences behind the backend seam. UI changes need a browser screenshot and interaction pass. Performance claims need a reproducible baseline and comparison. Save command results and evidence.
5. Amend. Read the amendment role, address each valid finding, and repeat the affected checks. Accept only when verification passes and review has no open blocker or major finding. Report unresolved issues honestly; never silently count a crashed worker, unrun check, or missing result as success.

Review and verification may run concurrently when independent. When delegation is unavailable or not requested, perform separate review and verification passes locally and describe them as self-review; do not claim an independent reviewer. After three rounds without convergence, reassess the cause and continue useful authorized work. Ask for a decision only when the remaining fork exceeds scope.

Harness adapters

• Claude Code with the Workflow tool: the existing .claude/workflows/dev-master-orchestrator.js automates delegated task waves. Read .claude/workflows/README.md for its arguments, worktree preconditions, and result schema. Its roster entries read the shared role files above.
• Codex, or Claude Code without that tool: execute the same loop using the tools actually exposed in this session. Do not try to run a workflow script in Bun/Node as if that supplied Claude's Workflow host, or assume .claude agent registrations are native Codex agents.
• Use the available planning, file-editing, browser, and question tools. Tool names such as TaskCreate, AskUserQuestion, or Read are capabilities, not prerequisites. A short written plan or direct question is a valid fallback.

Completion

Report what changed and why, the checks actually run and their outcomes, and material limitations. Provide log or screenshot paths when they carry evidence. Commit/push/release only within the user's authorized scope. Never create tags; CI owns release tags. Do not end with a request for confirmation already given.