---
name: markdown-tags
description: Add YAML frontmatter to feature documents for standardized metadata
status: done
parts:
  - src/types/feature.rs
  - src/servers/feature.rs
estimate:
  optimistic: 4 hours
  normal: 6 hours
  pessimistic: 10 hours
---

# Feature: markdown-tags

## Description

Add YAML frontmatter to all feature documents to standardize metadata and enable automated parsing. The frontmatter provides a consistent way to track feature status, affected components, and estimates.

## Requirements

### Frontmatter Format

Each feature document must have YAML frontmatter at the top using standard `---` delimiters:

```yaml
---
name: feature-name
description: Short description of the feature
status: draft|analyzing|awaiting_answers|ready|implementing|reviewing|done
parts:
  - component1
  - component2
estimate:
  optimistic: Xh
  normal: Yh
  pessimistic: Zh
---
```

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| name | string | Feature identifier (matches filename) |
| description | string | Brief one-line description |
| status | enum | Current feature status |
| parts | list | Affected project components/modules |
| estimate | object | Three-point time estimate for senior dev |

### Automatic Population

K4000 should automatically populate frontmatter fields from existing state:
- `name`: From feature name
- `status`: From feature status in state.json
- `description`: From feature description
- `estimate`: From estimate section if present

### Timing

1. **Add frontmatter**: After analysis is complete and all questions are answered (when status becomes `ready`)
2. **Update frontmatter**: Whenever status changes or after review iterations

### Integration with list_project_features

The `list_project_features` tool should:
- Parse frontmatter from each feature document
- Display frontmatter fields in a compact form in the output
- Show: name, status, parts (abbreviated), estimate (normal time)

### Existing Features

For features that already have content:
- Insert frontmatter at the very top of the document
- Preserve all existing content below the frontmatter

### Validation

K4000 should validate frontmatter and warn if:
- Required fields are missing
- Field values are malformed
- Status doesn't match one of the valid enum values
- Estimate format is incorrect

## Implementation Plan

1. **Add YAML parsing dependency** - Add `serde_yaml` crate for frontmatter parsing
2. **Create frontmatter types** - Define structs for frontmatter fields in `types/feature.rs`
3. **Implement frontmatter parser** - Parse frontmatter from markdown documents
4. **Implement frontmatter generator** - Generate frontmatter from feature state
5. **Update document functions** - Modify `update_feature_document` to manage frontmatter
6. **Update list_project_features** - Parse and display frontmatter fields
7. **Add validation** - Validate frontmatter on read/write operations
8. **Update existing features** - Add frontmatter to existing feature documents

## Testing Considerations

- Test frontmatter parsing with valid/invalid YAML
- Test frontmatter generation from feature state
- Test insertion into existing documents
- Test validation warnings for missing/malformed fields
- Test list_project_features output with frontmatter data

---

## Q & A

### Q1: Should the frontmatter use YAML syntax (with `---` delimiters) or a custom format?
**Category:** requirements
**Answer:** Use --- as delimiter both before and after (standard YAML frontmatter syntax)

### Q2: For the 'parts' field, should this be a list/array or comma-separated string?
**Category:** requirements
**Answer:** Use a list/array format for multiple parts

### Q3: Should K4000 automatically populate frontmatter fields from existing state?
**Category:** requirements
**Answer:** Yes, K4000 should automatically populate frontmatter fields from existing state

### Q4: When should the frontmatter be added?
**Category:** workflow
**Answer:** After analysis is complete, and update if anything changes afterwards

### Q5: Should list_project_features parse and display frontmatter fields?
**Category:** integration
**Answer:** Yes, list_project_features should parse and display frontmatter fields but in a compact form

### Q6: For existing features with content, how should frontmatter be added?
**Category:** edge_cases
**Answer:** Yes, insert frontmatter above existing content for existing features

### Q7: Should K4000 validate frontmatter format?
**Category:** requirements
**Answer:** Yes, K4000 should validate frontmatter format and warn if required fields are missing or malformed

---

## Estimate

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

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

### Assumptions
- Familiar with serde and YAML parsing in Rust
- Existing test infrastructure can be extended
- No breaking changes to existing MCP tool interfaces
- Excludes code review iterations
