ralphy-spec 0.1.0 → 0.2.0

package/dist/core/workspace/patch-mode.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatchModeWorkspace = void 0;
+exports.getPatchWorkspaceRoot = getPatchWorkspaceRoot;
+const execa_1 = require("execa");
+const node_path_1 = __importDefault(require("node:path"));
+const file_contract_1 = require("../spec/file-contract");
+class PatchModeWorkspace {
+    repoRoot;
+    mode = "patch";
+    stateByTask = new Map();
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+    }
+    async prepare(taskId) {
+        const snapshotCommit = await this.git(["rev-parse", "HEAD"]);
+        this.stateByTask.set(taskId, { snapshotCommit });
+        return { taskId, workingDir: this.repoRoot };
+    }
+    getWorkingDir(_taskId) {
+        return this.repoRoot;
+    }
+    async getChangedFiles(_taskId) {
+        // name-status gives: A/M/D/R... <path> ...
+        const out = await this.git(["diff", "--name-status"]);
+        const lines = out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        const changed = [];
+        for (const line of lines) {
+            const parts = line.split(/\s+/);
+            const status = parts[0] ?? "";
+            const file = parts[1] ?? "";
+            if (!file)
+                continue;
+            changed.push({ file, isNew: status.startsWith("A") });
+        }
+        return changed;
+    }
+    async enforceContract(taskId, contract) {
+        const changedFiles = await this.getChangedFiles(taskId);
+        const violations = (0, file_contract_1.evaluateFileContract)({ changedFiles, contract });
+        if (violations.length) {
+            await this.revert(taskId);
+        }
+        return violations;
+    }
+    async checkpoint(taskId, message) {
+        // Best effort: commit all changes. If nothing to commit, return HEAD.
+        await this.git(["add", "-A"]);
+        const commitMsg = `[ralphy-spec] ${taskId}: ${message}`;
+        try {
+            await this.git(["commit", "-m", commitMsg]);
+        }
+        catch {
+            // likely "nothing to commit"
+        }
+        const ref = await this.git(["rev-parse", "HEAD"]);
+        return { ref };
+    }
+    async merge(_taskId) {
+        // Patch mode executes on main; merge is no-op.
+    }
+    async revert(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        // Hard revert to snapshot; also remove untracked files.
+        await this.git(["reset", "--hard", state.snapshotCommit]);
+        await this.git(["clean", "-fd"]);
+    }
+    async cleanup(_taskId) {
+        // No-op for patch mode.
+    }
+    async git(args) {
+        const res = await (0, execa_1.execa)("git", args, {
+            cwd: this.repoRoot,
+            stdio: "pipe",
+        });
+        return res.stdout.trim();
+    }
+}
+exports.PatchModeWorkspace = PatchModeWorkspace;
+function getPatchWorkspaceRoot(repoRoot) {
+    return node_path_1.default.resolve(repoRoot);
+}
+//# sourceMappingURL=patch-mode.js.map

package/dist/core/workspace/patch-mode.js.map

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

package/dist/core/workspace/worktree-mode.d.ts

@@ -0,0 +1,28 @@
+import type { FileContract } from "../spec/types";
+import type { CheckpointRef, ContractViolation, WorkspaceContext, WorkspaceManager } from "./manager";
+/**
+ * WorktreeModeWorkspace uses git worktrees for task isolation.
+ *
+ * Each task runs in its own worktree branch, providing complete isolation
+ * from the main working directory. Changes are merged back on success.
+ */
+export declare class WorktreeModeWorkspace implements WorkspaceManager {
+    private readonly repoRoot;
+    mode: "worktree";
+    private readonly stateByTask;
+    private readonly worktreeBase;
+    constructor(repoRoot: string);
+    prepare(taskId: string): Promise<WorkspaceContext>;
+    getWorkingDir(taskId: string): string;
+    getChangedFiles(taskId: string): Promise<Array<{
+        file: string;
+        isNew: boolean;
+    }>>;
+    enforceContract(taskId: string, contract: FileContract): Promise<ContractViolation[]>;
+    checkpoint(taskId: string, message: string): Promise<CheckpointRef>;
+    merge(taskId: string): Promise<void>;
+    revert(taskId: string): Promise<void>;
+    cleanup(taskId: string): Promise<void>;
+    private git;
+}
+//# sourceMappingURL=worktree-mode.d.ts.map

