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

# GitHub Project for Spec Progress Tracking — Implementation Plan

> Purpose: Set up a GitHub Project board to track specification implementation progress across all cores. Last Updated: 2026-03-08 Status: Plan (ready for execut…

**Purpose:** Set up a GitHub Project board to track specification implementation progress across all cores.\
**Last Updated:** 2026-03-08\
**Status:** Plan (ready for execution)

***

## Executive Summary

This plan defines how to create and maintain a **GitHub Project** board that mirrors the spec status from `specs/SPEC_STATUS_REGISTRY.md`, `specs/DEFERRED_DASHBOARD.md`, and per-core implementation logs. The project provides a **single visual board** for tracking what's in progress, what's next, and what's complete—using GitHub Projects only.

**Key principle:** Spec *content* and completion *audit* remain in the repo (spec files, IMPLEMENTATION\_LOG, spec-complete, SPEC\_STATUS\_REGISTRY). The GitHub Project is the **tracking and visibility** layer.

***

## 1. Current State Summary

### Specs Overview

| Source                     | Content                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| **SPEC\_STATUS\_REGISTRY** | \~198 specs across 12 cores; 113 complete, 1 in progress, 84 not started; 57% avg completion |
| **DEFERRED\_DASHBOARD**    | 37+ deferred items (PM), 11+ (CL), plus HR-13, PF summaries                                  |
| **ROADMAP**                | FA, RH, CE, FM, IT, Production Readiness priorities                                          |
| **Implementation Logs**    | Per-core `specs/{core}/IMPLEMENTATION_LOG.md`                                                |

### Cores and Spec Counts (from Registry)

| Core                      | Total  | Complete | In Progress | Not Started | Avg %    |
| ------------------------- | ------ | -------- | ----------- | ----------- | -------- |
| PF (Platform Foundation)  | 53     | 42       | 0           | 11          | 79%      |
| HR (Human Resources)      | 21     | 16       | 1           | 4           | 85%      |
| FA (Finance & Accounting) | 13     | 12       | 0           | 1           | 92%      |
| FW (Forms & Workflow)     | 27     | 19       | 0           | 8           | 85%      |
| CL (Clinical & EHR)       | 30     | 25       | 0           | 5           | 83%      |
| PM (Practice Management)  | 19     | 19       | 0           | 0           | 100%     |
| CE (Community Engagement) | 3      | 3        | 0           | 0           | 100%     |
| RH, GR, FM, LO, IT        | varies | 0        | 0           | varies      | 0–varies |

### Existing Tracking (Repo-Based)

* **Spec workflow:** `create-spec → clarify-spec → validate-spec → spec-reviewer → [plan] → generate-tasks → implement → spec-complete`
* **Commands:** `whats-next`, `spec-status`, `spec-complete`, `spec deferred`, `list-specs`
* **Registry update:** `spec-complete --all --completion-report --update-registry`
* **Deferred sync:** `spec deferred --sync` (regenerates DEFERRED\_DASHBOARD.md)

***

## 2. GitHub Project Setup

### 2.1 Create the Project

1. **Navigate:** GitHub repo → **Projects** tab → **New project**
2. **Template:** Start from scratch → **Board** view (or Table if preferred)
3. **Name:** `Encore Spec Progress` (or `Spec Tracking`)
4. **Link repository:** Ensure the repo is linked so issues can be added
5. **Visibility:** Organization or repo, per your policy

### 2.2 Workflow States (Status Field)

Create a **Status** field (or use built-in) with these values, aligned with `whats-next` and spec workflow:

| Status Value         | Meaning                                                    | Maps to Registry           |
| -------------------- | ---------------------------------------------------------- | -------------------------- |
| **Backlog**          | Spec exists; not started or deferred                       | 📋 Not started             |
| **Spec in progress** | Clarify / validate / spec-reviewer / plan / generate-tasks | Work before implementation |
| **Ready for impl**   | TASKS file exists; implementation not started              | Ready for tasks            |
| **In progress**      | Implementation in progress                                 | 🚧 In progress             |
| **In review**        | All tasks done; verify-task / spec-complete pending        | Pre-complete               |
| **Done**             | spec-complete run; feature complete                        | ✅ Complete                 |

### 2.3 Custom Fields (Optional but Recommended)

| Field            | Type          | Values                                         | Purpose                                        |
| ---------------- | ------------- | ---------------------------------------------- | ---------------------------------------------- |
| **Core**         | Single select | PF, HR, FA, FW, CL, PM, CE, RH, GR, FM, LO, IT | Filter by module                               |
| **Priority**     | Single select | Critical, High, Medium, Low                    | From DEFERRED\_DASHBOARD priority              |
| **Completion %** | Number        | 0–100                                          | From SPEC\_STATUS\_REGISTRY (manual or script) |
| **Spec ID**      | Text          | e.g. HR-05, PM-EN-04                           | Quick reference                                |

### 2.4 Views

* **Board (Kanban):** Status columns = Backlog | Spec in progress | Ready for impl | In progress | In review | Done
* **Table:** Group by Core, filter by Status
* **Roadmap (timeline):** Optional; use if you add target dates

***

## 3. Data Source: GitHub Issues

Each spec (or high-priority deferred item) should have a **GitHub Issue** that is added to the project.

### 3.1 Issue template (canonical)

Canonical template: [`.github/ISSUE_TEMPLATE/spec-tracking.yml`](../../.github/ISSUE_TEMPLATE/spec-tracking.yml) (GitHub issue form). It applies `spec-tracking` only; authors add `core:*` after submit. Bootstrap/API-created issues should use the same fields in markdown (see **Issue body template** in [GITHUB\_MCP\_SPEC\_ISSUES.md](GITHUB_MCP_SPEC_ISSUES.md)).

### 3.2 Labels

Create labels in the repo:

| Label               | Color  | Purpose                                     |
| ------------------- | ------ | ------------------------------------------- |
| `spec-tracking`     | Blue   | All spec-tracking issues                    |
| `core:PF`           | Gray   | Platform Foundation                         |
| `core:HR`           | Gray   | Human Resources                             |
| `core:FA`           | Gray   | Finance & Accounting                        |
| `core:FW`           | Gray   | Forms & Workflow                            |
| `core:CL`           | Gray   | Clinical & EHR                              |
| `core:PM`           | Gray   | Practice Management                         |
| `core:CE`           | Gray   | Community Engagement                        |
| `core:RH`           | Gray   | Recovery Housing                            |
| `core:GR`           | Gray   | Governance & Risk                           |
| `core:FM`           | Gray   | Facilities Management                       |
| `core:LO`           | Gray   | Leadership OS                               |
| `core:IT`           | Gray   | IT Asset Management                         |
| `deferred`          | Orange | Deferred feature (from DEFERRED\_DASHBOARD) |
| `priority:critical` | Red    | Compliance or revenue-blocking              |
| `priority:high`     | Yellow | Ready to promote, high value                |

***

## 4. Bootstrap: Populate the Project

### 4.1 Strategy

**Option A – Manual (pilot):** Create issues for 1–2 cores first (e.g. HR, PM) to validate workflow, then expand.

**Option B – Scripted:** Use a script to read SPEC\_STATUS\_REGISTRY or scan `specs/{core}/specs/` and create issues via GitHub API (or `gh` CLI).

**Option C – Gradual:** Create issues only for "In progress" and "Not started" specs initially; add "Done" later if desired for historical visibility.

### 4.2 Scripted Bootstrap (Recommended)

Create `scripts/bootstrap-github-spec-issues.ts`:

1. **Input:** Parse `specs/SPEC_STATUS_REGISTRY.md` or scan `specs/{core}/specs/*.md`
2. **Output:** For each spec: `{ id, core, name, status, completion }`
3. **Action:** Use `gh issue create` or GitHub API to create issues with:
   * Title: `[CORE-##] Short name`
   * Body: Spec path, summary, "Next: run whats-next"
   * Labels: `spec-tracking`, `core:{core}`
4. **Project add:** Use `gh project item-add` (Projects v2) to add each new issue to the project
5. **Status:** Set project Status field from registry mapping (Complete → Done, etc.)

**Required:** GitHub CLI (`gh`) with `gh auth login`, or GitHub API token with `repo` and `project` scope.

### 4.3 Deferred Items

For high-priority deferred items (e.g. PM-EN-04, PM-EN-09 from DEFERRED\_DASHBOARD):

* Create separate issues with title `[PM-EN-04] Production Clearinghouse Transport`
* Add labels `deferred`, `enhancement`, and `priority:critical` where applicable
* Add to project; initial status = Backlog

For deferred/enhancement items that **do not yet have a dedicated enhancement spec file**, use an explicit placeholder in the issue body:

* `Enhancement Spec: Not yet created`
* `Parent Spec: PM-xx`
* `Source: specs/DEFERRED_DASHBOARD.md`

***

## 5. Ongoing Process

### 5.1 When to Update the Project

| Event                    | Action                                                                   |
| ------------------------ | ------------------------------------------------------------------------ |
| **Start work on a spec** | Move issue to "Spec in progress" or "In progress"; assign yourself       |
| **After whats-next**     | Optionally update issue description with "Next action" output            |
| **After spec-complete**  | Move issue to "Done"; add comment with completion date and log reference |
| **New spec created**     | Create corresponding issue; add to project; status = Backlog             |
| **Deferred promoted**    | Create issue for promoted item; add to project                           |

### 5.2 Sync from Registry (Periodic)

Run this invariant loop after any registry update (and at least weekly for active cores):

1. Refresh registry: `spec-complete --all --completion-report --update-registry` (or run the script directly: `node scripts/audit/audit-spec-completion.js --all --include-deferred --update-registry`)
2. Reconcile: `npm run spec:reconcile-tracking` (add `-- --output reports/SPEC_TRACKING_RECONCILE.md` if you want a snapshot)
3. Create missing canonical issues: `npm run bootstrap:spec-issues -- --sync --active-only`
4. Close stale/duplicate open issues: `npm run spec:close-stale-tracking`
5. Backfill board links for pre-existing issues: `npm run spec:add-tracking-to-project -- --state open`
6. Sync GitHub Project Status field: `npm run spec:sync-project-status`
7. Verify coverage gate (required):
   * `npm run spec-tracking:verify -- --scope active`
   * Optional focused checks: `npm run spec-tracking:verify -- --core CL --scope active` and `npm run spec-tracking:verify -- --core PM --scope active`

Notes:

* **Bootstrap vs. project board:** The bootstrap script only calls `gh project item-add` for issues it **creates in that same run**. If `--sync` skips an issue because the title already exists, that issue is **not** added to the project on that run.
* **Backfill existing issues onto the project:** `npm run spec:add-tracking-to-project` is repeat-safe; existing project items are skipped when `gh` reports duplicates.
* **Project auth prerequisites:** `spec:add-tracking-to-project` and `spec:sync-project-status` require `GH_PROJECT_NUMBER` and `gh` scopes including `project` + `read:project`.

### 5.3 PR and Branch Conventions

* **Branch:** `feat/HR-05-T3-description` or `spec/hr-05`
* **PR title:** `feat(HR-05): Add time-off request workflow`
* **PR body:** `Spec: [HR-05](../../specs/hr/specs/HR-05-time-attendance.md) | Project: #123`

### 5.4 Feature catalogue and enhancement lites (repo automation)

* `npm run spec:sync-deferred` — refresh `specs/DEFERRED_DASHBOARD.md` “By Core” from spec files.
* `npm run spec:feature-catalogue` — regenerate `specs/FEATURE_CATALOGUE.md` from the registry.
* `npm run spec:create-enhancement-catalogs` — bulk-create `*-ENHANCEMENTS.md` lites where appropriate (see script help).
* `npm run spec:validate-enhancement-catalogs` — structural validation of `*-ENHANCEMENTS.md` files; use `--fix` to insert missing `**Feature ID:**` lines.
* Registry refresh: `node scripts/audit/audit-spec-completion.js --all --include-deferred --update-registry`

***

## 6. Execution Checklist

### Phase 1: Setup (One-Time)

* [ ] Create GitHub Project "Encore Spec Progress" (Board view)
* [ ] Add Status field with values: Backlog, Spec in progress, Ready for impl, In progress, In review, Done
* [ ] Add Core field (single select) with all 12 cores
* [ ] Create labels: `spec-tracking`, `core:*`, `deferred`, `enhancement`, `priority:*`
* [ ] Verify issue template `.github/ISSUE_TEMPLATE/spec-tracking.yml` exists (and matches §3.1 canonical fields)
* [ ] Document project URL in this file and README
* [ ] Record **`GH_PROJECT_NUMBER`** (integer from project URL or `gh project list --owner <owner>`) in local env (`.env.local.example` documents the variable). Run **`gh auth refresh -s project`** so `gh project item-add` / `sync-project-status` work.

### Phase 2: Bootstrap

* [ ] **Pilot:** Manually create 5–10 issues for one core (e.g. HR in-progress + not-started)
* [ ] Add those issues to the project; set Status from registry
* [ ] Validate workflow: move one through states, verify visibility
* [ ] **Expand:** Run bootstrap script for remaining specs, or add incrementally

### Phase 3: Script (Optional)

* [ ] Implement `scripts/bootstrap-github-spec-issues.ts`
* [ ] Test on one core
* [ ] Run full bootstrap
* [ ] Add `npm run bootstrap:spec-issues` (or similar) to package.json

### Phase 4: Documentation

* [ ] Update `docs/development/SPEC_WORKFLOW.md` with pointer to this plan
* [ ] Add "Tracking" section to `specs/README.md` referencing GitHub Project
* [ ] Update `AGENTS.md` if project becomes canonical tracking method

***

## 7. Alternative: GitHub Projects Without Issues

GitHub Projects (v2) supports **Draft issues** (project-only items) that don't create repo issues. You can use these if you prefer not to clutter the issue tracker. Draft issues are only visible in the project. Trade-off: No automatic PR linking via `Fixes #123`; manual tracking only.

For full traceability (PR → issue → spec), prefer **real issues** linked to the project.

***

## 8. References

* **Reconciliation triage playbook:** [SPEC\_TRACKING\_TRIAGE.md](SPEC_TRACKING_TRIAGE.md)
* **Spec workflow:** [SPEC\_WORKFLOW.md](SPEC_WORKFLOW.md)
* **Completion tracking:** [SPEC\_COMPLETION\_TRACKING.md](SPEC_COMPLETION_TRACKING.md)
* **Registry:** [specs/SPEC\_STATUS\_REGISTRY.md](../../specs/SPEC_STATUS_REGISTRY.md)
* **Deferred:** [specs/DEFERRED\_DASHBOARD.md](../../specs/DEFERRED_DASHBOARD.md)
* **Roadmap:** README (overview & direction) · [ROADMAP\_SPEC\_MAPPING.md](ROADMAP_SPEC_MAPPING.md)
* **Creating issues via GitHub MCP:** [GITHUB\_MCP\_SPEC\_ISSUES.md](GITHUB_MCP_SPEC_ISSUES.md)
* **Issue status mapping (manual project update):** [GITHUB\_ISSUE\_STATUS\_MAPPING\_BY\_CORE.md](GITHUB_ISSUE_STATUS_MAPPING_BY_CORE.md) (all cores).
* **GitHub webhook (auto-label, idempotency):** [GITHUB\_WEBHOOK\_SETUP.md](GITHUB_WEBHOOK_SETUP.md).
* **GitHub Projects docs:** [Quickstart for Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects)

### Archived reports (2026-03-08)

Point-in-time alignment outputs are in [docs/archive/development/spec-tracking/](../../archive/development/spec-tracking/): MODULE\_STATUS\_BASELINE.md, SPEC\_TRACKING\_RECONCILIATION\_REPORT.md, SPEC\_TRACKING\_VALIDATION\_SUMMARY.md, SPEC\_TRACKING\_FINAL\_STATUS\_REPORT.md.

***

## 9. Appendix: Sample `gh` Commands

```bash theme={null}
# Create project (interactive)
gh project create --owner <org> --title "Encore Spec Progress"

# Create issue
gh issue create --title "[HR-05] Time & Attendance" --body "Spec: specs/hr/specs/HR-05-time-attendance.md" --label "spec-tracking,core:HR"

# Add issue to project (after creating project, get project number)
gh project item-add <project-number> --owner <org> --url <issue-url>

# Backfill all existing spec-tracking issues onto the project (repeat-safe)
npm run spec:add-tracking-to-project

# List issues by label
gh issue list --label "spec-tracking" --state all
```

Note: Exact `gh project` syntax may vary by `gh` version; check `gh project --help` for current subcommands.