Architecture breakdown
What owns what?
UI, persistence and the CSV serializer have explicit responsibilities. A deployment choice remains an open question.
Read 01-architecture-breakdown.mdSee the Product in Action
codeArbiter is easier to understand when you can inspect what it produces. This tour follows a saved-search application from project-level planning to a focused CSV export. The documents are readable outside a chat, and the example tests can be rerun without a model account.
Evidence boundary: the specification and plan below were created and validated by the native artifact engine at the recorded source identity. They remain unapproved drafts. The Python RED and GREEN results are actual local fixture runs. The project blueprint, conversation, host comparison, review, and delivery story are explanatory examples, not captured host executions. Nothing on this page approves work, changes your repository, or proves an installed release.
From an idea to a project
Section titled “From an idea to a project”Before a greenfield project has source, its architecture, delivery phases, and backlog need separate explanations. Decompose creates three named Markdown documents and asks you to review all three. A roadmap does not become an executable feature plan simply because both contain tasks. The examples retain unresolved questions so you can see where your decision is still needed.
The project before the first feature
Phased build plan
What becomes useful first?
MVP saves searches. v1 exports them. Collaboration waits for a separate decision. Each phase has an observable finish.
Read 02-phased-build-plan.mdTask backlog
What work is next?
Priority, phase, owner, estimate and dependencies make the work discussable. Unresolved assignments remain visible.
Read 03-task-backlog.mdIllustrative Markdown documents for the same saved-search product. These were authored for explanation, not generated by a completed interview. They retain unresolved decisions deliberately; no approval, initialization, or automatic cross-document synchronization is claimed.
Use Plan a new project for the actual interview and its approval boundary. Existing source takes a different path: Understand an existing project.
From a requirement to an inspectable plan
Section titled “From a requirement to an inspectable plan”For a qualified new full-lane workflow, the specification owns stable acceptance-criterion IDs. The plan references them instead of creating a competing requirements list. Choose a criterion below to see that connection. Open either native document to inspect its complete readable view. The files need no JavaScript or network access when opened offline.
One goal. Connected records.
Export saved searches
Choose a criterion to follow its connection into the plan. These are real native-rendered drafts, not a live coding session.
Specification Draft
AC-001 · Preserve fields and order
Parsed CSV has name/query headers and one row for each record in input order.
- Given
- Two saved searches with plain text fields.
- When
- Export the collection.
- Observe
- Parsed CSV has name/query headers and one row for each record in input order.
Implementation plan Pending
T-001 · Preserve fields and order
References AC-001
export_csv.py + test_export_csv.py
python -m unittest -v test_export_csv.TestExport.test_rowsRequired check: TestExport.test_rows
Specification Draft
AC-002 · Round-trip special characters
Every field equals the original text after CSV round-trip.
- Given
- A record containing commas, quotes, newlines and Unicode.
- When
- Export and parse using the standard CSV reader.
- Observe
- Every field equals the original text after CSV round-trip.
Implementation plan Pending
T-002 · Round-trip special characters
References AC-002
export_csv.py + test_export_csv.py
python -m unittest -v test_export_csv.TestExport.test_round_tripRequired check: TestExport.test_round_trip
Specification Draft
AC-003 · Keep an empty result explicit
The function returns None, not a header-only export.
- Given
- The input collection is empty.
- When
- Request an export.
- Observe
- The function returns None, not a header-only export.
Implementation plan Pending
T-003 · Keep an empty result explicit
References AC-003
export_csv.py + test_export_csv.py
python -m unittest -v test_export_csv.TestExport.test_emptyRequired check: TestExport.test_empty
A structural pass means the document’s shape and references satisfy that validator. It does not establish that a requirement is true, that a person approved it, or that implementation passed its review. Review specifications and plans explains what you must inspect.
Follow the delivery story
Section titled “Follow the delivery story”Use the stage controls to move at your own pace. With JavaScript unavailable, every stage remains readable in document order. The fixture’s two failing baseline assertions and three passing final checks demonstrate one pure-function contract, not a complete application release.
Follow one bounded change
This is an explanatory walkthrough. Only the native draft generation and the Python test runs are captured execution; conversation, review and PR steps below are illustrative.
Start with the outcome
Export my saved-search names and queries as CSV, preserving their order and punctuation. Do not create an export when there are no searches.
This fixture covers a pure serialization function. It does not implement a download UI, authenticate a user, or write a file.
Make the ambiguous part testable
Handle special characters correctly.
After parsing the export with the CSV reader, names and queries containing commas, quotes, newlines and Unicode equal their original values.
This is an illustrative review correction, not a recorded human approval. Inspect AC-002 in the workbench and request revisions through your own workflow.
Observe actual local fixture tests
Incomplete baseline · exit 1
test_empty (test_export_csv.TestExport.test_empty) ... ok
test_round_trip (test_export_csv.TestExport.test_round_trip) ... FAIL
test_rows (test_export_csv.TestExport.test_rows) ... FAIL
======================================================================
FAIL: test_round_trip (test_export_csv.TestExport.test_round_trip)
----------------------------------------------------------------------
Traceback (most recent call last):
File "<fixture-root>/test_export_csv.py", line 19, in test_round_trip
self.assertEqual(self.parse([record]), [["name", "query"], [record["name"], record["query"]]])
~~~~~~~~~~^^^^^^^^^^
File "<fixture-root>/test_export_csv.py", line 10, in parse
self.assertIsInstance(result, str, "Non-empty searches must produce CSV text")
~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: None is not an instance of <class 'str'> : Non-empty searches must produce CSV text
======================================================================
FAIL: test_rows (test_export_csv.TestExport.test_rows)
----------------------------------------------------------------------
Traceback (most recent call last):
File "<fixture-root>/test_export_csv.py", line 14, in test_rows
rows = self.parse([{"name": "Open", "query": "state:open"}, {"name": "Mine", "query": "owner:me"}])
File "<fixture-root>/test_export_csv.py", line 10, in parse
self.assertIsInstance(result, str, "Non-empty searches must produce CSV text")
~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: None is not an instance of <class 'str'> : Non-empty searches must produce CSV text
----------------------------------------------------------------------
Ran 3 tests in 0.001s
FAILED (failures=2)
Completed serializer · exit 0
test_empty (test_export_csv.TestExport.test_empty) ... ok
test_round_trip (test_export_csv.TestExport.test_round_trip) ... ok
test_rows (test_export_csv.TestExport.test_rows) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OK
The empty-input check already passes in the baseline. The other two fail by assertion, not by import or fixture error. These results are not workflow acceptance receipts.
Read the captured test envelopeDo not turn an interruption into a new authority
In a real interrupted run, inspect the persisted task and working changes. An IN_PROGRESS task requires reconciliation before redispatch; REVIEW requires fresh evidence. The demonstration documents remain draft throughout this tour.
Follow the recovery guideCheck the complete delivery boundary
A real finish includes current requirements, relevant tests, review findings and their dispositions, the authorized commit, and a PR. Passing the three serializer tests is not enough to claim that whole chain.
No PR for a saved-search application was created by this fixture. Use the complete feature guide to perform those actions in your own repository.
Complete one featureThe complete feature walkthrough connects the same request, criteria, files, tests, human review and actual PR responsibilities. It distinguishes the small-lane case from the full-lane artifact example rather than forcing extra ceremony onto tiny changes.
Keep project state when you change hosts
Section titled “Keep project state when you change hosts”Command spelling and integrations differ by host. The shared repository records remain the place to inspect your project. These panels compare documented entry points; they are not screenshots of real sessions and do not qualify concurrent use or unsupported host versions.
One repository. Native entry points.
Claude Code
/ca:feature "export saved searches"Plugin commands and agents, trusted hooks, and an optional settings-wired statusline. Current source implements typed prompt, verification and review authority adapters here, with reviews run by the read-only ca:authority-reviewer agent; the exact installed release still needs qualified capability.
Shared project records: .codearbiter/specs/, .codearbiter/plans/, decisions, tasks and audit history.
Codex
$ca-feature "export saved searches"Codex-native skills, trusted hook handlers, and packaged role resources. Current source implements typed prompt, verification and review authority adapters here; the exact installed release still needs qualified capability.
Shared project records: .codearbiter/specs/, .codearbiter/plans/, decisions, tasks and audit history.
Pi
/ca-feature "export saved searches"Generated aliases, project trust, a rich footer, and child work mediated by the parent adapter. Typed prompt approval, verification and review authority are not supported; native HTML capability alone cannot clear those stops.
Shared project records: .codearbiter/specs/, .codearbiter/plans/, decisions, tasks and audit history.
Syntax comparison, not captured host output or proof of identical capabilities. Understood intent can route without typing a command. Installed support, trust and artifact capability still apply; this does not demonstrate simultaneous editing.
Check typed-artifact authority by host and supported platform differences before execution.
Understand a stop before retrying
Section titled “Understand a stop before retrying”A stopped task is not necessarily a broken installation. It may need an approval, a fresh read, review evidence, or reconciliation of an interrupted operation. The explanations below preserve those differences. An error is not permission to edit a hidden flag or manufacture a receipt.
Read the reason before retrying
These are explanations of task states and diagnostic codes, not live state from your repository.
AUTHORITY_UNVERIFIEDA required authority record is absent, stale or inspection-only after upgrade.
Next safe action: Use the applicable current host-owned approval or evidence boundary. Preserve old receipts; do not relabel them or manufacture a successful event. An unsupported host adapter remains a stop.
DRAFT_BINDINGA plan is still bound to a draft specification.
Next safe action: Return to the existing approval and plan-binding workflow. Do not edit a JSON flag to make the plan executable.
IN_PROGRESSAn interrupted task may have changed files without finishing its review.
Next safe action: Inspect those files and the recorded task state. Reconcile through the owning workflow before redispatch.
REVIEWImplementation is awaiting current review and evidence.
Next safe action: Collect the required fresh evidence and scope review. The label alone is not acceptance.
BLOCKEDA hard boundary or exhausted recovery strategy stopped this task.
Next safe action: Resolve its specific reason. Preserve the failed strategy and attempt record; continue only independent authorized work.
STALE_CURSORA contributing specification, plan or authority record changed after the read.
Next safe action: Read the current context again and reconsider the action. Never force the old cursor.
RECOVERY_REQUIREDA transaction needs inspection before its outcome is known.
Next safe action: Use the recorded operation ID and the recovery path. Do not replay the write with a new ID or remove its journal.
An accepted label also needs current bindings and evidence. Expanding these explanations never changes a task or grants permission.
Follow Resume and recover with the actual diagnostic and operation identity from your repository. For installation problems, begin with Troubleshooting.
Statusline themes
Section titled “Statusline themes”These captures use the real Claude Code statusline renderer with deterministic, mocked project and accounting inputs. Theme selection changes presentation, not enforcement or task state. The violet default is intentionally distinct from this site’s gate-gold treatment.
One renderer. Five palettes.
violet · default
╭── /example/saved-searches ───────────────────────────────────────────────────────────────────────╮
│ git example/saved-searches │ feature/export Example model │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ ● stage:1 · tasks:3 · q:1 · over:0 │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ Session │ ↓ 2.4K ↑ 400 │ $0.05 │ ctx ████████░░░░░░░░░░░░░░░░░░░░░░░░░ 23% │
│ Today │ ↓ 4.8K ↑ 800 │ $0.10 │ 46.0K / 200K ↯ compact ~69% age 1m │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ subagents 1 active ↓ 1.2K ↑ 340 │
│ ● Review export model:fixture ↓ 1.2K ↑ 340 8s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯blue
╭── /example/saved-searches ───────────────────────────────────────────────────────────────────────╮
│ git example/saved-searches │ feature/export Example model │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ ● stage:1 · tasks:3 · q:1 · over:0 │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ Session │ ↓ 2.4K ↑ 400 │ $0.05 │ ctx ████████░░░░░░░░░░░░░░░░░░░░░░░░░ 23% │
│ Today │ ↓ 4.8K ↑ 800 │ $0.10 │ 46.0K / 200K ↯ compact ~69% age 1m │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ subagents 1 active ↓ 1.2K ↑ 340 │
│ ● Review export model:fixture ↓ 1.2K ↑ 340 8s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯green
╭── /example/saved-searches ───────────────────────────────────────────────────────────────────────╮
│ git example/saved-searches │ feature/export Example model │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ ● stage:1 · tasks:3 · q:1 · over:0 │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ Session │ ↓ 2.4K ↑ 400 │ $0.05 │ ctx ████████░░░░░░░░░░░░░░░░░░░░░░░░░ 23% │
│ Today │ ↓ 4.8K ↑ 800 │ $0.10 │ 46.0K / 200K ↯ compact ~69% age 1m │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ subagents 1 active ↓ 1.2K ↑ 340 │
│ ● Review export model:fixture ↓ 1.2K ↑ 340 8s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯amber
╭── /example/saved-searches ───────────────────────────────────────────────────────────────────────╮
│ git example/saved-searches │ feature/export Example model │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ ● stage:1 · tasks:3 · q:1 · over:0 │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ Session │ ↓ 2.4K ↑ 400 │ $0.05 │ ctx ████████░░░░░░░░░░░░░░░░░░░░░░░░░ 23% │
│ Today │ ↓ 4.8K ↑ 800 │ $0.10 │ 46.0K / 200K ↯ compact ~69% age 1m │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ subagents 1 active ↓ 1.2K ↑ 340 │
│ ● Review export model:fixture ↓ 1.2K ↑ 340 8s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯mono
╭── /example/saved-searches ───────────────────────────────────────────────────────────────────────╮
│ git example/saved-searches │ feature/export Example model │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ ● stage:1 · tasks:3 · q:1 · over:0 │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ Session │ ↓ 2.4K ↑ 400 │ $0.05 │ ctx ████████░░░░░░░░░░░░░░░░░░░░░░░░░ 23% │
│ Today │ ↓ 4.8K ↑ 800 │ $0.10 │ 46.0K / 200K ↯ compact ~69% age 1m │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ subagents 1 active ↓ 1.2K ↑ 340 │
│ ● Review export model:fixture ↓ 1.2K ↑ 340 8s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯Actual renderer, mocked project and usage inputs. Not an installed host capture, live usage, or billing statement. The same text is rendered in each palette. Scroll the terminal horizontally on a narrow screen. The settings-wired statusline is for Claude Code; Pi's footer is a separate integration.
Install before customizingInspect capture dataChoose the next step
Section titled “Choose the next step”To evaluate the workflow, open the example documents and inspect their capture identities. To use codeArbiter, choose your host, install and trust the adapter, and prove a real block in a disposable repository. For guided, verifier-backed practice, use Arbiter Academy in its published order. The tour does not create an account, import progress, or store completion state.