package/dist/core/workspace/worktree-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-mode.d.ts","sourceRoot":"","sources":["../../../src/core/workspace/worktree-mode.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,WAAW,CAAC;AAQnB;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAKhD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,IAAI,EAAE,UAAU,CAAc;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAET,QAAQ,EAAE,MAAM;IAIvC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoCxD,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK/B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IA2BjF,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYrF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBnE,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBpC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASrC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAiB9B,GAAG;CAalB"}

package/dist/core/workspace/worktree-mode.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorktreeModeWorkspace = void 0;
+const execa_1 = require("execa");
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const file_contract_1 = require("../spec/file-contract");
+/**
+ * WorktreeModeWorkspace uses git worktrees for task isolation.
+ *
+ * Each task runs in its own worktree branch, providing complete isolation
+ * from the main working directory. Changes are merged back on success.
+ */
+class WorktreeModeWorkspace {
+    repoRoot;
+    mode = "worktree";
+    stateByTask = new Map();
+    worktreeBase;
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+        this.worktreeBase = node_path_1.default.join(repoRoot, ".ralphy", "worktrees");
+    }
+    async prepare(taskId) {
+        // Ensure worktree base directory exists
+        await promises_1.default.mkdir(this.worktreeBase, { recursive: true });
+        // Get current HEAD as base
+        const baseCommit = await this.git(["rev-parse", "HEAD"], this.repoRoot);
+        // Create a unique branch name for this task
+        const branchName = `ralphy/${taskId}/${Date.now()}`;
+        const worktreePath = node_path_1.default.join(this.worktreeBase, taskId.replace(/[^a-zA-Z0-9-_]/g, "_"));
+        // Clean up existing worktree if present
+        try {
+            await promises_1.default.rm(worktreePath, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore if doesn't exist
+        }
+        // Remove stale worktree entry if any
+        try {
+            await this.git(["worktree", "remove", "--force", worktreePath], this.repoRoot);
+        }
+        catch {
+            // Ignore if doesn't exist
+        }
+        // Create new worktree with a new branch
+        await this.git(["worktree", "add", "-b", branchName, worktreePath, baseCommit], this.repoRoot);
+        this.stateByTask.set(taskId, { worktreePath, branchName, baseCommit });
+        return { taskId, workingDir: worktreePath };
+    }
+    getWorkingDir(taskId) {
+        const state = this.stateByTask.get(taskId);
+        return state?.worktreePath ?? this.repoRoot;
+    }
+    async getChangedFiles(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return [];
+        // Get changes compared to base commit
+        const out = await this.git(["diff", "--name-status", state.baseCommit], state.worktreePath);
+        const lines = out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        const changed = [];
+        for (const line of lines) {
+            const parts = line.split(/\s+/);
+            const status = parts[0] ?? "";
+            const file = parts[1] ?? "";
+            if (!file)
+                continue;
+            changed.push({ file, isNew: status.startsWith("A") });
+        }
+        return changed;
+    }
+    async enforceContract(taskId, contract) {
+        const changedFiles = await this.getChangedFiles(taskId);
+        const violations = (0, file_contract_1.evaluateFileContract)({ changedFiles, contract });
+        if (violations.length) {
+            // Revert the worktree to base state
+            await this.revert(taskId);
+        }
+        return violations;
+    }
+    async checkpoint(taskId, message) {
+        const state = this.stateByTask.get(taskId);
+        if (!state) {
+            throw new Error(`No worktree state for task ${taskId}`);
+        }
+        // Stage and commit all changes in worktree
+        await this.git(["add", "-A"], state.worktreePath);
+        const commitMsg = `[ralphy-spec] ${taskId}: ${message}`;
+        try {
+            await this.git(["commit", "-m", commitMsg], state.worktreePath);
+        }
+        catch {
+            // Likely nothing to commit
+        }
+        const ref = await this.git(["rev-parse", "HEAD"], state.worktreePath);
+        return { ref };
+    }
+    async merge(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        // Get the current branch in main repo
+        const currentBranch = await this.git(["rev-parse", "--abbrev-ref", "HEAD"], this.repoRoot);
+        // Merge the task branch back using --squash for clean history
+        try {
+            await this.git(["merge", "--squash", state.branchName], this.repoRoot);
+            await this.git(["commit", "-m", `[ralphy-spec] Merge task ${taskId}`], this.repoRoot);
+        }
+        catch (err) {
+            // If merge fails, user may need to resolve manually
+            throw new Error(`Failed to merge task ${taskId}: ${err?.message ?? String(err)}. Manual resolution may be required.`);
+        }
+    }
+    async revert(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        // Hard reset worktree to base commit
+        await this.git(["reset", "--hard", state.baseCommit], state.worktreePath);
+        await this.git(["clean", "-fd"], state.worktreePath);
+    }
+    async cleanup(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        try {
+            // Remove the worktree
+            await this.git(["worktree", "remove", "--force", state.worktreePath], this.repoRoot);
+            // Delete the branch
+            await this.git(["branch", "-D", state.branchName], this.repoRoot);
+        }
+        catch {
+            // Best effort cleanup
+        }
+        this.stateByTask.delete(taskId);
+    }
+    async git(args, cwd) {
+        const res = await (0, execa_1.execa)("git", args, {
+            cwd,
+            stdio: "pipe",
+            reject: false,
+        });
+        if (res.exitCode !== 0 && res.stderr) {
+            throw new Error(`git ${args.join(" ")} failed: ${res.stderr}`);
+        }
+        return res.stdout.trim();
+    }
+}
+exports.WorktreeModeWorkspace = WorktreeModeWorkspace;
+//# sourceMappingURL=worktree-mode.js.map

