ralpi/AGENTS.md

AGENTS.md

What this is

A Pi coding agent extension that registers the /ralpi slash command. Not a standalone app — it runs inside Pi's extension host.

Type checking

npm run typecheck    # tsc --noEmit

No build step needed — Pi loads extensions via 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).

Source structure

• index.ts — extension entry, command routing, UI registration, reload detection
• src/ — all logic modules:
  • parser.ts — task file parsing (Fio, checkbox, YAML formats)
  • dag.ts — Kahn's algorithm dependency resolution, batch planning
  • executor.ts — task execution, retry, parallel/sequential modes
  • progress.ts — .ralpi/progress.json state management
  • prompts.ts — prompt generation for spawned agent sessions
  • reflection.ts — reflection extraction from agent output
  • utils.ts — config loading, progress discovery, runAgentSession()
  • types.ts — all interfaces and DEFAULT_CONFIG
  • widget-batcher.ts — debounced widget updates for parallel tasks
  • constants.ts — static constants
• 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/reflections/ — per-task reflection JSON files
• .ralpi/prompts/ — generated prompts (timestamped, for debugging)
• .ralpi/sessions/ — full session transcripts

Task ID convention

Task IDs are zero-padded strings ("01", "02", etc.). The parser prepends 0 to parsed digits. Never use raw numeric IDs.

Command routing

/ralpi with no args → plan. First token looks like a path (@path, ./path, .md, etc.) → run. Otherwise dispatches to subcommand (run, plan, resume, reset).

Config

Read from .ralpi/config.yaml in project directory. Falls back to DEFAULT_CONFIG in src/types.ts when file is missing. Config is loaded at projectDir level, not extension level.