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

# Creating Spec-Tracking Issues via GitHub MCP

> 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…

**Purpose:** Use the GitHub MCP (`user-github`) to create all spec-tracking issues from [SPEC\_STATUS\_REGISTRY](../../specs/SPEC_STATUS_REGISTRY.md) in batches. Adding issues to the GitHub Project board is a separate step (see below).

**Related:** [GITHUB\_PROJECT\_SPEC\_TRACKING\_PLAN.md](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](../../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.

```bash theme={null}
# 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:

| Batch | Core(s) | Approx. count |
| ----- | ------- | ------------- |
| 1     | HR      | 21            |
| 2     | RH      | 8             |
| 3     | FA      | 13            |
| 4     | GR      | 10            |
| 5     | FW      | 27            |
| 6     | FM      | 6             |
| 7     | LO      | 5             |
| 8     | PF      | 53            |
| 9     | IT      | 3             |
| 10    | CL      | 30            |
| 11    | PM      | 19            |
| 12    | CE      | 3             |

### How to run (in chat)

1. **Provide owner and repo** (or ensure [scripts/github-spec-issues-config.json](../../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](../../.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:

```markdown theme={null}
## 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](GITHUB_PROJECT_SPEC_TRACKING_PLAN.md) for project setup and ongoing process.