aura-code 0.3.0

package/dist/orchestration/plan-store.js

@@ -0,0 +1,176 @@
+"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.planStore = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// Serialises concurrent writes to the same memory file so parallel steps
+// cannot clobber each other's entries (read-modify-write race condition).
+const writeLocks = new Map();
+/**
+ * On-disk persistence for execution plans and orchestration memory.
+ *
+ * Plans are stored as individual JSON files under ~/.aura/plans/{id}.json
+ * so they survive process restarts and can be inspected or replayed.
+ *
+ * Per-project memory is appended to {projectRoot}/.aura/memory.json and
+ * keyed by a string so specialists can share facts across steps.
+ */
+exports.planStore = {
+    /** Returns the directory where plan files are stored. */
+    plansDir() {
+        return path.join(process.env.HOME ?? '/tmp', '.aura', 'plans');
+    },
+    /**
+     * Persists an execution plan to ~/.aura/plans/{id}.json.
+     * Uses a .tmp rename to avoid corrupt files on crash.
+     */
+    async save(plan) {
+        const dir = this.plansDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, `${plan.id}.json`);
+        const tmp = filePath + '.tmp';
+        await fs.promises.writeFile(tmp, JSON.stringify(plan, null, 2), 'utf8');
+        await fs.promises.rename(tmp, filePath);
+    },
+    /**
+     * Loads a plan by id.
+     * Returns `null` if the file does not exist or cannot be parsed.
+     */
+    async load(id) {
+        const filePath = path.join(this.plansDir(), `${id}.json`);
+        if (!fs.existsSync(filePath))
+            return null;
+        const raw = await fs.promises.readFile(filePath, 'utf8');
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    },
+    /**
+     * Returns all saved plans, most recently created first.
+     * Silently skips files that cannot be parsed.
+     */
+    async list() {
+        const dir = this.plansDir();
+        if (!fs.existsSync(dir))
+            return [];
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+        const plans = [];
+        for (const file of files) {
+            const raw = await fs.promises.readFile(path.join(dir, file), 'utf8');
+            try {
+                plans.push(JSON.parse(raw));
+            }
+            catch {
+                /* skip corrupt file */
+            }
+        }
+        return plans.sort((a, b) => b.created - a.created);
+    },
+    /**
+     * Removes a plan file from disk.
+     * Resolves silently if the file does not exist.
+     */
+    async delete(id) {
+        const filePath = path.join(this.plansDir(), `${id}.json`);
+        if (!fs.existsSync(filePath))
+            return;
+        await fs.promises.unlink(filePath);
+    },
+    // ───────────────────────────────────────────────────────────────────────────
+    // Per-project orchestration memory
+    // ───────────────────────────────────────────────────────────────────────────
+    /** Returns the path to the memory file for a given project root. */
+    memoryPath(projectRoot) {
+        return path.join(projectRoot, '.aura', 'memory.json');
+    },
+    /**
+     * Appends a memory entry to {projectRoot}/.aura/memory.json.
+     * Creates the file (and parent directory) if they do not yet exist.
+     * Uses a .tmp rename to avoid corrupt files on crash.
+     */
+    async saveMemory(projectRoot, entry) {
+        const filePath = this.memoryPath(projectRoot);
+        const existing = writeLocks.get(filePath) ?? Promise.resolve();
+        const next = existing.then(async () => {
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            const entries = await this.listMemory(projectRoot);
+            entries.push(entry);
+            const tmp = filePath + '.tmp';
+            await fs.promises.writeFile(tmp, JSON.stringify(entries, null, 2), 'utf8');
+            await fs.promises.rename(tmp, filePath);
+        });
+        writeLocks.set(filePath, next);
+        return next;
+    },
+    /**
+     * Returns the most recent memory entry matching `key`, or `null` if none
+     * exists.  When multiple entries share the same key, the latest timestamp
+     * wins.
+     */
+    async getMemory(projectRoot, key) {
+        const all = await this.listMemory(projectRoot);
+        const matches = all.filter(e => e.key === key);
+        if (matches.length === 0)
+            return null;
+        return matches.reduce((best, e) => (e.timestamp > best.timestamp ? e : best));
+    },
+    /**
+     * Returns all memory entries for a project, sorted newest-first.
+     * Returns an empty array if the memory file does not exist.
+     */
+    async listMemory(projectRoot) {
+        const filePath = this.memoryPath(projectRoot);
+        if (!fs.existsSync(filePath))
+            return [];
+        const raw = await fs.promises.readFile(filePath, 'utf8');
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed)
+                ? parsed.sort((a, b) => b.timestamp - a.timestamp)
+                : [];
+        }
+        catch {
+            return [];
+        }
+    },
+};
+//# sourceMappingURL=plan-store.js.map

