isanna
isanna builder · a tech lead walkthrough

One spec. Every ceremony.
Every artifact.

Follow one small backend change from the sentence a tech lead starts with to a synced, host-verified record. At each step: who acts, what gets written, where a human decides, what can fail, and what the next agent is allowed to trust.

  • one concrete spec
  • nine ceremonies
  • canonical YAML first
  • RED → GREEN → VERIFY
  • agent claim ≠ host verdict
9ceremonies from specify to archive
43complete sample files, with no excerpts
7independent verify verdicts
2provenance registers in The Record
The sample

Make webhook delivery idempotent.

The feature is deliberately small enough to inspect end to end, but real enough to expose the whole method: retries, a race condition, a failure path, a data boundary, and a proof that must come from execution rather than prose.

idempotent-webhook-deliverysample spec
Tech lead asks

“If the provider retries the same event, fulfill it once and acknowledge every safe retry.”

Non-negotiables

No duplicate side effect, no raw payload in logs, no rewrite of historical rows.

Observable success

Two concurrent requests with one event id create one fulfillment; both calls terminate safely.

specifyingspecifieddesignedreviewedplannedimplementingimplementedverifyingsyncingsyncedarchived

The straight path is shown above. Builder also has honest branch states: an early independent pass can produce spec-reviewed, an implementation review can produce adversarially-reviewed, and a failed final verification producesverified_with_tasks and loops back to implementation.

The chain of custody

Requirement → design → task → evidence.

Stable ids make the work traceable. A requirement cannot quietly disappear between the conversation and the code; validation rejects orphaned or dangling links.

intent.yamlSS-1

Success signal: one side effect per provider event id.

requirements.yamlR1 / AC-R1-1

Two concurrent retries produce one fulfillment.

design.yamlD1

Atomic claim on a unique provider event id.

tasks.yamlT1

One RED-to-GREEN behavior slice.

evidence/task-T1.yamlE1-red / green / verify

Commands, exits, timestamps, and files written.

The complete run

What happens, step by step.

Phases 1–4 are authoring ceremonies with explicit human gates. Phases 5–6 consume locked task packets, execute autonomously, and return evidence. Sync reconciles the finished change with the system’s declared model before the run is complete.

/isanna-1-specify idempotent-webhook-delivery

Specify the outcome, including failure

Author + tech leadspecifying → specified
What happens

The author maps the affected capability in the system model, asks what must not regress, records unknowns instead of guessing, and writes shell-observable acceptance criteria. Repo rules from .builder/constitution.md and command defaults from .builder/setup-decisions.yaml constrain the work.

Human ceremony

The tech lead reviews scope and says Approve, Another pass, or Add more requirements. Nothing designs ahead of that decision.

intent.yamlsystem-model.yamlrequirements.yamlrequirements.mdspec.yamldecisions.yamlphase-log.yamlhandoff.yaml
requirements:
  - id: R1
    statement: WHEN two requests share one provider_event_id,
      the system SHALL create exactly one fulfillment.
    acceptance:
      - id: AC-R1-1
        observable_at: concurrent integration test
        oracle: { type: automated_test, expected: one fulfillment row }
        priority: must
/isanna-2-design idempotent-webhook-delivery

Allocate the responsibility

Design author + tech leadspecified → designed
What happens

The design places idempotency at the database write boundary: an atomic claim onprovider_event_id, a replay-safe response, and redacted diagnostics. It names the race, rollback, affected files, and the behavior each design item realizes.

Human ceremony

The tech lead checks ownership and tradeoffs, then answers Approve design or Another pass. A resolved choice is appended to decisions.yaml; an unresolved one cannot sneak into planning.

design.yamldesign.mddecisions.yamlspec.yamlphase-log.yamlhandoff.yaml
D1 · chosen boundaryLet the unique constraint arbitrate concurrency; do not rely on an in-process check-then-insert.
/isanna-3-review idempotent-webhook-delivery

Give the design to fresh eyes

Independent reviewerdesigned → reviewed
What happens

A fresh reviewer checks requirements, design, constitution, failure paths, tests, and unintended surface area. It does not author forward. Here it catches that a unique violation alone is insufficient unless the losing request reloads and returns the already-created outcome.

Human ceremony

Each finding is applied, skipped, or amended differently. Review provenance stays distinct from authorship, and a blocking constitution verdict stops the run.

review-log.yamlreview-log.mdconstitution-review.yamlconstitution-review.mddecisions.yamlspec.yamlphase-log.yamlhandoff.yaml
YELLOW · applied

Add an acceptance case for the concurrent loser returning the canonical fulfillment id.

/isanna-4-plan idempotent-webhook-delivery

Turn the design into runner-safe packets

