Groundwork

Workflow plugin for AI coding agents providing structured development practices: interview-driven planning, vertical-slice fan-out enforced by a run ledger and Stop-gate hook, advisor gates, and context management.

• Pi — Install via pi install git:github.com/IniZio/groundwork
• Claude Code — Install via /plugin (.claude-plugin/plugin.json)
• omp (Oh My Pi) — Install via omp plugin link / omp plugin install
• Codex — Install from the Codex plugin directory (.codex-plugin/plugin.json)

pi install git:github.com/IniZio/groundwork

Groundwork ships a .claude-plugin/plugin.json manifest (skills, agents, and the orchestrator CLAUDE.md via claudeMd). Add the marketplace and install:

/plugin marketplace add IniZio/groundwork
/plugin install groundwork@groundwork

omp recognizes the pi.extensions manifest in package.json and loads pi/pi.ts, which injects the orchestrator identity at session start. Link a local checkout (symlink, live-updates) or install a copy:

omp plugin link ./path/to/groundwork      # dev: symlink, tracks source
omp plugin install ./path/to/groundwork   # release: copy

Verify: omp plugin list should show groundwork@<version>.

Groundwork follows the native Codex plugin layout used by plugins such as Superpowers: .codex-plugin/plugin.json at the repository root and one skill directory per workflow directly under skills/. Open Codex's plugin directory (/plugins), search for Groundwork, and install it from the marketplace.

The direct Codex skill directories are generated from the canonical skills/groundwork/ tree by pnpm run generate:agents.

Restart your agent. Skills auto-discover.

Groundwork skills provide workflow instructions; they do not automatically add runtime tools to the host agent. The available runtime surface depends on the host platform.

For Codex specifically, installing this plugin makes the skills discoverable, but does not automatically install fan-out tools, handoff orchestration, or enforcement hooks. Codex handoff is intentionally file-only: the skill writes an artifact the user can review and provide to a later session.

1. Issue-type routing: bug → diagnose, small change → interview + implement, feature → interview → vertical-slice (writes the run ledger) → fan out general-purpose agents → advisor gate
2. Advisor gate before declaring done; recorded in the run ledger and enforced by the Stop-gate hook
3. Intent lives in a motive charter at .groundwork/motives/<slug>/motive.md with a compiled Decision Log; charters are runtime state and are not committed
4. Interview before slicing — understanding before synthesis

Each motive maintains a human-readable MAP at .groundwork/motives/<slug>/MAP.md. It is auto-regenerated and shows the motive's slices and progress in prose form. Open this file to review progress without running any CLI commands.

The ledger and journal CLIs (bin/ledger, bin/journal) are the implementation detail behind the MAP — they mutate run state; the MAP surfaces it for humans.

Non-trivial runs are tracked in a per-session ledger the Stop-gate hook (hooks/stop-gate.mjs) enforces. Legacy .groundwork/run.json is still honored for in-flight runs. Key fields:

• slices[].blocked_by — canonical wave-ordering dependency (depends_on is a legacy alias); a slice can't be marked complete until its blockers are.
• slices[].acceptance — string[] of checkbox-style, verifiable done-conditions; the Stop-gate surfaces unmet counts.
• gate.advisor — accepts the legacy string (APPROVE/REVISE/REJECT) or an object { verdict, rubric, axes: { correctness, completeness, over_engineering }, citation } (axes scored 0–3). The run is approved when the string or verdict is APPROVE.

The advisor gate scores correctness / completeness / over-engineering as independent axes, requires a concrete citation on any non-approval, and self-tests before recording a verdict.

Rejection KB — .groundwork/out-of-scope/<concept-slug>.md: one durable file per rejected concept (reasoning + a Prior requests list), scanned at triage to dedup repeat asks by concept rather than re-litigating a settled "no".

pnpm install
pnpm test        # run tests
pnpm run check   # typecheck

When using Pi with pi-subagents, the following agent types are auto-configured:

• src/ — shared TypeScript source (src/lib/, src/runtime.ts)
• pi/pi.ts — Pi extension entry point (compiled-TS; the one platform that is source, not a static .<platform>-plugin/ manifest)
• pi/pi-commands/, pi/pi-tools/ — Pi-only commands and tools
• .pi/skills/ — Pi skill definitions
• .codex-plugin/plugin.json — Codex plugin manifest