SDSection 7 →

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?
9 lessons · ~44 min
Loading AgentOS memory…

Topics

Lesson 1

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

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

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

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

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

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

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

Lesson 8 · Atomic checklist

/create-tasks

Decompose features into small, dependency-ordered tasks in tasks.md — a clear checklist linked to requirements.

Lesson 9

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.md

Prevent feature drift

Keeps the current feature and tasks in focus — what we are building now, not everything at once.

roadmap.md

Clarify priorities

Orders what comes next so agents and humans align on sequencing and deferrals.

techstack.md

Shared stack truth

Documents frameworks, versions, and conventions — removes guesswork about how this repo is built.

Copy templates

AgentOS workflow

Memory

Load persistent context

plan.md · roadmap.md · techstack.md
Understand

shape-spec — dialogue until intent is clear

requirements.md
Plan

/create-tasks — dependency-ordered atomic tasks

tasks.md
Build

Implement or orchestrate tasks

Code

Implementation 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

  1. 1Lesson 1: Specs as executable guardrails — requirements written to produce tests, not wishlists in a doc silo.
  2. 2Lesson 2: Verification gates are hard stops — spec, plan, task, runtime; human architect, AI executor within bounds.
  3. 3Lesson 3: PBT — EARS to invariants, counter-examples and shrinking; six-step recipe; Hypothesis / FastCheck as CI gates.
  4. 4Lesson 4: Expert crew — curse of instructions, orchestrator + specialists, contract-first handoffs, review gates A–D.
  5. 5Agent dilemma: speed vs context drift and silent assumptions — gates keep velocity without chaos.
  6. 6Runtime drift: evidence vs acceptance criteria; mismatch means update spec first, never code-only patches.
  7. 7Automate gates in CI — traceability and verification as merge blockers, quality as path of least resistance.
  8. 8Cover happy path, edge cases, and error cases with Given/When/Then; run the test-first gate before implementation.
  9. 9Property-based tests (Hypothesis, FastCheck) prove invariants; every requirement maps to an automated check.
  10. 10Trace requirement ID → scenario → verification command → PR for an auditable definition of done.
  11. 11AgentOS uses persistent memory files so AI assistants stop losing project context.
  12. 12plan.md, roadmap.md, and techstack.md anchor focus, priority, and stack knowledge.
  13. 13shape-spec + requirements.md eliminate ambiguity before any implementation.
  14. 14/create-tasks produces a dependency-ordered tasks.md checklist.
  15. 15Choose implement (control) or orchestrate (speed) based on risk and spec maturity.
  16. 16Structured workflows increase speed, consistency, and reliability — not chaos.