gsdd-cli 0.1.0

package/bin/adapters/claude.mjs

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const CLAUDE_MODEL_PROFILES = {
+  quality: 'opus',
+  balanced: 'sonnet',
+  budget: 'haiku',
+};
+
+function renderClaudePlanChecker(delegateContent, modelAlias = 'sonnet') {
+  return `---
+name: gsdd-plan-checker
+description: Fresh-context plan checker for GSDD plan drafts. Review-only; never edits plans directly.
+model: ${modelAlias}
+tools: Read, Grep, Glob
+---
+
+${delegateContent.trim()}
+`;
+}
+
+function renderClaudePlanSkill() {
+  return `---
+name: gsdd-plan
+description: Claude-native Phase planning with fresh-context plan checking for GSDD
+argument-hint: [phase-number]
+---
+
+You are the Claude-native \`/gsdd-plan\` skill for GSDD phase planning.
+
+Portable contract:
+- Read \`.agents/skills/gsdd-plan/SKILL.md\` first. That file remains the canonical vendor-agnostic plan contract.
+- Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
+- If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this Claude-native adapter path.
+
+Native Claude adapter rule:
+- This skill is the canonical Claude-native entry surface for \`/gsdd-plan\`.
+- Stay in the primary Claude context for orchestration. Do NOT fork this skill into a subagent, because the checker must run as its own fresh-context subagent.
+- Use the native \`gsdd-plan-checker\` subagent to regain the fresh-context checker pass that portable markdown alone cannot guarantee.
+- Do NOT claim that other runtimes have the same behavior unless their own adapters explicitly implement and prove it.
+
+Execution flow:
+1. Read \`.planning/SPEC.md\`, \`.planning/ROADMAP.md\`, \`.planning/config.json\`, relevant phase research, and any existing phase plan files.
+2. Resolve the target phase from the command arguments. If no phase is provided, choose the first roadmap phase that is not complete.
+3. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`.
+4. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
+5. If \`workflow.planCheck: true\`, invoke the native \`gsdd-plan-checker\` subagent with fresh context.
+6. Pass only explicit inputs to the checker:
+   - target phase goal and requirement IDs
+   - relevant locked decisions / deferred items from \`.planning/SPEC.md\`
+   - relevant phase research file(s)
+   - produced \`.planning/phases/*-PLAN.md\` file(s)
+7. Require the checker to return a single JSON object with this shape:
+   {
+     "status": "passed",
+     "summary": "One sentence overall assessment",
+     "issues": [
+       {
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance",
+         "severity": "blocker | warning",
+         "description": "What is wrong",
+         "plan": "01-PLAN",
+         "task": "1-02",
+         "fix_hint": "Specific revision instruction"
+       }
+     ]
+   }
+   Status must be either "passed" or "issues_found".
+8. If the checker returns \`passed\`, finish and summarize.
+9. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
+10. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+
+Return a concise orchestration summary:
+- target phase
+- whether native plan checking ran
+- checker cycle count
+- final result: passed | reduced_assurance | escalated
+
+Never return raw checker JSON without summarizing it.
+`;
+}
+
+function renderClaudePlanCommand() {
+  return `---
+description: Compatibility alias for the Claude-native \`/gsdd-plan\` skill
+argument-hint: [phase-number]
+allowed-tools: Read
+---
+
+Read \`.claude/skills/gsdd-plan/SKILL.md\` and execute that skill as the canonical Claude-native \`/gsdd-plan\` entry.
+
+Rules:
+- Do NOT duplicate orchestration logic here.
+- Do NOT fork into a separate planning subagent.
+- Preserve the argument value and apply it when resolving the target phase.
+`;
+}
+
+function createClaudeAdapter({ cwd, workflows, renderSkillContent, getDelegateContent, resolveRuntimeAgentModel }) {
+  const skillsDir = join(cwd, '.claude', 'skills');
+  const commandsDir = join(cwd, '.claude', 'commands');
+  const agentsDir = join(cwd, '.claude', 'agents');
+
+  return {
+    id: 'claude',
+    name: 'claude',
+    kind: 'native_capable',
+    detect() {
+      return existsSync(join(cwd, 'CLAUDE.md')) || existsSync(join(cwd, '.claude'));
+    },
+    isInstalled() {
+      return existsSync(skillsDir) || existsSync(commandsDir) || existsSync(agentsDir);
+    },
+    generate() {
+      const modelAlias = resolveRuntimeAgentModel({
+        cwd,
+        runtime: 'claude',
+        agentId: 'plan-checker',
+        profileMap: CLAUDE_MODEL_PROFILES,
+      });
+      for (const workflow of workflows) {
+        const dir = join(skillsDir, workflow.name);
+        mkdirSync(dir, { recursive: true });
+        const content = workflow.name === 'gsdd-plan'
+          ? renderClaudePlanSkill()
+          : renderSkillContent(workflow);
+        writeFileSync(join(dir, 'SKILL.md'), content);
+      }
+
+      mkdirSync(commandsDir, { recursive: true });
+      writeFileSync(join(commandsDir, 'gsdd-plan.md'), renderClaudePlanCommand());
+
+      mkdirSync(agentsDir, { recursive: true });
+      writeFileSync(
+        join(agentsDir, 'gsdd-plan-checker.md'),
+        renderClaudePlanChecker(getDelegateContent('plan-checker.md'), modelAlias)
+      );
+    },
+    summary(action) {
+      return `${action} Claude Code skills (.claude/skills/gsdd-*), native commands (.claude/commands/gsdd-*.md), and native agents (.claude/agents/gsdd-*.md)`;
+    },
+  };
+}
+
+export { createClaudeAdapter, CLAUDE_MODEL_PROFILES };

