@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/gjc-runtime/ultragoal-runtime.ts

@@ -2,6 +2,7 @@ import * as crypto from "node:crypto";
 import * as path from "node:path";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
+import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
 import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
@@ -474,13 +475,58 @@ export function buildUltragoalHudSummary(
 	});
 }
 
-function titleFromBrief(brief: string): string {
-	const firstLine = brief
+function clampTitle(title: string): string {
+	return title.length > 80 ? `${title.slice(0, 77)}...` : title;
+}
+
+function firstNonEmptyLine(text: string): string | undefined {
+	return text
 		.split(/\r?\n/)
 		.map(line => line.trim())
 		.find(line => line.length > 0);
+}
+
+function titleFromBrief(brief: string): string {
+	const firstLine = firstNonEmptyLine(brief);
 	if (!firstLine) return "Complete ultragoal brief";
-	return firstLine.length > 80 ? `${firstLine.slice(0, 77)}...` : firstLine;
+	return clampTitle(firstLine);
+}
+
+// A reserved, column-0 (unindented) `@goal` line opens a story. The character
+// right after `@goal` must be `:`, an ASCII space or tab, or end-of-line, so
+// `@goalish`, `@goals:`, `@goal-foo`, `@goal.foo`, `@goal/foo`, a non-breaking
+// space, and indented or mid-line `@goal:` are all ordinary objective text and
+// never delimiters.
+const GOAL_DELIMITER = /^@goal(?::|[ \t]+|$)[ \t]*(.*)$/;
+
+interface ParsedGoal {
+	title: string;
+	objective: string;
+}
+
+function parseGoalsFromBrief(brief: string): ParsedGoal[] {
+	const sections: { title: string; body: string[] }[] = [];
+	let current: { title: string; body: string[] } | undefined;
+	for (const line of brief.split(/\r?\n/)) {
+		const match = GOAL_DELIMITER.exec(line);
+		if (match) {
+			current = { title: match[1].trim(), body: [] };
+			sections.push(current);
+			continue;
+		}
+		current?.body.push(line);
+	}
+	if (sections.length === 0) {
+		return [{ title: titleFromBrief(brief), objective: brief.trim() }];
+	}
+	return sections.map((section, index) => {
+		const body = section.body.join("\n").trim();
+		const title = section.title || firstNonEmptyLine(body) || "";
+		if (!title && !body) {
+			throw new Error(`ultragoal @goal block ${index + 1} has no title or objective`);
+		}
+		return { title: clampTitle(title), objective: body || title };
+	});
 }
 
 export async function createUltragoalPlan(input: {
@@ -491,21 +537,23 @@ export async function createUltragoalPlan(input: {
 	const brief = input.brief.trim();
 	if (!brief) throw new Error("ultragoal brief is required");
 	const now = new Date().toISOString();
+	// Parse the untrimmed brief so the raw-line delimiter contract holds: a
+	// leading-indented `@goal` on the first line must stay objective text rather
+	// than being promoted to column 0 by trimming.
+	const goals: UltragoalGoal[] = parseGoalsFromBrief(input.brief).map((goal, index) => ({
+		id: `G${String(index + 1).padStart(3, "0")}`,
+		title: goal.title,
+		objective: goal.objective,
+		status: "pending",
+		createdAt: now,
+		updatedAt: now,
+	}));
 	const plan: UltragoalPlan = {
 		version: 1,
 		brief,
 		gjcGoalMode: input.gjcGoalMode ?? "aggregate",
 		gjcObjective: DEFAULT_ULTRAGOAL_OBJECTIVE,
-		goals: [
-			{
-				id: "G001",
-				title: titleFromBrief(brief),
-				objective: brief,
-				status: "pending",
-				createdAt: now,
-				updatedAt: now,
-			},
-		],
+		goals,
 		createdAt: now,
 		updatedAt: now,
 	};
@@ -1235,16 +1283,26 @@ function renderStatus(summary: UltragoalStatusSummary, json: boolean): string {
 function renderCompleteHandoff(
 	result: { plan: UltragoalPlan; goal?: UltragoalGoal; allComplete: boolean },
 	json: boolean,
+	cwd: string,
 ): string {
-	if (json) return `${JSON.stringify(result, null, 2)}\n`;
-	if (result.allComplete) return "All ultragoal goals are complete.\n";
-	if (!result.goal) return "No schedulable ultragoal goal found.\n";
+	if (json) {
+		return renderCliWriteReceipt({
+			ok: true,
+			all_complete: result.allComplete,
+			next_action: result.allComplete ? "none" : "execute-goal",
+			goal_id: result.goal?.id,
+			goal_status: result.goal?.status,
+			gjc_objective: result.plan.gjcObjective,
+			goals_path: getUltragoalPaths(cwd).goalsPath,
+		});
+	}
+	if (result.allComplete) return "ultragoal complete all=true\n";
+	if (!result.goal) return "ultragoal next-action=none\n";
 	return [
-		`Ultragoal handoff: ${result.goal.id} — ${result.goal.title}`,
-		`Objective: ${result.goal.objective}`,
-		`GJC objective: ${result.plan.gjcObjective}`,
-		'Call goal({"op":"get"}); call goal({"op":"create","objective":"<printed objective>"}) only if no active GJC goal exists, then keep the GJC goal active while this Ultragoal story is verified and checkpointed.',
-		'Before checkpointing complete, obtain a passing architectReview (architecture/product/code CLEAR + APPROVE) and executorQa (e2e/red-team passed with contractCoverage, surfaceEvidence, adversarialCases, and artifactRefs matrix evidence), then checkpoint with --quality-gate-json and a fresh active goal snapshot; record blockers instead of completing on any finding, plan/code mismatch, shallow evidence, or missing artifact link; call goal({"op":"complete"}) only after the final aggregate receipt exists.',
+		`ultragoal next-action=execute-goal goal-id=${result.goal.id}`,
+		`objective=${result.goal.objective}`,
+		`gjc-objective=${result.plan.gjcObjective}`,
+		"checkpoint requires=architectReview:CLEAR+APPROVE,executorQa:passed",
 		"",
 	].join("\n");
 }
@@ -1264,8 +1322,13 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					status: 0,
 					createdPlan: true,
 					stdout: json
-						? `${JSON.stringify(plan, null, 2)}\n`
-						: `Created ultragoal plan with ${plan.goals.length} goal at ${getUltragoalPaths(cwd).goalsPath}.\n`,
+						? renderCliWriteReceipt({
+								ok: true,
+								goals_count: plan.goals.length,
+								goal_ids: plan.goals.map(goal => goal.id),
+								goals_path: getUltragoalPaths(cwd).goalsPath,
+							})
+						: `Created ultragoal plan with ${plan.goals.length} goal${plan.goals.length === 1 ? "" : "s"} at ${getUltragoalPaths(cwd).goalsPath}.\n`,
 				};
 			}
 			case "complete-goals":
@@ -1274,6 +1337,7 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					stdout: renderCompleteHandoff(
 						await startNextUltragoalGoal({ cwd, retryFailed: hasFlag(args, "--retry-failed") }),
 						json,
+						cwd,
 					),
 				};
 			case "checkpoint": {
@@ -1288,9 +1352,19 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 					qualityGateJson: flagValue(args, "--quality-gate-json"),
 				});
+				const goal = plan.goals.find(item => item.id === goalId);
 				return {
 					status: 0,
-					stdout: json ? `${JSON.stringify(plan, null, 2)}\n` : `Checkpointed ${goalId} as ${status}.\n`,
+					stdout: json
+						? renderCliWriteReceipt({
+								ok: true,
+								goal_id: goalId,
+								status,
+								goals_path: getUltragoalPaths(cwd).goalsPath,
+								completion_receipt_kind: goal?.completionVerification?.receiptKind,
+								quality_gate_hash: goal?.completionVerification?.qualityGateHash,
+							})
+						: `ultragoal checkpoint goal-id=${goalId} status=${status}\n`,
 				};
 			}
 			case "steer": {
@@ -1303,9 +1377,17 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					evidence: flagValue(args, "--evidence") ?? "",
 					rationale: flagValue(args, "--rationale") ?? "",
 				});
