prizmkit 1.1.162 → 1.1.165

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.
Files changed (75) hide show
  1. package/bin/create-prizmkit.js +4 -4
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/adapters/cursor/assets/prizmkit-hook.cjs +65 -0
  4. package/bundled/adapters/cursor/hooks-adapter.js +139 -0
  5. package/bundled/adapters/cursor/paths.js +11 -0
  6. package/bundled/adapters/cursor/rules-adapter.js +49 -0
  7. package/bundled/adapters/cursor/skill-adapter.js +27 -0
  8. package/bundled/dev-pipeline/README.md +18 -5
  9. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +3 -25
  10. package/bundled/dev-pipeline/prizmkit_runtime/config.py +71 -14
  11. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +28 -4
  12. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +5 -2
  13. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +21 -3
  14. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +19 -5
  15. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +123 -28
  16. package/bundled/dev-pipeline/prizmkit_runtime/status.py +2 -0
  17. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +1 -42
  18. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +43 -6
  19. package/bundled/dev-pipeline/scripts/init-pipeline.py +46 -8
  20. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +41 -6
  21. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +143 -27
  22. package/bundled/dev-pipeline/scripts/update-feature-status.py +2 -2
  23. package/bundled/dev-pipeline/scripts/utils.py +3 -12
  24. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +4 -2
  25. package/bundled/dev-pipeline/templates/feature-list-schema.json +4 -2
  26. package/bundled/dev-pipeline/templates/refactor-list-schema.json +4 -2
  27. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +2 -1
  28. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +5 -23
  29. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +2 -2
  30. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +231 -0
  31. package/bundled/dev-pipeline/tests/test_unified_cli.py +406 -30
  32. package/bundled/dev-pipeline/tests/test_utils.py +23 -0
  33. package/bundled/rules/USAGE.md +3 -0
  34. package/bundled/skills/_metadata.json +1 -1
  35. package/bundled/skills/app-planner/SKILL.md +18 -9
  36. package/bundled/skills/app-planner/references/app-design-guide.md +7 -5
  37. package/bundled/skills/app-planner/references/brainstorm-guide.md +13 -21
  38. package/bundled/skills/app-planner/references/generated-plan-review.md +6 -2
  39. package/bundled/skills/bug-planner/SKILL.md +13 -5
  40. package/bundled/skills/bug-planner/assets/bug-confirmation-template.md +11 -7
  41. package/bundled/skills/bug-planner/references/generated-plan-review.md +7 -3
  42. package/bundled/skills/bug-planner/references/verification.md +0 -2
  43. package/bundled/skills/bug-planner/scripts/validate-bug-list.py +37 -7
  44. package/bundled/skills/feature-planner/SKILL.md +17 -11
  45. package/bundled/skills/feature-planner/assets/planning-guide.md +13 -13
  46. package/bundled/skills/feature-planner/references/completeness-review.md +8 -4
  47. package/bundled/skills/feature-planner/references/generated-plan-review.md +6 -2
  48. package/bundled/skills/feature-planner/scripts/validate-and-generate.py +43 -19
  49. package/bundled/skills/prizmkit-init/SKILL.md +1 -1
  50. package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
  51. package/bundled/skills/prizmkit-plan/SKILL.md +15 -4
  52. package/bundled/skills/prizmkit-plan/assets/plan-template.md +18 -3
  53. package/bundled/skills/prizmkit-plan/assets/spec-template.md +17 -5
  54. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +26 -24
  55. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +7 -5
  56. package/bundled/skills/prizmkit-plan/references/verification-checklist.md +15 -6
  57. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
  58. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
  59. package/bundled/skills/refactor-planner/SKILL.md +18 -11
  60. package/bundled/skills/refactor-planner/references/generated-plan-review.md +6 -2
  61. package/bundled/skills/refactor-planner/references/planning-phases.md +14 -9
  62. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +8 -2
  63. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +38 -9
  64. package/package.json +4 -2
  65. package/src/ai-cli-launch.js +9 -2
  66. package/src/clean.js +42 -6
  67. package/src/config.js +51 -10
  68. package/src/detect-platform.js +30 -8
  69. package/src/external-skills.js +33 -99
  70. package/src/index.js +5 -0
  71. package/src/manifest.js +30 -4
  72. package/src/platforms.js +11 -4
  73. package/src/prompts.js +12 -4
  74. package/src/scaffold.js +75 -4
  75. package/src/upgrade.js +15 -14
@@ -31,7 +31,7 @@ program
31
31
  program
32
32
  .command('install [directory]')
33
33
  .description('Install PrizmKit into a project directory')
