pi-adx-workflow
Declarative plan → build → verify → review workflow for pi-coding-agent, with in-house isolated sub-agents and never-stop auto-continue.
Package details
Install pi-adx-workflow from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-adx-workflow- Package
pi-adx-workflow- Version
1.2.0- Published
- Nov 14, 2026
- Downloads
- 938/mo · 482/wk
- Author
- mossaab1
- License
- MIT
- Types
- extension
- Size
- 248.6 KB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"extensions": [
"./src/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-adx-workflow
plan → build/verify → review → summarize workflow for
pi-coding-agent, built as a pi extension with
in-house sub-agent propagation: flow children (verifier / code reviewer)
run as isolated pi -p child processes — no pi-subagents dependency.
It implements a complete working method:
- Plan mode (read-only) — the planner explores and proposes acceptance
criteria (
flow_meta, keycriteria, statuspending). - Build mode — you approve, then
/adx-runstarts the workflow: the builder implements and marks criteriacompleted. - Verify loop — an isolated verifier sub-agent (fresh
pi -pchild session) checks each criterion and setspassed/failed. Failures send the builder back with a nudge carrying the verifier's findings. - Code review — an isolated code reviewer sub-agent reviews the git
diff and raises
review_findings. - Finalize loop — the builder must resolve or dismiss every finding.
- Summarize — final report + a "What to test" mini-tutorial.
The whole run is a declarative state machine: steps, ordered transitions,
metadata conditions, nudge re-entry, maxIterations safety cap,
$blocked handling, and persistence/resume.
Contents
- Requirements
- Install
- Usage
- Configuration
- Never-stop (auto-continue)
- Tools
- Sub-agents
- Workflows
- Development
- Contributing
- Troubleshooting
- Project layout
- License
Requirements
- pi-coding-agent ≥ 1.5 (the
piCLI is resolved from~/.pi/agent/bin/pi,ADX_PI_BIN, orPATH) - Node ≥ 22.19 (pi's own engine requirement)
pi-subagents is not required: children are plain pi -p processes that
load only this extension (child mode), so there is no retained-child state
and no "Agent is already processing" jams.
No npm install is needed for the extension itself: its runtime imports
(typebox, @earendil-works/pi-ai, @earendil-works/pi-coding-agent) are
host-provided — pi maps them to its own copies, so the extension shares
pi's classes and registries (declared as peerDependencies with a * range,
per the pi package conventions).
Install
Recommended: install as a pi package from npm:
pi install npm:pi-adx-workflow
Variants:
# project-local (written to .pi/settings.json, loads after project trust)
pi install --local npm:pi-adx-workflow
# from git (tracks the main branch)
pi install git:github.com/mossaab/pi-adx-workflow
Manage the install:
pi list # show configured packages
pi remove npm:pi-adx-workflow
pi update --extensions # reconcile git checkouts / npm specs
Development install (symlink)
To develop the extension, clone the repo and symlink it into pi's global
extension directory (pi discovers package.json with a pi.extensions
field one level deep):
git clone https://github.com/mossaab/pi-adx-workflow.git
ln -sfn ~/path/to/pi-adx-workflow ~/.pi/agent/extensions/adx-workflow
No build step: pi loads src/index.ts through jiti. If you move the repo,
re-create the symlink.
Usage
/adx-plan enter plan mode (read-only)
/adx-spec [path] enter spec mode (read-only brainstorm/research; writes a spec file, no build)
/adx-spec SPEC.md spec mode with a custom spec location (default: .pi/specs/<slug>.md)
/adx-approve approve the plan/spec: switch to build mode (turn plan/spec mode off, no launch)
/adx-run [workflow] [params] switch to build mode + launch a workflow (default: the configured build one)
/adx-run build-verify switch to build mode + launch the full build-verify workflow
/adx-run build-verify skip_review=true full workflow minus the code review step
/adx-run build-verify commit=true pipeline + commit & push at the end (auto-skips the "Commit changes?" picker)
/adx-run build-verify commit=false pipeline, changes left uncommitted (picker auto-skipped)
/adx-run build-verify commit=true message="feat: ..." commit phase with an explicit commit message
/adx-status show current workflow state
/adx-resume resume a blocked/waiting workflow
/adx-cancel cancel the current run
/adx-config show the effective config ("edit" menu / "set key=value")
Ctrl+Alt+A toggle plan/spec mode (spec mode exits; plan mode toggles)
Auto mode (unattended pipeline)
pi --adx-auto "Add a dark mode toggle: - toggle in settings, - persist to localStorage, - follow system preference"
--adx-auto runs the whole pipeline without any approval:
- Plan — the planner refines the acceptance points you provided into final criteria (no questions, no validation step) and adds them to the store.
- Build — plan mode exits automatically and the build-verify workflow launches (user steps like the work-location and commit pickers are auto-skipped — in auto mode the work is left uncommitted by default).
- Verify → recap — the verifier checks the criteria, then the summary
with "What to test" is printed. The code review step is skipped in auto
mode; use
/adx-run build-verifyfor the full pipeline with review.
Manual mode (/adx-plan + /adx-approve / /adx-run) is unchanged.
When the planner finishes in interactive mode it calls flow_plan_done, which
shows a picker: Build + verify (full pipeline) / Build (simple) /
Choose workspace (current workspace or fresh worktree, then the pipeline) /
Spec only — stop (export the stored criteria as a spec document and stop —
no build is launched).
Spec mode (brainstorm / research, no code)
/adx-spec is the "specs without dev" mode: pure brainstorming, research, and
spec writing — zero coding, zero verification, zero review.
- Read-only workspace — same gating as plan mode (edit/write disabled,
read-only bash allowlist). The single exception is the
spec_writetool, the only write channel: it writes the spec markdown file and nothing else. - Iterative reasoning — the spec agent asks you 1-3 focused questions per
turn (
ask_user), explores the codebase read-only, and researches on the web (web_search,fetch_content,source_check). - Output = a spec document — a markdown file with Context & goal,
Research notes, Decisions & assumptions, and an Acceptance criteria
checklist. Written to
.pi/specs/<slug>.mdby default (auto-generated timestamp slug); pass a path to/adx-spec(e.g./adx-spec SPEC.md) to choose the location.spec_writeis called exactly once, at the end. - No hand-off — after the spec is saved the session simply ends in normal
build mode; nothing is launched, verified, or reviewed. Exit spec mode early
with
/adx-approveor Ctrl+Alt+A (no launch). Spec mode is persisted per session and restored on resume (unfinished spec → continue, then callspec_writeonce).
After a regular plan, the flow_plan_done picker's Spec only — stop
option does the same export: it composes the spec from the stored criteria,
saves it to .pi/specs/<slug>.md, exits plan mode, and launches nothing.
Typical session
/adx-plan- Ask for a feature: "Add a dark mode toggle. Use flow_meta to define the
acceptance criteria." — the planner explores (read-only) and adds
criteria. Review them in the widget (or edit with
flow_meta). /adx-run(quick:build → summarize) or/adx-run build-verify(full:work_location → build → verify → code_review → finalize → summarize). The widget tracks step, iteration, and criterion status; the footer shows a compact status line.- When a criterion fails verification, the builder is nudged with the
verifier's findings and re-enters
builduntil everything ispassed. - The reviewer's findings are dispositioned in
finalize, then the summary with "What to test" is printed.
State lives per pi session in .pi/adx-flow/state/<sessionId>.json
(criteria, findings, execution state, plan-mode and spec-mode flags) — each session has its
own plan, and resuming a session restores exactly that session's plan/run.
New sessions (/new, fork) start 100% clean: no execution is restored and no
step auto-executes — an in-flight run left behind by a previous session stays in
that session's own file and comes back only when you re-resume it. When a resumed
session has no per-session file yet, an in-flight run still in the legacy shared
.pi/adx-flow/state.json (status ≠ done) is adopted into its file once, so
pre-per-session runs keep working — new sessions never touch the legacy file.
Flow sub-agents (verifier / code reviewer) write to the parent's state file
(passed via the ADX_FLOW_STATE env var) so their flow_meta updates land
in the driving session's store. It survives pi restarts — session_start
restores the resumed session's running run (and its plan/spec mode if the session
stopped mid-plan or mid-spec), and /adx-resume continues a blocked one.
Configuration
The user config file is created automatically on first run with all defaults, ready to edit:
- user:
~/.pi/agent/adx-workflow.json(auto-created, all projects) - project:
<cwd>/.pi/adx-workflow.json(optional, overrides user per key)
All keys optional, unknown keys ignored, malformed file = defaults.
You can also manage it from inside pi:
/adx-config show the effective config + file paths
/adx-config edit interactive menu: pick the file (user/project),
then pick a setting row to TOGGLE it (booleans flip,
defaultBuildWorkflow cycles) — repeat, "Done" exits
/adx-config set defaultPlanMode=true one-shot update (user file)
/adx-config set showWidget=false project # write to the project file
showWidget, skipReview and defaultBuildWorkflow apply immediately;
defaultPlanMode / autoMode apply from the next session.
{
"defaultPlanMode": true,
"showWidget": true,
"autoMode": false,
"skipReview": false,
"defaultBuildWorkflow": "build"
}
| Key | Default | Effect |
|---|---|---|
defaultPlanMode |
false |
Start every pi session in plan mode (no active run to restore) |
showWidget |
true |
false hides the bottom flow/criteria widget entirely |
autoMode |
false |
Persistent --adx-auto: unattended plan → build → verify → recap (the CLI flag still wins when passed) |
skipReview |
false |
Default skip_review=true for the build-verify pipeline (picker + /adx-run build-verify); an explicit skip_review= in the command args wins |
defaultBuildWorkflow |
"build" |
Which workflow /adx-run launches: "build" (simple) or "build-verify" (full) |
Never-stop (auto-continue)
The workflow never parks itself on you:
- Agent steps: when a run ends on an active agent step without
flow_step_done(context pressure, stream stop, the model pausing mid-reflection), theagent_before_settlehook appends a continuation message — carrying the agent's resume note (written withflow_meta, keyresume), the criteria status, and the step reason — and requests one more provider request. You never press "continue" (auto-continue /CONTINUE_PROMPTbehavior). - Context overflow: pi's built-in auto-compaction keeps the context usable between turns; the continuation message is what re-anchors the agent after a compaction.
- Sub-agents: if an isolated verifier/reviewer child stops before
finishing (context pressure, timeout) and its run id is known, the executor
revives it once by re-spawning the persisted child session
(
pi -p --session <runId>+ "continue from where you stopped"). - Safety: 8 consecutive auto-continues on one step → the run blocks
(
/adx-resume);maxIterationscaps the whole run. Explicit user aborts (Escape) are respected —/adx-resumecontinues from the persisted step. - Boot: after a pi restart,
session_startre-enters the current step of any running run (boot auto-continuation).
Tools
| Tool | Purpose |
|---|---|
flow_meta |
Shared workflow metadata store: criteria, todos, review_findings, resume (auto-continue notes) and progress (live display feed). Writes are atomic (per-process write chain + cross-process file lock — parent and pi -p children never lose updates); multi-item writes: add_batch (descriptions) / update_batch (items) |
flow_step_done |
Ends the current workflow step; the executor evaluates transitions and injects the next prompt (or a nudge) |
flow_plan_done |
Signals that planning is complete and hands off to the build pipeline (auto-launch in --adx-auto, picker in interactive mode — including Spec only — stop, which exports the criteria as a spec file and launches nothing) |
ask_user |
Structured question (choice / confirm / text) that pauses the turn for a user answer — plan/spec-mode clarification |
spec_write |
Writes the spec markdown document (spec mode only; defaultActive: false, so it is inactive in plan/build modes) — the single write channel while the workspace stays read-only |
Sub-agents
Flow children are spawned in-house as isolated pi -p child processes
(src/subagent.ts), not through pi-subagents:
pi -p --mode json --extension <adx-workflow> --no-extensions --no-mcp --no-skills
--tools "read,bash,flow_meta" --session-dir <cwd>/.pi/adx-flow/sessions
--session-id <runId> (fresh run) | --session <runId> (resume)
--append-system-prompt <agent role>
"<task>"
| Agent | Role |
|---|---|
adx-verifier |
Independent criterion verification; sets passed/failed via flow_meta |
adx-code-reviewer |
Reviews the git diff; manages review_findings via flow_meta |
- Fresh session per run (session files in
.pi/adx-flow/sessions/) → no retained in-process agent state → the "Agent is already processing" failure class (stuck retained child blocking all subsequent spawns) is structurally impossible. - Child mode (
ADX_CHILD=1): the child loads the extension with only theflow_metatool registered — no executor/commands/widgets, so the child can update the shared store but never advance the workflow itself. - Bounded failures: a 15-minute timeout kills the child process group; provider hangs are recovered by the never-stop resume (persisted session).
- Result contract: the child updates
flow_meta(criteria / review_findings) and writes a report to.pi/adx-flow/reports/<agent>.md. - Model: children use the user's default model; set
ADX_FLOW_MODEL(e.g.litellm/qwen3.8-27b) to pin a cheaper model for flow children, or a per-step"model"field on anysub_agentstep in a workflow file (takes precedence overADX_FLOW_MODEL) — e.g. a fast model for verify/review on small projects. - Env overrides:
ADX_PI_BIN(pi CLI path),ADX_EXTENSION_PATH(extension entry for the child).
Performance: no redundant verification
The executor keeps verification cheap in three ways:
- Re-run short-circuit — after a successful verify pass the executor
records a content hash of the project files (
.pi/,node_modules/,.git/, build dirs excluded). On re-entry to the verify step, if the hash is unchanged AND the step's metadata gate is now met (e.g. the store caught up after a lost write), the expensive verifier pass is skipped and the previous report is reused — a small project no longer pays 3-4 full verifier passes to re-converge on the same verdict. - Proportional effort — verify prompts get
{{projectFileCount}}/{{projectLines}}template variables and instruct the verifier to scale the effort to the project size (small project: focused read + one smoke run, not an exhaustive test suite). - Atomic store — the state file is protected by a cross-process lock
(parent + children) and
flow_metamutations are atomic read-modify-writes; the verifier records all criterion verdicts in a singleupdate_batchcall, so "the verifier said PASS but the store disagrees" re-loops can't happen.
Workflows
Workflow files are plain JSON state machines: workflows/*.workflow.json
(bundled), overridable per project in .pi/adx-workflows/ (highest
precedence) and per user in ~/.pi/agent/workflows/.
Four workflows are bundled:
build— simple:work_location → build → commit? → summarize. No automated verification, no code review; the builder self-checks before marking criteria complete. Launched by/adx-run.build-verify— the full pipeline (launched with/adx-run build-verify):work_location → build → verify → code_review → finalize → commit? → summarize.
Both build pipelines end with an optional commit & push phase (commit?
above), controlled by the commit launch parameter: commit=true runs the
commit & push step automatically (the "Commit changes?" picker is skipped),
commit=false skips it, and without the parameter an interactive
"Commit changes?" picker is shown (auto mode skips it — no commit by
default). The step stages only the session's files (never git add -A),
commits with a clear message, and pushes (rebase onto origin if rejected).
An optional message launch parameter sets the exact commit message
verbatim (without it, the agent derives one from the staged diff).
In a fresh worktree (the worklocation=new path) it commits on the
adx/<slug> branch and pushes that branch only — git push -u origin adx/<slug> — with no merge into the base branch: the merge stays manual
(open a PR or git merge adx/<slug> later), and the worktree + branch are
kept in place for follow-up work.
pr-review— PR review + fixes + squash-merge (requiresgh), launched with/adx-run pr-review pr_number=123.commit— commit & push:check_status → stage → commit → push → summarize. Stages only the session's files (nevergit add -A), commits with a clear message, and rebases onto origin if the push is rejected. Launched with/adx-run commit(optionalmessage="..."param to set the commit message explicitly).
Authoring reference (short)
- Steps:
agent(in-session LLM turn; must end withflow_step_done),sub_agent(isolated child bysubAgentType),shell(branch on exit code),user(pause; buttons derived fromstep_resulttransitions + aContinuefor thealwaystransition). - Transitions: ordered, first match wins. Conditions:
step_result,metadata_all_match,metadata_all_in(empty list ⇒ true),always.gototargets a step id,$done, or$blocked. - Templates:
{{workdir}},{{reason}},{{criteriaCount}},{{pendingCount}},{{criteriaList}},{{modifiedFiles}},{{stepOutput.<key>}}(incl.content,stdout,stderr,exitCode),{{params}}/ individual launch parameters. - Shell trust boundary:
shellstep commands run viash -c, and{{params.*}}/{{workdir}}are interpolated verbatim (unquoted). Launch parameters are trusted shell input: a value likemessage="a; rm -rf ~"is executed as shell code, and word-splitting applies (a paramargs="a b"becomes two words). Quote values yourself when composing commands from params. This is a deliberate trust assumption, not a bug — workflow JSON and launch args are authored by the user running the workflow. - Semantics:
settings.maxIterationscaps the whole run (default 50); no matching transition ⇒$blocked; agent steps re-enter withnudgePromptwhen their transition condition is unmet; state is persisted on every transition.
Full semantics: this extension is a self-contained declarative workflow
engine — steps, ordered transitions, metadata conditions, nudge re-entry,
maxIterations safety cap, $blocked handling, persistence and resume.
Development
git clone https://github.com/mossaab/pi-adx-workflow.git
cd pi-adx-workflow
npm install # dev dependencies (typescript, @types/node, jiti, typebox,
# @earendil-works/pi-ai + pi-coding-agent for the test scripts)
npm run setup-dev # link host-provided packages (typebox, @earendil-works/*)
# from your pi install into node_modules
npm run smoke # jiti-load the extension with a fake ExtensionAPI
npm run e2e # drive the full build-verify pipeline with fake pi + fake sub-agents
npm run typecheck # tsc --noEmit (strict)
npm run setup-dev replicates pi's runtime resolution: it symlinks the
host-provided packages (typebox, @earendil-works/*) from your pi install
into the local node_modules/, so the dev commands work from a fresh clone.
Re-run it if your pi install location changes (or use ADX_FLOW_JITI below).
The test scripts load TypeScript the same way pi does (via jiti). They find
jiti from your pi install — ~/.pi/agent/install/releases/<newest>/node_modules/jiti —
with no hard-coded paths. Override the lookup with
ADX_FLOW_JITI=/path/to/node_modules/jiti if your layout is unusual.
Extension development loop: symlink the repo into
~/.pi/agent/extensions/ (see Install), edit
src/*.ts, and restart pi (or /reload) — jiti loads the TypeScript
directly, no build step.
CI/CD
- CI (
.github/workflows/ci.yml): on every push tomainand on pull requests, GitHub Actions runsnpm ci→typecheck→smoke→e2e→e2e:lockon Node 22. The test scripts' jiti lookup is pointed at the devDependency copy viaADX_FLOW_JITI(runners have no pi install). - Publish (
.github/workflows/npm-publish.yml): publishing a GitHub release (or the manualworkflow_dispatch) runs the typecheck + smoke checks, thennpm publish --provenance. Configure the repo secretNPM_TOKENwith an npm automation token (fine-grained or classic with publish access);--provenanceadditionally requires the GitHub OIDC token, which the workflow requests via theid-token: writepermission.
Contributing
Contributions are welcome — fork, branch, and open a pull request.
- TypeScript, strict mode, no build step — the extension ships as TypeScript loaded by pi's jiti; keep it that way.
- Workflow engine changes: extend
scripts/e2e-executor.mjs— it drives the whole pipeline (nudge loops, verify/review sub-agents, resume, maxIterations blocking) against a fake pi, so it catches regressions fast. - New workflows: plain JSON state machines in
workflows/(schema insrc/types.ts); see the authoring reference. - Docs: README sections mirror the feature set — update both together.
Troubleshooting
piCLI not found — point the extension at it:export ADX_PI_BIN=/path/to/pi(or install pi-coding-agent so~/.pi/agent/bin/piexists).- Flow children using a model you don't want — pin one:
export ADX_FLOW_MODEL=<provider/model>. - Config not taking effect — run
/adx-configto see the effective config and which files were read. Note:defaultPlanMode/autoModeapply from the next session; the rest apply immediately. - "Agent is already processing" — structurally impossible here: flow
children are isolated
pi -pprocesses with fresh sessions, so no stuck retained child can block later spawns. A hung child is killed by the 15-minute timeout and revived by the never-stop resume. - Package install fails at startup (e.g. offline) — pi warns, skips the
package, and retries on the next start or
/reload;pi update --extensionsreports the failure explicitly. - Dev scripts can't find jiti — set
ADX_FLOW_JITIto your jiti install path (see Development).
Project layout
src/
├── index.ts # entry: tools, commands, events, wiring
├── types.ts # workflow schema types
├── store.ts # flow_meta store + execution state (file-backed)
├── templates.ts # template variable resolution
├── modes.ts # plan/build tool gating, bash allowlist, prompt sections
├── subagent.ts # in-house child-process propagation (pi -p spawn/resume)
├── executor.ts # the workflow state machine
├── tools.ts # flow_meta + flow_step_done tool definitions
├── widgets.ts # TUI widget (criteria checklist, step, findings)
└── workflows.ts # workflow loading (project > user > bundled)
workflows/
├── build.workflow.json
├── build-verify.workflow.json
├── commit.workflow.json
└── pr-review.workflow.json
scripts/
├── find-jiti.mjs # locate jiti in your pi install (used by the dev scripts)
├── setup-dev.mjs # npm run setup-dev (link host-provided packages)
├── smoke-load.mjs # npm run smoke
└── e2e-executor.mjs # npm run e2e
License
MIT © mossaab