Planner + tech leadreviewed → planned
What happens

The planner creates atomic tasks, dependencies, allowed files, done-when predicates, focused verify commands, and the SSOT change the finished spec will later reconcile. Each runs/task-T1.yamlpacket is the implementer’s exclusive interface; it must stand on its own.

Human ceremony

The tech lead reviews task boundaries and answers Approve tasks, Another pass, or Add tasks. Approval locks the packets that autonomous execution will receive.

tasks.yamltasks.mdtraceability.yamldependencies.yamlssot-delta.yamlruns/task-T1.yamlspec.yamlphase-log.yamlhandoff.yaml
  • G0 constitution
  • G1 no hidden human task
  • G2 decisions resolved
  • G3 verify lint
  • G4 real RED baseline
  • G5 one behavior per task
- id: T1
  title: Make webhook claim atomic
  tdd: { mode: required }
  requirement_ids: [R1]
  design_ids: [D1]
  acceptance_criteria: [AC-R1-1]
  allowed_change_files: [webhook.ts, webhook.test.ts]
  verify:
    - pnpm vitest webhook.test.ts --run
/isanna-5-implement idempotent-webhook-delivery

Execute one RED-to-GREEN slice at a time

Implementation runner + hostplanned → implementing → implemented
Runner discipline

The runner reads the approved packet, confirms dependencies, writes the failing concurrent-delivery test first, proves the expected failure, implements the smallest fix, then reruns the focused and project checks. It cannot broaden the allowed file set without a human-visible divergence.

Evidence discipline

Every attempted task records RED, GREEN, and final VERIFY with the command, exit code, timestamp, output tail, source, and files written. A passing test alone cannot prove it was ever capable of failing.

implementation-baseline.yamlevidence/task-T1.yamltraceability.yamlphase-log.yamlspec.yamlhandoff.yamlsource diff + tests
task_id: T1
entries:
  - step: red
    command: pnpm vitest webhook.test.ts --run
    exit_code: 1
    source: host
    timestamp: 2026-08-04T19:00:00Z
  - step: green
    command: pnpm vitest webhook.test.ts --run
    exit_code: 0
    source: host
  - step: verify
    command: pnpm test
    exit_code: 0
    source: host

A configured adversarial implementation review may move the spec throughadversarially-reviewed and back to implementing for bounded fixes before final verification.

/isanna-6-verify idempotent-webhook-delivery

Verify the final tree from the host outward

Independent verifier + hostimplemented → verifying → syncing
agent claimed

“The idempotency task is complete and the test suite passes.”

host verified

validate-spec.py exit 0 · focused test exit 0 · project suite exit 0 · final diff in scope

Host checks run before reviewer analysis. The verifier then issues one PASS or FAIL for each category: requirement coverage, acceptance criteria, host-verify green, traceability, no regression, evidence completeness, and constitution/guardrails.

gate-evidence/evidence/task-T1.yamlconstitution-review.yamlreview-log.yamltraceability.yamlphase-log.yamlspec.yamlhandoff.yaml
Failure is a real state. A missing behavior or weak proof writes follow-up tasks, sets verified_with_tasks, and returns to implementation. It is never rounded up to PASS. A clean result advances the status to syncing.
isanna sync --spec idempotent-webhook-delivery

Reconcile the declared change with the living system model

Host sync enginesyncing → synced
What happens

Builder compares the spec’s ssot-delta.yaml with the host-observed changed paths through .builder/sync-adapter.yaml, then updates the curated behavioral truth in docs/system-behaviors.yaml only when the declared and observed tuples agree.

Divergence ceremony

An undeclared capability change does not auto-amend the model. Sync writes the divergence and requires a human resolution before rerun. A clean result is the terminal completion signal: status: synced.

sync-scope.yamlsync-result.yamlsync-report.yamlssot-delta.yamldocs/system-behaviors.yamlspec.yamlphase-log.yamlhandoff.yaml
result: syncedObserved change matches the declared behavior enrichment; the system model is current.
isanna record build

Render the read-only flight record

Static Record buildersynced · visible
The Planner

Shows the spec portfolio by status, dependency arrows, blocked work, critical path, and release completeness. Completion math uses host-observed coverage, not a task count typed into spec.yaml.

The Run Record

Reconstructs this run in exactly two provenance registers: what agents reported and what the host observed. It is static and read-only—there are no control verbs for an agent to press or a server to trust.

.builder/record/index.html.builder/record/<project>/roadmap.html.builder/record/<project>/spec/<spec>.html.builder/releases/<release>.yaml
/isanna-archive idempotent-webhook-delivery

Close the active workspace without erasing the proof

Maintainersynced → archived
What happens

