@clickminded/coauthor-cli 0.0.23 → 0.0.25
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/README.md +4 -1
- package/dist/commands.js +201 -7
- package/dist/parser.js +13 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +10 -7
- package/skills/coauthor/references/brief-and-contract.md +6 -0
- package/skills/coauthor/references/publishing-and-export.md +1 -1
- package/skills/coauthor/references/troubleshooting.md +3 -0
- package/skills/cursor/coauthor-cli.mdc +20 -8
package/README.md
CHANGED
|
@@ -45,7 +45,9 @@ Updating the CLI updates installed skills automatically, unless you edited them;
|
|
|
45
45
|
A typical piece:
|
|
46
46
|
|
|
47
47
|
```sh
|
|
48
|
-
coauthor
|
|
48
|
+
coauthor profile list --json # pick the writer profile (voice, context, image style)
|
|
49
|
+
coauthor project create --title "Post title" --contract @brief.json --profile <profile id> --json
|
|
50
|
+
coauthor source add <id> notes.pdf --json # optional reference documents, before research
|
|
49
51
|
coauthor workflow run <id> --target contract --briefing-mode strict --json # CoAuthor questions the brief
|
|
50
52
|
coauthor outline generate <id> --json # review, then:
|
|
51
53
|
coauthor outline approve <id> --json
|
|
@@ -73,6 +75,7 @@ coauthor thread generate <id> --json
|
|
|
73
75
|
coauthor share <id> --json # public read-only link
|
|
74
76
|
coauthor export wordpress <id> --yes --slug <slug> --json # creates a WordPress draft post
|
|
75
77
|
coauthor credits <id> --json
|
|
78
|
+
coauthor integrations list --json # WordPress sites and X accounts
|
|
76
79
|
```
|
|
77
80
|
|
|
78
81
|
Run `coauthor --help` or `coauthor <command> --help` for every command and option. `--json` gives machine-readable output, `--wait` waits for long-running work, and JSON options such as `--data` and `--contract` accept `@file.json` (or `@-` for stdin).
|
package/dist/commands.js
CHANGED
|
@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
|
|
|
4
4
|
import { existsSync } from 'node:fs';
|
|
5
5
|
import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
|
|
6
6
|
import { homedir } from 'node:os';
|
|
7
|
-
import { dirname, join, resolve } from 'node:path';
|
|
7
|
+
import { basename, dirname, join, resolve } from 'node:path';
|
|
8
8
|
import { fileURLToPath } from 'node:url';
|
|
9
9
|
import { AgentHttpError, normalizeBaseUrl } from './client.js';
|
|
10
10
|
import { clearConfig, loadConfig, saveConfig } from './config.js';
|
|
@@ -29,6 +29,16 @@ export async function runCommand(input, context) {
|
|
|
29
29
|
return runArtifactCommand('research-plan', action, input, context.client);
|
|
30
30
|
if (scope === 'research')
|
|
31
31
|
return runResearchCommand(action, input, context);
|
|
32
|
+
if (scope === 'brief')
|
|
33
|
+
return runBriefCommand(action, input, context.client);
|
|
34
|
+
if (scope === 'log')
|
|
35
|
+
return runLogCommand(action, input, context.client);
|
|
36
|
+
if (scope === 'profile')
|
|
37
|
+
return runProfileCommand(action, input, context.client);
|
|
38
|
+
if (scope === 'integrations')
|
|
39
|
+
return { ok: true, data: await context.client.request({ path: 'integrations' }) };
|
|
40
|
+
if (scope === 'source')
|
|
41
|
+
return runSourceCommand(action, input, context.client);
|
|
32
42
|
if (scope === 'draft')
|
|
33
43
|
return runDraftCommand(action, input, context);
|
|
34
44
|
if (scope === 'workflow')
|
|
@@ -203,6 +213,9 @@ function inactiveAgentTokenCode(error) {
|
|
|
203
213
|
async function runProjectCommand(action, input, client) {
|
|
204
214
|
if (action === 'create') {
|
|
205
215
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, ['title', 'topic', 'audience']);
|
|
216
|
+
const profile = getString(input.values, 'profile');
|
|
217
|
+
if (profile)
|
|
218
|
+
body.profile_id = profile;
|
|
206
219
|
const rawContract = getString(input.values, 'contract');
|
|
207
220
|
if (rawContract !== undefined) {
|
|
208
221
|
if (!rawContract.trim())
|
|
@@ -412,6 +425,17 @@ async function runArtifactCommand(artifact, action, input, client) {
|
|
|
412
425
|
const data = await client.request({ path: basePath });
|
|
413
426
|
return { ok: true, data };
|
|
414
427
|
}
|
|
428
|
+
if (action === 'revise' && artifact !== 'contract') {
|
|
429
|
+
const feedback = getString(input.values, 'feedback') ?? input.positionals.slice(1).join(' ');
|
|
430
|
+
if (!feedback.trim())
|
|
431
|
+
throw new Error(`Usage: coauthor ${artifact} revise <projectId> --feedback "..." [--force]`);
|
|
432
|
+
const data = await client.request({
|
|
433
|
+
method: 'POST',
|
|
434
|
+
path: `${basePath}/revise`,
|
|
435
|
+
body: { feedback, ...(getBoolean(input.values, 'force') ? { force: true } : {}) },
|
|
436
|
+
});
|
|
437
|
+
return { ok: true, message: revisionMessage(artifact, data), data };
|
|
438
|
+
}
|
|
415
439
|
if (artifact === 'contract' && action === 'generate') {
|
|
416
440
|
throw new Error('contract generate is not supported. The brief comes from `coauthor project create`; refine it with `coauthor chat <project-id> --stage contract --message "..."` or replace it with `coauthor contract save <project-id> --data @contract.json`.');
|
|
417
441
|
}
|
|
@@ -1287,8 +1311,21 @@ async function buildArtifactApproveBody(artifact, input, client, basePath) {
|
|
|
1287
1311
|
function enrichChatResult(data, projectId, stage) {
|
|
1288
1312
|
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
1289
1313
|
return data;
|
|
1314
|
+
// Return the reply and which tools CoAuthor used, not the raw model message
|
|
1315
|
+
// (reasoning signatures and tool payloads are noise for an agent).
|
|
1316
|
+
const parts = extractNestedValue(data, ['responseMessage', 'parts']);
|
|
1317
|
+
const tools = Array.isArray(parts)
|
|
1318
|
+
? parts.flatMap((part) => {
|
|
1319
|
+
const type = part && typeof part === 'object' && !Array.isArray(part) ? part.type : null;
|
|
1320
|
+
if (typeof type !== 'string' || !type.startsWith('tool-'))
|
|
1321
|
+
return [];
|
|
1322
|
+
const state = part.state;
|
|
1323
|
+
return [{ tool: type.slice('tool-'.length), state: typeof state === 'string' ? state : null }];
|
|
1324
|
+
})
|
|
1325
|
+
: [];
|
|
1290
1326
|
const result = {
|
|
1291
|
-
|
|
1327
|
+
text: typeof data.text === 'string' ? data.text : '',
|
|
1328
|
+
tools,
|
|
1292
1329
|
transcript_command: `coauthor chat show ${projectId} --json`,
|
|
1293
1330
|
};
|
|
1294
1331
|
if (stage?.trim().toLowerCase() === 'draft') {
|
|
@@ -1297,6 +1334,124 @@ function enrichChatResult(data, projectId, stage) {
|
|
|
1297
1334
|
}
|
|
1298
1335
|
return result;
|
|
1299
1336
|
}
|
|
1337
|
+
function revisionMessage(artifact, data) {
|
|
1338
|
+
const summary = getResponseString(data, 'summary');
|
|
1339
|
+
const diff = getResponseValue(data, 'diff');
|
|
1340
|
+
const lines = [`${artifact === 'outline' ? 'Outline' : 'Research plan'} revised and saved (not approved).`];
|
|
1341
|
+
if (summary)
|
|
1342
|
+
lines.push(summary);
|
|
1343
|
+
if (diff && typeof diff === 'object' && !Array.isArray(diff)) {
|
|
1344
|
+
const list = (key) => {
|
|
1345
|
+
const value = diff[key];
|
|
1346
|
+
return Array.isArray(value) ? value : [];
|
|
1347
|
+
};
|
|
1348
|
+
const names = (values) => values.map((value) => typeof value === 'string' ? value : JSON.stringify(value)).join('; ');
|
|
1349
|
+
if (list('added').length > 0)
|
|
1350
|
+
lines.push(`Added: ${names(list('added'))}`);
|
|
1351
|
+
if (list('removed').length > 0)
|
|
1352
|
+
lines.push(`Removed: ${names(list('removed'))}`);
|
|
1353
|
+
if (list('renamed').length > 0)
|
|
1354
|
+
lines.push(`Renamed: ${list('renamed').map((entry) => `${entry.from} -> ${entry.to}`).join('; ')}`);
|
|
1355
|
+
if (list('changed').length > 0)
|
|
1356
|
+
lines.push(`Changed: ${list('changed').map((entry) => entry.heading ?? entry.section).join('; ')}`);
|
|
1357
|
+
if (diff.reordered === true)
|
|
1358
|
+
lines.push('Sections were reordered.');
|
|
1359
|
+
}
|
|
1360
|
+
lines.push(`Review it with: coauthor ${artifact} show <project-id> --json, then approve with: coauthor ${artifact} approve <project-id> --json`);
|
|
1361
|
+
return lines.join('\n');
|
|
1362
|
+
}
|
|
1363
|
+
async function runProfileCommand(action, input, client) {
|
|
1364
|
+
if (!action || action === 'list')
|
|
1365
|
+
return { ok: true, data: await client.request({ path: 'profiles' }) };
|
|
1366
|
+
if (action === 'show') {
|
|
1367
|
+
const profileId = input.positionals[0];
|
|
1368
|
+
if (!profileId)
|
|
1369
|
+
throw new Error('Usage: coauthor profile show <profile-id>');
|
|
1370
|
+
return { ok: true, data: await client.request({ path: `profiles/${encodeURIComponent(profileId)}` }) };
|
|
1371
|
+
}
|
|
1372
|
+
throw new Error('Usage: coauthor profile <list|show>');
|
|
1373
|
+
}
|
|
1374
|
+
const SOURCE_TYPES = { pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', markdown: 'text/markdown' };
|
|
1375
|
+
// Mirrors the server: base64 over the API caps PDFs at ~3.3 MB; text at 512 KB.
|
|
1376
|
+
const MAX_SOURCE_PDF_BYTES = 3_300_000;
|
|
1377
|
+
const MAX_SOURCE_TEXT_BYTES = 512 * 1024;
|
|
1378
|
+
async function runSourceCommand(action, input, client) {
|
|
1379
|
+
const projectId = requireProjectId(input);
|
|
1380
|
+
const path = `projects/${encodeURIComponent(projectId)}/sources`;
|
|
1381
|
+
if (!action || action === 'list')
|
|
1382
|
+
return { ok: true, data: await client.request({ path }) };
|
|
1383
|
+
if (action === 'add') {
|
|
1384
|
+
const filePath = input.positionals[1];
|
|
1385
|
+
if (!filePath)
|
|
1386
|
+
throw new Error('Usage: coauthor source add <project-id> <file.pdf|.txt|.md>');
|
|
1387
|
+
const fileName = basename(filePath);
|
|
1388
|
+
const extension = fileName.split('.').pop()?.toLowerCase() ?? '';
|
|
1389
|
+
const mimeType = SOURCE_TYPES[extension];
|
|
1390
|
+
if (!mimeType)
|
|
1391
|
+
throw new Error(`Unsupported file type ".${extension}". CoAuthor accepts PDF, .txt, and .md sources.`);
|
|
1392
|
+
const bytes = await readFile(filePath);
|
|
1393
|
+
const limit = mimeType === 'application/pdf' ? MAX_SOURCE_PDF_BYTES : MAX_SOURCE_TEXT_BYTES;
|
|
1394
|
+
if (bytes.byteLength > limit) {
|
|
1395
|
+
throw new Error(`${fileName} is ${Math.round(bytes.byteLength / 1024)} KB; the CLI accepts up to ${Math.round(limit / 1024)} KB for this type. Upload larger files in the web app.`);
|
|
1396
|
+
}
|
|
1397
|
+
const data = await client.request({
|
|
1398
|
+
method: 'POST',
|
|
1399
|
+
path,
|
|
1400
|
+
body: { file_name: fileName, mime_type: mimeType, content_base64: bytes.toString('base64') },
|
|
1401
|
+
});
|
|
1402
|
+
const invalidated = getResponseValue(data, 'research_invalidated') === true;
|
|
1403
|
+
return {
|
|
1404
|
+
ok: true,
|
|
1405
|
+
message: invalidated
|
|
1406
|
+
? `Added ${fileName}. Existing research and the draft are now stale; run research again so they use it.`
|
|
1407
|
+
: `Added ${fileName}. It is used the next time research runs.`,
|
|
1408
|
+
data,
|
|
1409
|
+
};
|
|
1410
|
+
}
|
|
1411
|
+
if (action === 'remove') {
|
|
1412
|
+
const documentId = input.positionals[1];
|
|
1413
|
+
if (!documentId)
|
|
1414
|
+
throw new Error('Usage: coauthor source remove <project-id> <source-id> --yes');
|
|
1415
|
+
if (!getBoolean(input.values, 'yes'))
|
|
1416
|
+
throw new Error('Removing a source can mark existing research and the draft stale. Re-run with --yes to confirm.');
|
|
1417
|
+
return { ok: true, data: await client.request({ method: 'DELETE', path: `${path}/${encodeURIComponent(documentId)}` }) };
|
|
1418
|
+
}
|
|
1419
|
+
throw new Error('Usage: coauthor source <list|add|remove> <project-id>');
|
|
1420
|
+
}
|
|
1421
|
+
async function runBriefCommand(action, input, client) {
|
|
1422
|
+
const projectId = requireProjectId(input);
|
|
1423
|
+
const path = `projects/${encodeURIComponent(projectId)}/brief`;
|
|
1424
|
+
if (action === 'review') {
|
|
1425
|
+
const data = await client.request({ method: 'POST', path: `${path}/review`, body: {} });
|
|
1426
|
+
return { ok: true, data };
|
|
1427
|
+
}
|
|
1428
|
+
if (action === 'answer') {
|
|
1429
|
+
if (readJsonOptionText(input.values) === undefined) {
|
|
1430
|
+
throw new Error('Usage: coauthor brief answer <projectId> --data @answers.json ({"answers":[{"question":"...","answer":"...","source":"agent|user|assumption"}]})');
|
|
1431
|
+
}
|
|
1432
|
+
const body = parseJsonOption(input.values);
|
|
1433
|
+
if (getBoolean(input.values, 'force'))
|
|
1434
|
+
body.force = true;
|
|
1435
|
+
const data = await client.request({ method: 'POST', path: `${path}/answer`, body });
|
|
1436
|
+
return { ok: true, message: `Brief updated (not approved). Changed: ${getResponseValue(data, 'changed_fields')?.join(', ') || 'nothing'}.`, data };
|
|
1437
|
+
}
|
|
1438
|
+
throw new Error('Usage: coauthor brief <review|answer> <projectId>');
|
|
1439
|
+
}
|
|
1440
|
+
async function runLogCommand(action, input, client) {
|
|
1441
|
+
const projectId = requireProjectId(input);
|
|
1442
|
+
const path = `projects/${encodeURIComponent(projectId)}/log`;
|
|
1443
|
+
if (action === 'show' || !action)
|
|
1444
|
+
return { ok: true, data: await client.request({ path }) };
|
|
1445
|
+
if (action === 'add') {
|
|
1446
|
+
const message = getString(input.values, 'message') ?? input.positionals.slice(1).join(' ');
|
|
1447
|
+
if (!message.trim())
|
|
1448
|
+
throw new Error('Usage: coauthor log add <projectId> --message "..." [--kind decision|assumption|question]');
|
|
1449
|
+
const kind = getString(input.values, 'kind');
|
|
1450
|
+
const data = await client.request({ method: 'POST', path, body: { message, ...(kind ? { kind } : {}) } });
|
|
1451
|
+
return { ok: true, message: 'Logged.', data };
|
|
1452
|
+
}
|
|
1453
|
+
throw new Error('Usage: coauthor log <add|show> <projectId>');
|
|
1454
|
+
}
|
|
1300
1455
|
function enrichResearchStatus(data) {
|
|
1301
1456
|
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
1302
1457
|
return data;
|
|
@@ -1476,8 +1631,13 @@ export function helpResult(command = []) {
|
|
|
1476
1631
|
' workspace show',
|
|
1477
1632
|
' chat [show|list]',
|
|
1478
1633
|
' contract show|save|approve',
|
|
1479
|
-
' outline show|generate|save|approve',
|
|
1480
|
-
' research-plan show|generate|save|approve',
|
|
1634
|
+
' outline show|generate|revise|save|approve',
|
|
1635
|
+
' research-plan show|generate|revise|save|approve',
|
|
1636
|
+
' brief review|answer',
|
|
1637
|
+
' profile list|show',
|
|
1638
|
+
' source list|add|remove',
|
|
1639
|
+
' integrations list',
|
|
1640
|
+
' log add|show',
|
|
1481
1641
|
' research run|status|structured',
|
|
1482
1642
|
' draft generate|status|get|save|revise',
|
|
1483
1643
|
' draft revision show|apply|discard',
|
|
@@ -1508,7 +1668,7 @@ function commandHelp(command) {
|
|
|
1508
1668
|
'--local-only removes the local credential without revoking the remote token. Use it only when explicitly abandoning remote revocation.',
|
|
1509
1669
|
].join('\n'),
|
|
1510
1670
|
'project create': [
|
|
1511
|
-
'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--json]',
|
|
1671
|
+
'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--profile <profile-id>] [--json]',
|
|
1512
1672
|
'',
|
|
1513
1673
|
'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
|
|
1514
1674
|
'--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
|
|
@@ -1555,21 +1715,55 @@ function commandHelp(command) {
|
|
|
1555
1715
|
'',
|
|
1556
1716
|
'create: --title, --topic, --audience, --contract <json|@file>. list: --limit. show: one project.',
|
|
1557
1717
|
].join('\n'),
|
|
1718
|
+
profile: [
|
|
1719
|
+
'Usage: coauthor profile list [--json]',
|
|
1720
|
+
' coauthor profile show <profile-id> [--json]',
|
|
1721
|
+
'',
|
|
1722
|
+
'Writer profiles hold the voice, writer and business context, and visual style. New projects use the default (most recently used) profile unless you pass --profile to project create. A project keeps its profile for good.',
|
|
1723
|
+
].join('\n'),
|
|
1724
|
+
integrations: [
|
|
1725
|
+
'Usage: coauthor integrations list [--json]',
|
|
1726
|
+
'',
|
|
1727
|
+
'Connected WordPress sites (ids for export wordpress --connection-id) and X accounts. Connect new ones in the web app.',
|
|
1728
|
+
].join('\n'),
|
|
1729
|
+
source: [
|
|
1730
|
+
'Usage: coauthor source list <project-id> [--json]',
|
|
1731
|
+
' coauthor source add <project-id> <file.pdf|.txt|.md> [--json]',
|
|
1732
|
+
' coauthor source remove <project-id> <source-id> --yes [--json]',
|
|
1733
|
+
'',
|
|
1734
|
+
'Reference documents CoAuthor researches from (up to 5 per project; PDF up to ~3.3 MB via the CLI, text up to 512 KB).',
|
|
1735
|
+
'Add them before research runs. Adding or removing one after research marks the research and draft stale.',
|
|
1736
|
+
].join('\n'),
|
|
1737
|
+
brief: [
|
|
1738
|
+
'Usage: coauthor brief review <project-id> [--json]',
|
|
1739
|
+
' coauthor brief answer <project-id> --data @answers.json [--force] [--json]',
|
|
1740
|
+
'',
|
|
1741
|
+
'review: CoAuthor critiques the brief and returns data.verdict, concerns, and questions (each with why, the field it changes, and answerable_by agent|human). Nothing is saved.',
|
|
1742
|
+
'answer: {"answers":[{"question","answer","source":"agent|user|assumption"}], "apply_suggested_patch"?: {...}}. CoAuthor folds them into the brief and returns changed_fields. The brief is saved, not approved.',
|
|
1743
|
+
].join('\n'),
|
|
1744
|
+
log: [
|
|
1745
|
+
'Usage: coauthor log add <project-id> --message "..." [--kind decision|assumption|question] [--json]',
|
|
1746
|
+
' coauthor log show <project-id> [--json]',
|
|
1747
|
+
'',
|
|
1748
|
+
'A decision log the user also sees in the project workspace in the web app.',
|
|
1749
|
+
].join('\n'),
|
|
1558
1750
|
contract: [
|
|
1559
1751
|
'Usage: coauthor contract <show|save|approve> <project-id> [--data <json|@file>] [--json]',
|
|
1560
1752
|
'',
|
|
1561
1753
|
'save replaces the brief ({"contract":{...}}); approve approves the saved brief. To have CoAuthor review it: coauthor workflow run <project-id> --target contract --briefing-mode strict --json',
|
|
1562
1754
|
].join('\n'),
|
|
1563
1755
|
outline: [
|
|
1564
|
-
'Usage: coauthor outline <show|generate|save|approve> <project-id> [--data <json|@file>] [--planning-model <id>] [--json]',
|
|
1756
|
+
'Usage: coauthor outline <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
|
|
1565
1757
|
'',
|
|
1566
1758
|
'generate creates an outline without approving it (data.sections). show returns the saved outline (data.artifact).',
|
|
1759
|
+
'revise --feedback: CoAuthor rewrites the outline from your feedback, saves it (not approved), and returns data.diff.',
|
|
1567
1760
|
'save replaces it with the complete list {"sections":[...]}; omitted sections are removed. approve approves the saved outline.',
|
|
1568
1761
|
].join('\n'),
|
|
1569
1762
|
'research-plan': [
|
|
1570
|
-
'Usage: coauthor research-plan <show|generate|save|approve> <project-id> [--data <json|@file>] [--planning-model <id>] [--json]',
|
|
1763
|
+
'Usage: coauthor research-plan <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
|
|
1571
1764
|
'',
|
|
1572
1765
|
'generate requires an approved outline (data.research_tasks). show returns the saved plan (data.artifact).',
|
|
1766
|
+
'revise --feedback: CoAuthor rewrites the plan from your feedback (add sources, change depth), saves it (not approved), and returns data.diff.',
|
|
1573
1767
|
'save replaces it with {"research_tasks":[...]}; approve approves the saved plan.',
|
|
1574
1768
|
].join('\n'),
|
|
1575
1769
|
research: [
|
package/dist/parser.js
CHANGED
|
@@ -66,6 +66,9 @@ const OPTIONS = {
|
|
|
66
66
|
'image-generation-model': { type: 'string' },
|
|
67
67
|
instruction: { type: 'string' },
|
|
68
68
|
scope: { type: 'string' },
|
|
69
|
+
feedback: { type: 'string' },
|
|
70
|
+
profile: { type: 'string' },
|
|
71
|
+
kind: { type: 'string' },
|
|
69
72
|
apply: { type: 'boolean', default: false },
|
|
70
73
|
accept: { type: 'string' },
|
|
71
74
|
reject: { type: 'string' },
|
|
@@ -142,6 +145,16 @@ function commandLength(positionals) {
|
|
|
142
145
|
return second === 'show' ? 2 : 1;
|
|
143
146
|
if (first === 'chat')
|
|
144
147
|
return second && ['show', 'list'].includes(second) ? 2 : 1;
|
|
148
|
+
if (first === 'brief')
|
|
149
|
+
return second && ['review', 'answer'].includes(second) ? 2 : 1;
|
|
150
|
+
if (first === 'log')
|
|
151
|
+
return second && ['add', 'show'].includes(second) ? 2 : 1;
|
|
152
|
+
if (first === 'profile')
|
|
153
|
+
return second && ['list', 'show'].includes(second) ? 2 : 1;
|
|
154
|
+
if (first === 'integrations')
|
|
155
|
+
return second === 'list' ? 2 : 1;
|
|
156
|
+
if (first === 'source')
|
|
157
|
+
return second && ['list', 'add', 'remove'].includes(second) ? 2 : 1;
|
|
145
158
|
if (first === 'skills')
|
|
146
159
|
return second && ['list', 'install'].includes(second) ? 2 : 1;
|
|
147
160
|
if (first === 'models')
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -29,21 +29,24 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
29
29
|
Typical timing: brief and outline under a minute; research and draft 3–10 minutes (deep research can take 20+); images about 20 seconds each; a revision 15–40 seconds. A typical article uses about 300 credits.
|
|
30
30
|
|
|
31
31
|
1. **Brief.** Gather topic, audience, angle, core promise, length, must-include points, and sources from the conversation and your context (the repo, docs, the user's site). Ask the user only what you cannot infer, in one message of at most 2–3 questions. Write the contract to a file (schema, field guide, and examples: `references/brief-and-contract.md`), then:
|
|
32
|
-
`coauthor project create --title "..." --contract @brief.json --json` → `data.project.id`
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
32
|
+
`coauthor project create --title "..." --contract @brief.json --profile <profile id> --json` → `data.project.id`
|
|
33
|
+
**Profile first.** A writer profile carries the voice, writer and business context, and image style, and a project keeps its profile for good. Run `coauthor profile list --json`. With one profile, omit `--profile`. With several, pick the one that fits the request (for example the company blog vs a personal newsletter) and ask the user if it isn't clear.
|
|
34
|
+
**Sources.** If the user gave you documents to work from (PDF, .txt, .md), add each before research: `coauthor source add <id> <file> --json` (up to 5; see `references/brief-and-contract.md`). Put source URLs in the brief instead.
|
|
35
|
+
2. **Brief review.** `coauthor brief review <id> --json`. CoAuthor critiques the brief and returns `data.verdict`, `data.concerns`, and `data.questions`, each with `why`, the `field` it changes, and `answerable_by`. Answer the `agent` questions from your context; take `human` ones (opinions, private business facts, numbers, risk tolerance) to the user in one message, or, if they asked not to be interrupted, answer them as assumptions. Write `{"answers":[{"question","answer","source":"agent|user|assumption"}]}` to a file (add `"apply_suggested_patch": <data.suggested_patch>` if its suggestions are good) and run `coauthor brief answer <id> --data @answers.json --json`. Repeat once if the verdict was `needs_answers`, then approve: `coauthor contract approve <id> --json`. Log what you assumed: `coauthor log add <id> --kind assumption --message "..." --json`.
|
|
36
|
+
3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
|
|
37
|
+
4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
|
|
36
38
|
5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
|
|
37
39
|
6. **Quality pass.** `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
38
40
|
7. **Images.** `coauthor image list <id> --json`, then for each placeholder `coauthor image generate <id> --placeholder-id <placeholder id> --json` (the `id` UUID, not `placeholder_id`), then poll `coauthor image status <id> --json` until none are generating. CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
|
|
39
41
|
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
40
|
-
9. **Deliver.** Give the user the final markdown (or `--format html`),
|
|
42
|
+
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
|
|
41
43
|
|
|
42
44
|
## When something stops
|
|
43
45
|
|
|
44
46
|
| Status or code | What to do |
|
|
45
47
|
| --- | --- |
|
|
46
|
-
| `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. |
|
|
48
|
+
| `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. (Prefer `brief review` / `brief answer`.) |
|
|
49
|
+
| `draft_exists`, `downstream_exists` | A later stage already depends on this one. Edit the draft instead; pass `--force` only if the user wants to restart from here. |
|
|
47
50
|
| `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
|
|
48
51
|
| `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
|
|
49
52
|
| `research_running_stale` | Research progress stopped for 30+ minutes. Show the user `coauthor research structured <id> --json` and ask before `coauthor workflow rewind <id> --target research --json`, which discards research done so far. |
|
|
@@ -59,4 +62,4 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
|
|
|
59
62
|
|
|
60
63
|
## Not in the CLI yet
|
|
61
64
|
|
|
62
|
-
|
|
65
|
+
Creating or editing writer profiles, PDFs over about 3.3 MB, adding more images than CoAuthor planned, LinkedIn, Facebook, and email versions, slideshows, and video. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
@@ -10,6 +10,12 @@ coauthor project create --title "Working title" --contract @brief.json --json
|
|
|
10
10
|
|
|
11
11
|
All fields are optional and omitted ones get defaults, but always include at least `topic`, `target_audience`, `core_promise`, and either `angle` or `additional_editorial_guidance`. `--topic` and `--audience` flags fill those fields when the contract leaves them empty. Keep `--topic` plain prose; never put JSON in it.
|
|
12
12
|
|
|
13
|
+
## Profiles and source documents
|
|
14
|
+
|
|
15
|
+
- `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full. Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
|
|
16
|
+
- `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
|
|
17
|
+
- Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
|
|
18
|
+
|
|
13
19
|
## Writing a sharp brief
|
|
14
20
|
|
|
15
21
|
- **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.
|
|
@@ -22,7 +22,7 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
|
|
|
22
22
|
1. The token needs publish permission. If an export fails with `insufficient_scope`, have the user run `coauthor auth login --with-publish` (in the background with `--no-browser`; they approve in the browser).
|
|
23
23
|
2. With the user's yes:
|
|
24
24
|
`coauthor export wordpress <id> --yes --slug <url-slug> --json`
|
|
25
|
-
3.
|
|
25
|
+
3. `coauthor integrations list --json` shows the connected WordPress sites (`id`, `label`, `site_base_url`, `enabled`) and X accounts. With several sites, ask which one and add `--connection-id <id>` (the error `wordpress_connection_required` lists them too).
|
|
26
26
|
4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
|
|
27
27
|
5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
|
|
28
28
|
|
|
@@ -18,6 +18,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
18
18
|
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
19
19
|
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
20
20
|
| `entitlement_sync_unavailable` | Subscription status couldn't be checked right now. | Don't retry in a loop. Try again in a few minutes. |
|
|
21
|
+
| `draft_exists` | `brief answer` on a project that already has a draft. | Edit the draft instead. `--force` only if the user wants to restart from the brief (the draft is regenerated). |
|
|
22
|
+
| `downstream_exists` | `outline revise` or `research-plan revise` after research ran. | Same: edit the draft, or `--force` to restart from that stage with the user's OK. |
|
|
23
|
+
| `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
|
|
21
24
|
| `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
|
|
22
25
|
| `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
|
|
23
26
|
| `review_pending`, `document_locked` | An AI review or edit is in progress in the editor. | Wait, or apply or discard it. |
|
|
@@ -31,21 +31,24 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
31
31
|
Typical timing: brief and outline under a minute; research and draft 3–10 minutes (deep research can take 20+); images about 20 seconds each; a revision 15–40 seconds. A typical article uses about 300 credits.
|
|
32
32
|
|
|
33
33
|
1. **Brief.** Gather topic, audience, angle, core promise, length, must-include points, and sources from the conversation and your context (the repo, docs, the user's site). Ask the user only what you cannot infer, in one message of at most 2–3 questions. Write the contract to a file (schema, field guide, and examples: `references/brief-and-contract.md`), then:
|
|
34
|
-
`coauthor project create --title "..." --contract @brief.json --json` → `data.project.id`
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
34
|
+
`coauthor project create --title "..." --contract @brief.json --profile <profile id> --json` → `data.project.id`
|
|
35
|
+
**Profile first.** A writer profile carries the voice, writer and business context, and image style, and a project keeps its profile for good. Run `coauthor profile list --json`. With one profile, omit `--profile`. With several, pick the one that fits the request (for example the company blog vs a personal newsletter) and ask the user if it isn't clear.
|
|
36
|
+
**Sources.** If the user gave you documents to work from (PDF, .txt, .md), add each before research: `coauthor source add <id> <file> --json` (up to 5; see `references/brief-and-contract.md`). Put source URLs in the brief instead.
|
|
37
|
+
2. **Brief review.** `coauthor brief review <id> --json`. CoAuthor critiques the brief and returns `data.verdict`, `data.concerns`, and `data.questions`, each with `why`, the `field` it changes, and `answerable_by`. Answer the `agent` questions from your context; take `human` ones (opinions, private business facts, numbers, risk tolerance) to the user in one message, or, if they asked not to be interrupted, answer them as assumptions. Write `{"answers":[{"question","answer","source":"agent|user|assumption"}]}` to a file (add `"apply_suggested_patch": <data.suggested_patch>` if its suggestions are good) and run `coauthor brief answer <id> --data @answers.json --json`. Repeat once if the verdict was `needs_answers`, then approve: `coauthor contract approve <id> --json`. Log what you assumed: `coauthor log add <id> --kind assumption --message "..." --json`.
|
|
38
|
+
3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
|
|
39
|
+
4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
|
|
38
40
|
5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
|
|
39
41
|
6. **Quality pass.** `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
40
42
|
7. **Images.** `coauthor image list <id> --json`, then for each placeholder `coauthor image generate <id> --placeholder-id <placeholder id> --json` (the `id` UUID, not `placeholder_id`), then poll `coauthor image status <id> --json` until none are generating. CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
|
|
41
43
|
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
42
|
-
9. **Deliver.** Give the user the final markdown (or `--format html`),
|
|
44
|
+
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
|
|
43
45
|
|
|
44
46
|
## When something stops
|
|
45
47
|
|
|
46
48
|
| Status or code | What to do |
|
|
47
49
|
| --- | --- |
|
|
48
|
-
| `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. |
|
|
50
|
+
| `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. (Prefer `brief review` / `brief answer`.) |
|
|
51
|
+
| `draft_exists`, `downstream_exists` | A later stage already depends on this one. Edit the draft instead; pass `--force` only if the user wants to restart from here. |
|
|
49
52
|
| `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
|
|
50
53
|
| `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
|
|
51
54
|
| `research_running_stale` | Research progress stopped for 30+ minutes. Show the user `coauthor research structured <id> --json` and ask before `coauthor workflow rewind <id> --target research --json`, which discards research done so far. |
|
|
@@ -61,7 +64,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
|
|
|
61
64
|
|
|
62
65
|
## Not in the CLI yet
|
|
63
66
|
|
|
64
|
-
|
|
67
|
+
Creating or editing writer profiles, PDFs over about 3.3 MB, adding more images than CoAuthor planned, LinkedIn, Facebook, and email versions, slideshows, and video. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
65
68
|
|
|
66
69
|
# Reference sections
|
|
67
70
|
|
|
@@ -81,6 +84,12 @@ coauthor project create --title "Working title" --contract @brief.json --json
|
|
|
81
84
|
|
|
82
85
|
All fields are optional and omitted ones get defaults, but always include at least `topic`, `target_audience`, `core_promise`, and either `angle` or `additional_editorial_guidance`. `--topic` and `--audience` flags fill those fields when the contract leaves them empty. Keep `--topic` plain prose; never put JSON in it.
|
|
83
86
|
|
|
87
|
+
### Profiles and source documents
|
|
88
|
+
|
|
89
|
+
- `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full. Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
|
|
90
|
+
- `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
|
|
91
|
+
- Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
|
|
92
|
+
|
|
84
93
|
### Writing a sharp brief
|
|
85
94
|
|
|
86
95
|
- **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.
|
|
@@ -369,7 +378,7 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
|
|
|
369
378
|
1. The token needs publish permission. If an export fails with `insufficient_scope`, have the user run `coauthor auth login --with-publish` (in the background with `--no-browser`; they approve in the browser).
|
|
370
379
|
2. With the user's yes:
|
|
371
380
|
`coauthor export wordpress <id> --yes --slug <url-slug> --json`
|
|
372
|
-
3.
|
|
381
|
+
3. `coauthor integrations list --json` shows the connected WordPress sites (`id`, `label`, `site_base_url`, `enabled`) and X accounts. With several sites, ask which one and add `--connection-id <id>` (the error `wordpress_connection_required` lists them too).
|
|
373
382
|
4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
|
|
374
383
|
5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
|
|
375
384
|
|
|
@@ -405,6 +414,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
405
414
|
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
406
415
|
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
407
416
|
| `entitlement_sync_unavailable` | Subscription status couldn't be checked right now. | Don't retry in a loop. Try again in a few minutes. |
|
|
417
|
+
| `draft_exists` | `brief answer` on a project that already has a draft. | Edit the draft instead. `--force` only if the user wants to restart from the brief (the draft is regenerated). |
|
|
418
|
+
| `downstream_exists` | `outline revise` or `research-plan revise` after research ran. | Same: edit the draft, or `--force` to restart from that stage with the user's OK. |
|
|
419
|
+
| `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
|
|
408
420
|
| `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
|
|
409
421
|
| `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
|
|
410
422
|
| `review_pending`, `document_locked` | An AI review or edit is in progress in the editor. | Wait, or apply or discard it. |
|