epic

Epic lifecycle management. Epics are feature groups that organize related tasks within a project.

Epic States

planning -> in_progress -> completed
               |
               v
            blocked -> in_progress

any -> archived

Commands

sibyl epic list - List epics
sibyl epic show - Show epic details
sibyl epic create - Create an epic
sibyl epic start - Start an epic
sibyl epic complete - Complete an epic
sibyl epic archive - Archive an epic
sibyl epic update - Update epic fields
sibyl epic tasks - List tasks in an epic
sibyl epic roadmap - Generate markdown roadmap document

epic list

List epics with optional filters.

Synopsis

bash

sibyl epic list [options]

Options

Option	Short	Default	Description
`--project`	`-p`	(auto)	Project ID
`--status`	`-s`	(all)	Filter: planning, in_progress, blocked, completed
`--limit`	`-n`	50	Max results
`--json`	`-j`	false	JSON output
`--all`	`-A`	false	Ignore context, list from all projects

Examples

bash

# List epics in current project
sibyl epic list

# List all in_progress epics
sibyl epic list --status in_progress

# List epics across all projects
sibyl epic list --all

Output:

Epics
ID              Title                    Status        Priority   Progress
───────────────────────────────────────────────────────────────────────────
epic_abc123...  Authentication System    in_progress   high       5/12
epic_def456...  API v2 Migration         planning      medium     0/8
epic_ghi789...  Performance Optimization in_progress   high       3/7

Showing 3 epic(s)

epic show

Show detailed epic information including progress.

Synopsis

bash

sibyl epic show <epic_id> [options]

Arguments

Argument	Required	Description
`epic_id`	Yes	Epic ID (full or prefix)

Options

Option	Short	Description
`--json`	`-j`	JSON output

Example

bash

sibyl epic show epic_abc123

Output:

Epic epic_abc123de
  Title:     Authentication System
  Status:    in_progress
  Priority:  high
  Progress:  5/12 tasks (41.7%)

  Project:   proj_xyz7...
  Leads:     nova, bliss

  Description:
  Complete authentication overhaul including OAuth2, MFA, and session management.

  Tags: security, auth, oauth

epic create

Create a new epic in a project.

Synopsis

bash

sibyl epic create --title <title> [options]

Required Options

Option	Description
`--title` / `-n`	Epic title (required)

Options

Option	Short	Default	Description
`--project`	`-p`	(auto)	Project ID (auto-resolves from linked path)
`--description`	`-d`	(none)	Epic description
`--priority`		`medium`	Priority: critical, high, medium, low, someday
`--assignee`	`-a`	(none)	Epic lead/owner
`--tags`		(none)	Comma-separated tags
`--sync`		false	Wait for creation
`--json`	`-j`	false	JSON output

Examples

bash

# Basic epic
sibyl epic create --title "Authentication System"

# Full example
sibyl epic create \
  --title "Authentication System" \
  --description "OAuth2, MFA, session management overhaul" \
  --priority high \
  --assignee "nova" \
  --tags "security,auth,oauth"

Output:

Epic created: epic_abc123def456
Lead: nova

epic start

Start working on an epic. Moves status to in_progress.

Synopsis

bash

sibyl epic start <epic_id> [options]

Options

Option	Short	Description
`--assignee`	`-a`	Epic lead
`--json`	`-j`	JSON output

Example

bash

sibyl epic start epic_abc123

Output:

Epic started: epic_abc123...

epic complete

Complete an epic.

Synopsis

bash

sibyl epic complete <epic_id> [options]

Options

Option	Short	Description
`--learnings`	`-l`	Key learnings from the epic
`--json`	`-j`	JSON output

Example

bash

sibyl epic complete epic_abc123 \
  --learnings "OAuth2 integration was smoother than expected. Key insight: use passport.js for strategy abstraction."

Output:

Epic completed: epic_abc123...
Learnings captured

epic archive

Archive an epic (terminal state).

Synopsis

bash

sibyl epic archive <epic_id> [options]

Options

Option	Short	Description
`--reason`	`-r`	Archive reason
`--yes`	`-y`	Skip confirmation
`--json`	`-j`	JSON output

Example

bash

sibyl epic archive epic_abc123 --reason "Superseded by epic_xyz" --yes

Output:

Epic archived: epic_abc123def456...

epic update

Update epic fields directly.

Synopsis

bash

sibyl epic update <epic_id> [options]

Options

Option	Short	Description
`--status`	`-s`	Status: planning, in_progress, blocked, completed
`--priority`	`-p`	Priority: critical, high, medium, low, someday
`--title`		Epic title
`--assignee`	`-a`	Epic lead
`--tags`		Comma-separated tags
`--json`	`-j`	JSON output

Examples

bash

# Change priority
sibyl epic update epic_abc123 --priority critical

# Update multiple fields
sibyl epic update epic_abc123 \
  --status in_progress \
  --assignee "bliss" \
  --tags "security,urgent"

Output:

Epic updated: epic_abc123def456...
Fields: status, assignees, tags

epic tasks

List tasks belonging to an epic.

Synopsis

bash

sibyl epic tasks <epic_id> [options]

Options

Option	Short	Default	Description
`--status`	`-s`	(all)	Filter by task status
`--limit`	`-n`	50	Max results
`--json`	`-j`	false	JSON output

