aidoc-flow-framework

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# aidoc-flow-framework

**AI-First, Specification-Driven Development for the agent era.**

A framework whose artifacts are written **for AI agents to implement, deploy, and
maintain** — not for humans to read. It turns a human's project seed into a
structured, traceable, machine-verifiable chain that an agent can build from
without drifting, and keeps that chain alive as reality changes.

> A human never reads the whole chain. A human asks an agent to summarize, review,
> or change it. The documents are the machine-readable contract; the natural-language
> view is generated on demand.

---

## Why this exists

AI writes code fast. The problem isn't writing — it's that **AI-generated code
without proper specification, plans, and traceability is unmaintainable**. An agent
will happily produce nice-looking, plausible, *partially-wrong* code and silently
drop a requirement it never noticed. And the next agent — fresh context, months
later, modifying code it didn't write — reconstructs intent *from the code itself*,
which is exactly how silent breakage compounds into a black box.

This framework is the **anti-drift harness**. It gives every agent — the one that
builds and every one that later maintains — the authoritative intent, the addressable
contract, and the test oracle that proves nothing broke. Structured intent +
traceability + test oracles is not bureaucracy in the agent era; it's the only thing
that makes AI-generated code maintainable instead of disposable.

---

## The model: seed → chain → adaptive loop

The framework does not invent the business and does not claim to know the world. It
sits between a **human seed** and the **agents** that realize and maintain it.

```
   HUMAN (owner / architect)                  FRAMEWORK + AI                       WORLD
   ─────────────────────────                  ──────────────                       ─────
   vision · strategy · real-world   ──seed──▶  BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN  ◀─signal─ spikes
   constraints (pre-framework docs)           (traceable, verifiable, buildable)            prod telemetry
                                                        │                                    canary
                                              PO review at EARS/BDD                          │
                                              (right definition of done)                     │
                                                        │                                    │
                                                   CHG + lifecycle  ◀──────reality delta─────┘
                                              MVP → PROD → New MVP → Updated PROD
```

1. **Human seeds the intent.** The business owner or architect creates the initial
   project documents (vision, strategy, constraints, prior-art corpus). This is where
   ground truth and real-world assumptions enter — the framework never originates them.
2. **The chain transforms the seed** into eight cumulative layers, each addressable and
   cross-linked, ending in code-ready implementation plans.
3. **The product owner (human or AI-as-PO) validates the oracle early** — at the EARS/BDD
   layer, *before* any architecture is committed (see "Why BDD before ADR").
4. **The world produces the truth signal** — a sandbox spike, a canary, production
   telemetry. No document can manufacture this; someone has to go observe reality.
5. **CHG ingests reality as bounded, traceable deltas.** The chain is not frozen; it is a
   living `MVP → PROD → New MVP → Updated PROD` loop.

---

## The layers

| Layer | Artifact | Answers |
|------|----------|---------|
| L1 | **BRD** — Business Requirements | Why are we building this? (C4 Context) |
| L2 | **PRD** — Product Requirements | What product capability? (C4 Container) |
| L3 | **EARS** — Formal Requirements | Precisely, what must it do? |
| L4 | **BDD** — Acceptance Scenarios | What does "correct" look like? (the **oracle**) |
| L5 | **ADR** — Architecture Decisions | How, and why this way? |
| L6 | **SPEC** — Component Contracts | The buildable interface (C4 Component) |
| L7 | **TDD** — Test Definitions | The tests that prove it, test-first |
| L8 | **IPLAN** — Implementation Plan | The exact, resumable build manifest for an agent |

Overlays: **CHG** governance gates (adaptive change control with approval + re-gate),
and markdown **development/work plans** (`plans/*.md`) — the human-and-agent-readable
plan-of-record for a single change.

Document numbers are **per-layer counters with no cross-layer alignment**; an upstream
item may fan out to many downstream documents. Lineage is carried by `@`-tags and
content-hash element IDs, never by matching numbers.

---

## What makes agents safe here

