| 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
2. docs/specs/{feature-name}.md
3. Glob: docs/specs/*{feature-name}*.md
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
Grep: "TBD|TODO|to be determined|to be decided" in spec file
Grep: "might|maybe|possibly|could be|we'll see|not sure" in spec file
Grep: "## Phase|### Phase|## Implementation|### Step" in spec file
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):
- What specific change are you making?
- Which file(s) will this affect?
- How will we know it works? (acceptance criteria)
- Any edge cases to handle?
- 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
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:
- Read phase requirements from spec
- Write tests first:
- Unit tests for business logic (70%)
- Integration tests for API/components (20%)
- E2E tests for critical paths (10%)
- Implement to pass tests
- Refactor while tests stay green
- Commit using worktrunk:
wt step commit --stage=modified
Commit Strategy
Make atomic commits per logical change:
wt step commit --stage=modified
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:
Run validation:
bun run lint
bun run typecheck
bun run test
bun run build
Phase 9: PR Creation
-
Ensure branch is pushed:
git push -u origin feat/{feature-name}
-
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}
Or manually:
wt remove feat/{feature-name}
Restore stashed changes if any:
git stash list
git stash pop
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}
wt switch -c feat/{feature-name} --base dev
Tests Fail After Implementation
- Diagnose the failure
- Check if test or implementation is wrong
- Fix and re-run
- 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