---
name: rename-features-to-tasks
description: Rename features to tasks with subfolder structure and local state storage
status: done
parts:
- src/servers/feature.rs
- src/types/feature.rs
- src/storage.rs
- src/bin/feature_mcp.rs
- CLAUDE.md
estimate:
  optimistic: 6 hours
  normal: 10 hours
  pessimistic: 16 hours
---

# Task: rename-features-to-tasks

## Description

Restructure K4000 from a `features/` folder with single `.md` files to a `tasks/` folder with subfolders per task. Each task subfolder contains:

- `task.md` - User-authored original description (read-only for K4000)
- `plan.md` - Implementation plan + estimate (K4000 writes this)
- `questions.md` - Q&A section (K4000 writes, updates as user answers)

State storage moves from central `K4000_DATA_DIR` to `tasks/.state/` within each project.

All MCP tools renamed from `*_feature*` to `*_task*` (breaking change).

## Complete Definition

### New Directory Structure

```
project/
  tasks/
    .state/
      my-task/
        state.json       # Task state (status, metadata)
        review-*.json    # Review sessions
    my-task/
      task.md            # User's original description (K4000 reads only)
      plan.md            # Implementation plan + estimate (K4000 writes)
      questions.md       # Q&A section (K4000 writes/updates)
      mockup.png         # User can add other assets
```

### File Responsibilities