Only a synced spec is eligible for the clean archive path. The canonical spec directory moves under the dated archive namespace with requirements, decisions, evidence, sync result, and handoffs intact.

Why it matters

Archiving is lifecycle housekeeping, not evidence deletion. A future maintainer can still recover what was requested, why a boundary was chosen, which commands actually ran, and what the host accepted.

.builder/specs/archive/<date>-idempotent-webhook-delivery/spec.yamlphase-log.yamlhandoff.yamlall prior evidence
The artifact ledger

Every file in this example has one reader and one reason.

Canonical YAML is working state; Markdown is a rendered human view when the repo uses dual artifact mode. The important distinction is not file format—it is who is allowed to claim what, and which host check consumes it.

Artifact familyCanonical filesWhat consumes them
Scopeintent.yaml · system-model.yaml · requirements.yamlDesign, review, coverage validation
Governancespec.yaml · decisions.yaml · constitution-review.yamlPhase state machine and human gates
Design & reviewdesign.yaml · review-log.yaml · handoff.yamlIndependent reviewer and next-phase session
Executiontasks.yaml · dependencies.yaml · runs/task-*.yamlDispatcher and locked runner session
Prooftraceability.yaml · evidence/task-*.yaml · gate-evidence/Host gate, verifier, The Run Record
Reconciliationssot-delta.yaml · sync-scope.yaml · sync-result.yaml · sync-report.yamlSync engine and living system model
Auditphase-log.yaml · workflow events · release manifestThe Planner, The Run Record, release status
Conditional artifacts stay explicit. A human intervention may addhuman-notes.yaml; legacy readmission may addsync-readmission-report.yaml; a divergence keeps its report. They are not silently presented as part of this clean sample run.
What the tech lead still owns

Builder automates motion, not accountability.

Scope and tradeoffs

Approve requirements, boundaries, exceptions, and any expansion beyond the agreed change.

Risky operations

Deploys, migrations, destructive actions, and production access remain separate authorization gates.

Evidence quality

A host-run weak test is still weak. Review the oracle, not just the green exit code.

Release judgment

Synced means the spec and living model agree; shipping the product remains an explicit human act.

The short version

The commands match the mental model.

one spec, end to end
/isanna-1-specify idempotent-webhook-delivery  # agree on what
/isanna-2-design idempotent-webhook-delivery   # allocate responsibility
/isanna-3-review idempotent-webhook-delivery   # fresh eyes
/isanna-4-plan idempotent-webhook-delivery     # lock task packets
/isanna-5-implement idempotent-webhook-delivery# RED → GREEN → VERIFY
/isanna-6-verify idempotent-webhook-delivery   # host-first verdicts
isanna sync --spec idempotent-webhook-delivery# reconcile the SSOT
isanna record build                              # render proof
/isanna-archive idempotent-webhook-delivery    # retain and close
The repository

Everything above is open source.

The walkthrough on this page is not a description of a product you have to take on trust — it is a description of code you can read. isanna Builder ships under Apache‑2.0: the prompts, the schemas, the deterministic validator, the dispatcher, the host gate, and the static Record generator, plus the test suite that holds all of it to the standard this page claims.

Apache-2.0permissive, with an express patent grant
0runtime dependencies — Python 3.11+ stdlib only
1,500+tests in the suite CI runs on every push
DCOsign off a commit; there is no CLA
install it into your own repo
curl -fsSL https://raw.githubusercontent.com/isanna-ai/builder/main/install.sh | bash -s -- --yes
/isanna-setup                      # it reads your repo and asks only what it cannot infer
/isanna-1-specify add dark mode      # and nothing is written until you approve
The gate runs on itself

Builder’s own CI runs make gate on Python 3.11, 3.12 and 3.13, then builds the public export and runs the whole suite inside it— because a suite that is green only on the maintainer’s machine proves nothing about the thing you clone.

Nothing publishes unscanned

A mechanical scrub gate blocks the release on any secret, personal path, or private hostname, and the public history is a single fresh root commit — so there is no old blob to leak. It is a required check, not a one-time read.

Fork it, rename it, ship it

Apache-2.0 grants you the code and a patent licence. The nameis the one thing held back: fork freely under a different name, so “isanna Builder” keeps meaning that the host really ran the tests.

Bring your own agent

The prompts install for VS Code + GitHub Copilot Chat, Claude Code, or Codex. The verdict comes from the host either way, so no agent gets to certify itself.

Read it before you trust it. The claim this whole page rests on is a narrow, checkable one: the host ran these commands against this work, observed these exit codes, and wrote this verdict. The code that does it is github.com/isanna-ai/builder.

isanna builder · canonical artifacts, independent review, host-observed evidence, and a read-only Record from intent through status: archived. Open source under Apache-2.0 · github.com/isanna-ai/builder