{"id":46886465,"url":"https://github.com/obedience-corp/festival","last_synced_at":"2026-05-30T08:01:14.583Z","repository":{"id":314347297,"uuid":"1053617248","full_name":"Obedience-Corp/festival","owner":"Obedience-Corp","description":"Organized AI Workspace | Complex Multi Phase Planning | Auditable Agent Workflows","archived":false,"fork":false,"pushed_at":"2026-05-27T07:01:57.000Z","size":3862,"stargazers_count":15,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T09:05:28.869Z","etag":null,"topics":["ai","ai-agents","ai-tools","ai-workflow","ai-workflow-optimization","ai-workspace","autonomous-agents","camp","claude-code","cli","codex","developer-tools","fest","festival","festival-methodology","goal-oriented-ai","hierarchical-agents","opencode","project-management","token-optimization"],"latest_commit_sha":null,"homepage":"https://fest.build","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Obedience-Corp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T17:35:11.000Z","updated_at":"2026-05-27T07:02:00.000Z","dependencies_parsed_at":"2025-09-12T00:56:42.384Z","dependency_job_id":"7b173fc3-a012-44da-aeb3-195ee976941e","html_url":"https://github.com/Obedience-Corp/festival","commit_stats":null,"previous_names":["lancekrogers/festival-methodology","obedience-corp/festival"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Obedience-Corp/festival","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Obedience-Corp%2Ffestival","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Obedience-Corp%2Ffestival/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Obedience-Corp%2Ffestival/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Obedience-Corp%2Ffestival/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Obedience-Corp","download_url":"https://codeload.github.com/Obedience-Corp/festival/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Obedience-Corp%2Ffestival/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33684413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-tools","ai-workflow","ai-workflow-optimization","ai-workspace","autonomous-agents","camp","claude-code","cli","codex","developer-tools","fest","festival","festival-methodology","goal-oriented-ai","hierarchical-agents","opencode","project-management","token-optimization"],"created_at":"2026-03-10T22:12:18.577Z","updated_at":"2026-05-30T08:01:14.577Z","avatar_url":"https://github.com/Obedience-Corp.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Festival\n\n![Festival Banner](docs/images/festival_banner.png)\n\n**A standardized workspace and workflow for solving difficult, multi-faceted problems with AI.**\n\nTo 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.\n\n\u003e [Get started](https://docs.fest.build/getting-started/quickstart) (takes ~5 minutes).\n\n```mermaid\ngraph TD\n    HP[\"\u003cb\u003eHard, multi-faceted problem\u003c/b\u003e\"]\n\n    HP --\u003e C[\"\u003cb\u003eContext\u003c/b\u003e\u003cbr/\u003e\u003cbr/\u003ea campaign workspace with\u003cbr/\u003eall projects, docs, and research\"]\n    HP --\u003e D[\"\u003cb\u003eDirection\u003c/b\u003e\u003cbr/\u003e\u003cbr/\u003ea structured plan that AI agents\u003cbr/\u003ecan execute, pause, and resume\"]\n    HP --\u003e V[\"\u003cb\u003eVerification\u003c/b\u003e\u003cbr/\u003e\u003cbr/\u003eall work captured in reviewable\u003cbr/\u003efiles you can trace and audit\"]\n\n    C --\u003e O[\"\u003cb\u003eFewer tokens · less time · better outcomes\u003c/b\u003e\"]\n    D --\u003e O\n    V --\u003e O\n```\n\n## Install\n\n**npm / pnpm / bun:**\n\n```bash\nnpm install -g @obedience-corp/festival\n```\n\n**macOS:**\n\n```bash\nbrew install --cask Obedience-Corp/tap/festival\n```\n\n**Arch Linux:**\n\n```bash\nyay -S festival-bin\n```\n\n**Debian/Ubuntu:** Download `.deb` from [releases](https://github.com/Obedience-Corp/festival/releases/latest)\n\n**Windows:** Stable Windows packages are temporarily paused while support is being hardened.\nFor now, use WSL2 and the Linux install method above.\n\n## Requirements\n\n- `git` is required. `camp` and `fest` use git internally for campaign init, project management, template sync, and commit-aware workflows.\n- `scc` is recommended but optional. Without it, `camp leverage` features will not work.\n\n## Updating Templates After Upgrades\n\nFestival 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.\n\nWhen a release includes template changes, update in two explicit steps:\n\n```bash\n# Refresh the local system template cache\nfest system sync\n\n# Preview campaign methodology/template changes before applying them\nfest system update --dry-run\n\n# Apply interactively, or create backups before updating\nfest system update\nfest system update --backup\n```\n\nUse `fest system update --force` only when you intentionally want to overwrite local changes. The manual update flow protects customized templates from accidental replacement.\n\n## Quick Start\n\n```bash\n# Shell integration (add to ~/.zshrc)\neval \"$(camp shell-init zsh)\"\neval \"$(fest shell-init zsh)\"\n\n# Create a campaign\ncamp init my-project \u0026\u0026 cd my-project\n\n# Add a project\ncamp project add https://github.com/you/your-repo\n\n# Create your first festival\nfest create festival --name \"my-first-feature\" --type standard\n\n# Fill the generated REPLACE markers in the new festival files\n# Then validate before execution\nfest validate\n\n# Start working\nfest next\n```\n\nAfter installing, see the [quick start guide](https://docs.fest.build/getting-started/quickstart/) for shell setup and first steps.\n\n## The Problem\n\nIf you work on more than a few things at once, staying organized becomes a job of its own.\n\nYour 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.\n\nAI 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.\n\nSo 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.\n\nFestival 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:\n\n1. **Context**: a workspace that holds all projects, docs, and planning for a mission in one place\n2. **Direction**: structured plans that AI agents can pick up, execute, and resume without losing the thread\n3. **Verification**: completion criteria and reviewable output baked into the workflow, not bolted on after\n\n## What Festival Does\n\nFestival ships two CLIs (`camp` and `fest`) that solve the three problems above.\n\n**`camp`** manages campaigns: isolated workspaces that hold all the projects, docs, research, and planning for a single mission, a high-level purpose like your startup, your job, or a hobby. A mission grows over time, and the campaign grows with it. It gives you instant navigation across everything in the workspace, project lifecycle management, and shell shortcuts that make `cd` obsolete.\n\n**`fest`** manages festivals: structured plans that break work into phases, sequences, and tasks. The hierarchy is designed for AI agents to execute autonomously, pause, and resume without context loss. Run `fest next` and the agent gets its next task with full surrounding context. Run `fest commit` and every commit traces back to the plan.\n\n### Where Festival Fits\n\nFestival is a **planning and context layer**, not a runtime orchestrator. It doesn't spawn agents or manage their processes. It gives them the structure, context, and goals they need to work autonomously. Runtime orchestrators tell agents what to do next. Festival tells agents *why* they're doing it, what success looks like, and where they are in a larger mission.\n\nThe context model is persistent and filesystem-based. Plans survive across sessions, days, and weeks, not just a single agent run. Festival is agent-agnostic: it works with Claude Code, Codex, Aider, OpenCode, or any CLI tool that can read files and run commands. Use an orchestrator to manage parallel agents, and Festival to give each agent the plan and context it needs.\n\n### Festival Methodology\n\nFestival is built around Festival Methodology: a hierarchical, goal-based planning system for human-directed AI execution. It preserves both agent context and operator context, uses ingest and planning phases to reduce chat iteration up front, and leaves a durable pre- and post-execution audit trail so you can scale difficult knowledge work without micromanaging every decision. Read the full methodology guide in the [`fest` repo](https://github.com/Obedience-Corp/fest/blob/main/methodology/README.md).\n\n### Real Example\n\nHere's what `obey-campaign` looks like, a real campaign that orchestrates Obedience Corp's internal platform and product stack:\n\n```\nobey-campaign/\n├── projects/                     # 19 project submodules\n│   ├── camp/                     # Campaign CLI\n│   ├── fest/                     # Festival planning CLI\n│   ├── festival/                 # Distribution repo (this one)\n│   ├── obey-platform-monorepo/   # Core platform\n│   ├── obey-chat/                # Chat client\n│   ├── guild-core/               # Reference implementation\n│   ├── obediencecorp.com/        # Company website\n│   ├── prototypes/               # Experiment sandbox\n│   └── ...                       # 11 more projects\n├── festivals/                    # Festival lifecycle workspace\n│   ├── planning/                 # Festivals being designed\n│   ├── active/                   # Currently executing\n│   ├── ready/                    # Prepared, awaiting execution\n│   ├── ritual/                   # Recurring processes\n│   └── dungeon/                  # completed/ | archived/ | someday/\n├── workflow/                     # Intents, code reviews, pipelines\n├── ai_docs/                      # AI research and documentation\n├── docs/                         # Human-authored documentation\n└── CLAUDE.md                     # Agent instructions\n```\n\nEvery project, every plan, every piece of context for this mission lives here. `cgo p fest` jumps to the fest project. `fgo` toggles between a festival and its linked project. Everything is navigable by both humans and AI agents.\n\n## Navigation\n\nShell integration gives you shorthand functions that make navigating a campaign instant. Add these to your shell config:\n\n```bash\neval \"$(camp shell-init zsh)\"   # gives you: cgo, cr, csw, cint\neval \"$(fest shell-init zsh)\"   # gives you: fgo, fls\n```\n\n### cgo: jump anywhere in your workspace\n\n`cgo` wraps `camp go` with real `cd` behavior. It's the fastest way to move around:\n\n```bash\ncgo                   # Toggle between campaign root and last location\ncgo p                 # Jump to projects/\ncgo p api             # Fuzzy-find \"api\" in projects/ (matches api-server, api-gateway, etc.)\ncgo f                 # Jump to festivals/\ncgo w                 # Jump to workflow/\ncgo wt api@feat       # Jump to a worktree branch\n```\n\nSingle-letter category shortcuts (`p`, `f`, `w`, `a`, `d`, `i`, `wt`, `du`, `cr`, `de`) map to top-level campaign directories. After the category, any additional argument is a fuzzy search. `cgo p mono` lands you in `obey-platform-monorepo/`. Tab completion works at every level.\n\nYou can also run a command without leaving your current directory:\n\n```bash\ncgo -c p api ls       # Run ls inside projects/api-* without cd'ing\ncr just build         # Run \"just build\" from campaign root\n```\n\n### fgo: toggle between a festival and its linked project\n\n`fgo` wraps `fest go`. Its standout feature is bidirectional toggling:\n\n```bash\nfgo                   # From a festival -\u003e jump to its linked project\n                      # From a linked project -\u003e jump back to the festival\n\nfgo 2                 # Jump to phase 002\nfgo 2/1               # Jump to phase 2, sequence 1\nfgo active            # Jump to festivals/active/\nfgo active my-fest    # Jump to a specific active festival\n```\n\nLink a festival to a project once (`fgo link`) and `fgo` with no args toggles between them forever. Named shortcuts work too: `fest go map n` bookmarks the current directory, then `fgo -n` jumps there.\n\n### Other shorthands\n\n| Shorthand | Expands to | What it does |\n|-----------|------------|--------------|\n| `csw`     | `camp switch` | Switch between campaigns (fuzzy match + interactive picker) |\n| `cint`    | `camp intent add` | Quick-capture an idea to the intent inbox |\n| `cr`      | `camp run` | Run a command from campaign root |\n| `fls`     | `fest list` | List festivals by status |\n\n### Concept shortcuts\n\n`camp` supports shorthand for subcommands too. `camp p` expands to `camp project`, so these are identical:\n\n```bash\ncamp p commit -m \"fix bug\"    # Same as: camp project commit -m \"fix bug\"\ncamp p add \u003curl\u003e              # Same as: camp project add \u003curl\u003e\ncamp p list                   # Same as: camp project list\n```\n\n## CLI Overview\n\nFull reference: [fest CLI](https://docs.fest.build/cli-reference/fest/) | [camp CLI](https://docs.fest.build/cli-reference/camp/)\n\n### camp: workspace management\n\n```bash\ncamp init my-startup             # Create a campaign\ncamp project add \u003curl\u003e           # Add a project as submodule\ncamp p commit -m \"fix auth\"      # Commit in a project (auto-stages all changes)\ncamp status all                  # Dashboard of all project statuses\ncamp doctor                      # Health check the workspace\ncamp intent add \"idea\"           # Capture an idea to the inbox\ncamp leverage                    # Measure productivity leverage across projects\n```\n\n### fest: planning and execution\n\nThe core workflow: create a festival, then let `fest next` drive execution.\n\n```bash\nfest create festival --name \"my-feature\" --type standard  # Scaffold the beginner path\nfest next                        # Get the next task with layered context (festival -\u003e phase -\u003e sequence -\u003e task)\nfest task completed              # Mark the current task done\nfest workflow advance            # Complete a workflow step and move to the next\nfest status                      # View progress across all levels\nfest commit -m \"implement auth\"  # Git commit with automatic festival/task reference\nfest understand                  # Teach an AI agent the full methodology\n```\n\n`fest next` is the entry point for agents. It resolves what to do next, includes surrounding context from every level of the hierarchy, and respects workflow ordering and completion criteria.\n\n```mermaid\ngraph LR\n    A[fest next] --\u003e B[Do the work]\n    B --\u003e C[fest task completed]\n    C --\u003e D[fest commit]\n    D --\u003e A\n```\n\n## Claude Code Plugin\n\nInstall the Festival plugin for Claude Code to get `fest` and `camp` CLI tools, slash commands, methodology skills, and specialized agents in one step:\n\n```bash\nclaude plugin add --source git-subdir --url Obedience-Corp/festival --path claude-plugin\n```\n\nIf `fest` and `camp` aren't already installed, the plugin installs them automatically on first session. It also checks for updates once per day and notifies you when a new release is available.\n\n### What you get\n\n| Component | Examples |\n|-----------|---------|\n| **Slash commands** | `/fest-next`, `/fest-create`, `/fest-done`, `/fest-commit`, `/fest-validate`, `/camp-intent`, `/camp-init` |\n| **Skills** | Auto-activating methodology knowledge, execution workflows, planning guidance |\n| **Agents** | `fest-planner` for designing festivals, `fest-executor` for working through tasks |\n\n## Documentation\n\nFull documentation at **[docs.fest.build](https://docs.fest.build)**:\n\n- [Methodology Overview](https://docs.fest.build/methodology/overview/): core principles and concepts\n- [Agent Workflows](https://docs.fest.build/guides/agent-workflows/): using Festival with AI coding tools\n- [First Festival Tutorial](https://docs.fest.build/tutorials/first-festival/): end-to-end walkthrough\n- [CI Integration](https://docs.fest.build/tutorials/ci-integration/): release smoke ownership and launch-path verification\n\n## License\n\n[Functional Source License 1.1 (FSL-1.1-ALv2)](LICENSE)\n\nBuilt by [Obedience Corp](https://obediencecorp.com). AI that does what you want, the way you want it done.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobedience-corp%2Ffestival","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobedience-corp%2Ffestival","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobedience-corp%2Ffestival/lists"}