ai-agentmanager 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/NOTICE +4 -0
- package/README.md +767 -2
- package/SECURITY.md +44 -0
- package/bin/agentmgr-hub.js +16 -0
- package/bin/agentmgr.js +4 -0
- package/docs/architecture.md +67 -0
- package/docs/distributed.md +147 -0
- package/docs/engines.md +177 -0
- package/docs/images/agents.jpg +0 -0
- package/docs/images/conflict-radar.jpg +0 -0
- package/docs/plugins.md +81 -0
- package/package.json +56 -4
- package/public/app.js +3083 -0
- package/public/hub/hub.css +230 -0
- package/public/hub/hub.js +766 -0
- package/public/hub/index.html +146 -0
- package/public/hub/term.js +147 -0
- package/public/index.html +342 -0
- package/public/share.html +34 -0
- package/public/share.js +41 -0
- package/public/style.css +541 -0
- package/public/touchscroll.js +73 -0
- package/public/transport.js +78 -0
- package/scripts/build-release.sh +58 -0
- package/scripts/fix-pty.js +15 -0
- package/src/backlog.js +413 -0
- package/src/brief.js +512 -0
- package/src/cli.js +1447 -0
- package/src/client.js +49 -0
- package/src/config.js +109 -0
- package/src/conflicts.js +105 -0
- package/src/engines/antigravity.js +296 -0
- package/src/engines/claude.js +98 -0
- package/src/engines/codex.js +331 -0
- package/src/engines/index.js +37 -0
- package/src/fleet.js +176 -0
- package/src/git.js +340 -0
- package/src/hub.js +857 -0
- package/src/hubactions.js +107 -0
- package/src/hubbacklog.js +373 -0
- package/src/hublink.js +437 -0
- package/src/inbox.js +94 -0
- package/src/judge.js +278 -0
- package/src/livebrowser.js +637 -0
- package/src/manager.js +2554 -0
- package/src/notify.js +284 -0
- package/src/plugins.js +119 -0
- package/src/preview.js +334 -0
- package/src/races.js +192 -0
- package/src/remote.js +284 -0
- package/src/server.js +759 -0
- package/src/service.js +150 -0
- package/src/sessions.js +160 -0
- package/src/store.js +104 -0
- package/src/stuck.js +160 -0
- package/src/tracker.js +311 -0
- package/src/trust.js +44 -0
package/src/brief.js
ADDED
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
// The agent's living brief: Problem, Solution, Diagram and Checks, written by
|
|
2
|
+
// Claude to a Markdown file outside the repository and shown in the UI.
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { paths } from './config.js';
|
|
6
|
+
|
|
7
|
+
export const BRIEF_FILE = 'BRIEF.md';
|
|
8
|
+
|
|
9
|
+
export function briefDir(agentId) {
|
|
10
|
+
return path.join(paths.briefs, agentId);
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export function briefPath(agentId) {
|
|
14
|
+
return path.join(briefDir(agentId), BRIEF_FILE);
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export const briefPrompt = (file) =>
|
|
18
|
+
`Keep a short, living brief of this task in ${file} (Markdown). Agent Manager shows it to the user ` +
|
|
19
|
+
'next to your terminal. Start it with one status line, then use exactly these four sections:\n' +
|
|
20
|
+
'Status: planning | working | blocked | done\n' +
|
|
21
|
+
'Set "done" only when the task is complete and its checks pass; set "blocked" when you need the user.\n' +
|
|
22
|
+
'## Problem\nWhat is wrong or what is needed, and why (2-5 sentences).\n' +
|
|
23
|
+
'## Solution\nThe approach and the key changes (files, components). Keep it current as the plan evolves.\n' +
|
|
24
|
+
'## Diagram\nOne ```mermaid code block showing the flow, sequence or architecture of the solution. ' +
|
|
25
|
+
'Keep it small and valid Mermaid syntax.\n' +
|
|
26
|
+
'## Checks\nA task list of how the work is verified, one line per check with the command or evidence: ' +
|
|
27
|
+
'"- [ ]" pending, "- [~]" running, "- [x]" passed, "- [!]" failed.\n' +
|
|
28
|
+
'## Results\nThe end result so far. First line "Outcome: in progress | partial | done | blocked". Then bullets:\n' +
|
|
29
|
+
'"- Delivered: ..." for each concrete result (PR or commit links, files, documents, answers), and\n' +
|
|
30
|
+
'"- Blocked by: ... (needs: who or what)" for anything blocking progress. Keep it current; it is what reviewers read first.\n' +
|
|
31
|
+
'Add a fifth section only when the task links Jira issues (or other tickets):\n' +
|
|
32
|
+
'## References\nLook each linked issue up (use your Jira / Atlassian tools if you have them) and list the ' +
|
|
33
|
+
'documents its fields point to, above all its PRD and Tech Spec fields, plus design docs or Confluence pages. ' +
|
|
34
|
+
'One line per document: "- **PRD**: [title](url) — the 1-2 points that matter for this task". If a field is ' +
|
|
35
|
+
'empty, say so ("- **Tech Spec**: none on IDEA-872"). If you cannot reach Jira, say that in one line. ' +
|
|
36
|
+
'Read the PRD and Tech Spec before settling the Solution.\n' +
|
|
37
|
+
'Write it as soon as you understand the task, then update it when the plan changes and whenever a check ' +
|
|
38
|
+
'runs. Keep it concise. The file is outside the repository: never copy it into the repo or commit it.';
|
|
39
|
+
|
|
40
|
+
const SECTION_ALIASES = {
|
|
41
|
+
problem: ['problem', 'problem statement', 'issue', 'context'],
|
|
42
|
+
solution: ['solution', 'approach', 'proposed solution', 'plan'],
|
|
43
|
+
diagram: ['diagram', 'design', 'flow', 'architecture', 'design/flow/architecture', 'design / flow / architecture'],
|
|
44
|
+
checks: ['checks', 'verification', 'tests', 'testing', 'validation'],
|
|
45
|
+
references: ['references', 'links', 'documents', 'docs', 'specs', 'prd / tech spec', 'prd/tech spec'],
|
|
46
|
+
results: ['results', 'result', 'outcome', 'status and results', 'results and status'],
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
// "- **PRD**: [Title](https://...) — highlight", tolerating ":" / "-" / "–" separators and bare URLs.
|
|
50
|
+
const REF_LINE =
|
|
51
|
+
/^\s*[-*]\s+(?:\*\*|__)?([^*_:\[\]]+?)(?:\*\*|__)?\s*:\s*(?:\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)|<?(https?:\/\/[^\s>]+)>?)?\s*(?:[—–-]\s*)?(.*)$/;
|
|
52
|
+
|
|
53
|
+
export function parseReference(line) {
|
|
54
|
+
const m = line.match(REF_LINE);
|
|
55
|
+
if (!m) return null;
|
|
56
|
+
const [, label, title, url1, url2, rest] = m;
|
|
57
|
+
const url = url1 ?? url2 ?? null;
|
|
58
|
+
const highlight = rest.trim();
|
|
59
|
+
// A key spec document (PRD / tech spec / design) is highlighted in the UI.
|
|
60
|
+
const key = /\b(prd|product requirements?|tech(nical)? spec|design (doc|spec)|architecture)\b/i.test(label);
|
|
61
|
+
return { label: label.trim(), title: title ?? null, url, highlight, key, missing: !url && /^none\b|^n\/a\b|^not (set|filled)/i.test(highlight) };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function sectionKey(heading) {
|
|
65
|
+
const h = heading.toLowerCase().replace(/[`*_:]/g, '').trim();
|
|
66
|
+
for (const [key, names] of Object.entries(SECTION_ALIASES)) {
|
|
67
|
+
if (names.includes(h) || names.some((n) => h.startsWith(`${n} `))) return key;
|
|
68
|
+
}
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const CHECK_STATES = { ' ': 'pending', '~': 'running', x: 'passed', X: 'passed', '!': 'failed' };
|
|
73
|
+
|
|
74
|
+
/** Parse the brief Markdown into its four sections. Unknown sections are ignored. */
|
|
75
|
+
export function parseBrief(markdown) {
|
|
76
|
+
const out = { status: null, problem: '', solution: '', diagram: null, diagramNotes: '', checks: [], references: [], results: null };
|
|
77
|
+
const st = markdown.split(/^##\s/m)[0].match(/^\s*\**status\**\s*:\s*\**\s*(planning|working|blocked|done)\b/im);
|
|
78
|
+
if (st) out.status = st[1].toLowerCase();
|
|
79
|
+
const parts = markdown.split(/^##\s+(.+?)\s*#*\s*$/m);
|
|
80
|
+
for (let i = 1; i < parts.length; i += 2) {
|
|
81
|
+
const key = sectionKey(parts[i]);
|
|
82
|
+
const body = (parts[i + 1] ?? '').trim();
|
|
83
|
+
if (!key) continue;
|
|
84
|
+
if (key === 'diagram') {
|
|
85
|
+
const m = body.match(/```mermaid\s*\n([\s\S]*?)```/);
|
|
86
|
+
out.diagram = m ? m[1].trim() : null;
|
|
87
|
+
out.diagramNotes = (m ? body.replace(m[0], '') : body).trim();
|
|
88
|
+
} else if (key === 'results') {
|
|
89
|
+
const outcome = body.match(/^\s*\**outcome\**\s*:\s*\**\s*(in progress|in-progress|partial|done|blocked)\b/im)?.[1];
|
|
90
|
+
const lines = body.split('\n');
|
|
91
|
+
const pick = (re) => lines.map((l) => l.match(re)?.[1]?.trim()).filter(Boolean);
|
|
92
|
+
out.results = {
|
|
93
|
+
outcome: outcome ? outcome.toLowerCase().replace('-', ' ') : null,
|
|
94
|
+
// Tolerates "Delivered:", "**Delivered:**" and "**Delivered**:".
|
|
95
|
+
delivered: pick(/^\s*[-*]\s+\**\s*delivered\s*\**\s*:\s*\**\s*(.+)$/i),
|
|
96
|
+
blockers: pick(/^\s*[-*]\s+\**\s*blocked by\s*\**\s*:\s*\**\s*(.+)$/i),
|
|
97
|
+
notes: lines
|
|
98
|
+
.filter((l) => !/^\s*\**\s*outcome\s*\**\s*:/i.test(l) && !/^\s*[-*]\s+\**\s*(delivered|blocked by)\s*\**\s*:/i.test(l))
|
|
99
|
+
.join('\n')
|
|
100
|
+
.trim(),
|
|
101
|
+
};
|
|
102
|
+
} else if (key === 'references') {
|
|
103
|
+
for (const line of body.split('\n')) {
|
|
104
|
+
const ref = parseReference(line);
|
|
105
|
+
if (ref) out.references.push(ref);
|
|
106
|
+
}
|
|
107
|
+
} else if (key === 'checks') {
|
|
108
|
+
for (const line of body.split('\n')) {
|
|
109
|
+
const m = line.match(/^\s*[-*]\s+\[([ xX!~])\]\s+(.+?)\s*$/);
|
|
110
|
+
if (m) out.checks.push({ state: CHECK_STATES[m[1]], text: m[2] });
|
|
111
|
+
}
|
|
112
|
+
} else {
|
|
113
|
+
out[key] = body;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
const count = (s) => out.checks.filter((c) => c.state === s).length;
|
|
117
|
+
out.summary = {
|
|
118
|
+
passed: count('passed'),
|
|
119
|
+
failed: count('failed'),
|
|
120
|
+
running: count('running'),
|
|
121
|
+
pending: count('pending'),
|
|
122
|
+
total: out.checks.length,
|
|
123
|
+
};
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Re-read the brief if it changed since `prev` (by mtime). Returns the new brief, or null if unchanged. */
|
|
128
|
+
export function loadBrief(agentId, prev) {
|
|
129
|
+
let st;
|
|
130
|
+
try {
|
|
131
|
+
st = fs.statSync(briefPath(agentId));
|
|
132
|
+
} catch {
|
|
133
|
+
return null;
|
|
134
|
+
}
|
|
135
|
+
if (prev && prev.mtimeMs === st.mtimeMs) return null;
|
|
136
|
+
const markdown = fs.readFileSync(briefPath(agentId), 'utf8');
|
|
137
|
+
return { ...parseBrief(markdown), mtimeMs: st.mtimeMs, updatedAt: st.mtime.toISOString() };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Ask the agent to learn and follow the project's and user's own rules before working.
|
|
142
|
+
* Claude Code gets the full list of its own files; other engines get their rules files
|
|
143
|
+
* (`rulesFiles` on the adapter) and a plain warning against turning this into research,
|
|
144
|
+
* which a smaller model otherwise did (it searched the whole disk for Claude's settings).
|
|
145
|
+
*/
|
|
146
|
+
export const conventionsPrompt = ({ withBrief, rulesFiles = null }) =>
|
|
147
|
+
(rulesFiles
|
|
148
|
+
? 'Before you change anything, take a quick look at the rules this project has set up, and follow them throughout:\n' +
|
|
149
|
+
`- Read ${rulesFiles.join(', ')} and any CONTRIBUTING guide in the repository root and the folders you work in, if they exist.\n` +
|
|
150
|
+
'- If the repository has SKILL.md files under .claude/skills/, read the ones relevant to this task.\n' +
|
|
151
|
+
"This is a quick check, not an investigation: don't search outside the repository, and if there's nothing, go straight to the task." +
|
|
152
|
+
(withBrief ? '\nRecord what applies as the first item under Checks in the brief, for example: "- [x] Reviewed conventions: AGENTS.md".' : '')
|
|
153
|
+
: conventionsClaude({ withBrief }));
|
|
154
|
+
|
|
155
|
+
const conventionsClaude = ({ withBrief }) =>
|
|
156
|
+
'Before you change anything, learn the rules this project and user have set up, and follow them throughout:\n' +
|
|
157
|
+
'- Read the CLAUDE.md and AGENTS.md files (repository root, the folders you work in, and ~/.claude/CLAUDE.md) ' +
|
|
158
|
+
'and any CONTRIBUTING guide.\n' +
|
|
159
|
+
'- Review the available skills: the ones listed to you, plus SKILL.md files under .claude/skills/ in the ' +
|
|
160
|
+
'repository and ~/.claude/skills/. Read the ones relevant to this task and use them rather than improvising.\n' +
|
|
161
|
+
'- Review hooks and permissions in .claude/settings.json, .claude/settings.local.json and ~/.claude/settings.json, ' +
|
|
162
|
+
'so you know what runs automatically (formatters, linters, checks) and work with it, not around it.\n' +
|
|
163
|
+
'- Check .claude/commands/ and .claude/agents/ for project workflows.\n' +
|
|
164
|
+
'If the repository is not available yet, review the user-level ones now and the repository ones as soon as it is.' +
|
|
165
|
+
(withBrief
|
|
166
|
+
? '\nRecord what applies as the first item under Checks in the brief, for example: ' +
|
|
167
|
+
'"- [x] Reviewed conventions: skills go-testing, release-notes; hooks: gofmt on edit".'
|
|
168
|
+
: '');
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* Prompt for a one-off, tool-less "explain what this agent is doing" call, built
|
|
172
|
+
* from the agent's live context: its conversation and actions, repository
|
|
173
|
+
* changes, status and brief.
|
|
174
|
+
*/
|
|
175
|
+
export function explainPrompt({ intent, status, digest, repo, briefMarkdown }) {
|
|
176
|
+
return [
|
|
177
|
+
"You are briefing a busy engineer on an AI coding agent's work so far. Use the context below (the agent's",
|
|
178
|
+
'actual conversation, actions and repository changes) and explain in plain language what it is doing.',
|
|
179
|
+
'',
|
|
180
|
+
'Write Markdown with exactly these sections:',
|
|
181
|
+
'### The ask',
|
|
182
|
+
'What the user asked for, in one or two sentences, including any later change of direction.',
|
|
183
|
+
'### Where it stands',
|
|
184
|
+
'One or two lines: the phase (planning, investigating, implementing, testing, done, blocked), what it is',
|
|
185
|
+
'doing right now, and whether it is waiting for the user and on what.',
|
|
186
|
+
'### Planned work',
|
|
187
|
+
'The plan as a short checklist, each step marked ✅ done, 🔄 in progress or ⏳ next, based on what the agent',
|
|
188
|
+
'said it would do and what it actually did.',
|
|
189
|
+
'### Solution',
|
|
190
|
+
'The approach and why, and the concrete changes so far: files or components touched, commits, PRs.',
|
|
191
|
+
'### Conclusions so far',
|
|
192
|
+
'Findings, decisions, answers and results (including test results). Write "None yet." if nothing is settled.',
|
|
193
|
+
'### Needs from you',
|
|
194
|
+
'Questions or decisions the agent is waiting on, plus risks and blockers. Write "Nothing right now." if none.',
|
|
195
|
+
'',
|
|
196
|
+
'Rules: rely only on the context. Clearly separate what was done from what was only planned. If the',
|
|
197
|
+
'context is thin or unclear, say so instead of guessing. No preamble. Keep it under about 400 words.',
|
|
198
|
+
'',
|
|
199
|
+
'<agent_status>',
|
|
200
|
+
status,
|
|
201
|
+
'</agent_status>',
|
|
202
|
+
'<intent>',
|
|
203
|
+
intent || '(none)',
|
|
204
|
+
'</intent>',
|
|
205
|
+
'<conversation>',
|
|
206
|
+
digest || '(no conversation recorded yet)',
|
|
207
|
+
'</conversation>',
|
|
208
|
+
'<repository>',
|
|
209
|
+
repo || '(no repository changes recorded)',
|
|
210
|
+
'</repository>',
|
|
211
|
+
'<brief>',
|
|
212
|
+
briefMarkdown || '(the agent has not written a brief yet)',
|
|
213
|
+
'</brief>',
|
|
214
|
+
].join('\n');
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** Prompt for "Insights": Why / What / How / Now, three tidy points each. */
|
|
218
|
+
export function insightsPrompt({ intent, status, digest, repo, briefMarkdown }) {
|
|
219
|
+
return [
|
|
220
|
+
"Give a human the four insights that matter about an AI coding agent's work, from its ask and live",
|
|
221
|
+
'context below. Write Markdown with exactly these four sections, in this order:',
|
|
222
|
+
'### Why',
|
|
223
|
+
'Why this work matters: the motivation, the user or business need, or the root cause of the problem.',
|
|
224
|
+
'### What',
|
|
225
|
+
'What is being done or delivered: the scope and the outcome.',
|
|
226
|
+
'### How',
|
|
227
|
+
'How it is being done: the approach, the key mechanism or the main changes.',
|
|
228
|
+
'### Now',
|
|
229
|
+
'Where it stands now and the next step, including anything waiting on the user.',
|
|
230
|
+
'',
|
|
231
|
+
'Style rules, strictly:',
|
|
232
|
+
'- Each section has 1 to 3 bullets, never more. Fewer is better when it is enough.',
|
|
233
|
+
'- Each bullet is one short, concrete line of at most 12 words: easy to remember and repeat.',
|
|
234
|
+
'- Lead with the key word; no filler, no hedging, no nested bullets, no preamble or closing text.',
|
|
235
|
+
'- Use only the context. If something is not known yet, write "Unclear yet" as the bullet.',
|
|
236
|
+
'',
|
|
237
|
+
'<agent_status>',
|
|
238
|
+
status,
|
|
239
|
+
'</agent_status>',
|
|
240
|
+
'<intent>',
|
|
241
|
+
intent || '(none)',
|
|
242
|
+
'</intent>',
|
|
243
|
+
'<conversation>',
|
|
244
|
+
digest || '(no conversation recorded yet)',
|
|
245
|
+
'</conversation>',
|
|
246
|
+
'<repository>',
|
|
247
|
+
repo || '(no repository changes recorded)',
|
|
248
|
+
'</repository>',
|
|
249
|
+
'<brief>',
|
|
250
|
+
briefMarkdown || '(the agent has not written a brief yet)',
|
|
251
|
+
'</brief>',
|
|
252
|
+
].join('\n');
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** Stakeholder documents built from an agent's live context. */
|
|
256
|
+
export const DOC_KINDS = {
|
|
257
|
+
analysis: {
|
|
258
|
+
title: 'Analysis',
|
|
259
|
+
sections: [
|
|
260
|
+
['Summary', 'Two or three sentences a stakeholder can read on their own.'],
|
|
261
|
+
['Context', 'The background and why this came up (link the ticket or idea if there is one).'],
|
|
262
|
+
['Findings', 'What was learned from the code, docs and discussion, as specific facts.'],
|
|
263
|
+
['Root cause / core problem', 'The real problem or constraint behind the request.'],
|
|
264
|
+
['Constraints and assumptions', 'Limits, dependencies and assumptions that shape any solution.'],
|
|
265
|
+
['Options considered', 'The options, each with pros and cons, and which one is favoured and why.'],
|
|
266
|
+
['Open questions', 'What still needs an answer, and from whom.'],
|
|
267
|
+
],
|
|
268
|
+
diagram: 'Include a diagram only if it clarifies the problem.',
|
|
269
|
+
},
|
|
270
|
+
design: {
|
|
271
|
+
title: 'Design',
|
|
272
|
+
sections: [
|
|
273
|
+
['Summary', 'What is being built and the key design decision, in two or three sentences.'],
|
|
274
|
+
['Goals and non-goals', 'Bullets.'],
|
|
275
|
+
['Architecture', 'Components and how they interact, with one ```mermaid flowchart or graph of the architecture.'],
|
|
276
|
+
['Components and changes', 'Each component or module touched: its responsibility and the change.'],
|
|
277
|
+
['Interfaces and data', 'APIs, configuration, schemas or data flows that change.'],
|
|
278
|
+
['Trade-offs and alternatives', 'What was chosen over what, and why.'],
|
|
279
|
+
['Risks and mitigations', 'Bullets.'],
|
|
280
|
+
['Testing and rollout', 'How it is verified and released (flags, phases, rollback).'],
|
|
281
|
+
],
|
|
282
|
+
diagram: 'Include exactly one architecture diagram.',
|
|
283
|
+
},
|
|
284
|
+
flow: {
|
|
285
|
+
title: 'Flow',
|
|
286
|
+
sections: [
|
|
287
|
+
['Summary', 'What the flow covers, in one or two sentences.'],
|
|
288
|
+
['End-to-end flow', 'A ```mermaid flowchart of the main path, then a numbered step-by-step walk-through.'],
|
|
289
|
+
['Key interactions', 'A ```mermaid sequenceDiagram of the most important interaction between components or services.'],
|
|
290
|
+
['Failure and edge cases', 'What happens when steps fail or inputs are unusual.'],
|
|
291
|
+
],
|
|
292
|
+
diagram: 'Use two diagrams: a flowchart and a sequenceDiagram.',
|
|
293
|
+
},
|
|
294
|
+
proposal: {
|
|
295
|
+
title: 'Proposal',
|
|
296
|
+
sections: [
|
|
297
|
+
['Summary', 'The recommendation in two or three sentences, written for a decision-maker.'],
|
|
298
|
+
['Problem', 'What is wrong or needed and why it matters now.'],
|
|
299
|
+
['Recommendation', 'The proposed approach and why it is the best option.'],
|
|
300
|
+
['Scope', 'In scope and out of scope.'],
|
|
301
|
+
['Plan', 'Phases or milestones with what each delivers.'],
|
|
302
|
+
['Effort and dependencies', 'Rough size, teams or systems involved, prerequisites.'],
|
|
303
|
+
['Risks', 'Main risks with mitigations.'],
|
|
304
|
+
['Decisions needed', 'The specific decisions or approvals requested from reviewers, as a list.'],
|
|
305
|
+
],
|
|
306
|
+
diagram: 'Include one small diagram if it helps the decision.',
|
|
307
|
+
},
|
|
308
|
+
};
|
|
309
|
+
|
|
310
|
+
export function docPrompt(kind, { intent, status, digest, repo, briefMarkdown, agentName }) {
|
|
311
|
+
const d = DOC_KINDS[kind];
|
|
312
|
+
return [
|
|
313
|
+
`Write a ${d.title} document about an AI coding agent's work, for stakeholders who will review it.`,
|
|
314
|
+
'Base it only on the context below: the original ask, the agent conversation and actions, repository changes',
|
|
315
|
+
'and its brief. Write for reviewers, not for the agent: no mention of the agent, its tools or this prompt.',
|
|
316
|
+
'',
|
|
317
|
+
`Start with a level-1 title: "# ${d.title}: <short name of the work>". Then these sections, as level-2 headings, in order:`,
|
|
318
|
+
...d.sections.map(([h, what]) => `## ${h}\n${what}`),
|
|
319
|
+
'',
|
|
320
|
+
'Rules:',
|
|
321
|
+
`- ${d.diagram} Diagrams go in \`\`\`mermaid code blocks with valid Mermaid syntax; keep node labels short and quote labels that contain punctuation.`,
|
|
322
|
+
'- Be specific: name the real files, components, tickets and documents from the context.',
|
|
323
|
+
'- Separate facts from proposals. Where the context does not say, write "To be confirmed" rather than guessing.',
|
|
324
|
+
'- Clear, neutral, professional prose; bullets where they help. Roughly 400-900 words.',
|
|
325
|
+
'- Output only the Markdown document.',
|
|
326
|
+
'',
|
|
327
|
+
'<agent_status>',
|
|
328
|
+
status,
|
|
329
|
+
'</agent_status>',
|
|
330
|
+
'<intent>',
|
|
331
|
+
intent || '(none)',
|
|
332
|
+
'</intent>',
|
|
333
|
+
'<conversation>',
|
|
334
|
+
digest || '(no conversation recorded yet)',
|
|
335
|
+
'</conversation>',
|
|
336
|
+
'<repository>',
|
|
337
|
+
repo || '(no repository changes recorded)',
|
|
338
|
+
'</repository>',
|
|
339
|
+
'<brief>',
|
|
340
|
+
briefMarkdown || '(no brief yet)',
|
|
341
|
+
'</brief>',
|
|
342
|
+
].join('\n');
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
// ------------------------------------------------------------------ Human vs AI
|
|
346
|
+
|
|
347
|
+
export const contextBlock = ({ intent, status, digest, repo, briefMarkdown }) => [
|
|
348
|
+
'<agent_status>',
|
|
349
|
+
status,
|
|
350
|
+
'</agent_status>',
|
|
351
|
+
'<intent>',
|
|
352
|
+
intent || '(none)',
|
|
353
|
+
'</intent>',
|
|
354
|
+
'<conversation>',
|
|
355
|
+
digest || '(no conversation recorded yet)',
|
|
356
|
+
'</conversation>',
|
|
357
|
+
'<repository>',
|
|
358
|
+
repo || '(no repository changes recorded)',
|
|
359
|
+
'</repository>',
|
|
360
|
+
'<brief>',
|
|
361
|
+
briefMarkdown || '(no brief yet)',
|
|
362
|
+
'</brief>',
|
|
363
|
+
];
|
|
364
|
+
|
|
365
|
+
/**
|
|
366
|
+
* Human vs AI: split the open questions about an agent's work into the few that need a
|
|
367
|
+
* person's judgment and the ones a model can answer by reasoning over the evidence, and
|
|
368
|
+
* answer those. JSON, so the page can lay it out and collect the person's answers.
|
|
369
|
+
*/
|
|
370
|
+
export function humanAiPrompt(ctx) {
|
|
371
|
+
return [
|
|
372
|
+
"You help a person supervise an AI coding agent. From the context below, work out the open questions about this work and split them by who should answer them.",
|
|
373
|
+
'',
|
|
374
|
+
'1. "human": the 5 most important questions only a person should answer, most important first. They need judgment the',
|
|
375
|
+
' context cannot supply: intent and priorities, product or user knowledge, risk appetite, trade-offs between goods,',
|
|
376
|
+
' ethics, policy or accountability. For each give:',
|
|
377
|
+
' - "question": one sentence.',
|
|
378
|
+
' - "why_human": why a model should not decide this, in one short sentence.',
|
|
379
|
+
' - "stakes": what goes wrong if it is answered badly or not at all, in one short sentence.',
|
|
380
|
+
' - "options": 2 or 3 short, concrete options.',
|
|
381
|
+
' - "lean": what the context already suggests, in one short sentence, or null. Never decide for them.',
|
|
382
|
+
'2. "ai": up to 5 questions a model can answer by reasoning over the context and evaluating the work: correctness,',
|
|
383
|
+
' edge cases, consistency with the ask, test coverage, risks in the changes, what is left to do. Answer each:',
|
|
384
|
+
' - "question": one sentence.',
|
|
385
|
+
' - "answer": 1 to 3 sentences.',
|
|
386
|
+
' - "confidence": "high", "medium" or "low".',
|
|
387
|
+
' - "evidence": the files, commits, commands, test results or quotes from the context it rests on.',
|
|
388
|
+
' - "check": how a person could verify it in a minute or two.',
|
|
389
|
+
'',
|
|
390
|
+
'Rules:',
|
|
391
|
+
'- Specific to this work: name the real files, tickets and decisions. No generic questions that fit any project.',
|
|
392
|
+
'- Use only the context. Where it does not say, answer that and use low confidence; do not guess.',
|
|
393
|
+
'- Do not put a question in "ai" if answering it means choosing what the person wants.',
|
|
394
|
+
'- Output only one JSON object, no code fence and no other text:',
|
|
395
|
+
' {"title": "<short name of the work>", "human": [...], "ai": [...]}',
|
|
396
|
+
'',
|
|
397
|
+
...contextBlock(ctx),
|
|
398
|
+
].join('\n');
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/** A second model double-checks the split and every AI answer, against the same context. */
|
|
402
|
+
export function critiquePrompt(ctx, draft) {
|
|
403
|
+
return [
|
|
404
|
+
'You are an independent reviewer double-checking another model. It looked at an AI coding agent\'s work (context below)',
|
|
405
|
+
'and split the open questions into ones only a person should answer ("human") and ones it answered itself ("ai").',
|
|
406
|
+
'Check its work against the context, sceptically. Do not trust its evidence without finding it in the context.',
|
|
407
|
+
'',
|
|
408
|
+
'Return:',
|
|
409
|
+
'- "ai": one entry per AI answer, in the same order: {"verdict": "agree" | "partly" | "disagree", "note": "..."}.',
|
|
410
|
+
' The note says why in one or two sentences; when you disagree or partly agree, give the corrected answer.',
|
|
411
|
+
'- "human": one entry per human question, in the same order: {"verdict": "keep" | "ai" | "reword", "note": "..."}.',
|
|
412
|
+
' "ai" means a model could answer it from the context (say what the answer is); "reword" means it is unclear,',
|
|
413
|
+
' leading or not the real decision (give a better wording).',
|
|
414
|
+
'- "missing": up to 3 important questions both lists missed: {"question": "...", "for": "human" | "ai", "why": "..."}.',
|
|
415
|
+
'- "summary": one or two sentences on how far the person can rely on the AI answers.',
|
|
416
|
+
'',
|
|
417
|
+
'Output only one JSON object with those four keys, no code fence and no other text.',
|
|
418
|
+
'',
|
|
419
|
+
'<review>',
|
|
420
|
+
JSON.stringify(draft, null, 2),
|
|
421
|
+
'</review>',
|
|
422
|
+
...contextBlock(ctx),
|
|
423
|
+
].join('\n');
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/** The first JSON object in a model's reply (tolerates a code fence or a sentence around it). */
|
|
427
|
+
export function parseJsonReply(text) {
|
|
428
|
+
const s = String(text ?? '');
|
|
429
|
+
const start = s.indexOf('{');
|
|
430
|
+
const end = s.lastIndexOf('}');
|
|
431
|
+
if (start < 0 || end <= start) throw new Error('The reply had no JSON in it');
|
|
432
|
+
return JSON.parse(s.slice(start, end + 1));
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
/** Markdown version, for Copy / Download / Print and the CLI. */
|
|
436
|
+
export function humanAiMarkdown({ data, critique, answers = {} }) {
|
|
437
|
+
const out = [`# Human vs AI: ${data.title ?? 'review'}`, ''];
|
|
438
|
+
const c = critique?.data;
|
|
439
|
+
out.push('## For you to decide', '');
|
|
440
|
+
(data.human ?? []).forEach((q, i) => {
|
|
441
|
+
out.push(`### ${i + 1}. ${q.question}`, '');
|
|
442
|
+
if (q.why_human) out.push(`- **Why you:** ${q.why_human}`);
|
|
443
|
+
if (q.stakes) out.push(`- **Stakes:** ${q.stakes}`);
|
|
444
|
+
if (q.options?.length) out.push(`- **Options:** ${q.options.join(' · ')}`);
|
|
445
|
+
if (q.lean) out.push(`- **The work so far suggests:** ${q.lean}`);
|
|
446
|
+
if (c?.human?.[i]) out.push(`- **Second opinion (${critique.label}):** ${c.human[i].verdict} — ${c.human[i].note}`);
|
|
447
|
+
out.push(`- **Your answer:** ${answers[i]?.trim() || '_not answered yet_'}`, '');
|
|
448
|
+
});
|
|
449
|
+
out.push('## Answered by AI', '');
|
|
450
|
+
(data.ai ?? []).forEach((q, i) => {
|
|
451
|
+
out.push(`### ${i + 1}. ${q.question}`, '', q.answer, '');
|
|
452
|
+
out.push(`- **Confidence:** ${q.confidence}`);
|
|
453
|
+
if (q.evidence) out.push(`- **Evidence:** ${Array.isArray(q.evidence) ? q.evidence.join('; ') : q.evidence}`);
|
|
454
|
+
if (q.check) out.push(`- **How to check:** ${q.check}`);
|
|
455
|
+
if (c?.ai?.[i]) out.push(`- **Second opinion (${critique.label}):** ${c.ai[i].verdict} — ${c.ai[i].note}`);
|
|
456
|
+
out.push('');
|
|
457
|
+
});
|
|
458
|
+
if (c) {
|
|
459
|
+
out.push(`## Second opinion: ${critique.label}`, '', c.summary ?? '', '');
|
|
460
|
+
for (const m of c.missing ?? []) out.push(`- **Missed (${m.for}):** ${m.question} — ${m.why}`);
|
|
461
|
+
} else if (critique?.error) {
|
|
462
|
+
out.push('## Second opinion', '', `Not available: ${critique.error}`);
|
|
463
|
+
}
|
|
464
|
+
return out.join('\n').trim();
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
/** What "Send my answers" tells the agent. */
|
|
468
|
+
export function humanAiMessage({ data, critique, answers = {} }) {
|
|
469
|
+
const lines = ['Answers to the open questions from my Human vs AI review:'];
|
|
470
|
+
(data.human ?? []).forEach((q, i) => {
|
|
471
|
+
const a = answers[i]?.trim();
|
|
472
|
+
if (a) lines.push(`${i + 1}. ${q.question}`, ` My answer: ${a}`);
|
|
473
|
+
});
|
|
474
|
+
const doubts = (data.ai ?? []).map((q, i) => [q, critique?.data?.ai?.[i]]).filter(([, v]) => v && v.verdict !== 'agree');
|
|
475
|
+
if (doubts.length) {
|
|
476
|
+
lines.push('', 'A second model doubted these conclusions about the work. Check them before relying on them:');
|
|
477
|
+
for (const [q, v] of doubts) lines.push(`- ${q.question} (${v.verdict}: ${v.note})`);
|
|
478
|
+
}
|
|
479
|
+
lines.push('', 'Take these into account and continue. If an answer changes the plan, say how before going further.');
|
|
480
|
+
return lines.join('\n');
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
// ------------------------------------------------------------------ plan review
|
|
484
|
+
|
|
485
|
+
export const PLAN_FILE = 'PLAN.md';
|
|
486
|
+
export const planPath = (agentId) => path.join(briefDir(agentId), PLAN_FILE);
|
|
487
|
+
|
|
488
|
+
/** For agents whose plan the user reviews first: plan, write it down, then wait. */
|
|
489
|
+
export const planReviewPrompt = (file) =>
|
|
490
|
+
'The user reviews your implementation plan before you implement anything. First investigate as much as you need ' +
|
|
491
|
+
`(reading code, docs and running read-only commands is fine), then write the plan to ${file} (Markdown) with these sections:\n` +
|
|
492
|
+
'# Plan: <short name>\n## Goal\n## Approach\n## Steps\nNumbered, each small enough to check.\n## Files to change\n' +
|
|
493
|
+
'## Tests and verification\n## Risks and open questions\n' +
|
|
494
|
+
'Then stop and wait. Until a message starting with "Plan approved" arrives, do not edit, create or delete files in ' +
|
|
495
|
+
'the repository, commit, or run commands that change anything. If a message starting with "Plan changes requested" ' +
|
|
496
|
+
`arrives, revise ${file} the same way and wait again. Once approved, implement the plan; if you have to depart from ` +
|
|
497
|
+
`it, update ${file} and say why.`;
|
|
498
|
+
|
|
499
|
+
export const planApprovedPrompt = (file) =>
|
|
500
|
+
`Your implementation plan in ${file} has been approved by the user. Implement it; if you have to depart from it, update the file and say why.`;
|
|
501
|
+
|
|
502
|
+
/** PLAN.md if it changed since `prev` (same shape as the brief: markdown + times). */
|
|
503
|
+
export function loadPlanFile(agentId, prev) {
|
|
504
|
+
let st;
|
|
505
|
+
try {
|
|
506
|
+
st = fs.statSync(planPath(agentId));
|
|
507
|
+
} catch {
|
|
508
|
+
return null;
|
|
509
|
+
}
|
|
510
|
+
if (prev && prev.mtimeMs === st.mtimeMs) return null;
|
|
511
|
+
return { markdown: fs.readFileSync(planPath(agentId), 'utf8').slice(0, 200_000), mtimeMs: st.mtimeMs, updatedAt: st.mtime.toISOString() };
|
|
512
|
+
}
|