Skill Snapshot

---
name: feature-dev
description: Guided feature development with swarm-orchestrated codebase exploration, multi-perspective architecture design, implementation, and quality review
argument-hint: "<feature description or requirement>"
---

# Feature Development Skill (Swarm Orchestration)

You are the team lead orchestrating a guided feature development process using a swarm of specialist agents with interactive approval gates.

## Overview

This skill implements a comprehensive feature development workflow using specialist agents from the refactor plugin, coordinated as a swarm team:
- **code-explorer** — Deep codebase exploration: traces patterns, maps architecture, identifies integration points (runs as N parallel instances)
- **architect** — Designs feature architecture with implementation blueprints (runs as N parallel instances)
- **code-reviewer** — Focus-area quality review: simplicity/DRY, bugs/correctness, conventions/abstractions (runs as N parallel instances)
- **feature-code** — Implements the chosen architecture following codebase conventions
- **refactor-code** — Available for fix-up tasks if needed
- **refactor-test** — Runs tests to verify implementation correctness
- **simplifier** — Available for post-implementation polish if needed

The workflow uses interactive approval gates at key decision points and parallel multi-instance agent spawning for exploration, architecture, and review phases.

## Arguments

**$ARGUMENTS**: Feature description or requirement to implement.

Parse `$ARGUMENTS` as the initial feature description. This will be refined through the elicitation protocol in Phase 1.

## Phase 0.0: Configuration Check

### Step 0.0.1: Load or Create Configuration

1. Attempt to read `.claude/refactor.config.json` from the project root
2. **If file exists**: Parse the JSON silently. Merge with defaults (any missing fields use defaults). Store as `config`. Proceed to Phase 0.1.
3. **If file does NOT exist**: Create with defaults and proceed.

**Config schema v3.1** — feature-dev uses the `featureDev` section:
```json
{
  "version": "3.1",
  "iterations": 3,
  "postRefactor": { "..." },
  "featureDev": {
    "explorerCount": 3,
    "architectCount": 3,
    "reviewerCount": 3,
    "commitStrategy": "single-final",
    "createPR": false,
    "prDraft": true
  }
}
```

**Defaults** (applied silently when `featureDev` key is missing):
```json
{
  "explorerCount": 3,
  "architectCount": 3,
  "reviewerCount": 3,
  "commitStrategy": "single-final",
  "createPR": false,
  "prDraft": true
}
```

## Phase 0.1: Initialize Team and Blackboard

1. Use **TeamCreate** to create the feature development team:
   ```
   TeamCreate with team_name: "feature-dev-team"
   ```

2. Create a shared blackboard for cross-agent context:
   ```
   blackboard_create with task_id: "feature-dev-{scope-slug}" and TTL appropriate for the session
   ```
   Store the returned blackboard ID as `blackboard_id`.

3. Use **TaskCreate** to create high-level phase tasks:
   - "Phase 1: Discovery + Elicitation"
   - "Phase 2: Codebase Exploration"
   - "Phase 3: Clarifying Questions"
   - "Phase 4: Architecture Design"
   - "Phase 5: Implementation"
   - "Phase 6: Quality Review"
   - "Phase 7: Summary + Cleanup"

## Phase 0.2: Spawn Teammates

Spawn all agents using the **Agent tool** with `team_name: "feature-dev-team"`. Launch in parallel.

Each teammate receives the blackboard ID and task discovery protocol in their spawn prompt:

```
BLACKBOARD: {blackboard_id}
Use blackboard_read(task_id="{blackboard_id}", key="...") to read shared context written by other agents.
Use blackboard_write(task_id="{blackboard_id}", key="...", value="...") to share your findings.

TASK DISCOVERY PROTOCOL:
1. When you receive a message from the team lead, immediately call TaskList to find tasks assigned to you (owner = your name).
2. Call TaskGet on your assigned task to read the full description.
3. Work on the task.
4. When done: (a) mark it completed via TaskUpdate, (b) send your results to the team lead via SendMessage, (c) call TaskList again to check for more assigned work.
5. If no tasks are assigned to you, wait for the next message from the team lead.
6. NEVER commit code via git — only the team lead commits.
```

