Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

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. 
# All specs (stdout)
npm run spec-issues:list

# Count only
npm run spec-issues:list -- --dry-run

# One core only
npm run spec-issues:list -- --core HR

# Write to file (for large batches)
npm run spec-issues:list -- --output scripts/.spec-issues-list.json

​
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:
BatchCore(s)Approx. count
1HR21
2RH8
3FA13
4GR10
5FW27
6FM6
7LO5
8PF53
9IT3
10CL30
11PM19
12CE3

​
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: 
## Spec
**Source:** `specs/{core}/specs/{specId}-*.md`
**Registry:** See [SPEC_STATUS_REGISTRY](../../specs/SPEC_STATUS_REGISTRY.md)

## Summary
{name}

## Next Action
(Run `whats-next --spec {specId}` when known)

## Status
- [ ] Backlog
- [ ] Spec in progress
- [ ] Ready for impl
- [ ] In progress
- [ ] In review
- [ ] Done

​
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.