Feature Dev Loop

Feature Dev Loop

Orchestrate a full software feature loop by composing local development skills instead of rewriting them: requirements baseline, plan breakdown, multi-perspective plan review, safe serial implementation, dynamic acceptance review, and an HTML PR summary.

This is a controller skill. It decides when to move between stages, how feedback is classified, when loops exit, what gets written to disk, and when to involve the user. It should call or follow existing local skills for the lower-level work when they are available, especially:

• superpowers:writing-plans for implementation plans
• superpowers:subagent-driven-development for task execution with implementer/reviewer agents
• superpowers:test-driven-development for feature and bugfix implementation
• superpowers:requesting-code-review for code review dispatch
• superpowers:verification-before-completion before claiming completion
• Frontend/browser verification skills when UI behavior changes

Operating Defaults

• Use this for non-trivial feature work, multi-step changes, PR-sized tasks, or explicit requests for plan review, subagent review, acceptance testing, code review, or PR summary generation.
• For tiny edits, use a lightweight version unless the user explicitly asks for the full loop.
• Default to safe serial implementation. Only run implementation workers in parallel when file/module ownership is disjoint and shared contracts are already fixed.
• Default to human gates at the end of plan review and before final release. If the user asks for full auto mode, proceed automatically when exit criteria are met and record all assumptions.
• Save process artifacts in the target repo under docs/dev-loop-runs/YYYY-MM-DD-feature-slug/.
• Be git-aware, but do not commit, push, or open PRs unless the user explicitly asks.
• Never loop forever. Each review loop has a default limit of 3 rounds.
• Respect the active tool policy for subagents. If the user explicitly asked for subagents, delegation, plan review by agents, the full feature-dev-loop, or this skill by name, proceed with subagent dispatch when available. If not, ask before the first subagent dispatch or perform the review inline and record the limitation.

Dependency Gate

Before starting a full loop, check whether the local prerequisite skills are available in the active session. This skill depends on Superpowers-style development workflows; it should not silently degrade into an ad-hoc process when those skills are missing.

Check dependencies from the active skill list when it is available. If the active skill list is unavailable, inspect likely local skill/plugin locations such as .agents/skills/superpowers, .codex/superpowers/skills, or the harness plugin list. Do not assume a dependency exists just because this skill mentions it.

Required skills

These are required for the intended workflow:

• superpowers:writing-plans - implementation plan breakdown
• superpowers:subagent-driven-development - serial task execution with implementer/reviewer agents
• superpowers:test-driven-development - red/green/refactor discipline for behavior changes
• superpowers:requesting-code-review - structured code review dispatch
• superpowers:verification-before-completion - evidence before completion claims

Recommended skills

These are not always required, but should be used when relevant:

• superpowers:brainstorming - when the request is still rough or product/design intent is unclear
• superpowers:systematic-debugging - when implementation or tests expose a bug
• superpowers:receiving-code-review - when applying reviewer feedback
• superpowers:finishing-a-development-branch - when the user wants merge/PR/branch cleanup guidance
• superpowers:using-git-worktrees - when the user wants isolated branch/worktree execution
• Frontend/browser automation skills - when UI behavior must be visually verified

Missing dependency behavior

If any required skill is missing:

1. Stop before creating the full run directory or starting implementation.
2. Tell the user exactly which prerequisite skills are missing.
3. Recommend installing Superpowers, because these required skills are provided by the Superpowers workflow.
4. If a plugin-install tool for Superpowers is available in the current harness, use it or ask the user to approve it according to the active tool policy. Otherwise provide the appropriate install hint for the harness when known:
   • Codex App: open Plugins in the sidebar, find Superpowers in the Coding section, click +, and follow the prompts.
   • Codex CLI: run /plugins, search for superpowers, and select Install Plugin.
   • Claude Code: run /plugin install superpowers@claude-plugins-official, or register the Superpowers marketplace with /plugin marketplace add obra/superpowers-marketplace and then run /plugin install superpowers@superpowers-marketplace.
