sago 0.2.2

Spec-Aware Generation Orchestrator - turns markdown specs into working code

Sago

Sago: The project planner for AI coding agents

You describe what you want in markdown. Sago generates a structured plan. Your coding agent (Claude Code, Cursor, Aider, etc.) builds it.

---

What sago does

Sago is a planning and orchestration tool, not a coding agent. It turns your project idea into a structured, verified plan — then gets out of the way and lets a real coding agent do the building.

You → sago init → sago plan → coding agent builds Phase 1 → sago replan → coding agent builds Phase 2 → ...

Why? AI coding agents (Claude Code, Cursor, etc.) are excellent at writing code but bad at planning entire projects from scratch. They lose track of requirements, skip steps, and produce inconsistent architectures. Sago solves the planning problem so the coding agent can focus on what it's good at — writing code.

---

Table of contents

• Quick start
• How it works
• Using with Claude Code
• Using with other agents
• Mission control
• Trace dashboard
• Commands
• Configuration
• Task format
• Why sago
• Sago vs GSD
• Development
• Acknowledgements
• License

---

Quick start

1. Install

pip install -e .

Requires Python 3.11+.

2. Set up your LLM provider

Create a .env file (or export the variables):

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=sk-your-key-here

Any LiteLLM-supported provider works — OpenAI, Anthropic, Azure, Gemini, etc. The LLM is used for plan generation only.

3. Create a project

sago init

Sago prompts for a project name and description. It generates the project scaffold:

my-project/
├── PROJECT.md          ← Vision, tech stack, architecture
├── REQUIREMENTS.md     ← What the project must do
├── PLAN.md             ← Atomic tasks with verify commands (after sago plan)
├── STATE.md            ← Progress log (updated as tasks complete)
├── CLAUDE.md           ← Instructions for the coding agent
├── IMPORTANT.md        ← Rules the coding agent must follow
└── .planning/          ← Runtime artifacts (cache, traces)

If you provide a description during init, the AI generates PROJECT.md and REQUIREMENTS.md for you. Otherwise, fill them in yourself.

4. Generate the plan

sago plan

Sago reads your PROJECT.md and REQUIREMENTS.md, detects your environment (Python version, OS, platform), and generates a PLAN.md with:

• Atomic tasks grouped into phases
• Task-level dependency ordering via depends_on
• Verification commands for each task
• A list of third-party packages needed
• Semantic validation (duplicate IDs, dependency cycles, missing fields, etc.)

Sago validates the plan automatically — if it finds structural errors (cycles, invalid dependencies, missing task IDs), it retries once with error feedback. You're shown validation results and asked to accept or reject before the plan is written.

5. Hand off to your coding agent

Point your coding agent at the project and tell it to follow the plan:

Claude Code:

cd my-project
claude
# Claude Code reads CLAUDE.md automatically and follows the plan

Cursor / Other agents: Open the project directory. The agent should read PLAN.md and execute tasks in order, running each <verify> command to confirm the task is done.

6. Watch your agent work

In a separate terminal, launch mission control:

sago watch

This opens a live dashboard in your browser that shows task completion, file activity, and phase progress — updated every second as your coding agent works through the plan.

7. Review between phases

After your coding agent finishes a phase, run the phase gate:

sago replan

This reviews the completed work, shows findings (warnings, suggestions), saves the review to STATE.md, shows actionable recommendations (e.g. "task failed 2+ times — consider replanning"), and optionally lets you adjust the plan before the next phase. Just press Enter to skip replanning if the review looks good.

8. Track progress

sago status              # quick summary + recommendations
sago status -d           # detailed per-task breakdown
sago lint-plan           # validate plan without running anything

---

How it works

┌─────────────────────────────────────────────────────┐
│  1. SPEC                                            │
│     You write PROJECT.md + REQUIREMENTS.md          │
│     (or describe your idea and sago generates them) │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  2. PLAN (sago)                                     │
│     Sago calls an LLM to generate PLAN.md:          │
│     - Atomic tasks with verification commands       │
│     - Task-level dependencies (depends_on DAG)      │
│     - Environment-aware (Python version, OS)        │
│     - Lists required third-party packages           │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  3. BUILD (your coding agent)                       │
│     Claude Code / Cursor / Aider reads PLAN.md      │
│     and executes tasks one by one:                  │
│     - Follows <action> instructions                 │
│     - Runs <verify> commands                        │
│     - Updates STATE.md with progress                │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  4. REVIEW (sago replan)                            │
│     Between phases, reviews completed work:         │
│     - Runs ReviewerAgent on finished phases         │
│     - Shows warnings, suggestions, issues           │
│     - Saves review to STATE.md                      │
│     - Optionally updates the plan with feedback     │
└──────────────────────┬──────────────────────────────┘
                       ▼
              (repeat 3→4 for each phase)
                       ▼