package/dist/orchestration/plan-store.js.map

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

package/dist/orchestration/router-prompts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * System prompt injected when the router asks a model to decide whether a
+ * task should be decomposed into a multi-agent plan or handled by a single
+ * agent.  The model must respond with a single JSON object and nothing else.
+ */
+export declare const ROUTER_SYSTEM_PROMPT = "You are the orchestration router for Aura, a multi-agent coding system.\n\nYour sole job is to analyse an incoming coding task and decide whether it should be:\n  A) Handled by a SINGLE agent in one continuous session, or\n  B) DECOMPOSED into a structured multi-agent execution plan.\n\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\nDECOMPOSE the task (shouldDecompose: true) ONLY when ALL of the following hold:\n  \u2022 The task contains genuinely independent subtasks that can proceed in parallel\n    or must be handed off between specialist roles (researcher \u2192 coder \u2192 reviewer).\n  \u2022 It requires BOTH deep research/exploration AND non-trivial implementation.\n  \u2022 It spans multiple unrelated modules that have no shared context requirements.\n  \u2022 The generated code would meaningfully benefit from a dedicated review pass\n    that could catch issues a single-agent loop would miss.\n\nSTAY SINGLE AGENT (shouldDecompose: false) when ANY of the following applies:\n  \u2022 The task is focused on one file, function, or tightly coupled area.\n  \u2022 Continuous rolling context is essential (refactors, bug hunts, exploratory work).\n  \u2022 The task is exploratory or the scope is unclear \u2014 decomposition would be premature.\n  \u2022 The task is simple enough to complete in a handful of tool calls.\n  \u2022 The overhead of coordinating multiple agents would exceed the benefit.\n\nWhen in doubt, default to SINGLE AGENT. Decomposition adds coordination cost;\nonly choose it when the parallelism or specialisation gain is obvious.\n\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\nOUTPUT FORMAT \u2014 respond with ONLY valid JSON, no prose, no markdown fences:\n\n{\n  \"shouldDecompose\": boolean,\n  \"reason\": string,\n  \"confidence\": number,\n  \"estimatedSteps\": number\n}\n\nField rules:\n  \u2022 \"shouldDecompose\" \u2014 true or false.\n  \u2022 \"reason\"          \u2014 one concise sentence explaining the decision.\n  \u2022 \"confidence\"      \u2014 your certainty in [0.0, 1.0]; use 0.5 when genuinely uncertain.\n  \u2022 \"estimatedSteps\"  \u2014 ONLY include this key when shouldDecompose is true;\n                        omit it entirely when shouldDecompose is false.\n\nDo NOT include any text, explanation, or formatting outside the JSON object.";

package/dist/orchestration/router-prompts.js

