development-loop.md

type	ProcessSpec
summary	Defines the default delivery loop for this repository.
id	SPEC-0001
spec-status	active
last-updated	2026-05-19
aliases	SPEC-0001

Development loop

Summary

This repo uses a spec-driven loop so intent, execution, rationale, and future-capacity improvements stay durable and queryable. Every substantial change moves through spec -> effort -> plan -> execute -> alignment-audit -> backport -> compound.

Goals

• keep specs normative, not retrospective
• make active work auditable through effort notes
• require deviations, backports, and compounding follow-ups instead of silent drift

Non-Goals

• replacing issue trackers or source control
• forcing every reference note into a rigid subtype
• defining architecture, runtimes, or product behavior in this spec

Requirements

Must

• Development work follows this ordered loop:
  1. Skills: load the relevant bundled skills from docs/specs/process/agent-skills.md.
  2. Spec: update the active spec in place by default, or create a new spec only when no authoritative note exists yet.
  3. Effort: create one effort note named YYYY-MM-DD-HH-MM-<slug>.md under docs/efforts/ via effort-new, allocate an EFF-XXXX id, freeze the spec set, and freeze the selected story / acceptance-criterion nodes with wikilinks to their durable block-id targets.
  4. Plan: derive a decision-complete implementation plan via plan, recorded in the effort.
  5. Execute: implement against the plan via implement and run the required checks.
  6. Audit: run alignment-audit with relevant audit types defined in audits.md.
  7. Backport: use backport to update specs, reference docs, code docs, or skills for any divergence that changed authoritative truth, and record deviations.
  8. Compound: use compound to turn repeated friction, missing evidence, missing access, validation gaps, and review patterns into durable future-capacity work.
  9. Repeat.
• Superseding a spec is exceptional. When a spec is marked superseded, it must point at an explicit successor; normal workflow should keep the active spec authoritative and evolve it in place.
• Every effort note includes: id, name, created-at, plan-approved-by, status, summary, scope, frozen spec set, frozen story/criterion scope, coverage checklist, plan, original intended delivery, actual delivered, execution notes, deviations, compounding follow-ups, closure checklist, and status narrative.
• Execution does not begin until all of the following are true:
  • The effort note exists under docs/efforts/.
  • The Plan section is decision-complete (tasks, tests, and acceptance criteria).
  • The plan has explicit user approval recorded in the effort header, with plan-approved-by set to the approver's actual human name rather than a placeholder, handle, or shorthand.
• Implementation phases belong only in Plan prose. They are a planning convention, not typed ontology workflow state.
• Specs that drive execution include a User Stories section with story-level ids, statuses, and typed acceptance criteria.
• Story readiness, satisfaction, acceptance-criterion structure, and carry-forward rules are defined in story-lifecycle.md and apply to every story selected into an effort.
• Effort creation includes an explicit story-selection step. The default is not "all stories"; decide which ready stories the effort will execute now.
• When a spec uses story increment numbers, effort creation may use those numbers to narrow the candidate slice, but the effort still freezes the exact selected story and criterion nodes as wikilinks in Stories In Scope (Frozen).
• Behavior-changing structural refactors require a spec delta before implementation edits begin.
• If execution is interrupted or aborted, the default next step is back to Plan.
• Execution resumes after an interruption only when the user explicitly confirms resume and scope has not changed.
• Deviations discovered during execution or audit are recorded in the effort note.
• Deviations is never left as None when scope, sequence, acceptance criteria, or implementation approach changed.
• Backport updates are applied before closing an effort when behavior diverges from specs.
• Human decisions, agent surprises, and new conclusions discovered during work are logged in the effort's Execution Notes with UTC DateTime entries and event-kind tags such as [decision], [surprise], or [learning].
• Decisions and surprises stay in the effort unless they change durable spec truth, reusable reference guidance, code documentation, or skill behavior. Backport only that changed truth; do not create a separate decision artifact for routine effort rationale.
• Behavior-changing structural refactor efforts must include a spec-alignment audit before closure.
• An effort is not truthfully complete until the closure checklist confirms implementation, audit, backport, and compounding work are done.
• The closure phases (alignment-audit, backport, compound) MUST be invoked as separate sub-agents — each one loading the named skill in its own context and receiving the effort note path plus the inputs the skill expects. The implement-phase agent does not run them inline, does not collapse them into a single pass, and does not flip status: complete before the closure checklist is true. See effort-lifecycle.md "Closure procedure" for the exact handoff and inputs.
• During implementation and backport, agents should keep effort-local rationale in Execution Notes; create or update specs, reference notes, code docs, or skills only when the rationale changes reusable or authoritative guidance.
• When linking implementation rationale, agents should prefer the smallest durable ontology node that explains the constraint, such as an embedded user story, typed acceptance criterion, or rationale block with a block-ID wikilink, rather than linking only to the parent spec.
• During compound, agents should record repeated friction and missing agent capabilities in Compounding Follow-ups rather than leaving them in chat, PR comments, or private prompts.

Should

• Audits include at least spec-alignment and one domain-specific type from audits.md.
• Efforts are scoped so they can be completed and audited in a single focused pass.
• rzm agent validate runs before handoff for every effort, scoped to checks relevant to the change.

May

• Add additional audit types when risk or scope warrants it.

Phase Exit Criteria

• Spec: target behavior is documented and no unresolved MUST-level ambiguity blocks implementation.
• Effort: effort note exists with frozen spec set, frozen story scope, and populated coverage checklist.
• Plan: implementation approach is decision-complete with tests and acceptance criteria.
• Execute: code changes are complete and required quality checks have run.
• Audit: required audit types have run and findings are recorded.
• Backport: specs/docs are updated for divergence and deviations are recorded in the effort note.
• Compound: repeated friction has been triaged and durable follow-ups or small fixes are recorded.

Open Questions

• none currently; plan-approved-by is the only required approval metadata