CLI Reference

What it does: Tells the agent "work on this specific requirement until it's done or you hit a wall."

felix run S-0001

When to use it:

• You have a specific requirement ready to implement
• You want focused, controlled execution
• You're testing a new spec before letting the agent loose

Real-world example:

# Execute requirement with rich terminal output (default)
felix run S-0042

# Get JSON events for parsing in scripts
felix run S-0042 --format json

# Push artifacts to backend server
felix run S-0042 --sync

What happens when it runs: Felix iterates on the requirement until it completes, is blocked by tests/validation, or hits an error. Control verbosity with --format, --verbose, and --quiet.

Exit codes tell the story:

• 0 = Success (requirement completed and validated)
• 1 = Error (agent crashed or hit an unexpected failure)
• 2 = Blocked by backpressure (tests failed too many times)
• 3 = Blocked by validation (acceptance criteria failed)

What it does: Autonomously processes all planned/in-progress requirements until the backlog is empty or you stop it.

felix loop

When to use it:

• Friday afternoon before the weekend (let it work while you're gone)
• You have 20 small requirements and don't want to babysit each one
• You trust your specs and backpressure tests

When NOT to use it:

• Your specs are half-baked or vague
• You haven't validated your test suite catches regressions
• It's Monday morning and your boss wants a demo at 10 AM

Options:

# Limit to 5 requirements then stop
felix loop --max-iterations 5

# Continuously sync artifacts to backend
felix loop --sync

# Skip git commits (useful for reviewing before committing)
felix loop --no-commit

Pro tip: Loop mode creates lock files in .felix/.locks/loop-<PID>.lock to prevent multiple loops from colliding. If Felix crashes and leaves a stale lock, you'll need to manually clean it up.

Tip: Clear acceptance criteria and stable tests make loop mode far more reliable.

What it does: Finds the next available requirement and runs it immediately — server-assigned in team mode, locally-picked in solo mode.

felix run-next
felix run-next --sync    # enable sync for this run
felix run-next --format json

Remote mode (sync enabled): claims work from the server so multiple agents on the same project never collide. Marks it reserved, then transitions to in_progress when the agent starts.

Local mode: picks the next in_progress then planned requirement from requirements.json, sorted by ID.

Exit codes:

The 5 exit code is designed for CI poll loops:

while ($true) {
    felix run-next --sync
    if ($LASTEXITCODE -eq 5) { Start-Sleep 60 }  # nothing to do, wait
    elseif ($LASTEXITCODE -ne 0) { break }        # error or block needs attention
}

Check on everything:

felix status

Check one requirement:

felix status S-0001

Get machine-readable output:

felix status --format json

What you'll see:

• Current requirement status (planned, in_progress, complete, blocked)
• Agent name and last execution time
• Validation results
• Git commit associated with completion

Why this matters: When your agent has been churning for 30 minutes and you're wondering if it's actually working or stuck in a loop, felix status is your reality check.

All requirements:

felix list

Filter by status:

felix list --status planned
felix list --status complete
felix list --status blocked

Filter by priority:

felix list --priority high
felix list --priority low

Filter by tags (comma-separated):

felix list --tags backend
felix list --tags backend,auth

Show requirements blocked by incomplete dependencies:

felix list --blocked-by incomplete-deps

Include dependency details in output:

felix list --with-deps

JSON for scripting:

felix list --format json | jq '.[] | select(.status == "blocked")'

Useful patterns:

# Morning standup: what got done overnight?
felix list --status complete

# Planning: what's ready to work on?
felix list --status planned

# What's stuck on unfinished dependencies?
felix list --blocked-by incomplete-deps

# Troubleshooting: what's stuck?
felix list --status blocked

What it does: Runs the validation criteria from the requirement spec without running the full agent loop.

What question it answers:

• Did we achieve what this requirement says should be true?
• Do the concrete checks in the spec pass right now?

How it works:

1. Reads the requirement's spec file
2. Looks at ## Validation Criteria (or ## Acceptance Criteria)
3. Runs the commands listed there
4. Compares outcomes against expected exit codes/status
5. Returns pass/fail with reasons and output

Important: felix validate is a requirement-level done check, not a generic quality score.

felix validate S-0001

Why you need this:

1. Testing your acceptance criteria before letting the agent loose
2. Debugging failures - run validation in isolation to see what's actually broken
3. Post-deployment checks - validate requirements still work after merging

Practical impact:

• Validation is only as strong as your criteria
• Vague or manual-only criteria can pass without strong proof
• Explicit runnable checks (pytest, API checks, UI smoke tests) make it a strong completion gate

Distinction:

• felix validate = requirement-level acceptance verification
• Backpressure in felix run / felix loop = iteration-level safety gate (tests/build/lint before committing)

Validation criteria format (from your spec file):

## Validation Criteria

- [ ] Backend starts: `python app/backend/main.py` (exit code 0)
- [ ] Health endpoint responds: `curl http://localhost:8080/health` (status 200)
- [ ] Tests pass: `pytest app/backend/tests` (exit code 0)

Critical rule: Only use backticks for actual executable commands. If it's not meant to run in a shell, don't wrap it in backticks. We learned this the hard way when someone wrote:

- [ ] File exists: `app/backend/config.py`

The validator tried to execute "app/backend/config.py" as a command and exploded. Correct version:

- [ ] File exists: **app/backend/config.py** (file exists)

Show dependencies for one requirement:

felix deps S-0001

Check if dependencies are satisfied:

felix deps S-0001 --check

See the full dependency tree:

felix deps --tree

Find what's blocking progress:

felix deps --incomplete

Why dependencies matter: Requirements have depends_on relationships. If S-0005 depends on S-0003 and S-0004, the agent won't start S-0005 until both dependencies are complete. This prevents building features on top of features that don't exist yet.

Dependency resolution is smart:

• Transitive dependencies work (A depends on B, B depends on C → A waits for C)
• Circular dependencies are detected and rejected
• Incomplete dependencies automatically block execution

Interactive mode (asks questions):

felix spec create "Add user authentication"

Quick mode (makes reasonable assumptions):

felix spec create "Add user authentication" --quick

What --quick does:

• Skips asking for detailed description (uses the title)
• Defaults to planned status
• No dependencies
• Generates minimal acceptance criteria

Interactive mode asks:

1. Do you want to provide a detailed description? (y/N)
2. What status should this be? (planned/draft/in-progress)
3. Does this depend on other requirements? (comma-separated IDs)
4. Do you want to generate acceptance criteria with the agent? (y/N)

What it creates: A new spec file in specs/ with a new requirement ID and frontmatter. In interactive mode it can also help draft acceptance criteria.

Pro tip: Use --quick for small, obvious requirements. Use interactive mode for complex features that need detailed planning.

Scan specs folder and fix alignment:

felix spec fix

Auto-rename duplicate spec IDs:

felix spec fix --fix-duplicates

What this does: Scans all S-*.md files in specs/ and reconciles them against .felix/requirements.json:

• Adds entries for spec files that are missing from requirements.json
• Removes stale entries for requirements that no longer have a spec file
• With --fix-duplicates: detects duplicate S-NNNN IDs and renames files to the next available ID

When to use:

• After manually creating or deleting spec files without using felix spec create/delete
• After cloning a repo where requirements.json is out of sync with specs/
• When you see "requirement not found" errors that don't match your spec files

Delete with confirmation:

felix spec delete S-0001

What gets deleted:

• The spec file (specs/S-NNNN.md)
• The requirement entry in .felix/requirements.json

What stays:

• Historical run artifacts in runs/ (for audit trail)
• Git history (no force deletion)

Safety: Prompts for confirmation unless you're piping input or using --force.

Change the status of a requirement:

felix spec status S-0042 planned
felix spec status S-0042 in_progress
felix spec status S-0042 complete
felix spec status S-0042 blocked

What it does: Updates the status field for the given requirement in .felix/requirements.json. Useful for manually overriding status without hand-editing the JSON file.

Common use cases:

• Unblocking a blocked requirement: felix spec status S-0042 planned
• Manually marking something complete: felix spec status S-0042 complete
• Forcing a requirement back into the queue: felix spec status S-0042 in_progress

Equivalent to: opening .felix/requirements.json and editing "status" directly, but without the risk of malforming the JSON.

Pull all specs that are out of date:

felix spec pull

Preview without writing any files:

felix spec pull --dry-run

Force overwrite of local files even if they exist:

felix spec pull --force

Also delete local specs that no longer exist on the server:

felix spec pull --delete

What it does:

1. Sends a manifest of local file hashes to the server
2. Server responds with which files are missing, outdated, or current
3. Downloads only the files that differ (.md specs and .meta.json sidecars)
4. Writes them to specs/ in the project

What are `.meta.json` sidecars?

Each spec has an accompanying specs/S-NNNN-name.meta.json file containing rich metadata stored by the server:

{
  "priority": "high",
  "tags": ["backend", "auth"],
  "depends_on": ["S-0001", "S-0002"],
  "updated_at": "2026-02-23"
}

• Generated automatically on spec create and spec fix
• Gitignored (specs/*.meta.json) so they don't pollute version control
• Used by the agent loop to resolve depends_on for the current requirement
• Downloaded fresh each time via felix spec pull

When to use it:

• Before starting work in remote/team mode to get the latest server state
• When another team member has updated spec priorities or dependencies
• After felix setup on a new clone — pull specs before running the loop

Authentication: Requires sync.api_key in .felix/config.json or FELIX_SYNC_KEY env var.

# Typical workflow before running the agent loop in team mode
felix spec pull
felix loop

Upload all specs:

felix spec push

Preview without uploading:

felix spec push --dry-run

Re-upload all even if unchanged:

felix spec push --force

What it does: Reads all *.md files from specs/, encodes them as base64, and sends them to the server in a single batch for storage.

Added support and clarified behavior:

• felix spec push uploads local specs/*.md files to the backend via POST /api/sync/specs/upload.
• felix spec push --dry-run previews files that would be uploaded without sending.
• felix spec push --force does two things:
• Re-uploads all local specs.
• Requests server-side create-if-missing requirement mappings for specs that do not yet exist remotely.

Important: --force depends on backend support. If the server does not implement create-if-missing for spec upload, the CLI logs this clearly and explains that local spec fix only updates local requirements.json.

Authentication: Requires sync.api_key in .felix/config.json or FELIX_SYNC_KEY env var.

When to use:

• After creating or editing specs locally that you want remote agents to pick up
• Before starting a distributed team session — push local changes so others get them via felix spec pull
• After bulk-creating specs with felix spec create --quick

Typical team workflow:

# Developer A: create and push specs
felix spec create "Add rate limiting" --quick
felix spec push

# Agent on another machine: pull and work
felix spec pull
felix loop

Standard build:

felix context build

Include hidden files:

felix context build --include-hidden

Skip overwrite confirmation:

felix context build --force

What it does: Launches the agent to autonomously analyze your project and generate CONTEXT.md - a comprehensive document describing:

• Project purpose and architecture
• Tech stack and dependencies
• File structure and organization
• Key components and how they connect
• Development setup and workflows

Why this exists: Every project needs a "README for your brain" that explains the big picture. Rather than manually maintaining this (and watching it go stale), let the agent regenerate it periodically.

Pro tip: Run this after major architectural changes or before onboarding new team members. The agent will analyze file patterns, dependency graphs, import statements, and configuration files to understand your stack.

Time commitment: Usually takes 2-5 minutes depending on project size.

felix context show

Displays CONTEXT.md content in your terminal. Useful for quick reference without opening an editor.

Upload all three docs:

felix context push

Preview without uploading:

felix context push --dry-run

Re-upload even if content is unchanged:

felix context push --force

What it does: Reads README.md, CONTEXT.md, and AGENTS.md from the repo root, skips files that haven't changed since the last push (using .felix/manifest-hashes.json as the cache), and uploads changed files to the server.

Authentication: Requires sync.api_key in .felix/config.json or FELIX_SYNC_KEY env var.

When to use:

• After updating CONTEXT.md to reflect architectural changes
• After modifying AGENTS.md with new agent instructions
• Keeping the UI project page and remote agents in sync with your local docs

Download changed docs:

felix context pull

Preview without writing files:

felix context pull --dry-run

Overwrite local files not in the manifest cache:

felix context pull --force

What it does: Fetches the latest manifest from the server, compares it against the cached values in .felix/manifest-hashes.json (written after the last pull or push), and writes only the files that have changed. Shows [SKIP] for up-to-date files and [OK] for files that were updated.

Authentication: Requires sync.api_key in .felix/config.json or FELIX_SYNC_KEY env var.

When to use:

• When another team member has updated docs and pushed them
• Before a work session to ensure you have the latest AGENTS.md
• After another machine has run felix context push

Typical workflow:

# Morning sync before starting work
felix context pull
felix spec pull
felix loop

felix setup

What it does: Guided wizard for configuring a Felix project from scratch (or reconfiguring an existing one). Safe to re-run — idempotent, never overwrites files that already exist.

Steps:

1. Confirm project folder — defaults to current directory; accepts a different path
2. Mode choice — local (no server) or remote (server-backed team mode)
3. Remote config — prompts for server URL, project git URL, and API key
4. Bootstrap — runs spec pull + spec fix to download and align requirements from the server
5. Agent configuration — interactive: prompts for LLM provider and model, writes .felix/agents.json
6. Scaffold — creates policies/, specs/, config.json, requirements.json, state.json from the engine template if missing
7. Test command — prompts for backpressure test command and mode

When to use:

• Bootstrapping a brand-new project
• Onboarding a new team member on an existing project
• After a global felix install to set up a project without copying engine files

felix agent list

Output:

Available Agents:

* ID: ag_ee77df894 - claude
  Provider: claude
  Executable: claude
  Adapter: claude

  ID: ag_16fffb5a4 - codex
  Provider: codex
  Executable: codex
  Adapter: codex

The * marks your current agent (configured in .felix/config.json). Agent IDs are generated automatically from agent config.

felix agent current

Shows the currently configured agent with full details.

felix agent setup

Interactive configuration for agents and default models. This writes or updates .felix/agents.json with selected agents and models.

felix agent use claude

Interactive selection:

felix agent use

What it does: Updates .felix/config.json to use a different agent profile from .felix/agents.json.

Why you'd switch:

• droid is fast and cheap, good for bulk work
• claude has better reasoning for complex problems
• codex uses a diff-based workflow (different UX)
• gemini if you want to test Google's model

Agents are interchangeable from the CLI's perspective; switch to match cost, speed, or reasoning quality.

felix agent test droid

What it does: Runs a quick smoke test to verify:

1. Executable is in PATH
2. Agent responds to commands
3. JSON event stream works
4. Basic code generation works

When to use this: After installing a new agent executable or updating versions.

felix agent register

What it does: Registers the current agent profile (from .felix/agents.json) with the sync server so it appears in the UI Fleet view and can claim work.

• Shows the target URL and API key prefix before attempting
• Prompts to proceed if sync is disabled in config
• Safe to re-run — repeated calls just refresh metadata
• Surfaces backend error detail inline: key mismatch, git URL mismatch, DB errors

Agent IDs are generated automatically, so .felix/agents.json only needs name, provider, and model. felix setup generates a correct agents.json automatically.

felix procs
felix procs list

Shows:

• Session ID (run identifier)
• Requirement being executed
• Agent name
• Process ID (PID)
• Running duration
• Status (running/paused)

Example output:

Active Sessions:

  Session: S-0042-20260217-143022-it1
  Requirement: S-0042
  Agent: droid
  PID: 18432
  Duration: 12:34
  Status: running

Why this matters: Sometimes you spawn felix loop in a background terminal and forget about it. felix procs shows you it's still churning away.

felix procs kill S-0042-20260217-143022-it1

Kill all running sessions at once:

felix procs kill all

What it does: Gracefully terminates an agent process:

1. Sends termination signal
2. Waits for agent to finish current iteration
3. Cleans up lock files
4. Updates requirement status

When you need this:

• Agent is stuck in an infinite loop
• You realized the spec is wrong mid-execution
• You need to free up CPU/memory for something else

Safety: This is a graceful shutdown. The agent finishes its current LLM call before exiting and commits any pending changes.

felix tui

Also available as:

felix dashboard

What it does: Launches an interactive terminal UI (built with .NET/Spectre.Console) that provides:

• Visual requirement status and progress tracking
• Interactive command menu (run, loop, validate, etc.)
• Real-time status visualization

Navigation:

Requirements: .NET SDK (dotnet CLI) must be installed. The TUI is the C# src/Felix.Cli project and is separate from the PowerShell CLI.

felix version

Displays the Felix CLI version, current git branch, and short commit hash. Useful for bug reports and confirming which version is installed.

Example output:

Felix CLI v0.3.0-alpha (Phase 1: PowerShell)
Repository: C:\dev\myproject
Branch: main
Commit: a3f8c12

felix help
felix help run
felix help loop
felix help spec
felix help context
felix help agent
felix help deps
felix help procs
felix help tui

Prints usage, options, and examples for any command. Running felix help with no argument prints the full command list.

JSON (machine-readable):

felix run S-0001 --format json

Every event as a complete JSON object on one line. Perfect for:

• Parsing in scripts
• Piping to other tools
• Remote execution / headless environments

Plain (human-readable text):

felix run S-0001 --format plain

Simple colored text output. Good for:

• Basic terminal environments
• Log files
• CI/CD pipelines where colors might break

Rich (default, fancy):

felix run S-0001 --format rich

Enhanced visuals with:

• Progress indicators
• Colored output
• Formatted tables
• Statistics summary

Default: Rich format for interactive terminals, JSON for scripts/pipelines.

felix run S-0001 --verbose

What you get:

• Debug-level log messages
• Internal state transitions
• LLM prompt construction details
• File I/O operations
• Git command execution

When to use it:

• Debugging agent behavior
• Understanding why a requirement failed
• Learning how Felix works internally

Warning: VERY chatty. Your terminal will scroll like the Matrix.

felix run S-0001 --quiet

What gets suppressed:

• Info-level messages
• Progress indicators
• Statistics

What you still see:

• Errors (obviously)
• Warnings
• Final status

Use case: Background jobs, cron tasks, CI/CD where you only want to know if it failed.

felix run S-0001 --no-stats

Normally Felix shows a summary at the end:

=== Run Statistics ===
Events: 1,247
Errors: 2
Warnings: 5
Tasks completed: 8
Validations passed: 3
Duration: 4m 32s

With --no-stats, this is suppressed. Useful for:

• JSON output mode (stats would break parsing)
• Scripted execution where you don't care
• Minimalist aesthetic preferences

No server required. Everything runs from local files.

• Work selection reads requirements.json directly
• in_progress requirements resume first, then planned, sorted by ID
• Dependencies (depends_on) read from specs/*.meta.json sidecars or inline in requirements.json
• No network calls during the agent loop

{
  "sync": {
    "enabled": false
  }
}

Requires a running Felix backend. Enables server-side work allocation so multiple agents can collaborate on the same project without stepping on each other.

{
  "sync": {
    "enabled": true,
    "base_url": "http://localhost:8080",
    "api_key": "fsk_..."
  }
}

How work allocation works:

Felix claims work from the server when you run felix loop and releases it if a run is blocked, so multiple agents can collaborate safely. Typical remote mode workflow:

# 1. Pull latest specs and metadata from server
felix spec pull

# 2. Start the autonomous loop (uses server work allocation)
felix loop

# Terminal 2 — second agent works in parallel on different requirements
felix loop

Environment variable overrides (useful for CI/CD):

$env:FELIX_SYNC_ENABLED = "true"
$env:FELIX_SYNC_URL     = "https://felix.company.com"
$env:FELIX_SYNC_KEY     = "fsk_prod_key_here"
felix loop

Usage:

felix run S-0001 --sync
felix loop --sync

What it does: Enables artifact mirroring to a remote backend for this run only, overriding the sync.enabled setting in .felix/config.json.

Why temporary override?

• You normally run locally without sync (faster, no network dependency)
• But for important requirements you want artifacts backed up
• Or you're showing progress to stakeholders who don't have local access

What gets synced:

• Agent registration (hostname, platform, version)
• Run creation (requirement ID, start time)
• Events (full NDJSON stream)
• Output files (logs, diffs, reports)
• Run completion (status, exit code)

Architecture:

CLI Agent → Writes locally to runs/ → Queues to .felix/outbox/*.jsonl
                                   → Background sync uploads to backend
                                   → Retry on failure (exponential backoff)

Sync failure handling:

• Non-blocking: Agent continues even if sync fails
• Queued: Failed uploads retry later when backend comes back
• Eventual consistency: All artifacts eventually reach the backend
• Duplicate uploads are skipped

Configuration hierarchy:

1. --sync flag (highest priority - this run only)
2. $env:FELIX_SYNC_ENABLED environment variable
3. .felix/config.json sync.enabled setting (persistent)

Pro tip: Set up sync for production/staging environments but disable for local dev:

# Production deployment
$env:FELIX_SYNC_ENABLED = "true"
$env:FELIX_SYNC_URL = "https://felix.company.com"
$env:FELIX_SYNC_KEY = "fsk_prod_key_here"
felix loop

# Local development (no sync)
felix run S-0001

Troubleshooting: If sync isn't working, check .felix/outbox/ for queued files. If you see hundreds of *.jsonl files, the agent couldn't reach the backend. Clean them up or let them retry when the network recovers.

Usage:

felix spec create "Add user authentication" --quick

What it skips:

• Detailed description prompts
• Dependency questions
• Status selection (defaults to "planned")
• Acceptance criteria generation

What you get:

• Spec file with title only
• Minimal frontmatter
• Ready to edit manually

When to use it:

• You know exactly what you want
• You'll flesh out details later
• You have 20 small requirements to batch-create

Time savings: Interactive mode: ~2-3 minutes per spec. Quick mode: ~5 seconds.

Usage:

felix run S-0001 --no-commit

What it does: Agent makes all code changes but skips git commit at the end.

When to use it:

• Testing a new spec for the first time
• Prototyping agent behavior
• You want to review changes before committing

Why this exists: Early on, we'd test a spec and Felix would commit broken code with a message like "Implement feature X [Claude]". Then we'd have to git reset --hard and lose the changes. --no-commit lets you see what the agent did before deciding to keep it.

Pro tip: Combine with --format plain for testing:

felix run S-0001 --no-commit --format plain | tee test-output.log

Review changes, then either commit manually or discard:

# Keep it
git add -A
git commit -m "Implement S-0001 (manually verified)"

# Discard it
git reset --hard

Symptom: Felix refuses to start with "Another process is running."

Fix: Confirm nothing is running:

felix procs list

If nothing is running:

Remove-Item .felix/run.lock

Symptom: Output contains strange characters or unreadable arrows.

Fix (PowerShell 5.1):

chcp 65001 | Out-Null
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

Symptom: --sync enabled but nothing appears on the server.

Fix: Verify FELIX_SYNC_URL and FELIX_SYNC_KEY, then check for queued uploads in .felix/outbox/.

Bad:

- [ ] User authentication works

Good:

- [ ] Login endpoint responds: `curl -X POST http://localhost:8080/api/auth/login -d '{"username":"test","password":"test"}' -H "Content-Type: application/json"` (status 200)
- [ ] Invalid credentials rejected: `curl -X POST http://localhost:8080/api/auth/login -d '{"username":"test","password":"wrong"}' -H "Content-Type: application/json"` (status 401)
- [ ] Auth tests pass: `pytest app/backend/tests/test_auth.py` (exit code 0)

Don't:

# Write 50 requirements
# Run felix loop
# Go on vacation
# Come back to 47 failures

Do:

# Write 3 requirements
# Run felix run S-0001
# Verify it works
# Adjust your spec style based on what worked
# Write 5 more requirements
# Run felix loop --max-iterations 5
# Verify those work
# Now scale up

When you have a mental model of 20 small requirements:

# Create them all with --quick
felix spec create "Add user login" --quick
felix spec create "Add password reset" --quick
felix spec create "Add email verification" --quick
# ... 17 more ...

# Go back and flesh out details for complex ones
felix spec fix S-0042
felix spec fix S-0051

Don't just fire and forget:

# Terminal 1: Run the loop
felix loop --sync

# Terminal 2: Watch progress
watch -n 30 'felix status'

# Terminal 3: Check for blockages
felix deps --incomplete

Local dev: No sync (fast, no network dependency)

felix run S-0001

Integration environment: Sync for troubleshooting

felix run S-0001 --sync

Production automation: Always sync

$env:FELIX_SYNC_ENABLED = "true"
felix loop

Track agent configuration changes in git:

git add .felix/agents.json
git commit -m "Switch default agent to claude for better reasoning"

Why? When a requirement fails, you want to know which agent ran it and with what configuration.

Run artifacts accumulate fast:

runs/
  2026-02-01T10-30-00/
  2026-02-01T11-15-22/
  2026-02-01T14-45-10/
  ... 500 more ...

Periodically archive:

# Move runs older than 30 days to archive
$cutoff = (Get-Date).AddDays(-30)
Get-ChildItem runs/* | Where-Object { $_.CreationTime -lt $cutoff } | Move-Item -Destination archive/runs/

Before letting the agent work on a requirement:

# Run the validation commands yourself
python app/backend/main.py  # Does it start?
curl http://localhost:8080/health  # Does the endpoint work?
pytest app/backend/tests/  # Do the tests pass?

# If any fail, your criteria are wrong
felix validate S-0042  # Confirm with the validator

Monday morning:

# Review what's ready
felix list --status planned

# Check dependencies
felix deps --tree

# Start the first batch
felix run S-0042
felix run S-0043
felix run S-0044

CI/CD pipeline:

# .github/workflows/felix.yml
- name: Run Felix requirements
  run: |
    felix loop --max-iterations 10 --format json --sync
  env:
    FELIX_SYNC_ENABLED: "true"
    FELIX_SYNC_URL: ${{ secrets.FELIX_BACKEND_URL }}
    FELIX_SYNC_KEY: ${{ secrets.FELIX_API_KEY }}

Before leaving Friday:

# Start loop in background
nohup felix loop --sync > felix-loop.log 2>&1 &

# Check progress Monday morning
felix status
grep -i error felix-loop.log
felix list --status blocked

Production is down, need quick fix:

# Create requirement
felix spec create "Fix authentication timeout issue" --quick

# Edit spec with exact criteria
code specs/S-0078.md

# Run focused execution, no distractions
felix run S-0078 --format plain --no-stats

# Verify fix
felix validate S-0078

# Deploy
git push

Error: "Another process is running"

Check:

felix procs list

Fix if stale:

Remove-Item .felix/run.lock

Check:

# See what it's doing
felix status S-0042 --format json | jq .current_iteration

# If iteration count keeps growing...
felix procs kill <session-id>

Common causes:

• Vague acceptance criteria that are never satisfied
• Flaky tests that sometimes pass/fail
• Agent making changes that break tests in a cycle

Symptoms: No artifacts appear in backend

Check local queue:

Get-ChildItem .felix\outbox\*.jsonl | Measure-Object

If empty: Sync disabled or failing silently

If hundreds: Network issue or backend down

Test backend connectivity:

curl http://localhost:8080/health

Enable debug logging:

felix run S-0001 --sync --verbose 2>&1 | Select-String -Pattern "sync"

Problem: Acceptance criteria look right, but validation fails

Debug:

# Run validation with verbose output
felix validate S-0042 --verbose

# Manually run the failing command
python app/backend/main.py  # Does it actually work?

# Check for environmental issues
echo $PATH
which python
python --version

Common gotchas:

• Wrong Python version
• Missing environment variables
• Database not running
• Port already in use