┌─────────────────────────────────────────────────────┐
│  5. TRACK (sago)                                    │
│     sago status shows progress                      │
│     Dashboard shows real-time updates               │
└─────────────────────────────────────────────────────┘

Sago is the project manager. Your coding agent is the developer. The markdown files are the contract between them.

---

Using with Claude Code

Sago generates a CLAUDE.md file during sago init that Claude Code reads automatically. It tells Claude Code how to follow the plan, execute tasks in order, and update STATE.md.

sago init my-project --prompt "A weather dashboard with FastAPI and PostgreSQL"
cd my-project
sago plan
claude

Claude Code picks up CLAUDE.md on startup and understands the task format. You can say something like:

"Follow the plan in PLAN.md. Start with task 1.1 and work through each task in order."

Or let it read CLAUDE.md and figure it out — the instructions are already there.

---

Using with Cursor

sago init my-project --prompt "A weather dashboard with FastAPI and PostgreSQL"
cd my-project
sago plan

Copy the sago workflow instructions into Cursor's rules file so the agent knows how to work:

cp CLAUDE.md .cursorrules

Then open the project in Cursor and use Agent mode. Tell it:

"Read PLAN.md and execute each task in order. After each task, run the verify command and update STATE.md."

Cursor's agent will follow the plan the same way Claude Code does.

---

Using with Aider

sago init my-project --prompt "A weather dashboard with FastAPI and PostgreSQL"
cd my-project
sago plan

Feed the plan and project context to Aider:

aider --read PLAN.md --read PROJECT.md --read REQUIREMENTS.md

Then tell it which task to work on:

"Execute task 1.1 from PLAN.md. Create the files listed, follow the action instructions, then run the verify command."

Work through tasks one at a time since Aider works best with focused, single-task instructions.

---

Using with any other agent

Sago's output is just markdown files. Any coding agent that can read files and run commands works. The agent needs to:

1. Read PLAN.md — the structured plan with phases and tasks
2. Read PROJECT.md — the project vision, tech stack, and architecture
3. Read REQUIREMENTS.md — what the project must do
4. If PLAN.md has a <dependencies> block, install those packages first
5. Follow task dependencies — check depends_on attributes to determine task order (tasks without depends_on depend on all prior tasks in their phase)
6. Run each task's <verify> command — it must exit 0 before moving on
7. Update STATE.md after each task with pass/fail status

The CLAUDE.md file generated by sago init contains these instructions in a format most agents understand. Rename or copy it to whatever your agent expects (.cursorrules, .github/copilot-instructions.md, etc.).

---

Mission control

While your coding agent builds the project, run mission control in a separate terminal:

sago watch                   # launch dashboard (auto-opens browser)
sago watch --port 8080       # use a specific port
sago watch --path ./my-app   # point to a different project

The dashboard shows:

• Overall progress — progress bar with task count and percentage
• Phase tree — every phase and task with live status icons (done, failed, pending)
• File activity — new and modified files detected in the project directory
• Dependencies — packages listed in PLAN.md
• Per-phase progress bars — at a glance, which phases are done

It polls STATE.md every second — as your coding agent marks tasks [✓] or [✗], the dashboard updates automatically. No extra dependencies (stdlib HTTP server + os.stat).

Trace dashboard

To view the planning trace after sago plan:

sago trace                   # opens dashboard for the last trace
sago trace --demo            # sample data, no API key needed

---

Commands

sago init                            # interactive: prompts for name + description
sago init [name]                     # quick scaffold with templates
sago init [name] --prompt "desc"     # generate spec files from a prompt via LLM
sago init -y                         # non-interactive, all defaults
sago plan                            # generate PLAN.md from requirements
sago plan --yes                      # auto-accept plan without confirmation
sago lint-plan                       # validate PLAN.md for structural/semantic issues
sago lint-plan --strict              # treat warnings as errors
sago lint-plan --json                # machine-readable JSON output
sago replan                          # phase gate: review completed work, optionally update plan
sago watch                           # launch mission control dashboard
sago watch --port 8080               # use a specific port
sago status                          # show project progress + recommendations
sago status -d                       # detailed per-task breakdown
sago trace                           # open dashboard for the last trace
sago trace --demo                    # open dashboard with sample data

Flags for sago plan

Flag	What it does
--force / -f	Regenerate PLAN.md if it already exists
--yes / -y	Auto-accept plan without confirmation prompt
--trace	Open live dashboard during planning

---

Configuration

Create a .env file in your project directory:

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=your-key-here
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=4096
LOG_LEVEL=INFO

