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

SourceContent
SPEC_STATUS_REGISTRY~198 specs across 12 cores; 113 complete, 1 in progress, 84 not started; 57% avg completion
DEFERRED_DASHBOARD37+ deferred items (PM), 11+ (CL), plus HR-13, PF summaries
ROADMAPFA, RH, CE, FM, IT, Production Readiness priorities
Implementation LogsPer-core specs/{core}/IMPLEMENTATION_LOG.md

​
Cores and Spec Counts (from Registry)

CoreTotalCompleteIn ProgressNot StartedAvg %
PF (Platform Foundation)534201179%
HR (Human Resources)21161485%
FA (Finance & Accounting)13120192%
FW (Forms & Workflow)27190885%
CL (Clinical & EHR)30250583%
PM (Practice Management)191900100%
CE (Community Engagement)3300100%
RH, GR, FM, LO, ITvaries00varies0–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 ValueMeaningMaps to Registry
BacklogSpec exists; not started or deferred📋 Not started
Spec in progressClarify / validate / spec-reviewer / plan / generate-tasksWork before implementation
Ready for implTASKS file exists; implementation not startedReady for tasks
In progressImplementation in progress🚧 In progress
In reviewAll tasks done; verify-task / spec-complete pendingPre-complete
Donespec-complete run; feature complete✅ Complete
FieldTypeValuesPurpose
CoreSingle selectPF, HR, FA, FW, CL, PM, CE, RH, GR, FM, LO, ITFilter by module
PrioritySingle selectCritical, High, Medium, LowFrom DEFERRED_DASHBOARD priority
Completion %Number0–100From SPEC_STATUS_REGISTRY (manual or script)
Spec IDTexte.g. HR-05, PM-EN-04Quick 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:
LabelColorPurpose
spec-trackingBlueAll spec-tracking issues
core:PFGrayPlatform Foundation
core:HRGrayHuman Resources
core:FAGrayFinance & Accounting
core:FWGrayForms & Workflow
core:CLGrayClinical & EHR
core:PMGrayPractice Management
core:CEGrayCommunity Engagement
core:RHGrayRecovery Housing
core:GRGrayGovernance & Risk
core:FMGrayFacilities Management
core:LOGrayLeadership OS
core:ITGrayIT Asset Management
deferredOrangeDeferred feature (from DEFERRED_DASHBOARD)
priority:criticalRedCompliance or revenue-blocking
priority:highYellowReady 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. 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

EventAction
Start work on a specMove issue to “Spec in progress” or “In progress”; assign yourself
After whats-nextOptionally update issue description with “Next action” output
After spec-completeMove issue to “Done”; add comment with completion date and log reference
New spec createdCreate corresponding issue; add to project; status = Backlog
Deferred promotedCreate 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

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