project-issues

Project Issues

Use the host-local project registry to select the correct issue workspace, account, and project for the current Git repository. Treat the configured context as authoritative for external issue writes.

Resolve Context First

1. Call resolve_project_context once when issue work begins.
2. Resolve again when the working repository changes or when configuration is edited.
3. State the selected provider, target, and authenticated identity before preparing a write.
4. Stop before a write if the repository, provider, credential, or identity is not configured or does not match.

Use project-context resolve --cwd <path> only when the project_issues MCP tools are unavailable.

Route Deterministically

Provider selection follows this order:

1. An explicit issue URL.
2. A qualified reference such as linear:ENG-123, github:#318, or jira:OPS-42.
3. One unique configured identifier pattern.
4. The configured default provider.

Never infer a provider from issue wording. Never retry a failed provider operation against another provider. List and search only the default provider unless the user explicitly names a provider or requests all configured providers.

Read Issues

• Use list_issues for canonical status filters and direct subissue listing, search_issues only for title/description text, and get_issue for a single issue. Request relation expansion only when parent, subissue, blocking, related, or duplicate information is needed.
• Use list_issue_comments when the user needs the discussion on one issue. Results are newest first and target-scoped; truncated: true means older comments were omitted. This tool does not return field history or a full activity timeline.
• Use get_issue_capabilities before creating an issue or whenever valid labels, priorities, issue types, canonical statuses, defaults, or presets are unknown. Pass returned option values unchanged.
• Use search_issue_options when a label, priority, issue type, cycle, or milestone capability points to it, when its inline catalog is truncated, or when a large catalog needs narrowing. Pass the returned value unchanged.
• Treat capability operations as authoritative. An empty option list does not mean arbitrary values are valid; check acceptsCustomValues, defaultValue, and discoveryTool.
• Treat optionsTruncated: true as incomplete. Do not claim an unlisted value is invalid solely because it is absent from a truncated catalog.
• Treat option-search truncated: true the same way: narrow the query rather than guessing or rejecting an absent value.
• Never select a creation preset silently. Present relevant named presets and let the user choose.
• Never simulate status filtering by searching for text such as "in progress".
• Treat truncated: true as incomplete. Surface missing or ambiguous mapping errors instead of weakening the requested filter.
• For an unconfigured repository, explain that host-local context is missing. Conversational or explicitly supplied context may support a read, but do not treat it as write authorization.
• GitHub pull requests are outside this skill even though the GitHub Issues API can return them.