Documentation

Core Concepts

Spec-Driven Development (SDD)

In SDD, every piece of work starts with a specification document. AI agents have no memory between conversations — the spec IS their memory. The flow is:

Spec (business + technical + acceptance criteria)
  → AI implements against the spec
  → Commit references the spec (git hook enforces)
  → PR updates the spec changelog (CI enforces)
  → Demo proves the spec works
  → Human accepts

The 4-Role Team

Role	Who	Responsibilities
Advisor	You (human)	Vision, architecture, QA, final say. ~10 hrs/week.
Lead Dev	AI agent	Architecture, complex features, PR reviews
Associate	AI agent	Smaller features, tests, infra scripts
PO Agent	AI agent	Backlog, ceremonies, daily reports, process glue

Sprint Lifecycle

SpecAg uses Saturday-to-Friday sprints (weekends for ceremonies so the human can attend):

Day	Time	Ceremony
Saturday	3:00 PM	Sprint Review + Demos + Deploy
Saturday	3:30 PM	Sprint Retrospective
Saturday	4:00 PM	Sprint Planning (next sprint)
Sunday	10:00 AM	Kickoff (tech spec grooming)
Daily	8:05 AM	Daily Standup (async)
Daily	6:00 PM	Daily Report + Burndown
Wednesday	2:00 PM	Backlog Refinement (async)

CLI Reference

specag init

Initialize a new SpecAg project in the current directory. Creates the folder structure, config file, and tier-appropriate templates.

$ specag init --name my-app --owner datta --tier starter

specag sprint prepare

Validate all specs in specs/ against the Definition of Ready for your current tier.

$ specag sprint prepare

specag sprint kickoff

Transition the current sprint from planned to active state.

$ specag sprint kickoff

specag stats

Display token usage, cost summary, and active hooks.

$ specag stats

specag tier show

Display current tier and enforcement matrix.

$ specag tier show

specag tier set <tier>

Upgrade or downgrade your project tier. Shows a diff of what changes before applying.

$ specag tier set medium

specag tier diff <tier>

Preview what changes if you switch to a different tier without applying.

$ specag tier diff personal

Pre-Call Hook Chain

Before any LLM API call, a chain of hooks runs. First non-ALLOW decision wins:

Hook	Decision	What it does
DailyCapHook	REJECT	Reject if daily token cap reached
WeeklyCapHook	REJECT	Reject if weekly cap reached
WorkWindowHook	REJECT	Reject if outside work hours
PausedRegistryHook	REJECT	Reject if epic is hard-paused (blocker T+7)
PCModeHook	DOWNGRADE	Route to cheaper model during discovery
BudgetGuardHook	REJECT	Reject if estimated cost exceeds budget

Cascading Blocker SLA

When work is blocked on a human decision:

Day	What Happens
T+1	PO Agent nudges in Slack
T+3	Priority bumps. Downstream impact broadcast.
T+7	HARD PAUSE. Token tracker rejects ALL LLM calls on blocked paths. Zero spend until human responds.

Configuration

All project settings live in specag.config.yaml:

project:
  name: "my-project"
  owner: "Your Name"
  tier: personal      # starter | personal | medium
  timezone: "America/Chicago"

hooks:
  enabled:
    - daily_cap
    - weekly_cap
    - work_window
    - paused_registry
    - budget_guard

alerts:
  thresholds: [50, 80, 100]
  slack_channel: "#dev"
  deduplicate_minutes: 60

Spec Format

Every spec follows this structure:

## [SUMMARY]       # App, owner, status, priority, story points
## [STORY]         # User story or feature description
## [TECH SPEC]     # Technical design, API contracts, files touched
## [STANDARDS]     # Rules extracted from the spec
## [ACCEPTANCE CRITERIA]  # Given/When/Then format
## [CHANGE LOG]    # Version history of the spec itself

Further Reading

For the complete methodology reference (~2000 lines, 31 sections), see the Project Bible on GitHub.

• Architecture — how the pieces fit together
• Study Guide — structured learning path (3-4 hours)
• Roadmap — what's built, what's next
• Tier Matrix — full strictness breakdown