Section 6
Living Specs & AgentOS
Lessons 1–4: guardrails, gates, PBT, expert AI crew. Lessons 5–9: AgentOS memory, shape-spec, tasks, and paths.
"When your team says a feature is done — is that an opinion, or a verifiable fact?
Topics
Lesson 1 · The Explainer
Living Specs & Executable Guardrails
Close the plan-vs-shipped gap — test-driven specs, Given/When/Then scenarios, test-first gate, property tests, and a traceable definition of done.
Lesson 2 · Speed without the cliff
Verification Gates
Agent's dilemma, hard-stop gates, spec/plan/task/runtime checkpoints, spec-first drift fixes, and CI that makes quality unavoidable.
Lesson 3 · Prove the rules
Property-Based Testing
Beyond examples — EARS to invariants, counter-example engines, shrinking, and a six-step recipe with Hypothesis and FastCheck in CI.
Lesson 4 · Beat the curse of instructions
Expert AI Crew
Orchestrator + specialists, shared job board, allowed-file tasks, contract-first DB→API→UI handoffs, and human review gates A–D.
Lesson 5 · AgentOS
Persistent Project Memory
AgentOS fixes AI context loss — project memory lives in version-controlled files agents read every time, not in chat history.
Lesson 6 · Plan · Roadmap · Techstack
Three Memory Files
plan.md prevents feature drift, roadmap.md sets priorities, techstack.md shares stack truth — one knowledge base for humans and AI.
Lesson 7 · Dialogue before code
shape-spec
Structured developer–AI conversation until features are understood; capture outcomes in requirements.md and clear ambiguity.
Lesson 8 · Atomic checklist
/create-tasks
Decompose features into small, dependency-ordered tasks in tasks.md — a clear checklist linked to requirements.
Lesson 9 · Control vs speed
Implementation Paths
Implement tasks for maximum control, or orchestrate tasks for speed — parallel specialist agents with fewer conflicts.
Three memory files
plan.mdPrevent feature drift
Keeps the current feature and tasks in focus — what we are building now, not everything at once.
roadmap.mdClarify priorities
Orders what comes next so agents and humans align on sequencing and deferrals.
techstack.mdShared stack truth
Documents frameworks, versions, and conventions — removes guesswork about how this repo is built.
AgentOS workflow
Load persistent context
plan.md · roadmap.md · techstack.mdshape-spec — dialogue until intent is clear
requirements.md/create-tasks — dependency-ordered atomic tasks
tasks.mdImplement or orchestrate tasks
CodeImplementation paths
Same AgentOS pipeline — different execution strategy.
High control
Implement Tasks
Execute one task at a time in order — ideal when you want tight review, Tier Two gates, and minimal parallel risk.
Best when
- ·Learning the codebase
- ·Risky or ambiguous work
- ·Constitution-heavy changes
Benefits
- ✓Faster delivery with fewer context resets between sessions
- ✓Consistent decisions — stack and priorities written once
- ✓Reliable handoffs — requirements and tasks are the contract
- ✓Strategic focus — you decide; AI executes within AgentOS rails
Practical Takeaways
- 1Lesson 1: Specs as executable guardrails — requirements written to produce tests, not wishlists in a doc silo.
- 2Lesson 2: Verification gates are hard stops — spec, plan, task, runtime; human architect, AI executor within bounds.
- 3Lesson 3: PBT — EARS to invariants, counter-examples and shrinking; six-step recipe; Hypothesis / FastCheck as CI gates.
- 4Lesson 4: Expert crew — curse of instructions, orchestrator + specialists, contract-first handoffs, review gates A–D.
- 5Agent dilemma: speed vs context drift and silent assumptions — gates keep velocity without chaos.
- 6Runtime drift: evidence vs acceptance criteria; mismatch means update spec first, never code-only patches.
- 7Automate gates in CI — traceability and verification as merge blockers, quality as path of least resistance.
- 8Cover happy path, edge cases, and error cases with Given/When/Then; run the test-first gate before implementation.
- 9Property-based tests (Hypothesis, FastCheck) prove invariants; every requirement maps to an automated check.
- 10Trace requirement ID → scenario → verification command → PR for an auditable definition of done.
- 11AgentOS uses persistent memory files so AI assistants stop losing project context.
- 12plan.md, roadmap.md, and techstack.md anchor focus, priority, and stack knowledge.
- 13shape-spec + requirements.md eliminate ambiguity before any implementation.
- 14/create-tasks produces a dependency-ordered tasks.md checklist.
- 15Choose implement (control) or orchestrate (speed) based on risk and spec maturity.
- 16Structured workflows increase speed, consistency, and reliability — not chaos.