---
name: scope-features-to-project
description: Show only current project features when listing, using list_project_features
status: done
parts:
  - CLAUDE.md
estimate:
  optimistic: 10 minutes
  normal: 20 minutes
  pessimistic: 45 minutes
---

# Feature: scope-features-to-project

## Description

When a user wants to know which features exist, only the current project's features should be shown. This means filtering the list_features tool to only show features belonging to the current project, rather than all features across all projects.

---

## Q & A

### Q1: Should we modify the existing `list_features` tool to accept an optional `project_path` parameter for filtering, or should we rely solely on `list_project_features` which already scans the project's ./features/ directory?
**Category:** clarification
**Answer:** Rely on `list_project_features` which already scans the project's ./features/ directory.

### Q2: Currently `list_features` shows all features from K4000_DATA_DIR (shared across projects). The `list_project_features` tool already shows only features from the current project's ./features/ folder. Should we: (A) Remove `list_features` entirely, (B) Add filtering to `list_features`, (C) Keep both but make `list_project_features` the primary/recommended tool?
**Category:** clarification
**Answer:** Option C - Keep both tools. `list_project_features` is the primary tool for users (shows current project's features), `list_features` is an internal/admin tool (shows all tracked state across all projects).

### Q3: How should the project be identified? Options: (A) Use the current working directory by default, (B) Require an explicit `project_path` parameter, (C) Both - optional parameter with cwd as default?
**Category:** clarification
**Answer:** Use the current working directory by default.

### Q4: For the filtering logic, should we match features by: (A) The `project_path` field stored in state.json, (B) The `document_path` field (checking if it's under the project's features/ directory), (C) Both?
**Category:** integration
**Answer:** Option C - Both. Check `project_path` first, fall back to checking if `document_path` is under the project's features/ directory.

### Q5: What should happen if a feature's state exists in K4000_DATA_DIR but its `project_path` is null or doesn't match the current project? Should these features be: (A) Hidden entirely, (B) Shown with a 'global' or 'unknown project' indicator?
**Category:** edge_case
**Answer:** Always assume that the current project path is the root of the features. Features without a matching project_path should be hidden from project-scoped listings.

---

## Complete Definition

### Overview

The `list_project_features` tool is already the correct solution for showing project-scoped features. It scans the `./features/` directory of the current project (using cwd by default) and shows only features that exist as markdown files in that directory.

The current implementation already:
1. Uses cwd as the default project path
2. Scans `{project_path}/features/` for `.md` files
3. Cross-references with K4000 state data when available
4. Shows "untracked" status for features without state

### What Needs to Change

The issue is **documentation and workflow guidance**, not code. The CLAUDE.md instructions should be updated to:

1. Recommend `list_project_features` as the primary tool for discovering features
2. Clarify that `list_features` is for internal/admin use (all features across all projects)
3. Update any workflow examples that use `list_features` to use `list_project_features` instead

### Tool Roles (Clarified)

| Tool | Purpose | Scope |
|------|---------|-------|
| `list_project_features` | **Primary** - Discover features to work on | Current project only |
| `list_features` | Internal/Admin - View all tracked feature states | All projects (global) |

---

## Implementation Plan

### Files to Modify

1. `CLAUDE.md` - Update documentation to clarify tool roles and recommend `list_project_features`

### Implementation Steps

1. **Update Feature Analyzer MCP Tools section in CLAUDE.md**
   - Add description clarifying `list_project_features` is the primary tool
   - Add note that `list_features` shows all features globally (admin use)

2. **Update Example Workflow in CLAUDE.md**
   - Add a step 0 showing how to discover features using `list_project_features`

3. **Update tool descriptions if needed**
   - Ensure `list_project_features` description emphasizes it's the primary discovery tool
   - Ensure `list_features` description clarifies it's global/admin

### No Code Changes Required

The `list_project_features` tool already implements the correct behavior:
- Defaults to current working directory
- Scans project's `./features/` directory
- Shows only that project's features
- Cross-references with state data for status

---

## Testing Considerations

1. **Verify `list_project_features`** correctly shows only current project features
2. **Verify `list_features`** continues to show all features globally
3. **Documentation review** - Ensure CLAUDE.md clearly guides users to the right tool

---

## Estimate

**Senior Developer Profile:** 5+ years experience, familiar with the project's tech stack.

| Scenario | Time |
|----------|------|
| Optimistic | 10 minutes |
| Normal | 20 minutes |
| Pessimistic | 45 minutes |

### Assumptions
- Only modifying CLAUDE.md documentation (no code changes needed)
- The existing `list_project_features` implementation is correct and complete
- No changes needed to MCP server code
- Clear understanding of existing tool behavior
