requirements.md•17.4 kB
# Feature: Project Creation
**Status:** In Development
## 1. Business Context
The execution system manages projects across multiple horizons of focus (10k-projects level). Currently, project creation requires manual file creation with YAML frontmatter, markdown structure following the Natural Planning Model, kebab-case filename generation, and validation of area/folder placement. This manual process is error-prone and time-consuming.
To streamline project creation and ensure consistency, the MCP server will provide a `create_project` tool that handles all aspects of project initialization. This enables Claude to create properly formatted projects with validated metadata, appropriate templates based on project type, and automatic placement in the correct folder structure. The MCP server is configurable to work with any execution system repository that follows this structure.
The system follows the Natural Planning Model with these core sections:
1. **Purpose & Principles** - Why this matters and what standards apply
2. **Vision/Outcome** - What success looks like
3. **Notes/Ideas** - Supporting information and brainstorming
Three project types require templates:
- **standard**: General projects (most common)
- **coordination**: Projects that link or coordinate other projects
- **habit**: Ongoing habit tracking projects
## 2. Requirements (EARS Notation)
| ID | Requirement |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Core Functionality** | |
| FR-1 | **THE SYSTEM SHALL** provide a `create_project` MCP tool that creates project files in the configured execution system repository. |
| FR-2 | **WHEN** a user invokes `create_project` with required parameters,<br/>**THE SYSTEM SHALL** generate a project markdown file with YAML frontmatter and structured markdown body. |
| FR-3 | **THE** `create_project` tool SHALL require the following parameters: `title` (string), `area` (string), `type` (enum: standard, coordination, habit), and `folder` (enum: active, incubator). |
| FR-4 | **THE** `create_project` tool SHALL accept the following optional parameters: `due` (ISO date string YYYY-MM-DD). |
| **YAML Frontmatter Generation** | |
| FR-5 | **THE SYSTEM SHALL** generate YAML frontmatter with the following fields: `area`, `title`, `type`, `created`, `last_reviewed`. |
| FR-6 | **THE** `created` field SHALL be automatically set to today's date in ISO format (YYYY-MM-DD). |
| FR-7 | **THE** `last_reviewed` field SHALL be automatically set to today's date in ISO format (YYYY-MM-DD). |
| FR-8 | **WHEN** the `folder` parameter is "active",<br/>**THE SYSTEM SHALL** include a `started` field in the YAML frontmatter set to today's date. |
| FR-9 | **WHEN** the `folder` parameter is "incubator",<br/>**THE SYSTEM SHALL NOT** include a `started` field in the YAML frontmatter. |
| FR-10 | **WHEN** the user provides a `due` parameter,<br/>**THE SYSTEM SHALL** include a `due` field in the YAML frontmatter with the provided date. |
| FR-11 | **WHEN** the user does not provide a `due` parameter,<br/>**THE SYSTEM SHALL NOT** include a `due` field in the YAML frontmatter. |
| **File Naming and Placement** | |
| FR-12 | **THE SYSTEM SHALL** generate the filename by converting the `title` to kebab-case (lowercase, hyphens for spaces, alphanumeric only). |
| FR-13 | **THE SYSTEM SHALL** place projects in the folder structure: `docs/execution_system/10k-projects/{folder}/{area_kebab}/{filename}.md` where `{folder}` is active/incubator/completed/descoped, `{area_kebab}` is the kebab-case version of the area, and `{filename}` is the kebab-case title. |
| FR-14 | **WHEN** the folder structure `docs/execution_system/10k-projects/{folder}/{area_kebab}/` does not exist,<br/>**THE SYSTEM SHALL** create the necessary area subdirectory under the specified folder. |
| **Area Validation** | |
| FR-15 | **THE SYSTEM SHALL** validate that the `area` parameter matches one of the configured areas of focus defined in the configuration file. |
| FR-16 | **WHEN** the `area` parameter does not match a configured area (case-insensitive),<br/>**THE SYSTEM SHALL** return an error with the list of valid areas from the configuration. |
| **Duplicate Detection** | |
| FR-17 | **THE SYSTEM SHALL** check for duplicate project titles (exact filename match) across all folders: active, incubator, completed, and descoped. |
| FR-18 | **WHEN** a project with the same filename already exists in any folder,<br/>**THE SYSTEM SHALL** return an error indicating which folder contains the duplicate. |
| **Template Generation** | |
| FR-19 | **THE SYSTEM SHALL** generate markdown body content based on the `type` parameter using predefined templates. |
| FR-20 | **WHEN** `type` is "standard",<br/>**THE SYSTEM SHALL** generate a template with sections: "1. PURPOSE - Why This Matters", "2. VISION/OUTCOME - What Success Looks Like", "Ideas Parking Lot". |
| FR-21 | **WHEN** `type` is "habit",<br/>**THE SYSTEM SHALL** generate a template with sections: "1. PURPOSE - Why This Matters", "2. VISION/OUTCOME - What Success Looks Like", "3. APPROACH", "Next Actions". |
| FR-22 | **WHEN** `type` is "coordination",<br/>**THE SYSTEM SHALL** generate a template with sections: "1. PURPOSE - Why This Matters", "2. PRINCIPLES - Standards & Values", "3. VISION/OUTCOME - What Success Looks Like", "Supporting Resources", "Ideas to Consider". |
| **Return Value** | |
| FR-23 | **WHEN** project creation succeeds,<br/>**THE SYSTEM SHALL** return a success message containing the full file path, area, folder, and filename. |
| FR-24 | **WHEN** project creation fails due to validation errors or file system errors,<br/>**THE SYSTEM SHALL** return a descriptive error message. |
## 3. Acceptance Criteria
| Requirement ID | Acceptance Criteria |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FR-1, FR-2, FR-3 | - Given valid parameters (`title="Test Project"`, `area="Career"`, `type="standard"`, `folder="active"`), the tool creates a file at the expected path with YAML frontmatter and markdown body. |
| FR-4, FR-10, FR-11 | - Given `due="2025-12-31"`, the YAML includes `due: 2025-12-31`.<br/>- Given no `due` parameter, the YAML does not include a `due` field. |
| FR-5, FR-6, FR-7 | - The YAML frontmatter contains `area`, `title`, `type`, `created`, `last_reviewed` with correct values.<br/>- `created` and `last_reviewed` are set to today's date in YYYY-MM-DD format. |
| FR-8, FR-9 | - Given `folder="active"`, YAML includes `started: <today's date>`.<br/>- Given `folder="incubator"`, YAML does not include `started` field. |
| FR-12 | - Given `title="My Test Project!"`, filename is `my-test-project.md`.<br/>- Given `title="Order Pokémon Cards"`, filename is `order-pokemon-cards.md`. |
| FR-13, FR-14 | - Project is created in correct folder path with area subdirectory (e.g., `active/health/myproject.md`).<br/>- Missing area subdirectories are created automatically. |
| FR-15, FR-16 | - Given `area="Career"` (valid), validation passes.<br/>- Given `area="Invalid"`, returns error with list of valid areas. |
| FR-17, FR-18 | - Given a project with filename `test-project.md` already exists in `completed/`, attempting to create another project with title "Test Project" returns an error indicating the duplicate in `completed/`. |
| FR-20, FR-21, FR-22 | - Standard template includes: "1. PURPOSE - Why This Matters", "2. VISION/OUTCOME - What Success Looks Like", "Ideas Parking Lot".<br/>- Habit template includes: "1. PURPOSE - Why This Matters", "2. VISION/OUTCOME - What Success Looks Like", "3. APPROACH", "Next Actions".<br/>- Coordination template includes: "1. PURPOSE - Why This Matters", "2. PRINCIPLES - Standards & Values", "3. VISION/OUTCOME - What Success Looks Like", "Supporting Resources", "Ideas to Consider". |
| FR-23, FR-24 | - Success message includes full file path, area, and folder.<br/>- Error messages clearly indicate the validation failure or file system error. |