@clickminded/coauthor-cli 0.0.9 → 0.0.11
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 +7 -1
- package/dist/commands.d.ts +1 -1
- package/dist/commands.js +157 -42
- package/dist/index.js +26 -8
- package/package.json +1 -1
- package/skills/agents/SKILL.md +4 -0
- package/skills/claude/SKILL.md +4 -0
- package/skills/codex/SKILL.md +4 -0
- package/skills/cursor/coauthor-cli.mdc +4 -0
package/README.md
CHANGED
|
@@ -148,7 +148,7 @@ Images and threads:
|
|
|
148
148
|
|
|
149
149
|
```sh
|
|
150
150
|
coauthor image list <project-id> --json
|
|
151
|
-
coauthor image generate <project-id> --prompt "..." --json
|
|
151
|
+
coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "..." --json
|
|
152
152
|
coauthor thread generate <project-id> --json
|
|
153
153
|
coauthor thread save <project-id> --data '{"posts":[]}' --json
|
|
154
154
|
```
|
|
@@ -189,6 +189,8 @@ Agents should:
|
|
|
189
189
|
- Use `--json` on every command they need to parse.
|
|
190
190
|
- Use `--wait` when starting long-running research or draft jobs and the user expects completion.
|
|
191
191
|
- Treat `status: "requires_key"` as a recoverable pause, not a failed workflow. Tell the user to add keys in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
192
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
193
|
+
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Wait for `project_state: "research_structured"` before generating a draft; do not rewind for this state.
|
|
192
194
|
- Use `coauthor credits <project-id> --json` to inspect credit allowance, pending holds, and remaining credits.
|
|
193
195
|
- Avoid retrying publish/export after uncertain network failures.
|
|
194
196
|
- Use `coauthor operation status <operation-key>` after uncertainty.
|
|
@@ -221,6 +223,10 @@ The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
|
|
|
221
223
|
|
|
222
224
|
`requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. The task is paused when possible. Open AI settings in the web app, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
|
|
223
225
|
|
|
226
|
+
`research_running_stale` means a research run is still marked running beyond the expected progress window. Inspect `coauthor research structured <project-id> --json`; if it only contains empty section shells, rewind research or report the stale run instead of repeatedly resuming.
|
|
227
|
+
|
|
228
|
+
Image generation requires an existing image placeholder. Run `coauthor image list <project-id> --json` after draft generation and pass the placeholder id to `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`.
|
|
229
|
+
|
|
224
230
|
If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
|
|
225
231
|
|
|
226
232
|
```sh
|
package/dist/commands.d.ts
CHANGED
|
@@ -9,4 +9,4 @@ export type CommandContext = {
|
|
|
9
9
|
token: string;
|
|
10
10
|
};
|
|
11
11
|
export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
|
|
12
|
-
export declare function helpResult(): CommandResult;
|
|
12
|
+
export declare function helpResult(command?: string[]): CommandResult;
|
package/dist/commands.js
CHANGED
|
@@ -632,10 +632,11 @@ function openBrowser(url) {
|
|
|
632
632
|
child.unref();
|
|
633
633
|
}
|
|
634
634
|
async function waitForResearch(client, projectId, initialData) {
|
|
635
|
-
const deadline = Date.now() + 20 * 60_000;
|
|
635
|
+
const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
|
|
636
|
+
const pollMs = waitPollMs();
|
|
636
637
|
let latest = initialData;
|
|
637
638
|
while (Date.now() < deadline) {
|
|
638
|
-
await sleep(
|
|
639
|
+
await sleep(pollMs);
|
|
639
640
|
latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
640
641
|
const status = extractNestedString(latest, ['run', 'status']);
|
|
641
642
|
if (status === 'succeeded')
|
|
@@ -645,14 +646,18 @@ async function waitForResearch(client, projectId, initialData) {
|
|
|
645
646
|
if (status === 'paused_requires_key') {
|
|
646
647
|
return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
|
|
647
648
|
}
|
|
649
|
+
const stale = researchRunningStaleResult(projectId, latest, null, initialData);
|
|
650
|
+
if (stale)
|
|
651
|
+
return stale;
|
|
648
652
|
}
|
|
649
|
-
return
|
|
653
|
+
return waitTimedOutResult(projectId, 'research', initialData, latest, null);
|
|
650
654
|
}
|
|
651
655
|
async function waitForDraft(client, projectId, initialData) {
|
|
652
|
-
const deadline = Date.now() + 20 * 60_000;
|
|
656
|
+
const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
|
|
657
|
+
const pollMs = waitPollMs();
|
|
653
658
|
let latest = initialData;
|
|
654
659
|
while (Date.now() < deadline) {
|
|
655
|
-
await sleep(
|
|
660
|
+
await sleep(pollMs);
|
|
656
661
|
latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
657
662
|
const state = getResponseString(latest, 'project_state');
|
|
658
663
|
const phase = getResponseString(latest, 'phase');
|
|
@@ -664,19 +669,17 @@ async function waitForDraft(client, projectId, initialData) {
|
|
|
664
669
|
if (phase === 'failed')
|
|
665
670
|
throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
|
|
666
671
|
}
|
|
667
|
-
return
|
|
672
|
+
return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
|
|
668
673
|
}
|
|
669
674
|
async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
670
|
-
const deadline = Date.now() + 40 * 60_000;
|
|
675
|
+
const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
|
|
676
|
+
const pollMs = waitPollMs();
|
|
671
677
|
let latestDraft = initialData;
|
|
672
678
|
let latestResearch = null;
|
|
673
679
|
let draftGenerate = null;
|
|
674
680
|
let attemptedDraftStart = false;
|
|
675
|
-
if (workflowIndicatesBackgroundResearch(initialData)) {
|
|
676
|
-
return researchRunningWorkflowResult(projectId, initialData, null, null);
|
|
677
|
-
}
|
|
678
681
|
while (Date.now() < deadline) {
|
|
679
|
-
await sleep(
|
|
682
|
+
await sleep(pollMs);
|
|
680
683
|
latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
681
684
|
const draftState = getResponseString(latestDraft, 'project_state');
|
|
682
685
|
const draftPhase = getResponseString(latestDraft, 'phase');
|
|
@@ -713,6 +716,9 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
713
716
|
draft_status: latestDraft,
|
|
714
717
|
});
|
|
715
718
|
}
|
|
719
|
+
const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
|
|
720
|
+
if (stale)
|
|
721
|
+
return stale;
|
|
716
722
|
if (!attemptedDraftStart
|
|
717
723
|
&& (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
|
|
718
724
|
&& draftPhase !== 'queued'
|
|
@@ -731,13 +737,73 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
731
737
|
}
|
|
732
738
|
}
|
|
733
739
|
}
|
|
740
|
+
return waitTimedOutResult(projectId, 'workflow draft target', initialData, latestResearch, latestDraft);
|
|
741
|
+
}
|
|
742
|
+
function waitPollMs() {
|
|
743
|
+
const raw = Number(process.env.COAUTHOR_CLI_WAIT_POLL_MS);
|
|
744
|
+
return Number.isFinite(raw) && raw >= 0 ? raw : 3000;
|
|
745
|
+
}
|
|
746
|
+
function waitTimeoutMs(defaultMs) {
|
|
747
|
+
const raw = Number(process.env.COAUTHOR_CLI_WAIT_TIMEOUT_MS);
|
|
748
|
+
return Number.isFinite(raw) && raw > 0 ? raw : defaultMs;
|
|
749
|
+
}
|
|
750
|
+
function researchStaleMs() {
|
|
751
|
+
const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
|
|
752
|
+
return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60_000;
|
|
753
|
+
}
|
|
754
|
+
function researchRunAgeMs(data) {
|
|
755
|
+
const timestamp = extractNestedString(data, ['run', 'updated_at'])
|
|
756
|
+
?? extractNestedString(data, ['run', 'created_at']);
|
|
757
|
+
if (!timestamp)
|
|
758
|
+
return null;
|
|
759
|
+
const time = Date.parse(timestamp);
|
|
760
|
+
if (!Number.isFinite(time))
|
|
761
|
+
return null;
|
|
762
|
+
return Date.now() - time;
|
|
763
|
+
}
|
|
764
|
+
function isResearchRunningStale(data) {
|
|
765
|
+
if (extractNestedString(data, ['run', 'status']) !== 'running')
|
|
766
|
+
return false;
|
|
767
|
+
if (getResponseString(data, 'project_state') !== 'research_running')
|
|
768
|
+
return false;
|
|
769
|
+
const ageMs = researchRunAgeMs(data);
|
|
770
|
+
return typeof ageMs === 'number' && ageMs >= researchStaleMs();
|
|
771
|
+
}
|
|
772
|
+
function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow) {
|
|
773
|
+
if (!isResearchRunningStale(researchStatus))
|
|
774
|
+
return null;
|
|
734
775
|
return {
|
|
735
|
-
ok:
|
|
736
|
-
|
|
776
|
+
ok: false,
|
|
777
|
+
status: 'research_running_stale',
|
|
778
|
+
exitCode: 2,
|
|
779
|
+
message: 'Research is still marked running and has not reported a terminal state within the expected window.',
|
|
737
780
|
data: {
|
|
738
|
-
workflow
|
|
739
|
-
research_status:
|
|
740
|
-
draft_status:
|
|
781
|
+
workflow,
|
|
782
|
+
research_status: enrichResearchStatus(researchStatus),
|
|
783
|
+
draft_status: draftStatus,
|
|
784
|
+
next_commands: [
|
|
785
|
+
`coauthor research status ${projectId} --json`,
|
|
786
|
+
`coauthor research structured ${projectId} --json`,
|
|
787
|
+
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
788
|
+
],
|
|
789
|
+
},
|
|
790
|
+
};
|
|
791
|
+
}
|
|
792
|
+
function waitTimedOutResult(projectId, target, workflow, researchStatus, draftStatus) {
|
|
793
|
+
return {
|
|
794
|
+
ok: false,
|
|
795
|
+
status: 'timed_out',
|
|
796
|
+
exitCode: 2,
|
|
797
|
+
message: `Timed out waiting for ${target}; check status before retrying.`,
|
|
798
|
+
data: {
|
|
799
|
+
workflow,
|
|
800
|
+
research_status: researchStatus,
|
|
801
|
+
draft_status: draftStatus,
|
|
802
|
+
next_commands: [
|
|
803
|
+
`coauthor research status ${projectId} --json`,
|
|
804
|
+
`coauthor draft status ${projectId} --json`,
|
|
805
|
+
`coauthor workflow resume ${projectId} --target draft --wait --json`,
|
|
806
|
+
],
|
|
741
807
|
},
|
|
742
808
|
};
|
|
743
809
|
}
|
|
@@ -790,8 +856,38 @@ function enrichResearchStatus(data) {
|
|
|
790
856
|
return data;
|
|
791
857
|
const runStatus = extractNestedString(data, ['run', 'status']);
|
|
792
858
|
const projectState = getResponseString(data, 'project_state');
|
|
793
|
-
if (runStatus !== 'running'
|
|
859
|
+
if (runStatus !== 'running')
|
|
860
|
+
return data;
|
|
861
|
+
if (isResearchRunningStale(data)) {
|
|
862
|
+
return {
|
|
863
|
+
...data,
|
|
864
|
+
diagnostic: {
|
|
865
|
+
code: 'research_running_stale',
|
|
866
|
+
message: 'Research is still marked running and has not reported a terminal state within the expected window. Inspect structured output before deciding whether to rewind.',
|
|
867
|
+
next_commands: [
|
|
868
|
+
'coauthor research status <project-id> --json',
|
|
869
|
+
'coauthor research structured <project-id> --json',
|
|
870
|
+
'coauthor workflow rewind <project-id> --target research --json',
|
|
871
|
+
],
|
|
872
|
+
},
|
|
873
|
+
};
|
|
874
|
+
}
|
|
875
|
+
if (projectState === 'research_running')
|
|
794
876
|
return data;
|
|
877
|
+
if (projectState === 'research_complete') {
|
|
878
|
+
return {
|
|
879
|
+
...data,
|
|
880
|
+
diagnostic: {
|
|
881
|
+
code: 'research_structuring',
|
|
882
|
+
message: 'Raw research is complete and the worker is structuring the results. Keep waiting until project_state is "research_structured"; do not rewind for this transition.',
|
|
883
|
+
next_commands: [
|
|
884
|
+
'coauthor research status <project-id> --json',
|
|
885
|
+
'coauthor draft status <project-id> --json',
|
|
886
|
+
'coauthor workflow resume <project-id> --target draft --wait --json',
|
|
887
|
+
],
|
|
888
|
+
},
|
|
889
|
+
};
|
|
890
|
+
}
|
|
795
891
|
return {
|
|
796
892
|
...data,
|
|
797
893
|
diagnostic: {
|
|
@@ -805,29 +901,6 @@ function enrichResearchStatus(data) {
|
|
|
805
901
|
},
|
|
806
902
|
};
|
|
807
903
|
}
|
|
808
|
-
function workflowIndicatesBackgroundResearch(data) {
|
|
809
|
-
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
810
|
-
return false;
|
|
811
|
-
return getResponseString(data, 'project_state') === 'research_running'
|
|
812
|
-
|| getResponseString(data, 'status') === 'research_running';
|
|
813
|
-
}
|
|
814
|
-
function researchRunningWorkflowResult(projectId, workflow, researchStatus, draftStatus) {
|
|
815
|
-
return {
|
|
816
|
-
ok: true,
|
|
817
|
-
status: 'research_running',
|
|
818
|
-
message: 'Research is running in the background. Draft generation has not started yet.',
|
|
819
|
-
data: {
|
|
820
|
-
workflow,
|
|
821
|
-
research_status: researchStatus,
|
|
822
|
-
draft_status: draftStatus,
|
|
823
|
-
next_commands: [
|
|
824
|
-
`coauthor research status ${projectId} --json`,
|
|
825
|
-
`coauthor workflow resume ${projectId} --target draft --wait --json`,
|
|
826
|
-
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
827
|
-
],
|
|
828
|
-
},
|
|
829
|
-
};
|
|
830
|
-
}
|
|
831
904
|
function requiresKeyPauseResult(projectId, target, message, data) {
|
|
832
905
|
const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
|
|
833
906
|
return {
|
|
@@ -895,10 +968,11 @@ function resourceCommandName(resource) {
|
|
|
895
968
|
return 'operation';
|
|
896
969
|
return resource;
|
|
897
970
|
}
|
|
898
|
-
export function helpResult() {
|
|
971
|
+
export function helpResult(command = []) {
|
|
972
|
+
const scoped = commandHelp(command);
|
|
899
973
|
return {
|
|
900
974
|
ok: true,
|
|
901
|
-
message: [
|
|
975
|
+
message: scoped ?? [
|
|
902
976
|
'Usage: coauthor <command> [options]',
|
|
903
977
|
'',
|
|
904
978
|
'Commands:',
|
|
@@ -925,3 +999,44 @@ export function helpResult() {
|
|
|
925
999
|
].join('\n'),
|
|
926
1000
|
};
|
|
927
1001
|
}
|
|
1002
|
+
function commandHelp(command) {
|
|
1003
|
+
const key = command.join(' ');
|
|
1004
|
+
const help = {
|
|
1005
|
+
'project create': [
|
|
1006
|
+
'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--json]',
|
|
1007
|
+
'',
|
|
1008
|
+
'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
|
|
1009
|
+
].join('\n'),
|
|
1010
|
+
'workflow run': [
|
|
1011
|
+
'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
|
|
1012
|
+
'',
|
|
1013
|
+
'--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
|
|
1014
|
+
].join('\n'),
|
|
1015
|
+
'workflow resume': [
|
|
1016
|
+
'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
|
|
1017
|
+
'',
|
|
1018
|
+
'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
|
|
1019
|
+
].join('\n'),
|
|
1020
|
+
'draft generate': [
|
|
1021
|
+
'Usage: coauthor draft generate <project-id> [--wait] [--json]',
|
|
1022
|
+
'',
|
|
1023
|
+
'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
|
|
1024
|
+
].join('\n'),
|
|
1025
|
+
'draft get': [
|
|
1026
|
+
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
|
|
1027
|
+
'',
|
|
1028
|
+
'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
|
|
1029
|
+
].join('\n'),
|
|
1030
|
+
'draft save': [
|
|
1031
|
+
'Usage: coauthor draft save <project-id> --data \'<json>\' [--json]',
|
|
1032
|
+
'',
|
|
1033
|
+
'Saves a draft document payload through the agent API.',
|
|
1034
|
+
].join('\n'),
|
|
1035
|
+
'image generate': [
|
|
1036
|
+
'Usage: coauthor image generate <project-id> --placeholder-id <placeholder-id> [--prompt "..."] [--json]',
|
|
1037
|
+
'',
|
|
1038
|
+
'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
|
|
1039
|
+
].join('\n'),
|
|
1040
|
+
};
|
|
1041
|
+
return help[key] ?? null;
|
|
1042
|
+
}
|
package/dist/index.js
CHANGED
|
@@ -11,7 +11,7 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
11
11
|
try {
|
|
12
12
|
const parsed = parseCliArgs(argv);
|
|
13
13
|
if (parsed.globals.help) {
|
|
14
|
-
process.stdout.write(renderResult(helpResult(), parsed.globals.json));
|
|
14
|
+
process.stdout.write(renderResult(helpResult(parsed.command), parsed.globals.json));
|
|
15
15
|
return 0;
|
|
16
16
|
}
|
|
17
17
|
const runtimeConfig = await resolveRuntimeConfig({
|
|
@@ -41,26 +41,44 @@ function formatCliError(error, baseUrl, argv = []) {
|
|
|
41
41
|
if (requiresKey)
|
|
42
42
|
return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
|
|
43
43
|
const message = extractErrorMessage(error.responseBody) ?? error.message;
|
|
44
|
-
const researchBlock =
|
|
44
|
+
const researchBlock = formatResearchDraftBlock(message, argv);
|
|
45
45
|
if (researchBlock)
|
|
46
46
|
return { error: new Error(researchBlock.message), result: researchBlock, exitCode: 2 };
|
|
47
47
|
return { error: new Error(message), exitCode: 1 };
|
|
48
48
|
}
|
|
49
49
|
return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
|
|
50
50
|
}
|
|
51
|
-
function
|
|
52
|
-
|
|
51
|
+
function formatResearchDraftBlock(message, argv) {
|
|
52
|
+
const stateMatch = /Cannot generate draft in state "(research_running|research_complete)"/i.exec(message);
|
|
53
|
+
if (!stateMatch)
|
|
53
54
|
return null;
|
|
55
|
+
const state = stateMatch[1]?.toLowerCase();
|
|
54
56
|
const projectId = resolveProjectIdFromArgv(argv);
|
|
57
|
+
const statusCommand = projectId ? `coauthor research status ${projectId} --json` : 'coauthor research status <project-id> --json';
|
|
58
|
+
const resumeCommand = projectId
|
|
59
|
+
? `coauthor workflow resume ${projectId} --target draft --wait --json`
|
|
60
|
+
: 'coauthor workflow resume <project-id> --target draft --wait --json';
|
|
61
|
+
if (state === 'research_complete') {
|
|
62
|
+
return {
|
|
63
|
+
ok: false,
|
|
64
|
+
status: 'research_structuring',
|
|
65
|
+
message: `${message}\nResearch is complete and the results are being structured. Wait for project_state "research_structured" before generating a draft.`,
|
|
66
|
+
next_commands: [
|
|
67
|
+
statusCommand,
|
|
68
|
+
resumeCommand,
|
|
69
|
+
],
|
|
70
|
+
exitCode: 2,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
55
73
|
const recoveryCommands = projectId
|
|
56
74
|
? [
|
|
57
|
-
|
|
58
|
-
|
|
75
|
+
statusCommand,
|
|
76
|
+
resumeCommand,
|
|
59
77
|
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
60
78
|
]
|
|
61
79
|
: [
|
|
62
|
-
|
|
63
|
-
|
|
80
|
+
statusCommand,
|
|
81
|
+
resumeCommand,
|
|
64
82
|
'coauthor workflow rewind <project-id> --target research --json',
|
|
65
83
|
];
|
|
66
84
|
return {
|
package/package.json
CHANGED
package/skills/agents/SKILL.md
CHANGED
|
@@ -16,7 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
18
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
20
|
+
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
19
21
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
22
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
23
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
20
24
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
21
25
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
26
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
package/skills/claude/SKILL.md
CHANGED
|
@@ -16,7 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
18
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
20
|
+
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
19
21
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
22
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
23
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
20
24
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
21
25
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
26
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -16,7 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
18
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
20
|
+
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
19
21
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
22
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
23
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
20
24
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
21
25
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
26
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
@@ -13,7 +13,11 @@ alwaysApply: true
|
|
|
13
13
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
14
14
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
15
15
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
16
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
17
|
+
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
16
18
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
19
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
20
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
17
21
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
18
22
|
- After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
|
|
19
23
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|