saga

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@[email protected]

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-blocker to 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: