# Feature

> Implement features using worktree-based development with TDD. Use after spec approval to build features in isolated git worktrees with quality gates.

- Skill: `l3wi/feature` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add l3wi/feature`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l3wi/feature/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: l3wi (https://skillmd.com/u/l3wi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l3wi/feature

---


# Feature Implementation Skill

Implement features using isolated git worktrees, TDD methodology, and structured PR creation.

**Key principle:** Don't start implementing until the spec is implementation-ready.

## Usage

```
/skill:feature [feature-name]                 # Implement from existing spec
/skill:feature [feature-name] --no-worktree   # Implement in current branch
/skill:feature [feature-name] --continue      # Resume work on existing worktree
/skill:feature [feature-name] --reset         # Delete existing worktree and start fresh
/skill:feature [feature-name] --skip-checks   # Skip readiness assessment (use with caution)
```

## Workflow Overview

```
1. Request Analysis      → Is the request clear enough?
2. Spec Discovery        → Find and load the spec
3. Readiness Assessment  → Is the spec implementation-ready?
4. Gap Resolution        → Interview or redirect if needed
5. Pre-flight Checks     → Git state, worktree setup
6. Implementation        → TDD approach
7. Quality Gates         → Tests, lint, build
8. PR Creation           → Draft PR for review
```

## Phase 1: Request Analysis

Before looking for a spec, analyze the user's request:

### Clear Requests (proceed)
```
/skill:feature user-avatar-upload      ✓ Specific feature name
/skill:feature api-rate-limiting       ✓ Clear scope
/skill:feature checkout-flow-v2        ✓ Named feature
```

### Vague Requests (need clarification)
```
/skill:feature improvements            ✗ Too vague - what improvements?
/skill:feature make it faster          ✗ No specific scope
/skill:feature fix the bugs            ✗ Which bugs?
/skill:feature                         ✗ No feature specified
```

**If request is vague, ask for clarification:**
- "What specific feature or improvement would you like to implement?"

**Route appropriately:**
| Response | Action |
|----------|--------|
| New feature, no spec | Suggest `/skill:plan {feature}` → `/skill:feature` |
| Improvement, has review | Suggest `/skill:plan {feature} --spec --from-review` → `/skill:feature` |
| Bug fix | Enter plan mode instead |
| Has spec file | Proceed with provided path |

## Phase 2: Spec Discovery

Search for the spec in order:

```bash
1. docs/specs/{feature-name}-spec.md      # Primary location
2. docs/specs/{feature-name}.md           # Alternate naming
3. Glob: docs/specs/*{feature-name}*.md   # Fuzzy match
```

**If no spec found:**
- Offer to create spec with `/skill:plan {feature-name} --spec`
- Allow specifying a different path
- For truly simple changes (< 50 lines), allow no-spec mode

## Phase 3: Readiness Assessment

**This is the critical gate.** Validate the spec is implementation-ready.

### Spec Readiness Criteria

| Criteria | Check | Blocking? |
|----------|-------|-----------|
| Implementation phases | Has numbered phases with descriptions | Yes |
| File targets | Specifies files to create/modify | Yes |
| Testable acceptance criteria | Has measurable success conditions | Yes |
| No TBD sections | No "TBD", "to be determined", "TODO" | Yes |
| No ambiguous language | No "might", "possibly", "maybe" | Yes |
| API contracts (if API) | Full request/response schemas | Yes |
| Data models (if data) | Types with field definitions | Yes |
| Error handling | Error scenarios enumerated | No (warn) |
| Performance targets | Specific numbers if relevant | No (warn) |

### Scanning for Issues

```bash
# Check for TBD/TODO in spec
Grep: "TBD|TODO|to be determined|to be decided" in spec file

# Check for ambiguous language
Grep: "might|maybe|possibly|could be|we'll see|not sure" in spec file

# Check for implementation phases
Grep: "## Phase|### Phase|## Implementation|### Step" in spec file

# Check for file targets
Grep: "src/|lib/|components/|\.ts|\.tsx|\.py" in spec file
```

## Phase 4: Gap Resolution

If readiness assessment finds issues, resolve them before proceeding.

### Minor Gaps (1-3 issues)
Conduct targeted interview:
- "The spec is missing [X]. Can you clarify?"

**Gap-specific questions:**
| Gap | Question |
|-----|----------|
| Missing phases | "How should we break this into implementation steps?" |
| Missing file targets | "Which files should this change touch?" |
| TBD section found | "The spec says TBD for [X]. What should it be?" |
| Ambiguous requirement | "The spec says 'might [X]'. Should we include this or not?" |
| Missing API schema | "What should the request/response look like for [endpoint]?" |
| Missing error handling | "What should happen when [error case] occurs?" |

After interview, update spec file and re-run assessment.

### Major Gaps (4+ issues)
Redirect to spec workflow:
```
The spec has significant gaps. Consider:
1. Run `/skill:plan {feature-name} --spec` to regenerate
2. Manually update the spec and retry
```

### No Spec Mode (simple changes only)

For changes estimated < 50 lines:

**Scoping interview (5 questions):**
1. What specific change are you making?
2. Which file(s) will this affect?
3. How will we know it works? (acceptance criteria)
4. Any edge cases to handle?
5. Estimated scope? (< 50 / 50-200 / > 200 lines)

**If > 50 lines:** Redirect to spec workflow
**If < 50 lines:** Generate lightweight task doc and proceed

## Phase 5: Pre-flight Checks

### Check Working Directory State

```bash
git status --porcelain
```

If dirty (uncommitted changes):
- **Prompt user**: "You have uncommitted changes. How should I proceed?"
  - `stash` - Stash changes and continue
  - `commit` - Commit changes first
  - `abort` - Stop and let user handle manually

### Check Existing Worktree

```bash
wt list  # List all worktrees
```

If `feat/{feature-name}` exists:
- `--continue` flag: Switch to it and resume
- `--reset` flag: Delete and recreate
- No flag: Prompt user for choice

### Verify Base Branch

```bash
git fetch origin dev
git rev-list --count dev..origin/dev
```

If behind, pull latest:
```bash
git checkout dev && git pull origin dev
```

## Phase 6: Worktree Setup (unless --no-worktree)

Create new worktree from `dev` using Worktrunk:

```bash
wt switch -c feat/{feature-name} --base dev
```

**Branch Strategy:**
- Features branch from `dev` (working branch)
- PRs merge to `dev`
- `dev` → `main` for releases

## Phase 7: Implementation Execution

### TDD Approach

For each phase in the spec:

1. **Read phase requirements** from spec
2. **Write tests first**:
   - Unit tests for business logic (70%)
   - Integration tests for API/components (20%)
   - E2E tests for critical paths (10%)
3. **Implement to pass tests**
4. **Refactor** while tests stay green
5. **Commit** using worktrunk:
   ```bash
   wt step commit --stage=modified  # LLM-generated commit message
   ```

### Commit Strategy

Make atomic commits per logical change:

```bash
# After completing a logical unit of work:
wt step commit --stage=modified  # Generates: "feat(avatar): add S3 upload configuration"
```

**Commit message format** (auto-generated):
```
feat({scope}): {description}
fix({scope}): {description}
test({scope}): {description}
refactor({scope}): {description}
```

## Phase 8: Quality Gates

Before proceeding to PR:

- [ ] All tests pass
- [ ] Coverage meets targets (80% for new code)
- [ ] No linting errors
- [ ] Build succeeds
- [ ] Types check
- [ ] Self-review complete

Run validation:
```bash
bun run lint
bun run typecheck  # if available
bun run test
bun run build
```

## Phase 9: PR Creation

1. Ensure branch is pushed:
   ```bash
   git push -u origin feat/{feature-name}
   ```

2. Create PR (targeting `dev` branch):

```bash
gh pr create --draft --base dev \
  --title "feat({scope}): {description}" \
  --body "## Summary

[Generated from spec - 2-3 sentences]

Implements: docs/specs/{feature-name}-spec.md

## Changes

- [Key change 1]
- [Key change 2]
- [Key change 3]

## Test Plan

- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist

- [ ] Tests pass
- [ ] Lint passes
- [ ] Build succeeds
- [ ] Self-reviewed
- [ ] Docs updated (if needed)

---
**Spec**: docs/specs/{feature-name}-spec.md
**PRD**: docs/prds/{feature-name}.md
"
```

## Phase 10: Cleanup (after merge)

After PR is merged:

```bash
wt merge feat/{feature-name}  # Squash, rebase, cleanup
```

Or manually:
```bash
wt remove feat/{feature-name}  # Delete worktree and branch
```

Restore stashed changes if any:
```bash
git stash list  # Check for auto-stash
git stash pop   # If found
```

## Output

- **Code**: Implementation in feature branch
- **Tests**: Test files per testing strategy
- **PR**: Draft pull request ready for review

## Implementation Guidelines

### PR Size

Keep PRs under 400 lines:
- If spec has multiple phases, consider one PR per phase
- Split large features into incremental PRs
- Each PR should be independently reviewable

### Code Quality

- Follow existing codebase patterns
- Use established utilities
- Don't introduce new dependencies without ADR
- Handle errors explicitly
- Add appropriate logging

## Error Handling

### Worktree Creation Fails
```bash
wt remove feat/{feature-name}  # Clean up
wt switch -c feat/{feature-name} --base dev  # Retry
```

### Tests Fail After Implementation
1. Diagnose the failure
2. Check if test or implementation is wrong
3. Fix and re-run
4. Don't proceed to PR with failing tests

## Examples

### Ready Spec → Direct Implementation

```
User: /skill:feature user-avatar-upload

Pi: Loading spec from docs/specs/user-avatar-upload-spec.md...

Readiness Assessment:
✓ Implementation phases: 3 phases
✓ File targets: 8 files specified
✓ Acceptance criteria: 5 testable criteria
✓ No TBD sections
✓ No ambiguous language
✓ API contracts: Complete
✓ Data models: Defined
✓ Error handling: Covered
✓ Performance targets: Specified

Spec is implementation-ready.

Pre-flight checks:
✓ Working directory clean
✓ No existing worktree
✓ dev branch up-to-date

Creating worktree...
> wt switch -c feat/user-avatar-upload --base dev

Starting implementation...
```

### Spec with Gaps → Interview

```
User: /skill:feature user-notifications

Pi: Loading spec...

Readiness Assessment:
✓ Implementation phases: 3 phases
✓ File targets: specified
✗ TBD found: "Notification storage: TBD"
✗ Ambiguous: "might support email notifications"
✓ API contracts: Complete

The spec has gaps. Let me clarify:

Q: The spec says 'Notification storage: TBD'. What storage should we use?
User: PostgreSQL with a notifications table

Q: Should we include email notifications in this implementation?
User: No, just in-app for now

Updated spec. Re-running assessment...
✓ All critical checks pass

Proceeding with implementation...
```

## Related

- `/skill:plan` - Planning workflow (PRD → Spec → Tasks)
- `/skill:review-codebase` - Review for improvement opportunities
- `/skill:swarm` - Parallel agent execution and orchestration