@kinqs/brainrouter-cli 0.3.4

package/dist/prompt/compactor.d.ts

@@ -0,0 +1,31 @@
+import type { LLMConfig } from '../config/config.js';
+export interface CompactionInput {
+    /** The chat history minus the system message. */
+    messages: Array<{
+        role: string;
+        content: string;
+        name?: string;
+    }>;
+    /** Workspace root, surfaced in the prompt so the model can be specific. */
+    workspaceRoot: string;
+    /** The last user message verbatim. */
+    lastUserMessage?: string;
+}
+export interface CompactionResult {
+    summary: string;
+    /** Approximate token estimate of the produced summary. */
+    estimatedTokens: number;
+    /** Wall clock for the compaction call (ms). */
+    durationMs: number;
+}
+/**
+ * Run compaction by asking the LLM for a structured summary. Returns the
+ * summary as a single string; the caller decides how to splice it back into
+ * the chat history. We don't mutate state here — that's the agent's job.
+ */
+export declare function runCompaction(llm: LLMConfig, input: CompactionInput): Promise<CompactionResult>;
+/**
+ * Compose the system block that replaces the verbose chat history after
+ * compaction. Keep it tagged so the agent loop knows it came from /compact.
+ */
+export declare function renderCompactSystemMessage(summary: string): string;

package/dist/prompt/compactor.js

@@ -0,0 +1,112 @@
+/**
+ * Conversation compaction for long sessions.
+ *
+ * The REPL's old `/compact` just nuked chat history. That works in a pinch but
+ * loses every decision the agent made. This module asks the model to write a
+ * structured summary of the conversation so far, then replaces the verbose
+ * history with a single condensed system message.
+ *
+ * The summary lives in a stable shape so the post-compact turn can reason
+ * about it without missing critical state:
+ *
+ *   - Goals: what the user is trying to accomplish
+ *   - Decisions: design choices already made
+ *   - Files touched: paths the agent has read or written
+ *   - Open work: what remains to do
+ *   - Last user request: verbatim so the next turn picks up cleanly
+ */
+const COMPACT_SYSTEM_PROMPT = [
+    'You are compacting a long agent conversation so it can continue in a fresh context window.',
+    'Produce a structured summary the next turn can read in 1 second. Use the headings shown below.',
+    '',
+    '# Goals',
+    'List the user\'s current high-level goals as bullets.',
+    '',
+    '# Decisions made',
+    'List decisions, choices, or assumptions already agreed upon. Quote file paths where helpful.',
+    '',
+    '# Files touched',
+    'List file paths the agent has read, written, or edited.',
+    '',
+    '# Open work',
+    'List what is still pending — bug fixes, follow-ups, tests, reviews.',
+    '',
+    '# Last user request',
+    'Quote the user\'s most recent message verbatim. Do not paraphrase.',
+    '',
+    'Output Markdown only. No preamble. No code fences around the summary itself.',
+].join('\n');
+/**
+ * Run compaction by asking the LLM for a structured summary. Returns the
+ * summary as a single string; the caller decides how to splice it back into
+ * the chat history. We don't mutate state here — that's the agent's job.
+ */
+export async function runCompaction(llm, input) {
+    const startedAt = Date.now();
+    const flattened = input.messages
+        .filter((m) => m.role !== 'system')
+        .map((m) => `### ${m.role.toUpperCase()}${m.name ? ` (${m.name})` : ''}\n${m.content}`)
+        .join('\n\n');
+    const userMsg = [
+        `# Compaction request`,
+        `Workspace: ${input.workspaceRoot}`,
+        input.lastUserMessage ? `Last user message (treat as anchor): ${input.lastUserMessage}` : '',
+        '',
+        '# Conversation transcript',
+        flattened,
+    ].filter(Boolean).join('\n');
+    const body = {
+        model: llm.model,
+        messages: [
+            { role: 'system', content: COMPACT_SYSTEM_PROMPT },
+            { role: 'user', content: userMsg },
+        ],
+    };
+    const endpoint = llm.endpoint || 'https://api.openai.com/v1';
+    const apiKey = llm.apiKey || process.env.OPENAI_API_KEY || '';
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    const timeoutMs = Number(process.env.BRAINROUTER_LLM_TIMEOUT_MS || 60000);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(`${endpoint}/chat/completions`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        const errText = await res.text();
+        throw new Error(`compaction call failed: ${res.status} ${res.statusText} - ${errText.slice(0, 500)}`);
+    }
+    const data = await res.json();
+    const text = String(data?.choices?.[0]?.message?.content ?? '').trim();
+    if (!text)
+        throw new Error('compaction returned an empty summary');
+    return {
+        summary: text,
+        estimatedTokens: Math.ceil(text.length / 4),
+        durationMs: Date.now() - startedAt,
+    };
+}
+/**
+ * Compose the system block that replaces the verbose chat history after
+ * compaction. Keep it tagged so the agent loop knows it came from /compact.
+ */
+export function renderCompactSystemMessage(summary) {
+    return [
+        '## Compacted conversation summary',
+        '',
+        'The conversation up to this point was compacted to fit the context window.',
+        'Treat the following as authoritative state and resume from "Last user request".',
+        '',
+        summary,
+    ].join('\n');
+}