- **Content-hash element IDs + cumulative `@`-tags** — every requirement, decision, and
  test has a stable address; a future agent cannot quietly reinterpret "this exact
  requirement."
- **Coverage checks** — every requirement/scenario must map to a component (or be
  explicitly deferred); silently-missing functionality is detectable, not discovered in
  production.
- **Test-first manifests (TDD/IPLAN)** — the oracle exists before the code; an agent
  cannot "finish" a component without the test that defines done.
- **Deterministic gates** — resolution, ID format, required tags, and coverage are
  mechanically checkable; "the chain verifies clean" is a fact, not an opinion.
- **Maker-checker for change (CHG)** — reality-driven changes propagate with a computable
  blast radius and a re-validation gate, not by code archaeology.

---

## Division of labor (who owns what)

| Owner | Responsibility |
|---|---|
| **Human (owner/architect)** | The **seed**: intent + real-world assumptions. The quality of the seed. |
| **Framework + AI** | Faithful **transformation** of the seed into a traceable, verifiable, buildable chain. |
| **Product owner (human or AI-PO)** | Validate the **oracle** at EARS/BDD: *is this the right definition of done?* |
| **The world** | Produce the **truth signal** (spike, canary, prod) — the only source of "is this assumption true?" |
| **CHG + lifecycle** | **Adapt** the chain to reality as bounded, traceable deltas. |

---

## Why BDD before ADR

Acceptance scenarios (L4) are authored **before** architecture decisions (L5) on
purpose. Two reasons:

1. **Review at the right altitude.** Plain Given/When/Then is exactly what a product
   owner — human or an AI acting as PO — can validate, with no implementation noise, and
   *before* a cent is spent on architecture.
2. **The oracle is pinned independently of the implementer.** Deciding "what correct
   means" before "how we'll build it" stops the common failure where the architecture
   quietly redefines the acceptance criteria to whatever's convenient. That's anti-drift
   at the *requirements* level, complementing the anti-drift at the code level.

---

## The correctness boundary

The framework guarantees **internal consistency, completeness, and adaptability**. It
does **not** guarantee the spec is true about the world — and it doesn't try to.

- An agent will faithfully implement a flawless spec of a **false assumption**. So the
  human's irreducible job narrows to two things only a human (or the world) can own:
  **is this assumption true**, and **is this the right definition of done**.
- Garbage-in still gives garbage-out — but **legible, reviewable, correctable** garbage
  that a PO catches at BDD and CHG fixes with a computable blast radius, instead of
  silent garbage compounding inside code.
- The framework's promise is to make a wrong idea's **consequences visible and its
  corrections cheap** — not to make a wrong idea right.

What used to look like "a gap inside the framework" is actually its **edge**: the seed
(human) and the act of observing reality (world). Naming those as outside the
framework's contract completes the model rather than exposing a weakness.

---

## Using it

1. **Seed it.** Provide vision/strategy/constraints/prior-art as the pre-framework input.
2. **Author the current cycle's set in full; stub the rest.** A cycle = a BRD *set*
   (platform BRD + its feature BRDs). Don't over-author distant features that depreciate
   before their cycle.
3. **Traverse the chain** BRD → … → IPLAN, assigning content-hash IDs and cumulative tags;
   keep references resolving and coverage complete.
4. **Gate it** (CHG): deterministic floor (IDs, references, required tags, coverage) +
   no unresolved P0/P1; the numeric readiness score is advisory.
5. **Validate the oracle** at EARS/BDD with a PO before building.
6. **Build test-first** from the IPLANs; sessions hand off via the IPLAN session-handoff.
7. **Observe reality**, then **adapt** via CHG — the chain is a control loop, not a
   blueprint.

---

## Issues this framework solves

The framework targets a specific cluster of failures that show up when AI agents — not
humans — write, ship, and maintain code. Grouped by what they actually break:

### 1. The generated code is plausible but wrong or incomplete

- **Silent requirement loss** — an agent produces a clean-looking module that quietly
  omits a requirement nobody noticed was missing. → **Coverage checks** force every EARS
  requirement and BDD scenario to map to a component or be explicitly deferred. On
  BeeLocal this literally surfaced two whole missing components (compliance/resilience,
  recipient management) that read as "done" until measured.
