ludi-agent-kit

日本語版 README

A Windows-first kit for planning, running, and checking AI coding work with Pi. Agents ask for capabilities rather than specific models; routing and the Pi adapter select the available provider/model. The kit also includes reusable skills, agent roles, a bounded Context Pack format, and a persistent orchestrator. It succeeds the frozen codex-setting project.

Start safely: installation does not configure credentials or working model bindings. Preview a plan before a live run; live agents can use provider quota and may change files when explicitly allowed.

Choose your starting point

| I want to… | Go to… | | --- | --- | | Install for Pi and bind models | Getting started · 日本語 | | Work from a source checkout | Source checkout | | Preview, start, or resume a run | Orchestrator guide | | Understand routing and model bindings | Architecture · Pi adapter | | Prepare a package release | Distribution checklist |

Install for Pi

pi install npm:@ludi-uni/ludi-agent-kit
pi list

This registers the pi-workflow, project-management, and visual-verification skills and the loop guard and ludi_orchestrate extensions. The separate pi-subagents package and its agent roles are not installed automatically. npm install alone does not register Pi resources; use pi install. A Git install is also available: pi install git:github.com/ludi-uni/ludi-agent-kit.

Before live execution, configure the user-level model bindings using IDs actually shown by pi --list-models. The repository's adapters/pi/models.json is a template, not proof of authentication, quota, availability, or price. Review extensions before enabling them: they run with your Pi process permissions. Restart Pi after updating an installed package.

Preview from a source checkout

node scripts/validate.mjs
node scripts/orchestrate.mjs --dry-run "Fix the failing test"

The default rules-based preview does not launch agents. For a live run, read the execution modes and safety rules first; --apply permits the coder pipeline to edit the selected repository. Persistent runs can be inspected with node scripts/orchestrate.mjs --list and --show <run-id>. Source-checkout requirements and the full local test command are in Getting started.

How the pieces connect

flowchart TD
    U[User request] --> P[Planner: goal and acceptance criteria]
    P --> G[Task graph: focused work and dependencies]
    G --> R[Runner: agent role and capability]
    R --> M[Routing: backend and bound model]
    M --> E[Execution and structured evidence]
    E --> V[Evaluator and progress tracking]
    V --> D{Execution Manager decision}
    D -->|continue / split / safe retry / bounded extension| G
    D -->|free or included route, when permitted| M
    D -->|review| Q[Findings and acceptance ledger]
    Q -->|focused repair / reverify / replan| G
    Q --> C{Completion gate}
    C -->|criteria satisfied; no blocking findings or pending approval| Done[Completed run]
    D -->|cost, safety, or user decision required| Stop[Approval or blocked: no automatic paid route]
    C -->|unverified or unresolved| Stop
    E -. run, task, decision, and trace history .-> DB[(SQLite persistence)]
    Q -. finding and evidence history .-> DB

The diagram is an overview, not a promise that every run takes every branch. The parent orchestrator keeps the goal and acceptance identities, chooses bounded next actions, and records decisions. A Context Pack can pass relevant, validated context to a worker instead of the entire repository. Evidence may complete an evidence-based task without a new file diff; tasks explicitly requiring a code change still need one. Completion depends on acceptance and review evidence, not merely the number of finished tasks. See the orchestrator guide for modes and limits.

Repository map

| Path | Responsibility | | --- | --- | | rules/, skills/, agents/ | Shared operating guidance, skills, and role definitions | | routing/ | Capability → logical backend routes and escalation ladders | | adapters/pi/ | Pi-specific model bindings, extensions, templates, and optional sync script | | context-pack/ | Bounded handoff contract and examples | | lib/orchestrator/, orchestration/ | Task evaluation, execution decisions, persistence, and policy | | scripts/, tests/ | CLI tools and checks |

Shared knowledge stays backend-neutral; provider-, model-, CLI-, and installation-specific configuration belongs under adapters/<backend>/. For scope and limitations see the roadmap. External tools retain their own terms (third-party dependencies). This repository is MIT-licensed (LICENSE).