@@ -0,0 +1,55 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// System prompts used by the orchestration router
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTER_SYSTEM_PROMPT = void 0;
+/**
+ * System prompt injected when the router asks a model to decide whether a
+ * task should be decomposed into a multi-agent plan or handled by a single
+ * agent.  The model must respond with a single JSON object and nothing else.
+ */
+exports.ROUTER_SYSTEM_PROMPT = `You are the orchestration router for Aura, a multi-agent coding system.
+
+Your sole job is to analyse an incoming coding task and decide whether it should be:
+  A) Handled by a SINGLE agent in one continuous session, or
+  B) DECOMPOSED into a structured multi-agent execution plan.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DECOMPOSE the task (shouldDecompose: true) ONLY when ALL of the following hold:
+  • The task contains genuinely independent subtasks that can proceed in parallel
+    or must be handed off between specialist roles (researcher → coder → reviewer).
+  • It requires BOTH deep research/exploration AND non-trivial implementation.
+  • It spans multiple unrelated modules that have no shared context requirements.
+  • The generated code would meaningfully benefit from a dedicated review pass
+    that could catch issues a single-agent loop would miss.
+
+STAY SINGLE AGENT (shouldDecompose: false) when ANY of the following applies:
+  • The task is focused on one file, function, or tightly coupled area.
+  • Continuous rolling context is essential (refactors, bug hunts, exploratory work).
+  • The task is exploratory or the scope is unclear — decomposition would be premature.
+  • The task is simple enough to complete in a handful of tool calls.
+  • The overhead of coordinating multiple agents would exceed the benefit.
+
+When in doubt, default to SINGLE AGENT. Decomposition adds coordination cost;
+only choose it when the parallelism or specialisation gain is obvious.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OUTPUT FORMAT — respond with ONLY valid JSON, no prose, no markdown fences:
+
+{
+  "shouldDecompose": boolean,
+  "reason": string,
+  "confidence": number,
+  "estimatedSteps": number
+}
+
+Field rules:
+  • "shouldDecompose" — true or false.
+  • "reason"          — one concise sentence explaining the decision.
+  • "confidence"      — your certainty in [0.0, 1.0]; use 0.5 when genuinely uncertain.
+  • "estimatedSteps"  — ONLY include this key when shouldDecompose is true;
+                        omit it entirely when shouldDecompose is false.
+
+Do NOT include any text, explanation, or formatting outside the JSON object.`;
+//# sourceMappingURL=router-prompts.js.map

package/dist/orchestration/router-prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-prompts.js","sourceRoot":"","sources":["../../src/orchestration/router-prompts.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,kDAAkD;AAClD,gFAAgF;;;AAEhF;;;;GAIG;AACU,QAAA,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EA0CyC,CAAC"}

package/dist/orchestration/router.d.ts

@@ -0,0 +1,23 @@
+import type { LLMProvider } from '../providers/types.js';
+import type { ProjectContext } from '../agent/context.js';
+import type { ProjectPerception } from '../perception/types.js';
+import type { RouterDecision } from './types.js';
+/** Inputs required to route a task through the orchestrator. */
+export interface RouterOptions {
+    /** Provider used to call the routing model. */
+    provider: LLMProvider;
+    /** Loaded project context (name, language, framework, tree, …). */
+    context: ProjectContext;
+    /** The raw user task string to be routed. */
+    task: string;
+    /** Optional perception snapshot; risk areas are surfaced to the router when present. */
+    perception?: ProjectPerception;
+}
+/**
+ * Asks the model to decide whether `task` should be decomposed into a
+ * multi-agent plan or handled by a single agent.
+ *
+ * Never throws — any parse or provider error returns a safe default that keeps
+ * execution on the single-agent path.
+ */
+export declare function routeTask(opts: RouterOptions): Promise<RouterDecision>;

