# Mpx Add Requirements

> Primary requirements skill. Create or update .mpx/SPEC.md from user input, then always re-parse via mpx-spec-analyzer into ROADMAP.md + phase checklists. Use when: "add requirement", "create spec", "update spec"

- Skill: `martinopolo/mpx-add-requirements` (Agent Skill)
- Install (CLI): `npx skillmds@latest add martinopolo/mpx-add-requirements`
- Raw SKILL.md: https://api.skillmd.com/api/skills/martinopolo/mpx-add-requirements/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: MartinoPolo (https://skillmd.com/u/martinopolo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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:

```markdown
# 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