@0xtiby/toby 0.0.1

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@0xtiby/toby",
+  "version": "0.0.1",
+  "description": "AI-assisted development loop engine CLI",
+  "type": "module",
+  "bin": {
+    "toby": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "prompts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "bootstrap": "bash scripts/bootstrap.sh",
+    "setup:branch-protection": "bash scripts/setup-branch-protection.sh"
+  },
+  "dependencies": {
+    "@0xtiby/spawner": "latest",
+    "ink": "^5.0.1",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "meow": "^13.2.0",
+    "react": "^18.3.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@semantic-release/github": "^12.0.2",
+    "@types/react": "^18.3.1",
+    "ink-testing-library": "^4.0.0",
+    "semantic-release": "^25.0.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}

package/prompts/PROMPT_BUILD.md

@@ -0,0 +1,94 @@
+# Build Mode
+
+You are in BUILD mode. Implement one task from the spec, validate, and commit.
+
+**Spec:** `{{SPECS_DIR}}/{{SPEC_NAME}}.md`
+**Iteration:** {{ITERATION}}
+**Session:** {{SESSION}}
+**Progress:** spec {{SPEC_INDEX}} of {{SPEC_COUNT}}
+**All specs:** {{SPECS}}
+
+---
+
+## Path Discovery Rules (CRITICAL)
+
+**NEVER guess or invent file paths.** Always verify paths exist before referencing them.
+
+Before editing ANY file:
+1. Use Glob to find files matching a pattern
+2. Use Grep to search for specific code
+3. Verify the file exists before editing it
+
+For new files: verify the parent directory exists first.
+
+---
+
+## Phase 1: Find Ready Task
+
+Read the spec file at `{{SPECS_DIR}}/{{SPEC_NAME}}.md` and find the first task where:
+- `status` is `"pending"`
+- All tasks listed in `dependencies` have `status: "done"`
+
+If no ready task exists:
+1. Check if all tasks are `"done"` → output `:::TOBY_DONE:::`
+2. Check if tasks are `"blocked"` → report blockers and output `:::TOBY_DONE:::`
+3. Otherwise → output `:::TOBY_DONE:::`
+
+## Phase 2: Implement Task
+
+1. Read the task's description, acceptance criteria, and files list
+2. Before making changes, search the codebase to:
+   - Verify functionality doesn't already exist
+   - Understand existing patterns
+   - Identify the actual files to modify
+3. Implement the task following the acceptance criteria
+4. Build small, validate early — tracer bullet mindset
+
+## Phase 3: Validate
+
+Run project validation commands. Common patterns:
+- Build: check the project compiles
+- Type check: verify no type errors
+- Lint: ensure code style
+- Test: run relevant tests
+
+If validation fails:
+1. First attempt: targeted fix based on error
+2. Second attempt: alternative approach
+3. Third attempt: revert changes, mark task as `"blocked"` in spec, and exit
+
+## Phase 4: Commit
+
+When validation passes:
+
+1. Stage and commit changes:
+   ```bash
+   git add -A
+   git commit -m "$(cat <<'EOF'
+   feat({{SPEC_NAME}}): [task title]
+
+   Progress: [what was completed]
+   Next: [remaining tasks, or "none" if last]
+   EOF
+   )"
+   ```
+
+2. Update the spec: set the completed task's status to `"done"`
+
+3. Push:
+   ```bash
+   git push -u origin HEAD
+   ```
+
+**STOP HERE.** Do not pick up another task. The loop engine handles continuation.
+Do NOT output `:::TOBY_DONE:::` after completing a task — just stop.
+
+---
+
+## Guardrails
+
+1. **Single task** — implement ONE task, then STOP
+2. **Validate before commit** — never commit failing code
+3. **Update spec** — mark task as done after committing
+4. **Verify paths** — use Glob/Grep before editing files
+5. **Tracer bullet** — build small, test immediately

package/prompts/PROMPT_PLAN.md

@@ -0,0 +1,124 @@
+# Planning Mode: Spec → PRD
+
+You are in PLANNING mode. Translate a spec into a structured PRD (Product Requirements Document) with actionable tasks.
+
+**Spec:** `{{SPECS_DIR}}/{{SPEC_NAME}}.md`
+**PRD output:** `{{PRD_PATH}}`
+**Iteration:** {{ITERATION}}
+
+---
+
+## Path Discovery Rules (CRITICAL)
+
+**NEVER guess or invent file paths.** Always verify paths exist before referencing them.
+
+Before referencing ANY file path:
+1. Use Glob to find files matching a pattern
+2. Use Grep to search for specific code
+3. Verify the file exists before adding it to a task's files list
+
+For new files (create): verify the parent directory exists first.
+
+---
+
+## If PRD exists: Refinement Mode
+
+If `{{PRD_PATH}}` already exists, read it and refine:
+- Check all spec requirements have corresponding tasks
+- Verify file paths are accurate (re-run Glob/Grep)
+- Split tasks that are too large (~2 min per task)
+- Add missing dependencies
+- Improve acceptance criteria specificity
+- If no improvements needed, output: :::TOBY_DONE:::
+
+## If PRD does not exist: Creation Mode
+
+### Step 1: Read & Understand the Spec
+
+Read the spec file at `{{SPECS_DIR}}/{{SPEC_NAME}}.md` and extract:
+- Problem statement (WHY)
+- User stories (WHAT users can do)
+- Data model (entities, relationships)
+- UI/UX flows (screens, interactions)
+- Acceptance criteria (verification)
+
+### Step 2: Explore Codebase
+
+Before creating tasks, validate assumptions against actual code:
+- **Find files to modify:** Search for existing files related to the spec
+- **Identify patterns:** Look at similar features for structure to follow
+- **Check reusable code:** Find existing utilities, helpers, components
+- **Verify data model:** Check current database schema or data structures
+
+### Step 3: Create PRD
+
+Write the PRD to `{{PRD_PATH}}` as a JSON file with this exact structure:
+
+```json
+{
+  "spec": "{{SPEC_NAME}}.md",
+  "createdAt": "<ISO 8601 timestamp>",
+  "tasks": [
+    {
+      "id": "task-001",
+      "title": "[Action verb] [specific deliverable]",
+      "description": "[What to implement and why]",
+      "acceptanceCriteria": [
+        "[Specific, testable criterion 1]",
+        "[Specific, testable criterion 2]"
+      ],
+      "files": [
+        "path/to/file.ts (modify) — verified via Glob",
+        "path/to/new-file.ts (create) — parent dir verified"
+      ],
+      "dependencies": [],
+      "status": "pending",
+      "priority": 1
+    }
+  ]
+}
+```
+
+### Task Design Rules
+
+**Granularity:** Each task should take ~2 minutes. If longer, break it down.
+
+**Tracer bullet approach:** The first tasks should form a minimal end-to-end vertical slice:
+- Wrong: Schema → all queries → all actions → all UI
+- Right: Schema + one query + one action + one UI = tracer bullet, then expand
+
+**Task structure:**
+1. **Tracer phase** (1+ tasks) — minimal e2e slice
+2. Remaining tasks expand from the tracer, ordered by dependencies
+3. Each task lists specific files with (modify) or (create) and verification method
+
+**Dependencies:** Use task IDs. A task cannot start until all dependencies are `done`.
+
+**Priority:** Lower number = higher priority. Tracer tasks get priority 1.
+
+### Step 4: Verify & Output
+
+After writing the PRD:
+1. Re-read the file to confirm it's valid JSON
+2. Verify task count covers all spec requirements
+3. Output a summary:
+
+```
+## PRD Created for: {{SPEC_NAME}}
+
+Tasks: [count]
+Tracer tasks: [count]
+Dependencies: [count] relationships
+
+Ready to build: task-001, task-002 (no dependencies)
+```
+
+---
+
+## Guardrails
+
+1. **DO NOT implement** — only create the PRD
+2. **~2 minute tasks** — break down larger work
+3. **Verify file paths** — use Glob/Grep before referencing
+4. **Valid JSON** — the PRD must be parseable
+5. **All spec requirements covered** — every user story needs tasks

package/prompts/prompts.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, accessSync } from "node:fs";
+import { join } from "node:path";
+
+const PROMPTS_DIR = join(import.meta.dirname, ".");
+
+const PROMPT_FILES = ["PROMPT_PLAN.md", "PROMPT_BUILD.md"] as const;
+
+function readPrompt(name: string): string {
+	return readFileSync(join(PROMPTS_DIR, name), "utf-8");
+}
+
+function extractVars(content: string): string[] {
+	const matches = content.matchAll(/\{\{(\w+)\}\}/g);
+	return [...new Set([...matches].map((m) => m[1]))];
+}
+
+describe("prompt files", () => {
+	it.each(PROMPT_FILES)("%s exists and is readable", (file) => {
+		expect(() => accessSync(join(PROMPTS_DIR, file))).not.toThrow();
+	});
+
+	it.each(PROMPT_FILES)("%s is non-empty markdown", (file) => {
+		const content = readPrompt(file);
+		expect(content.length).toBeGreaterThan(0);
+		expect(content).toContain("#");
+	});
+
+	it.each(PROMPT_FILES)("%s contains :::TOBY_DONE::: sentinel", (file) => {
+		const content = readPrompt(file);
+		expect(content).toContain(":::TOBY_DONE:::");
+	});
+
+	it.each(PROMPT_FILES)("%s uses {{VAR_NAME}} syntax", (file) => {
+		const content = readPrompt(file);
+		// No single-brace vars like {VAR}
+		const singleBrace = content.match(/(?<!\{)\{([A-Z_]+)\}(?!\})/g);
+		expect(singleBrace).toBeNull();
+	});
+
+	it.each(PROMPT_FILES)("%s does not start with frontmatter", (file) => {
+		const content = readPrompt(file);
+		expect(content.startsWith("---")).toBe(false);
+	});
+
+	it.each(PROMPT_FILES)("%s does not contain dead vars", (file) => {
+		const content = readPrompt(file);
+		const deadVars = ["BRANCH", "WORKTREE", "EPIC_NAME", "IS_LAST_SPEC", "IS_EPIC", "SPEC_CONTENT"];
+		for (const v of deadVars) {
+			expect(content).not.toContain(`{{${v}}}`);
+		}
+	});
+});
+
+describe("PROMPT_PLAN.md variables", () => {
+	const vars = extractVars(readPrompt("PROMPT_PLAN.md"));
+
+	it.each(["SPEC_NAME", "ITERATION", "PRD_PATH", "SPECS_DIR"])(
+		"contains %s",
+		(v) => {
+			expect(vars).toContain(v);
+		},
+	);
+});
+
+describe("PROMPT_BUILD.md variables", () => {
+	const vars = extractVars(readPrompt("PROMPT_BUILD.md"));
+
+	it.each(["SPEC_NAME", "ITERATION", "SPECS_DIR", "SPEC_INDEX", "SPEC_COUNT", "SESSION", "SPECS"])(
+		"contains %s",
+		(v) => {
+			expect(vars).toContain(v);
+		},
+	);
+});
+