Spec-driven development
All Aucert engineering work follows a spec-driven workflow. Every task — whether executed by a human or an AI agent — starts with a specification. The formality scales with task size.
Why spec-first?
Specifications serve three purposes in an agent-driven workflow:
- Alignment — Human and agent agree on what "done" looks like before work begins
- Context loading — Specs declare which context files the executor needs, reducing wasted tokens
- Audit trail — Every task has a written record: what was requested, what was approved, what was delivered
Task sizes
| Size | Time | Planning approach | Example |
|---|---|---|---|
| Small | < 1h | Plan in conversation (Plan mode), get approval, execute | Fix a typo, add a flag |
| Medium | 1–4h | Intent in .tasks/backlog/ → agent generates spec in .tasks/drafts/ → approve → execute | Add endpoint, write docs page |
| Large | Multi-day | Detailed backlog file → comprehensive spec → both founders review → execute | New pipeline layer, infra migration |
Task file lifecycle
| Directory | Purpose | Who writes |
|---|---|---|
.tasks/backlog/ | Raw intent files awaiting spec generation | Human |
.tasks/drafts/ | Generated specs awaiting review | AI agent |
.tasks/active/ | Approved specs ready for execution | Human (moves from drafts) |
.tasks/archive/ | Completed tasks | Automated (on merge) |
Context loading in specs
Task files declare which context to load, following the cascading context model:
context_load:
l1: [ARCHITECTURE.md, CONVENTIONS.md] # Always loaded
l2: [backend/.context/BACKEND.md] # Platform-specific
l3: [backend/.../domain/generation/spec/GENERATION.md] # Module-specific
This prevents agents from loading irrelevant context (a frontend task doesn't need CLOUD.md), which reduces token usage and improves output quality.
Spec file format
# Task: {title}
## Context
- Module: `backend/platform/src/.../domain/{module}/`
- Spec: `{module}/spec/{MODULE}.md`
- Related proto: `proto/{file}.proto`
## Requirements
1. Specific deliverable
2. Another deliverable
## Acceptance criteria
- [ ] Criterion 1
- [ ] Criterion 2
## Scope boundaries
- NOT in scope: {explicit exclusions}
## Context loading
context_load:
l1: [ARCHITECTURE.md]
l2: [backend/.context/BACKEND.md]
What's next
- Drift capture — How we track implementation drift from specs
- 5-layer deep dive — Pipeline architecture
- How to create an agent task — Practical guide