Spec before implementation
Intent and acceptance criteria are agreed before code begins.
00 · North Star
Platforms over projects.
Every feature must deliver user value now and reusable capability for whoever builds next.
Core doctrine: reuse is a planned, reviewed, and measurable delivery outcome—not an accidental by-product.
01 · Operating model
Seven stages. One learning loop.
Work moves through explicit phases, with structured artifacts at every handoff. Experience and learning are first-class deliverables.
01PlanCharter, value, constraints
02SpecifyExplore, propose, refine, approve
03BuildPlaybooks route work to agents
04VerifyUnit, integration, system, HIL
05ExperienceHuman QA and user feedback
06LearnPatterns, decisions, deltas
07ImproveSpecs, prompts, agents, platform
02 · Design principles
The rules of the system.
Artifacts are interfaces
Stable, versioned contracts keep agents and tools swappable.
Specialize the agents
Each role has bounded authority, clear inputs, and testable outputs.
Humans own judgment
People approve scope, architecture, experience, quality, and release.
Reuse is a deliverable
Every spec records platform impact and names the next beneficiaries.
Knowledge compounds
Decisions, patterns, tests, and lessons return to the shared system.
03 · System architecture
Five systems, coordinated through contracts.
The orchestrator moves approved artifacts between systems. Governance surrounds the flow; knowledge closes it.
Strategy systemVision, charter, outcomes, constraints
Knowledge systemSpecs, ADRs, patterns, lessons
Execution systemOpenSpec, playbooks, specialized agents
Orchestrator
Platform systemReusable services, APIs, components, tooling
Governance systemHuman checkpoints, reviews, go/no-go gates
Learning engineUpdates specs, prompts, playbooks, agents, platform
04 · Artifact contracts
Work is visible, traceable, and resumable.
Every artifact carries purpose, inputs, outputs, dependencies, review history, and links to the artifacts before and after it.
| Artifact | Purpose | Owner | Exit condition |
|---|---|---|---|
| Project charter | Mission, outcomes, scope, constraints, principles | Human product lead | Charter sign-off |
| OpenSpec | Requirements, risks, acceptance criteria, platform impact | Product + architect agents | Spec approval |
| Execution package | Approved plan prepared for orchestration | Orchestrator | Architecture review |
| Work package | Bounded tasks, inputs, outputs, and checks | Playbook | Implementation complete |
| Validation package | Automated results, experience review, release evidence | QA + humans | Release go/no-go |
| Learning package | Reusable components, knowledge deltas, system updates | Platform steward | Improvements committed |
05 · Human checkpoints
Automation moves fast. People decide what matters.
Charter sign-off
Is this the right outcome and scope?
Spec approval
Are behavior, constraints, and acceptance criteria clear?
Architecture review
Does the design strengthen the platform?
Pre-merge quality
Do code, tests, and evidence meet the bar?
Experience review
Does the prototype feel right to users?
Release gate
Is the system safe and ready to ship?
06 · Repository blueprint
The OS lives in the repo.
Plans, governance, agent definitions, test evidence, and learning are versioned beside the product.
ai-engineering-os/
shared source of truth
README.mdOrientation, operating model, and quick start
AGENTS.mdGlobal agent rules, boundaries, and conventions
charter/Vision, principles, outcomes, and constraints
specs/OpenSpec templates, approved features, platform-impact records
playbooks/Versioned workflows for features, release, pause, and resume
agents/Specialized roles with explicit contracts and checks
execution/Execution packages, work orders, and run state
validation/Automated evidence, human reviews, and release decisions
platform/Reusable services, APIs, components, and tooling
knowledge/Architecture decisions, patterns, lessons, and feedback
docs/Human-facing guides, references, and system maps
tests/Unit, integration, system, and hardware-in-the-loop suites
07 · Definition of done
A new agent can enter cold—and still ship correctly.
Given only the charter, templates, playbook, agent contracts, and example, a newly introduced agent can complete a feature, pass every gate, and leave the system more capable.
- Foundation
Charter, schemas, roles, and one complete example - Automation
Transitions, validation, traceability, and pause/resume state - Evolution
Measured reuse and systematic promotion of learning - Proof
Every delivery strengthens the platform and its operating system
08 · Reference implementation
From operating model to a playable game.
Sock Rescue applies the OS to a real RP2350 game: human design judgment defines the experience while structured artifacts turn it into bounded, testable engineering work.
Sock Rescue · Human-Designed AssetsExplore the production-ready art, animation, audio, UI, and gameplay-design handoff for the platform’s first game.View reference implementation →Feature outcome
- Start, pause, and resume without losing progress
- Immediate pause and exact-state resume
- Stable audio and input behavior
- Clear recovery from invalid state
- Automated and hardware-in-the-loop tests
- Human experience approval
Platform outcome
- Reusable game-state manager
- Pause-state machine
- Input-suspension service
- Audio-lifecycle manager
- Shared game-lifecycle API
- Reusable lifecycle test patterns
Platform ROI: future beneficiaries include Save/Load, suspend/resume, and event-driven gameplay systems.