package/dist/prompt/initAgentMd.d.ts

@@ -0,0 +1,13 @@
+export interface InitResult {
+    status: 'created' | 'exists';
+    path: string;
+}
+/**
+ * Create AGENT.md in the workspace root if neither AGENT.md nor AGENTS.md is
+ * already present. Idempotent: returns { status: 'exists' } when something
+ * already lives there.
+ *
+ * We use AGENT.md (singular) as the canonical name — most AGENT-md aware tools
+ * read both spellings, so a singular file works everywhere.
+ */
+export declare function initAgentMd(workspaceRoot: string): InitResult;

package/dist/prompt/initAgentMd.js

@@ -0,0 +1,194 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Repo-signal scan. We sniff for common project files and use that to populate
+ * the AGENT.md template with realistic guesses instead of a blank "Describe…"
+ * placeholder. Detected signals appear under "Detected project signals" so the
+ * user can verify them at a glance.
+ */
+function detectRepoSignals(root) {
+    const hits = [];
+    const buildCmds = [];
+    const testCmds = [];
+    const has = (rel) => fs.existsSync(path.join(root, rel));
+    const read = (rel) => {
+        try {
+            return fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    if (has('package.json')) {
+        hits.push('Node.js / npm (`package.json`)');
+        try {
+            const pkg = JSON.parse(read('package.json') ?? '{}');
+            const scripts = pkg.scripts ?? {};
+            if (scripts.build)
+                buildCmds.push('npm run build');
+            if (scripts.dev)
+                buildCmds.push('npm run dev');
+            if (scripts.test)
+                testCmds.push('npm test');
+            if (scripts.lint)
+                testCmds.push('npm run lint');
+            if (scripts.typecheck)
+                testCmds.push('npm run typecheck');
+            if (pkg.workspaces)
+                hits.push('npm workspaces (monorepo)');
+        }
+        catch { /* malformed package.json — skip */ }
+    }
+    if (has('pnpm-workspace.yaml') || has('pnpm-lock.yaml'))
+        hits.push('pnpm');
+    if (has('yarn.lock'))
+        hits.push('yarn');
+    if (has('tsconfig.json'))
+        hits.push('TypeScript (`tsconfig.json`)');
+    if (has('go.mod')) {
+        hits.push('Go (`go.mod`)');
+        buildCmds.push('go build ./...');
+        testCmds.push('go test ./...');
+    }
+    if (has('Cargo.toml')) {
+        hits.push('Rust (`Cargo.toml`)');
+        buildCmds.push('cargo build');
+        testCmds.push('cargo test');
+    }
+    if (has('pyproject.toml') || has('requirements.txt') || has('setup.py')) {
+        hits.push('Python');
+        if (has('pytest.ini') || (read('pyproject.toml') ?? '').includes('pytest')) {
+            testCmds.push('pytest');
+        }
+    }
+    if (has('Gemfile'))
+        hits.push('Ruby (`Gemfile`)');
+    if (has('Dockerfile'))
+        hits.push('Docker (`Dockerfile`)');
+    if (has('docker-compose.yml') || has('docker-compose.yaml') || has('compose.yaml'))
+        hits.push('Docker Compose');
+    if (has('.github/workflows'))
+        hits.push('GitHub Actions CI');
+    if (has('.gitlab-ci.yml'))
+        hits.push('GitLab CI');
+    if (has('Makefile')) {
+        hits.push('Makefile');
+        buildCmds.push('make');
+        testCmds.push('make test');
+    }
+    if (has('.env.example') || has('.env.sample'))
+        hits.push('Env template (`.env.example`)');
+    if (has('CLAUDE.md') || has('AGENTS.md'))
+        hits.push('Existing sibling agent doc');
+    if (has('README.md'))
+        hits.push('README.md');
+    return { hits, buildCmds: dedupe(buildCmds), testCmds: dedupe(testCmds) };
+}
+function dedupe(items) {
+    return Array.from(new Set(items));
+}
+function renderTemplate(signals, projectName) {
+    const { hits, buildCmds, testCmds } = signals;
+    const buildSection = buildCmds.length > 0
+        ? buildCmds.map((c) => `- Build / dev: \`${c}\``).join('\n')
+        : '- Build / dev: _(fill in — e.g. `npm run build`, `cargo build`, `go build ./...`)_';
+    const testSection = testCmds.length > 0
+        ? testCmds.map((c) => `- Test: \`${c}\``).join('\n')
+        : '- Test: _(fill in)_';
+    const signalsSection = hits.length > 0
+        ? hits.map((h) => `- ${h}`).join('\n')
+        : '- _(no signals detected — fill in stack manually)_';
+    return `# AGENT.md
+
+> Instructions for AI coding agents working in this repo. Compatible with AGENT.md / AGENTS.md aware tools.
+
+## Project context
+
+**${projectName}** — describe what this project is and the high-level architecture in 2-3 sentences.
+
+## Detected project signals
+
+${signalsSection}
+
+## Build, test, run
+
+${buildSection}
+${testSection}
+
+## Conventions
+
+- Code style: _(describe — formatter, lint config)_
+- Testing: _(unit/integration patterns)_
+- Commits: conventional commits (\`feat\`, \`fix\`, \`chore\`, ...)
+
+## Boundaries
+
+- Always do: run tests before claiming work is complete; cite memory record ids when used.
+- Ask first: schema migrations, dependency upgrades, anything that touches secrets.
+- Never do: commit \`.env\` or anything matching \`*.key\`, modify \`vendor/\`, skip git hooks.
+
+## Skill hints
+
+If you have catalogued BrainRouter skills relevant to this repo, list them here:
+
+- ${"`code-review-and-quality`"} — use before merging.
+- ${"`agentic-engineering-workflow`"} — use for /feature-dev.
+`;
+}
+const TEMPLATE_FALLBACK = `# AGENT.md
+
+> Instructions for AI coding agents working in this repo. Compatible with AGENT.md / AGENTS.md aware tools.
+
+## Project context
+
+Describe what this project is and the high-level architecture in 2-3 sentences.
+
+## Build, test, run
+
+- Install: \`npm install\`
+- Build:   \`npm run build\`
+- Test:    \`npm test\`
+- Run dev: \`npm run dev\`
+
+## Conventions
+
+- Code style: …
+- Testing: …
+- Commits: conventional commits (\`feat\`, \`fix\`, \`chore\`, …).
+
+## Boundaries
+
+- Always do: run tests before claiming work is complete; cite memory record ids when used.
+- Ask first: schema migrations, dependency upgrades, anything that touches secrets.
+- Never do: commit \`.env\` or anything matching \`*.key\`, modify \`vendor/\`, skip git hooks.
+
+## Skill hints
+
+If you have catalogued skills relevant to this repo, list them here so the
+\`memory_register_skill_hints\` tool can warm them up automatically:
+
+- ${"`code-review-and-quality`"} — use before merging.
+- ${"`agentic-engineering-workflow`"} — use for /feature-dev.
+`;
+/**
+ * Create AGENT.md in the workspace root if neither AGENT.md nor AGENTS.md is
+ * already present. Idempotent: returns { status: 'exists' } when something
+ * already lives there.
+ *
+ * We use AGENT.md (singular) as the canonical name — most AGENT-md aware tools
+ * read both spellings, so a singular file works everywhere.
+ */
+export function initAgentMd(workspaceRoot) {
+    const candidates = ['AGENT.md', 'AGENTS.md'].map((name) => path.join(workspaceRoot, name));
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            return { status: 'exists', path: candidate };
+        }
+    }
+    const target = candidates[0];
+    const projectName = path.basename(workspaceRoot);
+    const signals = detectRepoSignals(workspaceRoot);
+    const body = signals.hits.length > 0 ? renderTemplate(signals, projectName) : TEMPLATE_FALLBACK;
+    fs.writeFileSync(target, body, 'utf8');
+    return { status: 'created', path: target };
+}

