@open-product-primer/cli 0.4.1 → 0.7.0

package/dist/commands/doctor.js

@@ -189,6 +189,8 @@ function doctorCommand() {
             for (const entry of betEntries) {
                 if (!entry.isDirectory())
                     continue;
+                if (entry.name === 'archived')
+                    continue;
                 const betDir = path.join(betsDir, entry.name);
                 const hasDecision = fs.existsSync(path.join(betDir, 'bet-decision.md'));
                 if (!hasDecision)

package/dist/commands/init.js

@@ -113,12 +113,14 @@ function initCommand() {
         }
         else {
             let specFramework = 'openspec';
+            let pdrSurfacing = false;
             if (selectedAgents.includes('claude')) {
                 specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
+                pdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
             }
             console.log('\n' + chalk_1.default.bold('Installing agent skills...'));
             for (const agent of selectedAgents) {
-                (0, install_agent_1.installAgentSkills)(agent, projectRoot, specFramework);
+                (0, install_agent_1.installAgentSkills)(agent, projectRoot, specFramework, pdrSurfacing);
             }
             console.log('\n' + chalk_1.default.green('✓') + ` Agent skills installed: ${selectedAgents.join(', ')}`);
         }

package/dist/commands/update.js

@@ -51,11 +51,13 @@ function updateCommand() {
         const configAgents = (0, detect_1.readAgentsFromConfig)(projectRoot);
         if (configAgents !== null && configAgents.length > 0) {
             let specFramework = 'openspec';
+            let pdrSurfacing = false;
             if (configAgents.includes('claude')) {
                 specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
+                pdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
             }
             for (const agent of configAgents) {
-                (0, install_agent_1.installAgentSkills)(agent, projectRoot, specFramework);
+                (0, install_agent_1.installAgentSkills)(agent, projectRoot, specFramework, pdrSurfacing);
             }
             console.log(`\nAgent skills updated: ${configAgents.join(', ')}`);
         }
@@ -64,7 +66,8 @@ function updateCommand() {
             const legacyAgents = [];
             if (fs.existsSync(path.join(projectRoot, '.claude'))) {
                 const specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
-                (0, install_agent_1.installAgentSkills)('claude', projectRoot, specFramework);
+                const pdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
+                (0, install_agent_1.installAgentSkills)('claude', projectRoot, specFramework, pdrSurfacing);
                 legacyAgents.push('claude');
             }
             if (fs.existsSync(path.join(projectRoot, '.cursor'))) {
@@ -98,12 +101,14 @@ function updateCommand() {
             return;
         }
         let addSpecFramework = 'openspec';
+        let addPdrSurfacing = false;
         if (selected.includes('claude')) {
             addSpecFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
+            addPdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
         }
         console.log('\n' + chalk_1.default.bold('Installing agent skills...'));
         for (const agent of selected) {
-            (0, install_agent_1.installAgentSkills)(agent, projectRoot, addSpecFramework);
+            (0, install_agent_1.installAgentSkills)(agent, projectRoot, addSpecFramework, addPdrSurfacing);
         }
         const merged = Array.from(new Set([...currentAgents, ...selected]));
         (0, detect_1.writeAgentsToConfig)(merged, projectRoot);

package/dist/lib/detect.js

@@ -68,6 +68,10 @@ function detectAvailableAgents(projectRoot) {
         detected.push('claude');
     if (fs.existsSync(path.join(projectRoot, '.cursor')))
         detected.push('cursor');
+    if (fs.existsSync(path.join(projectRoot, 'AGENTS.md')))
+        detected.push('codex');
+    if (fs.existsSync(path.join(projectRoot, 'GEMINI.md')))
+        detected.push('gemini');
     return detected;
 }
 function writeAgentsToConfig(agents, projectRoot) {

package/dist/lib/install-agent.d.ts

@@ -1,9 +1,14 @@
-export type Agent = 'claude' | 'cursor';
+export type Agent = 'claude' | 'cursor' | 'codex' | 'gemini';
 export declare const SUPPORTED_AGENTS: readonly Agent[];
 export declare function promptFrameworkSelection(projectRoot: string): Promise<string>;
 export declare function promptAgentSelection(projectRoot: string): Promise<string[]>;
-export declare function installAgentSkills(agent: Agent, projectRoot: string, framework?: string): void;
+export declare function promptPdrSurfacing(): Promise<boolean>;
+export declare function installAgentSkills(agent: Agent, projectRoot: string, framework?: string, pdrSurfacing?: boolean): void;
+export declare const OPRIM_CONTEXT_SKILL_STEP = "## Step 0: Check relevant product decisions\nInvoke the `oprim:context` skill using the Skill tool. If matching PDRs are surfaced, review them before proceeding. If no PDRs match or `oprim/decisions/` is empty, the skill exits silently \u2014 continue to Step 1 immediately.";
 export declare const CLAUDE_SKILLS: Record<string, string>;
 export declare const CLAUDE_COMMANDS: Record<string, string>;
 export declare const CURSOR_SKILLS: Record<string, string>;
 export declare const CURSOR_COMMANDS: Record<string, string>;
+export declare function writeAgentInstructionFile(filePath: string, section: string): void;
+export declare function codexInstructions(): string;
+export declare function geminiInstructions(): string;

package/dist/lib/install-agent.js

@@ -36,16 +36,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CURSOR_COMMANDS = exports.CURSOR_SKILLS = exports.CLAUDE_COMMANDS = exports.CLAUDE_SKILLS = exports.SUPPORTED_AGENTS = void 0;
+exports.CURSOR_COMMANDS = exports.CURSOR_SKILLS = exports.CLAUDE_COMMANDS = exports.CLAUDE_SKILLS = exports.OPRIM_CONTEXT_SKILL_STEP = exports.SUPPORTED_AGENTS = void 0;
 exports.promptFrameworkSelection = promptFrameworkSelection;
 exports.promptAgentSelection = promptAgentSelection;
+exports.promptPdrSurfacing = promptPdrSurfacing;
 exports.installAgentSkills = installAgentSkills;
+exports.writeAgentInstructionFile = writeAgentInstructionFile;
+exports.codexInstructions = codexInstructions;
+exports.geminiInstructions = geminiInstructions;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const chalk_1 = __importDefault(require("chalk"));
 const scaffold_1 = require("./scaffold");
 const detect_1 = require("./detect");
-exports.SUPPORTED_AGENTS = ['claude', 'cursor'];
+exports.SUPPORTED_AGENTS = ['claude', 'cursor', 'codex', 'gemini'];
 async function promptFrameworkSelection(projectRoot) {
     const configPath = path.join(projectRoot, '.claude', 'hooks', 'config.json');
     if (fs.existsSync(configPath)) {
@@ -81,18 +85,53 @@ async function promptAgentSelection(projectRoot) {
         choices: [
             { name: 'Claude Code', value: 'claude', checked: detected.includes('claude') },
             { name: 'Cursor', value: 'cursor', checked: detected.includes('cursor') },
+            { name: 'Codex', value: 'codex', checked: detected.includes('codex') },
+            { name: 'Gemini CLI', value: 'gemini', checked: detected.includes('gemini') },
         ],
     });
 }
-function installAgentSkills(agent, projectRoot, framework = 'openspec') {
+async function promptPdrSurfacing() {
+    const { confirm } = await Promise.resolve().then(() => __importStar(require('@inquirer/prompts')));
+    return confirm({ message: 'Enable proactive PDR surfacing in skills? (y/N)', default: false });
+}
+function installAgentSkills(agent, projectRoot, framework = 'openspec', pdrSurfacing = false) {
     if (agent === 'claude') {
         const claudeDir = path.join(projectRoot, '.claude');
         const dirCreated = !fs.existsSync(claudeDir);
         const skillsBase = path.join(claudeDir, 'skills');
+        // oprim:context skill — install when opted in, remove when opted out
+        const contextSkillPath = path.join(skillsBase, 'oprim:context', 'SKILL.md');
+        if (pdrSurfacing) {
+            (0, scaffold_1.writeFile)(contextSkillPath, oprimContextSkill());
+            console.log(chalk_1.default.green('✓') + ' .claude/skills/oprim:context/SKILL.md');
+        }
+        else if (fs.existsSync(contextSkillPath)) {
+            fs.unlinkSync(contextSkillPath);
+            try {
+                fs.rmdirSync(path.dirname(contextSkillPath));
+            }
+            catch { /* not empty or already gone */ }
+            console.log(chalk_1.default.dim('  removed .claude/skills/oprim:context/SKILL.md'));
+        }
+        // oprim skills — prepend Step 0 when opted in
         for (const [name, content] of Object.entries(exports.CLAUDE_SKILLS)) {
-            (0, scaffold_1.writeFile)(path.join(skillsBase, name, 'SKILL.md'), content);
+            const skillContent = pdrSurfacing ? withContextStep(content) : content;
+            (0, scaffold_1.writeFile)(path.join(skillsBase, name, 'SKILL.md'), skillContent);
             console.log(chalk_1.default.green('✓') + ` .claude/skills/${name}/SKILL.md`);
         }
+        // openspec skills — add/remove Step 0 in-place when they exist
+        for (const name of OPENSPEC_SKILL_NAMES) {
+            const skillFilePath = path.join(skillsBase, name, 'SKILL.md');
+            if (fs.existsSync(skillFilePath)) {
+                const current = fs.readFileSync(skillFilePath, 'utf-8');
+                const updated = pdrSurfacing ? addContextStepToFile(current) : removeContextStepFromFile(current);
+                if (updated !== current) {
+                    fs.writeFileSync(skillFilePath, updated, 'utf-8');
+                    console.log(chalk_1.default.green('✓') +
+                        ` .claude/skills/${name}/SKILL.md (PDR surfacing ${pdrSurfacing ? 'enabled' : 'disabled'})`);
+                }
+            }
+        }
         const cmdsDir = path.join(claudeDir, 'commands', 'oprim');
         for (const [filename, content] of Object.entries(exports.CLAUDE_COMMANDS)) {
             (0, scaffold_1.writeFile)(path.join(cmdsDir, filename), content);
@@ -131,6 +170,16 @@ function installAgentSkills(agent, projectRoot, framework = 'openspec') {
             console.log(chalk_1.default.dim('  .claude/ created — Claude Code will discover these files automatically.'));
         }
     }
+    else if (agent === 'codex') {
+        const agentsFile = path.join(projectRoot, 'AGENTS.md');
+        writeAgentInstructionFile(agentsFile, codexInstructions());
+        console.log(chalk_1.default.green('✓') + ' AGENTS.md (oprim section written)');
+    }
+    else if (agent === 'gemini') {
+        const geminiFile = path.join(projectRoot, 'GEMINI.md');
+        writeAgentInstructionFile(geminiFile, geminiInstructions());
+        console.log(chalk_1.default.green('✓') + ' GEMINI.md (oprim section written)');
+    }
     else if (agent === 'cursor') {
         const cursorDir = path.join(projectRoot, '.cursor');
         const dirCreated = !fs.existsSync(cursorDir);
@@ -149,6 +198,73 @@ function installAgentSkills(agent, projectRoot, framework = 'openspec') {
         }
     }
 }
+// ─── PDR context surfacing ────────────────────────────────────────────────────
+const CTX_STEP_START = '<!-- oprim:context:start -->';
+const CTX_STEP_END = '<!-- oprim:context:end -->';
+exports.OPRIM_CONTEXT_SKILL_STEP = `## Step 0: Check relevant product decisions
+Invoke the \`oprim:context\` skill using the Skill tool. If matching PDRs are surfaced, review them before proceeding. If no PDRs match or \`oprim/decisions/\` is empty, the skill exits silently — continue to Step 1 immediately.`;
+// Openspec skill names whose files are managed by the openspec CLI and modified in-place by oprim
+const OPENSPEC_SKILL_NAMES = [
+    'openspec-propose',
+    'openspec-apply-change',
+    'openspec-explore',
+    'openspec-archive-change',
+];
+// Insert Step 0 into an oprim skill string (written fresh each time — no markers needed)
+function withContextStep(content) {
+    const lines = content.split('\n');
+    let closingDash = -1;
+    let dashCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            dashCount++;
+            if (dashCount === 2) {
+                closingDash = i;
+                break;
+            }
+        }
+    }
+    if (closingDash === -1)
+        return exports.OPRIM_CONTEXT_SKILL_STEP + '\n\n' + content;
+    const front = lines.slice(0, closingDash + 1).join('\n');
+    const body = lines.slice(closingDash + 1).join('\n').trimStart();
+    return `${front}\n\n${exports.OPRIM_CONTEXT_SKILL_STEP}\n\n${body}`;
+}
+// Idempotently add Step 0 to an openspec skill file (read-modify-write)
+function addContextStepToFile(content) {
+    if (content.includes(CTX_STEP_START))
+        return content; // already present
+    const lines = content.split('\n');
+    let closingDash = -1;
+    let dashCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            dashCount++;
+            if (dashCount === 2) {
+                closingDash = i;
+                break;
+            }
+        }
+    }
+    const block = `${CTX_STEP_START}\n${exports.OPRIM_CONTEXT_SKILL_STEP}\n${CTX_STEP_END}`;
+    if (closingDash === -1)
+        return block + '\n\n' + content;
+    const front = lines.slice(0, closingDash + 1).join('\n');
+    const body = lines.slice(closingDash + 1).join('\n').trimStart();
+    return `${front}\n\n${block}\n\n${body}`;
+}
+// Remove Step 0 block from an openspec skill file (read-modify-write)
+function removeContextStepFromFile(content) {
+    const s = content.indexOf(CTX_STEP_START);
+    if (s === -1)
+        return content;
+    const e = content.indexOf(CTX_STEP_END, s);
+    if (e === -1)
+        return content;
+    const before = content.slice(0, s).trimEnd();
+    const after = content.slice(e + CTX_STEP_END.length).replace(/^\n+/, '\n');
+    return before + after;
+}
 // ─── Claude skill playbooks ───────────────────────────────────────────────────
 exports.CLAUDE_SKILLS = {
     'oprim-pdr': pdrSkill(),
@@ -471,6 +587,36 @@ The bet is preserved in full at the archive location.
 \`\`\`
 `;
 }
+function oprimContextSkill() {
+    return `---
+name: oprim:context
+description: Surface relevant product decisions from oprim/decisions/ by keyword-matching against the current conversation — invoke at the start of any oprim or openspec workflow when PDR surfacing is enabled
+---
+
+Scan \`oprim/decisions/\` and surface PDRs that match keywords from the current conversation.
+
+## Steps
+
+### 1. Check for decisions
+Scan \`oprim/decisions/\` for files matching \`PDR-*.md\`. If the directory is empty or contains no PDR files, exit silently — produce no output and return immediately.
+
+### 2. Extract keywords
+From the current conversation context, extract 3–10 topic keywords: bet IDs referenced (e.g. \`BET-007\`), capability names, filenames mentioned, subject-area nouns. Focus on the most specific and distinctive terms.
+
+### 3. Match PDRs
+For each PDR file: read the filename and the first 25 lines (to capture title, status, and context). A PDR is relevant if any keyword appears in the filename, title (\`# PDR-NNN: ...\`), or body text (case-insensitive).
+
+### 4. Report or exit silently
+If one or more PDRs match:
+
+**Relevant product decisions:**
+- PDR-NNN: <title> — <Status> (\`oprim/decisions/PDR-NNN-<slug>.md\`)
+
+List each match on its own line, then return — the invoking skill continues to its next step.
+
+If no PDRs match: exit silently — produce no output.
+`;
+}
 function archiveCommandContent() {
     return `Use the Skill tool to invoke the \`oprim-archive\` skill.`;
 }
@@ -707,3 +853,92 @@ Validate the primer sequencing board and suggest rebalancing if needed.
 6. **Suggest moves** — recommend bets to defer to \`next\` or \`later\` to resolve violations
 `;
 }
+// ─── Instruction-file helpers (Codex / Gemini CLI) ────────────────────────────
+const OPRIM_START = '<!-- oprim:start -->';
+const OPRIM_END = '<!-- oprim:end -->';
+function writeAgentInstructionFile(filePath, section) {
+    const delimited = `${OPRIM_START}\n${section}\n${OPRIM_END}`;
+    if (!fs.existsSync(filePath)) {
+        fs.writeFileSync(filePath, delimited + '\n', 'utf-8');
+        return;
+    }
+    const existing = fs.readFileSync(filePath, 'utf-8');
+    const startIdx = existing.indexOf(OPRIM_START);
+    const endIdx = existing.indexOf(OPRIM_END);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + OPRIM_END.length);
+        fs.writeFileSync(filePath, before + delimited + after, 'utf-8');
+    }
+    else {
+        const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+        fs.writeFileSync(filePath, existing + separator + delimited + '\n', 'utf-8');
+    }
+}
+function oprimWorkflowsInline() {
+    return `
+## oprim workflows
+
+### Bet authoring (oprim-bet)
+Create a new bet in \`oprim/bets/\` and register it on the sequencing board.
+
+1. Show naming tip: "verb + object [for context] — e.g. 'Improve bet naming for scannability'"
+2. Ask for the bet title. Validate: fewer than 4 words OR fewer than 25 chars → warn, suggest reformulation, ask "Proceed anyway? (y/N)".
+3. Assign next BET ID: scan \`oprim/bets/BET-(\\d+)\` dirs, max+1 zero-padded to 3 digits (default 001).
+4. Check \`oprim/sequence.yaml\` exists — stop if not, advise \`oprim init\`.
+5. Gather: decision (default Build now), owner, review date (YYYY-MM-DD), why now, alternatives, expected outcomes, kill criteria, PDR links.
+6. Write \`oprim/bets/BET-NNN/bet-decision.md\` with all fields.
+7. Append to \`oprim/sequence.yaml\` backlog: \`{id, title, blocked_by: [], unlocks: [], requires_pdrs: []}\`.
+8. Ask: "Scaffold a discovery.md now? (y/N)" — if "y", write \`oprim/bets/BET-NNN/discovery.md\`.
+9. Report what was created.
+
+### Criteria authoring (oprim-criteria)
+Create or append to \`oprim/bets/BET-NNN/criteria.yaml\`.
+
+1. Ask which bet (e.g. BET-042). Verify dir exists.
+2. Gather: metric ID (snake_case), name, baseline, target, timeframe, launch date, segment.
+3. Ask source type (amplitude / bigquery).
+   - Amplitude: event, aggregation (unique_users/event_count/property_sum), denominator_event.
+   - BigQuery: table, metric_column, filter, aggregation, denominator_query.
+4. If file exists: append to \`metrics\` list (never overwrite). If not: create.
+5. Ask if adding more metrics.
+6. Report what was created.
+
+### PDR authoring (oprim-pdr)
+Create a new Product Decision Record in \`oprim/decisions/\`.
+
+1. Ask for decision title.
+2. Assign next PDR ID: scan \`oprim/decisions/PDR-(\\d+)-\`, max+1 zero-padded to 3 digits (default 001).
+3. Gather: context, decision, alternatives, consequences, evidence, related bets/specs.
+4. Ask if superseding an existing PDR.
+5. Write \`oprim/decisions/PDR-NNN-<slug>.md\`. If superseding, update old PDR Status.
+6. Report what was created.
+
+### KPI review (oprim-review)
+Create a KPI review artifact in \`oprim/reviews/\`.
+
+1. Ask which bet (e.g. BET-042).
+2. Read \`oprim/bets/BET-NNN/criteria.yaml\` for pre-fill. Check \`oprim/bets/BET-NNN/measurements/\` for \`run-*.yaml\` — use most recent if present.
+3. If no run result, ask for each metric's actual value.
+4. Status: actual >= target → hit; actual < target → missed; not provided → pending.
+5. Ask reviewer name and decision quality notes.
+6. Write \`oprim/reviews/YYYY-MM-DD-BET-NNN-kpi.md\`.
+7. Report what was created.
+
+### Bet archiving (oprim-archive)
+Archive a completed bet.
+
+1. Ask for bet ID (accept bet-005, 005, 5, BET-005 — normalize to BET-NNN).
+2. Verify \`oprim/bets/BET-NNN/\` exists.
+3. Check \`oprim/sequence.yaml\` for entries where \`blocked_by\` or \`unlocks\` reference the target bet — warn if found, ask "Archive anyway? (y/N)".
+4. Move directory: \`oprim/bets/BET-NNN → oprim/bets/archived/BET-NNN\`.
+5. Remove the bet entry from \`oprim/sequence.yaml\`.
+6. Report what was done.
+`;
+}
+function codexInstructions() {
+    return oprimWorkflowsInline();
+}
+function geminiInstructions() {
+    return oprimWorkflowsInline();
+}

package/dist/lib/measure.js

@@ -230,10 +230,12 @@ async function runBigQueryMetric(sqlPath) {
 }
 // ─── Criteria scanner (used by doctor) ───────────────────────────────────────
 function scanCriteriaForSourceType(projectRoot, sourceType) {
-    const betsDir = path.join(projectRoot, 'primer', 'bets');
+    const betsDir = path.join(projectRoot, 'oprim', 'bets');
     if (!fs.existsSync(betsDir))
         return false;
     for (const entry of fs.readdirSync(betsDir)) {
+        if (entry === 'archived')
+            continue;
         const criteriaPath = path.join(betsDir, entry, 'criteria.yaml');
         if (!fs.existsSync(criteriaPath))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-product-primer/cli",
-  "version": "0.4.1",
+  "version": "0.7.0",
   "description": "Open Product Primer CLI — product decisions, sequencing, and KPI tracking for repositories",
   "keywords": [
     "product",