Marketplace feature-file

Manage features.yml for tracking requirements and progress; use proactively ONLY when features.yml already exists, or invoke manually to create one; complements TodoWrite for persistent project state.

install

source · Clone the upstream repo

git clone https://github.com/aiskillstore/marketplace

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/aiskillstore/marketplace "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/chemiseblanc/feature-file" ~/.claude/skills/aiskillstore-marketplace-feature-file && rm -rf "$T"

manifest: skills/chemiseblanc/feature-file/SKILL.md

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

Check if
```
features.yml
```
exists in project root
If missing: do not use this skill proactively (stop here)
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
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)

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

Creating a New Feature File

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

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

Identify logical feature boundaries in the code
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
Run
```
./scripts/feature-status.py --validate
```
to check consistency
Run
```
./scripts/extract-work.py
```
to see gaps

Development Workflow (Incremental Progress)

Work on ONE requirement at a time:

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

Version Management

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

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

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

Modifying Existing Requirements

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

Deprecating/Removing Requirements

Document rationale
Either:
- Remove requirement entirely, OR
- Move to
```
known-issues
```
  as historical note (e.g., "req-x removed: no longer needed")
Remove or update associated test cases
Increment
```
version
```
field
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
```