Getting Started

Prerequisites

• Python 3.9+
• A GitHub repo for your project
• At least one LLM API key (Anthropic, OpenAI, DeepSeek, or Google)
• Optional: Slack workspace with 2 channels (#dev, #planning)

Step 1: Install SpecAg

$ pip install specag

Or with pipx (recommended for CLI tools):

$ pipx install specag

Step 2: Initialize Your Project

$ cd your-project
$ specag init

The interactive setup asks:

Is this a new project or an existing project? (new/existing): existing
Project name: my-saas-app
Your name: Dedeepya
Tier (starter/personal/medium) [personal]: starter

Sprint Configuration:
Sprint naming pattern (use {n} for number) [S{n}]:
Sprint cadence (days) [7]:
Sprint start day [sunday]:
First sprint start date [2026-04-13]:

This creates the following structure:

your-project/
├── specag.config.yaml      # your project config
├── specs/
│   ├── platform/            # PLAT-001 through PLAT-013
│   └── backlog/
├── agents/
│   ├── hooks/               # pre-call hook chain
│   └── state/               # paused epic registry
├── sprints/
│   ├── velocity.json        # velocity tracking
│   └── estimation-log.md    # estimation calibration
└── .sdd/
    ├── coding-standards.md
    └── templates/
        └── demo-script.md

Step 3: Write Your First Spec

Create specs/ROOT-001-user-login.spec.md:

# ROOT-001: User Login

## [SUMMARY]
- App: my-saas-app
- Epic owner: Lead Dev
- Status: READY
- Priority: S1
- Story points: 3

## [STORY]
As a user, I can log in with email and password
so I can access my account.

## [TECH SPEC]
- POST /api/auth/login — accepts email + password, returns JWT
- POST /api/auth/logout — invalidates token
- Password hashed with bcrypt, min 8 chars
- JWT expires in 24 hours
- Rate limit: 5 attempts per minute per IP

### Files Touched
- src/api/auth.py
- src/models/user.py
- tests/test_auth.py

## [ACCEPTANCE CRITERIA]
AC-001: Given valid credentials, when POST /login, then 200 + JWT.
AC-002: Given invalid password, when POST /login, then 401.
AC-003: Given 6 rapid attempts, when POST /login, then 429.

## [CHANGE LOG]
- 2026-04-12: Initial spec created

Step 4: Validate Your Sprint

$ specag sprint prepare

This validates your specs against the Definition of Ready for your tier:

PASS specs/ROOT-001-user-login.spec.md

All specs pass Definition of Ready. Ready for sprint.

Step 5: Check Your Budget

$ specag stats

SpecAg Cost Summary — my-saas-app (T1 Starter)

  No usage data yet. token_usage.db will be created on first API call.

  Active Hooks:
    daily_cap     enabled
    weekly_cap    enabled
    budget_guard  enabled

Step 6: Explore Tiers

$ specag tier show     # see current enforcement matrix
$ specag tier diff medium  # see what changes at T3

What's Next?

1. Read the full documentation to understand the framework
2. Review the tier matrix to see what's enforced at your tier
3. Write more specs — one per feature, max 5 story points each
4. Run your first sprint — specag sprint kickoff on Sunday
5. Check use cases for real-world examples

Environment Setup

Create a .env file in your project root:

# .env — NEVER commit this file
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...
SLACK_BOT_TOKEN=xoxb-...

FAQ

Do I need all 3 AI agents?

No. Start with just Lead Dev. PO Agent and Associate are optional at T1/T2.

Can I use Cursor / Claude Code / Copilot for the actual coding?

Yes. SpecAg doesn't generate code — it provides the process, specs, and cost guardrails. Use whatever AI coding tool you prefer.

What if I don't use Slack?

Slack is recommended but not required. At T1/T2, run ceremonies manually and check costs via specag stats.

Is this just for Python projects?

No. SpecAg is language- and stack-agnostic. The CLI and hooks are Python, but your project can be any language.