package/dist/core/workspace/worktree-mode.js.map

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

package/dist/index.js

@@ -1,18 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const init_1 = require("./commands/init");
-const validate_1 = require("./commands/validate");
-const update_1 = require("./commands/update");
+const init_1 = require("./cli/init");
+const validate_1 = require("./cli/validate");
+const update_1 = require("./cli/update");
+const run_1 = require("./cli/run");
+const status_1 = require("./cli/status");
+const report_1 = require("./cli/report");
+const tail_1 = require("./cli/tail");
+const checkpoint_1 = require("./cli/checkpoint");
 function buildProgram() {
     const program = new commander_1.Command();
     program
         .name("ralphy-spec")
         .description("One-command setup for Ralph loop + OpenSpec workflows across Cursor, OpenCode, and Claude Code.")
-        .version("0.1.0");
+        .version("0.1.2");
     (0, init_1.registerInitCommand)(program);
     (0, validate_1.registerValidateCommand)(program);
     (0, update_1.registerUpdateCommand)(program);
+    (0, run_1.registerRunCommand)(program);
+    (0, status_1.registerStatusCommand)(program);
+    (0, report_1.registerReportCommand)(program);
+    (0, tail_1.registerTailCommand)(program);
+    (0, checkpoint_1.registerCheckpointCommand)(program);
     return program;
 }
 async function main() {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAAA,yCAAoC;AACpC,0CAAsD;AACtD,kDAA8D;AAC9D,8CAA0D;AAE1D,SAAS,YAAY;IACnB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,aAAa,CAAC;SACnB,WAAW,CACV,iGAAiG,CAClG;SACA,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,mEAAmE;AACnE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAAA,yCAAoC;AACpC,qCAAiD;AACjD,6CAAyD;AACzD,yCAAqD;AACrD,mCAA+C;AAC/C,yCAAqD;AACrD,yCAAqD;AACrD,qCAAiD;AACjD,iDAA6D;AAE7D,SAAS,YAAY;IACnB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,aAAa,CAAC;SACnB,WAAW,CACV,iGAAiG,CAClG;SACA,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,wBAAkB,EAAC,OAAO,CAAC,CAAC;IAC5B,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,sCAAyB,EAAC,OAAO,CAAC,CAAC;IAEnC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,mEAAmE;AACnE,IAAI,EAAE,CAAC"}

package/dist/templates/claude-code/ralphy-archive.md

@@ -0,0 +1,22 @@
+# /ralphy:archive (Archive completed change)
+
+You are archiving a completed OpenSpec change.
+
+## Preconditions
+- All tasks are complete
+- Tests are green
+- Spec deltas reflect final behavior
+
+## Steps
+1. Run tests to confirm green.
+2. If OpenSpec CLI is available, archive via:
+   - `openspec archive <change-name> --yes`
+3. Otherwise, move the change folder from:
+   - `openspec/changes/<change-name>/`
+   to:
+   - `openspec/archive/<change-name>/`
+4. Confirm `openspec/specs/` is updated appropriately.
+
+## Output
+Provide a short summary and a test plan.
+

package/dist/templates/claude-code/ralphy-implement.md

@@ -0,0 +1,30 @@
+# /ralphy:implement (Implement OpenSpec tasks)
+
+You are implementing an OpenSpec change located under `openspec/changes/<change-name>/`.
+
+## Goal
+Complete all tasks in `tasks.md` and satisfy the acceptance criteria from the spec scenarios.
+
+## Ralph loop compatibility
+If this command is being executed in an iterative loop:
+- Make progress each iteration
+- Run tests frequently
+- Only declare success when verification passes
+
+## Steps
+1. Identify the active change folder under `openspec/changes/`.
+2. Read the change artifacts:
+   - `proposal.md`
+   - `tasks.md`
+   - spec deltas under `specs/`
+3. Implement tasks in order:
+   - Update code
+   - Add/update tests
+   - Run tests
+   - Mark tasks complete ONLY when verified
+
+## Completion promise
+Only output this exact text when ALL tasks are complete and tests pass:
+
+<promise>TASK_COMPLETE</promise>
+

package/dist/templates/claude-code/ralphy-plan.md

@@ -0,0 +1,31 @@
+# /ralphy:plan (PRD -> OpenSpec change)
+
+You are an AI coding assistant. Convert the user's PRD/requirements into an OpenSpec change proposal with clear, testable acceptance criteria.
+
+## Deliverables (create/modify files)
+Create a new change folder:
+- `openspec/changes/<change-name>/proposal.md`
+- `openspec/changes/<change-name>/tasks.md`
+- `openspec/changes/<change-name>/specs/<domain>/spec.md` (and others as needed)
+
+## Rules
+- Use MUST/SHALL language for requirements.
+- Every `### Requirement:` MUST include at least one `#### Scenario:`.
+- Include acceptance criteria that can be validated by tests or deterministic commands.
+- Keep scope explicit; list non-goals.
+
+## Procedure
+1. Read `openspec/project.md` and relevant specs under `openspec/specs/`.
+2. Propose a kebab-case change name (e.g. `add-profile-filters`).
+3. Create `proposal.md` explaining why/what and the constraints.
+4. Write spec deltas under `specs/` using:
+   - `## ADDED Requirements`
+   - `## MODIFIED Requirements`
+   - `## REMOVED Requirements`
+5. Write `tasks.md` as a numbered checklist. Each task includes:
+   - Implementation notes
+   - Test plan (what to run, what to assert)
+
+## Output
+Summarize created files and tell the user what to run next (typically implementation).
+

package/dist/templates/claude-code/ralphy-validate.md

@@ -0,0 +1,21 @@
+# /ralphy:validate (Validate against acceptance criteria)
+
+You are validating an OpenSpec change.
+
+## Goal
+Prove that the implementation matches the requirements/scenarios and that tests pass.
+
+## Steps
+1. Identify the active change folder under `openspec/changes/`.
+2. Extract acceptance criteria from:
+   - spec scenarios in `openspec/changes/<change-name>/specs/**`
+   - test plan notes in `tasks.md`
+3. Run tests and/or deterministic verification commands.
+4. If failures occur, fix them and re-run until green.
+
+## Output
+Report:
+- What passed
+- What failed (with next actions)
+- Any missing tests needed to satisfy acceptance criteria
+

package/dist/templates/cursor/ralphy-archive.md

@@ -0,0 +1,20 @@
+# /ralphy:archive (Archive completed change)
+
+You are an AI coding assistant archiving a completed OpenSpec change.
+
+## Preconditions
+- All tasks in `openspec/changes/<change-name>/tasks.md` are complete
+- Tests pass
+- Spec deltas are correct and reflect the final behavior
+
+## Steps
+1. Run validation (tests) and ensure green.
+2. Archive the change by moving it into `openspec/archive/` (or using the OpenSpec CLI if available).
+   - If OpenSpec CLI is installed, prefer:
+     - `openspec archive <change-name> --yes`
+3. Confirm the source-of-truth specs in `openspec/specs/` are updated appropriately.
+4. Provide a short release-style summary:
+   - What changed
+   - How to test
+   - Any follow-up work
+

package/dist/templates/cursor/ralphy-implement.md

@@ -0,0 +1,31 @@
+# /ralphy:implement (Implement OpenSpec tasks)
+
+You are an AI coding assistant implementing an existing OpenSpec change.
+
+## Goal
+Implement tasks from `openspec/changes/<change-name>/tasks.md` until acceptance criteria are met and tests pass.
+
+## Operating mode (Ralph loop compatible)
+If you are being run in an iterative loop, you may see the same prompt repeatedly. You MUST:
+- Use test failures as feedback
+- Keep making progress on the next incomplete task
+- Only claim completion when verification passes
+
+## Steps
+1. Identify the active change folder under `openspec/changes/` (ask the user if multiple exist).
+2. Read:
+   - `openspec/changes/<change-name>/proposal.md`
+   - `openspec/changes/<change-name>/tasks.md`
+   - Relevant spec deltas in `openspec/changes/<change-name>/specs/`
+   - Current specs in `openspec/specs/` as the baseline
+3. Implement tasks in order. For each task:
+   - Make the smallest correct change
+   - Update or add tests required by acceptance criteria
+   - Run tests and fix failures
+   - Mark the task as complete in `tasks.md` ONLY when verified
+
+## Completion promise (for Ralph loop runners)
+Only output this exact text when ALL tasks are complete AND tests pass:
+
+<promise>TASK_COMPLETE</promise>
+

package/dist/templates/cursor/ralphy-plan.md

@@ -0,0 +1,39 @@
+# /ralphy:plan (PRD -> OpenSpec change)
+
+You are an AI coding assistant. Your job is to convert user requirements into an OpenSpec change proposal with clear acceptance criteria.
+
+## Goal
+Create a new OpenSpec change folder under `openspec/changes/<change-name>/` containing:
+- `proposal.md`
+- `tasks.md`
+- `specs/<domain>/spec.md` (or multiple specs if needed)
+
+## Inputs
+- A PRD, feature request, or requirements description from the user.
+- Existing specs in `openspec/specs/` (source of truth).
+
+## Requirements
+- Use MUST/SHALL language in requirements.
+- Every requirement MUST have at least one `#### Scenario:` block.
+- Add acceptance criteria that can be validated via tests/commands.
+- Keep changes scoped and explicitly list what is out-of-scope.
+
+## Steps
+1. Read `openspec/project.md` and any relevant specs in `openspec/specs/`.
+2. Propose a short, kebab-case `<change-name>` (e.g. `add-profile-filters`).
+3. Create `openspec/changes/<change-name>/proposal.md` describing:
+   - Summary
+   - Motivation
+   - Scope / Non-goals
+   - Risks
+4. Create `openspec/changes/<change-name>/specs/...` as spec deltas:
+   - `## ADDED Requirements`
+   - `## MODIFIED Requirements`
+   - `## REMOVED Requirements`
+5. Create `openspec/changes/<change-name>/tasks.md`:
+   - Break into numbered tasks with checkboxes
+   - Each task includes test plan notes (what to run, what to assert)
+
+## Output
+When the OpenSpec change artifacts are created and consistent, summarize what you created and what the next command should be.
+

package/dist/templates/cursor/ralphy-validate.md

@@ -0,0 +1,24 @@
+# /ralphy:validate (Validate against acceptance criteria)
+
+You are an AI coding assistant validating an OpenSpec change against its acceptance criteria.
+
+## Goal
+Confirm the implementation satisfies the requirements/scenarios in:
+- `openspec/changes/<change-name>/specs/**`
+and that all tests pass.
+
+## Steps
+1. Identify the active change folder under `openspec/changes/`.
+2. Extract acceptance criteria from the spec scenarios and `tasks.md` test plan notes.
+3. Run the project test command (prefer package scripts), for example:
+   - `npm test`
+   - `pnpm test`
+   - `bun test`
+4. If tests fail:
+   - Diagnose the failure
+   - Fix code/tests
+   - Re-run tests
+5. Report results:
+   - Which requirements are proven (by which tests/commands)
+   - Any gaps (missing tests or unclear acceptance criteria)
+

package/dist/templates/opencode/AGENTS.md

@@ -0,0 +1,46 @@
+# Ralphy-OpenSpec Agent Instructions (OpenCode)
+
+You are an AI coding assistant operating in a repository that uses:
+- **OpenSpec** for spec-driven development (`openspec/specs/` + `openspec/changes/`)
+- **Ralph loop** for iterative execution (the same prompt may be repeated)
+
+## Golden rules
+- Treat `openspec/specs/` as the source of truth (current behavior).
+- Treat `openspec/changes/<change-name>/` as the proposed/active change.
+- Only mark tasks complete when verification (tests) passes.
+- Keep changes small, deterministic, and test-backed.
+
+## Workflow
+
+### 1) Plan (PRD -> OpenSpec)
+When asked to plan or create specs:
+1. Read `openspec/project.md` and relevant files in `openspec/specs/`.
+2. Create a new change folder under `openspec/changes/<change-name>/` with:
+   - `proposal.md` (why/what/scope/non-goals/risks)
+   - `tasks.md` (checklist with test plan notes)
+   - `specs/**/spec.md` (deltas: ADDED/MODIFIED/REMOVED)
+3. Ensure requirements use MUST/SHALL and each requirement has at least one scenario.
+
+### 2) Implement (Tasks -> Code)
+When asked to implement:
+1. Identify the active change folder under `openspec/changes/`.
+2. Implement tasks in order from `tasks.md`.
+3. Run tests frequently and fix failures.
+4. Update the checkbox status in `tasks.md` only when verified.
+
+### 3) Validate (Acceptance criteria)
+When asked to validate:
+1. Map scenarios/acceptance criteria to tests/commands.
+2. Run the project test command (commonly `npm test`).
+3. Report which requirements are proven and what gaps remain.
+
+### 4) Archive
+When asked to archive:
+- Prefer `openspec archive <change-name> --yes` if OpenSpec CLI is available.
+- Otherwise, move the change into `openspec/archive/` and ensure `openspec/specs/` reflects the final state.
+
+## Ralph loop completion promise
+If you are being run in a loop, only output this exact text when ALL tasks are complete and tests are green:
+
+<promise>TASK_COMPLETE</promise>
+

package/dist/templates/shared/openspec-tasks-template.md

@@ -0,0 +1,48 @@
+# OpenSpec Tasks Template
+
+Use this structure for `openspec/changes/<change-name>/tasks.md`.
+
+## 1. Planning / Scaffolding
+- [ ] 1.1 Confirm scope, non-goals, and impacted modules
+  - Acceptance criteria:
+    - GIVEN the current `openspec/specs/` baseline
+    - WHEN this change is implemented
+    - THEN only the intended domains are affected
+  - Test plan: N/A
+
+## 2. Implementation
+- [ ] 2.1 Implement feature behavior (spec-driven)
+  - Acceptance criteria:
+    - GIVEN ...
+    - WHEN ...
+    - THEN ...
+  - Test plan:
+    - Run: `npm test`
+    - Assert: ...
+
+## 3. Validators / Budgets (v2+)
+- [ ] 3.1 Define or update validators used by this change
+  - Notes:
+    - Validators are the ground truth (deterministic pass/fail)
+    - Prefer: `npm run typecheck`, `npm test`, `npm run lint`
+  - Test plan:
+    - Run the validator commands locally/CI
+
+- [ ] 3.2 If the change introduces budgeted execution (v2.1+), document expected behavior
+  - Notes:
+    - Optimal → Warning → Hard tier expectations
+    - WARNING tier should shrink context + enforce repair-only constraints
+    - HARD tier should stop safely (no silent retries)
+  - Test plan:
+    - Run a small demo task that crosses WARNING tier and confirm behaviors
+
+## 3. Validation
+- [ ] 3.1 Add/adjust tests to cover all scenarios
+  - Test plan:
+    - Run: `npm test`
+
+## 4. Documentation / Archive
+- [ ] 4.1 Update OpenSpec docs/spec deltas (if needed) and archive change
+  - Test plan:
+    - Run: `npm test`
+