Skip to content

Commit 708697b

Browse files
author
Test User
committed
manager job
1 parent 0a2b376 commit 708697b

62 files changed

Lines changed: 2705 additions & 45 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,4 @@ qa-artifacts/
4646

4747
night-watch.config.json
4848
.worktrees
49+
.night-watch/manager/

‎docs/guides/troubleshooting.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -392,6 +392,7 @@ crontab -l | grep night-watch
392392
| Reviewer | `logs/reviewer.log` | PR review cycles |
393393
| QA | `logs/qa.log` | QA test runs |
394394
| Audit | `logs/audit.log` | Code audit runs |
395+
| Manager | `logs/manager.log` | Roadmap/project health |
395396
| Server | `logs/server.log` | Web UI API requests |
396397

397398
---

‎docs/prds/manager-agent.md‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
# PRD: Manager Agent
2+
3+
**Complexity: 9 -> HIGH mode**
4+
5+
---
6+
7+
## 1. Context
8+
9+
**Problem:** Night Watch can execute, review, QA, audit, slice, and merge work, but it does not have a roadmap-aware manager that continuously checks whether the automation system, project board, PRDs, and documentation remain aligned.
10+
11+
**Files Analyzed:**
12+
13+
- `ROADMAP.md` - product direction and current/future agent responsibilities
14+
- `CLAUDE.md` - repo conventions for TypeScript, DI, tests, and package manager
15+
- `templates/prd-creator.md` - required PRD planning template
16+
- `packages/core/src/jobs/job-registry.ts` - central job metadata registry
17+
- `packages/core/src/types.ts` - config, job type, notification, and queue types
18+
- `packages/core/src/constants.ts` - default config and log/job constants
19+
- `packages/core/src/config.ts` - config loading, normalization, validation
20+
- `packages/core/src/config-env.ts` - environment variable overrides
21+
- `packages/cli/src/commands/agent.ts` - machine-readable agent status
22+
- `packages/cli/src/commands/board.ts` - board issue creation and roadmap sync patterns
23+
- `packages/cli/src/commands/install.ts` - cron installation patterns
24+
- `packages/cli/src/commands/queue.ts` - job queue command/job dispatch patterns
25+
- `packages/cli/src/commands/slice.ts` - scheduled AI job command pattern
26+
- `packages/cli/src/commands/notify.ts` - notification command/event integration
27+
28+
**Current Behavior:**
29+
30+
- Night Watch has first-class jobs for executor, reviewer, PR resolver, slicer, QA, audit, analytics, and merger.
31+
- The slicer turns roadmap items into PRDs, but there is no agent responsible for ongoing roadmap/project health.
32+
- `roadmapScanner.roadmapPath` already defaults to `ROADMAP.md` and should remain the shared roadmap source.
33+
- Notifications already support Slack, Discord, and Telegram via `notifications.webhooks`.
34+
- `night-watch agent status --json` exposes operational state for current jobs, but not a Manager job.
35+
- Runtime logs and local config are ignored; `.night-watch/manager` should also be local generated state.
36+
37+
**Integration Points Checklist:**
38+
39+
```markdown
40+
**How will this feature be reached?**
41+
- [ ] Entry point identified: `night-watch manager`
42+
- [ ] Entry point identified: installed cron entry when `manager.enabled` is true
43+
- [ ] Entry point identified: queue/agent status through existing job registry flows
44+
- [ ] Caller file identified: `packages/cli/src/cli.ts`
45+
- [ ] Registration/wiring needed: job registry, config defaults, install/uninstall, status/logs/queue, notification events
46+
47+
**Is this user-facing?**
48+
- [ ] YES -> CLI command, config fields, board draft issues, notifications, generated manager memory/docs
49+
50+
**Full user flow:**
51+
1. User enables Night Watch with board and notifications configured.
52+
2. Cron runs `night-watch manager` on the configured schedule.
53+
3. Manager reads `roadmapScanner.roadmapPath`, PRDs, board items, job status, queue state, logs, and documentation coverage signals.
54+
4. Manager updates Markdown memory under `.night-watch/manager/memory.md`.
55+
5. Manager writes Manager-owned generated docs under `.night-watch/manager/docs`.
56+
6. Manager creates draft GitHub Project issues in the configured target column for actionable gaps.
57+
7. Manager sends urgent blocker notifications for human-only work and a weekly roadmap/project summary.
58+
```
59+
60+
---
61+
62+
## 2. Solution
63+
64+
**Approach:**
65+
66+
- Add `manager` as a first-class Night Watch job instead of extending slicer, so it has its own config, schedule, status, pause/resume, logs, and provider assignment.
67+
- Reuse `roadmapScanner.roadmapPath` for roadmap input. Do not introduce a second roadmap path.
68+
- Default Manager authority to draft-only: it creates board draft issues, not ready PRDs or workflow mutations.
69+
- Store Manager memory as Markdown only under `.night-watch/manager/memory.md`.
70+
- Allow direct documentation writes only for Manager-owned generated docs under `.night-watch/manager/docs`.
71+
- Reuse existing notification webhooks with new Manager notification events.
72+
73+
**Architecture Diagram:**
74+
75+
```mermaid
76+
flowchart LR
77+
Cron[Cron / Manual CLI] --> Cmd[night-watch manager]
78+
Cmd --> Runner[Manager Runner]
79+
Runner --> Roadmap[ROADMAP.md via roadmapScanner.roadmapPath]
80+
Runner --> Status[Agent Status / Queue / Logs]
81+
Runner --> Board[Board Provider]
82+
Runner --> Memory[.night-watch/manager/memory.md]
83+
Runner --> Docs[.night-watch/manager/docs]
84+
Runner --> Notify[Existing Notifications]
85+
Board --> Drafts[Draft Board Issues]
86+
```
87+
88+
**Key Decisions:**
89+
90+
- [ ] Manager is a new job type: `manager`.
91+
- [ ] Default output is board draft issues.
92+
- [ ] Default roadmap source is `roadmapScanner.roadmapPath`.
93+
- [ ] Default memory is Markdown only.
94+
- [ ] Default escalation sends blocker notifications plus weekly summaries.
95+
- [ ] Manager-owned docs are local generated files under `.night-watch/manager/docs`.
96+
97+
**Data Changes:** None to SQLite. Add config fields and local generated Markdown files only.
98+
99+
---
100+
101+
## 3. Sequence Flow
102+
103+
```mermaid
104+
sequenceDiagram
105+
participant Cron
106+
participant CLI as night-watch manager
107+
participant Runner as Manager Runner
108+
participant Board
109+
participant Memory as Markdown Memory
110+
participant Notify as Notifications
111+
112+
Cron->>CLI: night-watch manager
113+
CLI->>Runner: runManager(projectDir, config, options)
114+
Runner->>Runner: read roadmap, PRDs, status, queue, logs, docs signals
115+
Runner->>Memory: load fingerprints and previous summary state
116+
Runner->>Board: read existing issues
117+
alt New actionable gap
118+
Runner->>Board: create draft issue
119+
Runner->>Memory: append finding fingerprint
120+
else Duplicate gap
121+
Runner->>Memory: record skipped duplicate
122+
end
123+
alt Human blocker
124+
Runner->>Notify: manager_blocked
125+
end
126+
alt Weekly summary due
127+
Runner->>Memory: append weekly summary
128+
Runner->>Notify: manager_weekly_summary
129+
end
130+
Runner-->>CLI: structured result
131+
```
132+
133+
---
134+
135+
## 4. Execution Phases
136+
137+
#### Phase 1: Job Registration - `manager` is a first-class Night Watch job
138+
139+
**Files (max 5):**
140+
141+
- `packages/core/src/types.ts` - add Manager job/config/notification types
142+
- `packages/core/src/constants.ts` - add default Manager config/log constants
143+
- `packages/core/src/jobs/job-registry.ts` - register Manager metadata
144+
- `packages/core/src/config.ts` - load/normalize Manager config
145+
- `packages/core/src/config-env.ts` - add Manager env overrides
146+
147+
**Implementation:**
148+
149+
- [ ] Add `manager` to `JobType` and `IJobProviders`.
150+
- [ ] Add `IManagerConfig` with `enabled`, `schedule`, `maxRuntime`, `authority`, `outputMode`, `targetColumn`, `memoryPath`, `docsDir`, `weeklySummaryEnabled`, and `weeklySummaryDay`.
151+
- [ ] Add notification events `manager_blocked` and `manager_weekly_summary`.
152+
- [ ] Add `DEFAULT_MANAGER` and `MANAGER_LOG_NAME`.
153+
- [ ] Register Manager in `JOB_REGISTRY` with `cliCommand: 'manager'`, `logName: 'manager'`, `lockSuffix: '-manager.lock'`, and priority below slicer but above audit/analytics.
154+
- [ ] Normalize config values conservatively and preserve defaults for invalid optional values.
155+
- [ ] Support `NW_MANAGER_ENABLED`, `NW_MANAGER_SCHEDULE`, and `NW_MANAGER_MAX_RUNTIME`.
156+
157+
**Tests Required:**
158+
159+
| Test File | Test Name | Assertion |
160+
|-----------|-----------|-----------|
161+
| `packages/core/src/__tests__/config.test.ts` | `loads default manager config` | default config has `manager.enabled === true` and `manager.outputMode === 'board-draft'` |
162+
| `packages/core/src/__tests__/config.test.ts` | `loads manager config from file` | configured schedule/memory/output values are preserved |
163+
| `packages/core/src/__tests__/jobs/job-registry.test.ts` | `includes manager in valid job types` | `getValidJobTypes()` contains `manager` |
164+
165+
**User Verification:**
166+
167+
- Action: Run `night-watch config get manager --json`
168+
- Expected: Resolved Manager config is returned.
169+
170+
#### Phase 2: CLI, Cron, Status, and Queue Wiring - Manager is operable
171+
172+
**Files (max 5):**
173+
174+
- `packages/cli/src/cli.ts` - register `managerCommand`
175+
- `packages/cli/src/commands/manager.ts` - add Manager command entry point
176+
- `packages/cli/src/commands/install.ts` - install Manager cron when enabled
177+
- `packages/cli/src/commands/uninstall.ts` - include Manager log/cron cleanup
178+
- `packages/cli/src/commands/agent.ts` - include Manager in machine-readable status through valid job types
179+
180+
**Implementation:**
181+
182+
- [ ] Implement `night-watch manager` with `--dry-run`, `--json`, `--timeout <seconds>`, and `--provider <provider>` where existing command patterns support it.
183+
- [ ] Apply cron scheduling delay and queue behavior consistently with other scheduled jobs.
184+
- [ ] Install cron entry writing to `logs/manager.log`.
185+
- [ ] Ensure pause/resume, valid job lists, and agent status include Manager through registry-based code.
186+
- [ ] Add `.night-watch/manager/` to `.gitignore`.
187+
188+
**Tests Required:**
189+
190+
| Test File | Test Name | Assertion |
191+
|-----------|-----------|-----------|
192+
| `packages/cli/src/__tests__/commands/manager.test.ts` | `prints dry-run json without side effects` | output includes `dryRun: true` and no created issues |
193+
| `packages/cli/src/__tests__/commands/install.test.ts` | `installs manager cron when enabled` | generated crontab includes `night-watch manager` |
194+
| `packages/cli/src/__tests__/commands/agent.test.ts` | `agent status includes manager` | JSON status contains Manager process/pause/lastRun fields |
195+
196+
**User Verification:**
197+
198+
- Action: Run `night-watch manager --dry-run --json`
199+
- Expected: Command exits zero with a structured analysis result.
200+
201+
#### Phase 3: Manager Runner - Manager analyzes roadmap and system state
202+
203+
**Files (max 5):**
204+
205+
- `packages/core/src/manager/manager-runner.ts` - core orchestration
206+
- `packages/core/src/manager/manager-memory.ts` - Markdown memory read/write and fingerprints
207+
- `packages/core/src/manager/manager-analysis.ts` - roadmap/system/docs signal analysis
208+
- `packages/core/src/manager/manager-prompts.ts` - PRD-quality draft body generation prompt helpers
209+
- `packages/core/src/index.ts` - selective exports
210+
211+
**Implementation:**
212+
213+
- [ ] Read the roadmap from `roadmapScanner.roadmapPath`.
214+
- [ ] Inspect current PRDs, board items, queue, health/status snapshot, and log metadata.
215+
- [ ] Generate findings for roadmap gaps, blocked work, stale execution signals, duplicate/stale PRDs, and missing Manager-owned docs.
216+
- [ ] Create stable fingerprints for findings.
217+
- [ ] Write Markdown memory with latest run summary, fingerprints, blocked items, created drafts, and weekly summary timestamp.
218+
- [ ] Write only Manager-owned docs under `manager.docsDir`.
219+
- [ ] In dry-run mode, return proposed actions without writing memory/docs or board issues.
220+
221+
**Tests Required:**
222+
223+
| Test File | Test Name | Assertion |
224+
|-----------|-----------|-----------|
225+
| `packages/core/src/__tests__/manager/manager-runner.test.ts` | `returns roadmap findings in dry run` | result includes proposed draft for unmatched roadmap gap |
226+
| `packages/core/src/__tests__/manager/manager-memory.test.ts` | `dedupes findings from markdown memory` | repeated fingerprint is skipped |
227+
| `packages/core/src/__tests__/manager/manager-runner.test.ts` | `writes only manager-owned docs` | generated docs path starts with configured `docsDir` |
228+
229+
**User Verification:**
230+
231+
- Action: Run Manager in a temp project with a roadmap and fake board provider.
232+
- Expected: Memory updates and duplicate runs do not create duplicate drafts.
233+
234+
#### Phase 4: Board Drafts and Notifications - Manager creates drafts and asks for help
235+
236+
**Files (max 5):**
237+
238+
- `packages/core/src/manager/manager-board.ts` - board draft creation and issue dedupe
239+
- `packages/core/src/manager/manager-notifications.ts` - Manager notification mapping
240+
- `packages/core/src/utils/notify.ts` - support Manager events if event-specific rendering is needed
241+
- `packages/cli/src/commands/manager.ts` - connect runner result to notifications
242+
- `packages/core/src/__tests__/manager/manager-notifications.test.ts` - notification tests
243+
244+
**Implementation:**
245+
246+
- [ ] Create GitHub Project draft issues by default in `manager.targetColumn`.
247+
- [ ] Draft issue bodies must follow `templates/prd-creator.md` structure enough to be executable after human approval.
248+
- [ ] Check existing board issue titles/labels and memory fingerprints before creating drafts.
249+
- [ ] Send `manager_blocked` only for findings requiring human credentials, external setup, destructive approval, or unclear priority.
250+
- [ ] Send `manager_weekly_summary` only when `weeklySummaryEnabled` is true and the configured weekday is due.
251+
252+
**Tests Required:**
253+
254+
| Test File | Test Name | Assertion |
255+
|-----------|-----------|-----------|
256+
| `packages/core/src/__tests__/manager/manager-board.test.ts` | `creates board draft for new finding` | provider receives `createIssue` with `column: 'Draft'` |
257+
| `packages/core/src/__tests__/manager/manager-board.test.ts` | `skips existing board issue` | duplicate title/fingerprint creates no issue |
258+
| `packages/core/src/__tests__/manager/manager-notifications.test.ts` | `notifies blockers only` | ordinary drafts do not emit `manager_blocked` |
259+
| `packages/core/src/__tests__/manager/manager-notifications.test.ts` | `sends weekly summary once` | second same-week run emits no summary |
260+
261+
**User Verification:**
262+
263+
- Action: Configure a Telegram webhook for Manager events and run Manager against a blocker fixture.
264+
- Expected: A blocker notification is sent; normal drafts do not spam.
265+
266+
#### Phase 5: Documentation and Verification - Manager is documented and stable
267+
268+
**Files (max 5):**
269+
270+
- `docs/reference/configuration.md` - document Manager config
271+
- `docs/reference/commands.md` - document `night-watch manager`
272+
- `docs/reference/features.md` - document Manager behavior
273+
- `docs/integrations/integrations.md` - document Manager notification events
274+
- `docs/guides/troubleshooting.md` - document Manager logs/memory
275+
276+
**Implementation:**
277+
278+
- [ ] Document Manager as a roadmap oversight agent, not a replacement for executor/slicer.
279+
- [ ] Document draft-only default and configurable output mode.
280+
- [ ] Document `.night-watch/manager/memory.md` and `.night-watch/manager/docs`.
281+
- [ ] Document notification subscription events.
282+
- [ ] Run focused tests and `yarn verify`.
283+
284+
**Tests Required:**
285+
286+
| Test File | Test Name | Assertion |
287+
|-----------|-----------|-----------|
288+
| Existing docs checks if present | docs references are valid | commands/config docs mention Manager |
289+
| Full verification | `yarn verify` | exits zero |
290+
291+
**User Verification:**
292+
293+
- Action: Read `night-watch manager --help` and reference docs.
294+
- Expected: User can configure, run, pause, and interpret Manager output.
295+
296+
---
297+
298+
## 5. Acceptance Criteria
299+
300+
- [ ] `docs/prds/manager-agent.md` exists and follows the PRD template.
301+
- [ ] `manager` is a valid Night Watch job type.
302+
- [ ] `night-watch manager --dry-run --json` works without creating board issues or files.
303+
- [ ] Manager uses `roadmapScanner.roadmapPath` and defaults to `ROADMAP.md`.
304+
- [ ] Manager default output is GitHub Project draft issues.
305+
- [ ] Manager memory defaults to `.night-watch/manager/memory.md`.
306+
- [ ] Manager direct docs are limited to `.night-watch/manager/docs`.
307+
- [ ] Manager dedupes using memory fingerprints and board state.
308+
- [ ] Manager sends blocker notifications and weekly summaries through existing notification webhooks.
309+
- [ ] `night-watch agent status --json`, job pause/resume, queue, cron install, and logs recognize Manager.
310+
- [ ] Focused tests and `yarn verify` pass.

