Files

Sheldon Finlay ecfbd0bb37 feat: worktree-based run isolation for parallel loops

Each /agent-loop:run now creates a git worktree for the feature branch
before generating stories. This provides full isolation:

- Multiple loops can run in parallel on different specs in the same project
- Main working directory stays on main, always available
- Each worktree has its own .loop/ state, tmux session, and branch
- Completed runs are archived to main's .loop/archive/ with runs.log

Changes:
- setup.sh: add --init-worktree mode for initializing worktree .loop/
- archive.sh: add archive_from_worktree() for cross-directory archiving
- loop.sh: replace branch checkout with validation (worktree is pre-checked-out)
- agents/planner.md: accept absolute path prefix for worktree .loop/ writes
- skills/run/SKILL.md: full rewrite — worktree creation in Phase 2, launch in
  Phase 3, archive on completion, .active-worktree tracking file
- skills/stories/SKILL.md: worktree-aware, defer to /run for full flow

Bump to 0.12.0.

2026-04-02 11:21:17 -04:00

2.2 KiB

Raw Permalink Blame History

name, description

name	description
stories	Generate prd.json and sprint contracts by dispatching the planner agent. Does not write source code.

/stories — Generate PRD and Sprint Contracts

Dispatch the planner agent to decompose a spec into stories. The planner agent cannot write source code or run bash commands — it can only write to .loop/.

Note: In most cases, use /agent-loop:run instead — it handles worktree creation, story generation, and launching the loop in one flow. Use /agent-loop:stories only if you want to generate stories without launching the loop.

Instructions

1. Check prerequisites

Verify .loop/config.json exists. If not, tell the user to run /agent-loop:setup first and stop.

2. Find the spec

Check these locations:

docs/superpowers/specs/*.md
docs/specs/*.md
SPEC.md, PRD.md, DESIGN.md at project root

If found, read the spec content.

If not found, ask: "What do you want to build? 1-3 sentences." Use their answer as the spec.

3. Read project context

Read the project root listing and any key config files (package.json, etc.) to understand the tech stack. Read .loop/config.json for the mode.

4. Dispatch planner agent

Use the Agent tool to launch the agent-loop:planner agent:

Agent(
  subagent_type: "agent-loop:planner",
  prompt: "Generate prd.json and sprint contracts for this project.\n\nMode: {mode}\nProject root: {path}\n\nSpec:\n{spec content}\n\nProject tech stack: {detected stack}",
  description: "Planning: generate stories"
)

If a worktree path is known (e.g., passed as context), include it in the prompt:

IMPORTANT: Write ALL files using absolute paths under: {WORKTREE_PATH}/.loop/

5. Present results

After the planner finishes, read .loop/prd.json (or {WORKTREE_PATH}/.loop/prd.json) and show the user:

Plan Ready — Review Before Running

Stories:

US-001: {title}

US-002: {title} ...

Review:

.loop/prd.json — stories and acceptance criteria

.loop/contracts/ — done conditions per story

Adjust anything, then:
/agent-loop:run

STOP. Do not start the loop. Do not write source code.

2.2 KiB Raw Permalink Blame History