feature

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

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:

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

# 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

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

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

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

If behind, pull latest:

git checkout dev && git pull origin dev

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

Create new worktree from dev using Worktrunk:

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:

   wt step commit --stage=modified  # LLM-generated commit message
   

Commit Strategy

Make atomic commits per logical change:

# 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:

bun run lint
bun run typecheck  # if available
bun run test
bun run build

Phase 9: PR Creation

1. Ensure branch is pushed:

   git push -u origin feat/{feature-name}
   

2. Create PR (targeting dev branch):

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:

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

Or manually:

wt remove feat/{feature-name}  # Delete worktree and branch

Restore stashed changes if any:

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

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