+				const goal = plan.goals.at(-1);
 				return {
 					status: 0,
-					stdout: json ? `${JSON.stringify(plan, null, 2)}\n` : "Accepted add_subgoal steering.\n",
+					stdout: json
+						? renderCliWriteReceipt({
+								ok: true,
+								kind,
+								goal_id: goal?.id,
+								goals_path: getUltragoalPaths(cwd).goalsPath,
+							})
+						: "Accepted add_subgoal steering.\n",
 				};
 			}
 			case "record-review-blockers": {
@@ -1317,7 +1399,13 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					evidence: flagValue(args, "--evidence") ?? "",
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 				});
-				return { status: 0, stdout: json ? `${JSON.stringify(plan, null, 2)}\n` : "Recorded review blockers.\n" };
+				const goal = plan.goals.at(-1);
+				return {
+					status: 0,
+					stdout: json
+						? renderCliWriteReceipt({ ok: true, goal_id: goal?.id, goals_path: getUltragoalPaths(cwd).goalsPath })
+						: "Recorded review blockers.\n",
+				};
 			}
 			default:
 				return { status: 1, stderr: `Unknown gjc ultragoal command: ${command}\n` };

package/src/gjc-runtime/workflow-command-ref.ts

@@ -0,0 +1,239 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/active-state";
+
+export type CommandRefVisibility = "public" | "hidden" | "planned";
+export type CommandRefIncludeWhen = "implemented-only" | "planned";
+
+export interface CommandRefCommand {
+	tokens: string[];
+	rendered: string;
+	visibility: CommandRefVisibility;
+	includeWhen: CommandRefIncludeWhen;
+	note?: string;
+}
+
+export interface CommandRefExample {
+	label?: string;
+	bytes: string;
+}
+
+export interface CommandRefBridge {
+	from: string;
+	to: string;
+	rendered: string;
+}
+
+export interface CommandRefBlock {
+	skill: CanonicalGjcWorkflowSkill;
+	blockId: string;
+	sourcePath: string;
+	renderOrder: number;
+	markers: {
+		start: string;
+		end: string;
+	};
+	commands: CommandRefCommand[];
+	examples: CommandRefExample[];
+	aliasesAndBridges: CommandRefBridge[];
+	notes: string[];
+}
+
+export interface RenderedCommandRefBlock {
+	skill: CanonicalGjcWorkflowSkill;
+	blockId: string;
+	markers: CommandRefBlock["markers"];
+	bytes: string;
+}
+
+const skillPath = (skill: CanonicalGjcWorkflowSkill): string =>
+	`packages/coding-agent/src/defaults/gjc/skills/${skill}/SKILL.md`;
+
+const stateWrite = (skill: CanonicalGjcWorkflowSkill): CommandRefCommand => ({
+	tokens: ["gjc", "state", skill, "write", "--input", `'{"current_phase":"handoff"}'`, "--json"],
+	rendered: `gjc state ${skill} write --input '{"current_phase":"handoff"}' --json`,
+	visibility: "public",
+	includeWhen: "implemented-only",
+	note: "Marks the workflow ready for the skill-tool chain guard.",
+});
+
+const stateHandoff = (
+	skill: CanonicalGjcWorkflowSkill,
+	targets: readonly CanonicalGjcWorkflowSkill[],
+): CommandRefCommand => ({
+	tokens: ["gjc", "state", skill, "handoff", "--to", `<${targets.join("|")}>`, "--json"],
+	rendered: `gjc state ${skill} handoff --to <${targets.join("|")}> --json`,
+	visibility: "public",
+	includeWhen: "implemented-only",
+	note: "Bridge command run in-process by the skill tool after slash-skill dispatch.",
+});
+
+export const WORKFLOW_COMMAND_REF_BLOCKS: readonly CommandRefBlock[] = [
+	{
+		skill: "deep-interview",
+		blockId: "state",
+		sourcePath: skillPath("deep-interview"),
+		renderOrder: 10,
+		markers: {
+			start: "<!-- gjc:cmdref:start state -->",
+			end: "<!-- gjc:cmdref:end state -->",
+		},
+		commands: [
+			stateWrite("deep-interview"),
+			{
+				tokens: [
+					"gjc",
+					"deep-interview",
+					"--write",
+					"--stage",
+					"final",
+					"--slug",
+					"{slug}",
+					"--spec",
+					"<markdown-or-path>",
+					"--deliberate",
+					"--json",
+				],
+				rendered:
+					"gjc deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json",
+				visibility: "public",
+				includeWhen: "implemented-only",
+				note: "Sanctioned deliberate deep-interview to ralplan bridge.",
+			},
+		],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state deep-interview write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+			{
+				label: "deliberate bridge",
+				bytes: "```\ngjc \\\ndeep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json\n```",
+			},
+		],
+		aliasesAndBridges: [
+			{
+				from: "deep-interview",
+				to: "ralplan",
+				rendered:
+					"gjc deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json",
+			},
+		],
+		notes: [
+			"Before invoking `/skill:ralplan`, `/skill:team`, or `/skill:ultragoal`, persist the final spec and mark deep-interview ready for handoff.",
+		],
+	},
+	{
+		skill: "ralplan",
+		blockId: "state",
+		sourcePath: skillPath("ralplan"),
+		renderOrder: 10,
+		markers: { start: "<!-- gjc:cmdref:start state -->", end: "<!-- gjc:cmdref:end state -->" },
+		commands: [stateWrite("ralplan"), stateHandoff("ralplan", ["team", "ultragoal"])],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state ralplan write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+		],
+		aliasesAndBridges: [
+			{ from: "ralplan", to: "team|ultragoal", rendered: "gjc state ralplan handoff --to <team|ultragoal> --json" },
+		],
+		notes: [
+			"Before invoking `/skill:team` or `/skill:ultragoal`, mark ralplan ready for handoff so the skill tool's chain guard permits the transition.",
+		],
+	},
+	{
+		skill: "ultragoal",
+		blockId: "state",
+		sourcePath: skillPath("ultragoal"),
+		renderOrder: 10,
+		markers: { start: "<!-- gjc:cmdref:start state -->", end: "<!-- gjc:cmdref:end state -->" },
+		commands: [stateWrite("ultragoal"), stateHandoff("ultragoal", ["ralplan", "deep-interview"])],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state ultragoal write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+		],
+		aliasesAndBridges: [
+			{
+				from: "ultragoal",
+				to: "ralplan|deep-interview",
+				rendered: "gjc state ultragoal handoff --to <ralplan|deep-interview> --json",
+			},
+		],
+		notes: [
+			"When the aggregate ultragoal is complete OR the user requests return to planning/clarification, mark ultragoal ready for handoff.",
+		],
+	},
+	{
+		skill: "team",
+		blockId: "state",
+		sourcePath: skillPath("team"),
+		renderOrder: 10,
+		markers: { start: "<!-- gjc:cmdref:start state -->", end: "<!-- gjc:cmdref:end state -->" },
+		commands: [stateWrite("team"), stateHandoff("team", ["ralplan", "deep-interview", "ultragoal"])],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state team write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+		],
+		aliasesAndBridges: [
+			{
+				from: "team",
+				to: "ralplan|deep-interview|ultragoal",
+				rendered: "gjc state team handoff --to <ralplan|deep-interview|ultragoal> --json",
+			},
+		],
+		notes: [
+			"When the team task-set completes OR the user requests return to planning/persistence, mark team ready for handoff.",
+		],
+	},
+] as const;
+
+export function listCommandRefBlocks(skill?: CanonicalGjcWorkflowSkill): CommandRefBlock[] {
+	const blocks =
+		skill === undefined
+			? WORKFLOW_COMMAND_REF_BLOCKS
+			: WORKFLOW_COMMAND_REF_BLOCKS.filter(block => block.skill === skill);
+	return [...blocks].sort(
+		(a, b) => a.skill.localeCompare(b.skill) || a.renderOrder - b.renderOrder || a.blockId.localeCompare(b.blockId),
+	);
+}
+
+export function renderCommandRefBlock(skill: CanonicalGjcWorkflowSkill, blockId = "state"): RenderedCommandRefBlock {
+	const block = WORKFLOW_COMMAND_REF_BLOCKS.find(item => item.skill === skill && item.blockId === blockId);
+	if (block === undefined) throw new Error(`Unknown command-reference block: ${skill}/${blockId}`);
+
+	const lines: string[] = [];
+	lines.push(block.markers.start);
+	lines.push(`### Generated command reference: ${block.blockId}`);
+	lines.push("");
+	for (const note of block.notes) lines.push(note);
+	lines.push("");
+	lines.push("Commands:");
+	for (const command of block.commands.filter(
+		item => item.visibility === "public" && item.includeWhen === "implemented-only",
+	)) {
+		lines.push(`- \`${command.rendered}\``);
+		if (command.note !== undefined) lines.push(`  - ${command.note}`);
+	}
+	lines.push("");
+	lines.push("Examples:");
+	for (const example of block.examples) {
+		if (example.label !== undefined) lines.push(`- ${example.label}:`);
+		lines.push(example.bytes);
+	}
+	lines.push("");
+	lines.push("Aliases and bridges:");
+	for (const bridge of block.aliasesAndBridges) lines.push(`- ${bridge.from} -> ${bridge.to}: \`${bridge.rendered}\``);
+	lines.push(block.markers.end);
+	lines.push("");
+
+	return { skill, blockId: block.blockId, markers: block.markers, bytes: lines.join("\n") };
+}
+
+export function isCanonicalGjcWorkflowSkill(value: string): value is CanonicalGjcWorkflowSkill {
+	return (CANONICAL_GJC_WORKFLOW_SKILLS as readonly string[]).includes(value);
+}

