Feature Dev Loop

Execute a complete feature lifecycle: issue → code → sync.

Prerequisites

• [ ] bd CLI available
• [ ] Git repository initialized
• [ ] .beads/ directory exists
• [ ] No .git/index.lock file

Run scripts/validate.sh to verify.

Input Schema

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | title | string | yes | - | Feature title for beads issue | | type | feature|bugfix|chore | no | feature | Issue type | | priority | P0|P1|P2|P3|P4 | no | P2 | Issue priority | | scope | string | no | core | Commit scope | | use_worktree | boolean | no | false | Create isolated worktree |

Procedure

Step 1: Create Issue

@check: No existing issue with same title

@command:

ISSUE_ID=$(bd create --title="<title>" --type=<type> --priority=<priority> --json 2>/dev/null | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
echo "Created: $ISSUE_ID"

@output: Issue ID (e.g., superpowers-abc)

@on-error: Check bd list for duplicate titles

---

Step 2: Worktree Isolation (Optional)

@check: use_worktree is true AND branch does not exist

@command:

sp wt create feature/<slug> ../sp-<slug> --base=main
cd $(sp wt switch feature/<slug>)

@output: Working directory is isolated worktree

@on-error: If branch exists, use existing worktree or choose different name

---

Step 3: Mark In Progress

@check: Issue exists and is open

@command:

bd update $ISSUE_ID --status=in_progress

@output: Issue status changed to in_progress

---

Step 4: Implement

@check: Issue is in_progress

Execute coding task:

• Write code changes
• Add tests if applicable

@command:

pnpm --filter @sp/<package> build
pnpm --filter @sp/<package> test

@output: Build succeeds, tests pass

@on-error: Fix errors before proceeding

---

Step 5: Finish (Atomic)

@check: Implementation complete, tests pass

Use the finish script for atomic close → sync → commit → push:

@command:

npx tsx .claude/skills/feature-dev-loop/scripts/finish.ts $ISSUE_ID "<type>(<scope>): <title>"

@output: Issue closed, JSONL synced, commit pushed

@on-error: Script provides recovery hints for each failure mode

The finish script (TypeScript):

1. Pre-flight checks: Validates git repo, bd CLI, issue exists, issue status
2. Closes issue with commit message as reason
3. Syncs beads (full sync, not just flush)
4. Commits with BD_SKIP_AUTO_CREATE=1 to prevent auto-issue loop
5. Handles "nothing to commit" gracefully
6. Pushes with retry (auto-rebase on rejection, up to 3 attempts)
7. Provides recovery hints on failure with step-specific guidance

Success Criteria

• [ ] bd show $ISSUE_ID returns status: closed
• [ ] .beads/issues.jsonl contains closed issue
• [ ] git log -1 shows commit with issue ID
• [ ] git status shows clean working directory
• [ ] Remote branch updated (check with git fetch && git status)

Error Recovery

The finish.ts script handles most errors automatically. Manual recovery only needed for:

| Error | Recovery Action | |-------|-----------------| | Rebase conflicts | Resolve conflicts, git rebase --continue && git push | | Branch exists | Use --force or choose different worktree name | | Tests fail | Fix code, re-run tests before Step 5 | | Issue already closed | Manual commit: git add . && git commit -m "..." |

Auto-handled by finish.ts:

• index.lock cleanup
• Push rejection (auto-rebase retry)
• Nothing to commit (graceful skip)
• JSONL sync issues

Output Schema

{
  "status": "complete",
  "issue_id": "<beads-issue-id>",
  "commit": "<git-commit-hash>",
  "branch": "<branch-name>"
}