cage-issues

File-based, topic-organized issue tracking for CAGE-enabled projects, exposed as an MCP server. AI agents interact with it through MCP tools; all state is stored as YAML files under a topics/ directory in any git repository.

Invocation

cage-issues-mcp --root <path>

--root is the path to the directory containing topics/. Defaults to the current working directory if omitted.

Environment variables

| Variable | Values | Default | Description | |---|---|---|---| | CAGE_SINGLE_TOPIC | true / false | false | When true, rejects a second create_topic call — enforces one topic per store | | CAGE_MERGE_POLICY | auto / manual | auto | auto merges and deletes the transaction branch on close_transaction; manual leaves the branch open for human review |

Directory layout

topics/
  <topic-id>/
    topic.yaml
    backlog.yaml
    issues/
      <issue-id>.yaml
config.yaml

MCP tools

Issues

| Tool | Description | |---|---| | create_issue | Create a new issue. Checks for duplicates automatically. | | get_issue | Get a single issue by ID, including derived maturity and track. | | update_issue | Partially update an issue. Status changes append to status_history. Task updates merge by task id. | | list_issues | List issues with optional filters (topic, status, priority, maturity, track, date range). | | search_issues | Free-text search across issue titles and descriptions, ranked by relevance. | | find_duplicates | Check for existing issues similar to a proposed new one. | | validate_issue | Record a validation signoff. On pass, appends to signoffs. On fail, no trace is recorded. |

Topics

| Tool | Description | |---|---| | create_topic | Create a new topic. | | list_topics | List all topics. | | close_topic | Close a topic (no new issues can be filed against it). |

Backlog

| Tool | Description | |---|---| | get_backlog | Get the backlog for a topic. | | update_backlog | Replace the backlog for a topic. | | add_to_backlog | Add an entry to the backlog for a topic. |

Tracks

| Tool | Description | |---|---| | create_track | Create a new track. | | list_tracks | List all tracks. | | update_track | Update a track. | | close_track | Close a track. |

Transactions

| Tool | Description | |---|---| | begin_transaction | Open a transaction on a topic. Creates a git branch as the lock. | | update_task_intent | Revise the commit type and description before committing. | | commit_task | Mint real issue IDs for any tmp- issues and produce a conventional commit. | | close_transaction | Merge or leave the transaction branch per CAGE_MERGE_POLICY. |

When to use transactions vs. direct calls

Use transactions (begin_transaction, commit_task, close_transaction) in standalone issue-management sessions where cage-issues fully owns the git context — no other process is using the same working tree.

Use direct calls (update_issue, update_backlog, create_issue, etc.) in feature-branch workflows where the calling agent owns the commit. These tools write YAML only — no git operations — and are safe to call at any point during implementation work without disturbing the working tree.

Note: The transaction model will be updated in a future release to use an isolated git worktree so it is safe in all contexts. Until then, prefer direct calls in feature-branch workflows.

Extension fields

Issue YAML files may contain top-level fields not defined in the Issue interface. These fields are preserved transparently through all read/write operations — they appear after the canonical fields in the serialized output and are never silently dropped.

Ecosystem

| Package | Description | |---|---| | @dleangen/cage-core | Protocol layer | | @dleangen/cage-cli | CLI tooling | | @dleangen/cage-issues | Issue tracking ← you are here |

License

MIT