package/dist/orchestration/router.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeTask = routeTask;
+const router_prompts_js_1 = require("./router-prompts.js");
+/**
+ * Asks the model to decide whether `task` should be decomposed into a
+ * multi-agent plan or handled by a single agent.
+ *
+ * Never throws — any parse or provider error returns a safe default that keeps
+ * execution on the single-agent path.
+ */
+async function routeTask(opts) {
+    const { provider, context, task, perception } = opts;
+    const userMessage = buildUserMessage(context, task, perception);
+    const history = [{ role: 'user', content: userMessage }];
+    let rawText = '';
+    try {
+        const response = await provider.complete(router_prompts_js_1.ROUTER_SYSTEM_PROMPT, history, []);
+        rawText = response.text.trim();
+    }
+    catch {
+        return safeDefault('Provider error — defaulting to single agent');
+    }
+    return parseDecision(rawText);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function buildUserMessage(context, task, perception) {
+    const lines = [
+        `Project: ${context.name}`,
+        `Language: ${context.language}`,
+        `Framework: ${context.framework}`,
+    ];
+    if (perception && perception.constraints.riskAreas.length > 0) {
+        lines.push(`Risk areas: ${perception.constraints.riskAreas.join(', ')}`);
+    }
+    lines.push('', `Task: ${task}`);
+    return lines.join('\n');
+}
+function parseDecision(raw) {
+    let parsed;
+    try {
+        // Strip accidental markdown fences the model might emit despite instructions
+        const cleaned = raw.replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/, '').trim();
+        parsed = JSON.parse(cleaned);
+    }
+    catch {
+        return safeDefault('Parse failed — defaulting to single agent');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return safeDefault('Unexpected response shape — defaulting to single agent');
+    }
+    const r = parsed;
+    const shouldDecompose = typeof r.shouldDecompose === 'boolean' ? r.shouldDecompose : false;
+    const reason = typeof r.reason === 'string' && r.reason.length > 0
+        ? r.reason
+        : 'No reason provided';
+    const rawConf = typeof r.confidence === 'number' && Number.isFinite(r.confidence) ? r.confidence : 0;
+    const confidence = Math.min(1, Math.max(0, rawConf));
+    const decision = { shouldDecompose, reason, confidence };
+    if (shouldDecompose && typeof r.estimatedSteps === 'number' && r.estimatedSteps > 0) {
+        decision.estimatedSteps = Math.round(r.estimatedSteps);
+    }
+    return decision;
+}
+function safeDefault(reason) {
+    return { shouldDecompose: false, reason, confidence: 0 };
+}
+//# sourceMappingURL=router.js.map

package/dist/orchestration/router.js.map

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

package/dist/orchestration/ruby-detect.d.ts

@@ -0,0 +1,6 @@
+import type { RubyProjectContext } from './ruby-types.js';
+/**
+ * Builds a RubyProjectContext from on-disk signals (Gemfile, layout, etc.).
+ * Safe to call on non-Ruby trees — returns `framework: 'unknown'` with empty entrypoints.
+ */
+export declare function detectRubyProject(projectRoot: string): RubyProjectContext;

package/dist/orchestration/ruby-detect.js

@@ -0,0 +1,130 @@
+"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.detectRubyProject = detectRubyProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function readTextIfExists(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return undefined;
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function detectRubyVersion(projectRoot) {
+    const dotRuby = readTextIfExists(path.join(projectRoot, '.ruby-version'));
+    if (dotRuby?.trim())
+        return dotRuby.trim();
+    const gemfile = readTextIfExists(path.join(projectRoot, 'Gemfile'));
+    if (!gemfile)
+        return undefined;
+    const m = gemfile.match(/^\s*ruby\s+['"]([^'"]+)['"]/m);
+    return m?.[1];
+}
+function detectFramework(projectRoot, gemfile) {
+    if (fs.existsSync(path.join(projectRoot, 'config', 'application.rb')))
+        return 'rails';
+    if (gemfile?.includes("'rails'") || gemfile?.includes('"rails"'))
+        return 'rails';
+    if (gemfile?.includes("'sinatra'") || gemfile?.includes('"sinatra"'))
+        return 'sinatra';
+    if (gemfile?.includes("'rack'") || gemfile?.includes('"rack"'))
+        return 'rack';
+    if (fs.existsSync(path.join(projectRoot, 'lib')) && fs.existsSync(path.join(projectRoot, 'Gemfile'))) {
+        return 'plain';
+    }
+    const rbFiles = fs.readdirSync(projectRoot).filter(f => f.endsWith('.rb'));
+    if (rbFiles.length > 0)
+        return 'plain';
+    return 'unknown';
+}
+function detectTestFramework(gemfile) {
+    if (!gemfile)
+        return 'unknown';
+    if (gemfile.includes('rspec'))
+        return 'rspec';
+    if (gemfile.includes('minitest'))
+        return 'minitest';
+    if (gemfile.includes('test-unit'))
+        return 'test-unit';
+    return 'unknown';
+}
+function detectEntrypoints(projectRoot, framework) {
+    const candidates = [
+        'config.ru',
+        'app.rb',
+        'main.rb',
+        'bin/rails',
+        'lib/application.rb',
+        'Rakefile',
+    ];
+    const found = [];
+    for (const rel of candidates) {
+        const full = path.join(projectRoot, rel);
+        if (fs.existsSync(full))
+            found.push(rel);
+    }
+    if (framework === 'rails' && !found.includes('config.ru')) {
+        const ru = path.join(projectRoot, 'config.ru');
+        if (fs.existsSync(ru))
+            found.push('config.ru');
+    }
+    return found;
+}
+/**
+ * Builds a RubyProjectContext from on-disk signals (Gemfile, layout, etc.).
+ * Safe to call on non-Ruby trees — returns `framework: 'unknown'` with empty entrypoints.
+ */
+function detectRubyProject(projectRoot) {
+    const gemfilePath = path.join(projectRoot, 'Gemfile');
+    const hasGemfile = fs.existsSync(gemfilePath);
+    const hasGemfileLock = fs.existsSync(path.join(projectRoot, 'Gemfile.lock'));
+    const gemfile = hasGemfile ? readTextIfExists(gemfilePath) : undefined;
+    const framework = detectFramework(projectRoot, gemfile);
+    return {
+        projectRoot,
+        framework,
+        hasGemfile,
+        hasGemfileLock,
+        rubyVersion: detectRubyVersion(projectRoot),
+        testFramework: detectTestFramework(gemfile),
+        entrypoints: detectEntrypoints(projectRoot, framework),
+        capturedAt: Date.now(),
+    };
+}
+//# sourceMappingURL=ruby-detect.js.map