- **No oracle, so "looks right" passes for "is right"** — agents are confident and
  wrong. → **Test-first (BDD→TDD→IPLAN)**: the acceptance test exists before the code,
  so an agent can't "finish" a component without satisfying the definition of done.

### 2. Drift across agents, sessions, and time

- **The second-agent problem** — a fresh-context agent months later modifies code it
  didn't write and reconstructs intent from the code, which is how silent breakage
  compounds. → **Content-hash IDs + cumulative `@`-tags** give every requirement a stable
  address it can't quietly reinterpret; **IPLAN session-handoff** preserves state across
  stateless agent calls so a resumed session doesn't regenerate or contradict prior work.
- **"Why is this here / what breaks if I change it?"** — untraceable code. → **End-to-end
  traceability** (component → ADR → BDD → EARS → PRD → BRD) makes the change blast-radius
  computable instead of guessed.

### 3. Building the wrong thing

- **Architecture silently redefines "done"** to whatever's convenient to implement. →
  **BDD-before-ADR** pins the oracle, reviewable by a product owner (human or AI-PO),
  before a cent goes into architecture — "what correct means" decided independently of
  "how we'll build it."
- **No safe checkpoint before spending** — teams build, then discover it's wrong. →
  **Deterministic gates** (structural floor + no unresolved P0/P1) give a mechanical
  "ready to proceed" at each layer boundary.

### 4. Verification is opinion, not fact

- **"Is it complete/consistent?" is a judgment call.** → The framework makes it
  mechanical: 0 unresolved references, 0 duplicate IDs, 100% coverage are **computed, not
  asserted**. "The chain verifies clean" is a fact.

### 5. Ambiguous human→agent instructions

- **Vague specs make agents guess.** → **Formal EARS** (WHEN…SHALL…WITHIN), typed **SPEC
  contracts**, and exact **IPLAN file manifests** give an agent unambiguous, addressable
  instructions it can't misread.

### 6. Documentation that rots / scope sprawl

- **Frozen docs that drift from reality and start lying.** → **CHG governance** + the
  MVP→PROD→New MVP lifecycle absorb reality as bounded, traceable, re-gated deltas — a
  living chain, not a blueprint.
- **Over-engineering distant features that depreciate before they're built.** → **"Author
  the current cycle's BRD set in full; stub the rest"** — bounded authoring tied to cycles.

### 7. Unmaintainable AI-built systems

- **The overarching one:** AI code without spec/plan/traceability becomes a black box. →
  The chain is the **durable intent + test oracle every future agent inherits**, so
  maintenance is a bounded, traceable delta instead of archaeology — and onboarding
  (human or agent) becomes "query the chain," not "reverse-engineer the code."

**What it deliberately does *not* solve** — and shouldn't be expected to: it doesn't
verify that your assumptions are *true about the world* (e.g., "Privy supports custodial
USDC on Solana"), and it can't make a bad **seed** good. Those stay with the human
(quality of the seed) and the world (the spike/canary/prod signal that tells you an
assumption is false). The framework's job is to make a wrong idea's consequences
**visible and cheap to correct** — caught at BDD, fixed via CHG — not to make a wrong
idea right.

**In one line:** it converts *"AI writes code fast but you can't trust, trace, or maintain
it"* into *"AI writes code that is provably complete against an explicit oracle, fully
traceable, and safely modifiable by the next agent."*

---

## Field note: why the volume isn't overhead

If the consumer is an agent, then the volume and the rigid structure aren't overhead —
they're the entire mechanism. A human skims; an agent needs an unambiguous, addressable,
machine-checkable contract or it drifts. So "too much ceremony for a person to read" is
a **category error**: nobody reads it, they query it.

The core claim is the strongest argument for the whole approach: the documents are the
**anti-drift harness**. The exact failure mode named here — an agent producing
nice-looking, plausible, partially-wrong code and silently dropping a requirement — is
precisely what the framework's machinery is built to prevent. On a real build it worked:
the coverage check found genuine components that didn't exist yet (would've been silently
missing); the reference resolver caught dangling links the moment they appeared; the
test-first manifests mean an agent can't "finish" a component without the oracle that
proves it. Content-hash IDs + cumulative tags give every future agent a stable address
for "this exact requirement" so it can't quietly reinterpret it. That's not documentation
theater — that's the leash.