Any LiteLLM-supported provider works. Set LLM_MODEL to the provider's model identifier (e.g., claude-sonnet-4-5-20250929, gpt-4o, gemini/gemini-2.0-flash).

---

Task format

Tasks in PLAN.md use XML inside markdown:

<phases>
  <dependencies>
    <package>flask>=2.0</package>
    <package>sqlalchemy>=2.0</package>
  </dependencies>

  <review>
    Review instructions for post-phase code review...
  </review>

  <phase name="Phase 1: Setup">
    <task id="1.1">
      <name>Create config module</name>
      <files>src/config.py</files>
      <action>Create configuration with pydantic settings...</action>
      <verify>python -c "import src.config"</verify>
      <done>Config module imports successfully</done>
    </task>

    <task id="1.2" depends_on="1.1">
      <name>Add database layer</name>
      <files>src/db.py</files>
      <action>Create database module using config...</action>
      <verify>python -c "import src.db"</verify>
      <done>Database module imports successfully</done>
    </task>
  </phase>
</phases>

• <dependencies> — third-party packages needed, with version constraints
• <review> — instructions for reviewing each phase's output
• <task> — atomic unit of work with files, action, verification, and done criteria
• depends_on — optional attribute on <task> listing comma-separated task IDs this task depends on. Omit it to depend on all prior tasks in the phase (sequential by default). Use it to express that a task has no dependencies or only specific ones, enabling parallel execution of independent tasks.

---

Why sago

The planning problem. AI coding agents are great at writing code for a well-defined task. But ask them to build an entire project from a vague description and they lose track of requirements, skip steps, pick incompatible dependencies, and produce inconsistent architectures. The gap isn't in code generation — it's in project planning.

Sago fills that gap. It uses an LLM to generate a structured, verified plan with atomic tasks, dependency ordering, and environment-aware dependency suggestions. Then it hands off to whatever coding agent you prefer.

Model-agnostic planning. Sago uses LiteLLM for plan generation, so you're not locked into any provider. Use OpenAI, Anthropic, Azure, Gemini, Mistral — whatever gives you the best plans.

Agent-agnostic execution. Sago doesn't care what builds the code. Claude Code, Cursor, Aider, Copilot, a human — anything that can read markdown and follow instructions. Sago generates the plan; you choose the builder.

Spec-first, always. Every sago project has a reviewable spec (PROJECT.md, REQUIREMENTS.md) and a reviewable plan (PLAN.md) before any code is written. You see exactly what will be built and can adjust before spending time or tokens on execution.

---

Sago vs GSD

GSD (Get Shit Done) is a great project that inspired sago. Both solve the same core problem — AI coding agents are bad at planning — but they take different approaches.

	Sago	GSD
What it is	Standalone CLI tool (pip install)	Prompt system loaded into Claude Code
Coding agent	Any — Claude Code, Cursor, Aider, Copilot, a human	Claude Code only (uses its sub-agent spawning)
Planning LLM	Any LiteLLM provider (OpenAI, Anthropic, Gemini, etc.)	Claude (via Claude Code)
Execution	You hand off to your coding agent	GSD spawns executor agents in fresh contexts
Context management	Not sago's concern — your agent manages its own context	Core feature — fights "context rot" by spawning fresh 200k-token windows per task
Phase transitions	Explicit phase gate (sago replan) with code review and optional replan	Automatic wave-based execution with /gsd:execute-phase
Research	You write PROJECT.md + REQUIREMENTS.md (or generate from a prompt)	Spawns parallel researcher agents to investigate the domain
Review	ReviewerAgent runs between phases via sago replan, saves findings to STATE.md	/gsd:verify-work with interactive debug agents

When to use GSD: You use Claude Code exclusively and want a fully automated pipeline — research, plan, execute, verify — all within Claude Code's sub-agent system. GSD's context rotation (fresh windows per task) is its killer feature for large projects.

When to use sago: You want to use different coding agents (or switch between them), want to use a non-Claude LLM for planning, or prefer an explicit human-in-the-loop workflow where you review the plan and gate phase transitions yourself. Sago is the project manager; you pick the developer.

---

Development

pip install -e ".[dev]"       # install with dev dependencies

pytest                        # run all tests
pytest tests/test_parser.py -v              # single file
pytest tests/test_parser.py::test_name -v   # single test

ruff check src/               # lint
black src/ tests/             # format
mypy src/                     # type check (strict mode)
skylos src/                   # dead code detection

---

Acknowledgements

This project was vibecoded with Claude Code.

Sago takes inspiration from:

• GSD (Get Shit Done) — spec-driven development and sub-agent orchestration for Claude Code
• Claude Flow — multi-agent orchestration platform with wave-based task coordination

Dead code is kept in check by Skylos.

---

License

Apache 2.0. See LICENSE.