What DoCoDeGo is

DoCoDeGo is a discipline for building anything where AI does the producing and a human still has to own the result. Software systems, contracts, research, content — anywhere a human commissions AI to make something consequential.

It is a framework, a manifesto, and a stance — operational practices grounded in non-negotiable values. The software-development context is where DoCoDeGo is most fully specified; the principles apply wherever AI produces and a human signs the result.

Intent is the primary artefact.

Implementation is a compiled derivative.

Governance is earned through the loop.

Read the full Manifesto →

Three paradigms.
Three cost-equation shifts.

Read the lineage in full →

DOcument · COmpose · DEmonstrate · GOvern

A loop, not a checklist. Each pillar feeds the next; the last feeds back into the first.

Deep-dive each pillar →

Sixteen rules that make the loop non-negotiable.

1. 01 DO Intent Is Absolute →
2. 02 DO The Spec Is the Contract →
3. 03 DO Quality Through Context →
4. 04 DO Simplicity of Spec →
5. 05 CO Code Is Regenerable →
6. 06 CO Resilience Over Robustness →
7. 07 CO Architecture Before Generation →
8. 08 CO Comprehension Is Non-Negotiable →
9. 09 DE Zero-Latency Evolution →
10. 10 DE Feedback Closes the Loop →
11. 11 DE Observability Is Non-Negotiable →
12. 12 DE Atomic Delivery →
13. 13 GO The Human as Governor →
14. 14 GO Transparent Reasoning →
15. 15 GO Security by Design →
16. 16 GO Alignment Before Demonstration →

Each statute in full, with principle, detail, and most-common violation →

Governance scales with autonomy.

A 2-person startup and a 200-person enterprise do not need the same GO practices. The loop runs at every scale.

Spec template · ICS · Metrics · Roles

• · Spec template — Intent · Acceptance Criteria · Constraints · Failure Modes
• · ICS (Intent Clarity Score) — 0–100 grade across Completeness, Testability, Unambiguity, Threat Coverage. ≥ 60 to begin composition.
• · Metrics — AAR (Agent Alignment Rate), GTR (Green-To-Red), DDL (Decision Diff Log), IRAF (Intent → Realised Artefact Flow).
• · Roles — Intent Architect, Compose Reviewer, Demonstration Gate, Governance Auditor.

Open the Practice page → · Try the live Spec Lab →

The honest list.

Every framework that claims to fit every context loses credibility the first time it doesn't. DoCoDeGo is wrong for one-off scripts, solo prototypes, live incidents, regulated SDLCs, resistant teams, pure research, ungovernable contexts, and 2-person founding teams with shared context.

Full breakdown on /why-not →

What could go wrong with the framework itself.

Statute 14 requires every spec to threat-model itself. The framework should too. Here are the failure modes we watch for in our own work:

• Specification theatre. Teams write specs that nobody reads, score them ICS≥60, and treat the green light as permission to ship. Mitigation: ICS gates on PRs; periodic spec→behaviour audits.
• Governance capture. A single Governor becomes the gatekeeper for everything; the loop becomes a queue. Mitigation: rotate the Governor role; cap WIP.
• DoCoDeGo becomes the new Agile. The framework calcifies into ceremony, certification industries form, the original intent is lost. Mitigation: Anti-Complexity Principle; this very page; never accredit.
• Spec sprawl. Every micro-change demands a spec; teams stop shipping. Mitigation: spec granularity guidance in /practice; "fits one screen" rule.
• Tool fetishism. Teams adopt the CLI tools but skip the discipline. ICS ≠ practice. Mitigation: tools are downstream of intent, not upstream.
• Alpha forever. "We're in Alpha" becomes the permanent excuse for instability. Mitigation: publish /changelog; commit to a Beta when statutes are stable for 6 months.

Every acronym, defined.

Full glossary with meanings, pillars, thresholds →

Copyable AI prompts.

Battle-tested system prompts for Claude / GPT / Cursor that produce DoCoDeGo-compliant work: Intent Architect, Compose Reviewer, Governor AAR, ICS Self-Scorer, Cursor system prompt.

Open /prompts →

Tooling.

Everything lives under tools/ in the framework repo. Two families:

