Architecture guide

Design a feature from zero

Start with the first caller and an outcome they can observe. Use Mind to join discovery, design and review in one conversation.

$codex-council:codex-mind · mid
Design a recoverable job queue from scratch. Ask me about choices that change the contract. Return the first working slice and its failure test.

Work through open decisions

Describe one real use. The lead looks up repository facts and asks the independent questions that affect the design.
Specialists send questions from their own lens. The lead merges duplicates, gives a recommendation with its trade-off, and asks follow-ups only after prerequisites are settled.
Delegate reversible details explicitly. The brief carries settled choices into one design with boundaries, contracts, recovery, and an acceptance example.
Council challenges the proposal. With a build verdict and your authorization, Hyper implements the approved slices and executes the checks.

Choose an effort

simpleOne opinion for a reversible choice.
midThree members and one reviewer for everyday architecture.
ultraSix members and five reviewers for deeper scrutiny.

These are ordinary Council counts. Hard risks require full coverage. Forge always has five creators. Skill review has three lenses. Frontend review adds Leonardo and browser evidence from Bob. Read the estimate before dispatch.

Add --details to estimate for a component breakdown.

Worked scenarios

Design exercises with a decision and a reproducible check.

Recoverable job queue

A worker stops after committing a side effect. Who issues the idempotency key, and when may it expire?

Once the caller owns the key, agree the retry window. Design the submission contract, durable job state and worker acknowledgement.

Acceptance test · Kill the worker between commit and acknowledgement. Submit the same key again and count committed results.

Tenant-aware access

A support user works across two accounts. Which tenant grants authority, and who can revoke it?

Decide the ownership boundary first. Then specify the authorization check at read time and how permission caches expire.

Acceptance test · Open a session, revoke the grant, and attempt the same read from both accounts. Check the agreed revocation deadline and audit record.

Versioned event ingestion

An offline device sends old events after an upgrade. Which versions must the receiver accept?

Agree retention before choosing a decoder. Define version detection, ordering and a quarantine path for unknown payloads.

Acceptance test · Replay an old event, its duplicate and an unknown version. Inspect persisted records, quarantine and offsets after restart.

Keep a local decision brief

For a long interview, create a new file, adapt its questions, then add an answer or a delegated assumption to each settled decision. Run interview again to see which questions are ready.

python3 scripts/codex_council.py interview --start "Recover a job" > brief.json
python3 scripts/codex_council.py interview --input brief.json
python3 scripts/codex_council.py estimate --topic "Job queue" --effort mid --brief brief.json
python3 scripts/codex_council.py init --topic "Job queue" --effort mid --brief brief.json --confirm-estimate

Research behind the method

These studies informed design choices. The local evidence lab reports separately what was exercised in this plugin.

This October preprint tests requirement understanding separately from implementation on 100 greenfield tasks. We use separate readback and acceptance checks. SWE-Clar · 2026

The authors select questions by the uncertainty they resolve in tool calls. We adapt that principle by asking which answer would change the design. Structured Uncertainty · ACL 2026

Coordination costs varied across sequential and decomposable tasks. We use bounded panels and reserve specialist time for independent questions. Scaling Agent Systems · 2026 revision

A human elicitation study compared interviews, focus groups and surveys for explainability. Broad surveys produced redundant needs. The lead consolidates questions before asking. Obaidi et al. · RE 2025

The workshop method refines stakeholder concerns into prioritized scenarios. We turn the most important scenario into a test for the first working slice. Quality Attribute Workshops · SEI