# Festival

> A CLI planning layer for AI coding agents.

Festival is a free, open-source CLI tool that structures complex software development work for AI agents. It introduces a hierarchical planning model: Campaigns > Festivals > Phases > Sequences > Tasks. Developers create campaigns to organize multi-project workspaces, then plan festivals (goal-oriented project plans) that AI agents like Claude Code, Codex, or Aider can execute autonomously.

## How It Works

1. **Campaigns** (camp CLI) - Top-level workspace containers that hold multiple projects, docs, and festivals. Navigate instantly with `cgo` shell integration.
2. **Festivals** (fest CLI) - Goal-oriented plans broken into phases (INGEST, PLAN, IMPLEMENT), sequences (cohesive task groups), and tasks (atomic, implementation-ready work units).
3. **Planning** - Human and AI collaborate to define goals, gather requirements, design architecture, and create detailed task specifications.
4. **Execution** - AI agents run `fest next` to get the next task with full context, execute it, mark complete, and continue. All state lives in the filesystem as markdown files.
5. **Context Persistence** - Plans, progress, and context survive across sessions. Any agent can pick up where the last one left off with `fest next`.

## Key Features

- **Two CLI tools**: `fest` (festival management) and `camp` (campaign management)
- **Structured planning**: Phases, sequences, and tasks with quality gates (testing, review, iterate)
- **Agent-agnostic**: Works with Claude Code, Codex, Aider, or any CLI-based AI tool
- **Zero config**: Works in 30 seconds after install
- **Filesystem-native**: All state stored as markdown, no database or cloud dependency
- **Shell integration**: `cgo`, `fgo`, `fls` for instant navigation between campaigns and festivals
- **Festival types**: Standard, implementation, research, ritual templates
- **Validation**: `fest validate` checks structure, quality gates, and task completeness before execution

## Use Cases

- Structuring complex multi-project software builds for AI agent execution
- Managing multiple concurrent development initiatives with different AI agents
- Planning and executing phased software development (requirements, design, implementation)
- Maintaining context and progress across AI coding sessions

## Links

- Website: https://fest.build
- Documentation: https://docs.fest.build/
- Installation: https://docs.fest.build/getting-started/installation/
- Quick Start: https://docs.fest.build/getting-started/quickstart/
- GitHub: https://github.com/Obedience-Corp/festival