@structured-vibe-coding/core 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -1103,15 +1103,6 @@ declare function recommendWorkflow(projectRoot: string, title: string, config: C
     alternatives: string[];
 }>;
 
-interface CreateChangeInput {
-    projectRoot: string;
-    config: Config;
-    title: string;
-    workflowName: string;
-    domain?: string;
-    flags?: Record<string, boolean | string | number>;
-    branch?: string;
-}
 interface ChangeContext {
     id: string;
     path: string;
@@ -1120,16 +1111,35 @@ interface ChangeContext {
     stages: Stage[];
     active: Stage[];
 }
-declare function createChange(input: CreateChangeInput): Promise<ChangeContext>;
 declare function loadChangeMeta(projectRoot: string, config: Config, changeId: string): Promise<ChangeMeta>;
 declare function saveChangeMeta(projectRoot: string, config: Config, meta: ChangeMeta): Promise<void>;
 declare function buildContext(projectRoot: string, config: Config, changeId: string): Promise<ChangeContext>;
 declare function listChanges(projectRoot: string, config: Config): Promise<string[]>;
 declare function getActiveChangeId(projectRoot: string, config: Config): Promise<string | null>;
-/** Clear active pointer if it points at this change id (does not re-resolve). */
 declare function clearActiveIf(projectRoot: string, config: Config, changeId: string): Promise<void>;
 declare function setActiveChange(projectRoot: string, config: Config, changeId: string): Promise<void>;
 declare function resolveChangeId(projectRoot: string, config: Config, changeId?: string): Promise<string>;
+
+/** Artifact + gate + verify checks before leaving the current stage. */
+declare function canLeaveStage(ctx: ChangeContext, config: Config): Promise<{
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}>;
+declare function approveGate(projectRoot: string, config: Config, changeId: string, stageId: string | undefined, note?: string, status?: "approved" | "waived" | "failed"): Promise<ChangeContext>;
+
+declare function formatStatus(ctx: ChangeContext): string;
+declare function buildAgentPrompt(ctx: ChangeContext, config: Config, projectRoot: string): Promise<string>;
+
+interface CreateChangeInput {
+    projectRoot: string;
+    config: Config;
+    title: string;
+    workflowName: string;
+    domain?: string;
+    flags?: Record<string, boolean | string | number>;
+    branch?: string;
+}
 interface AdvanceResult {
     ctx: ChangeContext;
     from: string;
@@ -1138,88 +1148,101 @@ interface AdvanceResult {
     artifactsCreated: string[];
     warnings: string[];
 }
-declare function canLeaveStage(ctx: ChangeContext, config: Config): Promise<{
-    ok: boolean;
-    errors: string[];
-    warnings: string[];
-}>;
+declare function createChange(input: CreateChangeInput): Promise<ChangeContext>;
 declare function advanceStage(projectRoot: string, config: Config, changeId: string, opts?: {
     force?: boolean;
 }): Promise<AdvanceResult>;
 declare function skipStage(projectRoot: string, config: Config, changeId: string, stageId: string, reason: string): Promise<ChangeContext>;
 declare function switchWorkflow(projectRoot: string, config: Config, changeId: string, workflowName: string, reason?: string): Promise<ChangeContext>;
-declare function approveGate(projectRoot: string, config: Config, changeId: string, stageId: string | undefined, note?: string, status?: "approved" | "waived" | "failed"): Promise<ChangeContext>;
 declare function completeChange(projectRoot: string, config: Config, changeId: string): Promise<{
     archivedTo: string | null;
     ctx: ChangeContext;
 }>;
-declare function formatStatus(ctx: ChangeContext): string;
-declare function buildAgentPrompt(ctx: ChangeContext, config: Config, projectRoot: string): Promise<string>;
 
 /**
  * AI coding agents (not IDEs).
- * VS Code / Cursor / IntelliJ are editors; they host tools like Copilot or Claude Code.
- *
  * Speckit-style: one integration at a time; public keys are short (`copilot`, `claude`).
  */
 type AgentTarget = "copilot" | "claude-code";
-declare const ALL_AGENT_TARGETS: AgentTarget[];
-/** Default when non-interactive and no --ai / --integration (matches Speckit). */
-declare const DEFAULT_INIT_INTEGRATION: AgentTarget;
-interface AgentTargetOption {
-    /** Internal install id (file paths / agents.json). */
+/** Registry entry — add a new AI agent by appending here only. */
+interface AgentIntegration {
     id: AgentTarget;
-    /** Speckit-style public key used with --ai / --integration. */
+    /** Speckit-style public key (`--ai` / `--integration`). */
     key: string;
+    aliases: string[];
     label: string;
     hint: string;
-    /** If true, CLI may check that the agent binary is on PATH. */
     requiresCli: boolean;
     installUrl: string;
+    /** Binary name when requiresCli (e.g. `claude`). */
+    cliBinary?: string;
+    /** Relative path for a thin role agent file. */
+    rolePath: (roleId: string) => string;
+    /** One markdown table row for AGENTS.md. */
+    agentsMdRow: string;
 }
-/** Human-facing options for interactive AI-agent pick (CLI / IDE). */
+declare const AGENT_INTEGRATIONS: AgentIntegration[];
+declare const ALL_AGENT_TARGETS: AgentTarget[];
+/** Default when non-interactive and no --ai (matches Speckit). */
+declare const DEFAULT_INIT_INTEGRATION: AgentTarget;
+/** @deprecated Prefer AgentIntegration / AGENT_INTEGRATIONS — kept for UI option lists. */
+type AgentTargetOption = Pick<AgentIntegration, "id" | "key" | "label" | "hint" | "requiresCli" | "installUrl">;
 declare const AGENT_TARGET_OPTIONS: AgentTargetOption[];
-/** Public CLI keys → internal targets (Speckit uses `claude`, not `claude-code`). */
+declare function getIntegration(target: AgentTarget): AgentIntegration;
 declare function integrationKeyFor(target: AgentTarget): string;
-declare function optionForTarget(target: AgentTarget): AgentTargetOption | undefined;
+declare function optionForTarget(target: AgentTarget): AgentTargetOption;
+/** Parse one Speckit-style integration key. */
+declare function parseIntegration(raw: string): AgentTarget;
 /**
- * Parse Speckit-style integration keys: `copilot`, `claude`, `claude-code`, …
- * Throws on unknown ids or IDE names.
+ * Parse one or more keys (comma-separated). Prefer parseIntegration for product flows.
+ * @deprecated Multi-install is not the product default; use parseIntegration.
  */
 declare function parseAgentTargets(raw: string | string[]): AgentTarget[];
-/** Parse a single Speckit-style integration (exactly one). */
-declare function parseIntegration(raw: string): AgentTarget;
-/** Roles emitted as thin agents (shared body generator — no skill files). */
+/** Roles emitted as thin agents (shared body generator). */
 type SddAgentRoleId = "sdd" | "sdd-planner" | "sdd-implementer" | "sdd-reviewer";
 interface SddAgentRole {
     id: SddAgentRoleId;
     description: string;
     roleLine: string;
-    /** Extra one-liner constraints for this role only */
     roleRules: string[];
 }
 declare const SDD_AGENT_ROLES: SddAgentRole[];
-interface InstallAgentsOptions {
+interface InstallAgentOptions {
     projectRoot: string;
-    targets?: AgentTarget[];
+    /** Single AI coding agent (Speckit-style). */
+    target: AgentTarget;
     force?: boolean;
 }
-interface InstallAgentsResult {
+interface InstallAgentResult {
     created: string[];
     skipped: string[];
-    targets: AgentTarget[];
+    target: AgentTarget;
 }
+/** @deprecated Use InstallAgentOptions / installAgentIntegration. */
+type InstallAgentsOptions = {
+    projectRoot: string;
+    targets?: AgentTarget[];
+    force?: boolean;
+};
+/** @deprecated Use InstallAgentResult. */
+type InstallAgentsResult = {
+    created: string[];
+    skipped: string[];
+    targets: AgentTarget[];
+};
+/**
+ * Install thin agents for **one** AI integration (registry-driven).
+ * Writes protocol + active-context + role stubs + single `.sdd/agents.json` snapshot.
+ */
+declare function installAgentIntegration(opts: InstallAgentOptions): Promise<InstallAgentResult>;
 /**
- * Install **agents only** (no skills, no fat instructions).
- *
- * Single playbook: `.sdd/protocol.md`
- * Live state:      `.sdd/active-context.md`
- * Thin agents:     `.claude/agents/*` and `.github/agents/*` (pointers + role)
+ * Install one or more integrations (writes each host's files; snapshot = last target).
+ * Prefer installAgentIntegration for product flows.
  */
 declare function installAgentIntegrations(opts: InstallAgentsOptions): Promise<InstallAgentsResult>;
-/** Thin agent body shared by Claude Code and GitHub Copilot (same text). */
+/** Thin agent body shared across hosts (same text). */
 declare function renderThinAgent(role: SddAgentRole): string;
-/** Write .sdd/active-context.md for the current change (all agents read this). */
+/** Write .sdd/active-context.md for the current change. */
 declare function refreshActiveAgentContext(projectRoot: string): Promise<string | null>;
 /** Single playbook — only long agent-facing content we author once. */
 declare const PROTOCOL_MD = "# SDD protocol\n\nThis repo uses **Structured Vibe Coding** (`sdd`). Agents must follow this file plus `.sdd/active-context.md`. Do not invent a parallel process.\n\n## Source of truth\n\n| What | Where |\n|------|--------|\n| Process state | `changes/<id>/meta.yaml` (workflow, stage, gates) |\n| Current task snapshot | `.sdd/active-context.md` |\n| Stable product/tech rules | `memory/*.md` |\n| Stage artifacts | files in `changes/<id>/` for the active change |\n\n## Required read order\n\n1. `.sdd/active-context.md`\n2. This file (`.sdd/protocol.md`)\n3. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)\n4. `memory/` when architecture or conventions matter\n\n## Stage behavior\n\n| Stage kind | Agent focus |\n|------------|-------------|\n| intent / feature / stories | Clarify scope; write short artifacts |\n| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |\n| tasks | Break work into implementable checklist |\n| implement | Code only for this change; follow tasks/acceptance |\n| local_verify | Check acceptance; fix only; prepare for complete |\n\n## Hard rules\n\n1. **Do not skip hard gates.** If blocked, tell the human to run `sdd gate approve` (or fix the gate).\n2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.\n3. **Honor constraints** in `arb-decision.md`, design, and memory non-negotiables.\n4. **Local verify** is part of done when the workflow has a verify stage: `sdd verify`.\n5. Prefer small, reviewable diffs.\n\n## Commands (human / shell)\n\n```bash\nsdd status\nsdd next\nsdd agent              # print handoff\nsdd agents refresh     # refresh active-context.md\nsdd verify\nsdd complete\n```\n\n## Out of scope for agents\n\n- Replacing CI/CD or team process tools\n- Deleting `.sdd` / archive history\n- Claiming complete without verify when required\n";
@@ -1228,12 +1251,11 @@ interface InitOptions {
     projectRoot: string;
     force?: boolean;
     /**
-     * AI coding agents to install (copilot | claude-code). Not IDEs.
-     * Opt-in only — never defaults to all agents.
+     * AI coding agent to install (single, Speckit-style). Not an IDE.
      * - omit / `false` — no agent files
-     * - `AgentTarget[]` — install only those AI agents
+     * - `AgentTarget` — install that integration only
      */
-    agents?: false | AgentTarget[];
+    agents?: false | AgentTarget;
 }
 interface InitResult {
     created: string[];
@@ -1291,4 +1313,4 @@ declare function listFiles(path: string): Promise<string[]>;
 declare function copyDir(src: string, dest: string): Promise<void>;
 declare function removePath(path: string): Promise<void>;
 
-export { AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdvanceResult, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_INIT_INTEGRATION, type Gate, GateSchema, type InitOptions, type InitResult, type InstallAgentsOptions, type InstallAgentsResult, PROTOCOL_MD, SDD_AGENT_ROLES, SDD_DIR, type SddAgentRole, type SddAgentRoleId, type Stage, StageSchema, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, advanceStage, approveGate, archiveDir, buildAgentPrompt, buildContext, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, clearActiveIf, completeChange, configPath, copyDir, createChange, defaultConfig, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, firstActiveStageId, formatStatus, getActiveChangeId, getStage, inferComplexity, initProject, installAgentIntegrations, integrationKeyFor, isInitialized, isStageSkipped, listChanges, listDirs, listFiles, listWorkflowNames, loadChangeMeta, loadConfig, loadWorkflow, memoryDir, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseIntegration, pathExists, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removePath, renderThinAgent, resolveChangeId, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, switchWorkflow, templatesDir, todayIsoDate, uniqueChangeDirName, workflowsDir, writeText, writeYaml };
+export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdvanceResult, type AgentIntegration, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_INIT_INTEGRATION, type Gate, GateSchema, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, PROTOCOL_MD, SDD_AGENT_ROLES, SDD_DIR, type SddAgentRole, type SddAgentRoleId, type Stage, StageSchema, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, advanceStage, approveGate, archiveDir, buildAgentPrompt, buildContext, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, clearActiveIf, completeChange, configPath, copyDir, createChange, defaultConfig, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, firstActiveStageId, formatStatus, getActiveChangeId, getIntegration, getStage, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, isInitialized, isStageSkipped, listChanges, listDirs, listFiles, listWorkflowNames, loadChangeMeta, loadConfig, loadWorkflow, memoryDir, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseIntegration, pathExists, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removePath, renderThinAgent, resolveChangeId, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, switchWorkflow, templatesDir, todayIsoDate, uniqueChangeDirName, workflowsDir, writeText, writeYaml };