# AGENTS.md

## What this is

A Pi coding agent extension that registers the `/ralpi` slash commands
(`/ralpi`, `/ralpi-run`, `/ralpi-plan`, `/ralpi-resume`, `/ralpi-reset`).
Not a standalone app — it runs inside Pi's extension host.

## Type checking

```
npm run typecheck    # tsc --noEmit
```

Tests: `bun test` (parser and DAG suites in `tests/`).

No build step needed — Pi loads extensions via [jiti](https://github.com/unjs/jiti), which compiles TypeScript at runtime. `index.ts` is the entry point directly.

## Entry point

`index.ts` at repo root (not `src/`). Exports a default function receiving `ExtensionAPI`.

## External dependencies

The extension imports from Pi SDK packages (not in `package.json` — provided by the host):

- `@earendil-works/pi-coding-agent` — `ExtensionAPI`, `ExtensionContext`, `createAgentSession`, etc.
- `@earendil-works/pi-tui` — `Box`, `Text` for custom message renderer

The only real npm dependency is `yaml` (^2.4.0). It is used for parsing YAML
task files (`src/parser.ts`) and config files (`parseSimpleYaml` in
`src/utils.ts`, which falls back to a flat key:value parser when the package
is unavailable).

## Source structure

- `index.ts` — extension entry, command registration (`ralpi`, `ralpi-run`,
  `ralpi-plan`, `ralpi-resume`, `ralpi-reset`), execution-mode + loop-option
  prompts, reload auto-resume via `session_start`, progress message renderer
- `src/` — all logic modules:
  - `parser.ts` — task file parsing (Fio/README numbered, phased, checkbox,
    YAML formats), dependency + parallel-group + timeout parsing,
    `updateTaskInFile()` for PRD checkbox updates
  - `dag.ts` — Kahn's algorithm dependency resolution, group-aware batching,
    cycle detection, sequential/parallel plan builders
  - `executor.ts` — task execution, parallel/sequential modes, model
    round-robin + failover, review-gated loop, worktree orchestration,
    batch-level conflict resolution
  - `review.ts` — review verdict extraction (`## REVIEW VERDICT`), review
    save/load to `.ralpi/reviews/`
  - `worktree.ts` — git worktree create/merge/cleanup helpers, stale-worktree
    cleanup, `finalizeCommittedWorktrees()`
  - `progress.ts` — `.ralpi/progress.json` state management (multi-PRD)
  - `prompts.ts` — prompt generation for spawned agent sessions
  - `reflection.ts` — reflection extraction from agent output
  - `utils.ts` — config loading, progress/PRD discovery, `runAgentSession()`,
    model resolution (`resolveModelSpec`), loop-active marker
  - `types.ts` — all interfaces and `DEFAULT_CONFIG`
  - `widget-batcher.ts` — debounced widget updates for parallel tasks
  - `task-manager-prompt.ts` — loads and expands the bundled
    `prompts/task-manager.md` template for `/ralpi-plan`
  - `constants.ts` — static constants (slash command, task file names,
    reflection/review patterns)
- `tests/` — bun test suites for parser and DAG behavior
- `skills/ralpi-use.md` — Pi skill definition for task execution
- `prompts/task-manager.md` — Pi prompt for task planning

## Runtime state

All runtime state lives in `.ralpi/` in the **project directory** (not this extension directory):

- `.ralpi/progress.json` — execution progress, supports multiple PRDs
- `.ralpi/loop-active.json` — marker written while a loop runs; drives
  auto-resume after a session reload
- `.ralpi/reflections/` — per-task reflection JSON files
- `.ralpi/reviews/<prdKey>/` — full review output JSON (only when
  `saveReviews` is on)
- `.ralpi/prompts/` — generated prompts (timestamped, for debugging)
- `.ralpi/config.yaml` — project-level config (optional)

There is no `.ralpi/sessions/` directory anymore — full task output is shown
inline via expandable `ralpi-progress` chat messages, and review output is
persisted under `.ralpi/reviews/`.

## Task ID convention

Task IDs are zero-padded strings (`"01"`, `"02"`, etc.) with an optional
single lowercase letter suffix for sub-tasks (`"02b"`, `"02c"`). The parser
normalizes `2b` → `02b` (see `normalizeTaskId` in `src/parser.ts`). Never
use raw numeric IDs.

## Command routing

- `/ralpi` — no args → show plan for `README.md`; first token looks like a
  path (`@path`, `./path`, `.md`, `.yaml`, etc.) → run; anything else →
  error suggesting the dash commands
- `/ralpi-run [task-file]` — run tasks (auto-resumes when progress already
  exists for the file; otherwise prompts for execution mode + loop options)
- `/ralpi-plan [prompt]` — loads the bundled `prompts/task-manager.md`
  template and sends it as a user message. Pi's `sendUserMessage()` sends
  with `expandPromptTemplates: false`, so the extension does its own
  frontmatter stripping and `$@`/`$1` arg substitution
  (`loadTaskManagerPrompt` in `src/task-manager-prompt.ts`)
- `/ralpi-resume [task-file]` — resume from persisted progress; prompts for
  the PRD when multiple loops have progress. Reuses the loop snapshot in
  `loop-active.json` (mode + autoCommit/autoReview/saveReviews) to resume
  non-interactively
- `/ralpi-reset [task-file]` — reset execution progress (does not modify the PRD)

The old `/ralpi plan|resume|reset` subcommand dispatch, plus `status` and
`next`, were removed.

## Config

Read from `.ralpi/config.yaml` in project directory (and global
`~/.pi/ralpi/config.yaml`), project overrides global. Falls back to
`DEFAULT_CONFIG` in `src/types.ts` when files are missing. Config is loaded
at `projectDir` level, not extension level. Execution keys explicitly
present in a loaded YAML are tracked in `execution.explicitKeys` so the
loop-startup interactive prompts (`selectLoopOptions` in `index.ts`) can be
skipped for fields the user already set.

Key config fields in `execution`:

- `autoCommit` / `autoReview` / `saveReviews` — loop options (selectable at
  loop startup via `selectLoopOptions`; review is asked FIRST, commit is
  mandated when review is on)
- `models` — slot-aware round-robin model list for parallel mode, with
  automatic failover to the next model per task
- `implModel` / `commitModel` / `reviewModel` — `<provider>/<model>` strings
  resolved via `resolveModelSpec` in `utils.ts`
- `maxReviewRetries` / `reviewBlockOnFail` — review-gated loop retry behavior
- `worktrees` — `"never" | "parallel" | "always"` git worktree isolation
  (default `"parallel"`; see `shouldUseWorktrees` in `src/executor.ts`)
- `commitTimeoutMs` / `reviewTimeoutMs` — timeouts for follow-up sessions
- `loopTimeoutMs` — max total loop duration in ms (0 = no limit; checked
  between batches in `executePlanBatches`)
- `timeoutMs` — per-task execution timeout
- `prompts.projectContext` / `prompts.reflectionPrompt` — prompt-level settings