| File | Created By | Read By | Written By |
|------|------------|---------|------------|
| task.md | User | K4000, User | User only |
| plan.md | K4000 | K4000, User | K4000 |
| questions.md | K4000 | K4000, User | K4000 |
| .state/*/state.json | K4000 | K4000 | K4000 |

### MCP Tool Renames

| Old Name | New Name |
|----------|----------|
| `list_features` | `list_tasks` |
| `list_project_features` | `list_project_tasks` |
| `create_feature` | `create_task` |
| `get_feature_status` | `get_task_status` |
| `get_feature_document` | `get_task_document` |
| `analyze_feature` | `analyze_task` |
| `save_questions` | `save_questions` (unchanged) |
| `save_qa_response` | `save_qa_response` (unchanged) |
| `update_feature_document` | `update_task_plan` |
| `set_feature_status` | `set_task_status` |
| `get_project_context` | `get_project_context` (unchanged) |

### Migration Support

When K4000 detects a `features/` folder but no `tasks/` folder:
1. Prompt user: "Found features/ folder. Would you like to migrate to tasks/ format?"
2. If yes, for each `feature-name.md`:
   - Create `tasks/feature-name/` folder
   - Copy content to `tasks/feature-name/task.md`
   - Extract Q&A section to `questions.md`
   - Extract Implementation Plan + Estimate to `plan.md`
   - Migrate state from `K4000_DATA_DIR/features/feature-name/` to `tasks/.state/feature-name/`
3. Optionally delete old `features/` folder after successful migration

### plan.md Format

```markdown
# Implementation Plan

## Task Summary

| ID | Task | Files |
|----|------|-------|
| T1 | Description | `path/to/file.rs` |

## Tasks

- [ ] **T1**: Detailed task description
- [ ] **T2**: Another task

## Testing Considerations

- How to test
- Edge cases

---

## Estimate

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

| Scenario | Time |
|----------|------|
| Optimistic | X hours |
| Normal | Y hours |
| Pessimistic | Z hours |

### Assumptions
- Assumption 1
- Assumption 2
```

### questions.md Format

```markdown
# Questions & Answers

## Q1: Question text here?
**Category:** clarification
**Answer:** User's answer here

## Q2: Another question?
**Category:** edge_case
**Answer:** *Pending*
```

### Behavior Changes

1. **analyze_task**: Reads `task.md`, generates questions, writes to `questions.md`
2. **save_qa_response**: Updates answer in `questions.md`
3. **update_task_plan**: Writes/updates `plan.md` (not task.md)
4. **Plan updates during implementation**: When Claude discovers the plan needs changes, update `plan.md` to reflect reality

---

## Q & A

### Q1: Should K4000 support BOTH folder names (`features/` and `tasks/`) for backwards compatibility, or should it exclusively use `tasks/` and require migration of existing projects?
**Category:** clarification
**Answer:** Only tasks/ folder - no backwards compatibility with features/

### Q2: For the state.json file (currently stored in K4000_DATA_DIR), should it remain in the central data directory or move into each task's subfolder alongside task.md/plan.md/questions.md?
**Category:** clarification
**Answer:** Create a .state/ folder inside the tasks/ folder and store state there (not in central K4000_DATA_DIR)

### Q3: When you say 'k4000 shouldn't touch task.md', should K4000 still READ task.md to extract the original description, or should task.md be completely ignored by K4000 (user creates it manually)?
**Category:** clarification
**Answer:** K4000 should READ task.md but should NOT write to it - it's user-authored only

### Q4: What content goes in plan.md? Is this the 'Implementation Plan' section that currently appears in feature documents, or something different? Should it include the estimate section too?
**Category:** missing_requirement
**Answer:** Yes - plan.md contains the Implementation Plan section and the Estimate section

### Q5: For questions.md, should this be the Q&A section (questions + answers) or just the questions? What format - markdown with headers per question, or simpler list format?
**Category:** missing_requirement
**Answer:** Q&A format - questions and answers together, updated when user answers

### Q6: What does 'changes along the way to the code or to the task should be reflected in the documents' mean specifically? Should K4000 auto-update plan.md when implementation differs from the plan? Track git commits? Something else?
**Category:** clarification
**Answer:** If during implementation new things come up and the task plan changes, plan.md needs to be updated to reflect reality

### Q7: How should existing features in the `features/` folder be handled? Automatic migration tool? Manual migration? Support both formats during transition?
**Category:** edge_case
**Answer:** Ask the user if they want to migrate existing features/ to tasks/ and help them through the migration

### Q8: Should the MCP tools be renamed too (e.g., `create_feature` → `create_task`, `list_features` → `list_tasks`)? This would be a breaking change for existing users.
**Category:** integration
**Answer:** Yes - rename all MCP tools from feature* to task* (breaking change)

---

## Implementation Plan

### Task Summary

| ID | Task | Files |
|----|------|-------|
| T1 | Rename types: Feature* → Task* | `src/types/feature.rs` → `src/types/task.rs`, `src/types/mod.rs` |
| T2 | Update storage for tasks/.state/ structure | `src/storage.rs` |
| T3 | Rename server and tools | `src/servers/feature.rs` → `src/servers/task.rs`, `src/servers/mod.rs` |
| T4 | Update binary entry point | `src/bin/feature_mcp.rs` → `src/bin/task_mcp.rs` |
| T5 | Implement multi-file task structure (task.md, plan.md, questions.md) | `src/servers/task.rs` |
| T6 | Add migration tool for features/ → tasks/ | `src/servers/task.rs` |
| T7 | Update CLAUDE.md documentation | `CLAUDE.md` |
| T8 | Update Cargo.toml binary names | `Cargo.toml` |

### Tasks

- [ ] **T1**: Rename all Feature* types to Task* (FeatureState → TaskState, FeatureStatus → TaskStatus, FeatureSummary → TaskSummary, etc.)
- [ ] **T2**: Modify StateManager to use `tasks/.state/{task-name}/` structure instead of central K4000_DATA_DIR. Remove dependency on K4000_DATA_DIR for task state.
- [ ] **T3**: Rename FeatureAnalyzerServer → TaskAnalyzerServer, rename all tool methods (list_features → list_tasks, etc.)
- [ ] **T4**: Rename binary from k4000-feature-mcp to k4000-task-mcp
- [ ] **T5**: Implement reading from task.md (read-only), writing to plan.md and questions.md separately
- [ ] **T6**: Add `migrate_features` tool that detects features/ folder and offers migration to tasks/ format
- [ ] **T7**: Update all documentation in CLAUDE.md to reference tasks instead of features
- [ ] **T8**: Update Cargo.toml [[bin]] section for new binary name

### Testing Considerations

- Test new directory structure creation (tasks/.state/, task subfolders)
- Test task.md is never written to by K4000
- Test plan.md and questions.md are created/updated correctly
- Test migration from existing features/ folder
- Test state loading from new tasks/.state/ location
- Ensure review server still works with renamed types

---

## Estimate

**Senior Developer Profile:** 5+ years experience, familiar with Rust and the K4000 codebase.

| Scenario | Time |
|----------|------|
| Optimistic | 6 hours |
| Normal | 10 hours |
| Pessimistic | 16 hours |

### Assumptions
- Existing test infrastructure can be adapted for new structure
- No changes needed to the review MCP server beyond type renames
- Migration tool is interactive (prompts user) rather than fully automatic
- Frontmatter system is simplified or removed (since content is split across files)
