backlog-mcp: Instructions file for Codex

Agent Instructions

Backlog (backlog-mcp)

Project stories and epics live in requirements/. Use the backlog-mcp MCP tools to interact with them — do not edit the index or backlog files by hand.

Tools

• list_stories — list stories, optionally filtered by epic_id or status
• get_story — read the full markdown content and metadata for a story
• set_story_status — update a story's status (draft, in-progress, done, blocked)
• add_story_note — append a timestamped note to a story file
• complete_story — mark a story done and append the completion summary note in one call
• get_index_summary — high-level epic/story counts by status
• bulk_update_acceptance_criteria — patch checked state of multiple AC items on one story in a single call
• bulk_update_stories — update status, notes, and/or criteria across multiple stories at once
• bulk_update_epics — update status and/or notes across multiple epics at once

Conventions

• Story IDs: STORY-NNN (e.g. STORY-047)
• Epic IDs: EPIC-NNN (e.g. EPIC-003)
• Always call set_story_status when you start work on a story (in-progress)
• Always call complete_story when you finish work on a story (do not use set_story_status + add_story_note separately)
• Use add_story_note to record decisions, blockers, or progress — never edit story files directly
• After create_story, immediately call set_acceptance_criteria with a concrete list of criteria before beginning implementation — a story with only the placeholder AC is not ready to implement
• Branch names must include the story ID (e.g. copilot/STORY-022-bulk-update-tools or chore/STORY-022-description). Never start implementation on a branch without a story — create the story first, then branch.

Testing (mandatory)

• Always write tests first. No production code is written before a failing test exists that demands it.
• Always write outside-in. Start from the outermost entry point (tool handler, HTTP handler, public API) and work inward. The first test must exercise the full slice of behaviour from the outside; only then add lower-level unit tests as needed to drive internal design.
• The test must fail for the right reason before any implementation is written. Verify the failure message makes sense.
• Only write enough production code to make the current failing test pass, then refactor before moving on.
• Do not write tests after the fact to cover code that already exists — if you find yourself doing this, stop, delete the code, and restart test-first.