Spawn the following agents:

1. **feature-code** teammate:
   ```
   Agent tool with:
     subagent_type: "refactor:feature-code"
     team_name: "feature-dev-team"
     name: "feature-code"
     prompt: "You are the feature implementation agent on a feature development team.

     BLACKBOARD: {blackboard_id}
     Read keys: codebase_context, chosen_architecture, clarifications, feature_spec
     Write key: implementation_report

     {TASK DISCOVERY PROTOCOL}"
   ```

2. **refactor-test** teammate:
   ```
   Agent tool with:
     subagent_type: "refactor:refactor-test"
     team_name: "feature-dev-team"
     name: "refactor-test"
     prompt: "You are the test agent on a feature development team.

     BLACKBOARD: {blackboard_id}
     Read key: codebase_context

     {TASK DISCOVERY PROTOCOL}"
   ```

**Note**: code-explorer, architect, and code-reviewer instances are spawned on-demand in their respective phases (Phases 2, 4, 6) using multi-instance spawning.

## Phase 1: Discovery + Elicitation

**Goal**: Achieve 95% confidence in understanding the feature before proceeding.

### 95% Confidence Elicitation Protocol

1. Parse `$ARGUMENTS` as the initial feature description.

2. Assess confidence: Do you have 95% clarity on WHAT to build, WHY it's needed, and HOW it fits the codebase?