34
- .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, or all')
34
+ .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, pi, cursor, or all')
35
35
  .option('--runtime <runtime>', 'Runtime assets: python or auto; unix/windows are accepted as legacy aliases for python')
36
36
  .option('--skills <suite>', 'Skill suite: core, minimal, or recommended:<type> (frontend/backend/fullstack/library)', 'core')
37
37
  .option('--pipeline', 'Install dev-pipeline (default: true)')
@@ -43,7 +43,7 @@ program
43
43
  .option('--open-cli-auto-download', 'Auto-download opencli extension if missing (default: true)')
44
44
  .option('--no-open-cli-auto-download', 'Skip auto-download, show manual steps only')
45
45
  .option('--rules <preset>', 'Rules preset: recommended, minimal, or none', 'recommended')
46
- .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, codex)')
46
+ .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, codex, pi, agent)')
47
47
  .option('--headless-prompt-arg <arg>', 'Prompt injection argv token for a custom AI CLI (e.g. -p or -i)')
48
48
  .option('--headless-extra-args <args>', 'Additional headless argv tokens for a custom AI CLI')
49
49
  .option('--external-skills <names>', 'Comma-separated external skill names to install (e.g. find-skills,impeccable)')
@@ -90,11 +90,11 @@ program
90
90
  program
91
91
  .command('config [directory]')
92
92
  .description('Reconfigure existing PrizmKit installation (change platform, skills, rules, options)')
93
- .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, or all')
93
+ .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, pi, cursor, or all')
94
94
  .option('--runtime <runtime>', 'Runtime assets: python or auto; unix/windows are accepted as legacy aliases for python')
95
95
  .option('--skills <suite>', 'Skill suite: core, minimal, or recommended:<type>')
96
96
  .option('--rules <preset>', 'Rules preset: recommended, minimal, or none')
97
- .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, codex)')
97
+ .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, codex, pi, agent)')
98
98
  .option('--headless-prompt-arg <arg>', 'Prompt injection argv token for a custom AI CLI (e.g. -p or -i)')
99
99
  .option('--headless-extra-args <args>', 'Additional headless argv tokens for a custom AI CLI')
100
100
  .option('--pipeline', 'Enable dev-pipeline')
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.162",
3
- "bundledAt": "2026-07-30T07:26:25.484Z",
4
- "bundledFrom": "43cdcc8"
2
+ "frameworkVersion": "1.1.165",
3
+ "bundledAt": "2026-08-02T02:15:32.796Z",
4
+ "bundledFrom": "24d3678"
5
5
  }
