Concepts

How Fellowship orchestrates AI agents with memory, specs, and code review.

How It Works

When you run a task, Fellowship orchestrates a full pipeline:

The Memory System

Fellowship maintains a persistent memory that grows with every run. This is what makes Day 30 runs better than Day 1.

How Memory Improves Runs

1. Before generating a spec, Fellowship searches learnings via FTS5
2. Relevant learnings + all gotchas are injected as context
3. The spec includes a ## Context Considered section showing exactly what was used
4. After each run, new learnings are extracted and distilled

Spec-First Workflow

Every task gets a detailed spec before any code is written. The spec engine takes your task description and combines it with:

• Project architecture — from architecture.md
• Past learnings — full-text searched via FTS5 for relevance
• Gotchas — all known pitfalls injected as warnings
• Agent profile — role-specific guidelines and conventions

This means the agent starts with a complete picture — not just your one-liner task description. You can preview any spec before running it:

# Preview the spec without executing
fellowship run "add WebSocket support" --dry-run

# Or generate just the spec file
fellowship spec "add WebSocket support"

Agents & Roles

Fellowship creates a team of specialized agents, each with a role, profile, and memory. Agents are defined in .fellowship/team.yaml and have individual profile files in .fellowship/profiles/.

A typical team might include:

• Carlos (Backend) — handles API endpoints, business logic, database queries
• Atlas (Database) — schema design, migrations, query optimization
• Merlín (Coordinator) — project-level decisions and planning
• Sentinel (Reviewer) — code review on every run

Fellowship automatically selects the right agent for each task based on the agent’s role and the task description. You can also add new agents with fellowship hire.

Writer-Reviewer Pattern

Fellowship uses a writer-reviewer pattern for every run. The coding agent (writer) implements the task, then Sentinel (reviewer) checks the code against the spec.

This creates a feedback loop:

1. Writer implements the code based on the spec
2. Sentinel reviews against acceptance criteria, catches bugs and edge cases
3. If issues found, the writer gets feedback and fixes them
4. Cycle repeats up to maxCycles (default: 2)
5. After passing review, changes go to human review (if --review flag used)

Sentinel — The Built-in Reviewer

Every project gets Sentinel, a dedicated AI code reviewer. Unlike using another coding agent as reviewer, Sentinel has a specialized profile focused on:

• Verifying acceptance criteria from the spec
• Catching bugs and missing edge cases
• Checking architecture compliance
• Not nitpicking style or suggesting rewrites

Sentinel reviews every run automatically. Configure via review: in config.yaml.

Background Runs

Background runs let the agent work while you keep coding. Your terminal stays free — no waiting around.

# Start a background run
fellowship run "add authentication" --bg

# Check on it any time
fellowship status
fellowship log --follow

# Review when notified
fellowship review

The agent works in an isolated git worktree, so there’s zero risk of conflicts with your current work. When it finishes, you get a notification.

Notifications

Fellowship notifies you when runs complete — zero config required.

Built-in (automatic)

Plus: terminal flash — colored bar on completion (green / red / yellow / blue).

Additional Providers

• Telegram — set bot token + chat ID in config or env vars
• Slack — set webhook URL in FELLOWSHIP_SLACK_WEBHOOK env var
• Custom — any shell command with env vars

Environment Variables in Hooks

Security

Fellowship includes prompt injection protection:

• 30+ detection patterns — XML tags, ChatML tokens, role markers, identity overrides, authority markers
• Sanitization on every run — Learnings, gotchas, and architecture scanned before injection
• fellowship sanitize — Manual scan with severity levels
• Dry-run reports — --dry-run shows sanitization results before committing to a run
• strictMode — Optional throw-on-detection for zero-tolerance environments

Skills System

Fellowship ships with built-in skills and supports project-level overrides:

fellowship/skills/          ← Built-in (shipped with CLI)
  code-review.md            ← Sentinel's review guidelines

.fellowship/skills/         ← Project overrides (optional)
  code-review.md            ← Your custom review guidelines

Project skills override built-in skills with the same name. Profiles reference skills with {{skill:name}}.

Platform Support

Supported Providers