vralphy 0.8.0

package/dist/lib/skills.js

@@ -0,0 +1,132 @@
+import { readFile, readdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, basename } from 'path';
+/**
+ * Parse frontmatter from markdown file
+ */
+function parseFrontmatter(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!frontmatterMatch) {
+        return { metadata: {}, content };
+    }
+    const [, frontmatter, body] = frontmatterMatch;
+    const metadata = {};
+    for (const line of frontmatter.split('\n')) {
+        const match = line.match(/^(\w+):\s*(.*)$/);
+        if (match) {
+            const [, key, value] = match;
+            if (value.startsWith('[') || value.startsWith('"')) {
+                try {
+                    metadata[key] = JSON.parse(value);
+                }
+                catch (e) {
+                    if (process.env.VRALPHY_VERBOSE === 'true') {
+                        console.warn(`Warning: Failed to parse JSON value for '${key}': ${value}`);
+                    }
+                    metadata[key] = value;
+                }
+            }
+            else if (value.startsWith('-')) {
+                metadata[key] = [value.slice(1).trim()];
+            }
+            else {
+                metadata[key] = value;
+            }
+        }
+        else if (line.startsWith('  -') && Object.keys(metadata).length > 0) {
+            const lastKey = Object.keys(metadata).pop();
+            const arr = metadata[lastKey];
+            if (Array.isArray(arr)) {
+                arr.push(line.slice(4).trim());
+            }
+        }
+    }
+    return { metadata, content: body };
+}
+/**
+ * Load a single skill from file
+ */
+async function loadSkill(path) {
+    const content = await readFile(path, 'utf-8');
+    const { metadata, content: body } = parseFrontmatter(content);
+    const name = metadata.name ?? basename(path, '.md');
+    return {
+        name,
+        path,
+        metadata: {
+            name,
+            description: metadata.description,
+            triggers: metadata.triggers,
+            alwaysInclude: metadata.alwaysInclude,
+        },
+        content: body,
+    };
+}
+/**
+ * Load all skills from a directory
+ */
+export async function loadSkills(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const files = await readdir(dir);
+    const mdFiles = files.filter((f) => f.endsWith('.md'));
+    const skills = [];
+    for (const file of mdFiles) {
+        try {
+            const skill = await loadSkill(join(dir, file));
+            skills.push(skill);
+        }
+        catch (e) {
+            console.error(`Failed to load skill ${file}:`, e);
+        }
+    }
+    return skills;
+}
+/**
+ * Filter skills by triggers matching text
+ */
+export function filterSkillsByTriggers(skills, text) {
+    const lowerText = text.toLowerCase();
+    return skills.filter((skill) => {
+        if (skill.metadata.alwaysInclude)
+            return true;
+        if (!skill.metadata.triggers)
+            return false;
+        return skill.metadata.triggers.some((trigger) => lowerText.includes(trigger.toLowerCase()));
+    });
+}
+/**
+ * Format skills for prompt injection
+ */
+export function formatSkillsForPrompt(skills) {
+    if (skills.length === 0)
+        return '';
+    let result = '## Loaded Skills\n\n';
+    for (const skill of skills) {
+        const name = skill.name ?? 'Unnamed Skill';
+        const description = skill.metadata?.description ?? '';
+        const content = skill.content ?? '';
+        result += `### ${name}\n`;
+        if (description) {
+            result += `${description}\n\n`;
+        }
+        result += `${content}\n\n`;
+    }
+    return result;
+}
+/**
+ * List available skills (for CLI command)
+ */
+export async function listSkills(dir) {
+    const skills = await loadSkills(dir);
+    return skills.map((s) => ({ name: s.name, description: s.metadata.description }));
+}
+/**
+ * Get skill by name
+ */
+export async function getSkill(dir, name) {
+    const skills = await loadSkills(dir);
+    return skills.find((s) => s.name === name);
+}
+//# sourceMappingURL=skills.js.map