Examples

bash

# All tasks in epic
sibyl epic tasks epic_abc123

# Only todo tasks
sibyl epic tasks epic_abc123 --status todo

# JSON for scripting
sibyl epic tasks epic_abc123 --json

Output:

Tasks
ID              Title                      Status    Priority   Assignees
───────────────────────────────────────────────────────────────────────────
task_abc12...   Setup OAuth2 provider      done      high       nova
task_def45...   Implement MFA              doing     high       bliss
task_ghi78...   Add session management     todo      medium     -
task_jkl01...   Write auth tests           todo      medium     nova

Showing 4 task(s) for epic

Common Workflows

Epic Planning

bash

# Create epic
sibyl epic create \
  --title "User Dashboard" \
  --description "New user dashboard with analytics and settings" \
  --priority high

# Create tasks under epic
sibyl task create --title "Design dashboard layout" --epic epic_abc123
sibyl task create --title "Implement analytics widgets" --epic epic_abc123
sibyl task create --title "Add user settings panel" --epic epic_abc123
sibyl task create --title "Write dashboard tests" --epic epic_abc123

# Check progress
sibyl epic show epic_abc123

Epic Execution

bash

# Start the epic
sibyl epic start epic_abc123 --assignee "nova"

# Check task status
sibyl epic tasks epic_abc123 --status todo

# Start first task
sibyl task start task_design --assignee "nova"

# Monitor progress
sibyl epic show epic_abc123

Completing Epics

bash

# Check remaining tasks
sibyl epic tasks epic_abc123 --status todo,doing,blocked

# If all done, complete epic
sibyl epic complete epic_abc123 \
  --learnings "Dashboard component architecture worked well. Consider extracting widget framework for reuse."

Moving Tasks to Epic

bash

# Find orphan tasks
sibyl task list --no-epic

# Assign to epic
sibyl task update task_xyz --epic epic_abc123

epic roadmap

Generate a markdown roadmap document from epics and tasks.

Synopsis

bash

sibyl epic roadmap [options]

Options

Option	Short	Default	Description
`--project`	`-p`	(auto)	Project ID
`--status`	`-s`	(all)	Filter epics: planning, in_progress, completed
`--include-done`		false	Include completed tasks in output
`--output`	`-o`	stdout	Output file path

Output Includes

Overview table: Epic counts by status
Each epic: Title, priority badge, status, description, progress bar
Tasks by status: To Do, In Progress, Blocked, Review, Done
Priority markers: 🔴 critical, 🟠 high on task names
Key Learnings: Aggregated learnings from completed tasks

Examples

bash

# Generate roadmap to stdout
sibyl epic roadmap

# Save to file
sibyl epic roadmap -o roadmap.md

# Include completed tasks
sibyl epic roadmap --include-done

# Only in-progress epics
sibyl epic roadmap --status in_progress

# Specific project
sibyl epic roadmap --project proj_abc123

Example Output

markdown

# Sibyl Roadmap

_Generated: 2026-01-04 11:08_

## Overview

| Status      | Count  |
| ----------- | ------ |
| Planning    | 11     |
| In Progress | 0      |
| Completed   | 2      |
| **Total**   | **13** |

## Epics

### 📋 Server Setup Wizard

**ID:** `epic_b3145...` | **Priority:** 🔴 critical | **Status:** planning

> Web-based first-run wizard that guides users through setup...

**Progress:** `[████████████████░░░░]` 9/11 (82%)

#### 📝 To Do

- [ ] 🔴Backend: First-user-is-admin logic (`task_daab...`)

**Done:** 8 task(s) _(use --include-done to show)_

---

## Key Learnings

- **Replace inline SVGs** (Server Setup Wizard)
  > Iconoir icons are already exported from @/components/ui/icons.tsx...

sibyl task create - Create task (with --epic)
sibyl task list - List tasks (with --epic filter)
sibyl project show - Project overview

epic ​

Epic States ​

Commands ​

epic list ​

Synopsis ​

Options ​

Examples ​

epic show ​

Synopsis ​

Arguments ​

Options ​

Example ​

epic create ​

Synopsis ​

Required Options ​

Options ​

Examples ​

epic start ​

Synopsis ​

Options ​

Example ​

epic complete ​

Synopsis ​

Options ​

Example ​

epic archive ​

Synopsis ​

Options ​

Example ​

epic update ​

Synopsis ​

Options ​

Examples ​

epic tasks ​

Synopsis ​

Options ​

Examples ​

Common Workflows ​

Epic Planning ​

Epic Execution ​

Completing Epics ​

Moving Tasks to Epic ​

epic roadmap ​

Synopsis ​

Options ​

Output Includes ​

Examples ​

Example Output ​

Related Commands ​

epic

Epic States

Commands

epic list

Synopsis

Options

Examples

epic show

Synopsis

Arguments

Options

Example

epic create

Synopsis

Required Options

Options

Examples

epic start

Synopsis

Options

Example

epic complete

Synopsis

Options

Example

epic archive

Synopsis

Options

Example

epic update

Synopsis

Options

Examples

epic tasks

Synopsis

Options

Examples

Common Workflows

Epic Planning

Epic Execution

Completing Epics

Moving Tasks to Epic

epic roadmap

Synopsis

Options

Output Includes

Examples

Example Output

Related Commands