feat(manager): add /gsd:manager — interactive milestone dashboard

[jippylong12]

Summary

Adds /gsd:manager, a single-terminal command center for managing milestones. Sits between fully autonomous (/gsd:autonomous) and manual phase-by-phase commands — gives you an overview of all phases, recommends next actions, and lets you dispatch work without context-switching or remembering where each phase is at.

Motivation

After using GSD across several milestones, I found that the autonomous mode works great for fire-and-forget, but I wanted more visibility and control over what's running without having to manually check /gsd:progress and remember phase numbers. The manager fills that gap:

• See everything at once — dashboard with status indicators (Discuss/Plan/Execute) per phase
• Smart recommendations — suggests what to do next based on actual disk state
• Dispatch from one terminal — discuss runs inline, plan/execute spawn as background agents
• Dependency awareness — won't suggest parallel work on phases that depend on each other

This is an initial implementation to get the idea out there and start discussion. Token efficiency and workflow refinement are areas that could benefit from community input.

Changes

New files

File	Purpose
commands/gsd/manager.md	Skill definition (entry point)
get-shit-done/workflows/manager.md	Full workflow spec — dashboard loop, action dispatch, background agent handling
tests/init-manager.test.cjs	16 tests covering status detection, dependencies, sliding window, recommendations

Modified files

File	Change
get-shit-done/bin/lib/init.cjs	New cmdInitManager() — phase parsing, dependency graph, recommendation engine
get-shit-done/bin/gsd-tools.cjs	Route init manager to new command
tests/copilot-install.test.cjs	Bump expected skill count 50 → 51
package-lock.json	Node engine min version update

Recommendation engine details

The core logic in cmdInitManager():

1. Prioritizes execute > plan > discuss
2. Filters conflicts — if a phase is actively executing, won't suggest executing another phase in the same dependency chain
3. Allows parallel work on independent phases — uses transitive dependency graph traversal to determine true independence
4. Sliding window — limits discuss to one phase at a time
5. Deps column — compact deps_display field (e.g. 1,3 or —) for the dashboard table

How it works

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► DASHBOARD
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ████░░░░░░░░░░░░░░░░ 20%  (1/5 phases)

 | # | Phase                | Deps | D | P | E | Status              |
 |---|----------------------|------|---|---|---|---------------------|
 | 1 | Foundation           | —    | ✓ | ✓ | ✓ | ✓ Complete          |
 | 2 | API Layer            | 1    | ✓ | ✓ | ○ | ○ Ready to execute  |
 | 3 | Auth System          | 1,2  | ✓ | ✓ | ○ | ○ Ready to execute  |
 | 4 | Dashboard UI         | 1    | ✓ | ○ | · | ○ Ready to plan     |
 | 5 | Notifications        | —    | ○ | · | · | ○ Ready to discuss  |

───────────────────────────────────────────────────────────────
▶ Next Steps
───────────────────────────────────────────────────────────────

Continue:
  → Execute Phase 2 (background)
  → Plan Phase 4 (background)
  → Discuss Phase 5 (inline)

Phase 3 has plans ready but depends on Phase 2 (not yet complete) — blocked from execution.
Phase 4 is independent of Phase 2, so it can be planned in parallel.
Phase 5 is independent (no deps) and next in line to discuss.

Known limitations / future work

• Token efficiency — the dashboard refresh loop and background agent dispatching could be optimized
• Activity detection — uses file mtime (5-min window) as a heuristic; not always accurate for distinguishing "just finished planning" from "actively planning"
• No persistent dispatch tracking — relies on disk state to infer what's running rather than tracking dispatched actions explicitly

Test plan

• All 16 new tests pass (node --test tests/init-manager.test.cjs)
• Existing test suite unaffected
• Manual testing with active milestone (used across several days of real project work)
• Verify background agent dispatch works end-to-end
• Test dependency filtering with phases that have complex dep chains

🤖 Generated with Claude Code

[trek-e]

Adversarial Review — PR #1282 (feat: /gsd:manager)

Nice feature concept — fills a real gap between autonomous and manual mode. The recommendation engine logic is solid and the test coverage for the init command is good. A few issues to address before merge:

---

Bug: Missing withProjectRoot() wrapper on output

Severity: Medium (breaks pattern, likely causes downstream issues)

Every other cmdInit* function in init.cjs wraps its output with withProjectRoot(cwd, result):

output(withProjectRoot(cwd, result), raw);

But cmdInitManager uses:

output(result, raw);

This means the JSON output will be missing the project_root field that other init commands include. The workflow spec doesn't reference it, but consumers may expect consistent shape from init commands — and the project_root is useful for the Task() prompts that need cwd.

---

Bug: No getMilestonePhaseFilter — stale phases from prior milestones may appear

Severity: Medium

cmdInitProgress uses getMilestonePhaseFilter(cwd) to filter phase directories to the current milestone scope. cmdInitManager reads the phases directory directly without this filter. In repositories with multiple milestones (shipped phases from v1 still on disk), the directory scan could pick up stale phase directories that don't belong to the current milestone, causing phantom entries or miscounts in the dashboard.

---

Code Quality: Significant phase-parsing duplication with cmdInitProgress

Severity: Low (no runtime impact, but maintenance burden)

