Help

Devloop Help

Interactive guide to devloop.

Step 1: Choose Topic

If $ARGUMENTS specifies a topic, skip to that section. Otherwise:

AskUserQuestion:
  questions:
    - question: "What would you like to learn about?"
      header: "Topic"
      multiSelect: false
      options:
        - label: "Getting Started"
          description: "New to devloop? Start here"
        - label: "Commands"
          description: "What each command does"
        - label: "The Loop"
          description: "The plan -> run -> fresh cycle"
        - label: "Skills & Agents"
          description: "On-demand knowledge and parallel work"
        - label: "Superpowers"
          description: "How devloop works with superpowers plugin"

Topic: Getting Started

What is devloop?

Development workflow where Claude does the work directly. No routine agents. Just you, Claude, and the code.

Quick Start

/devloop:plan "How should we implement feature X?"  # Plan (or --deep for exploration)
/devloop:run                                        # Execute tasks
/devloop:fresh && /clear                           # Save state, clear context (every fresh_threshold tasks (default 10, configurable in .devloop/local.md))
/devloop:run                                        # Continue execution

First Session

1. Have a task? /devloop:plan [task] (or --deep for detailed exploration)
2. Claude explores, creates plan
3. You approve
4. /devloop:run to implement
5. Every fresh_threshold tasks (default 10, configurable in .devloop/local.md): /devloop:fresh then /clear then /devloop:run
6. Done? /devloop:ship

Topic: Commands

Decision Tree

Starting new work?
|-- Unclear requirements  -> /devloop:plan --deep
|-- Small, clear task     -> /devloop:plan --quick
|-- Normal feature        -> /devloop:plan
|-- Have a plan           -> /devloop:run

Mid-workflow?
|-- Context heavy         -> /devloop:fresh -> /clear -> /devloop:run
|-- Ready to commit       -> /devloop:ship
|-- Want review           -> /devloop:review

Returning?
|-- /devloop:run

Command Reference

Migration from Old Commands

Topic: The Loop

Pattern

/devloop:plan [topic]    ->  Creates plan
       |
/devloop:run             ->  Implements tasks
       |
After fresh_threshold tasks (default 10, configurable in .devloop/local.md)?
|-- Yes -> /devloop:fresh -> /clear -> /devloop:run
|-- No  -> Continue

Why It Works

• Fresh context = better reasoning
• Plan preserves progress
• Checkpoints keep control
• Sustainable pace

When to Fresh

• After fresh_threshold tasks (default 10, configurable in .devloop/local.md)
• When responses slow
• After long exploration
• Before taking a break

State Files

Topic: Skills & Agents

Skills: On-Demand Knowledge

Load when needed: Skill: skill-name

Don't preload. Claude loads automatically when needed.

Agents: Parallel Work Only

Use for: parallel implementations, security scans, large exploration (50+ files) Don't use for: writing code, tests, git ops, single files, docs

Topic: Troubleshooting

Common Issues

Plan corrupted: rm .devloop/plan.md && /devloop Session ended: /devloop:run Abandon plan: /devloop:archive && /devloop Context heavy: /devloop:fresh && /clear && /devloop:run Skill not loading: Check exact name in skills/INDEX.md Progress not saving: Use [x] not [X] Statusline missing: /devloop:statusline, restart Claude Code

Claude Code Native Integrations

LSP tools in agents: engineer, qa-engineer, and security-scanner agents use LSP for symbol navigation (goToDefinition, findReferences, documentSymbol). Gracefully falls back to Grep/Glob if no LSP server is configured.

Monitor for long commands: run, run-epic, and run-swarm use Monitor (not Bash) for test suites, builds, and full-codebase linting to stream output in real-time. Falls back to Bash if Monitor is unavailable.

Worktree isolation: run-swarm --worktrees runs each worker in an isolated git worktree. Enable via flag or git.worktree_isolation: true in .devloop/local.md. Off by default.

Token budget: tokens.token_budget in .devloop/local.md caps how many tokens gather-task-context.sh collects per task (default: 4000). Lower for leaner context; raise for large codebases.

Cache-friendly context: tokens.cache_friendly_context: true (default) reorders agent spawn prompts to maximize prompt cache hits, reducing API costs on repeated runs.

Reset Everything

rm -rf .devloop/ && /devloop

Topic: Automation

Autonomous Execution

/devloop:run                      # Up to 50 iterations
/devloop:run --max-iterations 100 # Custom limit
/devloop:run --interactive        # With checkpoints

How It Works

1. /devloop:run creates ralph-loop state
2. Claude works on tasks, marks [x]
3. When all done, outputs <promise>ALL PLAN TASKS COMPLETE</promise>
4. Loop terminates

Context Guard

Auto-exits at 70% context usage. Configure in .devloop/local.md:

context_threshold: 80

Stopping Early

• /cancel-ralph
• Max iterations reached
• Context guard triggered

Topic: Superpowers

Complement, Not Dependency

Devloop and superpowers are complementary plugins with distinct lanes:

• Devloop = Workflow orchestration (plan, run, fresh, ship)
• Superpowers = Quality practices (TDD, debugging, verification, code review)

Devloop works fully standalone. Superpowers is optional.

When to Use Which

Key Difference

• /devloop:plan creates workflow plans (task breakdown, phased execution)
• superpowers:writing-plans creates implementation plans (architecture, design decisions)

Both can coexist. Use devloop for the workflow, superpowers for quality gates within tasks.

Step 3: Offer More

AskUserQuestion:
  questions:
    - question: "Learn about another topic?"
      header: "More"
      multiSelect: false
      options:
        - label: "Yes, show topics"
          description: "Return to topic menu"
        - label: "No, I'm good"
          description: "Exit help"

If yes, return to Step 1. If no:

Ready to start? Try /devloop:plan [task] or /devloop:run if you have a plan.