prloom 0.1.0

package/manual_agent.md

@@ -0,0 +1,164 @@
+# PRLoom Integration
+
+PRLoom is a CLI tool that orchestrates coding work through **plans** - markdown files that describe what needs to be built. Each plan contains an objective, context, and a TODO checklist. PRLoom manages the lifecycle: creating worktrees, opening PRs, and tracking progress.
+
+## What is a Plan?
+
+A plan is a markdown file with YAML frontmatter that describes a unit of work:
+
+```markdown
+---
+id: add-user-auth
+status: queued
+agent: manual
+base_branch: main
+---
+
+## Objective
+
+Add user authentication with email/password login.
+
+## Context
+
+- Auth library: `better-auth`
+- Database: SQLite via Drizzle ORM
+- Run tests: `bun test`
+
+## TODO
+
+- [ ] Create users table migration
+- [ ] Add login/signup API routes
+- [ ] Add session middleware
+
+## Progress Log
+
+<!-- Append entries as you complete work -->
+```
+
+## Plan Lifecycle
+
+1. **Create** - `prloom new <id> --agent manual --no-designer` creates a plan in `.prloom/inbox/<id>.md`
+2. **Edit** - Fill in the Objective, Context, and TODO sections
+3. **Dispatch** - When `prloom start` runs, the plan is moved to a git worktree and a draft PR is opened
+4. **Execute** - Complete each TODO, mark checkboxes, append to Progress Log
+5. **Complete** - When all TODOs are done, the PR is marked ready for review
+
+## CLI Commands
+
+| Command                                        | Description                                 |
+| ---------------------------------------------- | ------------------------------------------- |
+| `prloom init`                                  | Initialize prloom in a repository           |
+| `prloom new <id> --agent manual --no-designer` | Create a new plan skeleton                  |
+| `prloom status`                                | Show all plans with their worktree paths    |
+| `prloom edit <id> --no-designer`               | Print the path to an existing plan          |
+| `prloom poll <id>`                             | Fetch and display PR feedback               |
+| `prloom start`                                 | Start the dispatcher (manages PR lifecycle) |
+
+## Creating a New Plan
+
+```bash
+prloom new my-feature --agent manual --no-designer
+```
+
+Output:
+
+```
+Created plan in inbox: .prloom/inbox/my-feature.md
+Base branch: main
+Worker agent: manual
+
+Plan skeleton created. Edit manually or use your IDE.
+Run 'prloom start' to dispatch when ready.
+```
+
+The plan is now at `.prloom/inbox/my-feature.md`. Edit it to add your Objective, Context, and TODOs.
+
+## Finding Your Worktree
+
+After `prloom start` ingests the plan:
+
+```bash
+prloom status
+```
+
+Output:
+
+```
+INBOX (pending dispatch)
+────────────────────────────────────────────────────────────
+  (no inbox plans)
+
+ACTIVE PLANS
+────────────────────────────────────────────────────────────
+my-feature
+  Status:   active
+  Agent:    manual
+  PR:       PR #42
+  Worktree: /Users/dev/.prloom-worktrees/my-feature
+  Plan:     /Users/dev/.prloom-worktrees/my-feature/plans/my-feature.md
+
+────────────────────────────────────────────────────────────
+COMMANDS:
+  prloom new <id> --agent manual --no-designer  Create a new plan
+  prloom poll <id>                              View PR feedback
+  prloom edit <id> --no-designer                Get plan path
+```
+
+Open the worktree directory in your editor. The plan file is at `plans/<id>.md`.
+
+## Completing a TODO
+
+For each unchecked item (`- [ ] ...`):
+
+1. Read the task description
+2. Implement the change in code
+3. Mark the checkbox: `- [x] Task description`
+4. Add a progress entry:
+
+   ```
+   ## Progress Log
+
+   - 2026-01-04: Completed users table migration
+   ```
+
+5. Run any tests listed in the Context section
+6. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "[prloom] my-feature: users table migration"
+   git push
+   ```
+
+## Checking PR Feedback
+
+```bash
+prloom poll my-feature
+```
+
+Output:
+
+```
+PR FEEDBACK: my-feature
+PR #42 | Status: active
+────────────────────────────────────────────────────────────
+
+[1/4/2026] reviewer-name (comment)
+  Can you add input validation here?
+
+[1/4/2026] reviewer-name (inline comment)
+  File: src/routes/login.ts:45
+  This should handle the case where email is missing.
+
+────────────────────────────────────────────────────────────
+
+NEXT STEPS:
+  1. Review the feedback above
+  2. Add new TODO items to the plan if needed
+  3. Implement fixes in the worktree
+  4. Commit and push changes
+
+Worktree: /Users/dev/.prloom-worktrees/my-feature
+Plan:     /Users/dev/.prloom-worktrees/my-feature/plans/my-feature.md
+```
+
+Address the feedback by adding TODO items and implementing fixes.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "prloom",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "prloom": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    "prompts/**/*",
+    "manual_agent.md"
+  ],
+  "scripts": {
+    "gen:prompts": "bun run scripts/generate_prompts.ts",
+    "build": "bun run gen:prompts && bun build src/cli/index.ts --outdir dist/cli --target node",
+    "dev": "bun run gen:prompts && bun run src/cli/index.ts",
+    "test": "bun run gen:prompts && bun test",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.0.3",
+    "@types/yargs": "^17.0.35"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "execa": "^9.6.1",
+    "glob": "^13.0.0",
+    "gray-matter": "^4.0.3",
+    "handlebars": "^4.7.8",
+    "nanoid": "^5.1.6",
+    "yargs": "^18.0.0"
+  }
+}

package/prompts/designer.md

@@ -0,0 +1,36 @@
+# Designer Instructions
+
+You are helping the user create or refine a plan for a coding task.
+
+## Your Role
+
+1. Clarify what they want to build
+2. Discuss implementation approach if they want input
+3. Identify files, test commands, and context needed
+4. Fill in the plan sections
+
+## Plan Structure
+
+A plan file has already been created at the correct location (either `.prloom/inbox/<id>.md` before dispatch, or `plans/<id>.md` inside a worktree after dispatch).
+Your job is to fill in the sections of the existing file; do NOT create new plan files elsewhere.
+
+- **Objective**: Clear, specific description of what will be built
+- **Context**: Key files to modify, test commands, architecture notes, constraints
+- **TODO**: Granular, sequential tasks (keep them small and completable)
+
+The frontmatter (`id`, `status`, `agent`) is managed by the system — do not modify it.
+
+## Guidelines
+
+- TODOs should be small, completable in one session
+- Include test commands in Context if tests should be run
+- Inline all necessary context — Workers don't read other files
+
+{{#if existing_plan}}
+
+## Existing Plan
+
+The user wants to edit this existing plan:
+
+{{existing_plan}}
+{{/if}}

package/prompts/review_triage.md

@@ -0,0 +1,63 @@
+# Review Triage
+
+You are processing PR feedback for an active plan. Your job is to:
+
+1. Analyze all review feedback (comments, reviews, inline comments)
+2. Create specific, actionable TODO items for the plan
+3. Group related feedback into fewer tasks where appropriate
+4. Detect if a rebase was requested
+5. Compose a reply message for the reviewer(s)
+
+## Feedback to Process
+
+{{feedback}}
+
+## Current Plan
+
+{{plan}}
+
+## Instructions
+
+### Adding TODOs
+
+- Edit the plan file directly to add actionable TODOs
+- Add them at the end of the ## TODO section
+- Use the format: `- [ ] Specific actionable task`
+- Do NOT create vague tasks like "Address review comments"
+- Create SPECIFIC tasks like:
+  - "Update function X to handle null input"
+  - "Add test for Y edge case"
+  - "Rename Z for clarity"
+  - "Remove deprecated code in file A"
+- Group related comments into single tasks when logical
+- If the plan status is `done` and you add TODOs, change status to `active`
+
+### Writing the Result File
+
+After editing the plan, you MUST write `.prloom/triage-result.json` with:
+
+```json
+{
+  "reply_markdown": "## Triage Response\n\nThank you for your feedback...",
+  "rebase_requested": false
+}
+```
+
+**Required fields:**
+
+- `reply_markdown`: Your response to post on the PR (ALWAYS required, even for no-ops)
+- `rebase_requested`: Set to `true` if any comment mentions rebase, update branch, or similar
+
+### Reply Guidelines
+
+- Be polite and professional
+- Acknowledge specific feedback points
+- Explain what TODOs were created
+- If no changes needed, explain why
+- Keep it concise
+
+## Critical Rules
+
+1. You MUST write `.prloom/triage-result.json` even if you add no TODOs
+2. The result file must contain valid JSON only, no markdown wrapper
+3. Failure to write the result file will mark the plan as blocked

package/prompts/worker.md

@@ -0,0 +1,33 @@
+# Worker Instructions
+
+You are implementing exactly ONE task from this plan.
+
+## Your Task
+
+{{current_todo}}
+
+## Rules
+
+1. Implement only the specified task
+2. Update the plan file:
+   - Mark the task as `[x]`
+   - Add a Progress Log entry describing what you did
+3. Run tests if specified in the Context section
+4. If you get stuck and cannot complete the task:
+   - Set frontmatter `status: blocked`
+   - Explain the blocker in the Progress Log
+5. If this is the final TODO and all tasks are complete:
+   - Set frontmatter `status: done`
+6. Exit when complete
+
+## Important
+
+- Do NOT work on other TODOs, only the one specified above
+- The Progress Log is how humans track your work — be specific
+- If tests are specified, they must pass before marking complete
+
+---
+
+# Plan
+
+{{plan}}