cmdInitManager reimplements phase discovery from ROADMAP.md (regex parsing, directory scanning, status detection, plan/summary counting) that cmdInitProgress already does. The patterns are nearly identical:

• Same regex: /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi
• Same (INSERTED) stripping
• Same plan/summary/research file detection
• Same status classification logic

Consider extracting a shared analyzePhases(cwd) utility in core.cjs that both commands can use. This would also prevent the two commands from drifting apart on status classification logic (they already differ slightly — cmdInitProgress uses 'in_progress' while cmdInitManager uses 'planned' for the same state).

---

Workflow: --no-verify instruction in background agent prompt

Severity: Informational

The execute-phase background agent prompt in manager.md line 267 instructs:

"Use --no-verify on git commits."

This is consistent with the existing execute-phase.md workflow for parallel agents (documented in ARCHITECTURE.md and the existing workflow), so this is fine. Just noting it's there for awareness — the --no-verify usage is scoped correctly to background parallel execution where it's expected.

---

Test Coverage Assessment

16 tests, good coverage of the init command:

• Prerequisite validation (no ROADMAP, no STATE) ✓
• Phase status detection across all states ✓
• Dependency satisfaction (complete and incomplete) ✓
• Sliding window (sequential discuss) ✓
• Full pipeline scenario (execute + plan + discuss) ✓
• Recommendation ordering ✓
• All-complete flag ✓
• WAITING.json detection ✓
• Display name truncation ✓
• Activity detection ✓

Missing test coverage:

• Multi-milestone filtering (since getMilestonePhaseFilter is not used, this gap is consistent)
• Transitive dependency filtering (reaches() / hasDepRelationship() with actively executing phases) — no test exercises the conflict filter where activeExecuting blocks a dependent phase
• Phase number formats: 1A, 1.1 — the regex supports them but no tests exercise non-integer phase numbers
• Error handling: what happens when ROADMAP.md exists but is malformed or empty

---

Overlap with Other Open PRs

• #1268 (workstream namespacing): Moderate overlap. #1268 changes planningPaths() to be workstream-aware and moves from inline .planning/ paths to scoped paths. cmdInitManager hardcodes .planning/ROADMAP.md and .planning/STATE.md paths instead of using planningPaths(cwd). If #1268 merges first, cmdInitManager will bypass workstream scoping entirely. Recommend using planningPaths(cwd) instead of hardcoded paths.
• #1190 (knowledge layer): No overlap — different subsystem.
• #1289 (release strategy): No overlap — CI/release concerns only.

---

Summary

The recommendation engine is well-designed (priority ordering, dependency graph traversal, sliding window). The test suite covers the core scenarios well. Two bugs (missing withProjectRoot, missing milestone filter) and the planningPaths() forward-compatibility issue with #1268 should be addressed before merge. The duplication with cmdInitProgress is a suggestion, not a blocker.

Verdict: Requesting changes for the withProjectRoot bug and missing milestone phase filter.

[jippylong12]

Addressed in f7031e2:

1. withProjectRoot() — Fixed. Output now wraps with withProjectRoot(cwd, result).

2. getMilestonePhaseFilter — Fixed. Directory scan filters through isDirInMilestone().

3. planningPaths(cwd) — Fixed. All hardcoded .planning/ paths replaced, including prerequisite checks. Forward-compatible with #1268.

Tests: 19/19 passing

3 new tests added for the requested changes:

• conflict filter: blocks dependent phase execute when dep is active ✓
• conflict filter: allows independent phase execute in parallel ✓
• output includes project_root field ✓

All 16 original tests continue to pass with no regressions. Copilot install suite (106 tests) also unaffected.

Duplication with cmdInitProgress: Agreed — deferring shared analyzePhases() extraction to a follow-up PR.

--no-verify: Acknowledged — scoped to background parallel execution per existing convention.

[trek-e]

Re-review of fix commit f7031e2

All three findings from the initial review are correctly resolved:

1. withProjectRoot() wrapper — output(result, raw) replaced with output(withProjectRoot(cwd, result), raw). JSON output now includes project_root consistent with all other cmdInit* functions.

2. getMilestonePhaseFilter — Filter obtained via const isDirInMilestone = getMilestonePhaseFilter(cwd) and applied in the directory scan: .filter(isDirInMilestone). Stale phase directories from prior milestones are now excluded.

3. planningPaths(cwd) — All five hardcoded .planning/ references replaced: paths.roadmap (prerequisite check + read), paths.state (prerequisite check), paths.phases (directory scan). Forward-compatible with #1268 workstream scoping.

New tests (3 added, 19 total):

• conflict filter: blocks dependent phase execute when dep is active — exercises the activeExecuting filter with a transitive dependency chain (Phase 3 depends on Phase 2 which is partial). Asserts zero execute recommendations. Correct.
• conflict filter: allows independent phase execute in parallel — exercises the independence check where Phase 3 has no dependency on actively-executing Phase 2. Asserts exactly one execute recommendation for Phase 3. Correct.
• output includes project_root field — verifies project_root is present in JSON output and matches the temp directory (with macOS /var -> /private/var normalization via fs.realpathSync). Correct.

Fix commit scope: Clean — 2 files changed (init.cjs: 11 insertions, 10 deletions; test file: 55 insertions). No unrelated changes introduced.

No new issues found.