From 479bb55d2da682a188811015f0c547eff853e937 Mon Sep 17 00:00:00 2001 From: omp-port Date: Tue, 11 Aug 2026 09:20:04 -0400 Subject: [PATCH] port: sync from Mike/ralpi@85438c4a --- README.md | 307 ++---------------------------------------------------- 1 file changed, 7 insertions(+), 300 deletions(-) diff --git a/README.md b/README.md index b14edd9..f962454 100644 --- a/README.md +++ b/README.md @@ -1,304 +1,11 @@ -# Ralpi +# ralpi (omp port) -Execute tasks from task files until done using DAG-based dependency resolution with persistent progress tracking. +Execute tasks from task files using DAG-based dependency resolution. -```bash -# omp auto-discovers extensions in ~/.omp/agent/extensions// -git clone ~/.omp/agent/extensions/ralpi/ +## Install + +```sh +omp install @mikefreno/omp-ralpi ``` -## Features - -- **DAG-based execution**: Tasks ordered via dependencies (arrow notation, natural language, "must be done before", or YAML) -- **Parallel batching**: Independent tasks in each batch run concurrently, round-robin across configured models -- **Persistent progress**: Execution state saved to `.ralpi/progress.json`, supporting multiple PRDs simultaneously -- **Resume & auto-resume**: `/ralpi-resume` continues paused execution; a session reload mid-loop auto-resumes via `.ralpi/loop-active.json` -- **Reflection system**: Each task produces a reflection for downstream tasks -- **Phased plans**: `## Phase N — Title` sections add implicit phase-boundary dependencies -- **Model failover**: Unreachable providers cycle to the next model in the list before a task fails -- **Auto-commit / auto-review loop**: Optional per-task commit and review-gated re-execution until pass -- **Worktree isolation**: Parallel tasks run in separate git worktrees so they can't stomp each other, with batch-level merge-conflict resolution -- **Multiple formats**: Fio README (numbered + dependencies), phased, simple checkboxes, and YAML -- **Tool usage tracking**: Reports read/write/edit/bash usage from task execution -- **Configurable timeouts**: Task-level timeouts (inline, meta block, or YAML) with global fallback - -## Usage - -``` -/ralpi [task-file] # No args → show plan for README.md; path arg → run tasks -/ralpi-run [task-file] # Execute tasks from a task file -/ralpi-plan [prompt] # Open the Task Manager to plan tasks -/ralpi-resume [task-file] # Resume paused/interrupted execution -/ralpi-reset [task-file] # Reset execution progress — does not modify the PRD -``` - -`/ralpi` with no arguments shows the execution plan for the default task file. When the first token looks like a path (`@path`, `./path`, `path/file.md`, `.yaml`, etc.) it routes to `/ralpi-run`. Everything else is handled by the dedicated dash commands above (the old `/ralpi plan|resume|reset` subcommand syntax is gone). - -> The task-manager prompt (`/ralpi-plan`) pairs perfectly with ralpi's task file formats — use it for PRD construction. - -## Tasks - -### Simple Checkbox Format - -```markdown -- [ ] Setup project structure -- [ ] Implement auth -- [ ] Build API -``` - -Checkbox-only files get sequential IDs (`01`, `02`, ...). Status characters: `[ ]` pending, `[x]` done, `[~]` in progress, `[!]` failed, `[-]` skipped. - -### Fio Format (numbered tasks + dependencies) - -```markdown -# Build a web application - -## Tasks - -- [ ] 01 — Setup project structure -- [ ] 02 — Implement auth -- [ ] 03 — Build API - -## Dependencies - -01 -> 02, 03 -``` - -### YAML Format - -```yaml -objective: Build a web application -tasks: - - id: "01" - title: Setup project structure - file: tasks/01-setup.md - dependencies: [] - - id: "02" - title: Implement auth - file: tasks/02-auth.md - depends_on: ["01"] -``` - -## Task IDs - -Task IDs are zero-padded 2-digit strings (`01`, `02`, ...) with an optional -single lowercase letter suffix for sub-tasks inserted between two numbered -steps (e.g. `02b`, `02c`). The parser normalizes `2b` → `02b`. - -``` -- [ ] 01 — Setup -- [ ] 02 — Fix bugs -- [ ] 02b — Sub-step of 02 (inserted after the fact) -- [ ] 02c — Another sub-step of 02 -- [ ] 03 — Continue -``` - -Use lettered sub-tasks when you discover mid-stream that a step needs to be -split. They let you preserve sibling numbering (`01`, `02`, `03`, ...) while -adding granularity between two existing steps. - -## Phases - -`## Phase N — Title` headings group tasks into phases and add an implicit -dependency from the first task of each phase to the last task of the -previous one, so phases always run in order: - -```markdown -## Phase 1 — Push-to-Talk MVP - -- [ ] 01 — Voice capture -- [ ] 02 — Transmission - -## Phase 2 — Group Chat - -- [ ] 03 — Channels -- [ ] 04 — Presence -``` - -## Dependencies - -Dependency lines live in a `## Dependencies` section (or a plain -`Dependencies` heading). Multiple formats are supported and can be mixed. - -### Arrow Notation (recommended) - -``` -1 -> 2,3,4 -5 -> 6 -``` - -"Task 1 must complete before tasks 2, 3, and 4 can start." Also supports -chains (`03 -> 04 -> 05`) and multi-prereq sources (`05, 07, 08 -> 13`). - -### Natural Language - -``` -13 depends on 17, 18, 19, 20 -14 depends on 13, 15, 16 -22, 23, 24 depend on 21 -``` - -"Task 13 depends on tasks 17, 18, 19, and 20." `also depends on` is accepted. - -### "must be done before" - -``` -21 must be done before 22, 23, 24 -02, 03 must be done before 04 -``` - -### Parallel Groups - -``` -1, 2, 3, 4 can be done in parallel (Play Store prep) -5, 6, 7, 8 can be done in parallel -``` - -Tasks listed in a parallel group are allowed to run concurrently. Group -declarations imply no cross-group dependencies, and intra-group -dependencies are still respected — group-aware batching produces a plan -where tasks from any group run as soon as their dependencies are -satisfied. - -## Configuration - -### Task-Level Timeout - -Timeouts can be set inline on the task line, as an inline comment, via a -meta block in the Dependencies section, or in YAML: - -```markdown -- [ ] 01 — Setup project structure timeout: 10m -- [ ] 02 — Implement auth # timeout=30s -``` - -```markdown -## Dependencies - -01 -> 02 -01 [timeout] = 10m -``` - -```yaml -tasks: - - id: "01" - title: Setup project structure - timeout: 15m -``` - -Supported units: `m` / `min` (minutes), `s` (seconds), `ms` (milliseconds). -Bare numbers default to minutes; in YAML, numeric values ≥ 1000 are treated -as milliseconds. - -### Config files - -| Scope | Path | -|-------|------| -| **Global** | `~/.omp/ralpi/config.yaml` | -| **Project** | `./.ralpi/config.yaml` | - -Project config overrides global, which overrides defaults. Keys set -explicitly in YAML skip the corresponding loop-startup prompt. - -```yaml -execution: - maxParallel: 3 # ralpi-level concurrency only (0 = unlimited) - models: # round-robin for parallel tasks, / - - anthropic/claude-sonnet-4 - - openai/gpt-4o - autoCommit: true # commit after each task (mandated when autoReview is on) - autoReview: false # commit → review → loop on fail → merge on pass - saveReviews: false # persist full review output to .ralpi/reviews/ (only with autoReview) - maxReviewRetries: 2 # re-executions on a 'fail' verdict before giving up - reviewBlockOnFail: false # true = mark task failed after retries exhausted instead of merging - implModel: "" # model for task impl (empty = inherit parent session model) - commitModel: "" # model for commit sessions (empty = inherit task model) - reviewModel: "" # model for review sessions (empty = inherit task model) - timeoutMs: 0 # per-task timeout in ms (0 = inherit Pi's defaults) - commitTimeoutMs: 0 # timeout for auto-commit agent sessions (0 = inherit) - reviewTimeoutMs: 0 # timeout for auto-review agent sessions (0 = inherit) - loopTimeoutMs: 0 # max total loop duration in ms (0 = no limit; checked between batches) - worktrees: parallel # "never" | "parallel" (default) | "always" — git worktree isolation - chatStyle: compact # "compact" (default) | "verbose" — per-event tool-call stream -prompts: - projectContext: "Additional context for all tasks" - reflectionPrompt: "" # custom suffix for reflection extraction - reviewFocus: "" # per-review custom focus/instructions (e.g. "check security only") -review: - extraIgnorePatterns: [] # extra noise-filter exclusion regexes (merged into the default rules) - ignorePaths: [] # pathspec allowlist — files matching these stay in review scope -``` - -Review prompts (committed + uncommitted) run the diff through a noise filter -before inlining: lockfiles, minified/generated assets, source maps, -snapshots, build output, `node_modules`/`vendor`, and binary/media files are -excluded by default. The prompt gets a per-file `+/−` summary table, an -`### Excluded Files (n)` section listing what was filtered (path, counts, -reason), and — when a diff is oversized or touches >20 files — a -file-list + "use `read`" instruction instead of a byte-truncated diff. -`prompts.reviewFocus` injects a `### Custom Review Focus` section into each -review prompt. `review.extraIgnorePatterns` adds exclusion regexes (matched -against file paths), and `review.ignorePaths` is a pathspec allowlist that -keeps matching files in review scope even when a default rule would exclude -them. - -> `execution.models` uses slot-aware round-robin: with 3 models and 2 concurrent -> tasks, only the first two models are used. The third model is only touched when -> a third concurrent task starts. Freed model slots are reused before new ones -> are allocated. -> **Automatic failover**: if a provider/API is unreachable (rate limit, 503, etc.), -> the task automatically cycles to the next model in the list without counting it -> as a task failure. Each model is tried once before the task is marked as failed. -> **NOTE**: model lists are only used in parallel execution. In sequential mode -> (or parallel mode with no `models` list) the parent pi session's model is used, -> unless `implModel` is set. - -> `execution.chatStyle` controls how sub-agent tool calls appear in the chat during task execution: -> - **compact** (default): a single completion message per task with an expandable tool-call tree (collapsed shows the last 3 calls, expanded via Ctrl+O shows all). -> - **verbose**: each tool event is streamed live as its own chat line (`[01 · task-name] → bash ...` / `← (ok)`), like piolium/pygienium's per-event stream. - -#### Auto-review and Auto-commit - -At loop startup the review question is asked FIRST. When `autoReview` is -enabled, commit is **mandated** — after task execution, changes are -committed (via a commit agent session when the task agent didn't -self-commit), then the complete task diff (`baseRef..HEAD`) is reviewed -against the task description. On a `fail` verdict the task is -re-executed with the review feedback injected into the prompt (looping -until the review passes or `maxReviewRetries` is exhausted). After -re-execution, changes are committed again and the full diff is -re-reviewed with the same base ref so the reviewer sees the complete -state — original work plus fixes. On pass, the changes are already -committed and the worktree merges. - -When `autoReview` is disabled, `autoCommit` runs a follow-up commit -agent after each task with no review. With `autoReview` on, the user is -also asked whether to persist full review output to -`.ralpi/reviews//.json` (`saveReviews` — this is what -enables review feedback recovery when resuming interrupted loops). Both -options can be overridden at loop startup via a selection prompt (config -YAML values are honored without prompting when set explicitly). - -`commitModel` and `reviewModel` accept `/` strings (e.g. -`anthropic/claude-sonnet-4`) resolved via the model registry. When empty, the -task's model is inherited. `implModel` sets the model for task implementation -(used whenever no round-robin model is assigned — sequential mode, or parallel -mode with an empty `models` list; overridden by `execution.models` round-robin -in parallel mode). - -## State Files - -``` -.ralpi/progress.json # Execution progress (supports multiple PRDs) -.ralpi/loop-active.json # Active-loop marker used for auto-resume after a reload -.ralpi/reflections/ # Per-task reflections -.ralpi/reviews// # Full review output (when saveReviews is on) -.ralpi/prompts/ # Generated prompts (timestamped, for debugging) -.ralpi/config.yaml # Project-level config (optional) -``` - -Every `/ralpi run`, `/ralpi resume`, and `/ralpi reset` (plus the auto-resume -on session reload) ensures `.ralpi/` is present in the project's `.gitignore`, -so ralpi's own artifacts never show up as untracked/staged files in the user's -repo. Opt out per command with `--no-gitignore` (e.g. `/ralpi-run README.md ---no-gitignore`). +This is the omp port of [Mike/ralpi](https://git.freno.me/Mike/ralpi), regenerated automatically from the source repo. See the source repo for full documentation.