# DoCoDeGo — full canonical text > Generated at build time from the canonical framework docs. The website at > https://docodego.com renders a curated subset of this material; this file > exists for LLM consumers that want the full text in one place. > > See https://docodego.com/llms.txt for a concise table-of-contents version. --- # The DoCoDeGo Manifesto *We are uncovering better ways of building systems in an era where machines can build anything — but humans must account for everything.* --- AI has not made software development less human. It has made the human part more visible by stripping away everything that was merely mechanical. The valuable part was always the thinking — and the accountability for it. This conviction drives the framework's core axiom: ## The Axiom > **Intent is the primary artifact.** > **Implementation is a compiled derivative.** > **Governance is earned through the loop.** When AI generates the implementation, the specification becomes what code used to be. You do not patch intent; you refine it. You do not debug the agent; you clarify the brief. --- ## The Four Values | We Value | Over | |----------|------| | **Intent** | Implementation | | **Direction** | Production | | **Flow** | Releases | | **Governance** | Process | Both sides matter. When AI can generate implementation, produce output at scale, and simulate process compliance, the left side is where human accountability is non-negotiable. AI can assist with all of it. Someone must own all of it. ### **Intent over Implementation** Implementation is inexpensive when AI generates it. What cannot be delegated is the decision about what to build and the accountability for that decision. If the AI produces the wrong result, the failure belongs to the person who commissioned it — not the machine that built it. *When we default to implementation-first: we build accurately but wrongly — and the accuracy of the output makes the mistake harder to detect and more expensive to correct. The agent produces precisely what was asked for. What was asked for was wrong.* ### **Direction over Production** Production capacity is abundant. The scarce resource is accountable judgment. Direction means choosing the right problems, defining constraints, deciding what not to build, and being answerable for those choices. *When we default to production-first: we ship quickly into drift — discovering misalignment only when users or incidents reveal what a specification would have caught before a line was generated. Speed has a direction problem. Without direction, it compounds.* ### **Flow over Releases** The bottleneck is validation, not implementation. Value should flow continuously when validation confidence is met — not on a schedule. Every gate must earn its place. Artificial delays are waste. *When we default to release-first: we create delivery ceremonies that obscure whether value is actually flowing. The ceremony becomes the signal; the system's actual behavior — whether users are being helped, whether intent is being met — becomes secondary to the calendar. A team can complete every sprint on time, ship every Tuesday, hit every velocity target, and still deliver nothing of value — because the sprint clock ran out before anyone asked whether the feature solved the actual problem.* ### **Governance over Process** Process compliance can be faked. Accountability cannot. Governance means active, continuous ownership of what AI systems are doing — confidence thresholds, scope limits, reasoning trace audits, drift detection. The question is never "did we follow the process?" but "is the system doing what we said it would, and do we stand behind it?" *When we default to process-first: we satisfy the procedure while the system goes ungoverned. This is the most dangerous default: process compliance can be observed, audited, and certified. Accountability for AI system behavior requires more than a checklist. A team can pass every governance review, file every required report, and still be operating an AI system that has drifted months away from its approved specification — because the checklist asked "did we review?" not "is the system doing what we said it would?"* --- ## The Agile Shift Agile was right for its era. Its era has ended. | Agile (2001) | DoCoDeGo (2026) | Why the shift | |--------------|-----------------|---------------| | Working software over documentation | Intent over implementation | Specs are now the command interface for AI agents | | Responding to change over planning | Flow over releases | AI collapses build time; the constraint is validation | | Individuals and interactions over processes | Direction over production | AI agents are participants, not tools | | Customer collaboration over contract negotiation | Governance over process | Active alignment replaces passive compliance | DoCoDeGo does not contradict Agile's values. It inherits them and extends them into a world Agile did not anticipate. Teams practicing Agile well — disciplined, intent-driven, delivery-focused — are closer to DoCoDeGo than teams practicing Agile badly. --- ## Modern Work Values Beyond the four pillars, DoCoDeGo reflects how knowledge work has changed: | We Value | Over | |----------|------| | Research and context | Discussion without information | | Reading before commenting | Reacting without understanding | | Clarifying intent | Assuming understanding | | Updating specifications | Patching code | | AI-augmented analysis | Manual investigation | --- ## The Anti-Complexity Principle **This principle governs how the framework itself evolves. It is constitutional — not a guideline.** > Any addition to the framework must not increase the net ceremony burden on a team at any > maturity stage unless the increase in governance burden is proportional to demonstrated > AI autonomy risk at that stage. Governance scales with autonomy, not with organizational size or headcount. A Stage 1 team faces low AI autonomy risk; their governance must be correspondingly light. A Stage 4 team operates autonomous agents with high autonomy risk; their governance is necessarily substantial. Additions that increase governance burden without a corresponding increase in managed autonomy violate this principle and must not be accepted into the framework. This principle exists because complexity is commercially advantageous to consultants and naturally accretes in frameworks that lack a structural constraint against it. The principle does the structural work that good intentions alone cannot do. **Practical test for any proposed framework addition:** Does this reduce or maintain the ceremony burden on a team at the stage where it applies, or does it increase it? If it increases ceremony burden, what specific AI autonomy risk does it address, and is the increase proportional to that risk? A proposed addition that cannot answer this question concretely fails the test. --- ## What DoCoDeGo Is Not **It is not anti-Agile.** It is post-Agile. Agile solved the right problem for its era. **It is not a tool.** No specific AI model, platform, or vendor is required. **It is not a process.** It is a framework of values and principles that teams adapt to their context. There is no correct implementation of DoCoDeGo, only more or less aligned ones. **It is not contingent on AI being limited.** The entire framework is built on the assumption that AI capability will continue to improve — and that human accountability for what gets built and run does not diminish as a result. The stronger the AI, the more important it is to know who decided to use it, for what, and under what constraints. **It is not finished.** This is a living document. Intent evolves as understanding deepens. --- ## The Name DoCoDeGo is an anagram of **Good Code**. D-O-C-O-D-E-G-O → G-O-O-D-C-O-D-E. Same eight letters. The framework name is the outcome. This is not an accident retrofitted to a convenient coincidence. It is the correct way to read what the framework is for. Teams that practice DoCoDeGo write good code — not because they follow a process, but because they know what they are building before they build it, they direct AI with precision, they ship when validation passes, and they govern what they deploy. **The name is the claim. The practice is the proof.** When someone asks what DoCoDeGo produces, the answer is already in the name: Good Code. Not faster code. Not more code. Code that does what was intended. --- ## Who Signs This DoCoDeGo is an open framework. It does not have signatories in the way the Agile Manifesto did. It has practitioners — teams and individuals who work by its values, contribute to its evolution, and demonstrate their understanding through practice rather than credentials. A team that produces Good Code by the standards this framework defines is a DoCoDeGo team. That is the only recognition that matters. *"DoCoDeGo is the art. We are the artists. Art never fades."* --- *→ For the operational framework: [The Four Pillars](./02-pillar-00-overview.md)* --- **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # DoCoDeGo — Vision & Philosophy --- ## Where This Came From Software development has always been a human act. Not because humans wrote the code — machines have always run it. But because a human decided what the code should do, chose which problems were worth solving, and took responsibility for the consequences. Code was the medium. Intention was the message. Agile understood this, briefly. In 2001, seventeen people in a ski lodge in Utah agreed that the most important thing in software was the human conversation — between developers and customers, between intention and reality, between what was promised and what was built. Then Agile became a product. The conversation became a ceremony. The intention became a backlog item. The human connection became a standup. And the developers who were supposed to be freed by Agile found themselves constrained by it instead — their work broken into two-week boxes, their value measured in story points, their judgment replaced by process. What was supposed to free developers became the thing that constrained them. --- ## The AI Moment AI has not made software development less human. It has made the human part more visible by stripping away everything that was merely mechanical. A developer who spends their day writing boilerplate, translating specifications into syntax, and debugging integration failures is doing mechanical work. AI does it better and faster. This is not a threat. It is a reveal: that was never the valuable part. The valuable part was always the thinking — and the accountability for it. The clarity. The judgment about what to build and what not to build. The willingness to say "this is wrong" before a line is written. The commitment to stand behind what was built when it reaches the people who depend on it. AI amplifies that. It also amplifies the absence of it. A team that builds with intention becomes more capable with AI. A team that builds without intention builds faster toward the wrong destination. The amplification is not selective. It applies to both. This is the conviction behind the framework's core axiom: > **Intent is the primary artifact. Implementation is a compiled derivative. Governance is earned through the loop.** --- ## The Artistic Dimension We have said: DoCoDeGo is the art. We are the artists. This is not metaphor. Software, at its best, is a form of making — shaped by vision, tested by reality, revised by learning. The intent specification is not bureaucracy. It is the artist's brief: what does this need to be? The composition is not assembly. It is craft: how do we make it well? The delivery is not logistics. It is publication: releasing something made to the people it was made for. The governance is not compliance. It is stewardship: protecting what was made from what it was not meant to become. Art never fades because good making never becomes irrelevant. Techniques change. Tools change. The act of caring enough to do something well does not. --- ## What We Are Trying to Protect We are trying to protect the thing that makes software worth building: human intent made tangible. We are trying to resist the commodification of methodology — the transformation of a way of working into a product to be sold, a credential to be awarded, a compliance checklist to be completed. Agile was once a set of values. Then it became a noun. Then it became a consulting practice. Then it became something developers had imposed on them rather than chose for themselves. DoCoDeGo begins with this awareness. We know the path. We are choosing not to walk it. This framework will not produce certifications. It will not produce accredited trainers. It will not produce a SAFe equivalent that large enterprises can bolt onto their org charts. If it produces anything, it should produce engineers who think more clearly about what they are building and why — and organizations that trust them to do so. --- ## The Founding Orientation Future building doesn't start from your keyboard. It starts from your understanding of what matters to the people you are building for. It starts from the clarity to say what you mean. It starts from the courage to stop when what is being built no longer matches what was intended. The keyboard is last. The heart is first. The framework is the space between them. --- ## A Note on Language The DoCoDeGo framework documents are written to be practical, precise, and free of rhetorical ornament. That is intentional. Methodology should be clear. It should answer questions, not raise them. But methodology without philosophy is a checklist. It can be followed without being understood, applied without being believed, completed without having any effect on the actual work. This document is the philosophy. The rest of the framework is the methodology. Both are necessary. They are intentionally separated so that each can be what it is, without the other pulling it in the wrong direction. Read this when you need to remember why. Read the rest when you need to know what. --- *"DoCoDeGo is the art. We are the artists. Art never fades."* --- **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # The Four Pillars of DoCoDeGo **DOcument · COmpose · DEmonstrate · GOvern** --- ## The System at a Glance > **Intent is the primary artifact. Implementation is a compiled derivative. Governance is earned through the loop.** DoCoDeGo is a loop, not a checklist. Each pillar feeds the next, and the last feeds back into the first. Governance deepens as AI autonomy increases — you earn your way through the cycle. A team that skips any pillar does not get a lighter version of the framework; it gets a broken one. - **Skip DO:** AI generates code against undocumented assumptions. Six weeks later, the team debates what the system was supposed to do — and finds no record. - **Skip CO:** AI output ships unreviewed. Security gaps, architectural contradictions, and silent scope misreadings become production surprises. - **Skip DE:** Valid outputs wait in queues for the next release window. Value moves at the speed of coordination, not the speed of verification. - **Skip GO:** The system diverges from approved intent one small decision at a time, with no one watching. The divergence surfaces in an incident, a regulatory audit, or a customer complaint — not in a review. | Pillar | Human role | Core principle | |--------|-----------|----------------| | **DO** Document | Author | Specification is the only source of truth | | **CO** Compose | Architect | Human owns the architecture; AI implements it | | **DE** Demonstrate | Gatekeeper | Value flows at the speed of validation, not schedules | | **GO** Govern | Governor | Autonomy without accountability is catastrophe | --- ## The Loop ``` DO → CO → DE → GO ↑ ↓ └── feedback ←──┘ ``` | Phase | What happens | Human job | |-------|-------------|-----------| | **DO** | Write specification | Author intent precisely enough for a machine to act on it | | **CO** | Agents construct | Direct AI composition; review for architecture and correctness | | **DE** | Continuous delivery | Open the gate when validation passes, not on a schedule | | **GO** | Governance validates | Watch for drift, verify alignment, feed learnings back | | **Loop** | Repeat | Refine intent based on what GO revealed | --- ## The Maturity Dimension A 2-person startup and a 200-person enterprise do not need the same GO practices. The loop runs at every scale. Governance formalizes as AI autonomy increases. | Stage | Profile | What you run | |-------|---------|-------------| | **1 — Augmented** | Any team, any size | DO + CO: spec-first, AI-assisted. Manual review. | | **2 — Collaborative** | Growing team, shipping regularly | + DE: validation-gated delivery, observability | | **3 — Orchestrated** | Multi-agent, multi-team | + GO: alignment checks, scope limits, agent monitoring | | **4 — Autonomous** | Autonomous agent systems | Full GO: confidence thresholds, audit trails, kill switches | You do not skip stages. See [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md) for advancement criteria. --- ## DO — Document > *For the leader: AI agents need to be told what to build with the same clarity you > would need to brief a new employee. The specification is that brief.* The DO pillar is not about passive record-keeping. It is the command interface. When AI agents construct a system, the specification is what they act on. Ambiguity in the spec becomes defects in the output. Clarity in the spec becomes correct behavior. **The DO pillar requires:** - Structured, versioned specifications with explicit acceptance criteria - Every requirement independently testable - Threat models for failure scenarios - Explicit out-of-scope boundaries **The shift from traditional development:** Traditional: write code, document later (or never). DoCoDeGo: write the spec, then generate the code from it. → [Full DO Pillar](./02-pillar-01-do-documentation.md) · [Spec Template](./03-practice-02-spec-template.md) --- ## CO — Compose > *For the leader: Your team's job shifts from writing code to directing AI that writes > code. Architecture judgment and review capacity become the scarce resources.* Composition in DoCoDeGo is a collaboration between human architects and AI agents. The human sets constraints, defines structure, and reviews outputs. The AI generates implementation, suggests approaches, and executes at scale. **The CO pillar requires:** - Specifications complete and approved before composition begins - Human architectural review of AI-generated outputs - Multi-agent workflows for complex systems - Explicit handling of brownfield (existing, undocumented systems) **The shift from traditional development:** Traditional: developer is implementer. DoCoDeGo: developer is architect and reviewer; AI is implementer. → [Full CO Pillar](./02-pillar-02-co-compose.md) --- ## DE — Demonstrate > *For the leader: Shipping schedules are an artifact of human coordination bottlenecks. > When AI removes the implementation bottleneck, the only remaining gate should be > validation confidence.* Delivery in DoCoDeGo is gated by validation, not by calendar. There are no release events — there is only continuous state convergence toward declared intent. Every gate that exists must earn its place by reducing real risk. The IRAF loop (Intent → Reasoning → Action → Feedback) describes how each delivery cycle works: intent is the input, agent reasoning is the process, action is the output, and feedback from deployment refines the next cycle's intent. **The DE pillar requires:** - Delivery gated by validation confidence, not schedule - Observability built into every deployment - Automated acceptance test execution before delivery - Feedback loops that return to DO **The shift from traditional development:** Traditional: two-week sprints coordinating human work. DoCoDeGo: continuous delivery when validation passes. → [Full DE Pillar](./02-pillar-03-de-delivery.md) --- ## GO — Govern > *For the leader: The more autonomous your AI systems are, the more explicit your > oversight must be. Governance in DoCoDeGo is not a compliance gate — it is the > active accountability structure that makes autonomy safe.* Governance in DoCoDeGo is earned through the loop, not imposed from the start. In its minimal form, governance is always present: "did this do what we said it would?" It formalizes as AI autonomy deepens — autonomous agents require explicit boundaries, confidence thresholds, and audit trails that a developer using a coding assistant does not. Governance is structurally necessary — not a workaround for AI being imperfect. The reasons are durable: legal and regulatory accountability (EU AI Act, Cyber Resilience Act) does not diminish as AI improves; AI cannot know your organization's commitments and constraints; auditability is a permanent requirement for incident response and compliance; and more capable AI acting on misspecified intent causes larger harm, not smaller. Governance becomes *more* important as AI capability grows, not less. **The GO pillar at each maturity stage:** - Stage 1–2: Manual review, output validation, basic observability - Stage 3: Alignment checks, scope limits, agent monitoring, Intent Reviews - Stage 4: Confidence thresholds, kill switches, reasoning trace audits, drift detection **The shift from traditional development:** Traditional: governance as process compliance ("did we follow the checklist?"). DoCoDeGo: governance as active alignment ("is the system doing what we said it would?"). → [Full GO Pillar](./02-pillar-04-go-governance.md) · [Roles](./03-practice-04-roles.md) · [Metrics](./03-practice-05-metrics.md) --- ## The Human Through the Loop The human role changes at each pillar, but the human is present at every stage: | Pillar | Human as... | Primary skill required | |--------|------------|----------------------| | DO | Author | Clarity of intent | | CO | Architect | Systems judgment | | DE | Gatekeeper | Validation confidence | | GO | Governor | Accountability and drift detection | None of these roles disappear as AI capability increases. The accountability they carry cannot be delegated to a machine — only neglected. They deepen. --- ## Where to Go Next Read the four pillar documents in sequence — each one specifies what the pillar requires, not just what it is: 1. *→ [DO Pillar](./02-pillar-01-do-documentation.md)* — what specification-as-command-interface means in practice, including the two-phase workflow and the brownfield challenge 2. *→ [CO Pillar](./02-pillar-02-co-compose.md)* — how human architectural authority works when AI generates the implementation, including invariant protection and the skill atrophy problem 3. *→ [DE Pillar](./02-pillar-03-de-delivery.md)* — validation-gated delivery, the IRAF loop, and how to decide which gates earn their place 4. *→ [GO Pillar](./02-pillar-04-go-governance.md)* — the durable case for governance, bounded autonomy, and why governance becomes more important as AI capability grows *→ [Manifesto](./01-core-02-manifesto.md)* — the authoritative root of the framework · *→ [Statutes](./03-practice-01-statutes.md)* — the rules that make the loop non-negotiable · *→ [Spec Template](./03-practice-02-spec-template.md)* — start here to begin practicing today **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # DO — Document *The Intent Pillar* --- > *For the leader: A specification is not just a brief for an AI agent. It is the record > of what you decided to build and why. When something goes wrong, it is what you point to. > The DO pillar is the discipline of making that record clear enough to be accountable for.* --- ## The Principle **Specification is the only source of truth.** > **Intent is the primary artifact. Implementation is a compiled derivative.** > > *— [The Manifesto](./01-core-02-manifesto.md)* In traditional development, code was the source of truth. Documentation was written after the fact, if at all, and decayed the moment it was written. In AI-era development, this is inverted. The specification is what you write first. The code is what the AI generates from it. When the output is wrong, you do not patch the code — you refine the specification that generated it. When you want to change behavior, you do not edit the implementation — you update the intent that produced it. This is not documentation as bureaucracy. It is documentation as command interface. *When teams skip this: AI amplifies whatever was in the brief — correct or not. A vague or missing specification does not produce a vague output; it produces a confident, detailed output built on the AI's assumptions. Those assumptions will be wrong in ways that are expensive to discover after composition.* --- ## What DO Requires ### 1. Write Intent, Not Implementation A DoCoDeGo specification describes what a system must do and what it must not do. It does not describe how to build it. The "how" is the AI's job. **Note on simple tasks:** Not every task requires a full specification. Single-action, no-branching tasks use the Simple Spec mode — Intent, Constraints, Acceptance Criteria, Threat Model, and Out of Scope, with optional sections declared inapplicable. The overhead for a simple spec is measured in minutes, not hours. See [Spec Template](./03-practice-02-spec-template.md) for the Simple Spec vs. Full Spec distinction. **Wrong (implementation-oriented):** > "Create a REST API endpoint at `/api/tickets` that queries the PostgreSQL tickets table > and filters by status field, returning JSON with id, subject, and assignee fields." **Right (intent-oriented):** > "When a user requests open tickets, the system returns all tickets in 'open' or 'in-progress' > status, including their identifier, subject line, and current assignee. Response time must > not exceed 500ms under normal load." The first tells the AI how to build it. The second tells the AI what it must do. The AI can choose the implementation. The human chose the intent. ### 2. Make Every Requirement Testable Every requirement in a specification must be independently verifiable. If you cannot write a test for it, it is not a requirement — it is a hope. **Untestable:** "The system should be fast." **Testable:** "95th-percentile response time must not exceed 500ms under a load of 100 concurrent requests." **Untestable:** "The interface should be user-friendly." **Testable:** "A first-time user completes the primary workflow without assistance within 3 minutes in a usability session." ### 3. Version Like Code Specifications change. Intent evolves. A specification that is not versioned will drift from what was actually built. Every spec must have: - A version number - An owner (the Intent Architect) - A status (draft / review / approved / deprecated) - A change log when updated ### 4. Include a Threat Model Every specification must identify its top failure modes and their recovery paths. This is not optional. AI agents asked to fulfill a specification without a threat model will not proactively identify failure scenarios. The threat model is where the human's judgment about risk becomes part of the intent. Minimum: three failure modes with recovery paths. ### 5. Declare What Is Out of Scope Specifications without explicit scope boundaries will be interpreted generously by AI agents. If you do not say what the system should not do, you may get something that does more than you intended in ways you did not intend. ### 6. Score Before Composition (ICS) Every specification must be scored using the Intent Clarity Score (ICS) before composition begins. ICS measures spec quality across four dimensions: Completeness, Testability, Unambiguity, and Threat Coverage. The canonical definition and rubric are in [Spec Template](./03-practice-02-spec-template.md); thresholds and usage guidance are in [Metrics](./03-practice-05-metrics.md). A score of 60 or higher is required to begin CO. --- ## The Two-Phase DO Workflow For non-trivial features, DO operates in two distinct phases. Collapsing them into one produces specs that are internally correct but behaviorally contested. ### Phase A: Flow Definition **Output:** A behavioral flow document — lightweight, diagrammatic or narrative, covering the sequence of steps, decision points, branching paths, and (for stateful features) the entity state machine. **Who produces it:** Intent Architect, in collaboration with domain experts and stakeholders. **Review:** Team review before Phase B begins. The review question is: *Do we agree on what this feature does?* Not on how it's constrained or how it will be tested — just on the behavioral shape. **Gate to Phase B:** Team agreement on the flow. Disagreements resolved or explicitly parked with a decision owner. The flow does not need to be perfect — it needs to be agreed. **Triggering condition:** Phase A is required for any feature that has multiple steps, user decisions, branching paths, or stateful entities. Simple features (single action, single outcome, no branching) may proceed directly to Phase B. **What "commit separately" means:** The agreed flow is saved as a versioned artifact before spec writing begins. This creates a clear record of what was agreed and when — useful for drift detection, retrospectives, and onboarding. ### Phase B: Spec Writing **Input:** The agreed flow from Phase A becomes the Behavioral Flow section of the spec. It is not rewritten — it is incorporated. **Output:** The full intent specification, ICS-scored and ready for composition. **Key principle:** The flow drives the spec. Acceptance criteria should trace to flow steps. Business rules should govern flow decision points. Edge cases should address flow failure scenarios. A spec whose sections cannot be traced back to the flow has either a gap in the spec or an omission in the flow. ### When to Skip Phase A Simple features do not need Phase A: - Single action with no branching - Single outcome - No stateful entities - No user decisions For these, proceed directly to Phase B with the Behavioral Flow section declared inapplicable. --- ## The Constraint vs. CO Decision Boundary A common question: should specs include technology choices and API paths? The answer depends entirely on whether the item is a constraint or an implementation decision. ### Technology Choices | Situation | Classification | Where it belongs | |-----------|---------------|-----------------| | "Must use the existing PostgreSQL database" | **Constraint** | Constraints section | | "Must be implemented as a React component" | **Constraint** | Constraints section | | "Should probably use a queue for this" | **CO decision** | Not in the spec | | "Must not use third-party AI services" | **Constraint** | Constraints section | ### API Paths and Contracts | Situation | Classification | Where it belongs | |-----------|---------------|-----------------| | Existing path that external clients call | **Constraint** | Constraints section | | Path agreed upon with frontend team | **Constraint** | Constraints section | | New internal endpoint, path not decided | **CO decision** | Not in the spec | | Versioning requirement | **Constraint** | Constraints section | **The core principle:** A constraint is something the AI cannot change. A CO decision is something the AI should determine from context. **Default rule:** If changing it requires a stakeholder decision (not just a technical decision), it is a constraint. If uncertain, the Intent Architect should declare it as a constraint or explicitly escalate before spec approval. --- ## The Brownfield Challenge Most real work happens in existing systems — systems that were built without intent specifications, whose behavior is partially undocumented, and whose "correct" behavior is a matter of interpretation. DoCoDeGo does not pretend this is easy. For brownfield systems, the DO pillar requires an additional phase: **Intent Archaeology** Before writing a new spec, read the existing system as if you didn't build it. For each component, ask: what problem was this solving? Write provisional intent statements. Tag ambiguities explicitly. Mark undocumented behavior as "intent unknown — do not modify without investigation." A team that skips this phase and writes specs from assumption typically discovers the problem mid-composition: the authentication module they specced as "validates user credentials" turns out to silently handle account lockout for a compliance requirement that was never documented — and the AI overwrites it cleanly. **Behavior Verification** Write characterization tests for existing behavior. These are not the spec — they are a safety net during migration. They capture what the system currently does, not what it should do. **Intent Promotion** For the parts of the system you understand, write DoCoDeGo specs. Leave undocumented parts protected by characterization tests. Expand spec coverage incrementally as understanding deepens. This process is slow. It does not promise a quick migration. A large legacy system may require months of archaeology before DoCoDeGo composition can safely begin. This honesty is itself a principle: the framework does not oversell. --- ## The Amplification Effect AI amplifies what is already in your specifications. Clear intent → correct behavior, produced faster than any human team could. Vague intent → ambiguous behavior, produced at the same speed. But there is a second effect that matters as much as output quality: clear intent creates an accountable record. When the AI builds something and it turns out to be wrong, a team with a clear specification knows exactly where the failure was and who owned it. A team without one cannot answer that question at all. The DO pillar is the single highest-leverage investment a team can make. A team with strong specifications and average AI tooling will outperform a team with weak specifications and excellent AI tooling. Every time. This also means that teams that have historically been poor at requirements definition will not improve by adding AI. They will fail faster, and they will not know why. The DO pillar is the prerequisite that makes everything else in DoCoDeGo work. **External validation:** The 2025 Stack Overflow Developer Survey (49,000+ respondents) found that 66% of developers spend more time fixing "almost right" AI code than they save in generation — precisely the problem that ICS and structured specifications address. ThoughtWorks named spec-driven development "one of the most important practices to emerge in 2025." See [Research Validation](./05-ref-01-research-validation.md) for full citations. --- ## The Intent Architect The DO pillar has an owner: the Intent Architect. The Intent Architect is accountable for: - Writing and maintaining specifications - Approving specs before CO begins - The Intent Clarity Score of every spec they own - Refining intent when GO reveals misalignment The Intent Architect is not necessarily a developer. They are the person who understands what needs to be built well enough to write a precise brief for an AI agent. This role may be filled by a product manager, a domain expert, or a technical lead depending on context. What matters is clarity, not title. When the AI builds something technically correct but misaligned with what was actually wanted, the Intent Architect is accountable. Not because blame is the goal, but because accountability without clarity produces teams where no one improves their specifications. --- ## Accountability Assignment This accountability assignment is most important for teams where the Intent Architect is not a developer and where the natural instinct is to attribute output failures to the AI rather than the specification. When AI builds something technically correct but wrong: The Intent Architect is accountable. For example: a payment service spec that says "handle errors gracefully" without specifying retry behavior or idempotency requirements will produce an AI implementation that is internally consistent — and will double-charge users on network timeout. The AI built exactly what was specified. The spec did not capture what was needed. The spec was the contract. If the spec was clear and testable and the agent built to it, the failure is a failure of intent capture — an unclear or incomplete specification that did not express what was actually needed. This is uncomfortable. It is also the only assignment of accountability that incentivizes better specifications. --- ## Relationship to the Other Pillars - **DO feeds CO:** A complete, approved spec is the input to composition. CO cannot begin without it. - **DO feeds GO:** The spec is what governance validates against. Drift is measured against declared intent. - **GO feeds DO:** Governance reveals misalignment. That feedback refines the next specification. - **DE feeds DO:** Deployment telemetry reveals what the spec failed to capture. The loop restarts. --- ## Summary | Principle | Practice | |-----------|----------| | Intent before implementation | Write the spec before any composition begins | | Testable requirements | Every constraint has a verifiable test | | Versioned like code | Specs have owners, versions, and change logs | | Threat modeled | Every spec has 3+ failure modes with recovery paths | | Scope bounded | Out-of-scope is explicitly declared | A specification is the only artifact in the loop that is entirely human-authored. Everything downstream — composition, delivery, governance — inherits its quality. The DO pillar is where that quality is decided. --- *→ [Spec Template](./03-practice-02-spec-template.md) — the concrete artifact this pillar produces* *→ [CO Pillar](./02-pillar-02-co-compose.md) — what happens after the spec is complete* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # CO — Compose *The Synthesis Pillar* --- > *For the leader: Your engineers' time is now most valuable when they are reviewing, > directing, and deciding — not when they are writing boilerplate. The CO pillar defines > how human architectural judgment and AI composition work together.* --- ## The Principle **Human owns the architecture. AI implements it.** > **Intent is the primary artifact. Implementation is a compiled derivative.** In the CO pillar, this means the human's role is not to produce code — it is to own the decisions that produce it. > > *— [The Manifesto](./01-core-02-manifesto.md)* Composition in DoCoDeGo is not "let AI write the code." It is a deliberate collaboration where the human defines the architecture, constraints, and review criteria, and AI agents execute the implementation. The human's job does not shrink. It shifts. From implementation to direction. From writing to reviewing. From syntax to structure. And critically: from doing to *owning*. The Composition Lead is accountable for the architectural soundness of what is built — whether or not they wrote a single line of it. *When this principle is violated: human architects who defer architectural decisions to AI lose the ability to sign off with integrity. Accountability without comprehension is not accountability — it is rubber-stamping. The GO pillar weakens as a consequence.* --- ## What CO Requires ### 1. Specification Complete Before Composition Begins Composition does not begin until the DO phase is complete and the specification is approved. This is not process theater. It is the practical reality that AI agents asked to build without a clear specification will make assumptions. Those assumptions will be wrong in ways that are expensive to discover after composition. A specification is "ready for composition" when: - All acceptance criteria are independently testable - Threat model is complete - Scope is explicitly bounded - Intent Clarity Score ≥ 60 (see [Metrics](./03-practice-05-metrics.md)) ### 2. Human Architectural Authority The human's role during composition is architectural oversight, not line-by-line review. The Composition Lead is responsible for: - Defining the overall system structure before agents begin - Reviewing generated outputs for architectural soundness - Catching deviation from stated constraints - Escalating spec gaps discovered during composition back to the Intent Architect What does "architectural oversight" mean in practice? - Is the structure of what was generated consistent with the system's long-term constraints? - Does the generated code introduce dependencies or patterns not accounted for in the spec? - Are there emergent behaviors or edge cases the spec did not anticipate? These require human accountability. Even where AI can assist with architectural analysis, the Composition Lead is the person who signs off — who can be asked "why was it built this way?" and has to be able to answer. That accountability cannot be delegated. **"What if the AI output is clearly correct?"** Review effort scales with risk, not with doubt. For a simple, well-bounded feature with a high-ICS spec and passing acceptance tests, the architectural review is brief — confirm the structure matches the spec, no unexpected dependencies introduced, no scope additions. The question "is this what the spec said to build?" takes seconds on a clean output. The Composition Lead's value is in the cases where the answer is no — which a spec-first process makes visible precisely because there is a spec to compare against. ### 3. Multi-Agent Coordination Complex systems benefit from specialized agents working in coordination rather than a single agent attempting everything. A functional multi-agent team for a software composition task typically includes: - **Architect agent:** Designs the structure based on spec - **Coder agent:** Implements individual components - **Reviewer agent:** Reviews generated code against spec acceptance criteria - **Security agent:** Reviews for vulnerability patterns (regardless of whether issues are found) Multi-agent coordination is not mandatory for simple tasks. A single-agent workflow is appropriate for isolated, well-bounded features. Multi-agent becomes valuable when: - Multiple components must be built in parallel - Security review is non-negotiable - The scope is large enough that a single context window becomes a constraint A single-agent workflow building an authentication service produced functioning login logic — but no agent had the dedicated role of reviewing against OWASP patterns. Rate limiting was absent. A security agent with explicit scope over vulnerability patterns would have flagged it before delivery. When security review is non-negotiable, a single-agent workflow cannot cover it reliably. ### 4. Preserving System Invariants Code is regenerable. System invariants are not. Syntax can be regenerated from an improved specification. Business rules, data contracts, and integration contracts between systems cannot be changed without consequences that extend beyond the code. When constructing with AI, the Composition Lead must explicitly protect: - Data schema contracts (especially where other systems depend on them) - API contracts (what callers of this system expect) - Business rules that exist in the specification, not the code - Security invariants (authentication, authorization, encryption decisions) If a regeneration cycle would change these, it requires explicit human review and approval — not automatic acceptance. A concrete failure: a notification service regenerated from an updated spec silently renamed the `user_id` field to `userId` (camelCase) throughout the schema. The regenerated system passed all its own acceptance tests. Every downstream consumer that read `user_id` broke in production. The API contract was an invariant that was not declared — so it was not protected. **A note on non-determinism:** Regeneration from the same specification does not guarantee identical output. AI models are stochastic — the same prompt can produce different code across runs, and model updates can shift behavior silently. "Regenerable" means *reproducibly correct*, not *bit-for-bit identical*. This is why Regeneration Confidence (RC) is an active verification checklist, not a theoretical property. A regenerated system must pass acceptance tests, characterization tests, and integration checks — not just re-run cleanly. Do not assume equivalence; confirm it. ### 5. Handling Brownfield For systems being migrated into DoCoDeGo, composition follows after intent archaeology (see [DO Pillar](./02-pillar-01-do-documentation.md)). The key rule: **Do not regenerate what you do not have a spec for.** Characterization tests protect undocumented behavior. Composition only proceeds into areas where the intent has been explicitly captured in a specification. Systems that are partially documented can be partially migrated — there is no requirement to migrate all at once. --- ## The Skill Atrophy Problem If you cannot evaluate what was built, you cannot be accountable for it. This is the real risk, not a hypothetical one. A Composition Lead who cannot understand AI-generated output cannot sign off on it with integrity — regardless of how sophisticated the AI becomes. Accountability without comprehension is not accountability; it is rubber-stamping. DoCoDeGo requires that practitioners with architectural review responsibility maintain their technical depth through regular hands-on practice. This is not production work. It is deliberate skill maintenance: - Monthly: build something small from scratch without AI assistance - Quarterly: conduct a full architectural review of a system you didn't spec - The goal is not output; it is maintaining the comprehension required to own the output A team that loses this discipline will find that its GO pillar weakens — not because governance processes fail, but because the humans nominally running governance can no longer stand behind their sign-offs. **External validation:** The skill atrophy risk is compounded by the employment shift. Entry-level developer employment for ages 22–25 dropped nearly 20% in 2025 (see [Research Validation](./05-ref-01-research-validation.md)). The METR study (July 2025) found experienced developers were 19% *slower* with AI tools on complex tasks — validating that unstructured AI use degrades performance, and that the CO pillar's architecture-first discipline is not optional. --- ## Accountability in Composition When the AI builds something architecturally unsound or deviating from spec: The Composition Lead is accountable. The spec defines intent. The Composition Lead is responsible for ensuring the agent's output is consistent with that intent and architecturally sound. If a gap in the spec caused the deviation, the Composition Lead escalates to the Intent Architect — but does not proceed with flawed composition while waiting. --- ## Relationship to the Other Pillars - **DO feeds CO:** Composition begins only when the spec is approved. - **CO feeds DE:** A constructed and reviewed output is the input to delivery. - **CO reports to DO:** Gaps discovered during composition are reported as spec deficiencies, not code bugs. - **GO informs CO:** Post-deployment alignment failures may indicate composition-phase architectural decisions that need revisiting. --- ## Summary | Principle | Practice | |-----------|----------| | Spec first | Composition does not begin without an approved specification | | Architecture before generation | Human defines structure; AI implements | | Invariants protected | Business rules, data contracts, API contracts require explicit review | | Multi-agent for complex tasks | Specialized agents with defined roles for large-scope composition | | Technical depth maintained | Regular hands-on practice for architectural reviewers | The CO pillar is where the specification becomes a system — and where human architectural judgment determines whether the result is one worth delivering. --- *→ [DO Pillar](./02-pillar-01-do-documentation.md) — what CO depends on* *→ [DE Pillar](./02-pillar-03-de-delivery.md) — what CO feeds into* *→ [Roles](./03-practice-04-roles.md) — the Composition Lead role defined* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # DE — Demonstrate *The Flow Pillar* --- > *For the leader: Two-week sprints were designed to coordinate human work. When AI > removes the implementation bottleneck, the only remaining gate between a completed > feature and a delivered one should be: does it actually do what was specified?* --- ## The Principle **Value flows at the speed of validation, not at the speed of schedules.** > **Intent is the primary artifact. Implementation is a compiled derivative.** In the DE pillar, this means delivery is a question of verified convergence toward declared intent — not a question of calendar compliance. > > *— [The Manifesto](./01-core-02-manifesto.md)* Traditional release cycles — sprints, release trains, quarterly deployments — were solutions to human coordination bottlenecks. Multiple developers working on a system needed time windows that allowed their work to be integrated, reviewed, and tested without constant disruption. AI changes this. When implementation is generated in minutes rather than days, the coordination bottleneck is removed. What remains is validation: confirming that what was built actually matches the intent that was specified. Delivery in DoCoDeGo is gated by validation confidence. When validation passes, delivery proceeds. When validation fails, intent is refined. There is no release day. There is only the current state of the system and whether that state matches declared intent. *When this principle is violated: shipping on schedule regardless of validation state delivers misalignment to users. The release becomes the signal; whether intent was met becomes secondary. Unvalidated delivery is the fastest path to drift that governance cannot catch until it is already in production.* --- ## What DE Requires ### 1. Delivery Gated by Validation, Not Calendar Every gate in the delivery pipeline must earn its place by reducing real risk. A gate earns its place if removing it would result in measurable harm: - Automated test suite: earns its place (catches regressions) - Security scan: earns its place (catches vulnerability patterns) - Approval from a specific named individual for all changes: does not earn its place unless that individual adds judgment that cannot be automated "We always do it this way" does not earn a gate's place. "If we skip this, these specific things go wrong" does. A team that retained a mandatory "architecture lead sign-off" gate from its pre-AI workflow — where that lead reviewed implementation syntax they no longer wrote — added 1.8 days to every SDL with no corresponding reduction in defect rate. Removing the gate, and replacing it with a targeted acceptance test for the architectural constraint being protected, recovered the latency with better coverage. The practical question for every gate: what risk does this gate reduce, and is that risk real in our context? ### 2. The IRAF Loop The IRAF loop describes how each delivery cycle works: ``` Intent → Reasoning → Action → Feedback ↑ ↓ └──────── loop restarts ───────┘ ``` | Stage | What happens | |-------|-------------| | **Intent** | The spec defines what should be delivered | | **Reasoning** | The agent (or team) reasons about how to fulfill the intent | | **Action** | The output is delivered to the target environment | | **Feedback** | Telemetry, test results, and user signals return to the system | The feedback stage is not optional. Without feedback, the loop cannot refine intent. Without intent refinement, the system cannot improve. IRAF is not a replacement for OODA (Observe-Orient-Decide-Act). It is a specialization: IRAF centers intent as the starting condition, making it more appropriate for systems where declared intent (the specification) is the controlling variable. **Scope note:** IRAF is defined here at the delivery level — a complete specification moving from approved state to deployed state, with feedback closing back to intent. The same underlying principle (intent before action; feedback after every action) applies at the composition level when directing individual agent tasks in the CO pillar. When practitioners refer to "the IRAF loop" during composition, they are applying the same logic at narrower scope: the intent is a spec section, the action is a specific agent task, and the feedback is the deviation review. The delivery-level IRAF — spanning a full specification lifecycle — is the primary definition. Composition-level application is a natural extension of the principle, not a separate framework. ### 3. Observability Is Non-Negotiable Continuous delivery requires continuous visibility. You cannot govern what you cannot see. Every delivery must include: - Functional acceptance test results (did the acceptance criteria pass?) - Performance telemetry (is the system behaving within its specified constraints?) - Error rate monitoring (are failure modes being triggered?) - Behavioral drift indicators (is the system's behavior changing in ways not specified?) Observability is not an add-on. It is part of the delivery, built from the specification. Every acceptance criterion in the spec should have a corresponding observable metric. ### 4. Atomic Delivery Partial state is the enemy of continuous delivery. When a delivery fails mid-stream — some components updated, others not — the system enters an inconsistent state that is expensive to recover from and difficult to reason about. **The unit of atomicity is the specification.** One delivery = one approved spec, fully implemented and validated. A delivery that bundles outputs from multiple specs is not atomic — it combines validation scopes, making acceptance testing ambiguous and rollback complex. This means: - A single spec may produce multiple code changes — that is acceptable, if they all relate to the same declared intent - Multiple specs may not be bundled into a single delivery unit — each spec's delivery must be independently validated DoCoDeGo delivery requirements: - Atomic deployments: either the full spec's implementation is applied, or none of it is - Automatic rollback to last known-good state when acceptance tests fail - No partial state accepted without explicit human authorization and a defined rollback plan ### 5. Feedback Closes the Loop Every delivery cycle generates information that refines the next specification. The Flow Steward is responsible for ensuring that: - Delivery telemetry is aggregated and reviewed - Behavioral drift from the spec is flagged and escalated - Insights from deployment feed into the next DO cycle This is the mechanism by which the DO→CO→DE→GO loop actually improves the system over time. Delivery without feedback is delivery without learning. --- ## The No-Release-Event Principle There are no release events. There is only state convergence. A "release" implies a discrete moment of transition: before the release, users don't have the feature; after the release, they do. This model made sense when releases required significant human coordination to execute. In continuous delivery, the system converges continuously toward declared intent. Features appear when their validation criteria are met, not when a calendar milestone is reached. This requires: - Feature flags for partial rollouts - Progressive delivery (canary releases, staged rollouts) for high-risk changes - Clear separation between "deployed" (in the system) and "released" (visible to users) The goal is not to deploy constantly for its own sake. The goal is to remove artificial delays. A gate that exists because "we always release on Fridays" is artificial. A gate that exists because "changes to payment processing require manual sign-off" may be appropriate. **For teams with external constraints on release timing:** The No-Release-Event Principle does not require continuous deployment. It requires that releases not be gated by *arbitrary* schedules. Teams with genuine external constraints can apply the principle within their constraints: | Constraint | How to apply the principle | |------------|---------------------------| | Contractual release schedule (e.g., monthly customer releases) | Deploy continuously to staging; validate against acceptance criteria continuously; release to production on the contracted schedule. The delivery pipeline still runs; the production promotion is governed by contract, not ceremony. | | SOC 2 / FedRAMP compliance windows | Change control processes are earned gates, not artificial ones — they require documented rationale. The principle is satisfied if every gate has a documented justification. Compliance gates qualify. | | Customer-facing release notes | Separate deployment from announcement. Deploy continuously; release notes describe what has converged in the system since the last communication. This is a communication cadence, not a deployment gate. | | Regulated industries (healthcare, finance, defense) | Regulatory approval gates are earned gates. Apply spec-first practices within each approval cycle. The principle requires that no *additional* gates be imposed beyond those required by regulation. | The question to ask for every gate: "Would removing this gate cause a customer or compliance problem?" If yes, the gate is earned. If no, remove it. **External validation:** Kent Beck (Agile Manifesto co-author), 2025, explicitly shifted to writing narrowly-defined specifications followed by acceptance testing — the DE pillar's validation-gated model. Faros AI's 2025 study found AI adoption increased PR volume by 98% but also increased review time by 91%, with no company-level productivity gain — validating the DE pillar's focus on full-pipeline flow. See [Research Validation](./05-ref-01-research-validation.md). --- ## When Human Review Is the Bottleneck The Faros AI finding is the most practically important research result for the DE pillar: AI generates more output, but human review of that output takes 91% more time, eliminating the productivity gain. This is where most teams get stuck. The instinctive response — skip review to recover velocity — is the wrong response. It trades a pipeline problem for a governance failure. The correct response is to address why review takes longer, not whether to do it. **Why AI-generated output takes longer to review:** - "Almost right" output requires more scrutiny than clearly correct or clearly wrong output - Without a specification, reviewers must reconstruct intent from the code to verify it - Ambiguous acceptance criteria mean reviewers must use judgment on every PR, not verify against explicit criteria **The leverage point is the specification, not the reviewer:** | If review is slow because... | The solution is... | |-------------------------------|-------------------| | Reviewers are reconstructing intent from code | A higher-ICS spec — reviewers verify against criteria, not intent | | Acceptance criteria are ambiguous | Better Testability dimension in the ICS rubric | | Every PR requires expert judgment | More specific constraints that AI can test automatically | | Volume is overwhelming reviewers | Stage-appropriate automation: Stage 3+ with AAR ≥ 75% can sample-based review | **Tiered review by maturity stage:** | Stage | Review approach | When full review is triggered | |-------|-----------------|-------------------------------| | 1–2 | Every output reviewed | Always | | 3 | Sample-based review (every Nth delivery) | AAR drops below 75% for any cycle; new agent configuration; new spec domain | | 4 | Automated acceptance test as primary gate | Reasoning trace review; AAR drops below 85%; any Tier 2 escalation | **The AAR signal:** When AAR consistently exceeds 85%, the team has demonstrated enough alignment to rely more on automated acceptance tests and less on per-output human review. This is the legitimate path to review load reduction — earned through demonstrated alignment, not assumed in advance. --- ## Relationship to the Other Pillars - **CO feeds DE:** A constructed and reviewed output is the input to the delivery pipeline. - **DE feeds GO:** Deployed systems are what governance monitors. - **DE feeds DO:** Delivery telemetry and user signals reveal what the spec missed. - **GO can halt DE:** When governance detects critical alignment failure, delivery is paused until the issue is resolved. --- ## Summary | Principle | Practice | |-----------|----------| | Validation-gated | Delivery when acceptance criteria pass, not on schedule | | Observable | Every delivery includes telemetry and behavioral monitoring | | Atomic | All-or-nothing deployment with automatic rollback on failure | | Feedback-driven | Delivery signals feed back into the next DO cycle | | Gate-justified | Every gate in the pipeline must earn its place | Demonstration is the moment the loop becomes real: the specification either holds against the system, or it does not — and either outcome teaches the team something worth knowing. --- *→ [CO Pillar](./02-pillar-02-co-compose.md) — what DE depends on* *→ [GO Pillar](./02-pillar-04-go-governance.md) — what monitors DE* *→ [Roles](./03-practice-04-roles.md) — the Flow Steward role defined* *→ [Metrics](./03-practice-05-metrics.md) — Spec-to-Delivery Latency and related measures* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # GO — Govern *The Alignment Pillar* --- > *For the leader: The more autonomously your AI systems operate, the more explicitly > accountable you must be for what they do. Governance in DoCoDeGo is not a compliance > function — it is the active oversight that makes autonomous systems safe to run.* --- ## The Principle **Autonomy without accountability is catastrophe.** > **Governance is earned through the loop.** This is the third clause of the framework's core axiom: intent is the primary artifact; implementation is a compiled derivative; governance is how the organization remains accountable for both. > > *— [The Manifesto](./01-core-02-manifesto.md)* Governance in DoCoDeGo is earned through the loop, not imposed from the start. In its minimal form — "did this do what we said it would?" — governance is present at every stage. It formalizes as AI autonomy deepens. A team using AI for code suggestions needs light governance: review the output. A team running autonomous agents that deploy to production without human approval needs structured governance: confidence thresholds, scope limits, kill switches, audit trails, and drift detection. A 2-person startup should not be slowed down by governance infrastructure they don't need. An enterprise running autonomous agent fleets cannot operate without it. The framework applies to both. The practices are calibrated to the level of autonomy. --- ## The Durable Case for Governance The most common objection to the GO pillar: *"When AI gets better at understanding intent, won't governance become less necessary?"* The answer is no — and the reasons are structural, not contingent on any AI capability gap. **Reason 1: Legal and regulatory accountability does not diminish as AI improves.** When an AI-assisted output causes harm — a security breach, a deleted database, a discriminatory decision — the question of who is responsible does not become simpler as AI becomes more capable. The EU AI Act (full enforcement August 2026) and the EU Cyber Resilience Act require identifiable human accountability for AI-generated outputs that affect users. Governance is the mechanism by which that accountability is maintained. Regulators do not accept "the AI decided" as an answer. **Reason 2: AI cannot know what your organization has committed to.** Even a perfectly intent-inferring AI has no access to the organizational constraints, prior commitments, competing priorities, and strategic considerations that a human owner knows. Intent is not only about what you want to build — it is about what you should build given everything your organization has agreed to. That context requires a human steward. **Reason 3: Auditability is a permanent requirement.** The ability to answer "what was built, who approved it, why, and when?" is not a workaround for AI limitations. It is a requirement for institutional knowledge, incident response, regulatory compliance, and organizational trust. These requirements do not decrease as AI improves. If anything, the speed of AI-assisted output makes auditability more important, not less — the system changes faster and the audit trail becomes the only reliable record of what was decided. **Reason 4: Capability improvement increases, not decreases, the need for governance.** As AI agents become more autonomous, the consequences of misalignment grow. A more capable AI that is slightly misaligned with intent produces a more capable misaligned output. Governance scales with autonomy because the stakes scale with capability. This is why the maturity stage model exists: governance formalizes as capability increases. *The framework is not designed for the era of limited AI. It is designed for the era of capable AI — where the human role shifts entirely to stewardship, and stewardship requires structure.* --- ## Governance at Each Maturity Stage | Stage | AI autonomy level | Governance practices | |-------|-----------------|---------------------| | **1 — Augmented** | Human writes; AI assists | Manual code review. Output validation before merge. | | **2 — Collaborative** | AI constructs; human reviews | Automated acceptance tests. Deployment validation. Observability. | | **3 — Orchestrated** | Multi-agent workflows; human directs | Intent Reviews (weekly). Agent scope limits. Alignment checks. Escalation protocols. | | **4 — Autonomous** | Agents operate with minimal human input per cycle | Confidence thresholds. Kill switches. Reasoning trace audits. Drift detection. Provenance tracking. | You do not skip stages. You do not run Stage 4 governance on a Stage 1 team. --- ## What GO Requires ### 1. Intent Hardening Governance begins with the specification. A well-hardened spec is resistant to misinterpretation, scope creep, and adversarial or accidental deviation. Intent hardening means: - Acceptance criteria are explicit and binary (pass or fail, not "good enough") - Constraints are negative and specific ("shall not access user data outside session scope") - Scope boundaries are declared explicitly - The threat model addresses what happens when each constraint is violated A hardened specification is difficult to fulfill incorrectly by accident. ### 2. Bounded Autonomy Every agent in a DoCoDeGo system operates within explicit boundaries: - Scope: what the agent is permitted to act on - Permissions: what resources the agent can read, write, or execute - Confidence threshold: below what confidence level must the agent pause and escalate - Time limit: how long the agent may operate before requiring human acknowledgment These boundaries are not suggestions. They are enforced constraints. An agent that operates outside its declared boundaries is exhibiting drift — a governance event requiring investigation, not a feature. ### 3. Transparent Reasoning Every agent in a DoCoDeGo system must produce an auditable reasoning trace. No black boxes. This is not just a security requirement. It is the mechanism by which humans can govern what they cannot directly observe. When an agent's output is unexpected, the reasoning trace is how you determine whether: - The spec was unclear (return to DO) - The agent deviated from its reasoning (governance event) - The expected behavior was wrong (return to DO) Governance without transparent reasoning is theater. You cannot be accountable for what you cannot inspect. In the Replit/SaaStr incident (July 2025), an autonomous agent caused production harm and, without an auditable reasoning trace, there was no mechanism to determine whether the behavior was authorized by any specification or was purely agentic drift. The inability to answer "what did the agent decide and why?" made the accountability chain impossible to reconstruct. **External validation:** The 2025 Veracode GenAI Code Security Report found AI-generated code introduced security flaws in 45% of tests, with no improvement as models scaled — validating Statute 15's requirement for threat models. The Replit/SaaStr incident (July 2025) demonstrated autonomous agents causing production harm and denying it — precisely the governance failure this pillar prevents. Developer trust in AI tools fell to 60% in 2025 (Stack Overflow). See [Research Validation](./05-ref-01-research-validation.md). ### 4. The Governor Role Governance requires an owner: the Governor. The Governor is responsible for: - Running the weekly Intent Review (see [Intent Review](./03-practice-03-intent-review.md)) - Holding kill-switch authority - Monitoring Agent Alignment Rate - Escalating governance conflicts to human resolution - Maintaining the provenance record of what was built, when, and by which agent The Governor does not resolve governance conflicts autonomously. When two governance rules contradict — for example, a security requirement and a compliance deadline — the Governor escalates to human decision-makers with full context. Automated systems never resolve governance conflicts without human authorization. ### 5. Security by Design Security is not a governance add-on. It is embedded in every specification through the threat model. Every specification includes: - Top failure modes with recovery paths - Explicit access scope declarations (what this system may access) - Explicit data handling rules (what this system may store, transmit, or process) - Security constraints that are part of the acceptance criteria AI-generated code can introduce vulnerability patterns. The security review is not optional at any maturity stage. At Stage 1–2, this is a human code review step. At Stage 3–4, this includes automated security scanning as part of the delivery pipeline. ### 6. Accountability Chain When an autonomous agent causes harm — produces vulnerable code, deletes data, makes unauthorized changes — the accountability chain is clear: 1. The **Intent Architect** is accountable if the specification was unclear or incomplete 2. The **Composition Lead** is accountable if the architectural review missed the issue 3. The **Flow Steward** is accountable if delivery proceeded without passing validation 4. The **Governor** is accountable if governance oversight failed to detect the drift This chain is not about blame. It is about improvement. Clear accountability identifies where in the loop the failure occurred, so that loop can be strengthened. --- ## Governance Failure Modes ### Spec Misinterpretation The most common failure. Output is technically correct but misaligned with actual intent. Response: 1. Halt delivery 2. Surface the agent's reasoning trace 3. Identify the spec ambiguity that caused the deviation 4. Refine the specification 5. Regenerate This is not a bug to fix. It is a spec to improve. ### Telemetry Corruption Delivery metrics are inaccurate, causing the system to reinforce incorrect behavior. Response: 1. Cross-validate metrics against independent sources 2. Freeze spec updates until anomaly is explained 3. Verify the data pipeline before resuming ### Governance Conflict Two governance rules contradict. For example: security requirement vs. compliance deadline. Response: Escalate to human decision-maker with full context. **Governance conflicts must be resolved by a human with the authority to own the decision.** This is not a technical constraint — it is an accountability requirement. A conflict resolved by an automated system has no owner. No one can be held responsible for it, explain it, or be asked to justify it. Under any current regulatory or legal framework, that is not governance; it is the absence of governance. ### Partial Deployment A deployment fails mid-stream, leaving the system in inconsistent state. Response: 1. Automatic rollback to last known-good 2. No partial state accepted without explicit human authorization 3. Root cause investigation before retry --- ## Process Signals The six DoCoDeGo metrics (ICS, SDL, AAR, GTR, RC, DDL) are outcome metrics — they measure what happened. Governance also requires process signals: leading indicators that reveal whether the governance loop itself is functioning. These are not threshold metrics. They are observable conditions. A team that tracks them honestly will surface problems before they appear in the outcome metrics. | Signal | What it measures | Warning pattern | |--------|-----------------|----------------| | **Intent Review completion rate** | % of scheduled reviews actually held | < 90% over 4 weeks: governance is being skipped under pressure | | **Spec age at composition start** | Days between spec creation and composition begin | Increasing trend: specs are being written during or after composition begins | | **Escalation resolution time** | Days from GTR event to documented resolution | > 5 days: governance triggers are not being acted on | | **Stage gate dwell time** | Time since last stage gate assessment | > 8 weeks without reassessment at Stage 2+: the team is avoiding the advancement question | | **Metric ownership stability** | Whether the same person owns a metric and the behavior it measures | Flagged: creates structural incentive to game the metric | These signals belong in the weekly Intent Review as a standing check. A team that ignores process signals will see their outcome metrics degrade with a lag they could have prevented. --- ## The Anti-Surveillance Distinction Governance in DoCoDeGo is oversight of system behavior, not surveillance of engineers. The practices described here — reasoning traces, confidence thresholds, drift detection — apply to AI agents, not to human team members. A healthy governance culture asks "is the system aligned with our intent?" not "did the developer follow the process?" Teams that use governance to surveil their engineers rather than their systems have misunderstood the pillar. --- ## The Good Code Mark DoCoDeGo does not have certifications. It has the Good Code Mark. The name comes from the framework itself: DoCoDeGo is an anagram of Good Code. A team that earns the Good Code Mark is demonstrating exactly what the name says — that they write code that does what was intended, governed by the practices the framework defines. **The canonical definition of the Good Code Mark** — including complete gate criteria for all four stages, verification requirements, and the anti-commodification structure — is in [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md). **Summary:** - The Good Code Mark is tied directly to maturity stage gates - A team that meets the gate criteria for a given stage has earned the Mark at that stage - No standardized written exam. Assessment is through the **DoCoDeGo Practice Assessment**: a review of practice artifacts and a team walkthrough to confirm understanding. No accredited trainer, no renewal fee, no third-party issuing body. - For individuals: **Good Code Practitioner** recognition is earned through demonstrated contribution to a team's practice artifacts (see [Practitioner Training](./04-guide-04-practitioner-training.md)) If an organization creates a "Certified DoCoDeGo Master" or similar credential, they are operating outside the framework and should not use the name. --- ## Relationship to the Other Pillars - **DE feeds GO:** Deployed systems generate the signals that governance monitors. - **GO feeds DO:** Governance findings — drift, misalignment, unexpected behavior — refine the next specification. - **GO can halt DE:** Critical alignment failure pauses delivery until resolved. - **GO validates CO:** Post-deployment audit of composition outputs for architectural drift. --- ## Summary | Principle | Practice | |-----------|----------| | Earned, not imposed | Governance formalizes with AI autonomy, not with headcount | | Bounded autonomy | Every agent operates within explicit, enforced scope | | Transparent reasoning | Every agent produces auditable reasoning traces | | Security embedded | Threat model is part of every specification | | Human escalation | Governance conflicts require a human owner — accountability cannot be automated | Governance is not the last step in the loop — it is what makes the loop worth running. Without GO, the team produces output. With GO, the team produces output it can stand behind. --- *→ [DE Pillar](./02-pillar-03-de-delivery.md) — what GO monitors* *→ [Roles](./03-practice-04-roles.md) — the Governor role defined* *→ [Intent Review](./03-practice-03-intent-review.md) — the primary governance ritual* *→ [Metrics](./03-practice-05-metrics.md) — Agent Alignment Rate and Governance Trigger Rate* *→ [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md) — when governance formalizes* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # The Sixteen Statutes of Intent-Driven Engineering --- > *For the leader: These sixteen principles are the operating rules of DoCoDeGo. If your > team follows them, the framework is working. If they routinely violate them, something > in the adoption — process, culture, or tooling — needs to change. Use this list to > diagnose where.* --- ## The Statutes | # | Statute | Pillar | Principle | |---|---------|--------|-----------| | 1 | Intent Is Absolute | DO | Never exceed specification. Refine intent; do not patch symptoms. | | 2 | The Spec Is the Contract | DO | Every interaction begins with a structured, approved specification. | | 3 | Quality Through Context | DO | AI produces correct output when context is complete. Ambiguity causes defects. | | 4 | Simplicity of Spec | DO | Complexity in a specification signals unclear intent. Simplify before proceeding. | | 5 | Code Is Regenerable | CO | Preserve logic, not syntax. Regenerate from improved intent. | | 6 | Resilience Over Robustness | CO | Design for reconstruction. Rebuilding is safer than maintaining brittle systems. | | 7 | Architecture Before Generation | CO | The human defines system structure before agents begin. AI implements within the architecture, not instead of it. | | 8 | Comprehension Is Non-Negotiable | CO | If you cannot evaluate what was built, you cannot be accountable for it. | | 9 | Zero-Latency Evolution | DE | Changes demonstrate as fast as validation permits. No artificial delay. | | 10 | Feedback Closes the Loop | DE | Deployment telemetry informs the next specification cycle. | | 11 | Observability Is Non-Negotiable | DE | You cannot govern what you cannot see. Every demonstrated output includes telemetry. | | 12 | Atomic Delivery | DE | The unit of delivery is the specification: all or nothing. | | 13 | The Human as Governor | GO | Humans govern what AI produces. Primary skill: clarity of thought. | | 14 | Transparent Reasoning | GO | Every agent produces auditable reasoning traces. No black boxes. | | 15 | Security by Design | GO | Every specification includes a threat model. No exceptions. | | 16 | Alignment Before Demonstration | GO | No demonstration without governance validation at its required maturity level. | --- ## Statutes in Detail --- ## Document (DO) — Statutes 1–4 --- ### Statute 1 — Intent Is Absolute *Pillar: DO* **Principle:** When AI builds the wrong thing, the fix is never to patch the code. The fix is to refine the intent that generated it. **In practice:** - When a delivered output fails an acceptance criterion, return to the specification. Identify what the spec failed to express. Correct the spec. Regenerate. - "Hotfixing" AI-generated code without updating the spec creates hidden divergence between intent and implementation. This is technical debt of the most dangerous kind: debt that will reappear the next time the system is regenerated. - Exception: true production emergencies may require immediate code patches. These must be followed by a mandatory spec update within one cycle. **Becomes critical at:** Stage 1. This is the foundational discipline. --- ### Statute 2 — The Spec Is the Contract *Pillar: DO* **How this differs from Statute 1:** Statute 2 is a *precondition* — you must have an approved specification before composition begins. Statute 1 is a *response protocol* — when output is wrong, you fix the specification, not the output. Statute 2 governs the start of work; Statute 1 governs the response to failure. Both together create the spec-centric discipline that defines the DO pillar: begin with the spec, and return to the spec when anything goes wrong. **Principle:** Composition does not begin without an approved specification. Every agent interaction has a governing specification. **In practice:** - No task assigned to an AI agent without a corresponding spec section covering it. - The spec is the agreement between the Intent Architect (who defines what) and the Composition Lead (who directs how). When they disagree, the spec is the reference. - Verbal agreements, Slack messages, and meeting notes are not specs. They are inputs to spec writing. **In practice for small teams:** A "specification" for a small task may be a single paragraph with three acceptance criteria. The format scales with the complexity of the work. What does not scale down is the requirement to have it. **Becomes critical at:** Stage 1. The earliest discipline; everything else depends on it. --- ### Statute 3 — Quality Through Context *Pillar: DO* **Principle:** AI output quality is a function of context quality. Ambiguity in the specification becomes defects in the output. **In practice:** - When AI generates wrong output, the diagnostic question is: "What in the specification was ambiguous enough to produce this?" Not: "What is wrong with the AI?" - Context includes: the specification, examples of correct behavior, explicit constraints, and clear acceptance criteria. - The Intent Clarity Score measures context quality. A score below threshold predicts poor output before composition begins. - A payment service spec that uses "appropriate error handling" without defining retry behavior, idempotency, or timeout thresholds will reliably produce an implementation that double-charges on network failure — not because the AI is wrong, but because "appropriate" had no definition. **Becomes critical at:** Stage 1. This is why spec quality is the highest-leverage investment. --- ### Statute 4 — Simplicity of Spec *Pillar: DO* **Principle:** Complexity in a specification signals unclear intent. If you cannot express it simply, you do not understand it well enough to specify it. **In practice:** - Before adding complexity to a spec, ask: is this complexity in the problem, or is it complexity created by unclear thinking? - Complex acceptance criteria often indicate that the requirement is actually multiple requirements that need to be separated. - A simple spec is not a vague spec. It is a precise spec expressed at the right level of abstraction. - Spec debt accumulates when requirements are added without removing or simplifying existing requirements. Regular spec review is part of the DO cycle. - A ticket routing spec that conflates classification, assignment, and escalation into a single feature produces acceptance criteria that contradict each other and an AI composition that cannot satisfy them simultaneously. Separating the three into distinct specs — each simple and self-consistent — resolves the contradiction and produces composable outputs. **Becomes critical at:** Stage 1. Complexity in early specs creates compound difficulty in all subsequent stages. --- ## Compose (CO) — Statutes 5–8 --- ### Statute 5 — Code Is Regenerable *Pillar: CO* **Principle:** Code generated from a specification can be regenerated from an improved specification. The code is not the artifact. The specification is. **In practice:** - When a spec improves, the preferred response is regeneration — not manual editing of the generated code. - The corollary: if you cannot regenerate a system from its specification, the specification is incomplete. This is a DO failure, not a code quality problem. - System invariants (business rules, data contracts, API contracts) are NOT regenerable. They must be explicitly protected and require human review before any change. **What "regenerable" does not mean:** It does not mean disposable. Regeneration requires a complete, approved specification. It does not mean frequent. Regeneration is triggered by specification improvement, not by routine maintenance cycles. **Regeneration and production deployment:** Regenerating from an improved spec is permitted freely — that is the point of the statute. Before deploying any regenerated system to production, run the Regeneration Confidence (RC) checklist. The checklist verifies behavioral equivalence: that the regenerated system passes all original acceptance tests, matches performance within tolerance, introduces no new security findings, and preserves integration contracts. Statute 5 permits regeneration; RC governs whether the regenerated output reaches production. See [Metrics](./03-practice-05-metrics.md) for the RC checklist. **Becomes critical at:** Stage 2. When agents begin constructing larger systems, the discipline of preserving spec-as-source becomes essential. --- ### Statute 6 — Resilience Over Robustness *Pillar: CO* **Principle:** Design systems that can be rebuilt, not systems that cannot fail. **In practice:** - A system designed for resilience has clear specifications that allow reconstruction if it fails catastrophically. - A system designed for robustness has defensive code that tries to handle every failure mode, creating complexity that AI struggles to reason about. - In AI-era composition: prefer clear, simple systems with good specifications over complex, defensive systems with poor specifications. - When a system fails, the expected recovery path is: identify the spec gap, update the spec, regenerate the affected components. - A legacy payment processor with 4,000 lines of defensive error-handling code took weeks to safely modify because no one could trace which edge cases each branch handled. A replacement built from a clear spec with explicit failure modes was regenerated from scratch in a single composition cycle and passed all characterization tests. The robust system resisted change; the resilient one welcomed it. **Becomes critical at:** Stage 2. When systems begin serving real users, the failure-recovery path becomes important. --- ### Statute 7 — Architecture Before Generation *Pillar: CO* **Principle:** The human defines the system structure before agents begin. AI implements within the architecture, not instead of it. **In practice:** - Before any agent is assigned a composition task, the Composition Lead defines: overall system structure, component boundaries, integration points, and non-negotiable constraints. - Agents given architectural freedom will make architectural choices. Those choices accumulate into systems the human cannot understand or own. - The Composition Lead's sign-off on architecture is not a checkpoint — it is a precondition. No composition begins until the architecture is declared. **Becomes critical at:** Stage 2. When agents begin building larger systems, unguided architectural choices compound quickly. --- ### Statute 8 — Comprehension Is Non-Negotiable *Pillar: CO* **Principle:** If you cannot evaluate what was built, you cannot be accountable for it. Technical depth is a governance requirement, not a personal preference. **In practice:** - Composition Leads with architectural review responsibility maintain hands-on implementation skills through regular practice separate from production work. - Monthly: build something small without AI assistance. Quarterly: conduct a full architectural review of a system you did not spec. - A reviewer who rubber-stamps AI output without comprehension has not fulfilled the CO role — they have abandoned it. Accountability without comprehension is not accountability; it is rubber-stamping. **Becomes critical at:** Stage 2. When AI constructs the majority of the output, comprehension is the last line of defense against undetected architectural drift. --- ## Demonstrate (DE) — Statutes 9–12 --- ### Statute 9 — Zero-Latency Evolution *Pillar: DE* **Principle:** Changes demonstrate as fast as validation permits. Every delay beyond what validation requires is waste. **In practice:** - After composition, the next step is validation and demonstration — not a scheduled review, not a fixed release window, not a process gate that doesn't reduce real risk. - "Demonstrate as fast as validation permits" means that improving validation speed is a legitimate investment. A faster test suite directly reduces demonstration latency. - Zero-latency does not mean reckless. The gate is validation confidence, not the absence of gates. **Becomes critical at:** Stage 2. Continuous demonstration practices require this discipline to be explicit. --- ### Statute 10 — Feedback Closes the Loop *Pillar: DE* **Principle:** Every demonstration cycle generates information. That information must return to the DO phase to improve the next specification. **In practice:** - The Flow Steward is responsible for aggregating demonstration telemetry and flagging behavioral drift from spec. - After each demonstration cycle, the question is: what did we learn that should change the specification? - Feedback is not complaint. It is data: "the system did X when the spec said it should do Y." That is a DO input. - Feedback that is not fed back into DO is waste. It represents learning that will be repeated as a mistake. **Becomes critical at:** Stage 2. Continuous demonstration without feedback produces continuous drift. --- ### Statute 11 — Observability Is Non-Negotiable *Pillar: DE* **Principle:** You cannot govern what you cannot see. Every demonstrated output includes telemetry from the moment of demonstration. **In practice:** - Every demonstration includes: acceptance test results, performance telemetry, error rate monitoring, and behavioral drift indicators. - Observability is not an add-on. It is part of the specification. Every acceptance criterion has a corresponding observable metric. - A system that cannot be observed cannot be governed. Demonstration without observability is not demonstration — it is release into the unknown. **Becomes critical at:** Stage 2. Continuous demonstration without visibility produces continuous drift with no signal. --- ### Statute 12 — Atomic Delivery *Pillar: DE* **Principle:** Partial state is the enemy of continuous demonstration. The unit of delivery is the specification: all or nothing. **In practice:** - A single demonstrated delivery corresponds to one approved specification, fully implemented and validated. - Multiple specifications may not be bundled into a single delivery unit — each spec's demonstration must be independently validated. - When demonstration fails mid-stream, automatic rollback to last known-good state. No partial state is accepted without explicit human authorization. **Becomes critical at:** Stage 2. When delivery is frequent, partial state failures become costly to recover from and difficult to reason about. --- ## Govern (GO) — Statutes 13–16 --- ### Statute 13 — The Human as Governor *Pillar: GO* **Principle:** In an AI-era team, the human's primary contribution shifts from implementation to stewardship. Clarity of thought is the scarce resource. **In practice:** - The most valuable thing a human brings to an AI-era team is the judgment to decide what to build, the clarity to specify it precisely, and the accountability to own the consequences. - "Stewardship" means: responsible for the long-term alignment of what the system does with what the system was intended to do. - This does not mean humans stop coding. It means coding is not the primary measure of value. **On skill maintenance:** Stewardship requires technical depth. Engineers who no longer practice implementation skills lose the calibration needed to evaluate AI-generated outputs. The framework recommends regular hands-on practice separate from production work. A Composition Lead who signs off on AI-generated authentication code without reading it is not governing — they are rubber-stamping. When a security audit later finds that the generated code lacks session expiry, the sign-off on the record is their name, not the agent's. **Becomes critical at:** Stage 1. This is a values shift, not a technical one. --- ### Statute 14 — Transparent Reasoning *Pillar: GO* **Principle:** Every agent produces an auditable reasoning trace. No black boxes. **In practice:** - When an agent's output is unexpected, the first step is examining the reasoning trace — not re-running the agent with a different prompt. - Agents that cannot produce reasoning traces should not be assigned autonomous tasks. - Reasoning traces are reviewed during the Intent Review (see [Intent Review](./03-practice-03-intent-review.md)). - Traces are stored and retrievable for governance audits. **Why this matters:** Without transparent reasoning, governance is reactive — you see the output but not the process. Transparent reasoning makes governance preventive: you can identify misalignment in the reasoning before the output causes harm. **Becomes critical at:** Stage 3. At Stage 3+, agents are operating with meaningful autonomy. Opaque reasoning is a governance failure at this stage. --- ### Statute 15 — Security by Design *Pillar: GO* **Principle:** Every specification includes a threat model. Security is part of intent, not an afterthought. **In practice:** - Every spec has a Threat Model section with: top failure modes, their consequences, and recovery paths. This is not optional. - Security acceptance criteria are part of the spec and must pass before demonstration. - At Stage 1–2: a human security review of composition outputs. - At Stage 3–4: automated security scanning is mandatory in the demonstration pipeline. - The threat model addresses what happens when this system is used incorrectly, attacked, or fails. **What "security by design" prevents:** The common failure mode where security is reviewed after composition and found wanting — requiring rework that could have been avoided with a threat model at the spec stage. **Becomes critical at:** Stage 1. A spec without a threat model is incomplete. --- ### Statute 16 — Alignment Before Demonstration *Pillar: GO* **Principle:** Demonstration does not proceed when governance validation has not cleared the output at the current maturity level's required depth. **In practice:** - At Stage 1–2: acceptance tests pass, manual review complete. - At Stage 3: acceptance tests pass, alignment check complete, no governance flags. - At Stage 4: acceptance tests pass, confidence threshold met, reasoning trace reviewed, no drift indicators. - Governance does not clear demonstration by default. Demonstration clears demonstration by meeting the criteria set by governance. **The distinction:** This is not governance-as-gate. Governance does not slow demonstration by checking boxes. It defines the criteria that define "ready." Meeting those criteria is the demonstration pipeline's job. **Becomes critical at:** Stage 2. When demonstration is continuous, alignment checks must be part of the pipeline. --- ## By Pillar | Pillar | Statutes | Theme | |--------|----------|-------| | **DO** | 1–4 | Intent first, clarity always | | **CO** | 5–8 | Compose with integrity; own the architecture | | **DE** | 9–12 | Flow and feedback, observed and atomic | | **GO** | 13–16 | Accountable autonomy | --- ## Common Violation Patterns Each statute has a characteristic failure mode that surfaces in practice. The following patterns are the most frequently observed — use this list as a diagnostic when the framework is in place but not producing the expected results. | Statute | Most common violation | |---------|-----------------------| | 1 | Hotfixing AI output without updating the spec | | 2 | Starting composition from a verbal brief | | 3 | Blaming the AI model when the spec was the problem | | 4 | Adding requirements without reviewing whether existing ones still apply | | 5 | Manually editing generated code "just this once" | | 6 | Adding defensive code to handle cases not in the spec | | 7 | Letting agents begin without a declared system architecture | | 8 | Approving AI output without reading and understanding it | | 9 | Keeping a fixed release day after removing the need for one | | 10 | Reading demonstration metrics without asking what they mean for the spec | | 11 | Treating observability as an optional add-on after demonstration | | 12 | Bundling multiple spec outputs into a single delivery unit | | 13 | Measuring engineers by lines of code reviewed | | 14 | Accepting agent output without checking the reasoning trace | | 15 | Starting spec writing without a threat model section | | 16 | Merging a demonstration that skipped an alignment check "just this once" | Each violation in this table is a point where accountability slips. The statutes exist to make that slip visible before it compounds. --- *→ [Spec Template](./03-practice-02-spec-template.md) — how to write specs that honor these statutes* *→ [Anti-Patterns](./04-guide-01-anti-patterns.md) — what violations look like at the team level* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # The DoCoDeGo Specification Template *The day-one artifact. The brief an AI agent can act on.* --- > *For the leader: This is the document your team writes before any AI agent touches a > keyboard. Its quality directly determines the quality of everything that follows.* --- ## Why This Template Exists In DoCoDeGo, the specification is not documentation — it is the primary artifact from which implementation is compiled. If requirements are vague, AI will implement a plausible interpretation that satisfies the letter of what was written, not the actual intent. If acceptance criteria are untestable, there is no way to determine whether the output is correct before it reaches production. If the threat model is absent, security and failure-recovery are afterthoughts rather than design inputs. This template enforces the structure that prevents those outcomes. A spec scored at ICS ≥ 60 against this rubric is one that can be handed to an AI agent and evaluated against a defined standard. A spec that falls short of that threshold is a prediction: the output will require more correction time than starting from a better spec. --- ## Spec Complexity Modes The template supports two operating modes: | Mode | When to use | Sections to populate | |------|-------------|---------------------| | **Simple Spec** | Single action, no branching, single layer, single role, no external integrations | Intent + Constraints + Acceptance Criteria + Edge Cases + Threat Model + Out of Scope. All optional sections declared inapplicable. | | **Full Spec** | Multiple steps, branching, stateful entities, multiple roles, multi-layer, or cross-domain | All sections whose triggering conditions are met. Declared omission for the rest. | **The trigger for Full Spec:** If a feature needs a Behavioral Flow, it is a Full Spec. If not, it is a Simple Spec. **Stage 1 guidance:** Teams new to DoCoDeGo should default to Simple Spec. The Full Spec mode becomes natural once the team is comfortable with the Simple Spec rhythm. --- ## The Template Copy this template for every new specification. Required sections are marked. Optional sections are included when their triggering condition is met. ```markdown --- id: [unique identifier, e.g. SPEC-2026-042] version: 1.0.0 created: [YYYY-MM-DD] owner: [Intent Architect name] status: draft roles: [list defined roles, if applicable] --- # [System or Feature Name] ## Intent [One paragraph. What is this for? What problem does it solve for the people who depend on it? Write for a competent colleague who has never seen this system. No implementation details. No technical jargon unless the domain requires it.] ## Integration Map **Triggering condition:** Required when the feature calls an external system, consumes an event, or writes to a system outside its own domain. [Table of external dependencies:] | System | Interaction Type | When Called | What Happens If Unavailable | |--------|-----------------|-------------|------------------------------| | [system name] | [read/write/event] | [trigger condition] | [failure behavior] | **Declaring inapplicable:** If this feature has no external integrations, state: "No external integrations." ## Behavioral Flow **Triggering condition:** Required when the feature involves multiple steps, user decisions, or branching paths. [The sequence of steps and branching paths. Can be narrative, bulleted, or diagrammatic. Each step should name its actor explicitly: `[Actor] → action → outcome`] **Multi-actor scenarios:** Where actor handoffs occur (e.g., User submits → System validates → Admin is notified), mark the handoff point explicitly as a step. **Declaring inapplicable:** If this feature is a single action with no branching, state: "Single-action feature; no flow needed." ## State Machine **Triggering condition:** Required when the feature involves entities that have a lifecycle — orders, tasks, approvals, subscriptions, user accounts, tickets, bookings, content items. [Table or enumeration of states and transitions:] | From State | To State | Trigger | Guard Condition | |------------|----------|---------|-----------------| | [state] | [state] | [event] | [condition, if any] | **Declaring inapplicable:** If this feature has no stateful entities, state: "No stateful entities." ## Business Rules **Triggering condition:** Required when behavior differs based on combinations of conditions — pricing, eligibility, permissions, routing, classification, approval workflows. [Conditional logic that governs behavior:] - **Rule [name]:** IF [condition 1] AND [condition 2] AND [condition n] THEN [outcome] - **Rule [name]:** IF [condition] THEN [outcome] **Declaring inapplicable:** If behavior is unconditional, state: "No conditional business rules." ## Permission Model **Triggering condition:** Required when the feature has multiple user types, or some users can do things others cannot. [Table of roles and permissions:] | Role | Actions Permitted | Actions Denied | Visibility Constraints | |------|------------------|----------------|----------------------| | [role] | [actions] | [actions] | [what they can/cannot see] | **Declaring inapplicable:** If all users have the same capabilities, state: "Single role; no permission model needed." ## Constraints [Bullet list. Each item must be independently testable — binary pass or fail. Constraints define what must be true and what must not happen.] - The system must [specific, measurable requirement] - The system must not [specific prohibition] - Response time must not exceed [specific threshold] under [specific load condition] - [Continue as needed — no minimum, no maximum] **Constraint vs. CO decision:** - A **constraint** is non-negotiable — the AI cannot change it. Include technology choices and API paths that are pre-agreed or existing contracts. - A **CO decision** is an implementation choice — the AI should determine it from context. Do not include open technology decisions or new endpoint design. - **Default rule:** If changing it requires a stakeholder decision (not just a technical decision), it is a constraint. ## Acceptance Criteria [Binary pass/fail checklist. Every criterion must be automatable or manually verifiable. If you cannot write a test for it, it does not belong here.] - [ ] [Criterion 1: specific, measurable, unambiguous] - [ ] [Criterion 2] - [ ] [Criterion 3 — include at least one negative criterion: "does not X when Y"] **Traceability:** Acceptance criteria should map to flow steps and business rule conditions. A criterion that cannot be traced to a flow step may be testing the wrong thing. ## Edge Cases **Triggering condition:** Recommended for all features. Every feature has edge cases. [Non-adversarial failure scenarios — operational situations that require defined behavior:] | Scenario | Expected Behavior | Test Signal | |----------|------------------|-------------| | [what happens] | [what system must do] | [how this is verified] | **Examples:** empty states, boundary conditions, concurrent access, partial failures, invalid inputs, integration timeouts, duplicate submissions. ## Threat Model For each failure mode, name: what goes wrong, who or what causes it, what the consequence is, and how the system or team recovers. Minimum three failure modes. A threat model that cannot name three failure modes is a sign the spec is not yet understood well enough to build. **Focus:** This section covers security and adversarial failures. Operational edge cases belong in Edge Cases above. **Categories to consider:** incorrect or malicious inputs, system or dependency failures, adversarial use, data integrity issues, performance boundary violations, unauthorized access. ### Failure Mode 1: [Name] **What happens:** [Description of the failure and its trigger] **Source:** [Incorrect input / system failure / adversarial action / data issue / other] **Consequence:** [Impact on users, data, or system] **Recovery:** [How the system responds automatically, and what human action is required] ### Failure Mode 2: [Name] **What happens:** **Consequence:** **Recovery:** ### Failure Mode 3: [Name] **What happens:** **Consequence:** **Recovery:** ## Out of Scope [Explicit list of what this specification does NOT cover. This is as important as what it does cover. Forces clarity about boundaries.] - This specification does not address [specific capability or scenario] - [Continue as needed] ## Related Specifications [Links to specifications this one depends on or affects.] - [SPEC-ID: Name](link) — [brief description of relationship] ``` --- ## The Declared Omission Rule **Silence is not omission. Omission must be declared.** When an optional section's triggering condition is not met, the Intent Architect must explicitly state why the section is inapplicable. This prevents accidental gaps from being mistaken for deliberate ones. **Example declarations:** - "No external integrations." - "Single-action feature; no flow needed." - "No stateful entities." - "No conditional business rules." - "Single role; no permission model needed." --- ## Intent Clarity Score (ICS) Rubric Before composition begins, score the specification. Score below 60 requires refinement. | Dimension | 0 | 12–13 | 25 | Weight | |-----------|---|-------|----|--------| | **Completeness** | Missing sections | Most sections present | All required sections complete; optional sections included where triggering conditions are met or declared inapplicable | /25 | | **Testability** | Few/no testable criteria | Most criteria testable | All criteria independently testable; criteria trace to flow steps and business rules | /25 | | **Unambiguity** | Multiple vague qualifiers | Some ambiguity | No ambiguous terms; business rules and permissions fully defined | /25 | | **Threat Coverage** | No threat model | Threat model present but incomplete | 3+ failure modes with recovery paths; edge cases addressed | /25 | **Threshold:** ICS ≥ 60 required before CO begins. ICS < 40 means the spec is not ready for review. **Threat Coverage floor:** A Threat Coverage dimension score below 15 (out of 25) fails the gate regardless of the composite ICS score. A spec that is otherwise complete, testable, and unambiguous but has an inadequate threat model is not safe to build from. This floor cannot be compensated by high scores in other dimensions. **Inter-rater consistency:** ICS is most reliable when scored by two or more reviewers independently, then compared. Significant disagreement (> 10 points per dimension) indicates the spec is genuinely ambiguous and must be revised — the disagreement is the signal, not a problem to average away. When a single reviewer must score alone, they should score conservatively: if in doubt between two bands, score the lower one. The spec can always be improved; a false pass cannot be undone after composition begins. **Scoring anchors by dimension:** | Dimension | Low (0–10) | Mid (11–20) | High (21–25) | |-----------|-----------|------------|-------------| | **Completeness** | Multiple required sections missing or empty; optional sections needed but absent | Most sections present; one or two thin; some missing declarations | All sections complete; optional sections present or declared inapplicable; no placeholder content | | **Testability** | Criteria use unmeasurable language ("fast", "good") | Most criteria testable; one or two vague | Every criterion independently verifiable; traces to flow steps and rules | | **Unambiguity** | Multiple undefined terms; reader must guess | Some qualified language remains | No term requires inference; rules and permissions explicit | | **Threat Coverage** | No threat model | Threat model present but fewer than 3 failure modes | 3+ failure modes named with recovery; edge cases covered | **Ambiguous qualifiers to avoid:** fast, slow, good, user-friendly, intuitive, reasonable, appropriate, high-quality, robust, scalable (without a specific target), secure (without specific requirements), efficient (without measurement). --- ## Spec Hierarchy for Large Projects For products with multiple implementation layers, teams, or complex features, use the three-level hierarchy: ### Level 1: Product Context (one per product) **Purpose:** Establish shared constraints and intent across all specs. **Contains:** - Product mission - Cross-cutting constraints (data residency, accessibility, security posture, regulatory) - Scope boundary - Defined roles and user types - Shared glossary reference **File naming:** `[product-name]-context.md` **Not ICS-scored.** This is parent context, not a composition input. ### Level 2: Domain Spec (one per behavioral capability) **Purpose:** Define what a behavioral capability does — independent of implementation layer. **Contains:** Full enhanced spec template (Intent, optional sections, Constraints, Acceptance Criteria, Edge Cases, Threat Model). **Key principle:** Domain specs are layer-agnostic. All layers that implement this capability reference this spec. **ICS scored at this level.** ICS ≥ 60 means behavior is clear enough to implement. **Decomposition signal:** Split if: - Cannot be reviewed in one sitting - Covers more than one coherent user capability - Acceptance criteria exceed ~15–20 items - Entities have unrelated lifecycles **File naming:** `[product-name]-domain-[capability].md` ### Level 3: Component Spec (one per layer per domain) **Purpose:** Define what a specific implementation layer must do to fulfill a domain spec. **Contains:** - Reference to parent domain spec (inherits intent, rules, acceptance criteria) - Layer-specific constraints - Layer-specific acceptance criteria (additions, not replacements) - Layer-specific threat considerations **Does not contain:** Business rules, flows, state machines — these live in domain spec. **ICS scored at this level.** This score gates composition. **File naming:** `[product-name]-domain-[capability]-[layer].md` ### Hierarchy Visualization ``` Product Context (1) │ Cross-cutting constraints, roles, glossary │ ├── Release Scope: MVP (optional) │ └── In scope: Authentication, User Profile │ ├── Domain Spec: Authentication [ICS scored] │ ├── Component Spec: API [ICS scored, composition input] │ ├── Component Spec: Frontend [ICS scored, composition input] │ └── Component Spec: Mobile [ICS scored, composition input] │ └── Domain Spec: User Profile [ICS scored] ├── Component Spec: API [ICS scored, composition input] └── Component Spec: Frontend [ICS scored, composition input] ``` **Simplicity principle:** Use minimum hierarchy depth needed. Small projects may need only domain specs. **Release Scope (optional):** When delivering multiple domain specs as a coordinated increment, a Release Scope document can list which domain specs are in scope, release-level constraints, and rollback criteria. It is not ICS-scored and is not a composition input — it is an organizational wrapper for teams that need one. See [Glossary: Release Scope](./05-ref-03-glossary.md) for the full definition. --- ## What a Bad Spec Looks Like **Example of a spec that will fail:** ```markdown ## Intent Build a ticket routing system that routes tickets to the right team. ## Constraints - Should be fast - Should route correctly - Users should like it ## Acceptance Criteria - [ ] Routes tickets - [ ] Works well ## Threat Model [empty] ## Out of Scope [empty] ``` **Why it fails:** - "The right team" is undefined — the agent cannot determine what "right" means - "Fast" and "works well" are not testable - No acceptance criteria are binary pass/fail - No threat model - No scope boundaries - Optional sections not declared An AI agent given this spec will make assumptions about every undefined aspect. Those assumptions will be wrong in ways that are expensive to discover after composition. --- ## What a Good Spec Looks Like ```markdown --- id: SPEC-2026-001 version: 1.0.0 created: 2026-02-21 owner: Harshad Patil status: approved roles: [Customer, Support Agent, Routing System] --- # Customer Support Ticket Routing System ## Intent When a customer submits a support ticket, the system classifies it by issue type and assigns it to the team with responsibility for that issue type. The goal is to eliminate manual triage — tickets should reach the correct team without a human routing step. This system handles new ticket intake only; it does not manage ticket lifecycle after assignment. ## Integration Map | System | Interaction Type | When Called | What Happens If Unavailable | |--------|-----------------|-------------|------------------------------| | ticketing-platform | write | after classification | Queue for retry; alert ops if queue > 100 | | ml-classification-service | read | on ticket receipt | Route to General team | ## Behavioral Flow 1. [Customer] → submits ticket via web form → ticket created in system 2. [System] → extracts text and metadata → sends to classification service 3. [System] → receives classification + confidence score → evaluates threshold 4. [System] → IF confidence ≥ 70%: assigns to classified team; ELSE: assigns to General 5. [System] → logs decision with reasoning → writes to ticketing platform ## State Machine N/A — tickets are not stateful in this system. State management belongs to ticketing-platform. ## Business Rules - **Confidence Threshold:** IF classification confidence < 70% THEN route to General team - **Team Mapping:** IF classification = "billing" THEN team = Billing; IF "technical" THEN Technical; etc. ## Permission Model | Role | Actions Permitted | Actions Denied | Visibility | |------|------------------|----------------|------------| | Customer | Submit tickets | Override classification | Own tickets only | | Support Agent | View assigned tickets | Re-classify | Team's tickets only | | Routing System | Classify and assign | Modify ticket content | All tickets | ## Constraints - The system must classify each incoming ticket within 2 seconds of receipt - The system must assign tickets to one of five defined teams: Billing, Technical, Returns, Account Access, General - The system must not modify any ticket content - The system must not assign tickets to teams not on the approved list - Classification confidence below 70% must trigger escalation to the General team, not a random assignment - The system must log every classification decision with the reasoning that produced it ## Acceptance Criteria - [ ] 95% of tickets in a 500-ticket validation set are assigned to the correct team (correct = matches expert human triage of the same set) - [ ] No ticket takes longer than 2 seconds to classify from receipt to assignment - [ ] All classification decisions are retrievable with their reasoning for 90 days - [ ] Low-confidence tickets (< 70%) are routed to General, not discarded - [ ] The system produces no assignments to teams outside the approved five ## Edge Cases | Scenario | Expected Behavior | Test Signal | |----------|------------------|-------------| | Classification service timeout | Route to General; log timeout | Timeout log entry; General assignment | | Duplicate ticket submission | Idempotent — no re-classification | Same ticket ID; one classification | | Empty ticket body | Route to General | General assignment; empty-body flag in log | ## Threat Model ### Failure Mode 1: Confidence Degradation **What happens:** Model confidence drops over time as ticket language evolves, causing increasing misclassification. **Source:** Data drift **Consequence:** Tickets assigned to wrong teams; customer experience degrades. **Recovery:** Governance monitoring detects when 7-day rolling accuracy falls below 90%. Triggers manual review, spec update, and system regeneration. ### Failure Mode 2: Category Exhaustion **What happens:** A ticket type appears that does not match any of the five defined teams. **Source:** Product evolution **Consequence:** System attempts to force-fit to the closest match. **Recovery:** Low-confidence routing to General prevents wrong assignment. Weekly review of General-routed tickets identifies new category candidates. ### Failure Mode 3: Logging Failure **What happens:** Classification logging system fails while ticket routing continues. **Source:** System failure **Consequence:** Decisions are made without audit trail; governance is blind. **Recovery:** Delivery pipeline includes logging validation. If logging test fails, delivery halts until resolved. ## Out of Scope - Ticket lifecycle management after assignment (escalation, resolution, closure) - Multi-language support - Integration with any ticketing system other than the internal platform - Handling of tickets submitted through channels other than the web form ## Related Specifications - [SPEC-2026-000: Authentication and Authorization](../examples/greenfield/notification-preference-service/spec-notification-service.md) — example specification demonstrating the format ``` --- ## Versioning a Specification Specifications change. Use semantic versioning: - **Patch version** (1.0.0 → 1.0.1): Clarification of existing requirements. No new acceptance criteria. - **Minor version** (1.0.0 → 1.1.0): New acceptance criteria or constraints added. Triggers re-validation of existing composition. - **Major version** (1.0.0 → 2.0.0): Intent change. Existing composition may need full regeneration. Every version change requires the owner to review whether existing composition still satisfies the updated spec. If not, a CO cycle is triggered. --- ## Spec Status Lifecycle ``` draft → review → approved → [active] → deprecated ↓ (composition begins) ``` - **draft**: Being written. Not ready for review. - **review**: Complete. Under review by stakeholders. - **approved**: Accepted. Composition may begin. - **deprecated**: Superseded by a newer version or removed from scope. **Transition triggers:** | Transition | Required condition | |------------|-------------------| | draft → review | All required sections complete; optional sections present or declared; no placeholder content remaining | | review → approved | ICS ≥ 60; all reviewers have signed off; no open ambiguity items | | approved → deprecated | A newer version of this spec is approved, or the feature is removed from scope; any active composition is halted or completed before deprecation | | Any state → draft | Substantive change to intent, constraints, or acceptance criteria that invalidates the current review — restart the review process | A spec in **review** state must not remain there indefinitely. If review is blocked, the blocker is a governance item for the Intent Review. The lifecycle exists because a specification that is never approved, or never deprecated when superseded, is a spec that no one owns — and unowned intent is where misalignment starts. --- *→ [DO Pillar](./02-pillar-01-do-documentation.md) — the principles behind this template* *→ [Metrics](./03-practice-05-metrics.md) — the Intent Clarity Score defined fully* *→ [Anti-Patterns](./04-guide-01-anti-patterns.md) — what happens when this template is misused* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # DoCoDeGo Roles *Who does what, at what team size.* --- > *For the leader: These four roles describe how human responsibility is distributed > in a DoCoDeGo team. In small teams, one person holds multiple roles. In large teams, > roles may be full-time specializations. The roles do not require new hires — > they describe a reorientation of what existing people focus on.* --- ## Overview When AI handles implementation, the most dangerous failure is not bad code — it is unclear human accountability. If no one owns the specification, intent drifts. If no one owns the architecture, AI fills the gaps with assumptions. If no one owns the governance loop, drift goes undetected until it surfaces as an incident. DoCoDeGo defines exactly four roles — one accountability per pillar. No additional roles are required by the framework. Organizations that create additional required roles ("DoCoDeGo Coach", "Alignment Engineer", "Intent Facilitator") are operating outside the framework. | Role | Pillar | Primary accountability | Scales to | |------|--------|----------------------|-----------| | **Intent Architect** | DO | Specification quality | 1 per system or feature stream | | **Composition Lead** | CO | Architectural soundness of AI-generated outputs | 1 per agent team | | **Flow Steward** | DE | Delivery pipeline and delivery health | 1 per team | | **Governor** | GO | Alignment and oversight | 1 per team; may overlap with Intent Architect | --- ## Intent Architect **The human accountable for what was decided to be built.** The Intent Architect owns the specification. They are accountable for writing intent precisely enough that the decision is traceable, testable, and owned — regardless of who or what constructs from it. ### Responsibilities - Write and maintain specifications for their domain - **Lead flow definition (Phase A) for non-trivial features** — facilitate team agreement on behavioral flows before spec writing begins - Approve specifications before composition begins (Intent Clarity Score gate) - Escalate to stakeholders when intent cannot be clarified in a spec - Update specifications when GO or DE reveal misalignment - Own the drift log from Intent Reviews - **Own spec hierarchy decisions** — determine when to use Product Context, Domain Specs, and Component Specs ### What they are NOT accountable for - How the AI constructs the system (that is the Composition Lead's domain) - Whether delivery happens on time (that is the Flow Steward's domain) - Agent behavior during deployment (that is the Governor's domain) ### When the Intent Architect is accountable When the AI builds something technically correct but wrong — the spec expressed something different from what was actually needed. This is the most common failure mode. Accountability here is not blame: it is the incentive structure that drives better specs. ### Who fills this role Not necessarily a developer. The Intent Architect must understand the domain well enough to write precise requirements. This may be a product manager, domain expert, technical lead, or developer — depending on the system and organization. What matters is clarity, not job title. **When the Intent Architect is non-technical:** The Threat Coverage dimension of the ICS rubric (failure modes and recovery paths) requires security and systems judgment. If the Intent Architect does not have that background, the reviewing team should include someone who does — the Composition Lead or a security-aware team member — to score the Threat Coverage dimension. The Intent Architect still owns the specification; the threat model scoring is a shared review responsibility, not an escalation. ### Team size guidance | Team size | Configuration | |-----------|--------------| | 1–2 people | Intent Architect = everyone who writes specs (all of them) | | 3–10 people | One or two people specialize in this role | | 10+ people | Dedicated Intent Architects per feature stream or domain | --- ## Composition Lead **The human accountable for the architectural soundness of what was built.** The Composition Lead directs the AI composition process and owns the architectural quality of what is built. They do not write all the code — but they are the person who can be asked "why was it built this way?" and must be able to answer. ### Responsibilities - Define the system architecture before composition begins - Configure and orchestrate AI agent teams - Review generated outputs for architectural soundness and constraint compliance - Escalate spec gaps discovered during composition back to the Intent Architect - Maintain hands-on technical practice to preserve calibration (monthly minimum) ### What they are NOT accountable for - The clarity of the specification (that is the Intent Architect's domain) - The delivery pipeline (that is the Flow Steward's domain) - Post-deployment behavior (that is the Governor's domain) ### When the Composition Lead is accountable When a generated output passes spec review but introduces architectural problems — technical debt, brittle integrations, performance constraints not anticipated by the spec. These are composition-phase failures. ### Hands-on technical practice The Composition Lead must maintain the technical depth to own AI-generated outputs. You cannot be accountable for something you do not understand. This requires regular practice outside of production work: - **Monthly:** Build something small from scratch without AI assistance - **Quarterly:** Review a system they did not spec, from scratch This is not optional. A Composition Lead who cannot evaluate generated code cannot sign off on it with integrity — and a sign-off without integrity is not governance. ### Team size guidance | Team size | Configuration | |-----------|--------------| | 1–2 people | Composition Lead = whoever reviews AI output | | 3–10 people | One person specializes, especially for architectural decisions | | 10+ people | Composition Lead per agent team or workstream | --- ## Flow Steward **The human accountable for whether value reached production safely.** The Flow Steward owns the delivery pipeline. They ensure that value flows at the speed of validation — that gates exist for real reasons and that telemetry flows back to improve the next specification cycle. ### Responsibilities - Own the delivery pipeline from composition approval to deployment - Define and maintain validation thresholds - Monitor Spec-to-Delivery Latency - Aggregate delivery telemetry and flag behavioral drift - Ensure feedback from deployment reaches the Intent Architect - Identify artificial gates (gates that do not reduce real risk) and propose removal ### What they are NOT accountable for - Specification quality (that is the Intent Architect's domain) - Composition quality (that is the Composition Lead's domain) - Post-deployment governance (that is the Governor's domain) ### When the Flow Steward is accountable When delivery stalls for non-validation reasons — process gates that don't earn their place, pipeline failures, missing observability. Also when delivery feedback is not returned to the DO phase. ### Team size guidance | Team size | Configuration | |-----------|--------------| | 1–2 people | Flow Steward responsibilities shared informally | | 3–10 people | One person owns the delivery pipeline and telemetry | | 10+ people | Dedicated Flow Steward(s) for complex pipelines | --- ## Governor **The human accountable for what the system is doing in production.** The Governor holds the highest-trust role in a DoCoDeGo team at Stage 3+. They watch for drift between what the system is doing and what it was specified to do, and they have the authority and responsibility to act when misalignment is detected. When something goes wrong in production, the Governor is the person who can be asked "did you know?" and must have an answer. ### Responsibilities - Facilitate the weekly Intent Review - Hold kill-switch authority over autonomous agents - Monitor Agent Alignment Rate and Governance Trigger Rate - Review reasoning traces when behavior is unexpected - Maintain the provenance record (what was built, when, by which agent) - Escalate governance conflicts to human decision-makers — never resolve them autonomously - Enforce scope limits and confidence thresholds for agents ### What they are NOT accountable for - Writing specifications (Intent Architect) - Directing composition (Composition Lead) - Operating the delivery pipeline (Flow Steward) ### When the Governor is accountable When governance oversight failed — an agent operated outside its scope undetected, alignment failure was not caught before delivery, or a governance conflict was resolved without human authorization. ### Kill-switch authority The Governor has unilateral authority to halt delivery or suspend an agent's operation when they have evidence of alignment failure. This authority does not require consensus. The Governor does not need to prove harm has occurred to exercise this authority. Suspicion of alignment failure is sufficient to halt and investigate. **This is enforcement authority, not advisory.** The Governor is not a facilitator or a compliance reviewer — they have actual power to stop delivery. This distinguishes the Governor role from the Scrum Master role in Agile, which has facilitation authority but typically lacks enforcement authority. See [GO Pillar](./02-pillar-04-go-governance.md) for the governance failures that trigger kill-switch use. ### What checks the Governor The Governor has enforcement authority. That authority requires its own accountability. The Governor is not above the governance system — they are part of it. **Checks on Governor authority:** - **Documentation requirement:** Every kill-switch exercise, governance flag, and escalation decision must be recorded with the reasoning that produced it. The record is reviewable by the team and, in regulated environments, by external auditors. - **Spec boundary:** The Governor may halt delivery and suspend agents, but may not unilaterally modify specifications. That authority belongs to the Intent Architect. A Governor who rewrites intent without an Intent Architect review is overstepping. - **Intent Review accountability:** Governor decisions are surfaced and reviewed in the weekly Intent Review. The Governor cannot operate without team awareness of what governance actions were taken and why. - **External oversight:** In organizations with boards, compliance functions, or regulatory oversight, the governance record (reasoning traces, AAR, GTR, escalation log) is the accountability artifact for external review. - **Anti-capture check:** See [Anti-Patterns](./04-guide-01-anti-patterns.md), Anti-Pattern 7 (Governor Capture). A Governor who has not raised a governance flag in three months of Stage 3+ operation should ask: am I reviewing what needs to be reviewed, or am I approving what is expected of me? The Governance Trigger Rate metric exists to make this visible. **The Governor is not a compliance officer.** The role is active oversight, not checkbox completion. Governance authority without governance scrutiny is capture in the making. ### In small teams In teams of 1–3 people, the Governor role is typically held by the same person as the Intent Architect. This is appropriate when AI autonomy is low (Stage 1–2). As autonomy increases (Stage 3+), consider separating the roles. ### Team size guidance | Team size | Configuration | |-----------|--------------| | 1–2 people | Governor + Intent Architect same person | | 3–10 people | Governor is a designated person, not a separate hire | | 10+ people | Dedicated Governor(s) for autonomous agent operations | --- ## Role Overlap and the Same-Person Rule It is acceptable — and often correct — for one person to hold multiple roles. **Acceptable overlaps:** - Intent Architect + Governor (same person): common at Stage 1–2 - Composition Lead + Flow Steward (same person): common on small teams **Overlaps to avoid at Stage 3+:** - Governor + Composition Lead (same person): conflicts of interest in self-reviewing composition outputs - Governor + Flow Steward (same person): governance should have independence from delivery pressure **Stage-specific warnings:** - **Governor + Intent Architect (Stage 2+):** When the same person holds both roles, their own specifications must be scored by an external reviewer. Self-scoring creates a structural conflict of interest that undermines ICS integrity. - **Governor + Composition Lead (Stage 2+):** Prohibited at Stage 3+. At Stage 2, this combination requires that all architectural decisions be reviewed by a second person (typically the Intent Architect) before governance sign-off. - **Governor + Flow Steward (Stage 2+):** Delivery pressure and governance authority are fundamentally in tension. If the same person holds both roles, the Intent Review must include an explicit check for governance decisions made under delivery pressure. --- ## How These Roles Map from Agile Teams migrating from Scrum or Agile often ask which existing roles correspond to DoCoDeGo roles. The mapping is not one-to-one — the responsibilities shift significantly — but it provides a useful starting point for conversations about who takes on what. | Agile/Scrum Role | DoCoDeGo Role | What changes | |-----------------|---------------|-------------| | Product Owner | Intent Architect | Focus shifts from user stories to machine-parseable specifications | | Tech Lead / Senior Dev | Composition Lead | Shifts from implementation to architecture and AI direction | | DevOps / Release Engineer | Flow Steward | Shifts from managing human coordination to managing validation gates | | Scrum Master | Governor | Shifts from process facilitation to alignment oversight and kill-switch authority | The titles are different, but the underlying shift is the same across all four: accountability moves from managing activity to owning outcomes — and every role now answers to the specification. --- *→ [Intent Review](./03-practice-03-intent-review.md) — the meeting these roles run together* *→ [Metrics](./03-practice-05-metrics.md) — what each role measures* *→ [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md) — when roles formalize* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # DoCoDeGo Metrics *How to measure whether the framework is working.* --- > *For the leader: These metrics replace story points and velocity — not because those > measures are bad, but because they measure human production in a world where AI > handles production. These measures track the one thing that matters: is the system > doing what we said it would?* --- ## Overview DoCoDeGo defines six metrics. Two are diagnostic (measure spec quality), two are operational (measure delivery health), and two are governance (measure alignment). | Metric | Pillar | What it measures | Threshold | |--------|--------|-----------------|-----------| | Intent Clarity Score (ICS) | DO | Spec quality before composition | ≥ 60 required to begin CO | | Spec-to-Delivery Latency (SDL) | DE | Time from approved spec to delivered output | Trending down over time | | Agent Alignment Rate (AAR) | GO | % of agent outputs passing acceptance criteria on first attempt | ≥ 70% | | Governance Trigger Rate (GTR) | GO | % of delivery cycles requiring governance escalation | < 10% | | Regeneration Confidence (RC) | CO | Confidence that a regenerated system matches original behavior | ≥ 90% before production | | Drift Detection Latency (DDL) | GO | Time from behavioral drift occurring to it being detected | Trending down over time | --- ## Intent Clarity Score (ICS) **Pillar:** DO **Owner:** Intent Architect ### Definition A composite score from 0–100 measuring the quality of a specification before composition begins. Calculated across four dimensions. **Note:** The canonical ICS rubric with scored examples is in [Spec Template](./03-practice-02-spec-template.md). This section provides thresholds and usage guidance. ### Formula ``` ICS = Completeness (0–25) + Testability (0–25) + Unambiguity (0–25) + Threat Coverage (0–25) ``` ### Dimensions **Completeness (0–25)** Are all required sections present and non-empty? | Score | Condition | |-------|-----------| | 0 | More than two required sections missing | | 12 | Most sections present; one or two thin | | 25 | All sections complete: Intent, Constraints, Acceptance Criteria, Threat Model, Out of Scope | **Testability (0–25)** What percentage of acceptance criteria are independently testable (binary pass/fail)? | Score | Condition | |-------|-----------| | 0 | Fewer than 50% of acceptance criteria are testable | | 12 | 50–80% of acceptance criteria are testable | | 25 | All acceptance criteria are independently testable | Untestable: "system should be fast," "users should like it." Testable: "95th-percentile response time does not exceed 500ms," "task completion rate ≥ 80%." **Unambiguity (0–25)** Do the constraints and acceptance criteria contain ambiguous qualifiers? | Score | Condition | |-------|-----------| | 0 | Multiple ambiguous qualifiers present (fast, good, user-friendly, appropriate, etc.) | | 12 | One or two ambiguous qualifiers; rest specific | | 25 | No ambiguous qualifiers; all requirements are specific and measurable | **Threat Coverage (0–25)** Are the failure modes documented with recovery paths? | Score | Condition | |-------|-----------| | 0 | No threat model | | 12 | Threat model present with 1–2 failure modes | | 25 | Three or more failure modes documented with consequences and recovery paths | ### Thresholds | ICS | Meaning | Action | |-----|---------|--------| | < 40 | Not ready for review | Return to author for rework | | 40–59 | Under review; not ready for composition | Review and address gaps | | ≥ 60 | Approved; composition may begin | Proceed to CO | | ≥ 80 | High-quality specification | No action required | **What a persistently low ICS reveals:** A team whose specs consistently score below 55 is not struggling with the rubric — they are struggling with requirements clarity. The most common diagnosis is that the Intent Architect role is filled by someone who understands what to build but has never had to write falsifiable acceptance criteria. The ICS score surfaces this before composition begins, not after the output is wrong. **Threat Coverage floor:** A Threat Coverage dimension score below 15 (out of 25) fails the gate regardless of the composite ICS score. A spec that is otherwise complete, testable, and unambiguous but has an inadequate threat model is not safe to build from. This floor cannot be compensated by high scores in other dimensions. **On the 60 threshold:** The ≥ 60 gate is a starting convention, not an empirically derived universal threshold. Teams operating in high-risk domains (safety-critical software, regulated healthcare, financial systems) should consider raising it to 70 after two months of scoring, once they have calibrated what their scores mean in practice. Teams with short-lived or low-stakes outputs may find that consistent scores in the 55–65 range produce acceptable results. The threshold is adjustable — what matters is whether the gate is preventing poorly specified composition from proceeding. If high-ICS specs are producing poor outputs, the scoring calibration, not just the threshold, needs review. ### How to Score ICS is scored by the reviewing team during spec approval, not by the author. It is not a performance measure for the Intent Architect — it is a gate quality measure. The same person can score it if the team is small, provided they are not the author. ### ICS and Spec Hierarchy For projects using the three-level spec hierarchy (Product Context → Domain Spec → Component Spec): - **Domain Spec ICS** gates further decomposition — if the domain spec is unclear, component specs will inherit ambiguity - **Component Spec ICS** gates composition — this is the score that determines whether an AI agent has sufficient context to build A domain spec at ICS ≥ 60 means the behavior is clear enough to decompose into component specs. Each component spec must also score ICS ≥ 60 before its composition begins. The Product Context is not ICS-scored — it is parent context, not a composition input. --- ## Spec-to-Delivery Latency (SDL) **Pillar:** DE **Owner:** Flow Steward ### Definition The time elapsed from specification approval to the first deployment of that specification to the target environment. ### Formula ``` SDL = Timestamp(first deployment) - Timestamp(spec approval) ``` Measured in hours for standard features, days for complex systems. ### How to use it SDL is not a target — it is a diagnostic. The useful signal is the trend: - SDL decreasing over time: the team is removing friction from the path from spec to delivery - SDL increasing over time: something is adding friction — find it SDL does not measure speed for its own sake. A team taking 3 days to deliver a high-complexity feature with a high ICS spec is operating well. A team taking 3 days to deliver a trivial feature with a low ICS spec is not. ### Common SDL inflators - Waiting for spec review approval (reduce by defining review SLAs) - Manual testing steps that can be automated - Release windows that exist by convention, not by risk - Unresolved spec gaps discovered during composition (resolve by improving DO) **What a rising SDL reveals:** SDL that increases over successive cycles — even when feature complexity is stable — is the leading indicator that the team is accumulating process friction. The most common diagnosis is spec-gap rework during composition: the team starts composing, discovers an ambiguity in the spec, pauses to resolve it, and resumes. Each pause adds hours. A rising SDL trend almost always traces to a falling ICS trend from two to three cycles earlier. ### Getting started with SDL New teams have no trend to observe. In the first month of tracking, SDL is simply a measurement exercise — record the time for each spec-to-delivery cycle without drawing conclusions from individual readings. A meaningful trend requires at least five data points across comparable feature sizes. Early readings are often inflated by process unfamiliarity rather than structural friction — this is expected and will correct as the team builds the habit. What to do before a trend exists: track, and ask after each cycle whether anything obviously slowed delivery (a blocked spec review, a missed dependency, a review queue that sat idle). Address the obvious friction first. The trend will emerge within a month of consistent practice. --- ## Agent Alignment Rate (AAR) **Pillar:** GO **Owner:** Governor ### Why It Matters Governance requires evidence, not impression. Without a measured rate of first-attempt alignment, a team cannot distinguish a well-governed system from one where acceptance criteria are too loose, specs are too vague, or the Governor is not looking closely enough. AAR makes the alignment between intent and output visible — the precondition for acting on it. ### Definition The percentage of agent outputs in a delivery cycle that pass all spec-derived acceptance tests on first attempt, without human correction. ### Formula ``` AAR = (Outputs passing acceptance tests on first attempt / Total outputs) × 100 ``` Measured per delivery cycle. Reported at weekly Intent Review. ### Thresholds | AAR | Meaning | Action | |-----|---------|--------| | < 50% | Critical alignment failure | Pause delivery; investigate spec quality and agent configuration | | 50–69% | Below threshold | Identify top failure patterns; address in next DO cycle | | ≥ 70% | Acceptable | Monitor; continue | | ≥ 85% | Strong alignment | No action required | | ≥ 95% | Excellent alignment | Check if specs are too simple or acceptance criteria too loose | ### Warning signal A declining AAR over three consecutive cycles is a governance trigger regardless of whether the current cycle is above threshold. Investigate before the threshold is breached. **What a low AAR reveals:** A team with AAR persistently below 60% is experiencing one of two failures — either specs are too vague (the AI cannot satisfy criteria it cannot interpret), or acceptance criteria are set at the wrong level (testing implementation choices instead of behavioral outcomes). Both are DO failures, not agent failures. A team that responds to low AAR by switching AI tools instead of improving specifications will see the same AAR on a different model. ### Measurement notes "First attempt" means the output generated from the current approved spec version. Regenerations triggered by spec updates reset the baseline. --- ## Governance Trigger Rate (GTR) **Pillar:** GO **Owner:** Governor ### Why It Matters Governance without escalation is not governance — it is observation. The GTR measures whether the governance loop is completing: when alignment fails, does the team actually halt delivery and address it, or does delivery continue regardless? A team with no escalations in three months of autonomous operation is not necessarily well-governed; it may be a team that has stopped looking. GTR makes that distinction visible. ### Definition The percentage of delivery cycles in a reporting period (typically 4 weeks) that required a governance escalation — meaning delivery was paused or an agent was suspended due to alignment failure. ### Formula ``` GTR = (Cycles requiring governance escalation / Total delivery cycles) × 100 ``` ### Thresholds | GTR | Meaning | Action | |-----|---------|--------| | > 25% | Systemic governance problem | Review spec quality, agent configuration, and governance process | | 10–25% | Elevated | Identify pattern in escalations; address root causes | | < 10% | Acceptable | Monitor | | 0% | Investigate | Either governance is working perfectly or governance isn't looking | ### Interpretation GTR of 0% for an extended period at Stage 3+ is not necessarily good news. It may indicate that governance reviews are not deep enough to surface real issues. A team with GTR consistently at 0% should verify that their GO processes are actually examining the right things. **What 0% GTR for three months reveals:** Either the team's governance is genuinely working — which requires evidence (high AAR, stable DDL, reasoning traces reviewed) — or the Governor is not looking. A Governor who has never raised an escalation in a system running autonomous agents for a quarter is not governing; they are attending meetings. The diagnostic is to audit the drift log: if it is empty, governance is not functioning. If it has entries classified as "acceptable" with documented rationale, governance may be functioning well. --- ## Regeneration Confidence (RC) **Pillar:** CO **Owner:** Composition Lead ### Definition When a system is regenerated from an updated specification, Regeneration Confidence measures the degree of verified behavioral equivalence between the original system and the regenerated system. ### How it is assessed Regeneration Confidence is not a formula — it is a checklist of verification activities: | Check | Pass condition | Weight | |-------|---------------|--------| | Acceptance tests pass | All original acceptance tests pass on regenerated system | Required | | Characterization tests pass | Existing characterization tests (if any) pass | Required for brownfield | | Performance within tolerance | Performance metrics within 10% of original | Required | | Security scan clean | No new security findings introduced by regeneration | Required | | Integration contracts preserved | All upstream and downstream integration contracts verified | Required where applicable | **RC Threshold:** All Required checks must pass before regenerated system is deployed to production. ### Why this matters Regeneration is one of DoCoDeGo's most powerful properties — but it introduces a risk: that the new generation behaves differently in ways not captured by the specification. Stochastic AI outputs, changed model behavior, or floating-point variations can all produce subtly different systems from the same spec. Regeneration Confidence is the systematic check that catches these differences before they reach production. **What a failed RC check looks like:** A team regenerated their notification service after updating the spec to add a new channel. All new acceptance tests passed. The RC checklist then caught that the integration contract test with the downstream delivery-tracking system was failing — the regenerated service had renamed a response field. The spec had not declared the field name as an invariant; the RC check caught the contract break that the spec-derived tests did not cover. Without the RC checklist, a working service would have deployed and broken a downstream consumer silently. --- ## Drift Detection Latency (DDL) **Pillar:** GO **Owner:** Governor ### Definition The time elapsed between when a deployed system begins exhibiting behavior inconsistent with its specification and when that drift is detected by governance monitoring. ### Formula ``` DDL = Timestamp(drift detected) - Timestamp(drift began) (estimated when exact start time is unknown) ``` Measured in hours for critical systems, days for lower-criticality systems. ### How to use it DDL is a lagging indicator — it can only be measured after drift is detected. Its value is in trend analysis: - DDL decreasing over time: observability and monitoring are improving - DDL increasing over time: monitoring coverage is degrading The target is not zero (perfect real-time detection is not achievable). The target is a DDL appropriate to the system's criticality — a payment system requires lower DDL than a non-critical internal tool. **What a high DDL reveals:** A team that detects drift five days after it began did not have adequate observability for that system. The most common cause is that acceptance criteria defined in the spec were not translated into runtime monitors — the team tested the system at delivery but did not instrument it for ongoing behavioral verification. A DDL of five days on a payment service means the system may have been silently misprocessing transactions for 120 hours before anyone noticed. --- ## What These Metrics Replace | Traditional metric | DoCoDeGo metric | Why | |-------------------|----------------|-----| | Story points | ICS | Measures spec quality, not effort | | Velocity (points/sprint) | SDL | Measures actual delivery flow, not estimated capacity | | Bug count | AAR | Measures alignment between spec and output | | Sprint burndown | GTR | Measures governance health, not completion rate | | Code coverage | RC | Measures behavioral equivalence after regeneration | | Time to detect (MTTD) | DDL | Measures how quickly drift is caught | --- ## A Note on Gaming Any metric can be gamed. DoCoDeGo metrics are no exception. The most common gaming patterns to watch for: - **ICS gaming:** Scoring specs artificially high to pass the gate. Counter with periodic retrospective review of whether high-ICS specs produced good outputs. - **AAR gaming:** Writing loose acceptance criteria that everything passes. Counter with ICS testability dimension and periodic criteria review. - **GTR gaming:** Not escalating governance issues to keep the rate low. Counter with Intent Review drift log analysis. The goal of these metrics is not to optimize the numbers. It is to understand how well the loop is working and where it needs improvement. Teams optimizing for the metrics rather than the underlying health they indicate have lost the point. ### Structural Gaming Prevention Cultural recommendations alone do not prevent gaming in performance-linked environments. These structural requirements reduce the opportunity for gaming regardless of intent: **ICS — Cross-validation requirement:** The spec author cannot be the sole ICS scorer. A second reviewer must concur before a spec receives ICS ≥ 60. For any spec scored ≥ 80, external validation (outside the immediate team) is recommended. The ICS scorer should not be the person who directly benefits from faster composition — if the same person owns both spec quality and delivery speed, the conflict is structural. **AAR — Acceptance criteria independence:** Acceptance criteria must be written or reviewed by someone other than the person constructing against them. Criteria authored and tested by the same person have no independence. Persistently high AAR on specs with low Testability scores warrants investigation. **GTR — Escalation obligation:** When the Governor observes a governance threshold breach and decides not to escalate, the decision must be documented in the drift log with rationale. Undocumented non-escalation is a governance failure, not a judgment call. This makes the decision visible rather than invisible. **Metric ownership rotation:** The same person should not own a metric and the behavior it measures indefinitely. Rotate metric ownership (AAR and GTR specifically) at stage gate advancement or annually, whichever occurs first. --- ## Process Signals The six metrics above are outcome measures — they tell you what happened. A team also needs process signals: leading indicators that reveal whether the governance loop is functioning before problems appear in outcome data. These are not threshold metrics. They are observable conditions reviewed at each weekly Intent Review. A warning pattern is the prompt to investigate. | Signal | What to observe | Warning pattern | |--------|----------------|----------------| | **Intent Review completion rate** | % of scheduled reviews actually held | < 90% over 4 consecutive weeks | | **Spec age at composition start** | Days between spec creation and first composition action | Increasing trend — specs being written during or after composition | | **Escalation resolution time** | Days from GTR event to documented resolution | > 5 business days without resolution | | **Stage gate dwell time** | Time since last stage gate assessment | > 8 weeks without reassessment at Stage 2+ | | **Metric ownership stability** | Whether one person owns both a metric and the behavior it measures | Any combination persisting > 6 months at Stage 3+ | Process signals are a standing agenda item at the weekly Intent Review. See [Process Signals in the GO Pillar](./02-pillar-04-go-governance.md) for governance integration. --- *→ [Spec Template](./03-practice-02-spec-template.md) — where ICS is applied* *→ [Intent Review](./03-practice-03-intent-review.md) — where metrics are reviewed weekly* *→ [Roles](./03-practice-04-roles.md) — who owns each metric* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern* # DoCoDeGo Glossary *Definitions for all terms introduced by the DoCoDeGo framework. Where a term has a canonical document, it is linked. Definitions here are summaries — the canonical document governs.* --- ## Quick Index [A](#a) · [B](#b) · [C](#c) · [D](#d) · [E](#e) · [F](#f) · [G](#g) · [I](#i) · [K](#k) · [M](#m) · [P](#p) · [R](#r) · [S](#s) · [V](#v) --- ## A ### Agent Alignment Rate (AAR) **Pillar:** GO · **Threshold:** ≥ 70% The percentage of AI agent outputs that pass acceptance criteria on first attempt, without regeneration or human correction. `AAR = (Outputs passing acceptance criteria on first attempt / Total outputs) × 100` AAR below 70% indicates spec quality or agent configuration problems. A declining AAR over three consecutive cycles is a governance trigger regardless of whether the current cycle is above threshold — investigate before the threshold is breached. *→ [Metrics](./03-practice-05-metrics.md)* --- ### Amplification Effect The phenomenon where AI systems amplify poor intent into large volumes of incorrect implementation faster than a human team would produce incorrect work. A vague specification fed to an AI agent produces wrong code at scale, not just slowly — making intent clarity more consequential in AI-era development than in human-only development. *→ [DO Pillar](./02-pillar-01-do-documentation.md)* --- ### Atomic Delivery The DE pillar principle that each delivery unit should be independently deployable, verifiable, and relatable to a specific specification. Delivery that bundles unrelated changes violates atomicity and makes validation, rollback, and governance ambiguous. *→ [DE Pillar](./02-pillar-03-de-delivery.md)* --- ## B ### Behavioral Flow The sequence of steps and branching paths that occur when a feature is used. Covers both user-initiated flows (what the user does) and system flows (what the system does in response to events). Required section in Full Spec mode when a feature involves multiple steps, user decisions, or branching paths. Each step should name its actor explicitly: `[Actor] → action → outcome`. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Bounded Autonomy The GO pillar principle that every AI agent operates within explicitly defined and enforced constraints: scope (what the agent may act on), permissions (what resources it may read, write, or execute), confidence threshold (below which it must pause and escalate), and time limit (after which it requires human acknowledgment). These are not advisory guidelines — they are enforced operational limits. An agent operating outside its declared boundaries is exhibiting drift. *→ [GO Pillar](./02-pillar-04-go-governance.md) · [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md)* --- ### Brownfield Any existing system that lacks approved specifications. The dominant real-world condition for practicing engineers. DoCoDeGo requires Intent Archaeology before any modification of brownfield systems — composition is only permitted in areas with approved specs. *→ [DO Pillar §Brownfield](./02-pillar-01-do-documentation.md) · [CO Pillar §5](./02-pillar-02-co-compose.md)* --- ### Business Rules Conditional logic that governs behavior — the policy decisions an organization has made about how the system should act in specific circumstances. Required section in Full Spec mode when behavior differs based on combinations of conditions (pricing, eligibility, permissions, routing, classification, approval workflows). *→ [Spec Template](./03-practice-02-spec-template.md)* --- ## C ### Component Spec Level 3 of the spec hierarchy. Defines what a specific implementation layer must do to fulfill a domain spec. Contains layer-specific constraints, acceptance criteria, and threat considerations, but inherits business rules, flows, and state machines from the parent domain spec. ICS scored at this level; this score gates composition. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Composition Lead One of the four human roles. Responsible for reviewing AI-generated output for architectural soundness, classifying deviations from spec, escalating spec gaps to the Intent Architect, and protecting system invariants. Must maintain hands-on technical depth through regular practice. *→ [Roles](./03-practice-04-roles.md) · [CO Pillar](./02-pillar-02-co-compose.md)* --- ## D ### Declared Omission Rule The principle that silence is not omission — missing optional sections must be explicitly declared inapplicable. This prevents accidental gaps from being mistaken for deliberate ones. Example: "No external integrations" or "Single-action feature; no flow needed." *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Domain Spec Level 2 of the spec hierarchy. Defines what a coherent behavioral capability does — independent of which implementation layer delivers it. Contains the full spec template (Intent, optional sections, Constraints, Acceptance Criteria, Edge Cases, Threat Model). ICS scored at this level; ICS ≥ 60 means behavior is clear enough to implement. *→ [Spec Template](./03-practice-02-spec-template.md)* ### DDL → *see Drift Detection Latency* --- ### Drift Divergence between what a system does and what its approved specification says it should do. Drift is detected by the Governor during Intent Reviews and tracked via Drift Detection Latency. *→ [GO Pillar](./02-pillar-04-go-governance.md) · [Intent Review](./03-practice-03-intent-review.md)* --- ### Drift Detection Latency (DDL) **Pillar:** GO · **Threshold:** Trending down The elapsed time between when behavioral drift begins and when it is detected by governance processes. `DDL = Timestamp(drift detected) − Timestamp(drift began)` DDL is a lagging indicator — it can only be measured after drift is detected. The target is not a fixed number; it is a target appropriate to the system's criticality, trending downward over time. *→ [Metrics](./03-practice-05-metrics.md)* --- ## E ### Edge Case Catalog A structured list of non-adversarial failure scenarios — situations the system will encounter in normal operation that require defined behavior. Includes: empty states, boundary conditions, concurrent access, partial failures, invalid inputs, integration timeouts, duplicate submissions. Distinct from Threat Model, which covers security/adversarial failures. Recommended section for all features. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Escalation Protocol A documented, pre-planned sequence for responding to governance events at Stage 4. Defined across four tiers: Tier 1 (Alert — threshold breach, 30-minute acknowledgment by Flow Steward), Tier 2 (Governance flag — AAR degradation or unexplained drift, 4-hour acknowledgment by Governor), Tier 3 (Kill-switch consideration — confirmed misalignment or data integrity risk, immediate response), Tier 4 (Incident record — kill switch exercised or regulatory threshold reached, documented within 24 hours of resolution). The escalation protocol is itself a governance artifact — stored in the spec backlog and reviewed in Intent Reviews whenever a threshold was breached. *→ [Maturity Stage Gates §Stage 4](./04-guide-03-maturity-stage-gates.md)* --- ## F ### Flow Steward One of the four human roles. Validates delivery readiness, makes the confidence judgment for production deployment, ensures feedback flows from DE back to DO, and monitors telemetry for behavioral drift. Responsible for identifying and removing artificial gates in the delivery pipeline. *→ [Roles](./03-practice-04-roles.md) · [DE Pillar](./02-pillar-03-de-delivery.md)* --- ### Full Spec Spec mode for features with multiple steps, branching, stateful entities, multiple roles, or cross-domain concerns. Requires all sections whose triggering conditions are met, with declared omission for the rest. Triggered when a feature needs a Behavioral Flow. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ## G ### Good Code Mark The recognition model used by DoCoDeGo in place of certification. Earned by teams through demonstrated practice at each maturity stage. Verified through the **DoCoDeGo Practice Assessment**: a review of practice artifacts (specs, metrics history, and stage gate records) and a team walkthrough to confirm that the team understands the decisions behind their own records. No standardized written exam. The Good Code Mark cannot be purchased, franchised, sold, or issued by any third party. *→ [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md) — canonical definition and full Practice Assessment process* --- ### Governance Trigger Rate (GTR) **Pillar:** GO · **Threshold:** < 10% The percentage of delivery cycles that required governance escalation — a kill-switch event, an Intent Review override, or a spec-conflict resolution. `GTR = (Cycles requiring governance escalation / Total delivery cycles) × 100` GTR consistently at 0% at Stage 3+ is a warning sign, not a success indicator — it may mean governance processes are not being invoked when they should be. *→ [Metrics](./03-practice-05-metrics.md)* --- ### Governor One of the four human roles. Holds kill-switch authority and is accountable for alignment between agent behavior and approved intent. Runs weekly Intent Reviews. Resolves governance conflicts. The Governor's authority is enforcement authority — not advisory, not facilitation. *→ [Roles](./03-practice-04-roles.md) · [GO Pillar](./02-pillar-04-go-governance.md)* --- ### Governor Capture An anti-pattern in which the Governor role loses independence. Two forms: **engineering capture** (the Governor defers to the engineering team and GO becomes a rubber stamp) and **business capture** (the Governor defers to delivery pressure and GO becomes compliance theatre). Both render governance ineffective without visibly breaking it. *→ [Anti-Patterns](./04-guide-01-anti-patterns.md)* --- ### GTR → *see Governance Trigger Rate* --- ## I ### ICS → *see Intent Clarity Score* --- ### Intent Archaeology The process of recovering intent from an existing brownfield system that lacks specifications. Involves reading code, tests, commit history, and documentation to infer what the system was designed to do, then writing provisional intent statements that must be reviewed and approved before composition proceeds. *→ [DO Pillar](./02-pillar-01-do-documentation.md)* --- ### Intent Architect One of the four human roles. Responsible for writing and approving specifications before composition begins, maintaining the ICS gate, escalating when intent cannot be clarified, and updating specs when reality reveals gaps. *→ [Roles](./03-practice-04-roles.md) · [DO Pillar](./02-pillar-01-do-documentation.md)* --- ### Intent Clarity Score (ICS) **Pillar:** DO · **Threshold:** ≥ 60 to begin composition A rubric-based score measuring specification quality across four dimensions, each scored 0–25: `ICS = Completeness + Testability + Unambiguity + Threat Coverage` Maximum score: 100. Specifications scoring below 60 must not be handed to an AI agent — the output will require more correction time than starting from a higher-quality spec. ICS is scored by the reviewing team, not the author. *→ [Spec Template](./03-practice-02-spec-template.md) — canonical rubric · [Metrics](./03-practice-05-metrics.md)* --- ### Intent Review The weekly governance ritual. A 30-minute structured session with three segments: Drift Check, Spec Health, and GO Signal. Owned and facilitated by the Governor. The primary mechanism for detecting behavioral drift before it becomes a production failure. *→ [Intent Review](./03-practice-03-intent-review.md)* --- ### Integration Map A list of external systems, services, and APIs that a feature depends on or interacts with — including the nature of each interaction (read, write, event subscription) and the failure handling expectations. Required section when a feature calls an external system, consumes an event, or writes to a system outside its own domain. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### IRAF Loop **Intent → Reasoning → Action → Feedback** The delivery cycle model used in the DE pillar. Each cycle begins with approved intent (DO), proceeds through agent reasoning and composition (CO), executes a demonstration action (DE), and returns feedback to governance (GO) and back to intent (DO). IRAF specializes the OODA loop by centering intent as the starting condition. *→ [DE Pillar](./02-pillar-03-de-delivery.md)* --- ## K ### Kill-Switch The Governor's authority to unilaterally halt delivery or suspend an agent when there is evidence of alignment failure. Does not require consensus. Does not require proof of harm — suspicion of alignment failure is sufficient to halt and investigate. A human without kill-switch authority is an observer, not a governor. *→ [GO Pillar](./02-pillar-04-go-governance.md) · [Human Oversight](./03-practice-06-human-oversight.md)* --- ## M ### Maturity Stages The four progression stages that define how AI autonomy and governance practices scale together: | Stage | Name | Characteristic | |-------|------|----------------| | 1 | Augmented | AI assists human work | | 2 | Collaborative | AI constructs; human reviews every output | | 3 | Orchestrated | Multi-agent; human directs and governs | | 4 | Autonomous | Agents operate with minimal per-cycle human input | Teams advance through stage gates, not timelines. Rollback to a prior stage is explicitly supported. *→ [Maturity Stage Gates](./04-guide-03-maturity-stage-gates.md)* --- ## P ### Permission Model Who can perform which actions, under what conditions, and what each role can see versus what they cannot. Required section when a feature has multiple user types, or some users can do things others cannot. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Phase A / Phase B The two-phase DO workflow. Phase A: Flow Definition — agree on what the feature does before writing the spec. Phase B: Spec Writing — the agreed flow becomes the Behavioral Flow section of the spec. Phase A is required for non-trivial features; simple features may proceed directly to Phase B. *→ [DO Pillar](./02-pillar-01-do-documentation.md)* --- ### Product Context Level 1 of the spec hierarchy. Establishes shared constraints and intent across all specs in a product. Contains product mission, cross-cutting constraints, scope boundary, defined roles, and shared glossary reference. Not ICS-scored; this is parent context, not a composition input. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Provenance The audit trail of what was built, when, by which agent, under which specification, and with which governance decisions applied. Required at Stage 4. The foundation of accountability in autonomous systems. *→ [GO Pillar](./02-pillar-04-go-governance.md)* --- ## R ### RC → *see Regeneration Confidence* --- ### Regeneration Confidence (RC) **Pillar:** CO · **Threshold:** ≥ 90% before production deployment The verified confidence that a system regenerated from an updated specification matches the behavior of the prior version in all unmodified areas. Not a formula — a checklist of verification activities (behavioral tests, integration tests, system invariant checks) that must pass before a regenerated system reaches production. *→ [Metrics](./03-practice-05-metrics.md)* --- ### Release Scope Optional organizational wrapper that defines which domain specs are in scope for a release, and what cross-cutting release constraints apply. Contains list of included domain specs, release-level constraints, release-level acceptance criteria, and rollback criteria. Used by Governor, Flow Steward, and Composition Lead to scope and sequence delivery. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ## S ### SDL → *see Spec-to-Delivery Latency* --- ### Simple Spec Spec mode for single-action features with no branching, no stateful entities, and single layer/role. Requires Intent, Constraints, Acceptance Criteria, Edge Cases, Threat Model, and Out of Scope — with all optional sections declared inapplicable. *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### State Machine The defined states an entity can be in, and the transitions between them — including which transitions are permitted, which are forbidden, and what triggers each. Required section when a feature involves entities that have a lifecycle (orders, tasks, approvals, subscriptions, tickets). *→ [Spec Template](./03-practice-02-spec-template.md)* --- ### Same-Person Rule The pragmatic allowance that one person may hold multiple roles in small teams, subject to conflict constraints. Some combinations require additional checks; some are prohibited at higher maturity stages. See [Roles](./03-practice-04-roles.md) for the full constraint table. *→ [Roles](./03-practice-04-roles.md)* --- ### Spec Drift → *see Drift* --- ### Spec-to-Delivery Latency (SDL) **Pillar:** DE · **Threshold:** Trending down The elapsed time from specification approval to first production deployment of the specified behavior. `SDL = Timestamp(first deployment) − Timestamp(spec approval)` SDL is a diagnostic, not a target. A team delivering a complex feature in three days with a high-ICS spec is operating well. SDL increasing over time indicates friction in the path from spec to delivery. *→ [Metrics](./03-practice-05-metrics.md)* --- ### Specless Generation The practice of using AI to produce consequential output — code, analysis, proposals, decisions — without a preceding specification, acceptance criteria, or governance structure. The output arrives quickly but without a defined standard for correctness, leaving no clear basis for validation, ownership, or accountability. Specless generation is the failure mode DoCoDeGo is designed to replace. It is not a single practice but a category that includes several named patterns from software engineering and adjacent fields: - **Vibe coding** — generating software through AI prompts without understanding the output, iterating by feel rather than against defined acceptance criteria - **Specless analysis** — asking AI to produce a report or recommendation without first defining the question, evidence standard, or non-negotiable constraints - **Prompt-first composition** — directing AI with ad-hoc prompts instead of structured specifications; producing output that cannot be reliably regenerated or verified What these patterns share: AI produces output that feels right, evaluated by subjective judgment rather than specified criteria, owned by no one accountable for the decision. DoCoDeGo's response is the same in every case: **intent before generation; validation before use; governance of what was produced.** *→ [Manifesto](./01-core-02-manifesto.md) · [Anti-Patterns](./04-guide-01-anti-patterns.md) · [Beyond Software Development](./04-guide-08-beyond-software.md)* --- ### System Invariants Properties of a system that must be preserved across any regeneration, refactoring, or modification: data contracts, API contracts, security invariants, and performance invariants. The Composition Lead is responsible for explicitly identifying and protecting system invariants during every composition cycle. *→ [CO Pillar](./02-pillar-02-co-compose.md)* --- ## V ### Vibe Coding Industry shorthand (Andrej Karpathy, 2025) for the software development instance of specless generation: generating code through AI prompts without prior specification, iterating on AI output without defined acceptance criteria, and accepting the result by feel rather than by validation. DoCoDeGo is the structured alternative — addressing the same desire for faster development while maintaining accountability for what is built. See **[Specless Generation](#specless-generation)** for the broader category of which vibe coding is one named example. *→ [Manifesto](./01-core-02-manifesto.md) · [Anti-Patterns](./04-guide-01-anti-patterns.md)* --- *→ [Metrics](./03-practice-05-metrics.md) — full metric definitions and thresholds* *→ [Roles](./03-practice-04-roles.md) — full role definitions and constraints* *→ [Statutes](./03-practice-01-statutes.md) — the sixteen normative principles* **docodego.com** · *DOcument · COmpose · DEmonstrate · GOvern*