@spekn/cli 1.0.0

package/dist/repo-sync.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * repo-sync CLI command
+ *
+ * Syncs metadata for the current git repository with Spekn.
+ * Looks up the repo by its remote URL and updates name and default branch.
+ * Optionally runs AI analysis (same as repo register --analyze).
+ * Must be run from inside a local git clone.
+ *
+ * Usage: spekn repo sync --project-id <uuid> [--analyze] [--agent <name>] [--api-url <url>]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRepoSyncCli = runRepoSyncCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+const repo_common_1 = require("./repo-common");
+const structured_log_1 = require("./utils/structured-log");
+// ── Help & Args ─────────────────────────────────────────────────────
+function printHelp(stderr) {
+    stderr(`
+repo sync - Sync git repository metadata with Spekn
+
+USAGE:
+  spekn repo sync --project-id <uuid> [options]
+
+OPTIONS:
+  --project-id <uuid>   Project ID that owns the repository (optional if .spekn/context is present)
+  --analyze             Run AI analysis after syncing metadata
+  --agent <name>        Force a specific agent (claude, codex, opencode, etc.)
+  --path <dir>          Repository root path (default: current directory)
+  --dry-run             Discover files only, skip AI analysis
+  --mcp-url <url>       MCP HTTP server URL (default: MCP_HTTP_URL or https://app.spekn.com/mcp)
+  --api-url <url>       API base URL (default: SPEKN_API_URL or https://app.spekn.com)
+  --debug               Show detailed debug output (tokens, HTTP exchanges)
+  --help                Show this help message
+
+ENVIRONMENT:
+  SPEKN_API_URL         API base URL
+  SPEKN_AUTH_TOKEN      Bearer token for authentication
+  SPEKN_ORGANIZATION_ID Organization ID header
+  MCP_HTTP_URL          MCP HTTP server URL (default: https://app.spekn.com/mcp)
+  AGENT_ARGS            Override agent CLI args (skips ACP registry resolution)
+
+DESCRIPTION:
+  Reads the 'origin' remote URL from the current git repository, looks up the
+  matching registered repository in the project, and updates its name and
+  default branch to match the local git state.
+
+  With --analyze, also runs AI-powered analysis to discover specs, assess
+  governance, and create improvement specifications (same as repo register).
+
+EXAMPLES:
+  spekn repo sync --project-id 11111111-1111-4111-8111-111111111111
+  spekn repo sync --project-id 11111111-1111-4111-8111-111111111111 --analyze
+  spekn repo sync --project-id 11111111-1111-4111-8111-111111111111 --analyze --agent claude
+`);
+}
+function parseArgs(args) {
+    const opts = (0, repo_common_1.commonDefaults)(false);
+    for (let i = 0; i < args.length;) {
+        const consumed = (0, repo_common_1.parseCommonFlag)(args, i, opts);
+        if (consumed > 0) {
+            i += consumed;
+            continue;
+        }
+        i++; // skip unknown
+    }
+    return (0, repo_common_1.finalizeOptions)(opts);
+}
+// ── Main ────────────────────────────────────────────────────────────
+async function runRepoSyncCli(args, deps = repo_common_1.defaultDeps) {
+    try {
+        const options = parseArgs(args);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: "info",
+            message: "Starting repo sync",
+            details: { repoPath: options.repoPath, analyze: options.analyze, apiUrl: options.apiUrl },
+        });
+        const { authToken, organizationId, projectId } = await (0, repo_common_1.resolveAuth)(deps, {
+            projectId: options.projectId,
+            repoPath: options.repoPath,
+        });
+        // ── Phase 1: Sync repository metadata ──────────────────────────
+        const git = (0, repo_common_1.readGitMetadata)(options.repoPath, deps);
+        if (!git)
+            return 1;
+        deps.stdout(`Syncing repository "${git.name}" (${git.remoteUrl})\n`);
+        deps.stdout(`  Default branch : ${git.defaultBranch}\n`);
+        deps.stdout(`  Project        : ${projectId}\n`);
+        const client = (0, repo_common_1.createApiClient)(options.apiUrl, authToken, organizationId);
+        // Find matching repository
+        const repos = 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await client.gitRepository.list.query({
+            projectId,
+            limit: 100,
+            offset: 0,
+        });
+        const match = repos.find((r) => r.repositoryUrl === git.remoteUrl);
+        if (!match) {
+            deps.stderr(`Error: No registered repository found for URL "${git.remoteUrl}" in project ${projectId}.\n` +
+                "Use 'spekn repo register' to register this repository first.\n");
+            return 1;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await client.gitRepository.update.mutate({
+            projectId,
+            id: match.id,
+            data: { name: git.name, defaultBranch: git.defaultBranch },
+        });
+        deps.stdout(`Repository synced successfully. ID: ${match.id}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: "info",
+            message: "Repository metadata synced",
+            details: { projectId, repositoryId: match.id },
+        });
+        // ── Phase 2: AI analysis (optional) ─────────────────────────────
+        if (!options.analyze)
+            return 0;
+        const exitCode = await (0, repo_common_1.runAnalysisPhase)({ ...options, projectId }, authToken ?? "", deps, organizationId);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: exitCode === 0 ? "info" : "error",
+            message: "Repo sync completed",
+            details: { exitCode, analyzed: options.analyze, projectId },
+        });
+        return exitCode;
+    }
+    catch (error) {
+        if (error instanceof repo_common_1.HelpRequestedError) {
+            printHelp(deps.stderr);
+            return 0;
+        }
+        deps.stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runRepoSyncCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/resources/prompt-loader.d.ts

@@ -0,0 +1 @@
+export declare function loadPromptTemplate(name: string): string;

package/dist/resources/prompt-loader.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPromptTemplate = loadPromptTemplate;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const promptCache = new Map();
+function resolvePromptPath(name) {
+    const candidates = [
+        path.resolve(__dirname, "resources", "prompts", name),
+        path.resolve(__dirname, "prompts", name),
+        path.resolve(__dirname, "..", "resources", "prompts", name),
+        path.resolve(process.cwd(), "packages", "cli", "src", "resources", "prompts", name),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    throw new Error(`Prompt resource "${name}" not found. Looked in: ${candidates.join(", ")}`);
+}
+function loadPromptTemplate(name) {
+    const cached = promptCache.get(name);
+    if (cached)
+        return cached;
+    const promptPath = resolvePromptPath(name);
+    const content = fs.readFileSync(promptPath, "utf-8");
+    promptCache.set(name, content);
+    return content;
+}

package/dist/resources/prompts/README.md

@@ -0,0 +1,21 @@
+# CLI Prompt Resources
+
+This folder contains editable prompt templates used by the Spekn CLI.
+
+## Files
+
+- `repo-analysis.prompt.md`: prompt used by `spekn repo register --analyze`.
+  This is the ingestion/bootstrap-oriented analysis prompt.
+- `repo-sync-analysis.prompt.md`: prompt used by `spekn repo sync --analysis-engine acp|both`.
+  This prompt is sync-specific and focuses on drift/update decisions without duplicating existing specs.
+
+## Placeholders
+
+`repo-analysis.prompt.md` supports token replacement:
+
+- `{{PROJECT_ID}}`
+- `{{ORG_INSTRUCTION}}`
+- `{{REPO_PATH}}`
+- `{{FILE_LIST}}`
+
+Keep token names unchanged unless you also update the renderer in `packages/cli/src/commands/repo/common.ts`.

package/dist/resources/prompts/prompts/repo-analysis.prompt.md

@@ -0,0 +1,126 @@
+You are analyzing a repository to register it with a Spekn project.
+You have been given Spekn MCP tools to create specifications and decisions.
+
+PROJECT ID: {{PROJECT_ID}}{{ORG_INSTRUCTION}}
+REPO PATH: {{REPO_PATH}}
+
+DISCOVERED FILES:
+{{FILE_LIST}}
+
+STEP 0 — VERIFY TOOLS:
+Before doing anything else, list the available MCP tools to confirm you have
+access to spekn_spec_create, spekn_spec_list, and spekn_decision_create. If these tools are NOT available,
+output "ERROR: Spekn MCP tools not available. Cannot proceed with analysis." and stop.
+
+STEP 1 — READ AND UNDERSTAND THE REPOSITORY:
+Read the governance files (CLAUDE.md, AGENTS.md, README.md), package manifests
+(package.json, Cargo.toml, pyproject.toml, etc.), and key source directories
+to understand what this project does, its tech stack, and architecture.
+
+STEP 2 — CREATE MAIN PROJECT SPECIFICATION:
+Use spekn_spec_create to create a main project overview spec:
+  - Title: "{repo name} — Project Overview" (e.g. "linux-mdm — Project Overview")
+  - Content MUST start with a YAML frontmatter block:
+    ---
+    title: "{repo name} — Project Overview"
+    type: intent
+    version: "1.0.0"
+    status: draft
+    author: "repo ingestor"
+    tags: [overview, project]
+    hints:
+      constraints: ["Key project invariants and boundaries"]
+      requirements: ["Core project goals and capabilities"]
+      technical: ["Tech stack, architecture patterns, build system"]
+      guidance: ["Development conventions and contribution guidelines"]
+    ---
+  - After the frontmatter, include a comprehensive explanation of what the project does,
+    tech stack, directory structure, build system, development conventions, and key decisions
+  - This becomes the primary context for the engineering manager agent
+
+STEP 3 — IMPORT EXISTING SPECS:
+For each file categorized as "spec" in the DISCOVERED FILES list:
+  - Read the file content
+  - Use spekn_spec_create to create a Specification record
+  - Use the first # heading as the title (must be unique, 3-100 chars)
+  - If the file already has a YAML frontmatter block (---), preserve it but ensure author is set:
+    - author: "repo ingestor" (add it when missing)
+  - If no frontmatter exists, prepend one with:
+    - type: "capability"
+    - version: "1.0.0"
+    - author: "repo ingestor"
+    - hints: populate from the file content (constraints, requirements, technical, guidance)
+  - Set version to "1.0.0"
+
+For each file categorized as "decision" in the DISCOVERED FILES list:
+  - Read the file content
+  - First create/import its parent specification with spekn_spec_create if needed (type: "decision", author: "repo ingestor")
+  - Then perform ACP DECISION DETECTION before creating records:
+    - Extract one normalized decision object per explicit decision/ADR entry
+    - Ignore vague notes that do not state a concrete choice
+    - If one file contains multiple explicit ADR entries, create one decision record per entry
+  - Use this normalized structure for each extracted decision:
+    {
+      "title": "<3-100 chars, imperative/statement form>",
+      "description": "<what was decided, specific and concrete>",
+      "rationale": "<why this option was chosen>",
+      "alternatives": ["<rejected option 1>", "<rejected option 2>"]
+    }
+  - Formatting requirements:
+    - title must NOT include prefixes like "Decision:", "ADR-001:", markdown symbols, or file names
+    - description and rationale must be plain text (no markdown headings/bullets)
+    - alternatives must be plain option strings; use [] when none are explicit
+    - If rationale is missing, infer a concise rationale from nearby context (trade-offs/constraints)
+  - Create each record with spekn_decision_create using:
+    - projectId: PROJECT ID
+    - specificationId: parent decision specification ID
+    - title, description, rationale, alternatives from normalized object
+
+STEP 4 — ASSESS GOVERNANCE AND CREATE IMPROVEMENT SPECS:
+Assess governance quality — does the repo have CI/CD, tests, security guidelines,
+contribution guidelines, documentation structure?
+For each significant gap, use spekn_spec_create to create a draft improvement spec:
+  - Descriptive title (e.g. "CI/CD Pipeline", "Testing Strategy")
+  - Content MUST start with a YAML frontmatter block:
+    - type: "capability" for new features, "operational" for ops/process improvements
+    - status: "draft"
+    - author: "repo ingestor"
+    - tags: reflecting the gap area (e.g., [ci-cd, automation] or [testing, quality])
+    - hints: summarize what the spec covers in each context layer
+  - After frontmatter, describe what the repo SHOULD have (best practices)
+  - Focus on quality over quantity — only create specs for real gaps
+
+STEP 5 — FEATURE COVERAGE AND PLAN GAP ANALYSIS:
+Analyze feature implementation coverage against specs/FEATURE_MAP.md and related feature docs.
+- Read specs/FEATURE_MAP.md and list all rows marked "Planned", "Draft", "Active", "~95%", "pending", or "deferred"
+- For each such row, verify whether the repo has:
+  - implementation evidence in code (routers/services/components/tests)
+  - a corresponding feature document in specs/features/
+  - an implementation plan (IMPLEMENTATION_PLAN.md) when feature status implies planning/active build
+- For missing or weakly-covered items, create improvement specs with spekn_spec_create:
+  - Title pattern: "{repo name} — Gap: <feature>"
+  - type: "capability" for product/runtime gaps, "operational" for process/governance gaps
+  - tags must include "feature-coverage" and "plan-gap"
+  - hints must explicitly include missing code surfaces and missing planning artifacts
+- Do not duplicate if an equivalent gap spec already exists; update existing draft instead when possible
+
+STEP 6 — SUMMARY:
+Print a summary of what you created:
+  - Number of specs imported from existing files
+  - Number of decisions created from decision files
+  - Number of improvement specs created
+  - Overall governance assessment (strengths and gaps)
+  - Feature coverage summary (implemented vs partial vs missing)
+  - Missing plan features summary
+  - Include a "FEATURE_COVERAGE" section in this exact line format:
+    - FEATURE | <id-or-name> | <status> | <evidence-or-missing>
+  - Include a "MISSING_PLAN_FEATURES" section in this exact line format:
+    - PLAN_GAP | <id-or-name> | <missing-artifact> | <recommended-spec-title>
+  - Include a "DECISIONS_CREATED" section in this exact line format:
+    - DECISION | <source-file> | <title> | <specificationId>
+
+RULES:
+- ALWAYS use Spekn MCP create tools (spekn_spec_create / spekn_decision_create) — never just describe what you would create
+- Each spec title must be globally unique — prefix with the repo/project name if needed
+- Do NOT create specs for governance files (CLAUDE.md, AGENTS.md, .cursorrules) — those are context, not specs
+- If a tool call fails, report the error and continue with the next item

package/dist/resources/prompts/repo-analysis.prompt.md

@@ -0,0 +1,151 @@
+You are analyzing a repository to register it with a Spekn project.
+You have been given Spekn MCP tools to create specifications and decisions.
+
+PROJECT ID: {{PROJECT_ID}}{{ORG_INSTRUCTION}}
+REPO PATH: {{REPO_PATH}}
+
+DISCOVERED FILES:
+{{FILE_LIST}}
+
+STEP 0 — VERIFY TOOLS:
+Before doing anything else, list the available MCP tools to confirm you have
+access to spekn_spec_create, spekn_spec_list, and spekn_decision_create. If these tools are NOT available,
+output "ERROR: Spekn MCP tools not available. Cannot proceed with analysis." and stop.
+
+STEP 1 — READ AND UNDERSTAND THE REPOSITORY:
+Read the governance files (CLAUDE.md, AGENTS.md, README.md), package manifests
+(package.json, Cargo.toml, pyproject.toml, etc.), and key source directories
+to understand what this project does, its tech stack, and architecture.
+
+STEP 2 — CREATE MAIN PROJECT SPECIFICATION:
+Use spekn_spec_create to create a main project overview spec:
+  - Title: "Project Overview" — short, no repo name prefix
+  - Content MUST start with a YAML frontmatter block:
+    ---
+    title: "Project Overview"
+    type: intent
+    version: "1.0.0"
+    status: draft
+    author: "repo ingestor"
+    tags: [overview, project]
+    hints:
+      constraints: ["Key project invariants and boundaries"]
+      requirements: ["Core project goals and capabilities"]
+      technical: ["Tech stack, architecture patterns, build system"]
+      guidance: ["Development conventions and contribution guidelines"]
+    ---
+  - After the frontmatter, include a comprehensive explanation of what the project does,
+    tech stack, directory structure, build system, development conventions, and key decisions
+  - This becomes the primary context for the engineering manager agent
+
+STEP 3 — IMPORT EXISTING SPECS:
+For each file categorized as "spec" in the DISCOVERED FILES list:
+  - Read the file content
+  - Use spekn_spec_create to create a Specification record
+  - Use the first # heading as the title (must be unique, 3-100 chars)
+  - If the file already has a YAML frontmatter block (---), preserve it but ensure author is set:
+    - author: "repo ingestor" (add it when missing)
+  - If no frontmatter exists, prepend one with:
+    - type: "capability"
+    - version: "1.0.0"
+    - author: "repo ingestor"
+    - hints: populate from the file content (constraints, requirements, technical, guidance)
+  - Set version to "1.0.0"
+
+For each file categorized as "decision" in the DISCOVERED FILES list:
+  - Read the file content
+  - First create/import its parent specification with spekn_spec_create if needed (type: "decision", author: "repo ingestor")
+  - Then perform ACP DECISION DETECTION before creating records:
+    - Extract one normalized decision object per explicit decision/ADR entry
+    - Ignore vague notes that do not state a concrete choice
+    - If one file contains multiple explicit ADR entries, create one decision record per entry
+  - Use this normalized structure for each extracted decision:
+    {
+      "title": "<3-100 chars, imperative/statement form>",
+      "description": "<what was decided, specific and concrete>",
+      "rationale": "<why this option was chosen>",
+      "alternatives": ["<rejected option 1>", "<rejected option 2>"]
+    }
+  - Formatting requirements:
+    - title must NOT include prefixes like "Decision:", "ADR-001:", markdown symbols, or file names
+    - description and rationale must be plain text (no markdown headings/bullets)
+    - alternatives must be plain option strings; use [] when none are explicit
+    - If rationale is missing, infer a concise rationale from nearby context (trade-offs/constraints)
+  - Create each record with spekn_decision_create using:
+    - projectId: PROJECT ID
+    - specificationId: parent decision specification ID
+    - title, description, rationale, alternatives from normalized object
+
+STEP 4 — ANALYZE PDF DOCUMENTS:
+If any files categorized as "pdf" appear in the DISCOVERED FILES list:
+  - Check whether you have a tool that can read or extract text from PDF files
+    (e.g. `read_file` with PDF support, a `pdf` skill, or any PDF extraction tool)
+  - If you DO have PDF capability:
+    - Read each PDF file to extract its text content
+    - Determine what the document covers (architecture diagrams, requirements, RFCs,
+      compliance docs, contracts, design documents, etc.)
+    - For each PDF that contains specification-worthy content, use spekn_spec_create:
+      - Title: short descriptive name derived from the PDF content (NOT the filename)
+      - Content MUST start with a YAML frontmatter block:
+        - type: choose the best fit ("capability", "architectural", "intent", "operational")
+        - status: "draft"
+        - author: "repo ingestor"
+        - tags: ["pdf-import", ...relevant tags]
+        - hints: summarize key content in each layer
+      - After frontmatter, include the extracted content reformatted as clean markdown
+    - For PDFs containing decision records or ADRs, create decisions following STEP 3 rules
+  - If you do NOT have PDF capability:
+    - Log: "PDF files found but no PDF reading tool available — skipping PDF analysis"
+    - List the PDF files that were skipped so the user knows
+  - Do NOT fail the entire analysis if PDF reading is unavailable
+
+STEP 5 — ASSESS GOVERNANCE AND CREATE IMPROVEMENT SPECS:
+Assess governance quality — does the repo have CI/CD, tests, security guidelines,
+contribution guidelines, documentation structure?
+For each significant gap, use spekn_spec_create to create a draft improvement spec:
+  - Descriptive title (e.g. "CI/CD Pipeline", "Testing Strategy")
+  - Content MUST start with a YAML frontmatter block:
+    - type: "capability" for new features, "operational" for ops/process improvements
+    - status: "draft"
+    - author: "repo ingestor"
+    - tags: reflecting the gap area (e.g., [ci-cd, automation] or [testing, quality])
+    - hints: summarize what the spec covers in each context layer
+  - After frontmatter, describe what the repo SHOULD have (best practices)
+  - Focus on quality over quantity — only create specs for real gaps
+
+STEP 6 — FEATURE COVERAGE AND PLAN GAP ANALYSIS:
+Analyze feature implementation coverage against specs/FEATURE_MAP.md and related feature docs.
+- Read specs/FEATURE_MAP.md and list all rows marked "Planned", "Draft", "Active", "~95%", "pending", or "deferred"
+- For each such row, verify whether the repo has:
+  - implementation evidence in code (routers/services/components/tests)
+  - a corresponding feature document in specs/features/
+  - an implementation plan (IMPLEMENTATION_PLAN.md) when feature status implies planning/active build
+- For missing or weakly-covered items, create improvement specs with spekn_spec_create:
+  - Title: short descriptive name of the feature gap (e.g. "Flatpak Governance Enforcement", "Network Egress Policy")
+  - Do NOT prefix titles with the repo name, "Gap:", or any other prefix
+  - type: "capability" for product/runtime gaps, "operational" for process/governance gaps
+  - tags must include "feature-coverage" and "plan-gap"
+  - hints must explicitly include missing code surfaces and missing planning artifacts
+- Do not duplicate if an equivalent gap spec already exists; update existing draft instead when possible
+
+STEP 7 — SUMMARY:
+Print a summary of what you created:
+  - Number of specs imported from existing files
+  - Number of specs imported from PDF documents (or skipped if no PDF tool)
+  - Number of decisions created from decision files
+  - Number of improvement specs created
+  - Overall governance assessment (strengths and gaps)
+  - Feature coverage summary (implemented vs partial vs missing)
+  - Missing plan features summary
+  - Include a "FEATURE_COVERAGE" section in this exact line format:
+    - FEATURE | <id-or-name> | <status> | <evidence-or-missing>
+  - Include a "MISSING_PLAN_FEATURES" section in this exact line format:
+    - PLAN_GAP | <id-or-name> | <missing-artifact> | <recommended-spec-title>
+  - Include a "DECISIONS_CREATED" section in this exact line format:
+    - DECISION | <source-file> | <title> | <specificationId>
+
+RULES:
+- ALWAYS use Spekn MCP create tools (spekn_spec_create / spekn_decision_create) — never just describe what you would create
+- Each spec title must be unique within the project — use short descriptive titles, never prefix with repo name
+- Do NOT create specs for governance files (CLAUDE.md, AGENTS.md, .cursorrules) — those are context, not specs
+- If a tool call fails, report the error and continue with the next item

package/dist/resources/prompts/repo-sync-analysis.prompt.md

@@ -0,0 +1,85 @@
+You are synchronizing an already-registered repository with a Spekn project.
+Your role is to detect drift, decide what to update, and avoid duplicate specs.
+
+PROJECT ID: {{PROJECT_ID}}{{ORG_INSTRUCTION}}
+REPO PATH: {{REPO_PATH}}
+COMMIT CONTEXT:
+{{COMMIT_CONTEXT}}
+
+DISCOVERED FILES:
+{{FILE_LIST}}
+
+STEP 0 — VERIFY TOOLS:
+List available tools and confirm you have:
+- spekn_spec_list
+- spekn_spec_create
+- spekn_spec_update
+- spekn_decision_create
+- spekn_decision_update
+If missing critical tools, output an error and stop.
+
+STEP 1 — LOAD CURRENT SaaS STATE FIRST:
+Before touching anything:
+1. Call spekn_spec_list for the project using pagination.
+   - API limit is max 100 items per page.
+   - Use `limit <= 100` and increment `offset` until no more items are returned.
+2. Build a map of existing specs by:
+   - exact title
+   - normalized title (case/spacing/punctuation insensitive)
+3. Treat locked specs as canonical. Never create a duplicate just because content differs.
+
+STEP 2 — FILTER NON-SOURCE EXPORT ARTIFACTS:
+Files under `spekn/context/specs/**` and `spekn/context/decisions/**` are export artifacts.
+Do NOT re-import these as new specs by default.
+Only use them as evidence for drift, not as direct create input.
+
+STEP 3 — FOR EACH DISCOVERED SOURCE FILE, DECIDE ACTION:
+For each relevant source file, choose exactly one:
+- SKIP: no meaningful drift
+- UPDATE_EXISTING: matching spec exists and should be updated
+- CREATE_NEW: truly new capability/intent/decision area with no equivalent existing spec
+
+Decision policy:
+- Prefer UPDATE_EXISTING over CREATE_NEW when a semantically equivalent spec exists.
+- CREATE_NEW only when no reasonable existing target exists.
+- Never create a “repo ingestor import ...” duplicate of an existing locked/canonical spec.
+- If uncertain between update and create, choose update and explain rationale.
+- Give extra weight to commit-range changes since LAST_SYNC_COMMIT when deciding drift.
+- If code/protocol files changed, verify corresponding specs/decisions were updated; if not, propose targeted updates.
+
+STEP 4 — APPLY CHANGES:
+- Use spekn_spec_update for UPDATE_EXISTING actions.
+- Use spekn_spec_create only for CREATE_NEW actions.
+- Use decision create/update tools similarly with dedupe intent.
+- Keep titles stable for existing specs; avoid generating near-duplicate titles.
+- For UPDATE_EXISTING calls, include version/history intent:
+  - prefer `changeType: "patch"` for small clarifications
+  - use `changeType: "minor"` for new requirements/constraints
+  - set concise `changeDescription` referencing commit-range drift rationale
+
+STEP 4.5 — ASK FOR APPROVAL WHEN CONFIDENCE IS LOW:
+Before applying a low-confidence update/create (for example: weak evidence, ambiguous target mapping, or conflicting interpretation):
+- trigger an interactive ACP question to the client (`session/prompt`) with explicit options:
+  - approve
+  - skip
+- if approval is not explicit, skip the low-confidence change
+- mention each prompted item again in REVIEW_NOTES
+
+STEP 5 — OUTPUT SUMMARY:
+Output:
+1. DRIFT_SUMMARY
+   - file, drift type, severity, target spec (if any)
+2. SYNC_ACTION_PLAN
+   - ACTION | SKIP/UPDATE_EXISTING/CREATE_NEW | file | target/new title | reason
+3. SYNC_APPLIED
+   - APPLIED | update/create/skip | entity type | id/title
+4. REVIEW_NOTES
+   - low-confidence updates that should be human-reviewed
+   - missing spec/decision coverage for changed code/protocol files
+
+RULES:
+- Do not mass-create specs.
+- Minimize churn.
+- Respect existing canonical spec set.
+- Every tool call must include projectId and organizationId when required.
+- Spec titles must be short and descriptive — never prefix with the repo name, "Gap:", or other prefixes.

package/dist/skills-import-local.d.ts

@@ -0,0 +1,16 @@
+/**
+ * skills import-local CLI command
+ *
+ * Imports SKILL.md files from a local directory into a Spekn project.
+ *
+ * Usage: spekn skills import-local <path> --project-id <uuid> [--namespace <ns>] [--api-url <url>]
+ */
+import { CredentialsStore } from "./auth/credentials-store";
+interface Deps {
+    stdout: (content: string) => void;
+    stderr: (content: string) => void;
+    credentialsStore: CredentialsStore;
+}
+export declare function runSkillsImportLocalCli(args: string[], deps?: Deps): Promise<number>;
+export declare function main(): Promise<void>;
+export {};