The place this pays off most is the one easiest to under-weight: **maintenance by a
different agent, months later, in fresh context.** Writing the first version is the cheap
part. The expensive, dangerous part is the second agent modifying code it never wrote —
and without the spec + traceability + tests, that agent reconstructs intent from the code,
which is exactly how silent breakage compounds. The framework hands every future agent the
authoritative intent and the test that proves it didn't break the invariant. For an
AI-maintained system over years, that's the difference between maintainable and a
slowly-rotting black box.

**Verdict:** for an AI-driven build-deploy-maintain loop, this is closer to **necessary**
than merely worth it. The "is it worth the weight" question was a human-era question.

---

*This README captures the framework's design intent for the AI-agent era: a
transformation-and-maintenance layer between a human's seed and the agents that build
and keep a system alive — with its responsibilities drawn honestly.*

---

## Platforms

The framework spec is engine-agnostic; two independent platforms implement it, each
versioned independently. Both pass the same shared conformance suite.

| Platform | Engine | Version |
|----------|--------|---------|
| **Hermes AI** | MCP server | `hermes/v0.11.1` (`platforms/hermes/`) |
| **Claude Code plugin** | Native Claude Code (skills / agents / commands) | `claude-code-plugin/v0.23.4` (`platforms/claude-code-plugin/`) |

*Versions are the per-package `VERSION`-file values (namespaced as they would be
tagged); the git tag itself may not be cut yet — see `docs/TAGGING.md`.*

See [`docs/PARITY.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/docs/PARITY.md) for the capability comparison and a
"which platform should I use?" guide.

### Install the Claude Code plugin

This repo doubles as a plugin marketplace (`.claude-plugin/marketplace.json`).
From Claude Code:

```
/plugin marketplace add vladm3105/aidoc-flow-framework
/plugin install aidoc-flow@aidoc-flow-framework
```

## Status

The migration is complete (cutover shipped as `v1.0.0`); the project is now in
**post-cutover development** (latest project release `v1.1.0`), tracking
framework spec `0.37.2`. The Claude Code plugin is a **pre-1.0 preview** — APIs
and surfaces may change before 1.0. Platform release versions are in the
[Platforms](#platforms) table above.

Post-v1.0 development — delivered and planned — is tracked in
[`ROADMAP.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/ROADMAP.md); per-release detail is in
[`CHANGELOG.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/CHANGELOG.md). Development lands on the Claude Code plugin
first, with Hermes follow-on batches per
[`plans/HERMES-BACKLOG.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/plans/HERMES-BACKLOG.md).

## Contributing

Enable the pre-commit hooks before committing:

```sh
pip install pre-commit && pre-commit install
```

See `.pre-commit-config.yaml` for the hook set and [`SECURITY.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/SECURITY.md)
for the vulnerability-reporting policy.

## Documentation

- `ROADMAP.md` — delivery plan and post-v1.0 work (migration complete at `v1.0.0`).
- `CHANGELOG.md` — project-level changelog.
- `SECURITY.md` — security policy and vulnerability reporting.
- `docs/REPO_STRUCTURE.md` — repository layout (as-built).
- `docs/PROJECT.md` — versioning, branching, milestones, conformance, change management.
- `docs/TAGGING.md` — git-tag policy (release + bookmark tags).
- `docs/PARITY.md` — Hermes ↔ plugin capability comparison.
- `framework/README.md` — the engine-agnostic SDD specification.
- [`framework/docs/AIDOC.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/docs/AIDOC.md) — the `.aidoc/` provenance tier (third committed documentation tier).
- [`tests/ACCEPTANCE.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/tests/ACCEPTANCE.md) — pre-deployment acceptance-test methodology (driver, log layout, schema, `--promote`, phase definitions, partial-execution flags, CI integration).
- [`tests/README.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/tests/README.md) — tiered test-suite navigation hub.
- [`plans/ACCEPTANCE-SUITE-HISTORY.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/plans/ACCEPTANCE-SUITE-HISTORY.md) — per-PR implementation timeline + design evolution + lessons learned for the acceptance suite.
- [`docs/STARTUP_HANDOFF.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/docs/STARTUP_HANDOFF.md) — historical session brief from the Phase-3/4 migration period.

