Planning Agent Plugin

A portable Agent Plugins 1.0 capability for planning and backlog management across GitHub and Jira without introducing a third project-management database.

The plugin packages:

plugins/planning/
├── plugin.json
├── mcp.json
├── distribution.config.json
├── docs/
│   ├── atlassian-v2-boundary.md
│   ├── compatibility.md
│   └── runtime-evidence.md
├── evidence/
│   └── TEMPLATE.json
└── skills/
    ├── planning/
    │   ├── SKILL.md
    │   └── references/provider-contract.md
    └── backlog-management/
        ├── SKILL.md
        └── references/operations.md

Why this exists

Existing tools already solve the provider access problem:

• GitHub provides its official remote MCP server;
• Atlassian provides the official Rovo MCP server for Jira/Confluence;
• project-management tools such as Agents Board and AgentPM demonstrate that planning behavior + MCP tooling can form a coherent agent capability.

This plugin deliberately does not build another board, database, GitHub wrapper, or Jira wrapper. Its differentiating layer is provider-neutral planning/orchestration while GitHub/Jira remain the systems of record.

Skills

planning

Turns a new initiative/feature/migration into a dependency-aware work graph, chooses an authoritative provider per work item, and optionally persists the authorized plan.

backlog-management

Reads, triages, links, prioritizes, and updates existing GitHub/Jira backlog state without taking over code implementation.

The split is intentional: planning new work and operating an existing backlog have different activation boundaries. Repository implementation/PR/release work should be handed to delivery capabilities such as github-repo-autopilot rather than duplicated here.

MCP composition

mcp.json composes existing official servers:

No credentials are committed. distribution.config.json records endpoint provenance/purpose/review metadata; generated mcp.json contains only the portable Agent Plugins shape.

Rovo MCP v2 exposes a smaller primary tool surface and reaches some provider operations through its discover / execute convention. That is a provider-specific detail, not a reason to copy Atlassian's own Agent Skills into this plugin. Atlassian now maintains provider-native skills such as spec-to-backlog, triage-issue, and jira-sprint-dashboard in atlassian/atlassian-mcp-server; our planning and backlog-management skills remain cross-provider orchestration. See docs/atlassian-v2-boundary.md.

Install with GitHub Copilot CLI

Use the repository marketplace rather than a direct repo/path install. Copilot CLI 1.0.83 warns that direct plugin installs are deprecated and that future releases will support marketplace installs only.

copilot plugin marketplace add svg153/skills
copilot plugin marketplace browse svg153-skills
copilot plugin install planning@svg153-skills

For local development, register the checked-out repository itself as the marketplace:

copilot plugin marketplace add .
copilot plugin install planning@svg153-skills
copilot plugin list
copilot mcp list --json

The root marketplace.json is generated from repository/package state and publishes plugins/planning as the planning entry. This keeps the install path compatible with Copilot's marketplace-first direction while retaining the plugin as a monorepo subdirectory.

Install with OpenAI Codex CLI

Codex CLI 0.153.4 is verified in CI against the same portable Agent Plugin package; plugins/planning does not need a Codex-specific runtime manifest.

From a checkout:

codex plugin marketplace add .
codex plugin list --available --json
codex plugin add planning@svg153-skills --json
codex plugin list --json
codex mcp list --json

Codex loads the root Agent Plugins plugin.json, the shared skills/ tree, and the same portable mcp.json. CI verifies both github and atlassian MCP entries are discovered with streamable_http transport.

Authentication is completed through each client/provider flow. Installing the plugin does not grant GitHub or Atlassian access by itself.

See docs/compatibility.md for the client/version/evidence matrix.

Degraded operation

The skills are independent from either MCP server:

A provider failure must not silently move its records into the remaining provider or cause unrelated skills to disappear.

Mutation boundary

Read-only discovery/planning is preferred first. External mutations occur only when the user explicitly asked to create/update planning records.

Once the user has given that scoped instruction, the skills should execute it without adding redundant confirmation prompts for every ticket. Provider-returned identifiers are retained for subsequent links and relationships.

Source-of-truth rule

Do not create GitHub/Jira twins for the same mutable work item unless the user explicitly requires mirroring and a synchronization mechanism exists.

Recommended cross-provider pattern:

JIRA-123    program/customer/organizational record
   |
   +----> GH #456   repository implementation work
   +----> GH #457   another implementation slice

Cross-links are traceability, not implicit synchronization.

Generate and validate

The package manifests are derived from distribution.config.json and the local skills/ tree, while the repository marketplaces are derived from root catalog state plus discovered capability packages:

python scripts/generate-capability-plugin.py \
  --config plugins/planning/distribution.config.json \
  --check

python scripts/generate-distribution.py --check
python scripts/validate-planning-runtime-evidence.py

Repository CI validates skill frontmatter, MCP security/provenance policy, generated-manifest drift, cross-agent skill discovery, Copilot/Codex marketplace installation, MCP discovery, and the structure/security of any committed authenticated-runtime evidence.

Authenticated runtime evidence

Package and MCP discovery are already automated. Provider OAuth and real tool calls belong in a trusted interactive session rather than CI secrets.

Use docs/runtime-evidence.md for the Codex/Copilot OAuth, read, mutation, and cross-provider test procedure. Copy evidence/TEMPLATE.json, sanitize the results, and validate them before committing:

python scripts/validate-planning-runtime-evidence.py

The validator rejects common credential/token shapes and prevents stronger claims from being recorded without their prerequisites. A verified mutation, for example, requires verified provider authentication, explicit user intent, a provider-returned ID, and a sanitized result summary.

Status

This is an experimental pilot for svg153/skills#36.

• Agent Plugins/Agent Skills conformance: verified.
• npx skills discovery: verified.
• GitHub Copilot CLI 1.0.83 marketplace install/discovery: verified in CI.
• OpenAI Codex CLI 0.153.4 marketplace install/discovery: verified in CI.
• GitHub MCP discovery from plugin in Copilot and Codex: verified in CI.
• Atlassian Rovo MCP v2 discovery from plugin: being re-verified by svg153/skills#65; do not reuse the historical v1 evidence as a v2 runtime claim.
• GitHub MCP authenticated tool call: pending.
• Atlassian MCP v2 authenticated tool call: pending.
• end-to-end cross-provider mutation scenario: pending.

Do not treat MCP discovery evidence as proof that every client can authenticate to both remote MCP servers. Runtime evidence is recorded separately per client and version in docs/compatibility.md, with the stronger authenticated evidence procedure in docs/runtime-evidence.md.

References

• Agent Plugins 1.0: https://agent-plugins.org/specification
• GitHub Copilot CLI plugin reference: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
• GitHub Copilot CLI marketplaces: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace
• GitHub MCP Server: https://github.com/github/github-mcp-server
• GitHub MCP setup: https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/set-up-the-github-mcp-server
• Atlassian Rovo MCP repository: https://github.com/atlassian/atlassian-mcp-server
• Atlassian Rovo MCP v2: https://mcp.atlassian.com/v2/mcp
• Pilot issue: https://github.com/svg153/skills/issues/36