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:

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

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:

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