docs: add project schedule tools feature specification
Feature spec for MCP tools to query XER schedule data: - 4 user stories (load file, query activities, relationships, summary) - 14 functional requirements including pagination (100 item default) - Clarifications: P6 critical flags, multi-project selection, internal calendars
This commit is contained in:
42
specs/001-schedule-tools/checklists/requirements.md
Normal file
42
specs/001-schedule-tools/checklists/requirements.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Specification Quality Checklist: Project Schedule Tools
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-01-06
|
||||
**Feature**: [spec.md](../spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- Specification passed all validation checks
|
||||
- Clarification session completed 2026-01-06 (4 questions resolved)
|
||||
- Ready for `/speckit.plan`
|
||||
- 4 user stories defined (2 P1, 1 P2, 1 P3)
|
||||
- 14 functional requirements specified (added FR-013, FR-014 for pagination)
|
||||
- 7 measurable success criteria defined
|
||||
- 5 edge cases documented
|
||||
- Pagination limits (100 default) added to User Stories 2 and 3
|
||||
- Multi-project handling clarified in User Story 1
|
||||
145
specs/001-schedule-tools/spec.md
Normal file
145
specs/001-schedule-tools/spec.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Feature Specification: Project Schedule Tools
|
||||
|
||||
**Feature Branch**: `001-schedule-tools`
|
||||
**Created**: 2026-01-06
|
||||
**Status**: Draft
|
||||
**Input**: User description: "MCP tools to query activities, relationships, and schedules from XER data"
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### User Story 1 - Load XER File (Priority: P1)
|
||||
|
||||
As an AI assistant user, I want to load an XER file into the MCP server so that I can query its schedule data.
|
||||
|
||||
**Why this priority**: This is a prerequisite for all other functionality - no queries are possible without first loading data.
|
||||
|
||||
**Independent Test**: Can be tested by providing a file path and verifying the file is successfully parsed and available for queries.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a valid XER file path with a single project, **When** I request to load the file, **Then** the file is parsed, the project is auto-selected, and a success confirmation is returned with basic file info (project name, activity count)
|
||||
2. **Given** a valid XER file path with multiple projects, **When** I request to load the file without specifying a project, **Then** I receive a list of available projects and a prompt to select one
|
||||
3. **Given** a valid XER file path with multiple projects, **When** I request to load the file with a specific project ID, **Then** that project is selected and loaded
|
||||
4. **Given** an invalid file path, **When** I request to load the file, **Then** I receive a clear error message indicating the file was not found
|
||||
5. **Given** a corrupted or invalid XER file, **When** I request to load the file, **Then** I receive a clear error message describing the parsing failure
|
||||
6. **Given** a file is already loaded, **When** I load a new file, **Then** the previous data is replaced with the new file's data
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - Query Project Activities (Priority: P1)
|
||||
|
||||
As an AI assistant user, I want to query activities from a loaded XER file so that I can understand what work is planned in the project schedule.
|
||||
|
||||
**Why this priority**: Activities are the fundamental building blocks of any P6 schedule. Without the ability to query activities, no other schedule analysis is possible.
|
||||
|
||||
**Independent Test**: Can be fully tested by loading an XER file and querying for activities. Delivers immediate value by exposing schedule data to AI assistants.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an XER file is loaded, **When** I request all activities, **Then** I receive a list of activities with their names, IDs, and dates (limited to 100 by default)
|
||||
2. **Given** an XER file is loaded, **When** I request activities filtered by date range, **Then** I receive only activities that fall within that range (limited to 100 by default)
|
||||
3. **Given** an XER file is loaded, **When** I request a specific activity by ID, **Then** I receive the complete details for that activity
|
||||
4. **Given** no XER file is loaded, **When** I request activities, **Then** I receive a clear error message indicating no file is loaded
|
||||
5. **Given** an XER file with more than 100 activities, **When** I request activities without specifying a limit, **Then** I receive the first 100 activities plus pagination metadata (total count, has_more flag)
|
||||
6. **Given** an XER file is loaded, **When** I request activities with offset and limit parameters, **Then** I receive the specified page of results
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - Query Activity Relationships (Priority: P2)
|
||||
|
||||
As an AI assistant user, I want to query the relationships (dependencies) between activities so that I can understand the logical sequence of work and identify critical paths.
|
||||
|
||||
**Why this priority**: Relationships define the logical flow of work and are essential for schedule analysis, but require activities to be queryable first.
|
||||
|
||||
**Independent Test**: Can be tested by loading an XER file and querying predecessor/successor relationships for any activity.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an XER file is loaded, **When** I request predecessors for an activity, **Then** I receive a list of predecessor activities with their relationship types (FS, SS, FF, SF) and lag values
|
||||
2. **Given** an XER file is loaded, **When** I request successors for an activity, **Then** I receive a list of successor activities with their relationship types and lag values
|
||||
3. **Given** an activity has no predecessors, **When** I request its predecessors, **Then** I receive an empty list (not an error)
|
||||
4. **Given** an XER file is loaded, **When** I request all relationships, **Then** I receive the dependency network (limited to 100 by default) with pagination metadata
|
||||
5. **Given** an XER file is loaded, **When** I request relationships with offset and limit parameters, **Then** I receive the specified page of results
|
||||
|
||||
---
|
||||
|
||||
### User Story 4 - Query Project Summary (Priority: P3)
|
||||
|
||||
As an AI assistant user, I want to get a high-level summary of the project schedule so that I can quickly understand project scope, timeline, and key milestones.
|
||||
|
||||
**Why this priority**: Provides valuable context for AI analysis but depends on activity and relationship data being accessible first.
|
||||
|
||||
**Independent Test**: Can be tested by loading an XER file and requesting project summary information.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an XER file is loaded, **When** I request the project summary, **Then** I receive project name, start date, finish date, and total activity count
|
||||
2. **Given** an XER file with milestones, **When** I request milestones, **Then** I receive a list of milestone activities with their target dates
|
||||
3. **Given** an XER file is loaded, **When** I request the critical path, **Then** I receive the sequence of activities that determine the project end date
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- What happens when an XER file contains no activities? Return empty results with a clear indication that the file has no schedule data.
|
||||
- What happens when activity IDs are duplicated in the XER file? Use the last occurrence and log a warning.
|
||||
- What happens when relationship references point to non-existent activities? Skip invalid relationships and include them in a warnings list.
|
||||
- What happens when date fields are missing or malformed? Use null values for missing dates and report parsing warnings.
|
||||
- What happens when the XER file uses an unsupported version format? Attempt best-effort parsing and report version compatibility warnings.
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: System MUST parse standard Primavera P6 XER file format and extract schedule data
|
||||
- **FR-002**: System MUST expose an MCP tool to load an XER file from a specified file path
|
||||
- **FR-003**: System MUST expose an MCP tool to list all activities with filtering options (by date range, by WBS, by activity type)
|
||||
- **FR-004**: System MUST expose an MCP tool to retrieve detailed information for a specific activity by ID
|
||||
- **FR-005**: System MUST expose an MCP tool to query predecessor and successor relationships for any activity
|
||||
- **FR-006**: System MUST expose an MCP tool to retrieve project summary information (name, dates, activity count)
|
||||
- **FR-007**: System MUST expose an MCP tool to list milestone activities
|
||||
- **FR-008**: System MUST expose an MCP tool to identify the critical path
|
||||
- **FR-009**: System MUST return structured data that AI assistants can process and present to users
|
||||
- **FR-010**: System MUST provide clear, actionable error messages when operations fail
|
||||
- **FR-011**: System MUST preserve all date/time precision from the original XER file
|
||||
- **FR-012**: System MUST handle XER files with multiple projects by requiring explicit project selection; single-project files auto-select the only project
|
||||
- **FR-013**: System MUST implement pagination for list queries with a default limit of 100 items, supporting offset and limit parameters
|
||||
- **FR-014**: System MUST return pagination metadata (total_count, has_more, offset, limit) with all paginated responses
|
||||
|
||||
### Key Entities
|
||||
|
||||
- **Project**: The top-level container representing a P6 project with name, ID, start/finish dates, and calendar assignments
|
||||
- **Activity**: A unit of work with ID, name, type (task/milestone/LOE), planned dates, actual dates, duration, and status
|
||||
- **Relationship**: A dependency link between two activities with type (FS/SS/FF/SF), lag value, and driving flag
|
||||
- **WBS (Work Breakdown Structure)**: Hierarchical organization of activities with ID, name, parent reference, and level
|
||||
- **Calendar**: Work schedule definition that determines working days and hours for activities (internal use only; not exposed as queryable entity)
|
||||
- **Resource**: Labor, equipment, or material assigned to activities (exposed for future resource analysis features)
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: Users can load and query an XER file within 5 seconds for files up to 10,000 activities
|
||||
- **SC-002**: Users can retrieve activity details in under 1 second after file is loaded
|
||||
- **SC-003**: All standard XER table types used in schedule analysis are correctly parsed (TASK, TASKPRED, PROJECT, PROJWBS, CALENDAR)
|
||||
- **SC-004**: 100% of valid relationship types (FS, SS, FF, SF) are correctly identified and queryable
|
||||
- **SC-005**: Users receive actionable error messages that identify the specific issue when operations fail
|
||||
- **SC-006**: Critical path identification uses P6's stored critical flags, ensuring exact match with P6's own critical path
|
||||
- **SC-007**: AI assistants can successfully integrate with the MCP server and execute all exposed tools
|
||||
|
||||
## Clarifications
|
||||
|
||||
### Session 2026-01-06
|
||||
|
||||
- Q: What should be the default result limit for activity/relationship queries? → A: 100 items default limit per query
|
||||
- Q: How should critical path be determined? → A: Use P6's stored critical flags from XER data
|
||||
- Q: How should multi-project XER files be handled? → A: Require explicit project selection if multiple exist
|
||||
- Q: Should calendar data be exposed as queryable? → A: Internal use only (not exposed as queryable)
|
||||
|
||||
## Assumptions
|
||||
|
||||
- XER files follow the standard Primavera P6 export format (tab-delimited with %T headers)
|
||||
- The MCP server runs locally and has file system access to read XER files
|
||||
- Users have valid XER files exported from P6 (versions 6.0 through current)
|
||||
- Single-user operation - no concurrent access handling required for MVP
|
||||
- Memory is sufficient to hold parsed schedule data for typical project sizes (up to 50,000 activities)
|
||||
Reference in New Issue
Block a user