Append a timestamped note to a story file. Use to record progress, decisions made, or blockers encountered. Notes are appended under a '## Notes' section with an ISO 8601 timestamp. Returns {story_id, appended_at, path}.

Update the checked state of individual acceptance criteria on a story in one operation. Only the criteria explicitly listed are modified; all others are left untouched. Criteria are matched by exact text. If any criterion text is not found, no changes are made and an error is returned. Returns {story_id, path, content, criteria_updated, errors}.

Update multiple epics in one operation. Each entry may set status and/or append a note. Updates are applied atomically per file. If an epic does not exist, an error is recorded for that entry and processing continues. Returns an array of per-epic result objects with fields: epic_id, status_updated, old_status, new_status, note_appended, errors.

Update multiple stories in one operation. Each entry may set status, append a note, and/or patch acceptance criteria. Updates are applied atomically per file. If a story does not exist, an error is recorded for that entry and processing continues. Returns an array of per-story result objects with fields: story_id, status_updated, old_status, new_status, note_appended, criteria_updated, criteria_errors, errors.

Mark a single acceptance criterion as checked (- [ ] → - [x]) in a story file. Identify the target by criterion_index (0-based) or criterion_text (case-insensitive exact match). Exactly one must be provided. Returns {story_id, criterion, checked, path}. Errors if the story is not found, the criterion is not found, or it is already checked.

Mark a story done and append a mandatory completion summary note in one atomic call. Validates acceptance criteria before completing: if the AC section has not been set (contains only the placeholder), completion is blocked — call set_acceptance_criteria first. IMPORTANT: if a criterion is actually done, mark it [x] in the story file via set_acceptance_criteria BEFORE calling this tool — do not leave it unchecked. If criteria remain unchecked (genuinely not done), incomplete_items is required with one explanation per unchecked item explaining WHY it was not completed (e.g. deferred, out of scope). incomplete_items is for unfinished work only — never use it to confirm completed work. On success, removes the story from backlog.md and returns {story_id, completed_at, backlog_removed}.

Create a new epic. Assigns the next EPIC-NNN ID, creates the epic directory and epic.md file, and registers it in requirements-index.md with status draft. Returns {epic_id, path}.

Create a new story under an existing epic. Assigns the next STORY-NNN ID, writes the story file, and registers it in requirements-index.md and backlog.md with status draft. The story is appended to the end of the backlog. Returns {story_id, path}.

Get a high-level summary of all epics and their story counts broken down by status. Useful for situational awareness at the start of a session, without reading every file. Returns an array of {epic_id, title, status, counts: {status: n}, stories: [{story_id, status}]}.

Get the full markdown content and metadata for a single story. Returns {story_id, title, status, epic_id, path, content} where content is the raw markdown of the story file.

Reconcile the ## Stories section in an epic.md file with the story files on disk and the requirements index. Adds missing entries, removes entries for story files that no longer exist, and refreshes titles and done/undone markers. Returns {epic_id, added, removed, updated, unchanged}.

List stories from the project index, optionally filtered by epic, status, or type. Returns an array of {story_id, title, status, epic_id, story_type} objects. With no filters, returns all stories across all epics. Other tools in this server: get_story, get_index_summary, create_epic, create_story, set_story_status, set_epic_status, add_story_note, set_acceptance_criteria, check_acceptance_criterion, complete_story, bulk_update_stories, bulk_update_epics, bulk_update_acceptance_criteria, groom_epic, reorder_backlog.

Reorder the active backlog by supplying the desired story ID sequence. Entries present in story_ids are placed first in that order; any backlog entries omitted from the list are appended at the end so nothing is silently dropped. IDs not found in the backlog (e.g. already done) are reported in not_found but do not cause a failure. Returns {placed: [ordered story IDs written], not_found: [IDs absent from backlog], appended: [IDs moved to end because they were omitted]}.

Replace the acceptance criteria section of a story file. Each string in the criteria array becomes a - [ ] ... checklist line. Idempotent: calling again replaces the previous AC entirely. Acceptance criteria must be set before a story can be completed with complete_story. Returns {story_id, criteria_count, path}.

Update the lifecycle status of an epic. Use this tool to manage the epic's own status — not the status of individual stories within it (use set_story_status for that). Typical progression: draft → in-progress (when the first story starts) → done (when all stories are complete) or deferred (if the epic is postponed). Status meanings: 'draft' = epic created but no work started; 'in-progress' = actively being worked on; 'done' = all stories complete and the epic is closed; 'blocked' = progress prevented by an external dependency; 'deferred' = postponed indefinitely. Guards: (1) Setting 'done' requires a summary and checks all stories are done. If any are not done, the call fails — set override_incomplete=true only after the user explicitly confirms this is acceptable. (2) Moving backwards (e.g. done → in-progress, in-progress → draft) asks you to create new stories to justify the regression first. Set confirm_regression=true only if the user explicitly insists on skipping story creation. Returns {epic_id, old_status, new_status}.

Update the status of a story to draft, in-progress, blocked, or deferred. To mark a story done, use complete_story instead — it enforces acceptance criteria, appends a summary note, and removes the story from the backlog. Returns {story_id, old_status, new_status, backlog_updated}.