5. After the user installs it, restart the dependency check before proceeding.

If installation is not possible in the current harness, offer a reduced inline mode only after making the limitation explicit. Reduced inline mode must still create the run artifacts and record that subagent/Superpowers dependencies were unavailable.

Reference for installation and workflow names: https://github.com/obra/superpowers.

Feedback Severity

All reviewer comments must use these severities:

• BLOCKER: Must be resolved before the loop can exit.
• IMPORTANT: Should be resolved before exit. The controller may adjudicate and close it only with written rationale.
• QUESTION: Must be answered or converted into a concrete change before exit.
• NIT: Non-blocking improvement. Record it, but do not let it block progress.

A phase may exit only when there are no unresolved BLOCKER, IMPORTANT, or QUESTION items. Remaining NIT items become follow-ups.

Run Directory

At the start of a run:

1. Locate the repo root with git rev-parse --show-toplevel when available.
2. Check git status -sb.
3. Record base_sha, current branch, dirty-state summary, user request, and mode.
4. Create:

docs/dev-loop-runs/YYYY-MM-DD-feature-slug/
  00-requirements.md
  01-plan.md
  02-plan-review-rounds.md
  03-implementation-log.md
  04-acceptance-report.md
  05-pr-summary.html
  artifacts/
    screenshots/
    test-outputs/

If the working tree is dirty, do not revert anything. Decide whether existing changes are related to the requested task. If ambiguous and risky, ask the user before editing.

Phase 1: Requirements Baseline

Create 00-requirements.md before planning.

Use this structure:

# Requirements Baseline

## Goal
## Non-goals
## User-visible Behavior
## Acceptance Criteria
## Constraints
## Assumptions
## Open Questions
## Source Request
## Repo Context

Ask the user only for open questions that materially affect architecture, data model, security, user experience, compatibility, or test strategy. Infer ordinary implementation details from repo conventions and record them as assumptions.

Do not enter plan breakdown while blocking open questions remain.

Phase 2: Plan Breakdown

Explore the codebase before writing the plan. Prefer rg and existing project docs/tests. Let the repo teach the implementation style.

Create 01-plan.md. When available, follow superpowers:writing-plans.

The plan must include:

• Exact goal and architecture summary
• Files/modules expected to change
• Task order and dependencies
• Test strategy and exact verification commands
• Ownership boundaries for any worker subagents
• Acceptance criteria mapped back to 00-requirements.md
• Known risks and assumptions

Tasks should be small enough to implement and review independently. If a shared contract is needed, put it before dependent tasks.

Phase 3: Multi-perspective Plan Review Loop

Dispatch multiple plan-review subagents from different perspectives when subagents are available and permitted. Give each reviewer precise context: the requirements file, plan file, relevant repo conventions, and the requested output schema. Do not hand them the whole conversation history.

Default reviewer perspectives:

• Architecture reviewer: decomposition, boundaries, dependency order, extensibility, integration risk
• Test strategy reviewer: acceptance criteria, regression coverage, failure paths, verification commands
• Product/spec reviewer: user-visible behavior, requirement gaps, non-goals, ambiguous semantics
• Risk/complexity reviewer: hidden complexity, migration risk, rollout concerns, maintainability traps

Each reviewer must return:

## Verdict
APPROVED | COMMENTS

## Comments
- id:
  severity: BLOCKER | IMPORTANT | QUESTION | NIT
  area:
  target:
  comment:
  required_change:

## Approval Conditions

Aggregate all feedback into 02-plan-review-rounds.md.

For each round:

1. Fix the plan for all valid BLOCKER, IMPORTANT, and QUESTION feedback.
2. If rejecting a comment, write the adjudication and rationale.
3. Re-run the reviewers on the whole revised plan, not just the diff.
4. Stop after 3 rounds and escalate unresolved blocking disagreement to the user with a concrete recommendation.

Plan review exits when all reviewers approve or only NIT items remain.