Feature File Management

Manage features.yml - a waterfall-style planning document combining structured requirements tracking with incremental development.

Quick Reference

feature: "Feature Name"
phase: Requirements | Design | Implementation | Testing | Complete
version: 1
changelog: |
  ## [1]
  ### Added
  - Initial feature
decisions:
  - Decision rationale
known-issues:
  - Known bug or limitation
requirements:
  req-id:
    description: "When X, the system SHALL Y"
    status: Not-Started | In-Progress | Needs-Work | Complete
    tested-by: [test-id]
test-cases:
  test-id:
    name: "test_function_name"
    file: "tests/test_file.py"
    description: "Given X, when Y, then Z"
    passing: true | false
    type: unit | [integration, rainy-day]  # optional, string or list
---
# Next feature...

See references/schema.md for complete field documentation.

Proactive Usage

This skill should be used automatically when features.yml exists.

Before Starting Implementation

1. Check if features.yml exists in project root
2. If missing: do not use this skill proactively (stop here)
3. Plan the work in features.yml before writing code:
   • Add/update the feature with all requirements extracted from the user's request
   • Add anticipated test cases to test-cases (with passing: false)
   • Document design decisions in decisions if non-trivial choices are involved
4. Set the first requirement to status: In-Progress

During Implementation

• Update status to Complete as requirements are finished
• Add test cases to test-cases when writing tests
• Update passing field after running tests
• Add discovered issues to known-issues

After Completing Work

• Verify all implemented requirements are marked Complete
• Run ./scripts/feature-status.py --validate to check consistency
• Commit features.yml changes with the implementation

Relationship with TodoWrite

Tool	Purpose	Persistence
TodoWrite	Immediate session actions	Ephemeral
features.yml	Requirements and progress	Persistent (in repo)

Use both: TodoWrite for what to do now, features.yml for durable project state.

Phase Transitions

From	To	Conditions
Requirements	Design	All requirements have descriptions
Design	Implementation	decisions field exists (use [] if none needed)
Implementation	Testing	All requirements In-Progress or Complete
Testing	Complete	All requirements Complete AND all tests passing: true

Scripts validate these rules and report errors.

Workflows

Agent Workflow (Condensed)

1. ls features.yml → exists? Read it : Create it
2. Plan first: Add feature, requirements, test-cases, decisions
3. Set first requirement status: In-Progress
4. Implement, then set status: Complete
5. Run tests, update passing status
6. ./scripts/feature-status.py --validate
7. Commit with implementation changes

Creating a New Feature File

1. Create features.yml with first feature:

   feature: "Feature Name"
   phase: Requirements
   version: 1
   changelog: |
     ## [1]
     ### Added
     - Initial planning
   requirements:
     req-1:
       description: "Requirement description using EARS syntax"
       status: Not-Started

2. Run ./scripts/feature-status.py to validate structure

Minimal start (for quick bootstrapping during implementation):

feature: "Feature Name"
phase: Implementation
version: 1
changelog: |
  ## [1]
  ### Added
  - Initial implementation
requirements:
  req-1:
    description: "Requirement from user request"
    status: In-Progress

Building from Existing Codebase

1. Identify logical feature boundaries in the code
2. For each feature:
   • Create feature document, set phase based on current maturity
   • Extract requirements from code behavior, comments, documentation
   • Discover existing tests and add to test-cases
   • Link tests to requirements via tested-by
   • Set status based on implementation state and test coverage
3. Run ./scripts/feature-status.py --validate to check consistency
4. Run ./scripts/extract-work.py to see gaps

Development Workflow (Incremental Progress)

Work on ONE requirement at a time:

1. Run ./scripts/extract-work.py to see incomplete requirements
2. Pick highest priority requirement, update status: In-Progress
3. Implement the requirement
4. Write/update tests, add to test-cases with passing: false
5. Run tests, update passing: true when passing
6. Update requirement status: Complete
7. Run ./scripts/feature-status.py to check phase advancement eligibility
8. Repeat

Version Management

1. Run ./scripts/check-version.py to check for needed bumps

2. If bump recommended:

   • Increment version field

   • Add new changelog section:

     changelog: |
       ## [2]
       ### Added
       - New capability
     
       ## [1]
       ...

   • Commit the update

Scripts

All scripts read from features.yml in current directory. Scripts are executable and use inline dependencies via uv run --script.

feature-status.py

Overview of all features with progress and test status (with breakdown by type if defined).

./scripts/feature-status.py                    # Plain text output
./scripts/feature-status.py --format markdown  # Markdown table
./scripts/feature-status.py --validate         # Exit 1 if validation errors

extract-work.py

List requirements needing work (status != Complete).

./scripts/extract-work.py                      # All incomplete
./scripts/extract-work.py --phase Implementation
./scripts/extract-work.py --status In-Progress
./scripts/extract-work.py --format markdown

extract-issues.py

List known issues across all features.

./scripts/extract-issues.py
./scripts/extract-issues.py --format json

check-version.py

Check git history to see if versions need bumping.

./scripts/check-version.py

Compares when feature sections were last modified vs when version was last set.

Best Practices

• One requirement at a time: Complete and verify before starting next
• Update status immediately: Keep file in sync with actual state
• Document decisions: Capture rationale in decisions before implementation
• Track known issues: Document bugs and limitations in known-issues
• Bump version on requirement changes: Any add, modify, or remove
• Use EARS syntax for requirements: "When X, the system SHALL Y"
• Use Given/When/Then for test descriptions

Change Management

All requirement changes require a version bump. This ensures traceability and clear history.

Adding Requirements to Existing Feature

1. Add requirement with status: Not-Started
2. Increment version field
3. Add changelog entry under ### Added
4. If feature is past Design phase, consider whether new requirement needs design review

Modifying Existing Requirements

1. Document rationale for the change
2. Update requirement description
3. Update status:
   • If was Complete: set to Needs-Work
   • Otherwise: keep current status
4. Review affected test cases in tested-by - update or mark as needing revision
5. Increment version field
6. Add changelog entry under ### Changed

Deprecating/Removing Requirements

1. Document rationale
2. Either:
   • Remove requirement entirely, OR
   • Move to known-issues as historical note (e.g., "req-x removed: no longer needed")
3. Remove or update associated test cases
4. Increment version field
5. Add changelog entry under ### Removed

Version Bump Triggers

Always bump version when:

• Adding, modifying, or removing requirements
• Shipping a milestone
• Significant scope changes
• Phase transitions to Complete