From 0170eb7fef9d288d5dc9198def9743ea394e4d4c Mon Sep 17 00:00:00 2001 From: Bill Ballou Date: Tue, 6 Jan 2026 19:58:42 -0500 Subject: [PATCH] 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 --- .../checklists/requirements.md | 42 +++++ specs/001-schedule-tools/spec.md | 145 ++++++++++++++++++ 2 files changed, 187 insertions(+) create mode 100644 specs/001-schedule-tools/checklists/requirements.md create mode 100644 specs/001-schedule-tools/spec.md diff --git a/specs/001-schedule-tools/checklists/requirements.md b/specs/001-schedule-tools/checklists/requirements.md new file mode 100644 index 0000000..1f02217 --- /dev/null +++ b/specs/001-schedule-tools/checklists/requirements.md @@ -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 diff --git a/specs/001-schedule-tools/spec.md b/specs/001-schedule-tools/spec.md new file mode 100644 index 0000000..6d0bed6 --- /dev/null +++ b/specs/001-schedule-tools/spec.md @@ -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)