@@ -0,0 +1,65 @@
1
+ #!/usr/bin/env node
2
+ /* global process, require */
3
+ 'use strict';
4
+
5
+ const fs = require('node:fs');
6
+ const { spawnSync } = require('node:child_process');
7
+
8
+ function readInput() {
9
+ try {
10
+ const raw = fs.readFileSync(0, 'utf8').trim();
11
+ if (!raw) return {};
12
+ const value = JSON.parse(raw);
13
+ return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
14
+ } catch {
15
+ return {};
16
+ }
17
+ }
18
+
19
+ function writeOutput(value) {
20
+ process.stdout.write(`${JSON.stringify(value)}\n`);
21
+ }
22
+
23
+ function sessionStart() {
24
+ if (fs.existsSync('.prizmkit/prizm-docs/root.prizm')) {
25
+ return {
26
+ additional_context: 'PrizmKit: read exact .prizmkit/prizm-docs/root.prizm first, then load only relevant pointed module documents. Use the project Skills in .cursor/skills and Rules in .cursor/rules.',
27
+ };
28
+ }
29
+ return {
30
+ additional_context: 'PrizmKit: project documentation is not initialized. Use /prizmkit-init when project context bootstrap is required.',
31
+ };
32
+ }
33
+
34
+ function postToolUse(input) {
35
+ const toolInput = input && input.tool_input && typeof input.tool_input === 'object'
36
+ ? input.tool_input
37
+ : {};
38
+ const command = typeof toolInput.command === 'string' ? toolInput.command : '';
39
+ if (!/\bgit\s+(commit|merge|rebase)\b/.test(command)) return {};
40
+ if (!fs.existsSync('.prizmkit/scripts/run-python-hook.cjs')
41
+ || !fs.existsSync('.prizmkit/scripts/post-command-prizm-drift.py')) return {};
42
+
43
+ const result = spawnSync(
44
+ process.execPath,
45
+ ['.prizmkit/scripts/run-python-hook.cjs', '.prizmkit/scripts/post-command-prizm-drift.py'],
46
+ {
47
+ cwd: process.cwd(),
48
+ env: {
49
+ ...process.env,
50
+ CLAUDE_TOOL_INPUT: JSON.stringify(toolInput),
51
+ },
52
+ encoding: 'utf8',
53
+ timeout: 25000,
54
+ windowsHide: true,
55
+ },
56
+ );
57
+ const context = String(result.stdout || '').trim();
58
+ return context ? { additional_context: context } : {};
59
+ }
60
+
61
+ const input = readInput();
62
+ const operation = process.argv[2] || '';
63
+ if (operation === 'session-start') writeOutput(sessionStart(input));
64
+ else if (operation === 'post-tool-use') writeOutput(postToolUse(input));
65
+ else writeOutput({});
@@ -0,0 +1,139 @@
1
+ /** Merge PrizmKit-owned Cursor project hooks without replacing user hooks. */
2
+ import { existsSync, mkdirSync } from 'node:fs';
3
+ import { copyFile, readFile, rm, writeFile } from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { HOOK_SCRIPT, HOOKS_FILE, HOOKS_OWNERSHIP_MARKER } from './paths.js';
7
+
8
+ export const MANAGED_HOOK_MARKER = '.cursor/hooks/prizmkit-hook.cjs';
9
+
10
+ const MANAGED_HOOKS = {
11
+ sessionStart: [
12
+ {
13
+ command: `node ${MANAGED_HOOK_MARKER} session-start`,
14
+ timeout: 10,
15
+ },
16
+ ],
17
+ postToolUse: [
18
+ {
19
+ command: `node ${MANAGED_HOOK_MARKER} post-tool-use`,
20
+ matcher: 'Shell',
21
+ timeout: 30,
22
+ },
23
+ ],
24
+ };
25
+
26
+ function isObject(value) {
27
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
28
+ }
29
+
30
+ function isManagedHook(entry) {
31
+ try {
32
+ return JSON.stringify(entry).includes(MANAGED_HOOK_MARKER);
33
+ } catch {
34
+ return false;
35
+ }
36
+ }
37
+
38
+ export function mergeCursorHooks(existing = {}, managedHooks = MANAGED_HOOKS) {
39
+ if (!isObject(existing)) {
40
+ throw new Error('Cannot preserve malformed Cursor hooks: root must be an object');
41
+ }
42
+ if (existing.version !== undefined && existing.version !== 1) {
43
+ throw new Error(`Cannot preserve unsupported Cursor hooks schema version: ${existing.version}`);
44
+ }
45
+ if (existing.hooks !== undefined && !isObject(existing.hooks)) {
46
+ throw new Error('Cannot preserve malformed Cursor hooks: hooks must be an object');
47
+ }
48
+
49
+ const hooks = {};
50
+ for (const [event, entries] of Object.entries(existing.hooks || {})) {
51
+ if (!Array.isArray(entries)) {
52
+ throw new Error(`Cannot preserve malformed Cursor hooks: ${event} must be an array`);
53
+ }
54
+ hooks[event] = entries.filter(entry => !isManagedHook(entry));
55
+ }
56
+ for (const [event, entries] of Object.entries(managedHooks)) {
57
+ hooks[event] = [...(hooks[event] || []), ...entries];
58
+ }
59
+ return { ...existing, version: 1, hooks };
60
+ }
61
+
62
+ export function removeManagedCursorHooks(existing = {}) {
63
+ if (!isObject(existing)) {
64
+ throw new Error('Cannot preserve malformed Cursor hooks: root must be an object');
65
+ }
66
+ if (existing.version !== undefined && existing.version !== 1) {
67
+ throw new Error(`Cannot preserve unsupported Cursor hooks schema version: ${existing.version}`);
68
+ }
69
+ if (existing.hooks !== undefined && !isObject(existing.hooks)) {
70
+ throw new Error('Cannot preserve malformed Cursor hooks: hooks must be an object');
71
+ }
72
+
73
+ const hooks = {};
74
+ for (const [event, entries] of Object.entries(existing.hooks || {})) {
75
+ if (!Array.isArray(entries)) {
76
+ throw new Error(`Cannot preserve malformed Cursor hooks: ${event} must be an array`);
77
+ }
78
+ const preserved = entries.filter(entry => !isManagedHook(entry));
79
+ if (preserved.length || entries.length === 0) hooks[event] = preserved;
80
+ }
81
+ const next = { ...existing, hooks };
82
+ if (Object.keys(hooks).length === 0) delete next.hooks;
83
+ return next;
84
+ }
85
+
86
+ async function readCursorHooks(hooksPath) {
87
+ if (!existsSync(hooksPath)) return {};
88
+ try {
89
+ return JSON.parse(await readFile(hooksPath, 'utf8'));
90
+ } catch (error) {
91
+ throw new Error(`Cannot preserve malformed Cursor hooks at .cursor/hooks.json: ${error.message}`);
92
+ }
93
+ }
94
+
95
+ export async function installHooks(targetRoot) {
96
+ const hooksPath = path.join(targetRoot, HOOKS_FILE);
97
+ const scriptPath = path.join(targetRoot, HOOK_SCRIPT);
98
+ const ownershipPath = path.join(targetRoot, HOOKS_OWNERSHIP_MARKER);
99
+ const assetPath = fileURLToPath(new URL('./assets/prizmkit-hook.cjs', import.meta.url));
100
+ const hooksFileExisted = existsSync(hooksPath);
101
+ const merged = mergeCursorHooks(await readCursorHooks(hooksPath));
102
+
103
+ mkdirSync(path.dirname(hooksPath), { recursive: true });
104
+ mkdirSync(path.dirname(scriptPath), { recursive: true });
105
+ await writeFile(hooksPath, `${JSON.stringify(merged, null, 2)}\n`);
106
+ if (!hooksFileExisted) await writeFile(ownershipPath, 'PrizmKit created .cursor/hooks.json\n');
107
+ await copyFile(assetPath, scriptPath);
108
+ }
109
+
110
+ export async function removeHooks(targetRoot, dryRun = false) {
111
+ const hooksPath = path.join(targetRoot, HOOKS_FILE);
112
+ const scriptPath = path.join(targetRoot, HOOK_SCRIPT);
113
+ const ownershipPath = path.join(targetRoot, HOOKS_OWNERSHIP_MARKER);
114
+ const affected = [];
115
+
116
+ if (existsSync(hooksPath)) {
117
+ const existing = await readCursorHooks(hooksPath);
118
+ const next = removeManagedCursorHooks(existing);
119
+ const remainingKeys = Object.keys(next).filter(key => key !== 'version');
120
+ const removeCreatedFile = remainingKeys.length === 0 && existsSync(ownershipPath);
121
+ if (removeCreatedFile || JSON.stringify(next) !== JSON.stringify(existing)) {
122
+ affected.push({ path: HOOKS_FILE, action: removeCreatedFile ? 'removed' : 'updated' });
123
+ if (!dryRun) {
124
+ if (removeCreatedFile) await rm(hooksPath, { force: true });
125
+ else await writeFile(hooksPath, `${JSON.stringify(next, null, 2)}\n`);
126
+ }
127
+ }
128
+ }
129
+
130
+ if (existsSync(scriptPath)) {
131
+ affected.push({ path: HOOK_SCRIPT, action: 'removed' });
132
+ if (!dryRun) await rm(scriptPath, { force: true });
133
+ }
134
+ if (existsSync(ownershipPath)) {
135
+ affected.push({ path: HOOKS_OWNERSHIP_MARKER, action: 'removed' });
136
+ if (!dryRun) await rm(ownershipPath, { force: true });
137
+ }
138
+ return affected;
139
+ }
@@ -0,0 +1,11 @@
1
+ /** Cursor platform path constants and conventions. */
2
+ export const PLATFORM_ID = 'cursor';
3
+ export const CLI_COMMAND = 'agent';
4
+ export const SKILLS_DIR = '.cursor/skills';
5
+ export const RULES_DIR = '.cursor/rules';
6
+ export const HOOKS_FILE = '.cursor/hooks.json';
7
+ export const HOOK_SCRIPT = '.cursor/hooks/prizmkit-hook.cjs';
8
+ export const HOOKS_OWNERSHIP_MARKER = '.cursor/hooks/.prizmkit-created-hooks-json';
9
+ export const FRAMEWORK_RULE_FILE = 'prizmkit-framework.mdc';
10
+ export const SKILL_DEFINITION_FILE = 'SKILL.md';
11
+ export const SKILL_DIR_VAR = '${SKILL_DIR}';
@@ -0,0 +1,49 @@
1
+ /** Convert canonical PrizmKit guidance to Cursor project Rules. */
2
+ import { mkdirSync } from 'node:fs';
3
+ import { writeFile } from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import { parseFrontmatter, buildMarkdown } from '../shared/frontmatter.js';
6
+ import { FRAMEWORK_RULE_FILE } from './paths.js';
7
+
8
+ export function convertToMdc(markdown, fallbackDescription) {
9
+ const { frontmatter, body } = parseFrontmatter(markdown);
10
+ const description = String(frontmatter.description || fallbackDescription || 'PrizmKit project guidance');
11
+ return buildMarkdown(
12
+ {
13
+ description,
14
+ alwaysApply: true,
15
+ },
16
+ body,
17
+ );
18
+ }
19
+
20
+ export async function installRules(targetRoot, ruleFiles) {
21
+ const rulesDir = path.join(targetRoot, '.cursor', 'rules');
22
+ mkdirSync(rulesDir, { recursive: true });
23
+ for (const rule of ruleFiles) {
24
+ const baseName = path.basename(rule.name);
25
+ await writeFile(
26
+ path.join(rulesDir, `${baseName}.mdc`),
27
+ convertToMdc(rule.content, rule.name),
28
+ );
29
+ }
30
+ }
31
+
32
+ export async function installFrameworkGuidance(targetRoot, templateContent) {
33
+ const rulesDir = path.join(targetRoot, '.cursor', 'rules');
34
+ mkdirSync(rulesDir, { recursive: true });
35
+ const body = templateContent.replace(
36
+ '### Available Commands\nRun `/prizmkit` to see all available PrizmKit commands.',
37
+ `### Available PrizmKit Skills
38
+ Cursor discovers project Agent Skills from \`.cursor/skills/\`. Invoke them with \`/<name>\` (for example \`/prizmkit-plan\`).
39
+
40
+ - Start with \`/prizmkit\` to see all available PrizmKit skills.
41
+ - Skill assets and references live inside each \`.cursor/skills/<skill>/\` directory.
42
+ - PrizmKit behavioral rules live in \`.cursor/rules/\`; read the relevant Rule before commit, documentation, or context-loading work.
43
+ `,
44
+ );
45
+ await writeFile(
46
+ path.join(rulesDir, FRAMEWORK_RULE_FILE),
47
+ convertToMdc(body, 'PrizmKit framework guidance for Cursor project sessions'),
48
+ );
49
+ }
@@ -0,0 +1,27 @@
1
+ /** Convert canonical PrizmKit Skills to Cursor project Agent Skills. */
2
+ import { parseFrontmatter, buildMarkdown } from '../shared/frontmatter.js';
3
+
4
+ function applyCursorInteractionCompatibility(content) {
5
+ const fallback = 'Use Cursor\'s Ask Questions capability when it is available. If it is unavailable in the current surface, ask the same question directly in chat and wait for explicit user input. Tool unavailability is not permission to choose defaults.';
6
+ return content
7
+ .replace(/\bAskUserQuestion\b/g, "Cursor's Ask Questions capability")
8
+ .replace(
9
+ /Do NOT render options as plain text — the user must be able to click\/select\./g,
10
+ fallback,
11
+ )
12
+ .replace(
13
+ /Do NOT render options as plain text \(e\.g\., `\[A\] option \[B\] option`\) — the user must be able to click\/select, not type a letter\./g,
14
+ fallback,
15
+ );
16
+ }
17
+
18
+ export function convertSkill(skillContent, skillName) {
19
+ const { frontmatter, body } = parseFrontmatter(skillContent);
20
+ if (!frontmatter.name) frontmatter.name = skillName;
21
+
22
+ const convertedBody = applyCursorInteractionCompatibility(body)
23
+ .replace(/\$\{SKILL_DIR\}/g, `.cursor/skills/${skillName}`);
24
+ const note = `> Cursor project install: Cursor discovers this Agent Skill from \`.cursor/skills/${skillName}/SKILL.md\`. Invoke it as \`/${skillName}\` when manual invocation is needed.\n>\n> Cursor interaction compatibility: use Cursor's Ask Questions capability when available. If the current Cursor surface does not expose it, ask the same required question directly in chat and wait for explicit user input. Tool unavailability is not permission to choose defaults. Only true headless runs with no conversational user may use documented conservative defaults.\n\n`;
25
+
26
+ return buildMarkdown(frontmatter, note + convertedBody);
27
+ }
@@ -8,7 +8,7 @@ Autonomous development pipeline that drives iterative AI CLI sessions through Pr
8
8
 
