In ancient Greece, Aidos was the spirit of restraint — the inner voice that held you back from hubris. AI gave us the power to build anything. Aidos is the discipline to ask whether we should.
AI collapsed the cost of getting to a first pass. A spec that took a sprint can be drafted in an afternoon. A feature that took a team can be prototyped by one person with an agent. The mechanical cost of software has dropped dramatically.
But the thinking hasn't got cheaper. Humans still need to understand problems, align with each other, and make judgment calls. That part is as slow and expensive as it ever was — and when building is fast, bad assumptions compound faster too.
AIDOS helps teams think clearly, document decisions, and audit delivery quality — before implementation speed compounds mistakes.
📖 Read The Hard Part Isn't the Code for the full philosophy behind this project.
Four delivery artifacts that build on each other, plus one that outlasts the project:
Problem → Solution → Tech Design → Testing → Definition
| Artifact | Question It Answers |
|---|---|
| Problem | What is happening, for whom, why it matters, and what success looks like |
| Solution | How the proposed response works as a system, including options and trade-offs |
| Tech Design | How the solution will be implemented — components, interfaces, data, constraints |
| Testing | How we verify it works and trace results back to requirements |
| Definition | What was built, why it works this way, and what a maintainer needs to know |
The first four are delivery artifacts. The Definition is created after the work ships — the living, authoritative description of the feature, maintained as it evolves. Delivery artifacts archive; the Definition persists.
Each artifact is checked against its own quality rubric and against the artifact before it. The Solution has to actually solve the Problem. The Tech Design has to actually implement the Solution. The Testing has to actually verify the Tech Design against the Solution's goals. If the chain breaks, you find out in a review — not in production.
Rubrics with teeth. Not "is this good?" — but "can someone unfamiliar with this project understand the problem without prior conversation?" Pass, Partial, or Fail. With cited evidence. The artifact doesn't advance until bugs are fixed.
Builder/auditor separation. AIDOS depends on separation between artifact creation and artifact audit. One person sprints ahead with AI to create the artifact. A different person checks it against the rubrics and the preceding artifact. The same person can't be both builder and final judge. That's the governance.
AIDOS uses pulse-based delivery: short bursts of AI-assisted artifact creation, separated by explicit human review checkpoints.
- Sprint — build an artifact with AI in an afternoon that would've taken a sprint.
- Park — commit, update status, move on.
- Align — bring humans in. They review, react, decide.
- Feed back — process their decisions with AI in minutes, not days.
- Sprint again — or switch to another project while this one waits for the next human checkpoint.
The artifacts hold the state so you can context-switch between projects without losing anything. When Project A is parked waiting for stakeholder review, you sprint on Project B.
A team needs to improve how warehouse staff track inventory across multiple locations:
| Artifact | What Gets Captured |
|---|---|
| Problem | Warehouse staff can't get accurate stock counts without checking three separate systems, taking ~20 min per lookup. Affects 150+ operators making daily restocking decisions. |
| Solution | Add a unified stock dashboard to the warehouse management interface. Pull live counts from existing inventory sources, surface inline. |
| Tech Design | Query inventory APIs, cache counts with 15-minute refresh, expose via existing service layer. Component renders stock levels with fallback to "data unavailable." |
| Testing | Validate data freshness, permissions, rendering across devices, fallback states. Every test traces to a requirement in the Solution. |
The Problem artifact gets audited: is the stakeholder impact clear? Are the goals measurable? Is the scope bounded? Then the Solution gets audited against the Problem: does it actually address the stated goals? Then the Tech Design against the Solution. The chain holds or it breaks at an identifiable point.
For a full walkthrough showing the human–AI interaction pattern — assumption surfacing, audit findings, fix cycles, and escalated decisions — see Worked Example: Deployment Notifications.
AIDOS ships as two AI skills — Builder and Auditor — packaged for Claude.
| Skill | What It Does |
|---|---|
| AIDOS Builder | Runs a builder session. Scaffolds the right document structure for your scale, builds artifacts iteratively, captures decisions and issues inline. |
| AIDOS Auditor | Runs an audit session. Assesses artifacts against Core and discipline rubrics, checks coherence with preceding artifacts, classifies findings as Bug / Risk / Idea. |
Download the latest skill ZIPs from shobman.github.io/aidos/skills/:
- Go to Settings → Customize → Skills
- Click Upload and select the ZIP file
- The skill appears in your skill list — Claude will use it when relevant
Copy the skill folder into your project:
.claude/skills/aidos-builder/ ← contents of the builder ZIP
.claude/skills/aidos-auditor/ ← contents of the auditor ZIP
- Read
src/framework.md— the mechanics, rubrics, and operating model. - Pick your scale: Epic (big initiative), Feature (one deliverable), or Story (a day's work).
- Open any AI chat. Load the builder prompt — it's self-contained.
- Build through the stack in order — Problem, then Solution, then Tech Design, then Testing — using the document structure for your scale. At Feature and Story scale, multiple artifacts combine into one document.
- Have someone who didn't build it audit against the rubrics and the preceding artifact.
- After the work ships, write the Definition — the living description that persists. Archive the delivery artifacts.
No tooling to install. No platform to adopt. Markdown files, an AI, and discipline.
AIDOS is agent-agnostic. The builder and auditor prompts work with any AI that accepts a system prompt. The framework is designed so that the quality mechanism scales from human-directed to fully autonomous delivery — see Agent Autonomy Spectrum.
For Claude-specific setup — how to connect GitHub, invoke skills, and configure the MCP connector — see CLAUDE.md.
README.md ← You are here
CONTRIBUTING.md ← How to propose rubric changes
docs/
├── manifesto.md ← The philosophy — why decision quality matters
├── worked-example.md ← Full walkthrough — the human–AI workflow in action
├── maturity-model.md ← Agent autonomy spectrum — how the quality model scales
└── images/
├── aidos.jpg ← Hero image
└── social.jpg ← Social sharing image (1280×640)
src/
├── framework.md ← The full operating model — start here
├── rubrics/
│ ├── core.md ← Universal criteria (C1–C13) for every artifact
│ ├── problem.md ← Problem criteria (P1–P10) — Product lens
│ ├── solution.md ← Solution criteria (S1–S9) — Analysis lens
│ ├── tech-design.md ← Tech Design criteria (A1–A10) — Architecture lens
│ ├── testing.md ← Testing criteria (T1–T9) — Quality lens
│ └── definition.md ← Definition criteria (F1–F8) — Maintenance lens
├── templates/
│ ├── problem.md ← Problem artifact template
│ ├── solution.md ← Solution artifact template
│ ├── tech-design.md ← Tech Design artifact template
│ ├── testing.md ← Testing artifact template
│ ├── definition.md ← Definition artifact template
│ ├── issues-log.md ← Centralised escalation register
│ ├── overflow-log.md ← Captures ideas, risks, and insights that don't belong in the current artifact
│ ├── meeting-minutes.md ← Lean meeting capture
│ └── retrospective.md ← Rubric evolution mechanism
└── prompts/
├── builder-prompt.md ← Self-contained AI builder session prompt
└── auditor-prompt.md ← Self-contained AI auditor session prompt
skills/
├── builder/SKILL.md ← AIDOS Builder skill for Claude
├── auditor/SKILL.md ← AIDOS Auditor skill for Claude
└── build.ps1 ← Assembles and ZIPs skills for distribution
site/ ← Framework Explorer (GitHub Pages)
The Framework Explorer is hosted at shobman.github.io/aidos. To run locally: cd site && npm install && npm run dev.
Designed to work with any AI tool that supports system prompts or persistent instructions.
Every project that gets burned by something the rubrics didn't catch can make them better.
Six weeks in, nobody owns it? That's a rubric criterion now. Forgot to check if a vendor already solves this? Rubric criterion. Assumed the regulatory requirement was met without verifying? Rubric criterion.
Not just a framework. A continuously hardened review system, built from real delivery failures.
The most valuable contribution to this repo isn't code. It's: "We got burned by X. Here's the criterion that would have caught it."
See CONTRIBUTING.md.