festival

Festival

A standardized workspace and workflow for solving difficult, multi-faceted problems with AI.

To use AI to solve hard problems you need three things: context, direction, and verification. Festival provides a structured layer for each, resulting in dramatically fewer tokens and less time spent getting to the outcome you want.

Get started (takes ~5 minutes).

graph TD
    HP["<b>Hard, multi-faceted problem</b>"]

    HP --> C["<b>Context</b><br/><br/>a campaign workspace with<br/>all projects, docs, and research"]
    HP --> D["<b>Direction</b><br/><br/>a structured plan that AI agents<br/>can execute, pause, and resume"]
    HP --> V["<b>Verification</b><br/><br/>all work captured in reviewable<br/>files you can trace and audit"]

    C --> O["<b>Fewer tokens · less time · better outcomes</b>"]
    D --> O
    V --> O

Install

npm / pnpm / bun:

npm install -g @obedience-corp/festival

macOS:

brew install --cask Obedience-Corp/tap/festival

Arch Linux:

yay -S festival-bin

Debian/Ubuntu: Download .deb from releases

Windows: Stable Windows packages are temporarily paused while support is being hardened. For now, use WSL2 and the Linux install method above.

Requirements

• git is required. camp and fest use git internally for campaign init, project management, template sync, and commit-aware workflows.
• scc is recommended but optional. Without it, camp leverage features will not work.

Updating Templates After Upgrades

Festival releases may include updated methodology files, agents, examples, and templates. Upgrading the fest binary does not automatically rewrite those files because users often customize their .festival/ methodology directory and template files.

When a release includes template changes, update in two explicit steps:

# Refresh the local system template cache
fest system sync

# Preview campaign methodology/template changes before applying them
fest system update --dry-run

# Apply interactively, or create backups before updating
fest system update
fest system update --backup

Use fest system update --force only when you intentionally want to overwrite local changes. The manual update flow protects customized templates from accidental replacement.

Quick Start

# Shell integration (add one setup path to ~/.zshrc)

# Preferred when installed with install.sh:
source ~/.local/share/festival/shell/festival.zsh

# Or, if no helper file is installed:
eval "$(camp shell-init zsh)"
eval "$(fest shell-init zsh)"

# Create a campaign
camp init my-project && cd my-project

# Add a project
camp project add https://github.com/you/your-repo

# Create your first festival
fest create festival --name "my-first-feature" --type standard

# Fill the generated REPLACE markers in the new festival files
# Then validate before execution
fest validate

# Start working
fest next

After installing, see the quick start guide for shell setup and first steps.

The Problem

If you work on more than a few things at once, staying organized becomes a job of its own.

Your work spreads across repositories, documents, chats, notes, bookmarks, and AI conversations. Finding where something belongs becomes work. Remembering what you were doing becomes work. Switching between efforts becomes work.

AI makes this harder, not easier. It generates plans, code, research, and tasks faster than you can file them. The bottleneck moves from producing work to organizing it.

So every new AI session starts from zero. No memory of the larger goal, no structure for multi-step work, no way to pick up where you left off. You re-explain the same context, get inconsistent results, and lose coherence across sessions.

Festival is the organizational layer for work done with AI. Instead of asking "where should this go?" you put it in the campaign it belongs to. Instead of asking "what was I working on?" you resume the campaign. To turn that organization into outcomes, Festival gives every mission three things:

1. Context: a workspace that holds all projects, docs, and planning for a mission in one place
2. Direction: structured plans that AI agents can pick up, execute, and resume without losing the thread
3. Verification: completion criteria and reviewable output baked into the workflow, not bolted on after

What Festival Does

Festival ships two CLIs (camp and fest) that solve the three problems above.