• · spec-linter — structural validation of spec markdown
• · ics-scorer — canonical ICS grade (full rubric)
• · aar-gtr-tracker — after-action review / green-to-red tracking
• · rc-runner — runbook checklist automation
• · sdl-ddl-analyzer — SQL DDL analysis for spec extraction
• · spec-diff — spec version diffing
• · threat-validator — threat-model validation

• vscode-docodego Marketplace · coming soon

  Live ICS in the status bar · vague-term diagnostics with quick-fix replacements · CodeLens per section · acronym hovers · DocumentSymbol outline · Activity Bar sidebar listing every spec with band-coloured icons · New spec from template… + Score all → report commands · opt-in save guard · Getting Started walkthrough. Self-contained TypeScript heuristic; the Python ics-scorer remains canonical for CI.

• browser-extension-docodego Web Store · AMO · coming soon

  Live ICS badge on GitHub · GitLab · Bitbucket · Codeberg. Per-file pills in PR / commit diffs, multi-file PR summary, inline vague-term underlines, sparkline trend per URL, toolbar popup with settings + recent scores, options page, Side Panel (Chrome 114+), Alt+I shortcut. Plain MV3 + esbuild — no framework. Client-side, zero telemetry.

• github-action-ics Marketplace · coming soon

  Composite GitHub Action that scores every spec markdown changed in a PR using the canonical Python ics-scorer and gates the check below your threshold (default 60). Posts the per-spec breakdown as a sticky PR comment.

• mcp-docodego PyPI · coming soon

  Model Context Protocol server exposing the framework as a tool any MCP-compatible AI agent (Claude Desktop, Cursor, …) can attach. Tools: dcdg/axiom, dcdg/pillars, dcdg/score-spec, dcdg/statute, dcdg/glossary, dcdg/spec-template.

Until published, install from source — see each tool's README.md + CHANGELOG.md in the repo. The browser-side ICS approximator in the homepage Spec Lab is the same heuristic shipped in the VS Code and browser extensions.

The discipline is the same.

DoCoDeGo was named in a software context, but the loop applies anywhere a human commissions AI to make something consequential:

Same Axiom. Same four pillars. Different artefacts.

Built with Astro, Tailwind, no bullshit.

• · Astro 5 static site, deployed to Cloudflare Pages.
• · Tailwind CSS — Neubrutalist palette: yellow / blue / orange / purple / pink / green on white + black.
• · Inter + JetBrains Mono — sans for prose, mono for everything technical.
• · Dark mode via a top-right 3-state toggle (system / light / dark). A token cascade (--dcdg-canvas / --dcdg-ink / --dcdg-border / --dcdg-shadow) keeps pillar surfaces identity-correct in both themes.
• · Print stylesheet — Ctrl+P / ⌘P strips chrome and prints a clean B&W version. The Manifesto prints to A4 / Letter cleanly.
• · Site search via Pagefind — indexes every page at build time; wired into the ⌘K palette.
• · Per-page OG cards generated at build time via scripts/build-og-cards.mjs.
• · Zero analytics, zero trackers, zero ad scripts.
• · All animations respect prefers-reduced-motion.
• · All copy traces to canonical framework markdown sources.

For devs who poke around.

The site has a complete developer affordance layer: keyboard shortcuts, a command palette, a typed-keyword listener, a window.dcdg API, and a handful of named easter eggs.

Open /secret →  — the full decoder: 30+ eggs across keyboard, hidden interactions, toggles, Flair-gated flair, always-on visuals, and developer affordances — with live "▶ run" buttons and a working REPL.

Machine-readable too.

DoCoDeGo publishes its own metadata so AI agents and tooling can introspect what this site is about.

• llms.txt Machine-readable framework summary for AI agents
• llms-full.txt Verbatim concatenation of Manifesto, Vision, Statutes, Glossary
• /.well-known/docodego.json Framework metadata: pillars, statutes count, lineage, resources
• robots.txt All crawlers welcome
• sitemap-index.xml Generated sitemap for indexing

What "Alpha" means here.

We are a small founders team. DoCoDeGo is in Alpha — the framework is documented, the practices are battle-tested at small scale, the community and the team are forming in public.

Things will change. Statutes may be refined. New tooling will appear. We will say so when it does.

What changed, when, and why.

Reverse-chronological log of framework, site, tooling, and community changes. Alpha means evolving in public — and the log proves we're doing it.

Open /changelog →

Come build with us.

// end of handbook · thanks for reading