@soleri/forge 5.14.9 → 7.0.0

package/src/compose-claude-md.ts

@@ -0,0 +1,252 @@
+/**
+ * Soleri v7 — CLAUDE.md Composer
+ *
+ * Auto-generates CLAUDE.md from agent.yaml + instructions/ + workflows/ + skills/.
+ * This file is never manually edited. `soleri dev` watches and regenerates on change.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { AgentYaml } from './agent-schema.js';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface ComposedClaudeMd {
+  /** The full CLAUDE.md content */
+  content: string;
+  /** Files that contributed to this composition */
+  sources: string[];
+}
+
+export interface ToolEntry {
+  facade: string;
+  ops: string[];
+}
+
+// ─── Main Composer ────────────────────────────────────────────────────
+
+/**
+ * Compose CLAUDE.md from an agent folder.
+ *
+ * @param agentDir - Path to the agent folder (containing agent.yaml)
+ * @param tools - Registered MCP tools (from engine introspection). Optional —
+ *                if not provided, generates a placeholder table.
+ */
+export function composeClaudeMd(agentDir: string, tools?: ToolEntry[]): ComposedClaudeMd {
+  const sources: string[] = [];
+
+  // 1. Read agent.yaml
+  const agentYamlPath = join(agentDir, 'agent.yaml');
+  const agentYaml = parseYaml(readFileSync(agentYamlPath, 'utf-8')) as AgentYaml;
+  sources.push(agentYamlPath);
+
+  const sections: string[] = [];
+
+  // 2. Agent identity block
+  sections.push(composeIdentityBlock(agentYaml));
+
+  // 3. Activation commands
+  sections.push(composeActivation(agentYaml));
+
+  // 4. Session start
+  sections.push(composeSessionStart(agentYaml));
+
+  // 5. Essential tools table
+  sections.push(composeToolsTable(agentYaml, tools));
+
+  // 6. Engine rules (from instructions/_engine.md)
+  const enginePath = join(agentDir, 'instructions', '_engine.md');
+  if (existsSync(enginePath)) {
+    sections.push(readFileSync(enginePath, 'utf-8').trim());
+    sources.push(enginePath);
+  }
+
+  // 7. User instructions (instructions/*.md, excluding _engine.md)
+  const instructionsDir = join(agentDir, 'instructions');
+  if (existsSync(instructionsDir)) {
+    const files = readdirSync(instructionsDir)
+      .filter((f) => f.endsWith('.md') && f !== '_engine.md')
+      .sort();
+    for (const file of files) {
+      const filePath = join(instructionsDir, file);
+      sections.push(readFileSync(filePath, 'utf-8').trim());
+      sources.push(filePath);
+    }
+  }
+
+  // 8. Workflow index
+  const workflowsDir = join(agentDir, 'workflows');
+  if (existsSync(workflowsDir)) {
+    const workflowSection = composeWorkflowIndex(workflowsDir);
+    if (workflowSection) {
+      sections.push(workflowSection);
+      // Add workflow prompt files to sources
+      const dirs = readdirSync(workflowsDir, { withFileTypes: true }).filter((d) =>
+        d.isDirectory(),
+      );
+      for (const dir of dirs) {
+        const promptPath = join(workflowsDir, dir.name, 'prompt.md');
+        if (existsSync(promptPath)) sources.push(promptPath);
+      }
+    }
+  }
+
+  // 9. Skills index
+  const skillsDir = join(agentDir, 'skills');
+  if (existsSync(skillsDir)) {
+    const skillsSection = composeSkillsIndex(skillsDir);
+    if (skillsSection) sections.push(skillsSection);
+  }
+
+  const content = sections.join('\n\n') + '\n';
+  return { content, sources };
+}
+
+// ─── Section Composers ────────────────────────────────────────────────
+
+function composeIdentityBlock(agent: AgentYaml): string {
+  const lines: string[] = [
+    `# ${agent.name} Mode`,
+    '',
+    `## ${agent.name}`,
+    '',
+    `**Role:** ${agent.role}`,
+    `**Domains:** ${agent.domains.join(', ')}`,
+    `**Tone:** ${agent.tone}`,
+    '',
+    agent.description,
+    '',
+    '**Principles:**',
+    ...agent.principles.map((p) => `- ${p}`),
+  ];
+  return lines.join('\n');
+}
+
+function composeActivation(agent: AgentYaml): string {
+  return [
+    '## Activation',
+    '',
+    `**Activate:** "Hello, ${agent.name}!" → \`${agent.id}_core op:activate params:{ projectPath: "." }\``,
+    `**Deactivate:** "Goodbye, ${agent.name}!" → \`${agent.id}_core op:activate params:{ deactivate: true }\``,
+    '',
+    `On activation, adopt the returned persona. Stay in character until deactivated.`,
+  ].join('\n');
+}
+
+function composeSessionStart(agent: AgentYaml): string {
+  return [
+    '## Session Start',
+    '',
+    `On every new session: \`${agent.id}_core op:register params:{ projectPath: "." }\``,
+  ].join('\n');
+}
+
+function composeToolsTable(agent: AgentYaml, tools?: ToolEntry[]): string {
+  const lines: string[] = [
+    '## Essential Tools',
+    '',
+    '| Facade | Key Ops |',
+    '|--------|---------|',
+  ];
+
+  if (tools && tools.length > 0) {
+    for (const tool of tools) {
+      const opsStr = tool.ops
+        .slice(0, 6)
+        .map((o) => `\`${o}\``)
+        .join(', ');
+      const suffix = tool.ops.length > 6 ? ', ...' : '';
+      lines.push(`| \`${tool.facade}\` | ${opsStr}${suffix} |`);
+    }
+  } else {
+    // Placeholder — will be filled by engine introspection at dev time
+    lines.push(`| \`${agent.id}_core\` | \`health\`, \`identity\`, \`register\`, \`activate\` |`);
+    lines.push(
+      `| \`${agent.id}_vault\` | \`search_intelligent\`, \`capture_knowledge\`, \`capture_quick\` |`,
+    );
+    lines.push(`| \`${agent.id}_brain\` | \`recommend\`, \`strengths\`, \`feedback\` |`);
+    lines.push(
+      `| \`${agent.id}_planner\` | \`create_plan\`, \`approve_plan\`, \`plan_split\`, \`plan_reconcile\` |`,
+    );
+    lines.push(
+      `| \`${agent.id}_memory\` | \`memory_search\`, \`memory_capture\`, \`session_capture\` |`,
+    );
+    lines.push(
+      `| \`${agent.id}_curator\` | \`curator_groom\`, \`curator_status\`, \`curator_health\` |`,
+    );
+    lines.push(
+      `| \`${agent.id}_admin\` | \`admin_health\`, \`admin_tool_list\`, \`admin_diagnostic\` |`,
+    );
+
+    // Domain facades from packs
+    if (agent.packs) {
+      for (const pack of agent.packs) {
+        lines.push(`| \`${agent.id}_${pack.name}\` | \`get_patterns\`, \`search\`, \`capture\` |`);
+      }
+    }
+    // Domain facades from domains
+    for (const domain of agent.domains) {
+      lines.push(`| \`${agent.id}_${domain}\` | \`get_patterns\`, \`search\`, \`capture\` |`);
+    }
+  }
+
+  lines.push('');
+  lines.push(`> Full list: \`${agent.id}_admin op:admin_tool_list\``);
+
+  return lines.join('\n');
+}
+
+function composeWorkflowIndex(workflowsDir: string): string | null {
+  const dirs = readdirSync(workflowsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  if (dirs.length === 0) return null;
+
+  const lines: string[] = [
+    '## Available Workflows',
+    '',
+    '| Workflow | Description |',
+    '|----------|-------------|',
+  ];
+
+  for (const dir of dirs) {
+    const promptPath = join(workflowsDir, dir.name, 'prompt.md');
+    let description = dir.name;
+
+    if (existsSync(promptPath)) {
+      const content = readFileSync(promptPath, 'utf-8');
+      // Extract first non-heading, non-empty line as description
+      const descLine = content.split('\n').find((line) => line.trim() && !line.startsWith('#'));
+      if (descLine) description = descLine.trim().slice(0, 80);
+    }
+
+    lines.push(`| \`${dir.name}\` | ${description} |`);
+  }
+
+  return lines.join('\n');
+}
+
+function composeSkillsIndex(skillsDir: string): string | null {
+  const dirs = readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  if (dirs.length === 0) return null;
+
+  const lines: string[] = ['## Available Skills', ''];
+
+  for (const dir of dirs) {
+    const skillPath = join(skillsDir, dir.name, 'SKILL.md');
+    if (existsSync(skillPath)) {
+      const content = readFileSync(skillPath, 'utf-8');
+      // Extract description from frontmatter if present
+      const descMatch = content.match(/^description:\s*(.+)$/m);
+      const desc = descMatch ? descMatch[1].trim() : dir.name;
+      lines.push(`- **${dir.name}**: ${desc}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/lib.ts

@@ -18,9 +18,22 @@ export type {
   InstallKnowledgeResult,
   AddDomainResult,
 } from './types.js';
-export { AgentConfigSchema, SETUP_TARGETS } from './types.js';
+export { AgentConfigSchema, SETUP_TARGETS, MODEL_PRESETS } from './types.js';
+
+// ─── v7 File-Tree Agent ──────────────────────────────────────────────
+export { scaffoldFileTree } from './scaffold-filetree.js';
+export type { FileTreeScaffoldResult } from './scaffold-filetree.js';
+export { AgentYamlSchema, TONES } from './agent-schema.js';
+export type { AgentYaml, AgentYamlInput } from './agent-schema.js';
+export { composeClaudeMd } from './compose-claude-md.js';
+export type { ComposedClaudeMd, ToolEntry } from './compose-claude-md.js';
 export { generateExtensionsIndex, generateExampleOp } from './templates/extensions.js';
 export { generateClaudeMdTemplate } from './templates/claude-md-template.js';
 export { getEngineRulesContent, getEngineMarker } from './templates/shared-rules.js';
 export { generateInjectClaudeMd } from './templates/inject-claude-md.js';
 export { generateSkills } from './templates/skills.js';
+export { generateTelegramBot } from './templates/telegram-bot.js';
+export { generateTelegramAgent } from './templates/telegram-agent.js';
+export { generateTelegramConfig } from './templates/telegram-config.js';
+export { generateTelegramSupervisor } from './templates/telegram-supervisor.js';
+export { generateEntryPoint } from './templates/entry-point.js';

package/src/scaffold-filetree.ts

@@ -0,0 +1,409 @@
+/**
+ * Soleri v7 — File-Tree Agent Scaffolder
+ *
+ * Generates a folder tree with plain files (YAML, Markdown, JSON).
+ * No TypeScript, no package.json, no build step.
+ *
+ * Replaces the old scaffold() that generated TypeScript projects.
+ */
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringify as yamlStringify } from 'yaml';
+import type { AgentYaml, AgentYamlInput } from './agent-schema.js';
+import { AgentYamlSchema } from './agent-schema.js';
+import { getEngineRulesContent } from './templates/shared-rules.js';
+import { composeClaudeMd } from './compose-claude-md.js';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface FileTreeScaffoldResult {
+  success: boolean;
+  agentDir: string;
+  filesCreated: string[];
+  summary: string;
+}
+
+// ─── Built-in Workflows ───────────────────────────────────────────────
+
+interface WorkflowTemplate {
+  name: string;
+  prompt: string;
+  gates: string;
+  tools: string;
+}
+
+const BUILTIN_WORKFLOWS: WorkflowTemplate[] = [
+  {
+    name: 'feature-dev',
+    prompt: `# Feature Development
+
+## When to Use
+When building a new feature, adding functionality, or creating components.
+
+## Steps
+
+### 1. Understand
+- Search vault for existing patterns: \`op:search_intelligent\`
+- Read relevant source code
+- Clarify requirements with user if ambiguous
+
+### 2. Plan
+- Create structured plan: \`op:orchestrate_plan\`
+- Present plan to user, wait for approval
+- Do NOT write code before approval
+
+### 3. Test First
+- Write failing tests that define expected behavior
+- Run tests to confirm they fail (RED)
+
+### 4. Implement
+- Write minimum code to pass tests (GREEN)
+- Follow vault patterns, avoid known anti-patterns
+- Use semantic tokens, not hardcoded values
+
+### 5. Refactor
+- Clean up without changing behavior
+- Extract reusable patterns
+- Ensure all tests still pass
+
+### 6. Capture & Ship
+- Capture learned patterns: \`op:capture_knowledge\`
+- Link new entries to related knowledge: \`op:link_entries\`
+- Complete orchestration: \`op:orchestrate_complete\`
+`,
+    gates: `gates:
+  - phase: brainstorming
+    requirement: Requirements are clear and user has approved the approach
+    check: user-approval
+
+  - phase: pre-execution
+    requirement: Plan created via orchestrator and approved by user
+    check: plan-approved
+
+  - phase: post-task
+    requirement: All tests pass and code compiles
+    check: tests-pass
+
+  - phase: completion
+    requirement: Knowledge captured to vault with links
+    check: knowledge-captured
+`,
+    tools: `tools:
+  - soleri_vault op:search_intelligent
+  - soleri_vault op:capture_knowledge
+  - soleri_vault op:link_entries
+  - soleri_planner op:create_plan
+  - soleri_planner op:approve_plan
+  - soleri_brain op:recommend
+`,
+  },
+  {
+    name: 'bug-fix',
+    prompt: `# Bug Fix
+
+## When to Use
+When fixing bugs, resolving errors, or addressing regressions.
+
+## Steps
+
+### 1. Reproduce
+- Understand the reported issue
+- Search vault for similar past bugs: \`op:search_intelligent\`
+- Identify the root cause, not just the symptom
+
+### 2. Plan Fix
+- Create a plan: \`op:orchestrate_plan\`
+- Identify affected files and potential side effects
+- Wait for user approval
+
+### 3. Write Regression Test
+- Write a test that reproduces the bug (RED)
+- Confirm it fails for the right reason
+
+### 4. Fix
+- Apply the minimal fix
+- Run the regression test — must pass (GREEN)
+- Run full test suite — no new failures
+
+### 5. Capture
+- If the bug reveals a pattern or anti-pattern, capture it: \`op:capture_knowledge\`
+- Complete orchestration: \`op:orchestrate_complete\`
+`,
+    gates: `gates:
+  - phase: pre-execution
+    requirement: Root cause identified and fix plan approved
+    check: plan-approved
+
+  - phase: post-task
+    requirement: Regression test passes and no new failures
+    check: tests-pass
+
+  - phase: completion
+    requirement: Anti-pattern captured if applicable
+    check: knowledge-captured
+`,
+    tools: `tools:
+  - soleri_vault op:search_intelligent
+  - soleri_vault op:capture_knowledge
+  - soleri_planner op:create_plan
+  - soleri_brain op:recommend
+`,
+  },
+  {
+    name: 'code-review',
+    prompt: `# Code Review
+
+## When to Use
+When reviewing code, auditing quality, or checking for issues.
+
+## Steps
+
+### 1. Context
+- Search vault for relevant patterns and anti-patterns: \`op:search_intelligent\`
+- Understand the intent of the changes
+
+### 2. Review
+- Check for correctness, readability, and maintainability
+- Verify test coverage
+- Check for security issues
+- Validate accessibility if applicable
+
+### 3. Feedback
+- Provide actionable, specific feedback
+- Reference vault patterns where applicable
+- Distinguish blocking issues from suggestions
+
+### 4. Capture
+- If review reveals new patterns or anti-patterns, capture them: \`op:capture_knowledge\`
+`,
+    gates: `gates:
+  - phase: completion
+    requirement: All blocking issues addressed
+    check: issues-resolved
+`,
+    tools: `tools:
+  - soleri_vault op:search_intelligent
+  - soleri_vault op:capture_knowledge
+  - soleri_brain op:recommend
+`,
+  },
+];
+
+// ─── Main Scaffolder ──────────────────────────────────────────────────
+
+/**
+ * Scaffold a file-tree agent.
+ *
+ * Creates a folder with agent.yaml, .mcp.json, instructions/, workflows/,
+ * and auto-generates CLAUDE.md. No TypeScript, no build step.
+ */
+export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): FileTreeScaffoldResult {
+  // Validate config
+  const parseResult = AgentYamlSchema.safeParse(input);
+  if (!parseResult.success) {
+    return {
+      success: false,
+      agentDir: join(outputDir, input.id ?? 'unknown'),
+      filesCreated: [],
+      summary: `Invalid config: ${parseResult.error.message}`,
+    };
+  }
+
+  const config = parseResult.data;
+  const agentDir = join(outputDir, config.id);
+  const filesCreated: string[] = [];
+
+  // Check for existing directory
+  if (existsSync(agentDir)) {
+    return {
+      success: false,
+      agentDir,
+      filesCreated: [],
+      summary: `Directory already exists: ${agentDir}. Choose a different ID or remove it.`,
+    };
+  }
+
+  // ─── 1. Create directory structure ──────────────────────────
+  const dirs = ['', 'instructions', 'workflows', 'knowledge', 'skills', 'hooks', 'data'];
+
+  // Add workflow subdirectories
+  for (const wf of BUILTIN_WORKFLOWS) {
+    dirs.push(`workflows/${wf.name}`);
+  }
+
+  for (const dir of dirs) {
+    mkdirSync(join(agentDir, dir), { recursive: true });
+  }
+
+  // ─── 2. Write agent.yaml ────────────────────────────────────
+  const agentYamlContent = yamlStringify(buildAgentYaml(config), {
+    lineWidth: 100,
+    singleQuote: true,
+  });
+  writeFile(agentDir, 'agent.yaml', agentYamlContent, filesCreated);
+
+  // ─── 3. Write .mcp.json ─────────────────────────────────────
+  const mcpJson = {
+    mcpServers: {
+      'soleri-engine': {
+        command: 'npx',
+        args: ['@soleri/engine', '--agent', './agent.yaml'],
+      },
+    },
+  };
+  writeFile(agentDir, '.mcp.json', JSON.stringify(mcpJson, null, 2) + '\n', filesCreated);
+
+  // ─── 4. Write .gitignore ────────────────────────────────────
+  writeFile(
+    agentDir,
+    '.gitignore',
+    [
+      '# Auto-generated — do not commit',
+      'CLAUDE.md',
+      'AGENTS.md',
+      'instructions/_engine.md',
+      '',
+    ].join('\n'),
+    filesCreated,
+  );
+
+  // ─── 5. Write engine rules ──────────────────────────────────
+  writeFile(agentDir, 'instructions/_engine.md', getEngineRulesContent(), filesCreated);
+
+  // ─── 6. Write user instruction files ────────────────────────
+  // Generate domain-specific instruction file if agent has specialized domains
+  if (config.domains.length > 0) {
+    const domainLines = [
+      '# Domain Knowledge',
+      '',
+      `This agent specializes in: ${config.domains.join(', ')}.`,
+      '',
+      '## Principles',
+      '',
+      ...config.principles.map((p) => `- ${p}`),
+      '',
+    ];
+    writeFile(agentDir, 'instructions/domain.md', domainLines.join('\n'), filesCreated);
+  }
+
+  // ─── 7. Write workflows ─────────────────────────────────────
+  for (const wf of BUILTIN_WORKFLOWS) {
+    writeFile(agentDir, `workflows/${wf.name}/prompt.md`, wf.prompt, filesCreated);
+    writeFile(agentDir, `workflows/${wf.name}/gates.yaml`, wf.gates, filesCreated);
+    writeFile(agentDir, `workflows/${wf.name}/tools.yaml`, wf.tools, filesCreated);
+  }
+
+  // ─── 8. Write empty knowledge bundle ────────────────────────
+  for (const domain of config.domains) {
+    const bundle = {
+      domain,
+      version: '1.0.0',
+      entries: [],
+    };
+    writeFile(
+      agentDir,
+      `knowledge/${domain}.json`,
+      JSON.stringify(bundle, null, 2) + '\n',
+      filesCreated,
+    );
+  }
+
+  // ─── 9. Generate CLAUDE.md ──────────────────────────────────
+  const { content: claudeMd } = composeClaudeMd(agentDir);
+  writeFile(agentDir, 'CLAUDE.md', claudeMd, filesCreated);
+
+  // ─── 10. Summary ────────────────────────────────────────────
+  const summary = [
+    `Agent "${config.name}" scaffolded at ${agentDir}`,
+    '',
+    `  Files: ${filesCreated.length}`,
+    `  Domains: ${config.domains.join(', ')}`,
+    `  Workflows: ${BUILTIN_WORKFLOWS.map((w) => w.name).join(', ')}`,
+    '',
+    'Next steps:',
+    `  1. cd ${config.id}`,
+    '  2. Review agent.yaml and customize instructions/',
+    '  3. Run: soleri install   (registers MCP server)',
+    '  4. Run: soleri dev       (watches files, auto-regenerates CLAUDE.md)',
+    '',
+    'No build step needed — this agent is ready to use.',
+  ].join('\n');
+
+  return {
+    success: true,
+    agentDir,
+    filesCreated,
+    summary,
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function writeFile(
+  agentDir: string,
+  relativePath: string,
+  content: string,
+  filesCreated: string[],
+): void {
+  const fullPath = join(agentDir, relativePath);
+  const dir = join(
+    agentDir,
+    relativePath.includes('/') ? relativePath.split('/').slice(0, -1).join('/') : '',
+  );
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(fullPath, content, 'utf-8');
+  filesCreated.push(relativePath);
+}
+
+/**
+ * Build a clean agent.yaml object for serialization.
+ * Strips defaults and empty optionals for cleaner output.
+ */
+function buildAgentYaml(config: AgentYaml): Record<string, unknown> {
+  const yaml: Record<string, unknown> = {
+    id: config.id,
+    name: config.name,
+    role: config.role,
+    description: config.description,
+    domains: config.domains,
+    principles: config.principles,
+  };
+
+  if (config.tone && config.tone !== 'pragmatic') {
+    yaml.tone = config.tone;
+  }
+
+  if (config.greeting) {
+    yaml.greeting = config.greeting;
+  }
+
+  // Engine config — only include non-defaults
+  const engine: Record<string, unknown> = {};
+  if (config.engine?.vault) engine.vault = config.engine.vault;
+  if (config.engine?.learning === false) engine.learning = false;
+  if (config.engine?.cognee === true) engine.cognee = true;
+  if (Object.keys(engine).length > 0) yaml.engine = engine;
+
+  // Vaults
+  if (config.vaults && config.vaults.length > 0) {
+    yaml.vaults = config.vaults;
+  }
+
+  // Setup — only include non-defaults
+  const setup: Record<string, unknown> = {};
+  if (config.setup?.target && config.setup.target !== 'opencode')
+    setup.target = config.setup.target;
+  if (config.setup?.model && config.setup.model !== 'claude-code-sonnet-4')
+    setup.model = config.setup.model;
+  if (Object.keys(setup).length > 0) yaml.setup = setup;
+
+  // Packs
+  if (config.packs && config.packs.length > 0) {
+    yaml.packs = config.packs;
+  }
+
+  return yaml;
+}