Encore OS — Documentation

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: eos-spec next, eos-spec status, spec-complete, spec deferred, eos-spec list
Registry update: spec-complete --all --update-registry
Deferred sync: spec deferred --sync (regenerates DEFERRED_DASHBOARD.md)

2. GitHub Project Setup

2.1 Create the Project

Navigate: GitHub repo → Projects tab → New project
Template: Start from scratch → Board view (or Table if preferred)
Name: Encore Spec Progress (or Spec Tracking)
Link repository: Ensure the repo is linked so issues can be added
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 eos-spec 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 (superpowers:verification-before-completion) / 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 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).

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:

Input: Parse specs/SPEC_STATUS_REGISTRY.md or scan specs/{core}/specs/*.md
Output: For each spec: { id, core, name, status, completion }
Action: Use gh issue create or GitHub API to create issues with:
- Title: [CORE-##] Short name
- Body: Spec path, summary, “Next: run eos-spec next”
- Labels: spec-tracking, core:{core}
Project add: Use gh project item-add (Projects v2) to add each new issue to the project
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 eos-spec 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):

Refresh registry: spec-complete --all --update-registry (or run the script directly: node scripts/audit/audit-spec-completion.js --all --include-deferred --update-registry)
Reconcile: npm run spec:reconcile-tracking (add -- --output reports/SPEC_TRACKING_RECONCILE.md if you want a snapshot)
Create missing canonical issues: npm run bootstrap:spec-issues -- --sync --active-only
Close stale/duplicate open issues: npm run spec:close-stale-tracking
Backfill board links for pre-existing issues: npm run spec:add-tracking-to-project -- --state open
Sync GitHub Project Status field: npm run spec:sync-project-status
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 workflow: SPEC_WORKFLOW.md
Completion tracking: SPEC_COMPLETION_TRACKING.md
Registry: specs/SPEC_STATUS_REGISTRY.md
Deferred: specs/DEFERRED_DASHBOARD.md
Roadmap: README (overview & direction) · ROADMAP_SPEC_MAPPING.md
Creating issues via GitHub MCP: GITHUB_MCP_SPEC_ISSUES.md
Issue status mapping (manual project update): GITHUB_ISSUE_STATUS_MAPPING_BY_CORE.md (all cores).
GitHub webhook (auto-label, idempotency): GITHUB_WEBHOOK_SETUP.md.
GitHub Projects docs: Quickstart for Projects

Archived reports (2026-03-08)

Point-in-time alignment outputs are in docs/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

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

​Executive Summary

​1. Current State Summary

​Specs Overview

​Cores and Spec Counts (from Registry)

​Existing Tracking (Repo-Based)

​2. GitHub Project Setup

​2.1 Create the Project

​2.2 Workflow States (Status Field)

​2.3 Custom Fields (Optional but Recommended)

​2.4 Views

​3. Data Source: GitHub Issues

​3.1 Issue template (canonical)

​3.2 Labels

​4. Bootstrap: Populate the Project

​4.1 Strategy

​4.2 Scripted Bootstrap (Recommended)

​4.3 Deferred Items

​5. Ongoing Process

​5.1 When to Update the Project

​5.2 Sync from Registry (Periodic)

​5.3 PR and Branch Conventions

​5.4 Feature catalogue and enhancement lites (repo automation)

​6. Execution Checklist

​Phase 1: Setup (One-Time)

​Phase 2: Bootstrap

​Phase 3: Script (Optional)

​Phase 4: Documentation

​7. Alternative: GitHub Projects Without Issues

​8. References

​Archived reports (2026-03-08)

​9. Appendix: Sample gh Commands