package/bin/adapters/codex.mjs

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+function safeTomlString(value) {
+  return value.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n');
+}
+
+function renderCodexPlanChecker(delegateContent, modelId = null) {
+  const safe = delegateContent.trim().replaceAll('"""', '"" "');
+  const modelLine = modelId ? `model = "${safeTomlString(modelId)}"\n` : '';
+  return `name = "gsdd-plan-checker"
+description = "Fresh-context plan checker for GSDD plan drafts. Review-only; never edits plans directly."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+${modelLine}
+developer_instructions = """
+${safe}
+"""
+`;
+}
+
+function createCodexAdapter({
+  cwd,
+  getDelegateContent,
+  getRuntimeModelOverride,
+  loadProjectModelConfig,
+}) {
+  const agentsDir = join(cwd, '.codex', 'agents');
+
+  return {
+    id: 'codex',
+    name: 'codex',
+    kind: 'native_capable',
+    detect() {
+      return existsSync(join(cwd, '.codex'));
+    },
+    isInstalled() {
+      return existsSync(agentsDir);
+    },
+    generate() {
+      const config = loadProjectModelConfig(cwd);
+      const checkerModelId = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+
+      mkdirSync(agentsDir, { recursive: true });
+
+      // Checker agent (read-only reviewer, spawned by the portable skill's orchestration loop)
+      writeFileSync(
+        join(agentsDir, 'gsdd-plan-checker.toml'),
+        renderCodexPlanChecker(getDelegateContent('plan-checker.md'), checkerModelId)
+      );
+    },
+    summary(action) {
+      return `${action} Codex CLI native agent (.codex/agents/gsdd-plan-checker.toml)`;
+    },
+  };
+}
+
+export { createCodexAdapter };

package/bin/adapters/index.mjs