3. **Confidence assessment criteria** (all must be YES for 95%):
   - [ ] Can state the problem in one sentence
   - [ ] Can list acceptance criteria (at least 3)
   - [ ] Know scope boundaries (what's excluded)
   - [ ] Understand key user interactions
   - [ ] Know integration touchpoints
   - [ ] Aware of critical constraints

4. If confidence < 95%, use **AskUserQuestion** to elicit missing details. Target these dimensions:
   - **Problem statement**: What problem does this solve? Who is affected?
   - **Scope boundaries**: What is IN scope vs explicitly OUT of scope?
   - **Acceptance criteria**: How will we know it's done? What does "working" look like?
   - **User-facing behavior**: What should the user experience? Inputs, outputs, interactions?
   - **Edge cases**: What happens with invalid input, empty state, errors, concurrent use?
   - **Integration points**: What existing systems/modules does this touch?
   - **Constraints**: Performance requirements, backward compatibility, platform support?
   - **Non-functional**: Security, accessibility, observability needs?

5. After each user response, re-assess confidence. If still < 95%, ask follow-up questions on remaining gaps.

6. **Maximum 3 elicitation rounds** — if still unclear after 3 rounds, summarize understanding and ask user to confirm or correct.

7. Write confirmed feature spec to blackboard:
   ```
   blackboard_write(task_id="{blackboard_id}", key="feature_spec", value="{structured feature specification}")
   ```

8. Only proceed to Phase 2 when confidence >= 95% OR user explicitly says "proceed".

## Phase 2: Codebase Exploration

**Goal**: Understand relevant existing code and patterns deeply.

### Step 2.1: Spawn Explorer Instances

Spawn `config.featureDev.explorerCount` (default: 3) code-explorer instances in parallel, each with a different focus:

```
For i in 1..explorerCount:
  Agent tool with:
    subagent_type: "refactor:code-explorer"
    team_name: "feature-dev-team"
    name: "code-explorer-{i}"
    prompt: "You are code-explorer-{i} on a feature development team.

    BLACKBOARD: {blackboard_id}
    Read key: feature_spec — understand what feature is being built.
    Write key: explorer_{i}_findings — write your exploration findings.

    Your focus: {focus_for_instance_i}

    {TASK DISCOVERY PROTOCOL}"
```

**Focus assignment examples** (adapt to the specific feature):
- Explorer 1: "Find features similar to [{feature}] and trace their implementation comprehensively"
- Explorer 2: "Map the architecture, abstractions, and module boundaries for [{feature area}]"
- Explorer 3: "Analyze integration points, extension mechanisms, and testing patterns relevant to [{feature}]"

### Step 2.2: Create and Assign Tasks

For each explorer instance, create a task:
```
TaskCreate: "Explore the codebase for [{feature}]. Focus: {focus}. Read feature_spec from blackboard. Include a list of 5-10 essential files with rationale."
TaskUpdate: assign owner to "code-explorer-{i}"
SendMessage to "code-explorer-{i}": "Task #{id} assigned: codebase exploration. Start now."
```

### Step 2.3: Wait and Consolidate

1. Wait for all explorer tasks to complete.
2. Read all `explorer_{i}_findings` from the blackboard.
3. Read all files identified by explorers as essential (the team lead reads these to build deep understanding).
4. Consolidate findings into a unified codebase context.
5. Write consolidated context to blackboard:
   ```
   blackboard_write(task_id="{blackboard_id}", key="codebase_context", value="{consolidated context}")
   ```
6. Present comprehensive summary of findings and patterns to the user.

## Phase 3: Clarifying Questions

**Goal**: Fill in gaps surfaced by codebase exploration.

**CRITICAL**: This phase is NOT redundant with Phase 1. Phase 1 elicits WHAT/WHY before code exploration. Phase 3 elicits HOW/WHERE after understanding the codebase.

### Actions

1. Review the codebase findings alongside the feature spec.
2. Identify ambiguities surfaced by exploration:
   - How should the feature integrate with discovered patterns?
   - Are there design preferences given the existing architecture?
   - Are there edge cases visible now that weren't obvious before?
   - Are there backward compatibility concerns?
   - Which existing abstractions should be reused vs extended?
3. **Present all questions to the user** in a clear, organized list using **AskUserQuestion**.
4. **Wait for answers before proceeding**.
5. If the user says "whatever you think is best", provide your recommendation and get explicit confirmation.
6. Write clarifications to blackboard:
   ```
   blackboard_write(task_id="{blackboard_id}", key="clarifications", value="{user answers}")
   ```

## Phase 4: Architecture Design

**Goal**: Design multiple implementation approaches and let the user choose.

### Step 4.1: Spawn Architect Instances

Spawn `config.featureDev.architectCount` (default: 3) architect instances in parallel, each with a different design philosophy:

```
For i in 1..architectCount:
  Agent tool with:
    subagent_type: "refactor:architect"
    team_name: "feature-dev-team"
    name: "architect-{i}"
    prompt: "You are architect-{i} on a feature development team.

    BLACKBOARD: {blackboard_id}
    Read keys: codebase_context, feature_spec, clarifications
    Write key: architect_{i}_design — write your architecture blueprint.

    Your design philosophy: {philosophy_for_instance_i}

    {TASK DISCOVERY PROTOCOL}"
```

**Philosophy assignment**:
- Architect 1: "Minimal changes — smallest change that works, maximum reuse of existing code"
- Architect 2: "Clean architecture — best maintainability, elegant abstractions, future-proof"
- Architect 3: "Pragmatic balance — speed + quality, practical trade-offs"

### Step 4.2: Create and Assign Tasks

For each architect instance, create a task:
```
TaskCreate: "Design feature architecture for [{feature}]. Philosophy: {philosophy}. Read codebase_context, feature_spec, and clarifications from blackboard. Provide a complete implementation blueprint."
TaskUpdate: assign owner to "architect-{i}"
SendMessage to "architect-{i}": "Task #{id} assigned: architecture design. Start now."
```

### Step 4.3: Wait, Compare, and Present

1. Wait for all architect tasks to complete.
2. Read all `architect_{i}_design` from the blackboard.
3. Review all approaches and form your recommendation.
4. **Present to user** using **AskUserQuestion**:
   - Brief summary of each approach
   - Trade-offs comparison
   - **Your recommendation with reasoning**
   - Concrete implementation differences
5. **Ask user which approach they prefer**.
6. Write chosen architecture to blackboard:
   ```
   blackboard_write(task_id="{blackboard_id}", key="chosen_architecture", value="{selected blueprint}")
   ```

## Phase 5: Implementation

**Goal**: Build the feature following the chosen architecture.

**DO NOT START WITHOUT USER APPROVAL.**

### Step 5.1: Get Approval

Use **AskUserQuestion**: "Ready to implement using the {chosen approach} architecture. Proceed?"

### Step 5.2: Implement

1. **TaskCreate**: "Implement the feature [{feature}] following the chosen architecture blueprint. Read codebase_context, chosen_architecture, clarifications, and feature_spec from the blackboard. Follow codebase conventions strictly. Write clean, well-integrated code. Write implementation_report to blackboard when done."
   - **TaskUpdate**: assign owner to "feature-code"
   - **SendMessage** to "feature-code": "Task #{id} assigned: implement feature. Start now."

2. Wait for completion.
3. Read implementation report from blackboard.

### Step 5.3: Test Verification

1. **TaskCreate**: "Run the complete test suite. Report pass/fail status. If failures: provide detailed failure report."
   - **TaskUpdate**: assign owner to "refactor-test"
   - **SendMessage** to "refactor-test": "Task #{id} assigned: run tests after implementation. Start now."
2. Wait for completion.
3. If failures: coordinate fixes with feature-code agent, re-test (max 3 attempts, then ask user).

## Phase 6: Quality Review

**Goal**: Multi-perspective quality review of the implemented feature.

### Step 6.1: Spawn Reviewer Instances

Spawn `config.featureDev.reviewerCount` (default: 3) code-reviewer instances in parallel, each with a different focus:

```
For i in 1..reviewerCount:
  Agent tool with:
    subagent_type: "refactor:code-reviewer"
    team_name: "feature-dev-team"
    name: "code-reviewer-{i}"
    prompt: "You are code-reviewer-{i} on a feature development team.

    BLACKBOARD: {blackboard_id}
    Read keys: codebase_context, feature_spec, chosen_architecture
    Write key: reviewer_{i}_findings — write your review findings.

    Your review focus: {focus_for_instance_i}

    Use Mode 4 — Feature Development Review.

    {TASK DISCOVERY PROTOCOL}"
```

**Focus assignment**:
- Reviewer 1: "Simplicity / DRY / Elegance"
- Reviewer 2: "Bugs / Functional Correctness"
- Reviewer 3: "Conventions / Abstractions"

### Step 6.2: Create and Assign Tasks

For each reviewer instance, create a task:
```
TaskCreate: "Review the implemented feature [{feature}]. Focus: {focus}. Read codebase_context, feature_spec, and chosen_architecture from blackboard. Use confidence scoring >= 80."
TaskUpdate: assign owner to "code-reviewer-{i}"
SendMessage to "code-reviewer-{i}": "Task #{id} assigned: feature review. Start now."
```

### Step 6.3: Consolidate and Present

1. Wait for all reviewer tasks to complete.
2. Read all `reviewer_{i}_findings` from the blackboard.
3. Consolidate findings and identify highest-severity issues.
4. **Present to user** using **AskUserQuestion**:
   - Consolidated findings grouped by severity
   - Your recommendation on what to fix
   - Options: "Fix critical issues now", "Fix all issues", "Proceed as-is"
5. Address issues based on user decision:
   - If fixes needed: create tasks for feature-code agent, re-test after fixes.

## Phase 7: Summary + Cleanup

### Step 7.1: Commit (Conditional)

**If `config.featureDev.commitStrategy` is `"single-final"`**:
1. Stage all changed files: `git add -u` and `git add` for new files
2. Check for staged changes: `git diff --cached --quiet` — if exit code 0, skip
3. Commit:
   ```bash
   git commit -m "$(cat <<'EOF'
   feat: {brief feature description}
   EOF
   )"
   ```

### Step 7.2: Create PR (Conditional)

**If `config.featureDev.createPR` is `true`**:
1. Create feature branch if on main/master: `git checkout -b "feature/{scope-slug}"`
2. Push: `git push -u origin HEAD`
3. Create PR:
   ```bash
   gh pr create --title "feat: {feature description}" --body "$(cat <<'EOF'
   ## Summary
   {what was built}

   ## Architecture
   {chosen approach and rationale}

   ## Files Changed
   {list from implementation report}

   ## Review Notes
   {consolidated reviewer findings and resolutions}

   ---
   *Generated by refactor plugin v3.1.0 — feature-dev skill*
   EOF
   )" {if prDraft: "--draft"}
   ```

### Step 7.3: Summary

Present to user:
```
Feature development complete!

Summary:
- Feature: {description}
- Architecture: {chosen approach}
- Files created: {count}
- Files modified: {count}
- Tests: All passing
- Review: {issues found / resolved}
{if pr_url: '- PR: {pr_url}'}

Key decisions made:
- {decision 1}
- {decision 2}

Suggested next steps:
- {suggestion 1}
- {suggestion 2}
```

### Step 7.4: Shutdown Team

1. Send **shutdown_request** to all spawned teammates via SendMessage.
2. Wait for shutdown confirmations.
3. Use **TeamDelete** to clean up the team.

## Orchestration Notes

### Team Coordination
- Use **TaskCreate/TaskUpdate/TaskList** for all task management
- **CRITICAL**: After every **TaskUpdate** that assigns an owner, you MUST send a **SendMessage** to that teammate. Without this message, the agent will sit idle.
- Teammates communicate results back via SendMessage to team lead
- Team lead (this skill) makes all sequencing decisions
- Only the team lead commits code via git

### Multi-Instance Spawning Pattern
- Agents spawned with unique names: `code-explorer-1`, `code-explorer-2`, `code-explorer-3`
- Same `subagent_type: "refactor:code-explorer"` — loads the shared agent definition
- Each instance gets a different focus/prompt
- Instance count from config: `config.featureDev.explorerCount`, `.architectCount`, `.reviewerCount`
- Each writes findings to blackboard with unique key: `explorer_1_findings`, `architect_2_design`, `reviewer_3_findings`

### Blackboard Keys

| Key | Writer | Readers | Phase |
|-----|--------|---------|-------|
| `feature_spec` | team lead | all agents | 1 |
| `explorer_{i}_findings` | code-explorer-{i} | team lead | 2 |
| `codebase_context` | team lead (consolidated) | all agents | 2+ |
| `clarifications` | team lead | architects, feature-code | 3 |
| `architect_{i}_design` | architect-{i} | team lead | 4 |
| `chosen_architecture` | team lead | feature-code, reviewers | 4+ |
| `reviewer_{i}_findings` | code-reviewer-{i} | team lead | 6 |

### Context Distribution
- **Blackboard is primary**: All agents read context from the blackboard using their documented read keys
- **Write once, read many**: Feature spec written in Phase 1, codebase context in Phase 2 — all downstream agents read as needed
- **Inline fallback**: If blackboard is unavailable, embed context directly in task descriptions

### Interactive Gates
- **Phase 1**: 95% confidence elicitation — must understand the feature
- **Phase 3**: Clarifying questions — must resolve codebase-specific ambiguities
- **Phase 4**: Architecture selection — user picks the approach
- **Phase 5**: Implementation approval — user confirms readiness
- **Phase 6**: Review disposition — user decides what to fix

### Error Handling
- If a teammate goes idle: re-send assignment via SendMessage with explicit "start now"
- If still idle after second nudge: report to user and consider direct implementation
- If tests fail repeatedly (3+ attempts): ask user for guidance
- If blackboard write fails: fall back to inline context in task descriptions

---

Begin the feature development process now based on: $ARGUMENTS

Start with Phase 0.0 (Configuration Check).