Make tasks server the primary master plans doc surface deprecating MkDocs
Problem
Two doc servers confuse contributors. Once the tasks server covers browsing + live status, MkDocs should become secondary or retired for master plans.
Longer-term end state (tracked across follow-on tasks): just tasks serve as the only local “plans site,” with navigation that mirrors milestones → workstreams → tasks/initiatives on the server, and eventual removal of just plans once parity and static export (if any) are settled.
Context
- Dependency add-tasks-serve-command-and-plans-server is completed (PR #712 merged). The tasks server ships
/status,/status.json, and/browse/endpoints via FastAPI on port 8005. - MkDocs (
just plans, port 8004) remains active for: Material theme search, macro-rendered content (macros.py), Mermaid diagrams, and the static deploy pipeline (.github/workflows/deploy-static-sites.yml→ GCS bucket). - CI still runs
mkdocs build -f tasks/mkdocs.ymlfor static hosting. Removing this requires a separate static-export story for the tasks server. - Operator /status UX: improve-tasks-serve-status-ui-for-operator-triage.
- Rename + paths: rename-master-plans-tree-to-tasks — committed tree →
tasks/, runtime state →<repo>/.tasks/, explicitTASKS_ROOT/--tasks-rootinstead of hard-codedtasks/path math.
Possible Solutions
- A — Docs-only migration: Update AGENTS.md, cli-reference.md, and justfile help to prefer
just tasks servefor local browsing. Keep MkDocs for static deploy and as a secondary option. No code changes, no CI changes. - B — Remove MkDocs for plans: Delete
tasks/mkdocs.ymland all MkDocs-specific assets after building a static export path for the tasks server. Requires CI pipeline changes. - Recommended: A now. B only after a static-export story ships and stakeholder sign-off.
Plan
- [x] Audit feature gap: tasks server covers live status + markdown browse; MkDocs adds search, macros, Mermaid, and static deploy. Gap accepted for local dev workflow — search and macros are not needed for day-to-day task browsing.
- [x] Update AGENTS.md to list
just tasks serveas primary local workflow, MkDocs as secondary/static. - [x] Update
tasks/tools/cli-reference.mdto reflect primary status. - [x] Update justfile help text to label tasks server as primary and MkDocs as legacy.
- [ ] (Future — out of scope) Adjust CI/publish pipeline once static export story exists.
- [ ] (Future) README/CLAUDE entrypoints still to prefer
just tasks serveexplicitly (see Implementation Progress).
Implementation Progress
Audit: feature gap accepted
| Feature | Tasks Server | MkDocs |
|---|---|---|
| Task status + live heartbeat | Yes (/status) |
No |
| Markdown browse | Yes (/browse/) |
Yes (rendered) |
| Search | No | Yes (Material) |
| Macros / Mermaid | No | Yes |
| Static deploy (GCS) | No | Yes |
For local dev and operator workflows, live task status is the primary need. Search and macros are nice-to-haves used mainly for milestone/strategy docs, not daily task work. Gap accepted.
Changes made
- AGENTS.md: Updated "Plans serving modes" to prefer
just tasks serveas the primary local workflow, withjust plansas secondary for static content. - cli-reference.md: Removed "separate from MkDocs" framing; stated tasks server is the primary local surface.
- justfile: Updated help text to label tasks server as "Primary" and MkDocs as "Legacy".
Follow-up
- README.md / CLAUDE.md still do not consistently list
just tasks serveas the primary operator path for master plans — track as a small docs sweep or reopen scope.
QA Exploration
- [x] N/A — docs-only changes, no UI affected
Review Feedback
- [ ] Review cleared