package/dist/orchestration/ruby-detect.js.map

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

package/dist/orchestration/ruby-types.d.ts

@@ -0,0 +1,44 @@
+/** Detected application framework for a Ruby codebase. */
+export type RubyFramework = 'rails' | 'sinatra' | 'rack' | 'plain' | 'unknown';
+/** Test runner commonly used in Ruby projects. */
+export type RubyTestFramework = 'rspec' | 'minitest' | 'test-unit' | 'unknown';
+/**
+ * Snapshot of Ruby-specific project metadata used by the orchestrator when
+ * routing goals and assigning specialists to gem- or Rails-aware work.
+ */
+export interface RubyProjectContext {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** Inferred framework from Gemfile / directory layout. */
+    framework: RubyFramework;
+    /** Whether a Gemfile exists at the project root. */
+    hasGemfile: boolean;
+    /** Whether a Gemfile.lock is present (dependency graph is pinned). */
+    hasGemfileLock: boolean;
+    /** Parsed `.ruby-version` or Gemfile `ruby` directive, if found. */
+    rubyVersion?: string;
+    /** Detected test framework, if any. */
+    testFramework: RubyTestFramework;
+    /** Top-level entry files the orchestrator should treat as significant. */
+    entrypoints: string[];
+    /** Unix timestamp (ms) when this context was captured. */
+    capturedAt: number;
+}
+/** Identifies which Ruby Diamond surface produced or consumes orchestration data. */
+export type RubyDiamondSurface = 'aura-code' | 'ruby-diamond-client' | 'harness' | 'unknown';
+/**
+ * Cross-surface envelope for passing orchestration payloads between Aura CLI,
+ * Ruby Diamond desktop, and Python harness generators.
+ */
+export interface RubyDiamondEnvelope<T = unknown> {
+    /** Schema version for forward-compatible deserialization. */
+    version: 1;
+    /** Originating or target surface. */
+    surface: RubyDiamondSurface;
+    /** Logical message kind (e.g. plan_created, step_done). */
+    kind: string;
+    /** Unix timestamp (ms). */
+    timestamp: number;
+    /** Typed payload. */
+    payload: T;
+}

package/dist/orchestration/ruby-types.js

@@ -0,0 +1,6 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// Ruby language / Ruby Diamond project context
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ruby-types.js.map

package/dist/orchestration/ruby-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-types.js","sourceRoot":"","sources":["../../src/orchestration/ruby-types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+CAA+C;AAC/C,gFAAgF"}

package/dist/orchestration/specialist-prompts.d.ts