## Pre-migration history

This project was migrated from the pre-migration `ucx_framework` (v0.20.4)
into the multi-platform structure above. The **pristine pre-migration project**
is preserved on the protected, read-only branch
**`legacy-ucx-v3.2-read-only`** (`git checkout legacy-ucx-v3.2-read-only`).
The full migration record — per-task plans, audits, verify records, and the
decision log — lives under `plans/`.

aidoc-flow-framework

AI-First, Specification-Driven Development for the agent era.

A framework whose artifacts are written for AI agents to implement, deploy, and maintain — not for humans to read. It turns a human's project seed into a structured, traceable, machine-verifiable chain that an agent can build from without drifting, and keeps that chain alive as reality changes.

A human never reads the whole chain. A human asks an agent to summarize, review, or change it. The documents are the machine-readable contract; the natural-language view is generated on demand.

Why this exists

AI writes code fast. The problem isn't writing — it's that AI-generated code without proper specification, plans, and traceability is unmaintainable. An agent will happily produce nice-looking, plausible, partially-wrong code and silently drop a requirement it never noticed. And the next agent — fresh context, months later, modifying code it didn't write — reconstructs intent from the code itself, which is exactly how silent breakage compounds into a black box.

This framework is the anti-drift harness. It gives every agent — the one that builds and every one that later maintains — the authoritative intent, the addressable contract, and the test oracle that proves nothing broke. Structured intent + traceability + test oracles is not bureaucracy in the agent era; it's the only thing that makes AI-generated code maintainable instead of disposable.

The model: seed → chain → adaptive loop

The framework does not invent the business and does not claim to know the world. It sits between a human seed and the agents that realize and maintain it.

   HUMAN (owner / architect)                  FRAMEWORK + AI                       WORLD
   ─────────────────────────                  ──────────────                       ─────
   vision · strategy · real-world   ──seed──▶  BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN  ◀─signal─ spikes
   constraints (pre-framework docs)           (traceable, verifiable, buildable)            prod telemetry
                                                        │                                    canary
                                              PO review at EARS/BDD                          │
                                              (right definition of done)                     │
                                                        │                                    │
                                                   CHG + lifecycle  ◀──────reality delta─────┘
                                              MVP → PROD → New MVP → Updated PROD

Human seeds the intent. The business owner or architect creates the initial project documents (vision, strategy, constraints, prior-art corpus). This is where ground truth and real-world assumptions enter — the framework never originates them.
The chain transforms the seed into eight cumulative layers, each addressable and cross-linked, ending in code-ready implementation plans.
The product owner (human or AI-as-PO) validates the oracle early — at the EARS/BDD layer, before any architecture is committed (see "Why BDD before ADR").
The world produces the truth signal — a sandbox spike, a canary, production telemetry. No document can manufacture this; someone has to go observe reality.
CHG ingests reality as bounded, traceable deltas. The chain is not frozen; it is a living MVP → PROD → New MVP → Updated PROD loop.

The layers

Layer	Artifact	Answers
L1	BRD — Business Requirements	Why are we building this? (C4 Context)
L2	PRD — Product Requirements	What product capability? (C4 Container)
L3	EARS — Formal Requirements	Precisely, what must it do?
L4	BDD — Acceptance Scenarios	What does "correct" look like? (the oracle)
L5	ADR — Architecture Decisions	How, and why this way?
L6	SPEC — Component Contracts	The buildable interface (C4 Component)
L7	TDD — Test Definitions	The tests that prove it, test-first
L8	IPLAN — Implementation Plan	The exact, resumable build manifest for an agent

