---
name: list-features-in-features-folder
description: New MCP tool to list features in project's ./features/ directory with status
status: done
parts:
  - src/servers/feature.rs
---

# Feature: list-features-in-features-folder

## Description

Create a new tool in the features MCP to list all features that exist in the ./features/ directory of the project's root. Mark the features that have been done so that the user can select a feature that should be implemented.

---

## Q & A

### Q1: Currently, `list_features` only shows features that have a state.json in the K4000_DATA_DIR. The new tool should scan the project's ./features/ directory for .md files. Should this new tool replace `list_features` or be a separate tool (e.g., `list_project_features`)?
**Category:** clarification
**Answer:** Create a new separate tool. The current list_features is used to check if features exist in state. The new tool is for working with markdown files - letting users see what has been implemented and select features to analyze/implement.

### Q2: How should we determine if a feature is 'done'? Options: (A) Check if there's a corresponding state.json with status='done', (B) Look for a specific marker in the markdown file itself (e.g., '## Status: Done'), (C) Both - check state.json first, then fall back to markdown parsing?
**Category:** clarification
**Answer:** Option C - Check state.json first for status='done', then fall back to markdown parsing if no state exists.

### Q3: Should the tool require a project_path parameter, or should it default to the current working directory like `create_feature` does?
**Category:** clarification
**Answer:** Default to current working directory (like create_feature does).

### Q4: What information should be returned for each feature? Minimum would be: name, file_path, is_done. Should we also include: description (first paragraph), status (from state.json if available), has_questions, question_count?
**Category:** missing_requirement
**Answer:** Minimum info (name, file_path, is_done) plus question_count and answered_count.

### Q5: How should we handle .md files in ./features/ that were not created by K4000 (i.e., no corresponding state.json)? Should they be listed as 'untracked' features that can be imported?
**Category:** edge_case
**Answer:** Show the file name and let the user select one if they want to begin analyzing and implementing it. This is the core use case - discovering features to work on.

### Q6: Should the tool only list top-level .md files in ./features/ or also recursively scan subdirectories?
**Category:** edge_case
**Answer:** Look recursively for all ./features/**/*.md files.

### Q7: Feature name extraction - For a file at `features/auth/login.md`, what should the name be?
**Category:** clarification
**Answer:** Flattened with separator: `auth-login`

### Q8: State matching - When checking for state.json, how should we match?
**Category:** clarification
**Answer:** Check both - exact filename match AND check `document_path` in existing states to find matches.

---

## Complete Definition

### Tool Name
`list_project_features`

### Purpose
Scan the `./features/` directory of a project to discover feature markdown files, showing their status and enabling users to select features for analysis and implementation.

### Input Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `project_path` | string | No | Current working directory | Path to the project root |

### Output Schema
```json
{
  "features": [
    {
      "name": "auth-login",
      "file_path": "/project/features/auth/login.md",
      "status": "done",
      "is_done": true,
      "question_count": 5,
      "answered_count": 5
    },
    {
      "name": "payment-integration",
      "file_path": "/project/features/payment-integration.md",
      "status": "untracked",
      "is_done": false,
      "question_count": 0,
      "answered_count": 0
    }
  ],
  "project_path": "/project",
  "total_count": 2,
  "done_count": 1,
  "untracked_count": 1
}
```

### Status Values
- `done` - Feature implementation is complete
- `reviewing` - Feature is in code review
- `implementing` - Feature is being implemented
- `ready` - Feature spec is ready for implementation
- `awaiting_answers` - Questions pending answers
- `analyzing` - Feature is being analyzed
- `draft` - Initial state
- `untracked` - Markdown file exists but no K4000 state

### Feature Name Extraction
For nested files, flatten the path with `-` separator:
- `features/login.md` → `login`
- `features/auth/login.md` → `auth-login`
- `features/payments/stripe/checkout.md` → `payments-stripe-checkout`

### State Matching Logic
1. First, try exact match: look for `{K4000_DATA_DIR}/features/{name}/state.json`
2. Then, scan all existing states and check if any `document_path` matches the markdown file path
3. If no state found, mark as `untracked`

### Markdown Status Fallback
If no state.json exists, optionally parse the markdown for status markers:
- Look for `## Status` section
- Look for `status: done` in frontmatter (if YAML frontmatter exists)
- Default to `untracked` if no markers found

---

## Implementation Plan

### Files to Modify
1. `src/servers/feature.rs` - Add the new tool, request type, and helper functions

### Implementation Steps

1. **Add Request Type** - `ListProjectFeaturesRequest` with optional `project_path`

2. **Add Response Types**:
   - `ProjectFeatureSummary` struct for individual features
   - `ListProjectFeaturesResponse` struct for the full response

3. **Add Helper Function** - `scan_features_directory()`:
   - Use `walkdir` or manual recursive scan of `{project_path}/features/`
   - Find all `*.md` files
   - Extract feature name from relative path (flatten with `-`)
   - For each file, determine status using state matching logic
   - Return sorted list

4. **Implement the Tool** - `list_project_features()`:
   - Accept optional `project_path` (default to cwd)
   - Call `scan_features_directory()`
   - Calculate summary counts
   - Return JSON response

5. **Add Unit Tests**:
   - Test with empty features directory
   - Test with mixed tracked/untracked features
   - Test recursive scanning and name flattening
   - Test status determination logic
   - Test state matching by document_path

### Dependencies
May need to add `walkdir` crate for recursive directory scanning (or use `tokio::fs` with manual recursion).

---

## Testing Considerations

1. **Empty directory** - Should return empty features array gracefully
2. **No features directory** - Should return empty array or create the directory
3. **Mixed states** - Some features tracked, some untracked
4. **Nested directories** - Verify correct name flattening
5. **State matching** - Verify both exact match and document_path match work
6. **Permission errors** - Handle gracefully if directory not readable