@@ -0,0 +1,20 @@
+import { createRootAgentsAdapter } from './agents.mjs';
+import { createClaudeAdapter } from './claude.mjs';
+import { createCodexAdapter } from './codex.mjs';
+import { createOpenCodeAdapter } from './opencode.mjs';
+
+function createAdapterRegistry(context) {
+  const agentsAdapter = createRootAgentsAdapter(context, 'agents');
+
+  return {
+    claude: createClaudeAdapter(context),
+    opencode: createOpenCodeAdapter(context),
+    codex: createCodexAdapter(context),
+    agents: agentsAdapter,
+    cursor: createRootAgentsAdapter(context, 'cursor'),
+    copilot: createRootAgentsAdapter(context, 'copilot'),
+    gemini: createRootAgentsAdapter(context, 'gemini'),
+  };
+}
+
+export { createAdapterRegistry };

package/bin/adapters/opencode.mjs

@@ -0,0 +1,237 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import os from 'os';
+import { join } from 'path';
+
+function expandHome(filePath) {
+  if (!filePath) return filePath;
+  if (filePath.startsWith('~/')) {
+    return join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+function parseJsonc(content) {
+  if (!content) return {};
+  if (content.charCodeAt(0) === 0xFEFF) {
+    content = content.slice(1);
+  }
+
+  let result = '';
+  let inString = false;
+  let i = 0;
+
+  while (i < content.length) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (inString) {
+      result += char;
+      if (char === '\\' && i + 1 < content.length) {
+        result += next;
+        i += 2;
+        continue;
+      }
+      if (char === '"') {
+        inString = false;
+      }
+      i++;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      result += char;
+      i++;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      while (i < content.length && content[i] !== '\n') {
+        i++;
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      i += 2;
+      while (i < content.length - 1 && !(content[i] === '*' && content[i + 1] === '/')) {
+        i++;
+      }
+      if (i < content.length - 1) i += 2;
+      continue;
+    }
+
+    result += char;
+    i++;
+  }
+
+  return JSON.parse(result.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function readOpenCodeConfig(configPath) {
+  if (!configPath || !existsSync(configPath)) return null;
+  try {
+    return parseJsonc(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function getOpenCodeConfigPaths(cwd) {
+  const globalConfig = join(os.homedir(), '.config', 'opencode', 'opencode.json');
+  const customConfig = process.env.OPENCODE_CONFIG
+    ? expandHome(process.env.OPENCODE_CONFIG)
+    : null;
+  const projectConfig = join(cwd, 'opencode.json');
+
+  return [globalConfig, customConfig, projectConfig].filter(Boolean);
+}
+
+function detectOpenCodeConfiguredModel(cwd) {
+  let configuredModel = null;
+
+  for (const configPath of getOpenCodeConfigPaths(cwd)) {
+    const config = readOpenCodeConfig(configPath);
+    if (config && typeof config.model === 'string' && config.model.includes('/')) {
+      configuredModel = config.model.trim();
+    }
+  }
+
+  if (process.env.OPENCODE_CONFIG_CONTENT) {
+    try {
+      const inlineConfig = parseJsonc(process.env.OPENCODE_CONFIG_CONTENT);
+      if (typeof inlineConfig.model === 'string' && inlineConfig.model.includes('/')) {
+        configuredModel = inlineConfig.model.trim();
+      }
+    } catch {
+      // Ignore malformed inline config and keep the best file-based result.
+    }
+  }
+
+  return configuredModel;
+}
+
+function renderOpenCodePlanChecker(delegateContent, modelId = null) {
+  const modelLine = modelId ? `model: ${modelId}\n` : '';
+  return `---
+description: Fresh-context plan checker for GSDD plan drafts. Review-only; never edits plans directly.
+mode: subagent
+hidden: true
+${modelLine}tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+${delegateContent.trim()}
+`;
+}
+
+function renderOpenCodePlanCommand() {
+  return `---
+description: OpenCode-native phase planning with fresh-context plan checking for GSDD
+subtask: false
+---
+
+You are the OpenCode-native \`/gsdd-plan\` command for GSDD phase planning.
+
+Portable contract:
+- Read \`.agents/skills/gsdd-plan/SKILL.md\` first. That file remains the canonical vendor-agnostic plan contract.
+- Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
+- If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this OpenCode-native adapter path.
+
+Native OpenCode adapter rule:
+- This command is the canonical OpenCode-native entry surface for \`/gsdd-plan\`.
+- Stay in the primary conversation context for orchestration so the checker can run as its own fresh-context subagent.
+- Use the native \`gsdd-plan-checker\` subagent for review-only checking.
+- Do NOT claim that other runtimes have the same behavior unless their own adapters explicitly implement and prove it.
+
+Execution flow:
+1. Read \`.planning/SPEC.md\`, \`.planning/ROADMAP.md\`, \`.planning/config.json\`, relevant phase research, and any existing phase plan files.
+2. Resolve the target phase from the command arguments. If no phase is provided, choose the first roadmap phase that is not complete.
+3. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`.
+4. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
+5. If \`workflow.planCheck: true\`, invoke the hidden \`gsdd-plan-checker\` subagent with fresh context.
+6. Pass only explicit inputs to the checker:
+   - target phase goal and requirement IDs
+   - relevant locked decisions / deferred items from \`.planning/SPEC.md\`
+   - relevant phase research file(s)
+   - produced \`.planning/phases/*-PLAN.md\` file(s)
+7. Require the checker to return a single JSON object with this shape:
+   {
+     "status": "passed",
+     "summary": "One sentence overall assessment",
+     "issues": [
+       {
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance",
+         "severity": "blocker | warning",
+         "description": "What is wrong",
+         "plan": "01-PLAN",
+         "task": "1-02",
+         "fix_hint": "Specific revision instruction"
+       }
+     ]
+   }
+   Status must be either "passed" or "issues_found".
+8. If the checker returns \`passed\`, finish and summarize.
+9. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
+10. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+
+Return a concise orchestration summary:
+- target phase
+- whether native plan checking ran
+- checker cycle count
+- final result: passed | reduced_assurance | escalated
+
+Never return raw checker JSON without summarizing it.
+`;
+}
+
+function createOpenCodeAdapter({
+  cwd,
+  workflows,
+  renderOpenCodeCommandContent,
+  getDelegateContent,
+  getRuntimeModelOverride,
+  loadProjectModelConfig,
+}) {
+  const commandsDir = join(cwd, '.opencode', 'commands');
+  const agentsDir = join(cwd, '.opencode', 'agents');
+
+  return {
+    id: 'opencode',
+    name: 'opencode',
+    kind: 'native_capable',
+    detect() {
+      return existsSync(join(cwd, '.opencode'));
+    },
+    isInstalled() {
+      return existsSync(commandsDir) || existsSync(agentsDir);
+    },
+    generate() {
+      const config = loadProjectModelConfig(cwd);
+      const modelId = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+      mkdirSync(commandsDir, { recursive: true });
+      for (const workflow of workflows) {
+        const content = workflow.name === 'gsdd-plan'
+          ? renderOpenCodePlanCommand()
+          : renderOpenCodeCommandContent(workflow);
+        writeFileSync(
+          join(commandsDir, `${workflow.name}.md`),
+          content
+        );
+      }
+
+      mkdirSync(agentsDir, { recursive: true });
+      writeFileSync(
+        join(agentsDir, 'gsdd-plan-checker.md'),
+        renderOpenCodePlanChecker(getDelegateContent('plan-checker.md'), modelId)
+      );
+    },
+    summary(action) {
+      return `${action} OpenCode slash commands (.opencode/commands/gsdd-*.md) and native agents (.opencode/agents/gsdd-*.md)`;
+    },
+  };
+}
+
+export { createOpenCodeAdapter, detectOpenCodeConfiguredModel };

package/bin/gsdd.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+// gsdd - GSD Distilled CLI
+
+import { realpathSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createAdapterRegistry } from './adapters/index.mjs';
+import {
+  renderAgentsBoundedBlock,
+  renderAgentsFileContent,
+  renderOpenCodeCommandContent,
+  renderSkillContent,
+  upsertBoundedBlock,
+  getDelegateContent,
+} from './lib/rendering.mjs';
+import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
+import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
+import { cmdFindPhase, cmdVerify, cmdScaffold } from './lib/phase.mjs';
+import { createCmdHealth } from './lib/health.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DISTILLED_DIR = join(__dirname, '..', 'distilled');
+const AGENTS_DIR = join(__dirname, '..', 'agents');
+const CWD = process.cwd();
+const PLANNING_DIR = join(CWD, '.planning');
+const IS_MAIN = process.argv[1]
+  ? realpathSync(process.argv[1]) === realpathSync(__filename)
+  : false;
+
+const [,, command, ...args] = process.argv;
+
+const WORKFLOWS = [
+  { name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions', agent: 'Code', opencodeType: 'edit' },
+  { name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle', agent: 'Code', opencodeType: 'edit' },
+  { name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action', agent: 'Plan', opencodeType: 'plan' },
+  { name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', agent: 'Plan', opencodeType: 'plan' },
+];
+
+const FRAMEWORK_VERSION = 'v1.2';
+
+const ADAPTERS = createAdapterRegistry({
+  cwd: CWD,
+  workflows: WORKFLOWS,
+  renderAgentsBoundedBlock,
+  renderAgentsFileContent,
+  renderOpenCodeCommandContent,
+  renderSkillContent,
+  upsertBoundedBlock,
+  getDelegateContent,
+  loadProjectModelConfig,
+  getRuntimeModelOverride,
+  resolveRuntimeAgentModel,
+});
+
+const INIT_CONTEXT = {
+  cwd: CWD,
+  planningDir: PLANNING_DIR,
+  distilledDir: DISTILLED_DIR,
+  agentsDir: AGENTS_DIR,
+  workflows: WORKFLOWS,
+  frameworkVersion: FRAMEWORK_VERSION,
+  adapters: ADAPTERS,
+};
+
+const cmdInit = createCmdInit(INIT_CONTEXT);
+const cmdUpdate = createCmdUpdate(INIT_CONTEXT);
+const cmdHealth = createCmdHealth({ frameworkVersion: FRAMEWORK_VERSION });
+
+const COMMANDS = {
+  init: cmdInit,
+  update: cmdUpdate,
+  models: cmdModels,
+  health: cmdHealth,
+  'find-phase': cmdFindPhase,
+  verify: cmdVerify,
+  scaffold: cmdScaffold,
+  help: cmdHelp,
+};
+
+async function runCli(cliCommand = command, cliArgs = args) {
+  if (!cliCommand || !COMMANDS[cliCommand]) {
+    cmdHelp();
+    if (cliCommand) process.exitCode = 1;
+    return;
+  }
+
+  await COMMANDS[cliCommand](...cliArgs);
+}
+
+if (IS_MAIN) {
+  await runCli();
+}
+
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFindPhase, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION };

package/bin/lib/cli-utils.mjs

@@ -0,0 +1,28 @@
+// cli-utils.mjs — Pure CLI utility functions (no external deps)
+
+export function parseFlagValue(flagArgs, flagName) {
+  const idx = flagArgs.indexOf(flagName);
+  if (idx === -1) return { present: false, value: null, invalid: false };
+
+  const value = flagArgs[idx + 1];
+  if (!value || value.startsWith('--')) {
+    return { present: true, value: null, invalid: true };
+  }
+
+  return { present: true, value, invalid: false };
+}
+
+export function parseToolsFlag(flagArgs) {
+  const { value } = parseFlagValue(flagArgs, '--tools');
+  if (!value) return [];
+  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents'];
+  return value.split(',').map((v) => v.trim()).filter(Boolean);
+}
+
+export function parseAutoFlag(flagArgs) {
+  return flagArgs.includes('--auto');
+}
+
+export function output(data) {
+  console.log(JSON.stringify(data, null, 2));
+}