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