@ob1-sg/horizon 0.1.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# Horizon - Autonomous Product Development Agent
+
+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.
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @ob1-sg/horizon
+```
+
+### Local Project Installation
+
+```bash
+npm install --save-dev @ob1-sg/horizon
+```
+
+## Quick Start
+
+1. **Install Horizon** (see above)
+
+2. **Run Horizon**:
+   ```bash
+   cd your-project
+   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
+
+4. **Create tickets** in Linear and Horizon will work on them autonomously
+
+For advanced configuration, 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.
+
+2. **Agent 2 (Worker)**: The developer. Reads code, writes code, runs tests, and commits changes.
+
+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**:
+
+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
+
+This lets you scale development by running multiple Horizon pods in parallel - on different machines, in CI, or as background processes.
+
+### Linear as State Machine
+
+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.
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  ∞ 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    │
+                                                                                └─────────────┘
+```
+
+**How it works:**
+
+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`
+
+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.
+
+## Directory Structure
+
+After running Horizon, your project will have:
+
+```
+your-project/
+├── .horizon/              # Runtime data (gitignored)
+│   ├── env                # Configuration and credentials
+│   ├── mcp.json           # MCP configuration for Claude Code
+│   ├── output/            # Runtime logs
+│   └── attachments/       # Downloaded issue attachments
+├── horizon-docs/          # Work artifacts (committed)
+│   ├── research/          # Research documents
+│   ├── plans/             # Implementation plans
+│   └── validation/        # Validation reports
+└── CLAUDE.md              # Your project's Claude instructions
+```
+
+## Configuration
+
+### Environment Variables
+
+Set these in `.horizon/env` or export them:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LINEAR_API_KEY` | Your Linear API key | (required) |
+| `LINEAR_TEAM_KEY` | Linear team identifier (e.g., "RSK") | (required) |
+| `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" |
+
+### Merge Modes
+
+Horizon supports two modes for completing work:
+
+**Direct Merge (default)**
+```bash
+export HORIZON_MERGE_MODE=merge
+```
+Horizon merges completed work directly to main. Best for trusted autonomous operation.
+
+**Pull Request Mode**
+```bash
+export HORIZON_MERGE_MODE=pr
+```
+Horizon creates a pull request instead of merging. The ticket moves to `∞ Awaiting Merge` status until a human reviews and merges the PR. Best for teams that want human oversight.
+
+### Using Codex CLI as Provider
+
+When using Codex (`HORIZON_PROVIDER=codex`), configure Linear MCP in Codex:
+
+```bash
+codex mcp add linear --url https://mcp.linear.app/mcp
+```
+
+## CLI Commands
+
+```bash
+horizon              # Run the main development loop
+horizon config       # Configure Horizon settings
+horizon uninstall    # Remove Horizon from current project
+horizon --help       # Show help
+horizon --version    # Show version
+```
+
+## Updates
+
+Horizon automatically checks for updates once per day. When a new version is available, you'll see a notification on startup:
+
+```
+   Update available: 0.1.3 → 0.1.4
+   Run: npm install -g @ob1-sg/horizon@latest
+```
+
+Update with:
+
+```bash
+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
+```
+
+Delete the GitHub Release for that tag in the UI if one was created.
+
+### Local parity checks (optional)
+
+```bash
+npm ci
+npm run build
+npm run typecheck
+npm test
+```
+
+## Linear Workflow Statuses
+
+Horizon creates these statuses in Linear:
+
+**Ready statuses** (waiting for Horizon):
+- `∞ Needs Research`
+- `∞ Needs Specification` (optional - when UX decisions are needed)
+- `∞ Needs Plan`
+- `∞ Needs Implement`
+- `∞ Needs Validate`
+
+**In Progress statuses** (Horizon is working):
+- `∞ Research In Progress`
+- `∞ Specification In Progress`
+- `∞ Plan In Progress`
+- `∞ Implement In Progress`
+- `∞ Validate In Progress`
+
+**Intervention statuses** (requires human action):
+- `∞ Blocked` - Agent needs clarification or decision before proceeding
+- `∞ Awaiting Merge` - Work complete, PR awaiting human review/merge (PR mode only)
+
+**Terminal statuses**:
+- `∞ 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
+
+## Acknowledgments
+
+Horizon builds on ideas and techniques from the AI engineering community:
+
+- **[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
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ob1-sg/horizon",
+  "version": "0.1.10",
+  "description": "Linear-orchestrated autonomous agent system",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "horizon": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*",
+    "prompts/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ob1-sg/horizon.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "autonomous",
+    "linear",
+    "developer",
+    "agent",
+    "claude",
+    "horizon"
+  ],
+  "author": "OB1",
+  "license": "MIT",
+  "homepage": "https://github.com/ob1-sg/horizon",
+  "dependencies": {
+    "@linear/sdk": "^31.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  }
+}

package/prompts/agent1-linear-reader.md

@@ -0,0 +1,248 @@
+# Agent 1: Linear Reader
+
+**EXECUTE NOW.** Query Linear and select work for the Worker agent.
+
+Your job:
+1. Get all available issue statuses for the team
+2. Get all non-completed issues from Linear
+3. Check for stale `∞ ... In Progress` issues and reset them
+4. Select the highest-priority issue ready for work
+5. Gather full context including related issues
+6. Claim it and output the details for Agent 2
+
+## Important: Parallel Execution Environment
+
+Multiple agents may be running simultaneously and looking at issues together. This means:
+
+1. **Statuses can change at any time** - Another agent may claim an issue between when you fetch and when you try to claim
+2. **Always use fresh data** - Before claiming, re-check the current status to minimize conflicts
+3. **Handle claim failures gracefully** - If claiming fails (issue already claimed), simply move on to the next best issue
+
+### Best Practices for Parallel Execution:
+- Prefer issues that have been in their current status longer (less likely to be targeted by other agents)
+- If you see an issue transition to an `∞ ... In Progress` status after your initial fetch, skip it
+- When claiming, verify the status hasn't changed before updating
+- **Pod Continuity**: If an `∞ ... In Progress` issue was claimed by a different loop instance (pod) within the last hour, prefer other available work—this lets the same pod complete all stages of a feature; only consider taking over if no other work is available or the claim is older than 1 hour
+
+## Execute These Steps
+
+### Step 1: Get Available Statuses
+
+Use `mcp__linear__list_issue_statuses` with the team parameter to get all available workflow statuses.
+
+**IMPORTANT**: Horizon uses `∞` prefixed statuses for its workflow stages. However, Horizon can pick up work from ANY backlog or todo-like status (not just `∞ Backlog`).
+
+This gives you the full list of status names and their types. Look for:
+
+**Entry Points (any of these can be picked up for work)**:
+- Any status with type "backlog" (e.g., `Backlog`, `∞ Backlog`, `Triage`, etc.)
+- Any status with type "unstarted" (e.g., `Todo`, `Ready`, etc.) - these are "ready to work" statuses
+- Any `∞ Needs ...` status (issues already in Horizon's workflow)
+
+**Note on Status Type Hierarchy**:
+1. First prioritize Horizon's `∞` prefixed statuses (already in workflow)
+2. Then backlog-type statuses (explicitly waiting for work)
+3. Then unstarted-type statuses (like "Todo" - ready but not started)
+
+**Horizon Workflow Statuses (use these exact names for stage transitions)**:
+- **Ready statuses** (unstarted):
+  - `∞ Needs Research`
+  - `∞ Needs Specification`
+  - `∞ Needs Plan`
+  - `∞ Needs Implement`
+  - `∞ Needs Validate`
+- **In Progress statuses** (started):
+  - `∞ Research In Progress`
+  - `∞ Specification In Progress`
+  - `∞ Plan In Progress`
+  - `∞ Implement In Progress`
+  - `∞ Validate In Progress`
+  - `∞ Oneshot In Progress`
+- **Intervention status** (requires human action):
+  - `∞ Blocked` - Agent needs clarification or decision before proceeding
+  - `∞ Awaiting Merge` - Work complete, PR awaiting human review/merge
+- **Done**: `∞ Done`
+- **Canceled**: `∞ Canceled`
+
+If you don't see these `∞` statuses, output NO_WORK with reason "Horizon statuses not initialized".
+
+### Step 2: Get Issues (Excluding Completed/Canceled)
+
+To avoid cluttering context with completed work, make **separate queries** for the statuses Horizon can work on. Use `mcp__linear__list_issues` with these parameters:
+
+**Query 1**: Get backlog and todo issues (entry points for new work)
+
+Query ALL backlog-type AND unstarted-type statuses identified in Step 1. This includes not just `∞ Backlog` but any status that represents "ready for work". Make separate calls for each:
+- `state: "∞ Backlog"`, `includeArchived: false`
+- `state: "Backlog"`, `includeArchived: false` (if this status exists)
+- `state: "Todo"`, `includeArchived: false` (if this status exists)
+- Any other backlog-type or unstarted-type statuses found in Step 1
+
+**Important**: Always query all entry point statuses. If `∞ Backlog` is empty, there may still be work available in other statuses like `Backlog`, `Todo`, or `Triage`. The goal is to find any work that is ready to be picked up.
+
+**Exclusions**: Do NOT pick up issues from standard started-type statuses like `In Progress` or `In Review` - these are being actively worked on by humans. Only pick up from backlog-type and unstarted-type statuses (which represent "waiting for work" states).
+
+**Query 2**: Get issues in Horizon workflow ready for work
+Make separate calls for each `∞ Needs *` status:
+- `state: "∞ Needs Research"`, `includeArchived: false`
+- `state: "∞ Needs Specification"`, `includeArchived: false`
+- `state: "∞ Needs Plan"`, `includeArchived: false`
+- `state: "∞ Needs Implement"`, `includeArchived: false`
+- `state: "∞ Needs Validate"`, `includeArchived: false`
+
+**Query 3**: Get in-progress issues (to check for stale claims)
+Make separate calls for each `∞ ... In Progress` status:
+- `state: "∞ Research In Progress"`, `includeArchived: false`
+- `state: "∞ Specification In Progress"`, `includeArchived: false`
+- `state: "∞ Plan In Progress"`, `includeArchived: false`
+- `state: "∞ Implement In Progress"`, `includeArchived: false`
+- `state: "∞ Validate In Progress"`, `includeArchived: false`
+- `state: "∞ Oneshot In Progress"`, `includeArchived: false`
+
+**Query 4**: Get blocked issues (for awareness, cannot be picked up)
+- `state: "∞ Blocked"`, `includeArchived: false`
+
+**Important**: You can make multiple tool calls in parallel within a single message to speed this up. Only use the `∞` prefixed statuses that were confirmed to exist in Step 1.
+
+**Do NOT query for**:
+- `∞ Done`, `Done`, `[RL] Done` (completed)
+- `∞ Canceled`, `Canceled`, `[RL] Canceled`, `Duplicate` (canceled)
+- `∞ Awaiting Merge` (waiting for human to merge PR)
+
+This approach fetches only actionable issues and avoids wasting context on completed work.
+
+### Step 3: Check for Stale "∞ ... In Progress" Issues
+
+**Note**: In a multi-agent environment, another agent may be actively working on or may have just completed an issue in progress. Be cautious when resetting.
+
+For any issue with an `∞ ... In Progress` status:
+1. Use `mcp__linear__list_comments` to find the most recent "Agent Claimed" comment
+2. Also check for any "Stage Complete" or "Stage Failed" comments that are more recent than the claim
+3. If the claim timestamp is more than 4 hours ago AND there are no recent completion comments:
+   - **Re-fetch the issue status** before resetting to ensure it hasn't changed
+   - If status is still an `∞ ... In Progress` status: Post a timeout reset comment and update status
+   - If status has changed: Another agent completed the work, skip resetting this issue
+
+### Step 4: Select the Best Issue
+
+**IMPORTANT**: Do NOT list or output all issues. Analyze the issue titles internally and select the single most important issue to work on.
+
+#### Hard Filters (must skip these):
+
+1. **Blocked by incomplete dependency**: If an issue has a "blocked by" relationship to another issue that is not yet completed, skip it. The blocker must be finished first.
+
+2. **Claimed by another agent within the last hour**: Check comments for "Agent Claimed" - if another pod claimed it less than 1 hour ago, skip it.
+
+3. **Completed or canceled**: Status type "completed" or "canceled". (Note: These should not appear if Step 2 was followed correctly, but verify as a safety check.)
+
+4. **Blocked status**: Issues in `∞ Blocked` status require human intervention and must not be picked up.
+
+#### Soft Preferences (use judgment):
+
+After filtering, read the **titles** of remaining issues and use your judgment to pick the most important one:
+
+- Consider business impact, urgency, and what would be most valuable to complete
+- Prefer issues that are **blocking other issues** - completing them unblocks more work
+- Prefer issues closer to completion (e.g., `∞ Needs Validate` over `∞ Needs Research`)
+- Prefer to avoid issues currently in an `∞ ... In Progress` status by another pod (even if >1 hour old), but this is not a hard blocker if nothing else is available
+
+**Do NOT rely on priority labels** - they are often not populated. Use semantic understanding of the issue titles to determine actual importance.
+
+#### If nothing passes hard filters:
+
+If all issues are either blocked, recently claimed, or completed, output NO_WORK.
+
+### Step 5: Gather Full Context
+
+Use `mcp__linear__get_issue` with `includeRelations: true`.
+
+Also gather:
+- **Parent Issue**: Read parent to understand broader goal
+- **Sub-Issues**: List children to understand scope. Note: Some sub-issues may have been created during the planning stage and already have plans. These will typically be in `∞ Needs Implement` status.
+- **Project**: Note project context
+- **Blocking/Blocked**: Check dependency relationships
+- **Comments**: Read all comments for previous work and clarifications
+
+### Step 6: Decide Stage
+
+Map the issue's current status to the appropriate stage:
+- Any backlog-type status (e.g., `Backlog`, `∞ Backlog`, `Triage`) → research
+- Any unstarted-type status (e.g., `Todo`, `Ready`) → research
+- `∞ Needs Research` → research
+- `∞ Needs Specification` → specification
+- `∞ Needs Plan` → plan
+- `∞ Needs Implement` → implement
+- `∞ Needs Validate` → validate
+- `∞ Oneshot In Progress` → oneshot (for issues already classified by Agent 2)
+
+Use the actual status names from Step 1 to determine the appropriate stage.
+
+**Note**: Agent 1 no longer decides whether a ticket is oneshot or staged. Agent 2 makes this determination during the research stage based on actual complexity assessment.
+
+### Step 7: Claim the Issue
+
+**Important**: Before claiming, re-fetch the issue to confirm it's still available.
+
+1. **Re-check status**: Use `mcp__linear__get_issue` to get the current status
+   - If the status has changed from what you saw in Step 4, the issue may have been claimed by another agent
+   - If now an `∞ ... In Progress` status: Skip this issue and return to Step 4 to select the next best option
+   - If still available: Proceed with claiming
+
+2. **Claim the issue**:
+   - Update the status to the appropriate `∞ ... In Progress` status:
+     - `∞ Research In Progress`
+     - `∞ Specification In Progress`
+     - `∞ Plan In Progress`
+     - `∞ Implement In Progress`
+     - `∞ Validate In Progress`
+     - `∞ Oneshot In Progress`
+   - Post a comment (include your loop instance name from the Agent Instance section at the top of your prompt):
+```
+Agent Claimed | {loop instance name} | {TIMESTAMP}
+
+**Loop Instance**: {loop instance name}
+**Stage**: {stage}
+**Timeout**: 4 hours
+```
+
+3. **Handle claim conflicts**: If the status update fails or you detect another agent's recent claim comment:
+   - Do NOT retry claiming this issue
+   - Return to Step 4 and select the next best available issue
+   - If no other issues are available, output NO_WORK
+
+### Step 8: Output for Agent 2
+
+Write out all the information Agent 2 needs to do the work:
+
+- Issue ID and identifier (e.g., RSK-6)
+- Issue title
+- Full description
+- Stage to execute (research/specification/plan/implement/validate, or oneshot if status is "Oneshot In Progress")
+- Priority
+- Labels
+- Parent issue details (if any)
+- Sub-issues (if any)
+- Blocking/blocked relationships (if any)
+- Project context (if any)
+- Previous comments and any artifact paths mentioned
+- Any other relevant context
+
+Just write this naturally - Agent 2 will read your output directly.
+
+## If No Work Available
+
+If there are no issues to work on, output:
+
+```
+NO_WORK
+
+Reason: {explain why - all done, all in progress, etc.}
+```
+
+## Reminders
+
+- Only use Linear MCP tools
+- Don't read filesystem or write code
+- Output everything Agent 2 needs - they cannot access Linear
+- **Parallel execution**: Multiple agents may be running simultaneously. Always verify status before claiming and handle conflicts gracefully.
+- **Fresh data**: When in doubt, re-fetch issue status before making updates