{
  "markdown": "# aidoc-flow-framework\n\n**AI-First, Specification-Driven Development for the agent era.**\n\nA framework whose artifacts are written **for AI agents to implement, deploy, and\nmaintain** — not for humans to read. It turns a human's project seed into a\nstructured, traceable, machine-verifiable chain that an agent can build from\nwithout drifting, and keeps that chain alive as reality changes.\n\n> A human never reads the whole chain. A human asks an agent to summarize, review,\n> or change it. The documents are the machine-readable contract; the natural-language\n> view is generated on demand.\n\n---\n\n## Why this exists\n\nAI writes code fast. The problem isn't writing — it's that **AI-generated code\nwithout proper specification, plans, and traceability is unmaintainable**. An agent\nwill happily produce nice-looking, plausible, *partially-wrong* code and silently\ndrop a requirement it never noticed. And the next agent — fresh context, months\nlater, modifying code it didn't write — reconstructs intent *from the code itself*,\nwhich is exactly how silent breakage compounds into a black box.\n\nThis framework is the **anti-drift harness**. It gives every agent — the one that\nbuilds and every one that later maintains — the authoritative intent, the addressable\ncontract, and the test oracle that proves nothing broke. Structured intent +\ntraceability + test oracles is not bureaucracy in the agent era; it's the only thing\nthat makes AI-generated code maintainable instead of disposable.\n\n---\n\n## The model: seed → chain → adaptive loop\n\nThe framework does not invent the business and does not claim to know the world. It\nsits between a **human seed** and the **agents** that realize and maintain it.\n\n```\n   HUMAN (owner / architect)                  FRAMEWORK + AI                       WORLD\n   ─────────────────────────                  ──────────────                       ─────\n   vision · strategy · real-world   ──seed──▶  BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN→CHG→EVAL  ◀─signal─ spikes\n   constraints (pre-framework docs)           (traceable, verifiable, buildable)            prod telemetry\n                                                        │                                    canary\n                                              PO review at EARS/BDD                          │\n                                              (right definition of done)                     │\n                                                        │                                    │\n                                                   CHG + lifecycle  ◀──────reality delta─────┘\n                                              MVP → PROD → New MVP → Updated PROD\n```\n\n1. **Human seeds the intent.** The business owner or architect creates the initial\n   project documents (vision, strategy, constraints, prior-art corpus). This is where\n   ground truth and real-world assumptions enter — the framework never originates them.\n2. **The chain transforms the seed** into ten cumulative layers (8 SDD + CHG + EVAL), each addressable and\n   cross-linked, ending in code-ready implementation plans.\n3. **The product owner (human or AI-as-PO) validates the oracle early** — at the EARS/BDD\n   layer, *before* any architecture is committed (see \"Why BDD before ADR\").\n4. **The world produces the truth signal** — a sandbox spike, a canary, production\n   telemetry. No document can manufacture this; someone has to go observe reality.\n5. **CHG ingests reality as bounded, traceable deltas.** The chain is not frozen; it is a\n   living `MVP → PROD → New MVP → Updated PROD` loop.\n\n---\n\n## The layers\n\n| Layer | Artifact | Answers |\n|------|----------|---------|\n| L1 | **BRD** — Business Requirements | Why are we building this? (C4 Context) |\n| L2 | **PRD** — Product Requirements | What product capability? (C4 Container) |\n| L3 | **EARS** — Formal Requirements | Precisely, what must it do? |\n| L4 | **BDD** — Acceptance Scenarios | What does \"correct\" look like? (the **oracle**) |\n| L5 | **ADR** — Architecture Decisions | How, and why this way? |\n| L6 | **SPEC** — Component Contracts | The buildable interface (C4 Component) |\n| L7 | **TDD** — Test Definitions | The tests that prove it, test-first |\n| L8 | **IPLAN** — Implementation Plan | The exact, resumable build manifest for an agent |\n| L9 | **CHG** — Change Management | Governance gates, adaptive change control with approval + re-gate |\n| L10 | **EVAL** — Evaluation & QA | Test strategy, coverage matrices, quality governance |\n\nOverlays: markdown **development/work plans** (`plans/*.md`) — the human-and-agent-readable\nplan-of-record for a single change.\n\n### Dual-Template Architecture (Standard vs. Workflow-Driven)\n\nEvery layer provides two authoring templates:\n\n- **Standard Templates** (`{TYPE}-TEMPLATE.yaml`): Declarative, structured specifications for standard features.\n- **Workflow Templates** (`{TYPE}-SWF-TEMPLATE.yaml`): Workflow-driven specifications employing the **Hybrid Envelope Architecture** (`subtype: workflow`) to house embedded [CNCF Serverless Workflow](https://serverlessworkflow.io/) v0.8 DSL state machines. These govern complex, long-running, multi-step, or compensatory lifecycle processes (e.g., strategic ROI gating, acceptance test runners, ADR decision matrices, saga rollbacks) while maintaining 100% structural schema compliance with `sdd_doc_lint`.\n\nDocument numbers are **per-layer counters with no cross-layer alignment**; an upstream\nitem may fan out to many downstream documents. Lineage is carried by `@`-tags and\ncontent-hash element IDs, never by matching numbers.\n\n---\n\n## What makes agents safe here\n\n- **Content-hash element IDs + cumulative `@`-tags** — every requirement, decision, and\n  test has a stable address; a future agent cannot quietly reinterpret \"this exact\n  requirement.\"\n- **Coverage checks** — every requirement/scenario must map to a component (or be\n  explicitly deferred); silently-missing functionality is detectable, not discovered in\n  production.\n- **Test-first manifests (TDD/IPLAN)** — the oracle exists before the code; an agent\n  cannot \"finish\" a component without the test that defines done.\n- **Deterministic gates** — resolution, ID format, required tags, and coverage are\n  mechanically checkable; \"the chain verifies clean\" is a fact, not an opinion.\n- **Maker-checker for change (CHG)** — reality-driven changes propagate with a computable\n  blast radius and a re-validation gate, not by code archaeology.\n\n---\n\n## Division of labor (who owns what)\n\n| Owner | Responsibility |\n|---|---|\n| **Human (owner/architect)** | The **seed**: intent + real-world assumptions. The quality of the seed. |\n| **Framework + AI** | Faithful **transformation** of the seed into a traceable, verifiable, buildable chain. |\n| **Product owner (human or AI-PO)** | Validate the **oracle** at EARS/BDD: *is this the right definition of done?* |\n| **The world** | Produce the **truth signal** (spike, canary, prod) — the only source of \"is this assumption true?\" |\n| **CHG + lifecycle** | **Adapt** the chain to reality as bounded, traceable deltas. |\n\n---\n\n## Why BDD before ADR\n\nAcceptance scenarios (L4) are authored **before** architecture decisions (L5) on\npurpose. Two reasons:\n\n1. **Review at the right altitude.** Plain Given/When/Then is exactly what a product\n   owner — human or an AI acting as PO — can validate, with no implementation noise, and\n   *before* a cent is spent on architecture.\n2. **The oracle is pinned independently of the implementer.** Deciding \"what correct\n   means\" before \"how we'll build it\" stops the common failure where the architecture\n   quietly redefines the acceptance criteria to whatever's convenient. That's anti-drift\n   at the *requirements* level, complementing the anti-drift at the code level.\n\n---\n\n## The correctness boundary\n\nThe framework guarantees **internal consistency, completeness, and adaptability**. It\ndoes **not** guarantee the spec is true about the world — and it doesn't try to.\n\n- An agent will faithfully implement a flawless spec of a **false assumption**. So the\n  human's irreducible job narrows to two things only a human (or the world) can own:\n  **is this assumption true**, and **is this the right definition of done**.\n- Garbage-in still gives garbage-out — but **legible, reviewable, correctable** garbage\n  that a PO catches at BDD and CHG fixes with a computable blast radius, instead of\n  silent garbage compounding inside code.\n- The framework's promise is to make a wrong idea's **consequences visible and its\n  corrections cheap** — not to make a wrong idea right.\n\nWhat used to look like \"a gap inside the framework\" is actually its **edge**: the seed\n(human) and the act of observing reality (world). Naming those as outside the\nframework's contract completes the model rather than exposing a weakness.\n\n---\n\n## Using it\n\n1. **Seed it.** Provide vision/strategy/constraints/prior-art as the pre-framework input.\n2. **Author the current cycle's set in full; stub the rest.** A cycle = a BRD *set*\n   (platform BRD + its feature BRDs). Don't over-author distant features that depreciate\n   before their cycle.\n3. **Traverse the chain** BRD → … → IPLAN, assigning content-hash IDs and cumulative tags;\n   keep references resolving and coverage complete.\n4. **Gate it** (CHG): deterministic floor (IDs, references, required tags, coverage) +\n   no unresolved P0/P1; the numeric readiness score is advisory.\n5. **Validate the oracle** at EARS/BDD with a PO before building.\n6. **Build test-first** from the IPLANs; sessions hand off via the IPLAN session-handoff.\n7. **Observe reality**, then **adapt** via CHG — the chain is a control loop, not a\n   blueprint. Which flow an adaptation takes — the 6 traversal-path graph lifecycles\n   (SDD2C greenfield, DIR2C direct request, SEED2C brownfield restart, CODE2C bugfix,\n   CODE2S reconciliation, or HOTFIX emergency) — is routed by\n   `framework/governance/CHG_REQUEST_FLOWS.md` (ratified 0.57.0, CHG-06; modernized in 0.88.0+).\n\n---\n\n## Issues this framework solves\n\nThe framework targets a specific cluster of failures that show up when AI agents — not\nhumans — write, ship, and maintain code. Grouped by what they actually break:\n\n### 1. The generated code is plausible but wrong or incomplete\n\n- **Silent requirement loss** — an agent produces a clean-looking module that quietly\n  omits a requirement nobody noticed was missing. → **Coverage checks** force every EARS\n  requirement and BDD scenario to map to a component or be explicitly deferred. In\n  practice this has surfaced whole missing components (compliance/resilience,\n  recipient management) that read as \"done\" until measured.\n- **No oracle, so \"looks right\" passes for \"is right\"** — agents are confident and\n  wrong. → **Test-first (BDD→TDD→IPLAN)**: the acceptance test exists before the code,\n  so an agent can't \"finish\" a component without satisfying the definition of done.\n\n### 2. Drift across agents, sessions, and time\n\n- **The second-agent problem** — a fresh-context agent months later modifies code it\n  didn't write and reconstructs intent from the code, which is how silent breakage\n  compounds. → **Content-hash IDs + cumulative `@`-tags** give every requirement a stable\n  address it can't quietly reinterpret; **IPLAN session-handoff** preserves state across\n  stateless agent calls so a resumed session doesn't regenerate or contradict prior work.\n- **\"Why is this here / what breaks if I change it?\"** — untraceable code. → **End-to-end\n  traceability** (component → ADR → BDD → EARS → PRD → BRD) makes the change blast-radius\n  computable instead of guessed.\n\n### 3. Building the wrong thing\n\n- **Architecture silently redefines \"done\"** to whatever's convenient to implement. →\n  **BDD-before-ADR** pins the oracle, reviewable by a product owner (human or AI-PO),\n  before a cent goes into architecture — \"what correct means\" decided independently of\n  \"how we'll build it.\"\n- **No safe checkpoint before spending** — teams build, then discover it's wrong. →\n  **Deterministic gates** (structural floor + no unresolved P0/P1) give a mechanical\n  \"ready to proceed\" at each layer boundary.\n\n### 4. Verification is opinion, not fact\n\n- **\"Is it complete/consistent?\" is a judgment call.** → The framework makes it\n  mechanical: 0 unresolved references, 0 duplicate IDs, 100% coverage are **computed, not\n  asserted**. \"The chain verifies clean\" is a fact.\n\n### 5. Ambiguous human→agent instructions\n\n- **Vague specs make agents guess.** → **Formal EARS** (WHEN…SHALL…WITHIN), typed **SPEC\n  contracts**, and exact **IPLAN file manifests** give an agent unambiguous, addressable\n  instructions it can't misread.\n\n### 6. Documentation that rots / scope sprawl\n\n- **Frozen docs that drift from reality and start lying.** → **CHG governance** + the\n  MVP→PROD→New MVP lifecycle absorb reality as bounded, traceable, re-gated deltas — a\n  living chain, not a blueprint.\n- **Over-engineering distant features that depreciate before they're built.** → **\"Author\n  the current cycle's BRD set in full; stub the rest\"** — bounded authoring tied to cycles.\n\n### 7. Unmaintainable AI-built systems\n\n- **The overarching one:** AI code without spec/plan/traceability becomes a black box. →\n  The chain is the **durable intent + test oracle every future agent inherits**, so\n  maintenance is a bounded, traceable delta instead of archaeology — and onboarding\n  (human or agent) becomes \"query the chain,\" not \"reverse-engineer the code.\"\n\n**What it deliberately does *not* solve** — and shouldn't be expected to: it doesn't\nverify that your assumptions are *true about the world* (e.g., \"the chosen provider\nsupports the required flow on the target platform\"), and it can't make a bad **seed** good. Those stay with the human\n(quality of the seed) and the world (the spike/canary/prod signal that tells you an\nassumption is false). The framework's job is to make a wrong idea's consequences\n**visible and cheap to correct** — caught at BDD, fixed via CHG — not to make a wrong\nidea right.\n\n**In one line:** it converts *\"AI writes code fast but you can't trust, trace, or maintain\nit\"* into *\"AI writes code that is provably complete against an explicit oracle, fully\ntraceable, and safely modifiable by the next agent.\"*\n\n---\n\n## Field note: why the volume isn't overhead\n\nIf the consumer is an agent, then the volume and the rigid structure aren't overhead —\nthey're the entire mechanism. A human skims; an agent needs an unambiguous, addressable,\nmachine-checkable contract or it drifts. So \"too much ceremony for a person to read\" is\na **category error**: nobody reads it, they query it.\n\nThe core claim is the strongest argument for the whole approach: the documents are the\n**anti-drift harness**. The exact failure mode named here — an agent producing\nnice-looking, plausible, partially-wrong code and silently dropping a requirement — is\nprecisely what the framework's machinery is built to prevent. On a real build it worked:\nthe coverage check found genuine components that didn't exist yet (would've been silently\nmissing); the reference resolver caught dangling links the moment they appeared; the\ntest-first manifests mean an agent can't \"finish\" a component without the oracle that\nproves it. Content-hash IDs + cumulative tags give every future agent a stable address\nfor \"this exact requirement\" so it can't quietly reinterpret it. That's not documentation\ntheater — that's the leash.\n\nThe place this pays off most is the one easiest to under-weight: **maintenance by a\ndifferent agent, months later, in fresh context.** Writing the first version is the cheap\npart. The expensive, dangerous part is the second agent modifying code it never wrote —\nand without the spec + traceability + tests, that agent reconstructs intent from the code,\nwhich is exactly how silent breakage compounds. The framework hands every future agent the\nauthoritative intent and the test that proves it didn't break the invariant. For an\nAI-maintained system over years, that's the difference between maintainable and a\nslowly-rotting black box.\n\n**Verdict:** for an AI-driven build-deploy-maintain loop, this is closer to **necessary**\nthan merely worth it. The \"is it worth the weight\" question was a human-era question.\n\n---\n\n*This README captures the framework's design intent for the AI-agent era: a\ntransformation-and-maintenance layer between a human's seed and the agents that build\nand keep a system alive — with its responsibilities drawn honestly.*\n\n---\n\n## Tooling\n\nThe framework is engine-agnostic. Any capable AI agent derives its behavior from\nthe spec, templates, and playbooks directly — no platform-specific wrapper needed.\n\n| Tool | Purpose |\n|------|---------|\n| `sdd_doc_lint/` | Structural linter — 320+ deterministic checks against layer standard and workflow templates |\n| `hooks/sdd-doc-review.sh` | PostToolUse advisory hook — surfaces lint findings on SDD document edits |\n| `hooks/ch-gate-check.sh` | PreCommit advisory hook (also pre-commit) — warns on code without an active CHG |\n| `hooks/sync-version-refs.sh` | Version synchronization hook — propagates framework version across playbooks and metadata |\n| `framework/governance/workflows/` | Declarative CNCF Serverless Workflow state machines (12 cataloged workflows) |\n\nThe former platforms (Hermes MCP server, Claude Code plugin) were archived on\n2026-09-07 and their code has since been removed — no live platform code\nremains; the framework is the whole product.\n\n## Status\n\nThe migration is complete (cutover shipped as `v1.0.0` in the 0.53.x era);\nthe project is in **post-cutover development** tracking framework spec **`0.86.1`**.\nThe framework has fully adopted the **CNCF Serverless Workflow v0.8 specification** across all 10 SDD layers (PRs #904 through #926, Decisions GD-51 through GD-61), establishing vendor-neutral declarative state machines and the Dual-Template Architecture. Platforms (Hermes, Claude Code plugin) have been archived — the framework is self-sufficient for any AI agent.\n\n> *This overview is a point-in-time snapshot (as of 2026-10-06); it is not\n> wired into the version-sync hook. For live version state see `framework/VERSION`.*\n\nDevelopment is tracked in [GitHub issues](https://github.com/vladm3105/aidoc-flow-framework/issues);\nthe live document-of-record for spec changes is [`framework/CHANGELOG.md`](framework/CHANGELOG.md) (the root `CHANGELOG.md` is a frozen tombstone).\n\n## Contributing\n\nEnable the pre-commit hooks before committing:\n\n```sh\npip install pre-commit && pre-commit install\n```\n\nSee `.pre-commit-config.yaml` for the hook set and [`SECURITY.md`](SECURITY.md)\nfor the vulnerability-reporting policy.\n\n## Documentation\n\n- [`framework/CHANGELOG.md`](framework/CHANGELOG.md) — live document-of-record for spec changes (GATE-SPEC-E008); root `CHANGELOG.md` is a frozen tombstone.\n- [`framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md`](framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md) — end-to-end SDD practitioner guide covering dual-template architecture, structural linting, and saga rollback compensation.\n- [`framework/AI_ASSISTANT_RULES.md`](framework/AI_ASSISTANT_RULES.md) — instructions for AI coding assistants on selecting templates, respecting gates, and preventing drift.\n- [`framework/README.md`](framework/README.md) — the engine-agnostic SDD specification and layer architecture.\n- [`framework/governance/README.md`](framework/governance/README.md) — governance policies, change management (CHG), and catalog of 12 CNCF Serverless Workflows.\n- [`framework/governance/GOVERNANCE_WORKFLOW_STANDARD.md`](framework/governance/GOVERNANCE_WORKFLOW_STANDARD.md) — normative CNCF Serverless Workflow standard and catalog.\n- [`framework/governance/CHG_REQUEST_FLOWS.md`](framework/governance/CHG_REQUEST_FLOWS.md) — change request classification and flow routing across 6 traversal paths (HOTFIX, CODE2S, CODE2C, SEED2C, DIR2C, SDD2C).\n- [`framework/governance/WORKTREE_FLOW.md`](framework/governance/WORKTREE_FLOW.md) — per-task worktree invariants and order guards.\n- [`framework/governance/aidoc/AIDOC.md`](framework/governance/aidoc/AIDOC.md) — the `.aidoc/` provenance tier (third committed documentation tier).\n- `SECURITY.md` — security policy and vulnerability reporting.\n- `docs/REPO_STRUCTURE.md` — repository layout (as-built).\n- `docs/ADAPTATION-GUIDE.md` — how a new project adapts the framework (`.aidoc/` layer, profile knobs, overrides).\n- `docs/PROJECT.md` — versioning, branching, milestones, conformance, change management.\n- `docs/TAGGING.md` — git-tag policy (release + bookmark tags).\n- [`plans/ACCEPTANCE-HISTORY.md`](plans/ACCEPTANCE-HISTORY.md) — retired acceptance-test methodology (moved from `tests/ACCEPTANCE.md`, CHG-08 #670).\n- [`tests/README.md`](tests/README.md) — tiered test-suite navigation hub.\n- [`docs/STARTUP_HANDOFF.md`](docs/STARTUP_HANDOFF.md) — historical session brief from the Phase-3/4 migration period.\n\n## Pre-migration history\n\nThis project was migrated from the pre-migration `ucx_framework` (v0.20.4)\ninto the multi-platform structure above. The **pristine pre-migration project**\nis preserved on the protected, read-only branch\n**`legacy-ucx-v3.2-read-only`** (`git checkout legacy-ucx-v3.2-read-only`).\nThe full migration record — per-task plans, audits, verify records, and the\ndecision log — lives under `plans/`.\n",
  "bytes": 21317,
  "sha": "2a241f01cf4b5c0d5861a40ae7a79a1e5a30cdda603b08bebdcf3508e1e3df6c",
  "repo_slug": "vladm3105/aidoc-flow-framework",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_vladm3105_aidoc_flow_framework_doc_ears__217a3207/readme"
}