Festival Planning

Start Here

fest understand methodology
fest understand structure
fest understand tasks
fest understand rules
fest types festival

Naming Rules (Automation-Critical)

• Phase dir: NNN_UPPER_CASE/ (e.g., 001_IMPLEMENT/)
• Sequence dir: NN_lower_snake_case/ (e.g., 01_auth_module/)
• Task file: NN_lower_snake_case.md (e.g., 01_create_handler.md)

Every sequence should include SEQUENCE_GOAL.md.

Festival Types (Choose Before Scaffolding)

Use fest types festival / fest types festival show <type> as source of truth.

• standard: Full planning + implementation (recommended for most work)
• implementation: Execution-only (use when requirements already exist)
• research: Investigation and exploration
• ritual: Recurring processes

fest create festival --name "<name>" --type standard
fest create festival --name "<name>" --type implementation
fest create festival --name "<name>" --type research
fest create festival --name "<name>" --type ritual --dest ritual

Phase Types

• planning: Workflow phase for architecture/decisions (WORKFLOW.md, no numbered sequences)
• research: Investigation and findings
• ingest: Normalizing incoming context/specs
• implementation: Sequence-driven coding (numbered sequences/tasks, quality gates)
• review: Freeform acceptance/signoff
• non_coding_action: Operational actions

fest create phase --name "001_IMPLEMENT" --type implementation

Create / Promote

fest create festival
fest create phase
fest create sequence
fest create task

fest promote
fest validate

Link + Navigation

fest link [path]
fest link --show
fest links
fest unlink

# Shell helper after eval "$(fest shell-init zsh)"
fgo
fgo project
fgo fest

Scaffolding from Plan

fest scaffold from-plan --plan STRUCTURE.md --name my-festival

Standalone WORKFLOW.md (Outside a Festival)

For a short, repeatable step checklist that does not need a full festival (phases/sequences/tasks), scaffold a standalone WORKFLOW.md instead:

fest create workflow <name>
# or, equivalently:
fest workflow create <name>

Both accept --steps '<json>' / --steps-file <file> for agent mode, --type for the standalone workflow type, and --no-init for advanced mode (skip runtime init and lazily bootstrap a tracked run on first fest workflow advance). See the fest-standalone-workflows skill for the full step-JSON schema and execution loop. Reach for a full festival instead when the work needs multi-phase planning, sequencing, or quality gates.

Common Mistakes

• Using fest link --project ... (invalid flag).
• Picking implementation type when requirements are still unclear.
• Using noncompliant naming patterns (P1-..., S1-...).
• Treating fest scaffold base command as if it performs generation by itself.