Docs Project Dashboard Legacy

Docs Project Dashboard Legacy

Custom skill created by Maggie Lerman.

Deprecation Note

Prefer $context-layer-dashboard-backfill for existing repos that need the modern sidebar-based generated dashboard.

Use this legacy skill only when:

• the repo already has standardized docs scaffolding
• you need to backfill the dashboard without rerunning the broader scaffold workflow
• you explicitly want the standalone retrofit path

Overview

Use this legacy skill to add a generated PROJECTS/dashboard.html file plus a reusable repo-side generator script so the dashboard can be regenerated after project-doc changes.

The generator also supports an optional repo-side content calendar. When docs/content/content-calendar.json, docs/content/blog-content-calendar.json, or another docs/content/*calendar*.json file exists, the dashboard renders a Content Calendar section with cadence metrics and planned items.

Assume the target repository already follows the product-operating-system-scaffold project layout:

• DOCS/, docs/, or documentation/
• PROJECTS/active/
• PROJECTS/in-review/
• PROJECTS/blocked/
• PROJECTS/completed/
• PROJECTS/backlog/
• PROJECTS/stale/

Treat folder placement as the primary lifecycle signal and frontmatter status as secondary metadata.

What The Dashboard Should Show

The generated dashboard is a lightweight local PM system, not a replacement for the project docs themselves. The HTML dashboard should give the user an at-a-glance answer to:

• what exists
• what needs attention now
• what is blocked
• what is waiting for sign-off
• what changed recently
• where each planning document lives

The source of truth remains the markdown project docs in the repo. The HTML page is derived output.

The output contract lives in references/dashboard-contract.md. Read it only when you need to change the dashboard structure or extend the extracted metadata.

Workflow

1. Confirm the repo is a backfill candidate

Check for an existing docs root in this order:

1. DOCS/
2. docs/
3. documentation/

If more than one exists, prefer the one that already contains PROJECTS/ and a README.md or index.md. If ambiguity remains, ask the user before writing.

If the repo does not already have a PROJECTS/ tree, stop and use $product-operating-system-scaffold instead.

2. Run the installer script

Use the bundled installer:

python3 <skill_dir>/scripts/install_docs_project_dashboard.py --repo /absolute/path/to/repo

Optional flags:

python3 <skill_dir>/scripts/install_docs_project_dashboard.py \
  --repo /absolute/path/to/repo \
  --docs-root DOCS \
  --force-dashboard \
  --with-content-calendar

The installer:

• discovers the docs root
• copies the repo-side generator to scripts/docs/projects-dashboard.mjs
• adds docs:projects-dashboard to package.json when present
• appends or updates a dashboard link in PROJECTS/README.md
• optionally installs starter content-calendar.json and content-calendar.md files under <docs-root>/content/
• generates PROJECTS/dashboard.html
• rebuilds the docs manifest when scripts/docs/manifest.mjs exists

3. Respect safe-write behavior

• Treat PROJECTS/dashboard.html as generated output.
• If PROJECTS/dashboard.html already exists and is not marked as generated by this skill, do not overwrite it unless the user explicitly asks or you pass --force-dashboard.
• For package.json and PROJECTS/README.md, add only the missing dashboard wiring.
• Do not rewrite existing project docs.
• If an older generated PROJECTS/dashboard.md exists from a previous version of this skill, it is safe to remove it during install.

4. Regenerate after project-doc changes

After the backfill lands, regenerate with:

node scripts/docs/projects-dashboard.mjs <docs_root>

If package.json includes scripts, prefer:

npm run docs:projects-dashboard

5. Verify before finishing

Confirm:

• PROJECTS/dashboard.html exists
• dashboard cards and rows link to the correct planning docs
• content calendar appears when a supported calendar JSON exists
• blocked, in-review, and active queues render
• recently updated projects are sorted correctly
• grouped program rows appear when parentProject or programTrack metadata exists
• manifest regeneration succeeds when available

Repo Conventions

• Preserve actual casing for the repo's chosen docs root.
• Keep the dashboard inside the PROJECTS/ root so it stays next to the planning docs.
• Use folder location as the lane shown in the dashboard even when frontmatter status drifts.
• Surface lane/frontmatter drift in the dashboard instead of silently correcting project docs.
• Use relative links from PROJECTS/dashboard.html to the planning documents.
• Keep the content calendar optional: install starter files only when requested, and let existing repos surface their own calendar JSON without rewriting it.

Resources

• Installer: scripts/install_docs_project_dashboard.py
• Dashboard contract: references/dashboard-contract.md
• Repo-side generator asset: assets/repo/scripts/docs/projects-dashboard.mjs
• Optional content calendar templates: assets/repo/docs/content/content-calendar.{json,md}