@@ -0,0 +1,19 @@
+import type { PlanStep, OrchestrationMemory } from './types.js';
+/**
+ * System prompt for the researcher specialist.
+ * The researcher is read-only: it gathers context, identifies patterns, and
+ * produces structured summaries. It must never write or modify files.
+ */
+export declare const RESEARCHER_SYSTEM_PROMPT = "You are the Research specialist for Aura \u2014 a multi-agent coding system.\n\n## Your role\nYou gather context, read code, and produce structured analysis. You have only\nread-only tools. You never create, edit, or delete files.\n\n## Your process\n1. READ everything relevant to the task \u2014 do not guess or assume.\n2. FOLLOW import chains and dependency graphs to understand relationships.\n3. IDENTIFY patterns, conventions, and constraints in the codebase.\n4. OUTPUT a structured summary in the exact format below.\n\n## Output format\nAfter you have gathered sufficient information, ouput ONLY the following\nstructured summary. No markdown fences, no extra prose \u2014 just the raw sections:\n\n---\nKEY FILES FOUND\n- path/to/file.ts \u2014 brief description of what it contains and why it matters\n- path/to/another.ts \u2014 brief description\n...\n\nIMPORTANT PATTERNS\n- pattern description (e.g. \"all middleware exports a factory function\")\n...\n\nDEPENDENCIES DISCOVERED\n- file-a.ts depends on file-b.ts (via import of X)\n- external: package-name (used in N files)\n...\n\nRISKS IDENTIFIED\n- risk description (e.g. \"auth.ts has no error boundaries on line 42\")\n...\n\n---\n\n## Rules\n- NEVER write, edit, or delete files.\n- Always read files before reporting on them.\n- If a file is large, use line ranges to focus on the relevant sections.\n- Prefer search_code to find patterns across the codebase.\n- If you cannot find enough information, say so explicitly rather than guessing.\n- Keep your analysis focused on the task at hand \u2014 don't wander.\n- Spend at most 2 turns reading/gathering, then produce your summary.";
+/**
+ * System prompt for the reviewer specialist.
+ * The reviewer checks correctness, security, style, and test coverage. It is
+ * read-only and MUST output issues in a structured JSON format.
+ */
+export declare const REVIEWER_SYSTEM_PROMPT = "You are the Review specialist for Aura \u2014 a multi-agent coding system.\n\n## Your role\nYou review code changes for correctness, security, test coverage, and style\nconsistency. You have only read-only tools. You never create, edit, or delete files.\n\n## Your process\n1. READ the files that were modified \u2014 check the diff with git_diff.\n2. READ related files that may be impacted.\n3. CHECK for:\n   - Correctness: logic errors, edge cases, off-by-one errors.\n   - Security: injection risks, leaked secrets, unsafe input handling.\n   - Test coverage: are new paths tested? Do existing tests still pass?\n   - Style consistency: does the change follow existing conventions?\n4. OUTPUT a structured issues list.\n\n## Output format\nAfter you have completed your review, output ONLY a valid JSON object:\n\n{\n  \"issues\": [\n    {\n      \"severity\": \"critical\" | \"major\" | \"minor\",\n      \"description\": \"What the issue is\",\n      \"location\": \"file.ts:line-number\"\n    }\n  ]\n}\n\nIf you find no issues, output exactly:\n{ \"issues\": [] }\nand then clearly state: \"No issues found.\"\n\n## Severity guide\n- critical \u2014 security vulnerability, data loss, or crash-on-start\n- major    \u2014 incorrect behaviour, missing error handling, broken test\n- minor    \u2014 style drift, missing comment, unnecessary verbosity\n\n## Rules\n- NEVER write, edit, or delete files.\n- Never approve code that introduces security vulnerabilities.\n- If you find a critical issue, state it first and be explicit about the risk.\n- Do not flag issues you cannot verify \u2014 if unsure, omit it rather than misattribute.\n- Each issue must include a specific file path and line number.";
+/**
+ * Builds the context block injected into the coder's task description.
+ * Includes step-specific scope, relevant memory from prior steps, and an
+ * explicit instruction to stay focused on the assigned task.
+ */
+export declare function CODER_CONTEXT_TEMPLATE(step: PlanStep, memory: OrchestrationMemory[]): string;