Skip to main content

A2C AI principles — architecture first, AI as ergonomics

Short mental model for how A2C uses AI. Read this when you want the whole picture in one place; operational detail lives in principles.md, pathname:///a2c-assets/rules/05-ai-behavior.md, and ../architecture/overview.md.

Core idea: design A2C so it works fully without AI, then let AI make that design easier to follow — not different.

1. Architecture must stand on its own​

A2C should be fully understandable and operable without any AI.

Core behavior is defined by:

AI is layered on top of this system. It does not replace architecture or become a hidden source of truth.

In practice: you can run a2c commands, read specs, and follow commit plans from a terminal without opening an AI chat.

2. Contracts before models​

Every meaningful operation must have:

  • a data contract (files, schemas, event formats), and
  • a command contract (CLI, script, API shape).

AI agents work through those contracts, not around them:

  • no hidden business rules in prompts
  • no side effects that humans cannot express via the same contracts

In practice: task shape is in schemas/ and ../task-authoring.md; behavior is in a2c_core and exposed via a2c_cli — not improvised in chat.

3. AI as ergonomic layer, not logic layer​

AI's primary roles in A2C are:

RoleWhat it does
ExplainerWhat does this workflow do? Why this architecture?
GuideWhich command or prompt do I use for this scenario?
OrchestratorCall CLIs and scripts in the correct sequence per the contracts

Business logic, invariants, and lifecycle rules live in:

  • a2c_core
  • a2c_cli / a2c_tui
  • repo artifacts (ADRs, schemas, tests)

—not in the model's personality or hidden prompt text.

In practice: see ../architecture/package-boundaries.md — the CLI orchestrates; the core owns logic.

4. Workflow designers vs workflow users​

Workflow designers / architectsWorkflow users
Design contracts, ADRs, and CLIsOperate within those workflows
Decide where AI is appropriate and how it may actDo not need deep AI internals
Define prompts and guardrails that turn architecture into workflowsRely on AI to explain and drive the system while staying inside the architecture

Designers edit prompts/, rules/, and governing docs in a2c-workflow. Users follow commit plans, run commands, and review batches in their project repo.

In practice: ../cursor-integration.md describes how consuming projects mount method assets without forking policy silently.

5. Repeatability, cost, and scripts​

Repeatable workflows must be:

  • executable via scripts and CLI
  • testable without AI
  • documented in the repo — not only as chat history

Strong models are used for:

  • architecture reasoning
  • ADRs and prompt design
  • generating tools (scripts, utilities)

The tools then handle repetitive work cheaply. AI remains the high-leverage, low-frequency layer.

In practice: milestones in ../architecture/implementation-plan.md ship with tests and CLI surfaces; prompts bootstrap phases, not permanent runtime behavior.

6. AI must be answerable to the architecture​

When asked "why is this done this way?", AI should:

  • point back to ADRs, architecture docs, and contracts
  • explain the rationale in human terms
  • not invent incompatible behavior

If AI behavior and written architecture diverge, the architecture wins and the workflow must be adjusted.

In practice: accepted ADRs are immutable in substance (pathname:///a2c-assets/rules/08-adr-editing-evolution.md); meaning changes require a superseding ADR, not a silent prompt tweak.

How this relates to other docs​

You want…Read…
Full workflow principles (docs first, small steps, traceability)principles.md
What agents must do / must not dopathname:///a2c-assets/rules/05-ai-behavior.md
Product structure (a2c_core, CLI, extension)../architecture/overview.md
Cursor and prompt entry points../cursor-integration.md
Agent entry pointAGENTS.md at repository root (not synced to docs portal)