name	local-config
description	This skill should be used for configuring devloop project settings via .devloop/local.md, git workflow preferences, commit settings, review options
when_to_use	Configuring devloop settings, .devloop/local.md, project preferences

Local Configuration

Project-specific devloop settings via .devloop/local.md (NOT git-tracked).

Format

YAML frontmatter followed by optional markdown notes:

---
git:
  auto-branch: false           # Create branch when plan starts
  branch-pattern: "feat/{slug}" # {slug}, {date}, {user}
  main-branch: main
  pr-on-complete: ask          # ask | always | never
  worktree_isolation: false    # Isolate swarm workers in git worktrees (opt-in)

commits:
  style: conventional          # conventional | simple
  scope-from-plan: true
  sign: false

review:
  before-commit: ask           # ask | always | never
  use-plugin: null             # null | code-review | pr-review-toolkit

github:
  link-issues: false           # Enable GH issue linking
  auto-close: ask              # ask | always | never
  comment-on-complete: true

tokens:
  token_budget: 4000           # Max tokens for gather-task-context.sh output (default: 4000)
  cache_friendly_context: true # Order agent prompts for prompt cache hits (default: true)
---

Settings Reference

Setting	Values	Default
`git.auto-branch`	true/false	false
`git.branch-pattern`	Pattern with {slug}, {date}, {user}	feat/{slug}
`git.pr-on-complete`	ask/always/never	ask
`git.worktree_isolation`	true/false	false
`commits.style`	conventional/simple	conventional
`commits.sign`	true/false	false
`review.before-commit`	ask/always/never	ask
`review.use-plugin`	null/code-review/pr-review-toolkit	null
`github.link-issues`	true/false	false
`github.auto-close`	ask/always/never	ask
`github.comment-on-complete`	true/false	true
`fresh_threshold`	5-50	10
`context_threshold`	50-95	70
`tokens.token_budget`	1000-20000	4000
`tokens.cache_friendly_context`	true/false	true

Example Configurations

Minimal (Git-aware)

---
git:
  auto-branch: true
---

Full CI/CD Workflow

---
git:
  auto-branch: true
  pr-on-complete: always
commits:
  style: conventional
  sign: true
review:
  before-commit: always
  use-plugin: pr-review-toolkit
---

Issue-Driven Development

---
git:
  auto-branch: true
  pr-on-complete: always
github:
  link-issues: true
  auto-close: always
  comment-on-complete: true
---

Worktree Isolation

When running /devloop:run-swarm with many parallel tasks, you can enable git worktree isolation so each worker operates in its own isolated branch. This prevents workers from overwriting each other's in-progress changes.

---
git:
  worktree_isolation: true   # Each swarm worker runs in an isolated git worktree
---

Effect: Equivalent to passing --worktrees to every /devloop:run-swarm invocation. The orchestrator merges results back after each batch. Default is false — opt-in only.

When to enable:

Large parallel plans (5+ concurrent workers) with overlapping file scopes
You want maximum isolation between workers at the cost of slightly more git overhead

When to leave off (default):

Most plans: workers are already assigned non-overlapping tasks
Single-task or sequential plans
Environments where git worktrees are not supported

Context & Performance

---
fresh_threshold: 10            # Tasks before suggesting /devloop:fresh (default: 10)
context_threshold: 70          # Exit ralph loop at this context % (default: 70)
---

Setting	Values	Default	Description
`fresh_threshold`	5-50	10	Tasks completed before suggesting a fresh restart. Set higher (20-30) for 1M context models.
`context_threshold`	50-95	70	Context usage % that triggers automatic ralph loop exit.

Token Efficiency

Control how devloop manages context size and prompt caching when spawning agents.

---
tokens:
  token_budget: 4000           # Max tokens for context gathering (default: 4000)
  cache_friendly_context: true # Order agent prompts for prompt cache hits (default: true)
---

token_budget

Passed as --token-budget N to gather-task-context.sh. The script estimates file sizes (~4 chars per token) and stops collecting files once the budget is reached. Files are prioritized:

Files directly mentioned in the task description (by name)
Files matching keywords in content or filename

When to adjust:

Lower (1000-2000): Fast swarm runs where many small tasks run in parallel; you want lean context per worker.
Default (4000): Standard single-task execution; balanced coverage.
Higher (8000-16000): Complex tasks spanning many files; you want more context per task. Increase fresh_threshold when raising this, as heavier context exhausts session budget faster.

cache_friendly_context

When true (default), agent prompts are structured with static content first (instructions, phase name, project conventions) and dynamic content last (task description, gathered file contents). This maximizes Claude's prompt cache hit rate when multiple agents are spawned in the same session.

Effect: On the 2nd+ agent spawn in a parallel batch, the static prefix is already cached -- reducing latency and API cost. The first spawn always pays the full cost; subsequent spawns only pay for the dynamic suffix.

When to disable: If you are debugging agent prompt content and need to see the exact prompt structure without reordering, set cache_friendly_context: false. This has no other effect.

Setting	Values	Default	Description
`tokens.token_budget`	1000-20000	4000	Max tokens for `gather-task-context.sh`. Lower = faster/leaner; higher = more context.
`tokens.cache_friendly_context`	true/false	true	Put static prompt content first for cache hits. Disable only for debugging.

Plugin Integration

---
plugins:
  superpowers-suggestions: false  # Disable seeAlso to superpowers skills
---

Usage

Edit .devloop/local.md directly; changes take effect on next command
Parsed by ${CLAUDE_PLUGIN_ROOT}/scripts/parse-local-config.sh
Add to .gitignore to keep local-only