Overlays: CHG governance gates (adaptive change control with approval + re-gate), and markdown development/work plans (plans/*.md) — the human-and-agent-readable plan-of-record for a single change.

Document numbers are per-layer counters with no cross-layer alignment; an upstream item may fan out to many downstream documents. Lineage is carried by @-tags and content-hash element IDs, never by matching numbers.

What makes agents safe here

Content-hash element IDs + cumulative @-tags — every requirement, decision, and test has a stable address; a future agent cannot quietly reinterpret "this exact requirement."
Coverage checks — every requirement/scenario must map to a component (or be explicitly deferred); silently-missing functionality is detectable, not discovered in production.
Test-first manifests (TDD/IPLAN) — the oracle exists before the code; an agent cannot "finish" a component without the test that defines done.
Deterministic gates — resolution, ID format, required tags, and coverage are mechanically checkable; "the chain verifies clean" is a fact, not an opinion.
Maker-checker for change (CHG) — reality-driven changes propagate with a computable blast radius and a re-validation gate, not by code archaeology.

Division of labor (who owns what)

Owner	Responsibility
Human (owner/architect)	The seed: intent + real-world assumptions. The quality of the seed.
Framework + AI	Faithful transformation of the seed into a traceable, verifiable, buildable chain.
Product owner (human or AI-PO)	Validate the oracle at EARS/BDD: is this the right definition of done?
The world	Produce the truth signal (spike, canary, prod) — the only source of "is this assumption true?"
CHG + lifecycle	Adapt the chain to reality as bounded, traceable deltas.

Why BDD before ADR

Acceptance scenarios (L4) are authored before architecture decisions (L5) on purpose. Two reasons:

Review at the right altitude. Plain Given/When/Then is exactly what a product owner — human or an AI acting as PO — can validate, with no implementation noise, and before a cent is spent on architecture.
The oracle is pinned independently of the implementer. Deciding "what correct means" before "how we'll build it" stops the common failure where the architecture quietly redefines the acceptance criteria to whatever's convenient. That's anti-drift at the requirements level, complementing the anti-drift at the code level.

The correctness boundary

The framework guarantees internal consistency, completeness, and adaptability. It does not guarantee the spec is true about the world — and it doesn't try to.

An agent will faithfully implement a flawless spec of a false assumption. So the human's irreducible job narrows to two things only a human (or the world) can own: is this assumption true, and is this the right definition of done.
Garbage-in still gives garbage-out — but legible, reviewable, correctable garbage that a PO catches at BDD and CHG fixes with a computable blast radius, instead of silent garbage compounding inside code.
The framework's promise is to make a wrong idea's consequences visible and its corrections cheap — not to make a wrong idea right.

What used to look like "a gap inside the framework" is actually its edge: the seed (human) and the act of observing reality (world). Naming those as outside the framework's contract completes the model rather than exposing a weakness.

Using it

Seed it. Provide vision/strategy/constraints/prior-art as the pre-framework input.
Author the current cycle's set in full; stub the rest. A cycle = a BRD set (platform BRD + its feature BRDs). Don't over-author distant features that depreciate before their cycle.
Traverse the chain BRD → … → IPLAN, assigning content-hash IDs and cumulative tags; keep references resolving and coverage complete.
Gate it (CHG): deterministic floor (IDs, references, required tags, coverage) + no unresolved P0/P1; the numeric readiness score is advisory.
Validate the oracle at EARS/BDD with a PO before building.
Build test-first from the IPLANs; sessions hand off via the IPLAN session-handoff.
Observe reality, then adapt via CHG — the chain is a control loop, not a blueprint.

Issues this framework solves

The framework targets a specific cluster of failures that show up when AI agents — not humans — write, ship, and maintain code. Grouped by what they actually break:

1. The generated code is plausible but wrong or incomplete

Silent requirement loss — an agent produces a clean-looking module that quietly omits a requirement nobody noticed was missing. → Coverage checks force every EARS requirement and BDD scenario to map to a component or be explicitly deferred. On BeeLocal this literally surfaced two whole missing components (compliance/resilience, recipient management) that read as "done" until measured.
No oracle, so "looks right" passes for "is right" — agents are confident and wrong. → Test-first (BDD→TDD→IPLAN): the acceptance test exists before the code, so an agent can't "finish" a component without satisfying the definition of done.

2. Drift across agents, sessions, and time

The second-agent problem — a fresh-context agent months later modifies code it didn't write and reconstructs intent from the code, which is how silent breakage compounds. → Content-hash IDs + cumulative @-tags give every requirement a stable address it can't quietly reinterpret; IPLAN session-handoff preserves state across stateless agent calls so a resumed session doesn't regenerate or contradict prior work.
"Why is this here / what breaks if I change it?" — untraceable code. → End-to-end traceability (component → ADR → BDD → EARS → PRD → BRD) makes the change blast-radius computable instead of guessed.

3. Building the wrong thing

Architecture silently redefines "done" to whatever's convenient to implement. → BDD-before-ADR pins the oracle, reviewable by a product owner (human or AI-PO), before a cent goes into architecture — "what correct means" decided independently of "how we'll build it."
No safe checkpoint before spending — teams build, then discover it's wrong. → Deterministic gates (structural floor + no unresolved P0/P1) give a mechanical "ready to proceed" at each layer boundary.

4. Verification is opinion, not fact

"Is it complete/consistent?" is a judgment call. → The framework makes it mechanical: 0 unresolved references, 0 duplicate IDs, 100% coverage are computed, not asserted. "The chain verifies clean" is a fact.

5. Ambiguous human→agent instructions

Vague specs make agents guess. → Formal EARS (WHEN…SHALL…WITHIN), typed SPEC contracts, and exact IPLAN file manifests give an agent unambiguous, addressable instructions it can't misread.

6. Documentation that rots / scope sprawl

Frozen docs that drift from reality and start lying. → CHG governance + the MVP→PROD→New MVP lifecycle absorb reality as bounded, traceable, re-gated deltas — a living chain, not a blueprint.
Over-engineering distant features that depreciate before they're built. → "Author the current cycle's BRD set in full; stub the rest" — bounded authoring tied to cycles.

7. Unmaintainable AI-built systems

The overarching one: AI code without spec/plan/traceability becomes a black box. → The chain is the durable intent + test oracle every future agent inherits, so maintenance is a bounded, traceable delta instead of archaeology — and onboarding (human or agent) becomes "query the chain," not "reverse-engineer the code."

What it deliberately does not solve — and shouldn't be expected to: it doesn't verify that your assumptions are true about the world (e.g., "Privy supports custodial USDC on Solana"), and it can't make a bad seed good. Those stay with the human (quality of the seed) and the world (the spike/canary/prod signal that tells you an assumption is false). The framework's job is to make a wrong idea's consequences visible and cheap to correct — caught at BDD, fixed via CHG — not to make a wrong idea right.

In one line: it converts "AI writes code fast but you can't trust, trace, or maintain it" into "AI writes code that is provably complete against an explicit oracle, fully traceable, and safely modifiable by the next agent."

Field note: why the volume isn't overhead

If the consumer is an agent, then the volume and the rigid structure aren't overhead — they're the entire mechanism. A human skims; an agent needs an unambiguous, addressable, machine-checkable contract or it drifts. So "too much ceremony for a person to read" is a category error: nobody reads it, they query it.

The core claim is the strongest argument for the whole approach: the documents are the anti-drift harness. The exact failure mode named here — an agent producing nice-looking, plausible, partially-wrong code and silently dropping a requirement — is precisely what the framework's machinery is built to prevent. On a real build it worked: the coverage check found genuine components that didn't exist yet (would've been silently missing); the reference resolver caught dangling links the moment they appeared; the test-first manifests mean an agent can't "finish" a component without the oracle that proves it. Content-hash IDs + cumulative tags give every future agent a stable address for "this exact requirement" so it can't quietly reinterpret it. That's not documentation theater — that's the leash.

The place this pays off most is the one easiest to under-weight: maintenance by a different agent, months later, in fresh context. Writing the first version is the cheap part. The expensive, dangerous part is the second agent modifying code it never wrote — and without the spec + traceability + tests, that agent reconstructs intent from the code, which is exactly how silent breakage compounds. The framework hands every future agent the authoritative intent and the test that proves it didn't break the invariant. For an AI-maintained system over years, that's the difference between maintainable and a slowly-rotting black box.

Verdict: for an AI-driven build-deploy-maintain loop, this is closer to necessary than merely worth it. The "is it worth the weight" question was a human-era question.

This README captures the framework's design intent for the AI-agent era: a transformation-and-maintenance layer between a human's seed and the agents that build and keep a system alive — with its responsibilities drawn honestly.

Platforms

The framework spec is engine-agnostic; two independent platforms implement it, each versioned independently. Both pass the same shared conformance suite.

Platform	Engine	Version
Hermes AI	MCP server	`hermes/v0.11.1` (`platforms/hermes/`)
Claude Code plugin	Native Claude Code (skills / agents / commands)	`claude-code-plugin/v0.23.4` (`platforms/claude-code-plugin/`)

Versions are the per-package VERSION-file values (namespaced as they would be tagged); the git tag itself may not be cut yet — see docs/TAGGING.md.

See docs/PARITY.md for the capability comparison and a "which platform should I use?" guide.

Install the Claude Code plugin

This repo doubles as a plugin marketplace (.claude-plugin/marketplace.json). From Claude Code:

/plugin marketplace add vladm3105/aidoc-flow-framework
/plugin install aidoc-flow@aidoc-flow-framework

Status

The migration is complete (cutover shipped as v1.0.0); the project is now in post-cutover development (latest project release v1.1.0), tracking framework spec 0.37.2. The Claude Code plugin is a pre-1.0 preview — APIs and surfaces may change before 1.0. Platform release versions are in the Platforms table above.

Post-v1.0 development — delivered and planned — is tracked in ROADMAP.md; per-release detail is in CHANGELOG.md. Development lands on the Claude Code plugin first, with Hermes follow-on batches per plans/HERMES-BACKLOG.md.

Contributing

Enable the pre-commit hooks before committing:

pip install pre-commit && pre-commit install

See .pre-commit-config.yaml for the hook set and SECURITY.md for the vulnerability-reporting policy.

Documentation

ROADMAP.md — delivery plan and post-v1.0 work (migration complete at v1.0.0).
CHANGELOG.md — project-level changelog.
SECURITY.md — security policy and vulnerability reporting.
docs/REPO_STRUCTURE.md — repository layout (as-built).
docs/PROJECT.md — versioning, branching, milestones, conformance, change management.
docs/TAGGING.md — git-tag policy (release + bookmark tags).
docs/PARITY.md — Hermes ↔ plugin capability comparison.
framework/README.md — the engine-agnostic SDD specification.
framework/docs/AIDOC.md — the .aidoc/ provenance tier (third committed documentation tier).
tests/ACCEPTANCE.md — pre-deployment acceptance-test methodology (driver, log layout, schema, --promote, phase definitions, partial-execution flags, CI integration).
tests/README.md — tiered test-suite navigation hub.
plans/ACCEPTANCE-SUITE-HISTORY.md — per-PR implementation timeline + design evolution + lessons learned for the acceptance suite.
docs/STARTUP_HANDOFF.md — historical session brief from the Phase-3/4 migration period.

Pre-migration history

This project was migrated from the pre-migration ucx_framework (v0.20.4) into the multi-platform structure above. The pristine pre-migration project is preserved on the protected, read-only branch legacy-ucx-v3.2-read-only (git checkout legacy-ucx-v3.2-read-only). The full migration record — per-task plans, audits, verify records, and the decision log — lives under plans/.