<!--
Plan to Code Async
Part of the Bles Software agent skills repository:
https://www.bles-software.com/claude-skills

Install for Claude Code:
  mkdir -p ~/.claude/skills/plan-to-code-async
  mv plan-to-code-async.md ~/.claude/skills/plan-to-code-async/SKILL.md

Install for Codex:
  mkdir -p ~/.codex/skills/plan-to-code-async
  mv plan-to-code-async.md ~/.codex/skills/plan-to-code-async/SKILL.md

For Gemini CLI and other agents, drop the body of this file into the
project instruction file the agent already reads.

Note: in production this skill also ships 2 helper file(s) alongside
SKILL.md. The procedure below is complete and self-contained; the helpers are
convenience scripts you can rebuild from the steps described here.
-->

---
name: plan-to-code-async
description: |
  Orchestrate large multi-part development projects autonomously.
  Takes a development task file (produced by /build-plan-doc-and-tasks), breaks it into
  ordered tasks with dependencies, and executes each part via Claude with self-healing,
  testing, and Telegram updates.
  Use when user wants to build a big project, run a dev loop, execute a multi-part plan,
  or automate a development document into working code.
  ALWAYS run /build-plan-doc-and-tasks first to generate the task file.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# plan-to-code-async — Autonomous Development Orchestrator

> **START HERE**: Before running this skill, run `/build-plan-doc-and-tasks` first.
> It will interview you about the project and produce the `dev-tasks.json` this skill needs.
>
> **Flow**: `/build-plan-doc-and-tasks` → `dev-tasks.json` → `/plan-to-code-async`

Turns a structured task file into working code, part by part, with
self-healing, dependency management, testing, and real-time Telegram progress.

## Quick Start

### 1. Generate the task file first

Run `/build-plan-doc-and-tasks` and provide your project description.
It will produce a `dev-tasks.json` file ready to use here.

Alternatively, create `dev-tasks.json` manually:

```json
{
  "project": "Project Name",
  "source_document": "path/to/implementation-doc.md",
  "project_root": "/absolute/path/to/project",
  "test_framework": "pytest",
  "created_at": "2026-02-20",
  "status": "pending",
  "instructions": "Project-specific instructions for Claude (patterns, constraints, env vars)",
  "tasks": [
    {
      "id": "1-task-slug",
      "step": 1,
      "title": "Short Task Title",
      "description": "Detailed description of what to implement",
      "files_to_create": ["path/to/new_file.py"],
      "files_to_modify": ["path/to/existing_file.py"],
      "test_file": "tests/test_new_file.py",
      "depends_on": [],
      "status": "pending",
      "attempts": 0,
      "errors": []
    }
  ]
}
```

### 2. Launch the dev loop

```bash
# Full launch (watchdog + dev loop + Telegram updates)
~/.claude/skills/plan-to-code-async/scripts/launch.sh /path/to/dev-tasks.json

# Check status
~/.claude/skills/plan-to-code-async/scripts/launch.sh /path/to/dev-tasks.json --status

# Stop everything
~/.claude/skills/plan-to-code-async/scripts/launch.sh /path/to/dev-tasks.json --stop

# Dry run (show task order)
~/.claude/skills/plan-to-code-async/scripts/launch.sh /path/to/dev-tasks.json --dry-run

# Run single task
~/.claude/skills/plan-to-code-async/scripts/dev-loop.sh /path/to/dev-tasks.json --task 1-task-slug
```

## Architecture

```
┌─────────────────────────────────────────────────┐
│ Layer 1: LAUNCHER (launch.sh)                   │
│  Validates prerequisites, starts watchdog       │
└─────────────────────────────────────────────────┘
                      |
┌─────────────────────────────────────────────────┐
│ Layer 2: WATCHDOG (dev-watchdog.sh)             │
│  Checks every 60s, restarts on crash,           │
│  alerts on stuck tasks, exits when done         │
└─────────────────────────────────────────────────┘
                      |
┌─────────────────────────────────────────────────┐
│ Layer 3: DEV LOOP (dev-loop.sh)                 │
│  Per task: spawn Claude -> verify -> test ->    │
│  self-heal (2x) -> mark complete/failed         │
│  Telegram updates after each task               │
└─────────────────────────────────────────────────┘
```

## Task File Reference

| Field | Required | Description |
|-------|----------|-------------|
| `project` | Yes | Project name (used in Telegram messages) |
| `project_root` | Yes | Absolute path to project root |
| `source_document` | No | Path to implementation doc (relative to project_root) |
| `test_framework` | No | `pytest` (default), `vitest`, `jest`, `go test`, `cargo test` |
| `instructions` | No | Project-specific Claude instructions |
| `tasks[].id` | Yes | Unique task ID (slug format) |
| `tasks[].step` | Yes | Execution order number |
| `tasks[].title` | Yes | Human-readable title |
| `tasks[].description` | Yes | What Claude should implement |
| `tasks[].files_to_create` | No | New files to create |
| `tasks[].files_to_modify` | No | Existing files to modify |
| `tasks[].test_file` | No | Test file to verify task |
| `tasks[].depends_on` | No | Task IDs that must complete first |

## Configuration

Timeouts and limits are configurable via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_TIMEOUT` | 1800 | Seconds per task (30 min) |
| `TEST_TIMEOUT` | 120 | Seconds for test run |
| `MAX_ATTEMPTS` | 5 | Max retries per task |
| `MAX_FIX_ATTEMPTS` | 2 | Self-healing attempts per failure |
| `CHECK_INTERVAL` | 60 | Watchdog check frequency |
| `STUCK_THRESHOLD` | 1800 | Seconds before stuck alert |

## Telegram Notifications

If `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are set (in `.env.telegram` at project_root
or as env vars), the system sends:

- Task started / completed / failed / retrying
- Progress counter (N/M complete)
- Watchdog alerts (crash, stuck, restart)
- Final "all done" message

## Generating Tasks from a Document or Idea

Use `/build-plan-doc-and-tasks` to do this automatically. That skill will:

1. Interview you about the project
2. Create a planning document
3. Break it into ordered tasks with dependencies
4. Write the `dev-tasks.json` ready to pass to this skill

Then come back here and run `launch.sh` with that file.

## Proven Results

This system built Darwin GM v3.0 (15 tasks, 12 Python modules, full test suite)
autonomously in a single session with self-healing. Production-grade and battle-tested.