‎docs/reference/commands.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,27 @@ night-watch audit --timeout 3600 # Override max runtime (1 hour)
122122

123123
---
124124

125+
## `night-watch manager`
126+
127+
Run the Manager agent. Manager compares the roadmap, PRDs, board state, job status, logs, and documentation coverage, then reports or drafts follow-up work according to `manager.outputMode`.
128+
129+
```bash
130+
night-watch manager # Run Manager now
131+
night-watch manager --dry-run # Analyze without writing memory/docs/issues
132+
night-watch manager --dry-run --json # Machine-readable dry-run result
133+
night-watch manager --provider codex # Override provider
134+
night-watch manager --timeout 1800 # Override max runtime
135+
```
136+
137+
**Behavior:**
138+
139+
- Uses `roadmapScanner.roadmapPath` as the roadmap source.
140+
- Writes Manager memory under `manager.memoryPath` and generated docs under `manager.docsDir`.
141+
- Creates board draft issues when `manager.outputMode` is `board-draft` and the board provider is configured.
142+
- Logs cron output to `logs/manager.log`.
143+
144+
---
145+
125146
## `night-watch install`
126147

127148
Install crontab entries for automated execution.
@@ -131,6 +152,7 @@ night-watch install # Install with default schedules
131152
night-watch install --schedule "0 * * * *" # Custom executor schedule
132153
night-watch install --reviewer-schedule "0 */2 * * *" # Custom reviewer schedule
133154
night-watch install --no-reviewer # Skip reviewer cron
155+
night-watch install --no-manager # Skip manager cron
134156
```
135157

136158
**Default Schedules:**

0 commit comments

Comments
 (0)