Skip to main content
Purpose: Use the GitHub MCP (user-github) to create all spec-tracking issues from SPEC_STATUS_REGISTRY in batches. Adding issues to the GitHub Project board is a separate step (see below). Related: GITHUB_PROJECT_SPEC_TRACKING_PLAN.md.

​
Prerequisites

  1. Owner and repo: The MCP requires owner and repo for every call. Set them in scripts/github-spec-issues-config.json (replace YOUR_GITHUB_OWNER_OR_ORG with your org or username) or pass them when asking the agent to create issues.
  2. Labels in the repo: These labels must exist in the repository or issue creation will fail: spec-tracking, core:PF, core:HR, core:FA, core:FW, core:CL, core:PM, core:CE, core:RH, core:GR, core:FM, core:LO, core:IT. Create them under Settings → Labels if needed.
  3. GitHub MCP: Authenticated and available as user-github (e.g. get_me works in Cursor).

​
Generate the spec list

The payload script parses the registry and outputs a JSON array of { specId, name, core } for the agent to consume.

​
Create issues via MCP in batches

The GitHub MCP does not support Projects (create project or add item to project). It can only create and list issues. Use it to create issues; then add them to the project via gh or the GitHub UI.

​
Sync mode (skip existing)

Before creating, the agent can call list_issues with owner, repo, labels: ["spec-tracking"], and paginate to build a set of existing issue titles. Any spec whose title [SPEC-ID] Name already exists is skipped.

​
Batch boundaries (by core)

Process in batches to avoid turn limits. Order matches the registry. Approximate counts:

​
How to run (in chat)

  1. Provide owner and repo (or ensure scripts/github-spec-issues-config.json has the correct values and the agent reads it).
  2. Optional sync: Ask the agent to list existing issues with label spec-tracking and skip any title that already exists.
  3. Create by batch: e.g. “Use GitHub MCP to create spec-tracking issues for owner X repo Y. Sync first. Create batch 1 (HR only).” The agent will run spec-issues:list --core HR (or read the full list and filter), then call issue_write for each item with:
    • method: "create"
    • owner, repo
    • title: [specId] Name (truncate name to ~80 chars if needed)
    • body: Spec source, Registry link, Summary, Next Action, Status checkboxes (align with .github/ISSUE_TEMPLATE/spec-tracking.yml and the bootstrap script body below)
    • labels: ["spec-tracking", "core:XX"]
  4. Next batch: e.g. “Continue with batch 2 (RH).”

​
Issue body template

Use the same body as the bootstrap script and the issue template:

​
After issues are created

Adding issues to the Encore Spec Progress GitHub Project and setting Status (Backlog / In progress / Done) cannot be done via the GitHub MCP. Use one of:
  • gh CLI: Run the bootstrap script with GH_PROJECT_NUMBER and owner configured; new issues are created and added to the project in the same run. For issues that already exist (bootstrap --sync skips them), run npm run spec:add-tracking-to-project (scripts/add-spec-tracking-issues-to-github-project.ts) to backfill gh project item-add for labeled spec-tracking issues.
  • Manual: In the GitHub Project board, add each issue and set its Status from the registry.
See GITHUB_PROJECT_SPEC_TRACKING_PLAN.md for project setup and ongoing process.