@ob1-sg/horizon 0.1.11 → 0.2.0

package/README.md

@@ -1,6 +1,13 @@
-# Horizon - Autonomous Product Development Agent
+# Horizon - Turn Linear Tickets into Pull Requests with Parallel Agents
 
-Horizon is an AI-powered autonomous development system that works on Linear tickets without human intervention. It orchestrates multiple AI agents to research, plan, implement, and validate code changes, all while keeping Linear updated with progress.
+Horizon turns Linear tickets into pull requests with code changes. You write tickets, Horizon runs a loop of researching, planning, implementing, and validating changes on its own. Multiple Horizon agents can work in parallel so you can focus on reviewing high-quality PRs. The validation pipeline ensures the pull requests are tested, easy to review, and ready to merge.
+
+## Prerequisites
+
+- Node v24.12.0 (only version tested so far)
+- [Claude Code (recommended)](https://code.claude.com/docs/en/setup#installation) or OpenAI Codex CLI installed
+- A Linear account with API access
+- Git repository initialized
 
 ## Installation
 
@@ -20,57 +27,27 @@ npm install --save-dev @ob1-sg/horizon
 
 1. **Install Horizon** (see above)
 
-2. **Run Horizon**:
+2. **Run Horizon** in your project:
    ```bash
-   cd your-project
+   cd your-project-with-git-initialized
    horizon              # Global install
    npx horizon          # Local install
    ```
 
-3. **First-run setup** - On first run, Horizon will:
-   - Prompt for your Linear API key
-   - Auto-detect your Linear team
-   - Create necessary directories and configuration
-   - Start the development loop
+3. **First-run wizard** — Horizon walks you through setup:
+   - Enter your Linear API key
+   - Auto-detects your Linear team (or lets you pick)
+   - Auto-selects AI provider (Claude Code or OpenAI Codex) based on what's installed, defaulting to Claude Code
+   - Choose merge mode: `auto` (recommended), `merge`, or `pr`
+   - Creates `.horizon/` config directory
+   - Sets up Horizon Agent's `∞` workflow statuses in your Linear team
 
-4. **Create tickets** in Linear and Horizon will work on them autonomously
+4. **Create tickets** in Linear and Horizon works on them autonomously
 
-For advanced configuration, run `horizon config` to change settings like provider, model, and iteration limits.
+Run `horizon config` to change settings like provider, model, and iteration limits.
 
 ## How It Works
 
-Horizon uses three core concepts: **Pods**, **Loops**, and **Agents**.
-
-### Pods, Loops, and Agents
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         Pod (swift-wyvern)                              │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                         │
-│  Loop 1: Ticket RSK-42                                                  │
-│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐            │
-│  │   Agent 1    │     │   Agent 2    │     │   Agent 3    │            │
-│  │    Linear    │────▶│    Worker    │────▶│    Linear    │            │
-│  │    Reader    │     │              │     │    Writer    │            │
-│  └──────────────┘     └──────────────┘     └──────────────┘            │
-│                                                                         │
-│  Loop 2: Ticket RSK-43                                                  │
-│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐            │
-│  │   Agent 1    │────▶│   Agent 2    │────▶│   Agent 3    │            │
-│  └──────────────┘     └──────────────┘     └──────────────┘            │
-│                                                                         │
-│  Loop 3: ...                                                            │
-│                                                                         │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-- **Pod**: A running instance of Horizon. Each pod gets a unique name (e.g., "swift-wyvern") and continuously processes tickets until stopped. You can run multiple pods in parallel.
-
-- **Loop**: One complete cycle of work. Each loop claims a ticket, works on it, and updates Linear. A pod runs loops continuously until there's no more work.
-
-- **Agent**: An AI worker that handles one part of the loop. Three agents work in sequence to complete each loop.
-
 ### The Agent Pipeline
 
 1. **Agent 1 (Linear Reader)**: Scans Linear for available tickets, prioritizes by urgency, **claims** the highest-priority ticket, and gathers context.
@@ -79,48 +56,52 @@ Horizon uses three core concepts: **Pods**, **Loops**, and **Agents**.
 
 3. **Agent 3 (Linear Writer)**: Updates Linear with results - posts comments, updates status, and links commits.
 
-### Parallel Execution
 
-Multiple pods can work on the same codebase simultaneously. Horizon prevents conflicts through **ticket claiming**:
+### The Agent Loop
 
-1. When Agent 1 finds a ticket to work on, it immediately changes the status to "In Progress"
-2. Other pods see this status and skip the ticket
-3. Each pod works on different tickets, avoiding collisions
+```
++-----------------------------------------------------------------------+
+|                        Instance (yellow-giraffe)                      |
++-----------------------------------------------------------------------+
+|                                                                       |
+|  Loop 1: Ticket PROJ-12                                               |
+|  +------------+     +------------+     +------------+                 |
+|  |  Agent 1   |     |  Agent 2   |     |  Agent 3   |                 |
+|  |  Linear    |---->|  Worker    |---->|  Linear    |                 |
+|  |  Reader    |     |            |     |  Writer    |                 |
+|  +------------+     +------------+     +------------+                 |
+|                                                                       |
+|  Loop 2: Ticket PROJ-13                                               |
+|  +------------+     +------------+     +------------+                 |
+|  |  Agent 1   |---->|  Agent 2   |---->|  Agent 3   |                 |
+|  +------------+     +------------+     +------------+                 |
+|                                                                       |
+|  Loop 3: ...                                                          |
+|                                                                       |
++-----------------------------------------------------------------------+
+```
 
-This lets you scale development by running multiple Horizon pods in parallel - on different machines, in CI, or as background processes.
+1. Create a ticket in Linear and set its status to `Backlog (default)` (or any `Needs ...` status)
+2. Horizon claims it, does the work, and advances to the next stage
+3. This repeats automatically until the ticket reaches `∞ Done`
+4. Retry any stage by moving the ticket back to `Backlog` (or any `Needs ...` status)
+5. Queue multiple tickets — Horizon processes them by priority, which you can configure in Linear. Provide feedback or unblock the agent when human intervention is needed
 
-### Linear as State Machine
+### Parallel Execution
 
-Horizon uses Linear as its state machine. You don't need to configure Horizon or tell it what to work on - just add tickets to Linear and Horizon handles the rest.
+Run `horizon` in a separate terminal window for each parallel agent. Agents coordinate through Linear: when one agent claims a ticket, it changes the status to "In Progress" so other agents skip it. Agent 1 (the orchestrator) understands ticket hierarchy and dependencies, so it picks the right work in the right order. Each instance runs loops continuously until there's no more work.
 
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  ∞ Needs    │────▶│  ∞ Needs    │────▶│  ∞ Needs    │────▶│  ∞ Needs    │────▶│  ∞ Needs    │
-│  Research   │     │    Spec*    │     │    Plan     │     │  Implement  │     │  Validate   │
-└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
-       │                  │                   │                   │                   │
-       ▼                  ▼                   ▼                   ▼                   ▼
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│ ∞ Research  │     │  ∞ Spec In  │     │  ∞ Plan In  │     │∞ Implement  │     │ ∞ Validate  │
-│ In Progress │     │  Progress*  │     │  Progress   │     │ In Progress │     │ In Progress │
-└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
-                                                                                      │
-                          * Specification is optional - only when                     ▼
-                            research determines UX decisions are needed         ┌─────────────┐
-                                                                                │   ∞ Done    │
-                                                                                └─────────────┘
-```
+### Git Worktree Isolation
 
-**How it works:**
+Each Agent 2 (Worker) runs in its own [git worktree](https://git-scm.com/docs/git-worktree), so multiple agents can work on different tickets in parallel without conflicts. When a ticket is claimed:
 
-1. **You create a ticket** in Linear and set its status to `∞ Needs Research` (or any "Needs" status)
-2. **Horizon picks it up** - Agent 1 scans for tickets in "Needs" statuses
-3. **Horizon claims it** - Changes status to "In Progress" so other pods skip it
-4. **Horizon works on it** - Agent 2 does the actual development work
-5. **Horizon advances it** - Agent 3 moves the ticket to the next status
-6. **Repeat** until the ticket reaches `∞ Done`
+1. Horizon creates a worktree at `.horizon/worktrees/{issue-identifier}/`
+2. The worktree checks out a dedicated branch: `horizon/{issue-identifier}`
+3. Dependencies are installed in the worktree automatically
+4. Agent 2 runs entirely within the worktree
+5. After completion, the worktree is cleaned up
 
-This means you can queue up work by creating tickets, and Horizon will process them in priority order. You can also intervene at any point - move a ticket back to a "Needs" status and Horizon will re-do that step.
+This means you can run multiple `horizon` instances simultaneously — each one gets an isolated copy of the repo with its own branch, so there are no working directory conflicts between agents.
 
 ## Directory Structure
 
@@ -131,15 +112,25 @@ your-project/
 ├── .horizon/              # Runtime data (gitignored)
 │   ├── env                # Configuration and credentials
 │   ├── mcp.json           # MCP configuration for Claude Code
+│   ├── prompts/           # Agent prompt templates (synced from package)
 │   ├── output/            # Runtime logs
+│   ├── worktrees/         # Git worktrees for parallel agents
 │   └── attachments/       # Downloaded issue attachments
 ├── horizon-docs/          # Work artifacts (committed)
 │   ├── research/          # Research documents
 │   ├── plans/             # Implementation plans
-│   └── validation/        # Validation reports
+│   ├── validation/        # Validation reports
+│   ├── oneshot/           # Oneshot completions
+│   ├── specifications/    # Feature specifications
 └── CLAUDE.md              # Your project's Claude instructions
 ```
 
+### Horizon Documentation Folder
+
+The `horizon-docs/` folder contains the work artifacts for Horizon. You can use this folder to track the work that Horizon has done.
+
+However, the main purpose of this folder is for the agent to document its work and historical changes, which are valuable for understanding the codebase evolution and development of future features.
+
 ## Configuration
 
 ### Environment Variables
@@ -153,19 +144,25 @@ Set these in `.horizon/env` or export them:
 | `HORIZON_PROVIDER` | AI provider: "claude" or "codex" | "claude" |
 | `HORIZON_CLAUDE_MODEL` | Claude model: "opus", "sonnet", "haiku" | "opus" |
 | `HORIZON_MAX_ITERATIONS` | Stop after N iterations (0 = unlimited) | 0 |
-| `HORIZON_MERGE_MODE` | Merge mode: "merge" or "pr" | "merge" |
+| `HORIZON_MERGE_MODE` | Merge mode: "auto", "merge", or "pr" | "auto" |
 
 ### Merge Modes
 
-Horizon supports two modes for completing work:
+Horizon supports three modes for completing work:
 
-**Direct Merge (default)**
+**Auto (default)**
+```bash
+export HORIZON_MERGE_MODE=auto
+```
+The agent decides the safest path — merge directly for small changes, create a PR for larger ones.
+
+**Direct Merge**
 ```bash
 export HORIZON_MERGE_MODE=merge
 ```
 Horizon merges completed work directly to main. Best for trusted autonomous operation.
 
-**Pull Request Mode**
+**Pull Request**
 ```bash
 export HORIZON_MERGE_MODE=pr
 ```
@@ -204,69 +201,26 @@ Update with:
 npm install -g @ob1-sg/horizon@latest
 ```
 
-## Releasing (Maintainers)
-
-Releases are performed via GitHub Actions.
-
-### Preflight
-
-1. Confirm GitHub repo secrets:
-   - `NPM_TOKEN` (required): npm publish token with access to publish `@ob1-sg/horizon`.
-   - `RELEASE_TOKEN` (optional): GitHub token/PAT with `contents: write` in case `github.token` can’t push to `main` due to branch protections (also used to create the GitHub Release).
-2. Confirm no other release run is in progress (the workflow uses `concurrency: release`).
-
-### Optional: dry run (CI gates only)
-
-1. GitHub → Actions → `Release` → Run workflow (branch: `main`)
-2. Inputs:
-   - `release_type`: `patch`
-   - `npm_tag`: `latest`
-   - `dry_run`: `true`
-3. Expectation: build/typecheck/tests run and pass; **no** version bump commit, tag, GitHub Release, or npm publish is created.
-
-### Patch release
-
-1. GitHub → Actions → `Release` → Run workflow (branch: `main`)
-2. Inputs:
-   - `release_type`: `patch` (or `minor` / `major`)
-   - `npm_tag`: `latest` (or another intended dist-tag)
-   - `dry_run`: `false`
-3. Expected outputs:
-   - A commit on `main` with message like `chore(release): vX.Y.Z`
-   - A git tag `vX.Y.Z` pushed to the repo
-   - A GitHub Release created for `vX.Y.Z` (auto-generated notes)
-   - `@ob1-sg/horizon@X.Y.Z` published to npm under the chosen dist-tag
-
-### Recovery (partial failures)
-
-- **Tag exists but npm publish failed**: GitHub → Actions → `Publish existing ref to npm`
-  - `ref`: the tag (e.g. `vX.Y.Z`)
-  - `npm_tag`: the intended dist-tag (default `latest`)
-- **npm publish succeeded but GitHub Release creation failed**: create a GitHub Release from the existing tag (UI or `gh release create vX.Y.Z --generate-notes`).
-
-### Rollback (only if necessary)
-
-If a tag was created but should not exist (and npm publish did not occur):
-
-```bash
-git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
-```
+## Writing Good Tickets
 
-Delete the GitHub Release for that tag in the UI if one was created.
+Horizon works best with clear, specific tickets:
 
-### Local parity checks (optional)
+**Good ticket**:
+> Add a dark mode toggle to the settings page. Should save preference to localStorage and apply a .dark-theme class to the body.
 
-```bash
-npm ci
-npm run build
-npm run typecheck
-npm test
-```
+**Tips**:
+- Include **acceptance criteria** when possible
+- Reference existing code patterns to follow
+- Specify any constraints or requirements
+- Link related issues if dependencies exist
 
 ## Linear Workflow Statuses
 
 Horizon creates these statuses in Linear:
 
+**Backlog**:
+- `Backlog (default)`
+
 **Ready statuses** (waiting for Horizon):
 - `∞ Needs Research`
 - `∞ Needs Specification` (optional - when UX decisions are needed)
@@ -280,6 +234,7 @@ Horizon creates these statuses in Linear:
 - `∞ Plan In Progress`
 - `∞ Implement In Progress`
 - `∞ Validate In Progress`
+- `∞ Oneshot In Progress`
 
 **Intervention statuses** (requires human action):
 - `∞ Blocked` - Agent needs clarification or decision before proceeding
@@ -289,55 +244,21 @@ Horizon creates these statuses in Linear:
 - `∞ Done`
 - `∞ Canceled`
 
-## Writing Good Tickets
-
-Horizon works best with clear, specific tickets:
-
-**Good ticket**:
-> Add a dark mode toggle to the settings page. Should save preference to localStorage and apply a .dark-theme class to the body.
-
-**Tips**:
-- Include acceptance criteria when possible
-- Reference existing code patterns to follow
-- Specify any constraints or requirements
-- Link related issues if dependencies exist
-
 ## Developing Horizon
 
 If you want to contribute or modify Horizon:
 
-```bash
-# Clone the repo
-git clone https://github.com/ob1-sg/horizon
-cd horizon
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run from source
-npm start
-
-# Type check
-npm run typecheck
-```
-
-## Prerequisites
-
-- Node.js 18+
-- [Claude Code](https://claude.ai/claude-code) or Codex CLI installed
-- A Linear account with API access
-- Git repository initialized
+See [CONTRIBUTING.md](CONTRIBUTING.md) for release process and maintainer guidelines.
 
 ## Acknowledgments
 
 Horizon builds on ideas and techniques from the AI engineering community:
 
+- **[Ramp Inspect](https://builders.ramp.com/post/why-we-built-our-background-agent)** - For agent UIUX, infrastructure and tooling inspiration.
+- **[Stripe Minions](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)** - For the architecture and design of multiple agents working in parallel.
 - **[Dex Horthy](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md)** - For the research/plan/implement pattern that structures how Horizon approaches work
 - **[Geoff Huntley](https://ghuntley.com/ralph/)** - For the Ralph Wiggum technique that inspires Horizon's autonomous agent approach
-- **[Vaibhav @ BoundaryML](https://boundaryml.com/podcast)** - For BAML and the "AI That Works" podcast series on building reliable AI systems
+- **[Vaibhav's BoundaryML Podcast](https://boundaryml.com/podcast)** - For "AI That Works" podcast series on building reliable AI systems
 
 ## License
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyCA,OAAO,iBAAiB,CAAC;AACzB,OAAO,gBAAgB,CAAC;AAwjBxB,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAiI1C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8CA,OAAO,iBAAiB,CAAC;AACzB,OAAO,gBAAgB,CAAC;AAgpBxB,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAqI1C"}