SAGA
Structured Autonomous Goal Achievement - Transform epic ideas into shipped code through structured planning, autonomous execution, and continuous journaling.
A complete development lifecycle from collaborative planning through story breakdown and rigorous implementation. Plans become stories. Workers execute autonomously. Everything is documented.
flowchart LR
A[📝 Epic] -->|VISION| B[📋 Stories]
B -->|BREAKDOWN| C[⚡ Implement]
C -->|TDD| D((✅))
A -.- A1[epic.json]
B -.- B1[story.json]
C -.- C1[journal.md]
Table of Contents
- Quick Start
- How It Works
- Key Features
- Skills Reference
- Workflow Examples
- Directory Structure
- Non-Negotiable Rules
- Plugin Architecture
- CLI Package
- Requirements
- Contributing
Quick Start
Installation
Option 1: From GitHub (Latest)
# Add the marketplace
/plugin marketplace add Roeia1/saga
# Install latest version
/plugin install saga@saga-core
Option 2: Specific Version
# Install a specific version
/plugin install saga@saga-core@1.0.0
Option 3: Interactive
# Browse and install via menu
/plugin
# Select "Browse Plugins" → find saga → install
See CHANGELOG.md for version history.
Initialize Your Project
# Navigate to your project
cd your-project
# Start Claude Code
claude
# Initialize SAGA
> /init
This creates the .saga/ directory structure:
.saga/
├── epics/ # Epic definitions (JSON)
├── stories/ # Story definitions, tasks, and journals
├── archive/ # Completed story archives
└── worktrees/ # Git worktrees for story isolation (gitignored)
Your First Plan
# 1. Plan your work (collaborative discussion → stories)
> /plan user authentication with OAuth
# 2. Implement a story autonomously
> /execute-story login-flow
# 3. If blocked, resolve and continue
> /resolve-blocker login-flow
> /execute-story login-flow
How It Works
Development Lifecycle
| Phase | Focus | Output |
|---|---|---|
| Planning | WHAT + HOW | Collaborative discussion → stories (standalone or epic-based) |
| Story Execution | DO the work | Tested, documented, reviewed code |
Planning
Tell Claude what you want to build in natural language:
> /plan real-time notifications for order updates
Claude will:
- Explore the codebase for relevant context
- Collaborate with you through a deep discussion about goals, scope, approach, and tradeoffs
- Propose the right structure: a single story for cohesive goals, or an epic with multiple stories for larger goals
- Create stories with git branches, worktrees, and draft PRs
Output: Stories in .saga/stories/ (and optionally .saga/epics/ for multi-story plans)
Story Execution
Stories are executed autonomously using the /execute-story command:
> /execute-story websocket-setup
The orchestrator spawns worker Claude instances that complete tasks incrementally. Workers exit with:
- FINISH - All tasks complete
- BLOCKED - Needs human decision (use
/resolve-blockerto unblock) - TIMEOUT - Max time exceeded
Key Features
Test-Driven Development (Non-Negotiable)
Tests are written before implementation. After test creation, they can only be modified with explicit user approval. This isn't optional—it's enforced.
Continuous Journaling
Workers document progress throughout execution:
- Tasks completed and their outcomes
- Technical decisions and their reasoning
- Blockers and resolutions
- Key learnings and insights
Output: journal.md alongside each story
Parallel Execution with Git Worktrees
Work on multiple stories simultaneously:
.saga/worktrees/
├── websocket-setup/ # Full project checkout
├── event-handlers/ # Full project checkout
└── ui-components/ # Full project checkout
Each worktree is isolated. Commit, push, and test independently.
Dynamic Story Status
No manual status updates. Status is derived from filesystem and git state: