MartinoPolo/mpx-add-requirements

Add Requirements

Primary entry point for specification authoring. Accept requirements, normalize them into precise checklist items in .mpx/SPEC.md, then always regenerate .mpx/ROADMAP.md and .mpx/phases/*/CHECKLIST.md via mpx-spec-analyzer.

Iron Law

DOCUMENTATION ONLY. This skill updates .mpx/ files only. It NEVER modifies source code, configs, tests, or any non-.mpx/ file.

Requirements Format

• One requirement = one checkbox line in SPEC.md
• Use clear, testable language with no ambiguity
• Preserve all user-provided details, constraints, and edge cases
• Prefer completeness over brevity when they conflict
• Mark already-built requirements as [x]; pending requirements as [ ]

Prerequisites

• .mpx/ directory should exist (create if missing)
• .mpx/SPEC.md may be missing (create if missing)

Workflow

Step 1: Gather Input

If requirements are provided as argument, use them. If no argument, ask:

"What requirements should be added to the specification? Include constraints, edge cases, and what counts as done."

Step 2: Clarify Ambiguity

If any requirement is ambiguous, conflicting, or missing acceptance details, ask targeted follow-ups with AskUserQuestion before writing:

• Clarify actor/scope/trigger
• Clarify expected behavior
• Clarify edge cases/failure modes
• Clarify done criteria

Step 3: Read Current State

Read:

• .mpx/SPEC.md (if exists)
• .mpx/ROADMAP.md (if exists)
• .mpx/phases/*/CHECKLIST.md (if exists)

Use existing content for deduplication and conflict detection only.

Step 4: Update SPEC.md (Source of Truth)

Create or update .mpx/SPEC.md in this format:

# Project Specification

## Requirements

- [ ] Requirement statement with complete behavior, constraints, and edge cases.
- [x] Requirement already implemented.

Rules:

• Only append new requirements or update incomplete ones.
• Do not delete or modify existing requirements without explicit instruction.
• Don't touch the completed [x] requirements
• Keep requirements as checkbox list items
• Preserve all requirement information from user input
• Normalize wording for precision without dropping details
• Avoid implementation instructions unless user explicitly gives them as constraints

Step 5: Parse into phase CHECKLISTs by Agent (Always)

Always spawn mpx-spec-analyzer after SPEC.md changes:

Use Task tool:
  subagent_type: "mpx-spec-analyzer"
  prompt: "Read .mpx/SPEC.md and update .mpx/ROADMAP.md and .mpx/phases/*/CHECKLIST.md. Treat unchecked requirements as planned work. Skip requirements marked [x] as already implemented unless they are needed as dependencies/context. If requirements are ambiguous, ask clarifying questions before finalizing output. Keep ROADMAP concise for completed phases."

Step 6: Single Summary Output

Return one unified summary:

Requirements Updated and Re-Parsed!

Requirements Added/Updated:
  - [requirement]

Clarifications Collected:
  - [question → answer] (if any)

Files Updated:
  - .mpx/SPEC.md
  - .mpx/ROADMAP.md
  - .mpx/phases/.../CHECKLIST.md

Skipped as Already Implemented:
  - [requirement] (if marked [x])

Next:
  - Run `/mp-execute mpx` to execute next task.

Error Handling

• Empty requirements: "Please specify requirements to add or update."
• Unclear requirements: ask clarifying questions before writing
• Analyzer run fails: keep SPEC.md changes, report analyzer error, suggest running /mpx-parse-spec

Notes

• This skill modifies project files - changes can be reviewed with git diff
• SPEC.md is the long-lived source of truth
• ROADMAP.md and phase checklists are derived artifacts regenerated by analyzer
• Completed requirement checkboxes ([x]) indicate implemented scope that analyzer should skip for new planning