Skip to main content

Workflow principles

These principles govern A2C execution in every A2C-based repository.

Docs first​

Work begins with documentation and architecture rather than code generation. Typical early artifacts:

  • README and docs structure
  • Architecture overview
  • ADR README and index
  • Templates, rules, and prompts
  • Commit plan

Architecture as contract​

Architecture docs, specs, and accepted ADRs are governing artifacts. AI must use them as the contract — not as loose inspiration.

When a spec and implementation disagree, stop and reconcile before proceeding.

Small bounded steps​

Implementation happens in small, cohesive, reviewable, commit-sized slices. A2C explicitly rejects big-bang generation.

Each batch has a defined scope and a stop condition. Do not continue into the next batch without review.

Repository-native workflow memory​

The repository stores rules, templates, prompts, plans, profiles, docs structure, and workflow metadata. This makes the process:

  • reusable across projects
  • consistent for AI across sessions
  • inspectable in Git history

AI as force multiplier​

AI performs scaffolding, documentation plumbing, repetitive configuration, refactoring assistance, and CI wiring inside explicit constraints.

The developer keeps control of architecture, quality bar, and review.

For the full mental model — architecture that works without AI, contracts before models, designer vs user roles — see ai-principles.md.

ADR-first architectural history​

Significant decisions are captured in ADRs and committed with the dedicated adr(<category>): ... type. One ADR per commit. See ../adr/README.md.

When ASRs are used, treat them as first-class contracts with the same change discipline; see asr-adr-pr-governance.md.

Traceability​

Commit plans connect batches to architecture and ADRs. Git history should tell a clear story: docs → decisions → scaffolding → implementation.

Changelog (CHANGELOG.md) provides curated release-level history — what changed in each version — separate from commit logs and ADR rationale. See changelog-policy.md.