doc-brd-fixer
vladm3105/aidoc-flow-framework · skills.sh
Open source Repository Open in the app JSON README (API)
About
Skill publicada por vladm3105/aidoc-flow-framework no skills.sh. Instale com: npx skills add vladm3105/aidoc-flow-framework@doc-brd-fixer
Details
- Kind
- Agent skills
- Publisher
- vladm3105
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 17
- Forks
- 3
- Last push
- 2026-10-07T02:00:35Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-10-07 06:28:22
- Updated
- 2026-10-07 06:28:22
- Origin id
vladm3105/aidoc-flow-framework/doc-brd-fixer
README
# 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→CHG→EVAL ◀─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 ten cumulative layers (8 SDD + CHG + EVAL), 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 |
| L9 | **CHG** — Change Management | Governance gates, adaptive change control with approval + re-gate |
| L10 | **EVAL** — Evaluation & QA | Test strategy, coverage matrices, quality governance |
Overlays: markdown **development/work plans** (`plans/*.md`) — the human-and-agent-readable
plan-of-record for a single change.
### Dual-Template Architecture (Standard vs. Workflow-Driven)
Every layer provides two authoring templates:
- **Standard Templates** (`{TYPE}-TEMPLATE.yaml`): Declarative, structured specifications for standard features.
- **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`.
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. Which flow an adaptation takes — the 6 traversal-path graph lifecycles
(SDD2C greenfield, DIR2C direct request, SEED2C brownfield restart, CODE2C bugfix,
CODE2S reconciliation, or HOTFIX emergency) — is routed by
`framework/governance/CHG_REQUEST_FLOWS.md` (ratified 0.57.0, CHG-06; modernized in 0.88.0+).
---
## 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. In
practice this has surfaced 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., "the chosen provider
supports the required flow on the target platform"), 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.*
---
## Tooling
The framework is engine-agnostic. Any capable AI agent derives its behavior from
the spec, templates, and playbooks directly — no platform-specific wrapper needed.
| Tool | Purpose |
|------|---------|
| `sdd_doc_lint/` | Structural linter — 320+ deterministic checks against layer standard and workflow templates |
| `hooks/sdd-doc-review.sh` | PostToolUse advisory hook — surfaces lint findings on SDD document edits |
| `hooks/ch-gate-check.sh` | PreCommit advisory hook (also pre-commit) — warns on code without an active CHG |
| `hooks/sync-version-refs.sh` | Version synchronization hook — propagates framework version across playbooks and metadata |
| `framework/governance/workflows/` | Declarative CNCF Serverless Workflow state machines (12 cataloged workflows) |
The former platforms (Hermes MCP server, Claude Code plugin) were archived on
2026-09-07 and their code has since been removed — no live platform code
remains; the framework is the whole product.
## Status
The migration is complete (cutover shipped as `v1.0.0` in the 0.53.x era);
the project is in **post-cutover development** tracking framework spec **`0.86.1`**.
The 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.
> *This overview is a point-in-time snapshot (as of 2026-10-06); it is not
> wired into the version-sync hook. For live version state see `framework/VERSION`.*
Development is tracked in [GitHub issues](https://github.com/vladm3105/aidoc-flow-framework/issues);
the live document-of-record for spec changes is [`framework/CHANGELOG.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/CHANGELOG.md) (the root `CHANGELOG.md` is a frozen tombstone).
## 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
- [`framework/CHANGELOG.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/CHANGELOG.md) — live document-of-record for spec changes (GATE-SPEC-E008); root `CHANGELOG.md` is a frozen tombstone.
- [`framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md) — end-to-end SDD practitioner guide covering dual-template architecture, structural linting, and saga rollback compensation.
- [`framework/AI_ASSISTANT_RULES.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/AI_ASSISTANT_RULES.md) — instructions for AI coding assistants on selecting templates, respecting gates, and preventing drift.
- [`framework/README.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/README.md) — the engine-agnostic SDD specification and layer architecture.
- [`framework/governance/README.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/governance/README.md) — governance policies, change management (CHG), and catalog of 12 CNCF Serverless Workflows.
- [`framework/governance/GOVERNANCE_WORKFLOW_STANDARD.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/governance/GOVERNANCE_WORKFLOW_STANDARD.md) — normative CNCF Serverless Workflow standard and catalog.
- [`framework/governance/CHG_REQUEST_FLOWS.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/governance/CHG_REQUEST_FLOWS.md) — change request classification and flow routing across 6 traversal paths (HOTFIX, CODE2S, CODE2C, SEED2C, DIR2C, SDD2C).
- [`framework/governance/WORKTREE_FLOW.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/governance/WORKTREE_FLOW.md) — per-task worktree invariants and order guards.
- [`framework/governance/aidoc/AIDOC.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/framework/governance/aidoc/AIDOC.md) — the `.aidoc/` provenance tier (third committed documentation tier).
- `SECURITY.md` — security policy and vulnerability reporting.
- `docs/REPO_STRUCTURE.md` — repository layout (as-built).
- `docs/ADAPTATION-GUIDE.md` — how a new project adapts the framework (`.aidoc/` layer, profile knobs, overrides).
- `docs/PROJECT.md` — versioning, branching, milestones, conformance, change management.
- `docs/TAGGING.md` — git-tag policy (release + bookmark tags).
- [`plans/ACCEPTANCE-HISTORY.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/plans/ACCEPTANCE-HISTORY.md) — retired acceptance-test methodology (moved from `tests/ACCEPTANCE.md`, CHG-08 #670).
- [`tests/README.md`](https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/tests/README.md) — tiered test-suite navigation hub.
- [`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/`.