package/dist/prompt/skillRunner.d.ts

@@ -0,0 +1,34 @@
+import type { McpClientWrapper } from '../runtime/mcpClient.js';
+export interface SkillResolution {
+    name: string;
+    body: string;
+    source: 'mcp' | 'filesystem' | 'fallback';
+}
+export interface RunSkillOptions {
+    /** Free-text input from the user (e.g., feature description, review scope). */
+    input?: string;
+    /** Optional extra orchestration directives appended after the skill body. */
+    orchestration?: string;
+    /** Skill section to fetch from get_skill. Defaults to "workflow" — pass "full" for the entire SKILL.md. */
+    section?: 'description' | 'overview' | 'when_to_use' | 'workflow' | 'usage' | 'detailed_instructions' | 'phases' | 'checklist' | 'red_flags' | 'rationalizations' | 'full';
+}
+/**
+ * Slash-command → skill mapping. Each entry names the skill catalogued in
+ * the BrainRouter skills/ folder (and exposed by the MCP server) that the
+ * command delegates to. The CLI sends a thin prompt; the heavy lifting lives
+ * in the skill body, so authoring is centralized.
+ */
+export declare const SLASH_TO_SKILL: Record<string, string>;
+/**
+ * Resolve a skill by name. Prefers the MCP server (so users get whatever the
+ * server has loaded, including their own private skills), falls back to a
+ * local filesystem scan of `skills/` for when the MCP tool is unavailable.
+ */
+export declare function resolveSkill(mcpClient: McpClientWrapper, name: string, workspaceRoot: string, section?: RunSkillOptions['section']): Promise<SkillResolution>;
+/**
+ * Build the user prompt that asks the agent to execute a skill. The skill
+ * body is embedded so the agent does not need to round-trip through
+ * `get_skill` again. Orchestration affordances (spawn_agent, update_plan)
+ * are reminded explicitly so multi-agent workflows are actually triggered.
+ */
+export declare function buildSkillPrompt(skill: SkillResolution, options?: RunSkillOptions): string;

