Feature Cycle Workflow

This skill defines the complete feature development workflow. It wraps TDD cycles with higher-level orchestration.

Cycle Overview

PLAN → [TDD-CYCLE → COMMIT]* → ARCHIVE → DOCUMENT

Human approval required before each phase transition.

Phase Details

PLAN: Define Feature Specification

Agent: feature-planner

Actions:

1. Analyze user request
2. Research existing codebase patterns
3. Identify ambiguities — ask human for clarification
4. Write feature specification with acceptance criteria
5. Stop and present spec for approval

Output: Feature specification with numbered acceptance criteria (ACs)

Exit: Human approves spec → proceed to first TDD cycle

TDD-CYCLE: Implement One Acceptance Criterion

Skill: tdd-workflow

Actions:

1. Pick next incomplete AC from feature spec
2. Run full TDD cycle: RED → GREEN → REVIEW → REFACTOR
3. Report completion status

Rules:

• One AC per TDD cycle
• Follow tdd-workflow skill completely
• Update .feature_context.md with AC completion status

Exit: TDD cycle complete → proceed to commit

COMMIT: Commit Changes

Actions:

1. Stage relevant files
2. Generate commit message based on convention
3. Human approves commit
4. Commit changes

Commit Message Detection:

1. Check for .release-please-manifest.json or release-please-config.json
2. If present, follow configured commit convention
3. If absent, use conventional commits
4. Study recent git history to match established patterns

Conventional Commit Prefixes:

Rules:

• Never auto-commit — ask human first
• Keep commits atomic — one logical change per AC
• Combine test and implementation in single commit when they form one logical unit

Exit: Commit complete → check if more ACs remain

Loop Check: More Acceptance Criteria?

After each COMMIT:

1. Review .feature_context.md for remaining ACs
2. If incomplete ACs exist → return to TDD-CYCLE
3. If all ACs complete → propose feature completion to human
4. Human confirms → proceed to ARCHIVE

ARCHIVE: Preserve Context

Actions:

1. Move .tdd_context.md to .tdd_archive/ with timestamp
2. Archive .feature_context.md similarly

Archive Naming: YYYY-MM-DD_HH-MM_feature-name.md

Exit: Context archived → proceed to DOCUMENT

DOCUMENT: Update Project Documentation

Actions:

1. Review cycle for documentation-worthy insights:
   • New patterns discovered
   • Project structure decisions
   • Technology choices and rationales
   • Common pitfalls and solutions
2. Update relevant project docs:
   • CLAUDE.md/AGENTS.md — project configuration
   • CONTRIBUTING.md — development workflow
   • Architecture decision records
3. Stage and commit documentation changes

Rules:

• Documentation commits use docs: prefix
• Only document actual learnings — no speculation
• Ask human approval before committing

Exit: Documentation updated → feature cycle complete

Context Preservation

Feature Context File

.feature_context.md tracks feature-level state across TDD cycles:

# Feature Context

**Feature**: User Authentication
**Started**: 2026-01-29 10:00
**Current Phase**: TDD-CYCLE (AC #2)

## Acceptance Criteria

- [x] AC1: User can log in with email and password
- [ ] AC2: User can log out from any page
- [ ] AC3: Invalid credentials show error message

## Commits

- `feat: implement login with email/password` (AC1)

## Notes

- Using JWT with RS256 algorithm
- Tokens stored in httpOnly cookies

TDD Context File

.tdd_context.md tracks state within a single TDD cycle. See tdd-workflow skill for format.

Archive Structure

.tdd_archive/
├── 2026-01-29_10-00_auth-feature_context.md
├── 2026-01-29_10-00_auth-ac1_tdd.md
├── 2026-01-29_11-30_auth-ac2_tdd.md
└── ...

Gitignore Entry:

# Feature cycle context files
.feature_context.md
.tdd_context.md
.tdd_archive/

Anti-Patterns

• Starting TDD without approved feature spec
• Implementing multiple ACs in one TDD cycle
• Committing without human approval
• Skipping ARCHIVE or DOCUMENT phases
• Modifying feature spec mid-cycle without human approval