@kernel.chat/kbot 3.9.0 → 3.10.0

package/dist/spec.js

@@ -0,0 +1,177 @@
+// kbot Spec — Spec-Driven Development
+//
+// Generates formal requirements + acceptance criteria before coding.
+// Uses the architect agent to produce a structured specification document.
+//
+// Usage:
+//   $ kbot spec "build a user authentication system"
+//   $ kbot spec "add rate limiting" --implement
+//   $ kbot spec "refactor the database layer" --agent researcher
+//   $ kbot spec "notification service" --output ./specs/notifications.md
+import { runAgent } from './agent.js';
+import { gatherContext, formatContextForPrompt } from './context.js';
+import { getRepoMapForContext } from './repo-map.js';
+import { printInfo, printSuccess, createSpinner } from './ui.js';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import chalk from 'chalk';
+const AMETHYST = chalk.hex('#6B5B95');
+// ── System Prompt ──
+const SPEC_SYSTEM_PROMPT = `You are a systems architect producing a formal specification document. Your output will be saved directly as a markdown file and used as the source of truth for implementation.
+
+You MUST output a specification in EXACTLY this markdown format. Do not deviate from the structure. Do not add preamble or commentary outside the spec. Output ONLY the spec document:
+
+\`\`\`
+# Specification: [descriptive title derived from the task]
+
+## Requirements
+1. [REQ-001] [requirement written in EARS notation (Easy Approach to Requirements Syntax)]
+2. [REQ-002] ...
+(continue numbering sequentially)
+
+## Acceptance Criteria
+- [ ] [AC-001] [specific, testable criterion — must be verifiable by a human or automated test]
+- [ ] [AC-002] ...
+(continue numbering sequentially)
+
+## Technical Design
+- Architecture: [brief architectural approach — patterns, layers, data flow]
+- Key files: [list of files to create or modify, with brief purpose]
+- Dependencies: [external packages, internal modules, APIs needed]
+
+## Implementation Plan
+1. [concrete implementation step — ordered by dependency]
+2. [next step]
+...
+
+## Risks
+- [risk description] — Mitigation: [concrete mitigation strategy]
+- ...
+\`\`\`
+
+Rules for writing specs:
+1. Requirements MUST use EARS notation. Examples:
+   - Ubiquitous: "The system shall [action]"
+   - Event-driven: "When [trigger], the system shall [response]"
+   - State-driven: "While [state], the system shall [behavior]"
+   - Unwanted: "If [condition], then the system shall [reaction]"
+   - Optional: "Where [feature is supported], the system shall [behavior]"
+2. Each acceptance criterion MUST be independently testable — a developer should be able to write a test for it.
+3. Requirements should be atomic — one concern per requirement.
+4. The implementation plan should be ordered so each step builds on the previous.
+5. Identify at least 2 risks and their mitigations.
+6. Use the project context and repository structure to inform your technical design — reference real files and patterns in the codebase.
+7. Do NOT wrap the spec in code fences. Output raw markdown directly.`;
+// ── Slug Generation ──
+function slugify(description) {
+    return description
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+}
+export async function generateSpec(description, options = {}) {
+    const agent = options.agent || 'architect';
+    const agentOpts = options.agentOpts || {};
+    // Gather project context for informed spec generation
+    let contextStr = '';
+    try {
+        const context = gatherContext();
+        contextStr = formatContextForPrompt(context);
+    }
+    catch { /* context is non-critical */ }
+    let repoMap = '';
+    try {
+        repoMap = await getRepoMapForContext();
+    }
+    catch { /* repo map is non-critical */ }
+    // Build the prompt — system instructions prepended, then the task
+    const userMessage = [
+        SPEC_SYSTEM_PROMPT,
+        '',
+        '---',
+        '',
+        contextStr ? `Project context:\n${contextStr}\n` : '',
+        repoMap ? `Repository structure:\n${repoMap}\n` : '',
+        `Task: ${description}`,
+        '',
+        'Generate the specification now:',
+    ].filter(Boolean).join('\n');
+    const spinner = createSpinner('Generating specification...');
+    spinner.start();
+    let response;
+    try {
+        response = await runAgent(userMessage, {
+            ...agentOpts,
+            agent,
+            stream: false, // Don't stream — we need the full content for file saving
+        });
+        spinner.stop();
+    }
+    catch (err) {
+        spinner.stop();
+        throw err;
+    }
+    let spec = response.content;
+    // Clean up: if the AI wrapped output in code fences, strip them
+    const fenceMatch = spec.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/m);
+    if (fenceMatch) {
+        spec = fenceMatch[1];
+    }
+    // Determine output path
+    const slug = slugify(description);
+    const outputPath = options.output || join(process.cwd(), '.kbot', 'specs', `${slug}.md`);
+    // Ensure directory exists
+    const dir = dirname(outputPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Save the spec
+    writeFileSync(outputPath, spec, 'utf-8');
+    const result = {
+        spec,
+        path: outputPath,
+        agent,
+    };
+    // Print the spec to stdout
+    console.log();
+    console.log(`  ${AMETHYST('Specification generated')}`);
+    console.log(`  ${chalk.dim('─'.repeat(60))}`);
+    console.log();
+    console.log(spec);
+    console.log();
+    console.log(`  ${chalk.dim('─'.repeat(60))}`);
+    printSuccess(`Saved to ${outputPath}`);
+    console.log();
+    // If --implement, pass the spec to the coder agent
+    if (options.implement) {
+        printInfo('Passing spec to coder agent for implementation...');
+        console.log();
+        const implementMessage = [
+            'Implement the following specification. Follow the implementation plan exactly.',
+            'Check off each acceptance criterion as you complete it.',
+            'After implementation, run verification to confirm everything works.',
+            '',
+            '---',
+            '',
+            spec,
+        ].join('\n');
+        const implResponse = await runAgent(implementMessage, {
+            ...agentOpts,
+            agent: 'coder',
+            stream: agentOpts.stream ?? true,
+        });
+        result.implementation = implResponse;
+        // Print implementation result if it wasn't streamed
+        if (!implResponse.streamed) {
+            console.log();
+            console.log(implResponse.content);
+        }
+        console.log();
+        printSuccess(`Implementation complete (${implResponse.toolCalls} tool calls)`);
+    }
+    return result;
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernel.chat/kbot",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "The only AI agent that builds its own tools. Self-evolving terminal AI: 290 tools, 23 agents, 20 providers. Runtime tool forging via forge_tool, Forge Registry for community tools, autopoietic health monitoring, immune self-audit agent. Cost-aware model routing, fallback chains, Bayesian skill routing. Embedded llama.cpp, MCP server, programmatic SDK. MIT.",
   "type": "module",
   "repository": {