package/dist/lib/skills.js.map

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

package/dist/lib/slack.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Slack webhook notifications for vralphy
+ * Fire-and-forget - never blocks or fails execution
+ */
+export interface SlackMessage {
+    text: string;
+    blocks?: SlackBlock[];
+}
+interface SlackBlock {
+    type: string;
+    text?: {
+        type: string;
+        text: string;
+        emoji?: boolean;
+    };
+}
+/**
+ * Send a message to Slack via webhook
+ * Fire-and-forget: never blocks or throws
+ */
+export declare function sendSlack(webhookUrl: string, message: SlackMessage): void;
+/**
+ * Create session start message
+ */
+export declare function sessionStartMessage(project: string, command: string, maxIterations: number, engine: string, model: string): SlackMessage;
+/**
+ * Create iteration end message
+ */
+export declare function iterationEndMessage(project: string, iteration: number, maxIterations: number, durationMs: number): SlackMessage;
+/**
+ * Create session end message
+ */
+export declare function sessionEndMessage(project: string, iterations: number, totalDurationMs: number, success: boolean): SlackMessage;
+/**
+ * Create error message for iteration failure
+ */
+export declare function iterationErrorMessage(project: string, iteration: number, maxIterations: number, error?: string): SlackMessage;
+/**
+ * Create plan completion message
+ */
+export declare function planCompletedMessage(project: string, totalTasks: number, iteration: number, durationMs: number): SlackMessage;
+export {};
+//# sourceMappingURL=slack.d.ts.map

package/dist/lib/slack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.d.ts","sourceRoot":"","sources":["../../src/lib/slack.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAQzE;AAeD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,YAAY,CAcd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,YAAY,CAMd;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,OAAO,GACf,YAAY,CA4Bd;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,YAAY,CAed;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,YAAY,CAiBd"}

package/dist/lib/slack.js

