playbooks

home / skills / tomkrikorian / visionosagents / ralph-driven-development-linear

ralph-driven-development-linear skill

/skills/ralph-driven-development-linear

This skill automates Linear project task execution by sequentially running Codex agents, advancing issues, and tracking retries for efficient workflow.

npx playbooks add skill tomkrikorian/visionosagents --skill ralph-driven-development-linear

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.7 KB
---
name: ralph-driven-development-linear
description: Ralph Driven Development workflow that pulls Linear project issues via the Linear MCP and runs them sequentially with Codex. Use when automating task execution from a Linear project and when you need a runner that advances issues and asks for the next task automatically.
---

# Ralph Driven Development (Linear)

## Description and Goals

This skill provides a Ralph Driven Development workflow that pulls Linear project issues via the Linear MCP and runs them sequentially with Codex. It automates task execution from a Linear project and advances issues automatically.

### Goals

- Automate development workflow using Linear project issues
- Integrate with Linear MCP for issue management
- Run Codex agents sequentially against Linear issues
- Track progress and handle retries automatically
- Support customizable runner configuration

## What This Skill Should Do

When automating task execution from a Linear project, this skill should:

1. **Connect to Linear** - Authenticate with Linear MCP and resolve project
2. **Fetch issues** - Pull issues from the specified Linear project
3. **Execute sequentially** - Run Codex against each issue in order
4. **Track progress** - Monitor completion and handle retries
5. **Advance issues** - Automatically move to the next issue after completion

Use this skill when automating task execution from a Linear project and when you need a runner that advances issues and asks for the next task automatically.

## Information About the Skill

### Prerequisites

- `codex` is on PATH.
- Linear MCP is authenticated: `codex mcp login linear`
- Provide a project via `--project` or `AGENTS.MD`.

### Run

```bash
python scripts/ralph-linear.py --project "Project Name"
```

### Flags

- `--project` Linear project name or ID. If omitted, reads `Linear Project:` under `## PROJECT` in `AGENTS.MD`.
- `--agents-path` Path to `AGENTS.MD`. Default: `AGENTS.MD`.
- `--codex-exe` Codex executable name or path. Default: `codex`.
- `--codex-args` Space-separated Codex args string. Default: `exec --dangerously-bypass-approvals-and-sandbox`.
- `--codex-timeout` Seconds before killing a Codex run; `0` = unlimited. Default: `0`.
- `--max-tasks` Max issues to process; `0` = unlimited. Default: `0`.
- `--max-attempts-per-task` Retries per issue. Default: `5`.
- `--log-path` Log file path (repo-relative or absolute). Default: `docs/logs/linear.log`.
- `--dry-run` Resolve project and exit without running Codex.

### Examples

```bash
python scripts/ralph-linear.py --project "VisionOS Agents" --max-tasks 3
```

```bash
python scripts/ralph-linear.py \
  --project "VisionOS Agents" \
  --codex-args 'exec --full-auto -m gpt-5.2-codex'
```

Overview

This skill automates a Ralph Driven Development workflow that pulls issues from a Linear project and runs them sequentially with Codex. It advances issues automatically, tracks progress, and supports configurable retries and timeouts. Use it to turn a Linear backlog into an automated runner that executes tasks end-to-end.

How this skill works

The runner authenticates with Linear MCP, resolves the target project, and fetches open issues in order. For each issue it launches a Codex process (configurable executable and args), monitors execution, records success or failure, and advances the issue on completion. The workflow supports retries, limits on tasks, and dry-run mode to validate configuration without executing Codex.

When to use it

  • Automating execution of Linear project issues with minimal manual intervention
  • Running sequential Codex agents against a scoped backlog
  • Continuously advancing issues after Codex completes tasks
  • Testing runner configuration with dry-run before full execution
  • Limiting runs with max-tasks or enforcing max attempts per issue

Best practices

  • Ensure `codex` is on the PATH and reachable from your environment
  • Authenticate Linear MCP beforehand using `codex mcp login linear`
  • Start with --dry-run to confirm project resolution and AGENTS.MD settings
  • Set sensible `--codex-timeout` and `--max-attempts-per-task` to avoid runaway runs
  • Log outputs to an explicit `--log-path` so you can audit progress and failures

Example use cases

  • Process a VisionOS feature backlog by running Codex against each Linear issue sequentially
  • Automate repetitive maintenance tasks tracked in a Linear project and advance completed items
  • Limit a pilot run with `--max-tasks 3` to validate agent behavior before scaling
  • Run with alternative Codex args to test different agent models or safety modes
  • Use `--dry-run` in CI to verify project connectivity and AGENTS.MD parsing

FAQ

What are the mandatory prerequisites?

Codex must be installed and on PATH, and Linear MCP must be authenticated via `codex mcp login linear`. Provide the project via --project or configure it in AGENTS.MD.

How do I stop a long-running Codex task?

Set `--codex-timeout` to a nonzero number of seconds so the runner will kill Codex after that interval. Use `0` for unlimited.

Can I limit how many issues are processed in one run?

Yes. Use `--max-tasks` to cap issues processed in a single invocation; `0` means unlimited.