9
9
  - Python 3.8+
10
10
  - [jq](https://jqlang.github.io/jq/) (`brew install jq`)
11
- - AI CLI in PATH: CodeBuddy (`cbc`), Claude Code (`claude`), or Codex (`codex`)
11
+ - AI CLI in PATH: CodeBuddy (`cbc`), Claude Code (`claude`), Codex (`codex`), Pi (`pi`), or verified Cursor Agent (`agent`)
12
12
  - `.prizmkit/plans/feature-list.json` generated by the `feature-planner` skill (for feature pipeline)
13
13
  - `.prizmkit/plans/bug-fix-list.json` generated by the `bug-planner` skill (for bug pipeline)
14
14
 
@@ -461,7 +461,7 @@ python3 scripts/detect-stuck.py \
461
461
 
462
462
  ### `scripts/parse-stream-progress.py` — Real-Time Progress Parser
463
463
 
464
- Reads AI CLI `stream-json` output and extracts progress metrics.
464
+ Reads provider JSONL output and extracts progress metrics. Cursor support recognizes `system`, `user`, `assistant`, `tool_call`, and terminal `result` events, including read/write/function tool variants and additive unknown fields.
465
465
 
466
466
  ```bash
467
467
  python3 scripts/parse-stream-progress.py \
@@ -550,8 +550,8 @@ Also exports: `log_info`, `log_warn`, `log_error`, `log_success` (with timestamp
550
550
 
551
551
  | Variable | Default | Used By | Description |
552
552
  |----------|---------|---------|-------------|
553
- | `AI_CLI` | auto-detect | Python runtime | AI CLI command name. Auto-detects `cbc`, `claude`, or `codex` |
554
- | `PRIZMKIT_PLATFORM` | auto-detect | Python runtime | Platform hint for custom/wrapped AI CLI commands: `codebuddy`, `claude`, or `codex` |
553
+ | `AI_CLI` | auto-detect | Python runtime | AI CLI command name. Auto-detects `cbc`, `claude`, `codex`, `pi`, or verified Cursor `agent` |
554
+ | `PRIZMKIT_PLATFORM` | auto-detect | Python runtime | Platform hint for custom/wrapped AI CLI commands: `codebuddy`, `claude`, `codex`, `pi`, or `cursor` |
555
555
  | `MODEL` | (none) | cli.py run feature, cli.py run bugfix | AI model fallback. Overridden by per-feature `model` field. See [Model Selection](#model-selection) |
556
556
  | `CODEBUDDY_CLI` | (deprecated) | Python runtime | Legacy alias for `AI_CLI`. Prefer `AI_CLI` |
557
557
  | `VERBOSE` | `0` | cli.py run feature | Set to `1` to enable `--verbose` on AI CLI |
@@ -647,7 +647,7 @@ The pipeline auto-detects which AI CLI to use. Detection priority:
647
647
  3. `.prizmkit/manifest.json` or `.prizmkit/config.json` → `platform` field
648
648
  4. `CODEBUDDY_CLI` environment variable (legacy)
649
649
  5. Installed PrizmKit platform artifacts
650
- 6. PATH fallback: `claude` → `cbc` → `codex`
650
+ 6. PATH fallback: `claude` → `cbc` → `codex` → `pi` → verified Cursor `agent`
651
651
 
652
652
  To permanently configure, create `.prizmkit/config.json`:
653
653
 
@@ -670,8 +670,21 @@ AI_CLI=claude python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plan
670
670
  python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
671
671
  MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
672
672
  AI_CLI=cbc python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
673
+ AI_CLI=agent python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
673
674
  ```
674
675
 
676
+ ### Cursor Agent native headless contract
677
+
678
+ Install Cursor Agent separately (`curl https://cursor.com/install -fsS | bash` on macOS/Linux/WSL, or `irm 'https://cursor.com/install?win32=true' | iex` in native Windows PowerShell). Verify and authenticate with `agent --version`, `agent login`, and `agent status`; update with `agent update`. Because `agent` is a generic executable name, PATH fallback verifies Cursor identity and the required help flags before selecting it.
679
+
680
+ For a Pipeline session, PrizmKit runs:
681
+
682
+ ```bash
683
+ agent --print --force --trust --output-format stream-json [--model <model>]
684
+ ```
685
+
686
+ The complete coordinator Prompt is sent through stdin and the active task checkout is the process `cwd`. PrizmKit does not pass Cursor `--worktree`, does not disable Cursor sandbox policy, and does not create or modify `.cursor/cli.json`; user and enterprise deny policy continues to apply. Authentication is inherited from `agent login` or `CURSOR_API_KEY`, never serialized into PrizmKit config, argv, or logs. Cursor exposes no documented effort parameter, so `PRIZMKIT_EFFORT` must remain unset for `AI_CLI=agent`; a non-empty value fails with an actionable diagnostic.
687
+
675
688
  ---
676
689
 
677
690
  ## How It Works
@@ -9,10 +9,7 @@ from dataclasses import dataclass, field
9
9
  from pathlib import Path, PurePosixPath
10
10
  from typing import Any, Mapping
11
11
 
12
- from .test_result import (
13
- valid_legacy_test_artifact_pair,
14
- valid_test_artifact_pair,
15
- )
12
+ from .test_result import valid_test_artifact_pair
16
13
 
17
14
  VALID_CHECKPOINT_STATUSES = {"pending", "in_progress", "completed", "skipped", "failed"}
18
15
  TERMINAL_STEP_STATUSES = {"completed", "skipped"}
@@ -771,19 +768,7 @@ def _derive_semantic_state(
771
768
  for step in steps
772
769
  if step.status == "completed"
773
770
  )
774
- completion_artifacts_valid = artifacts_valid or (
775
- legacy_sequence_valid
776
- and all(
777
- _required_step_artifacts_valid(
778
- step,
779
- checkpoint_path,
780
- project_root,
781
- allow_legacy_test=True,
782
- )
783
- for step in steps
784
- if step.status == "completed"
785
- )
786
- )
771
+ completion_artifacts_valid = artifacts_valid
787
772
  retrospective_step = _single_step(steps, "prizmkit-retrospective")
788
773
  retrospective_valid = bool(
789
774
  retrospective_step
@@ -923,8 +908,6 @@ def _required_step_artifacts_valid(
923
908
  step: CheckpointStep,
924
909
  checkpoint_path: Path | None,
925
910
  project_root: Path | None,
926
- *,
927
- allow_legacy_test: bool = False,
928
911
  ) -> bool:
929
912
  """Validate declared artifacts, including semantic test terminal output."""
930
913
  if step.skill == "prizmkit-test":
@@ -937,12 +920,7 @@ def _required_step_artifacts_valid(
937
920
  result_path = (root / results[0]).resolve()
938
921
  if not _is_within_root(report_path, root) or not _is_within_root(result_path, root):
939
922
  return False
940
- validator = (
941
- valid_legacy_test_artifact_pair
942
- if allow_legacy_test
943
- else valid_test_artifact_pair
944
- )
945
- return validator(
923
+ return valid_test_artifact_pair(
946
924
  report_path,
947
925
  result_path,
948
926
  required_result="TEST_PASS",
@@ -6,6 +6,7 @@ import json
6
6
  import os
7
7
  import shlex
8
8
  import shutil
9
+ import subprocess
9
10
  from collections.abc import Mapping
10
11
  from dataclasses import dataclass
11
12
  from pathlib import Path
@@ -77,6 +78,7 @@ AI_CLIENT_PRECEDENCE = (
77
78
  "PATH:cbc",
78
79
  "PATH:codex",
79
80
  "PATH:pi",
81
+ "PATH:agent",
80
82
  )
81
83
 
82
84
  _EFFORT_VALUES_BY_PLATFORM = {
@@ -84,6 +86,7 @@ _EFFORT_VALUES_BY_PLATFORM = {
84
86
  "codex": ("low", "medium", "high", "xhigh"),
85
87
  "codebuddy": ("low", "medium", "high", "xhigh"),
86
88
  "pi": ("off", "minimal", "low", "medium", "high", "xhigh", "max"),
89
+ "cursor": (),
87
90
  }
88
91
 
89
92
 
@@ -173,27 +176,40 @@ def _cli_names_for_platform(platform: str | None) -> tuple[str, ...]:
173
176
  return ("cbc",)
174
177
  if normalized == "pi":
175
178
  return ("pi",)
179
+ if normalized == "cursor":
180
+ return ("agent",)
176
181
  if normalized == "both":
177
182
  return ("claude", "cbc")
178
183
  if normalized == "all":
179
- return ("codex", "claude", "cbc", "pi")
184
+ return ("codex", "claude", "cbc", "pi", "agent")
180
185
  return ()
181
186
 
182
187
 
183
188
  def _known_platform_from_cli(cli_command: str | None) -> str | None:
184
- if not cli_command:
189
+ if not cli_command or not cli_command.strip():
185
190
  return None
186
- try:
187
- token = shlex.split(cli_command)[0]
188
- except ValueError:
189
- token = cli_command.split()[0].strip("'\"")
190
- name = Path(token).name.lower()
191
+ raw = cli_command.strip()
192
+ unquoted = raw[1:-1] if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in "'\"" else raw
193
+ if len(unquoted) >= 3 and unquoted[1:3] in {":\\", ":/"} and unquoted.lower().endswith((".exe", ".cmd", ".bat")):
194
+ token = unquoted
195
+ else:
196
+ try:
197
+ token = shlex.split(raw)[0]
198
+ except (ValueError, IndexError):
199
+ token = raw.split()[0].strip("'\"")
200
+ name = token.replace("\\", "/").rsplit("/", 1)[-1].lower()
201
+ for suffix in (".exe", ".cmd", ".bat"):
202
+ if name.endswith(suffix):
203
+ name = name[: -len(suffix)]
204
+ break
191
205
  if name == "claude":
192
206
  return "claude"
193
207
  if name == "codex":
194
208
  return "codex"
195
209
  if name == "pi":
196
210
  return "pi"
211
+ if name == "agent":
212
+ return "cursor"
197
213
  if name in {"cbc", "codebuddy"}:
198
214
  return "codebuddy"
199
215
  return None
@@ -201,13 +217,42 @@ def _known_platform_from_cli(cli_command: str | None) -> str | None:
201
217
 
202
218
  def _concrete_platform(platform: str | None) -> str | None:
203
219
  normalized = _normalize_platform(platform)
204
- return normalized if normalized in {"claude", "codebuddy", "codex", "pi"} else None
220
+ return normalized if normalized in {"claude", "codebuddy", "codex", "pi", "cursor"} else None
221
+
222
+
223
+ def _cursor_agent_is_verified(executable: str) -> bool:
224
+ """Verify the generic `agent` executable with safe Cursor version/help probes."""
225
+ outputs: list[str] = []
226
+ for argument in ("--version", "--help"):
227
+ try:
228
+ completed = subprocess.run(
229
+ [executable, argument],
230
+ text=True,
231
+ stdout=subprocess.PIPE,
232
+ stderr=subprocess.STDOUT,
233
+ check=False,
234
+ timeout=5,
235
+ )
236
+ except (OSError, subprocess.SubprocessError):
237
+ return False
238
+ if completed.returncode != 0:
239
+ return False
240
+ outputs.append(completed.stdout or "")
241
+ version_output, help_output = outputs
242
+ identity = f"{version_output}\n{help_output}".lower()
243
+ required = ("--print", "--force", "--trust", "--output-format")
244
+ return "cursor" in identity and all(flag in help_output for flag in required)
205
245
 
206
246
 
207
247
  def _resolve_cli_name(cli_name: str, env: Mapping[str, str]) -> str | None:
208
248
  if cli_name == "cbc" and env.get("CODEBUDDY_CLI"):
209
249
  return env["CODEBUDDY_CLI"]
210
- return cli_name if shutil.which(cli_name, path=env.get("PATH", "")) else None
250
+ resolved = shutil.which(cli_name, path=env.get("PATH", ""))
251
+ if not resolved:
252
+ return None
253
+ if cli_name == "agent" and not _cursor_agent_is_verified(resolved):
254
+ return None
255
+ return cli_name
211
256
 
212
257
 
213
258
  def _cli_for_platform(platform: str | None, env: Mapping[str, str]) -> str | None:
@@ -291,6 +336,10 @@ def _installed_platform_cli(
291
336
  resolved = _resolve_cli_name("cbc", env)
292
337
  if resolved:
293
338
  return resolved, "installed-platform:codebuddy"
339
+ if (paths.project_root / ".cursor" / "skills" / "prizmkit" / "SKILL.md").is_file():
340
+ resolved = _resolve_cli_name("agent", env)
341
+ if resolved:
342
+ return resolved, "installed-platform:cursor"
294
343
  return None, None
295
344
 
296
345
 
@@ -389,7 +438,7 @@ def _resolve_ai_client(paths: RuntimePaths, env: Mapping[str, str]) -> AIClientR
389
438
  precedence=AI_CLIENT_PRECEDENCE,
390
439
  )
391
440
 
392
- for candidate in ("claude", "cbc", "codex", "pi"):
441
+ for candidate in ("claude", "cbc", "codex", "pi", "agent"):
393
442
  resolved = _resolve_cli_name(candidate, env)
394
443
  if resolved:
395
444
  return AIClientResolution(
@@ -435,11 +484,18 @@ def validate_effort(effort: str | None, platform: str | None) -> EffortValidatio
435
484
  "codex": "Codex",
436
485
  "codebuddy": "CodeBuddy",
437
486
  "pi": "Pi",
487
+ "cursor": "Cursor Agent CLI",
438
488
  }.get(_concrete_platform(platform) or "codebuddy", "CodeBuddy")
439
- message = (
440
- f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
441
- f"({label}). Supported values for {label}: {', '.join(supported)}"
442
- )
489
+ if not supported:
490
+ message = (
491
+ f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
492
+ f"({label}). Cursor Agent CLI exposes no documented effort parameter; leave PRIZMKIT_EFFORT unset."
493
+ )
494
+ else:
495
+ message = (
496
+ f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
497
+ f"({label}). Supported values for {label}: {', '.join(supported)}"
498
+ )
443
499
  return EffortValidationResult(
444
500
  effort=normalized_effort,
445
501
  platform=_concrete_platform(platform),
@@ -465,6 +521,7 @@ def load_runtime_config(paths: RuntimePaths, env: Mapping[str, str] | None = Non
465
521
  paths.project_root / ".claude",
466
522
  paths.project_root / ".codex",
467
523
  paths.project_root / ".pi",
524
+ paths.project_root / ".cursor",
468
525
  ),
469
526
  path_entries=_path_entries(runtime_env),
470
527
  sources=("environment", "prizmkit-env", "prizmkit-config", "installed-platform-markers", "PATH"),