@@ -0,0 +1,130 @@
+/**
+ * Slack webhook notifications for vralphy
+ * Fire-and-forget - never blocks or fails execution
+ */
+/**
+ * Send a message to Slack via webhook
+ * Fire-and-forget: never blocks or throws
+ */
+export function sendSlack(webhookUrl, message) {
+    fetch(webhookUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(message),
+    }).catch(() => {
+        // Silently ignore errors - notifications should never block execution
+    });
+}
+/**
+ * Format duration in milliseconds to human-readable string
+ */
+function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds}s`;
+}
+/**
+ * Create session start message
+ */
+export function sessionStartMessage(project, command, maxIterations, engine, model) {
+    const iterationText = maxIterations > 0 ? `${maxIterations} iterations` : 'unlimited iterations';
+    return {
+        text: `:rocket: vralphy ${command} started on \`${project}\` (${iterationText})`,
+        blocks: [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `:rocket: *vralphy ${command} started*\nProject: \`${project}\`\nEngine: ${engine} (${model})\nIterations: ${iterationText}`,
+                },
+            },
+        ],
+    };
+}
+/**
+ * Create iteration end message
+ */
+export function iterationEndMessage(project, iteration, maxIterations, durationMs) {
+    const iterationText = maxIterations > 0 ? `${iteration}/${maxIterations}` : `${iteration}`;
+    const duration = formatDuration(durationMs);
+    return {
+        text: `:hourglass: Iteration ${iterationText} completed on \`${project}\` (${duration})`,
+    };
+}
+/**
+ * Create session end message
+ */
+export function sessionEndMessage(project, iterations, totalDurationMs, success) {
+    const duration = formatDuration(totalDurationMs);
+    if (success) {
+        return {
+            text: `:white_check_mark: vralphy completed on \`${project}\` - ${iterations} iteration(s), ${duration}`,
+            blocks: [
+                {
+                    type: 'section',
+                    text: {
+                        type: 'mrkdwn',
+                        text: `:white_check_mark: *vralphy completed*\nProject: \`${project}\`\nIterations: ${iterations}\nDuration: ${duration}`,
+                    },
+                },
+            ],
+        };
+    }
+    return {
+        text: `:x: vralphy failed on \`${project}\` after ${iterations} iteration(s)`,
+        blocks: [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `:x: *vralphy failed*\nProject: \`${project}\`\nIterations completed: ${iterations}`,
+                },
+            },
+        ],
+    };
+}
+/**
+ * Create error message for iteration failure
+ */
+export function iterationErrorMessage(project, iteration, maxIterations, error) {
+    const iterationText = maxIterations > 0 ? `${iteration}/${maxIterations}` : `${iteration}`;
+    const errorText = error ? `\nError: ${error}` : '';
+    return {
+        text: `:x: vralphy failed on iteration ${iterationText} on \`${project}\`${errorText}`,
+        blocks: [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `:x: *vralphy failed on iteration ${iterationText}*\nProject: \`${project}\`${errorText}`,
+                },
+            },
+        ],
+    };
+}
+/**
+ * Create plan completion message
+ */
+export function planCompletedMessage(project, totalTasks, iteration, durationMs) {
+    const duration = formatDuration(durationMs);
+    return {
+        text: `[${project}] Plan completed! ${totalTasks} tasks done in ${iteration} iteration(s) (${duration})`,
+        blocks: [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `:tada: *[${project}] Plan Completed*\n` +
+                        `All ${totalTasks} tasks are now checked off.\n` +
+                        `Iterations: ${iteration} | Duration: ${duration}\n` +
+                        `_Session continues - agent may find new work._`,
+                },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=slack.js.map

package/dist/lib/slack.js.map

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

package/dist/lib/slack.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=slack.test.d.ts.map

package/dist/lib/slack.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.test.d.ts","sourceRoot":"","sources":["../../src/lib/slack.test.ts"],"names":[],"mappings":""}

package/dist/lib/slack.test.js

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { sessionStartMessage, iterationEndMessage, sessionEndMessage, iterationErrorMessage, planCompletedMessage, } from './slack.js';
+describe('Slack message formatters', () => {
+    describe('sessionStartMessage', () => {
+        it('returns message with text and blocks', () => {
+            const msg = sessionStartMessage('my-project', 'build', 5, 'claude', 'opus');
+            expect(msg.text).toContain('my-project');
+            expect(msg.text).toContain('build');
+            expect(msg.blocks).toBeDefined();
+            expect(msg.blocks.length).toBeGreaterThan(0);
+        });
+        it('handles unlimited iterations', () => {
+            const msg = sessionStartMessage('proj', 'build', 0, 'claude', 'opus');
+            expect(msg.text).toContain('unlimited');
+        });
+    });
+    describe('iterationEndMessage', () => {
+        it('returns message with iteration count', () => {
+            const msg = iterationEndMessage('my-project', 3, 10, 60000);
+            expect(msg.text).toContain('3/10');
+            expect(msg.text).toContain('my-project');
+        });
+        it('handles unlimited iterations', () => {
+            const msg = iterationEndMessage('proj', 5, 0, 30000);
+            expect(msg.text).toContain('5');
+            expect(msg.text).not.toContain('5/');
+        });
+    });
+    describe('sessionEndMessage', () => {
+        it('returns success message with blocks', () => {
+            const msg = sessionEndMessage('my-project', 3, 120000, true);
+            expect(msg.text).toContain('completed');
+            expect(msg.text).toContain('my-project');
+            expect(msg.blocks).toBeDefined();
+        });
+        it('returns failure message with blocks', () => {
+            const msg = sessionEndMessage('my-project', 2, 60000, false);
+            expect(msg.text).toContain('failed');
+            expect(msg.blocks).toBeDefined();
+        });
+    });
+    describe('iterationErrorMessage', () => {
+        it('returns error message with blocks', () => {
+            const msg = iterationErrorMessage('my-project', 2, 5, 'Something went wrong');
+            expect(msg.text).toContain('failed');
+            expect(msg.text).toContain('2/5');
+            expect(msg.text).toContain('Something went wrong');
+            expect(msg.blocks).toBeDefined();
+        });
+        it('handles missing error message', () => {
+            const msg = iterationErrorMessage('my-project', 1, 3);
+            expect(msg.text).toContain('failed');
+            expect(msg.blocks).toBeDefined();
+        });
+    });
+    describe('planCompletedMessage', () => {
+        it('returns completion message with text and blocks', () => {
+            const msg = planCompletedMessage('my-project', 10, 3, 180000);
+            expect(msg.text).toContain('my-project');
+            expect(msg.text).toContain('10');
+            expect(msg.text).toContain('3');
+            expect(msg.blocks).toBeDefined();
+            expect(msg.blocks.length).toBeGreaterThan(0);
+        });
+        it('includes celebration and context in blocks', () => {
+            const msg = planCompletedMessage('proj', 5, 2, 60000);
+            const blockText = msg.blocks[0].text?.text || '';
+            expect(blockText).toContain(':tada:');
+            expect(blockText).toContain('Plan Completed');
+            expect(blockText).toContain('continues');
+        });
+    });
+});
+//# sourceMappingURL=slack.test.js.map

package/dist/lib/slack.test.js.map

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

package/dist/lib/templates/injections.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Injection markers and content for CLAUDE.md and AGENTS.md files
+ */
+export declare const INJECTION_MARKERS: {
+    readonly start: "<!-- vralphy:start -->";
+    readonly end: "<!-- vralphy:end -->";
+};
+/**
+ * Content to inject into CLAUDE.md files
+ * References the comprehensive README in .vralphy/
+ */
+export declare const CLAUDE_MD_INJECTION = "\n## vralphy Integration\n\nThis project uses vralphy for autonomous AI development. Key references:\n\n- **Full documentation**: @.vralphy/README.md\n- **Project context**: @.vralphy/AGENTS.md\n- **Current plan**: @IMPLEMENTATION_PLAN.md\n\nWhen working on vralphy tasks, check IMPLEMENTATION_PLAN.md for current progress.\n";
+/**
+ * Content to inject into root AGENTS.md files
+ * Minimal section pointing to vralphy documentation
+ */
+export declare const AGENTS_MD_INJECTION = "\n## vralphy\n\nThis project uses vralphy. See `.vralphy/README.md` for full documentation.\n";
+//# sourceMappingURL=injections.d.ts.map

package/dist/lib/templates/injections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injections.d.ts","sourceRoot":"","sources":["../../../src/lib/templates/injections.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mBAAmB,0UAU/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,kGAI/B,CAAC"}

package/dist/lib/templates/injections.js

@@ -0,0 +1,32 @@
+/**
+ * Injection markers and content for CLAUDE.md and AGENTS.md files
+ */
+export const INJECTION_MARKERS = {
+    start: '<!-- vralphy:start -->',
+    end: '<!-- vralphy:end -->',
+};
+/**
+ * Content to inject into CLAUDE.md files
+ * References the comprehensive README in .vralphy/
+ */
+export const CLAUDE_MD_INJECTION = `
+## vralphy Integration
+
+This project uses vralphy for autonomous AI development. Key references:
+
+- **Full documentation**: @.vralphy/README.md
+- **Project context**: @.vralphy/AGENTS.md
+- **Current plan**: @IMPLEMENTATION_PLAN.md
+
+When working on vralphy tasks, check IMPLEMENTATION_PLAN.md for current progress.
+`;
+/**
+ * Content to inject into root AGENTS.md files
+ * Minimal section pointing to vralphy documentation
+ */
+export const AGENTS_MD_INJECTION = `
+## vralphy
+
+This project uses vralphy. See \`.vralphy/README.md\` for full documentation.
+`;
+//# sourceMappingURL=injections.js.map

package/dist/lib/templates/injections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injections.js","sourceRoot":"","sources":["../../../src/lib/templates/injections.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE,wBAAwB;IAC/B,GAAG,EAAE,sBAAsB;CACnB,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;CAUlC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;CAIlC,CAAC"}

package/dist/lib/templates/readme.d.ts

@@ -0,0 +1,6 @@
+/**
+ * README template for .vralphy/README.md
+ * Comprehensive documentation for external AI coding agents
+ */
+export declare const README_TEMPLATE = "# vralphy - AI Agent Documentation\n\nThis project uses **vralphy**, a CLI tool implementing the Ralph Playbook methodology for autonomous AI development.\n\n## What is vralphy?\n\nvralphy wraps AI coding CLIs (Claude, OpenCode, Codex) with a loop-based execution model. It enables AI agents to autonomously plan, build, test, and commit code through structured iteration.\n\n## The Workflow Loop\n\n```\nUser specs \u2192 Plan phase \u2192 Build phase \u2192 Tests \u2192 Commit \u2192 Loop\n     \u2191                                              \u2502\n     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n1. **Specs** (`specs/*.md`): Define what to build\n2. **Plan** (`vralphy plan`): AI analyzes specs and creates IMPLEMENTATION_PLAN.md\n3. **Build** (`vralphy build`): AI executes tasks from the plan\n4. **Tests**: Validation runs after each iteration\n5. **Commit**: Changes are committed on successful validation\n6. **Loop**: Process repeats until plan is complete\n\n## Writing Specifications\n\nCreate `.md` files in `specs/` directory. Format:\n\n```markdown\n# Feature Name\n\n## Goal\nWhat this feature should accomplish.\n\n## Requirements\n- Requirement 1\n- Requirement 2\n\n## Constraints\n- Any technical limitations or preferences\n\n## Acceptance Criteria\n- [ ] Criterion 1\n- [ ] Criterion 2\n```\n\n### Good Spec Examples\n\n- Clear, atomic features\n- Measurable acceptance criteria\n- Specific constraints (not \"make it fast\")\n- References to existing code when relevant\n\n### Avoid\n\n- Vague requirements (\"improve the code\")\n- Multiple unrelated features in one spec\n- Implementation details (let AI decide how)\n\n## Key Commands\n\n| Command | Description |\n|---------|-------------|\n| `vralphy plan` | Analyze specs and create/update IMPLEMENTATION_PLAN.md |\n| `vralphy build` | Execute tasks from the implementation plan |\n| `vralphy spec <topic>` | Interactive specification creation |\n| `vralphy init` | Initialize vralphy in a project |\n| `vralphy cleanup` | Remove vralphy artifacts |\n| `vralphy engines` | List available AI engines |\n\n### Common Options\n\n```bash\n--engine <name>           # claude | opencode | codex\n--planning-model <model>  # Model for planning (default: opus)\n--executor-model <model>  # Model for execution (default: sonnet)\n--verbose                 # Detailed output\n--dry-run                 # Preview without executing\n```\n\n## Loop Mechanics\n\n### Iteration Flow\n\nEach `vralphy build` iteration:\n1. Reads IMPLEMENTATION_PLAN.md\n2. Identifies next unchecked task (`- [ ]`)\n3. Executes task using AI engine\n4. Runs validation (typecheck, tests, lint)\n5. On success: marks task complete (`- [x]`), commits\n6. Continues to next task\n\n### Context Window Management\n\n- Each iteration starts fresh\n- The AI reads relevant files on demand\n- AGENTS.md provides persistent project context\n- IMPLEMENTATION_PLAN.md tracks progress\n\n### Plan Completion\n\nWhen all tasks are `- [x]`:\n- Build mode exits successfully\n- Slack notification sent (if configured)\n- Ready for next spec or manual review\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `specs/*.md` | Feature specifications (input) |\n| `IMPLEMENTATION_PLAN.md` | Task list with checkboxes (state) |\n| `.vralphy/AGENTS.md` | Project context for AI agents |\n| `.vralphy/prompts/*.md` | Customizable prompts |\n| `.vralphy/logs/events.jsonl` | Event log (auto-rotates at 5MB) |\n| `.vralphy/config.json` | Project-specific configuration |\n\n## Event Logging\n\nEvents are logged to `.vralphy/logs/events.jsonl`:\n\n```json\n{\"timestamp\":\"...\",\"event\":\"build:start\",\"data\":{...}}\n{\"timestamp\":\"...\",\"event\":\"task:complete\",\"data\":{...}}\n{\"timestamp\":\"...\",\"event\":\"build:complete\",\"data\":{...}}\n```\n\nLog files auto-rotate at 5MB to prevent unbounded growth.\n\n## Model System\n\nvralphy uses a two-tier model approach:\n\n- **Planning model** (opus): Complex reasoning, orchestration, plan creation\n- **Executor model** (sonnet): Fast parallel task execution\n\n## Configuration\n\nPriority order:\n1. CLI flags (`--engine`, `--planning-model`)\n2. Environment (`VRALPHY_ENGINE`, `VRALPHY_PLANNING_MODEL`)\n3. Project config (`.vralphy/config.json`)\n4. Global config (`~/.config/vralphy/config.json`)\n5. Built-in defaults\n\n### Example Config\n\n```json\n{\n  \"engine\": \"claude\",\n  \"planningModel\": \"opus\",\n  \"executorModel\": \"sonnet\",\n  \"slackWebhook\": \"https://hooks.slack.com/...\"\n}\n```\n\n## Tips for AI Agents\n\n1. **Read IMPLEMENTATION_PLAN.md first** - understand current progress\n2. **Check .vralphy/AGENTS.md** - project-specific conventions\n3. **Run validation commands** - typecheck, test, lint before committing\n4. **Atomic commits** - one task = one commit\n5. **Update plan on completion** - mark tasks `- [x]` when done\n";
+//# sourceMappingURL=readme.d.ts.map

package/dist/lib/templates/readme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.d.ts","sourceRoot":"","sources":["../../../src/lib/templates/readme.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,eAAe,0gKAkK3B,CAAC"}

package/dist/lib/templates/readme.js

@@ -0,0 +1,168 @@
+/**
+ * README template for .vralphy/README.md
+ * Comprehensive documentation for external AI coding agents
+ */
+export const README_TEMPLATE = `# vralphy - AI Agent Documentation
+
+This project uses **vralphy**, a CLI tool implementing the Ralph Playbook methodology for autonomous AI development.
+
+## What is vralphy?
+
+vralphy wraps AI coding CLIs (Claude, OpenCode, Codex) with a loop-based execution model. It enables AI agents to autonomously plan, build, test, and commit code through structured iteration.
+
+## The Workflow Loop
+
+\`\`\`
+User specs → Plan phase → Build phase → Tests → Commit → Loop
+     ↑                                              │
+     └──────────────────────────────────────────────┘
+\`\`\`
+
+1. **Specs** (\`specs/*.md\`): Define what to build
+2. **Plan** (\`vralphy plan\`): AI analyzes specs and creates IMPLEMENTATION_PLAN.md
+3. **Build** (\`vralphy build\`): AI executes tasks from the plan
+4. **Tests**: Validation runs after each iteration
+5. **Commit**: Changes are committed on successful validation
+6. **Loop**: Process repeats until plan is complete
+
+## Writing Specifications
+
+Create \`.md\` files in \`specs/\` directory. Format:
+
+\`\`\`markdown
+# Feature Name
+
+## Goal
+What this feature should accomplish.
+
+## Requirements
+- Requirement 1
+- Requirement 2
+
+## Constraints
+- Any technical limitations or preferences
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+\`\`\`
+
+### Good Spec Examples
+
+- Clear, atomic features
+- Measurable acceptance criteria
+- Specific constraints (not "make it fast")
+- References to existing code when relevant
+
+### Avoid
+
+- Vague requirements ("improve the code")
+- Multiple unrelated features in one spec
+- Implementation details (let AI decide how)
+
+## Key Commands
+
+| Command | Description |
+|---------|-------------|
+| \`vralphy plan\` | Analyze specs and create/update IMPLEMENTATION_PLAN.md |
+| \`vralphy build\` | Execute tasks from the implementation plan |
+| \`vralphy spec <topic>\` | Interactive specification creation |
+| \`vralphy init\` | Initialize vralphy in a project |
+| \`vralphy cleanup\` | Remove vralphy artifacts |
+| \`vralphy engines\` | List available AI engines |
+
+### Common Options
+
+\`\`\`bash
+--engine <name>           # claude | opencode | codex
+--planning-model <model>  # Model for planning (default: opus)
+--executor-model <model>  # Model for execution (default: sonnet)
+--verbose                 # Detailed output
+--dry-run                 # Preview without executing
+\`\`\`
+
+## Loop Mechanics
+
+### Iteration Flow
+
+Each \`vralphy build\` iteration:
+1. Reads IMPLEMENTATION_PLAN.md
+2. Identifies next unchecked task (\`- [ ]\`)
+3. Executes task using AI engine
+4. Runs validation (typecheck, tests, lint)
+5. On success: marks task complete (\`- [x]\`), commits
+6. Continues to next task
+
+### Context Window Management
+
+- Each iteration starts fresh
+- The AI reads relevant files on demand
+- AGENTS.md provides persistent project context
+- IMPLEMENTATION_PLAN.md tracks progress
+
+### Plan Completion
+
+When all tasks are \`- [x]\`:
+- Build mode exits successfully
+- Slack notification sent (if configured)
+- Ready for next spec or manual review
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| \`specs/*.md\` | Feature specifications (input) |
+| \`IMPLEMENTATION_PLAN.md\` | Task list with checkboxes (state) |
+| \`.vralphy/AGENTS.md\` | Project context for AI agents |
+| \`.vralphy/prompts/*.md\` | Customizable prompts |
+| \`.vralphy/logs/events.jsonl\` | Event log (auto-rotates at 5MB) |
+| \`.vralphy/config.json\` | Project-specific configuration |
+
+## Event Logging
+
+Events are logged to \`.vralphy/logs/events.jsonl\`:
+
+\`\`\`json
+{"timestamp":"...","event":"build:start","data":{...}}
+{"timestamp":"...","event":"task:complete","data":{...}}
+{"timestamp":"...","event":"build:complete","data":{...}}
+\`\`\`
+
+Log files auto-rotate at 5MB to prevent unbounded growth.
+
+## Model System
+
+vralphy uses a two-tier model approach:
+
+- **Planning model** (opus): Complex reasoning, orchestration, plan creation
+- **Executor model** (sonnet): Fast parallel task execution
+
+## Configuration
+
+Priority order:
+1. CLI flags (\`--engine\`, \`--planning-model\`)
+2. Environment (\`VRALPHY_ENGINE\`, \`VRALPHY_PLANNING_MODEL\`)
+3. Project config (\`.vralphy/config.json\`)
+4. Global config (\`~/.config/vralphy/config.json\`)
+5. Built-in defaults
+
+### Example Config
+
+\`\`\`json
+{
+  "engine": "claude",
+  "planningModel": "opus",
+  "executorModel": "sonnet",
+  "slackWebhook": "https://hooks.slack.com/..."
+}
+\`\`\`
+
+## Tips for AI Agents
+
+1. **Read IMPLEMENTATION_PLAN.md first** - understand current progress
+2. **Check .vralphy/AGENTS.md** - project-specific conventions
+3. **Run validation commands** - typecheck, test, lint before committing
+4. **Atomic commits** - one task = one commit
+5. **Update plan on completion** - mark tasks \`- [x]\` when done
+`;
+//# sourceMappingURL=readme.js.map