package/dist/prompt/skillRunner.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * Slash-command → skill mapping. Each entry names the skill catalogued in
+ * the BrainRouter skills/ folder (and exposed by the MCP server) that the
+ * command delegates to. The CLI sends a thin prompt; the heavy lifting lives
+ * in the skill body, so authoring is centralized.
+ */
+export const SLASH_TO_SKILL = {
+    '/feature-dev': 'agentic-engineering-workflow',
+    '/review': 'code-review-and-quality',
+    '/implement-plan': 'incremental-skill',
+    '/spec': 'spec-driven-skill',
+    '/plan-write': 'planning-skill',
+    '/debug': 'debug-skill',
+    '/handover': 'handover-skill',
+    '/commit-skill': 'git-workflow-skill',
+    '/changelog': 'changelog-generator',
+    '/refactor': 'code-simplification',
+    '/test': 'testing-skill',
+};
+const WORKSPACE_SKILL_ROOTS = ['skills', '.brainrouter/skills'];
+/**
+ * Resolve a skill by name. Prefers the MCP server (so users get whatever the
+ * server has loaded, including their own private skills), falls back to a
+ * local filesystem scan of `skills/` for when the MCP tool is unavailable.
+ */
+export async function resolveSkill(mcpClient, name, workspaceRoot, section = 'full') {
+    try {
+        const res = await mcpClient.callTool('get_skill', { name, section });
+        if (!res.isError && Array.isArray(res.content) && res.content[0]?.text) {
+            return { name, body: res.content[0].text, source: 'mcp' };
+        }
+    }
+    catch {
+        // Fall through to filesystem lookup.
+    }
+    const body = readSkillFromFilesystem(workspaceRoot, name);
+    if (body) {
+        return { name, body, source: 'filesystem' };
+    }
+    return {
+        name,
+        body: `(No SKILL.md found for "${name}". Use your general judgement and the agentic-engineering-workflow defaults.)`,
+        source: 'fallback',
+    };
+}
+function readSkillFromFilesystem(workspaceRoot, name) {
+    for (const root of skillSearchRoots(workspaceRoot)) {
+        if (!fs.existsSync(root))
+            continue;
+        const match = findSkillDir(root, name);
+        if (match) {
+            try {
+                return fs.readFileSync(path.join(match, 'SKILL.md'), 'utf8');
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return undefined;
+}
+/**
+ * Roots to search for SKILL.md when the MCP server is unavailable. Includes:
+ *  - the user's workspace (so per-project skills win locally)
+ *  - the installed @kinqs/brainrouter-mcp-server package directory (so the canonical
+ *    BrainRouter catalogue is found even when MCP is down, because prepack
+ *    bundles `skills/` into the published package)
+ *  - the monorepo root (when running from source during development)
+ */
+function skillSearchRoots(workspaceRoot) {
+    const roots = [];
+    for (const sub of WORKSPACE_SKILL_ROOTS) {
+        roots.push(path.join(workspaceRoot, sub));
+    }
+    const mcpPkgDir = resolveInstalledMcpPackageDir();
+    if (mcpPkgDir)
+        roots.push(path.join(mcpPkgDir, 'skills'));
+    return roots;
+}
+function resolveInstalledMcpPackageDir() {
+    try {
+        const pkgJsonPath = requireFromHere.resolve('@kinqs/brainrouter-mcp-server/package.json');
+        return path.dirname(pkgJsonPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function findSkillDir(rootDir, skillName, depth = 3) {
+    if (depth < 0)
+        return undefined;
+    let entries;
+    try {
+        entries = fs.readdirSync(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const child = path.join(rootDir, entry.name);
+        if (entry.name === skillName && fs.existsSync(path.join(child, 'SKILL.md'))) {
+            return child;
+        }
+        const nested = findSkillDir(child, skillName, depth - 1);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+/**
+ * Build the user prompt that asks the agent to execute a skill. The skill
+ * body is embedded so the agent does not need to round-trip through
+ * `get_skill` again. Orchestration affordances (spawn_agent, update_plan)
+ * are reminded explicitly so multi-agent workflows are actually triggered.
+ */
+export function buildSkillPrompt(skill, options = {}) {
+    const sections = [];
+    sections.push(`# Executing skill: ${skill.name}`);
+    sections.push(`Source: ${skill.source}`);
+    sections.push('');
+    sections.push('## Skill instructions');
+    sections.push(skill.body.trim());
+    if (options.input?.trim()) {
+        sections.push('');
+        sections.push('## User input');
+        sections.push(options.input.trim());
+    }
+    sections.push('');
+    sections.push('## Execution affordances');
+    sections.push([
+        '- You may delegate bounded parallel work with `spawn_agent` (roles: explorer, architect, reviewer, worker, verifier).',
+        '- Keep the durable plan current with `update_plan`. At most one item should be `in_progress`.',
+        '- Persist meaningful outputs through BrainRouter memory tools (`memory_capture_turn`, `memory_working_offload`) as the skill dictates.',
+        '- Always synthesize child outputs in your own words before claiming work is done.',
+    ].join('\n'));
+    if (options.orchestration?.trim()) {
+        sections.push('');
+        sections.push('## CLI orchestration hints');
+        sections.push(options.orchestration.trim());
+    }
+    return sections.join('\n');
+}

package/dist/prompt/systemPrompt.d.ts

@@ -0,0 +1,10 @@
+export interface SystemPromptContext {
+    workspaceRoot: string;
+    launchCwd: string;
+    sessionKey: string;
+    instructionSummary?: string;
+    /** Communication style overlay set by /personality. */
+    personality?: 'concise' | 'standard' | 'detailed' | 'pair-programmer';
+}
+export declare function buildSystemPrompt(context: SystemPromptContext): string;
+export declare function loadWorkspaceInstructionSummary(workspaceRoot: string): string | undefined;