package/src/gjc-runtime/workflow-manifest.generated.json

@@ -78,7 +78,8 @@
           "write",
           "clear",
           "contract",
-          "handoff"
+          "handoff",
+          "doctor"
         ],
         "enumValues": [
           "deep-interview",
@@ -96,6 +97,7 @@
           "clear",
           "contract",
           "handoff",
+          "doctor",
           "kickoff",
           "write-spec",
           "write-artifact"
@@ -151,6 +153,26 @@
         "name": "force",
         "type": "boolean"
       },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "enumValues": [
+          "deep-interview",
+          "ralplan",
+          "ultragoal",
+          "team"
+        ],
+        "name": "skill",
+        "type": "enum"
+      },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "name": "json",
+        "type": "boolean"
+      },
       {
         "appliesToVerbs": [
           "kickoff"
@@ -267,6 +289,10 @@
         "name": "handoff",
         "surface": "state-action"
       },
+      {
+        "name": "doctor",
+        "surface": "state-action"
+      },
       {
         "name": "kickoff",
         "surface": "command-flag"
@@ -426,7 +452,8 @@
           "write",
           "clear",
           "contract",
-          "handoff"
+          "handoff",
+          "doctor"
         ],
         "enumValues": [
           "deep-interview",
@@ -444,6 +471,7 @@
           "clear",
           "contract",
           "handoff",
+          "doctor",
           "kickoff",
           "write-spec",
           "write-artifact"
@@ -499,6 +527,26 @@
         "name": "force",
         "type": "boolean"
       },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "enumValues": [
+          "deep-interview",
+          "ralplan",
+          "ultragoal",
+          "team"
+        ],
+        "name": "skill",
+        "type": "enum"
+      },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "name": "json",
+        "type": "boolean"
+      },
       {
         "appliesToVerbs": [
           "kickoff"
@@ -604,6 +652,10 @@
         "name": "handoff",
         "surface": "state-action"
       },
+      {
+        "name": "doctor",
+        "surface": "state-action"
+      },
       {
         "name": "kickoff",
         "surface": "command-flag"
@@ -783,7 +835,8 @@
           "write",
           "clear",
           "contract",
-          "handoff"
+          "handoff",
+          "doctor"
         ],
         "enumValues": [
           "deep-interview",
@@ -801,6 +854,7 @@
           "clear",
           "contract",
           "handoff",
+          "doctor",
           "kickoff",
           "write-spec",
           "write-artifact"
@@ -856,6 +910,26 @@
         "name": "force",
         "type": "boolean"
       },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "enumValues": [
+          "deep-interview",
+          "ralplan",
+          "ultragoal",
+          "team"
+        ],
+        "name": "skill",
+        "type": "enum"
+      },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "name": "json",
+        "type": "boolean"
+      },
       {
         "appliesToVerbs": [
           "start"
@@ -1010,6 +1084,10 @@
         "name": "handoff",
         "surface": "state-action"
       },
+      {
+        "name": "doctor",
+        "surface": "state-action"
+      },
       {
         "name": "start",
         "surface": "command-positional"
@@ -1196,7 +1274,8 @@
           "write",
           "clear",
           "contract",
-          "handoff"
+          "handoff",
+          "doctor"
         ],
         "enumValues": [
           "deep-interview",
@@ -1214,6 +1293,7 @@
           "clear",
           "contract",
           "handoff",
+          "doctor",
           "kickoff",
           "write-spec",
           "write-artifact"
@@ -1269,6 +1349,26 @@
         "name": "force",
         "type": "boolean"
       },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "enumValues": [
+          "deep-interview",
+          "ralplan",
+          "ultragoal",
+          "team"
+        ],
+        "name": "skill",
+        "type": "enum"
+      },
+      {
+        "appliesToVerbs": [
+          "doctor"
+        ],
+        "name": "json",
+        "type": "boolean"
+      },
       {
         "appliesToVerbs": [
           "create-goals"
@@ -1444,6 +1544,10 @@
         "name": "handoff",
         "surface": "state-action"
       },
+      {
+        "name": "doctor",
+        "surface": "state-action"
+      },
       {
         "name": "status",
         "surface": "command-positional"

package/src/gjc-runtime/workflow-manifest.ts

@@ -64,7 +64,7 @@ const AGENTS_RETENTION: RetentionPolicy = { category: "agents" };
 const PRUNE_RETENTION: RetentionPolicy = { category: "prune/delete", maxAgeDays: 30 };
 const FORCE_RETENTION: RetentionPolicy = { category: "force", maxAgeDays: 90 };
 
-const STATE_VERBS = ["read", "write", "clear", "contract", "handoff"] as const;
+const STATE_VERBS = ["read", "write", "clear", "contract", "handoff", "doctor"] as const;
 const PLANNED_ADMIN_VERBS = ["graph", "prune", "migrate", "force-overwrite"] as const;
 
 const COMMON_TYPED_ARGS: TypedArgSpec[] = [
@@ -82,6 +82,8 @@ const COMMON_TYPED_ARGS: TypedArgSpec[] = [
 	},
 	{ name: "replace", type: "boolean", appliesToVerbs: ["write"] },
 	{ name: "force", type: "boolean", appliesToVerbs: ["write", "clear", "handoff"] },
+	{ name: "skill", type: "enum", enumValues: [...CANONICAL_GJC_WORKFLOW_SKILLS], appliesToVerbs: ["doctor"] },
+	{ name: "json", type: "boolean", appliesToVerbs: ["doctor"] },
 ];
 
 function verb(name: string, surface: WorkflowVerb["surface"]): WorkflowVerb {