@syntesseraai/pi-feature-factory

Pi package for Feature Factory orchestration. It reuses the OpenCode Feature Factory assets as source material, then runs the workflow in Pi as a same-session phase state machine.

No Pi subagents are required.

Install & Update

pi install npm:@syntesseraai/pi-feature-factory

Update to latest:

pi uninstall @syntesseraai/pi-feature-factory 2>/dev/null; pi install npm:@syntesseraai/pi-feature-factory@latest

For local development:

pi install -l ./packages/pi-extension

Deploying phase definitions

ff-pi-deploy is the only mechanism that writes generated Feature Factory Pi phase definitions. It reads definitions from assets/agents/, rewrites them for same-session Pi execution, and writes user-editable phase files to:

${PI_CODING_AGENT_DIR:-~/.pi/agent}/ff-phases/

Usage:

npm run deploy-pi                 # interactive phase runtime/model overrides
npm run deploy-pi -- -y           # non-interactive suggestions
npm run deploy-pi -- --list-models
npm run deploy-pi -- --list-native-models
npm run deploy-pi -- --list-acp-models

Interactive deploy walks phases in this clearer order:

feature-factory → architect → experience → planning → fast-building → building → advanced-building → code-reviewing → documenting → full-reviewing

This is deploy/configuration order only; automatic routing still uses planning → building → code-reviewing → documenting → full-reviewing.

Interactive deploy lets each phase choose:

• native runtime with a Pi model only
• acp runtime with an ACP model/provider only, e.g. antigravity (acpx gemini agent)
• For acp phases, choose acpx output mode by setting acp_format (default text, optional json).

When re-running deploy-pi -- -y, existing phase files keep their runtime choice; brand-new phase files default to native.

The extension never auto-generates phase files during session startup, so users can modify ~/.pi/agent/ff-phases/*.md safely. Default workflow routing only accepts planning, building, code-reviewing, documenting, and full-reviewing; optional helper files such as feature-factory.md are deployed as explicit/manual definitions with workflow_phase: false.

Running Feature Factory

/feature-factory I need to change X, Y, Z

Pi supports multi-line command input with shift+enter before submit.

Submitting /feature-factory starts the first turn immediately, so you should not need a manual follow-up prompt.

The extension sets the session name from a one-line summary of the request (first 25 normalized characters, then ... if needed) so multi-line slash input does not spill into the title/status area.

Phase transitions are deferred until Pi becomes idle, then injected as a normal user message with no follow-up/steer delivery mode. This keeps the next phase visible as a real user turn without racing agent_end.

The workflow advances in one Pi session:

planning → building → code-reviewing → documenting → full-reviewing → done

Review phases can push back to building by returning REWORK_REQUIRED: true or PHASE_STATUS: changes_requested. Automatic advancement stops after 25 phase turns by default (FF_PI_MAX_ITERATIONS=<positive integer> overrides this) to prevent runaway review/build loops.

Follow-ups while active:

/feature-factory follow-up add this constraint...
/ff-follow-up add this constraint...

If the model is busy, the follow-up command waits for Pi to become idle and then sends the follow-up as a normal user turn.

Standalone phase commands

Optional helper phases can be invoked directly without running the full Feature Factory workflow:

/full-reviewing review this change...
/code-reviewing review this change...
/documenting update the docs for...
/architect advise on the architecture for...
/experience evaluate the UX of...

Each command loads the corresponding phase definition, sets the model/tools/thinking for that phase, and runs a single turn. No auto-advance occurs after the phase completes.

ACP-backed phases

The extension registers a custom Pi provider, feature-factory-acp, for deployed phases with runtime: "acp".

ACP turns are handled by acpx — a headless ACP client that manages protocol handshakes, permissions, tool execution, and graceful lifecycle. acpx is installed automatically by ff-pi-deploy when any ACP-backed phases are configured. acpx <agent> exec does not support the --model flag; model selection is handled by the acpx agent adapter itself.

The Pi provider serializes the conversation context to a temp file and spawns acpx in one-shot (exec) mode. By default it streams human-readable text output. Set acp_format: json in an ACP phase file to enable acpx --format json --json-strict and render structured content (text, thinking blocks, tool calls) as native Pi events.

Context Truncation

ACP agents have smaller context windows than Pi's native models. When the serialized context exceeds the phase's context_window × 0.7 character budget (default 100K characters), the oldest messages are dropped and a [Truncated N earlier messages] notice is inserted. Add context_window (in tokens) to ACP phase frontmatter to configure:

context_window: 128000

What it provides

• /feature-factory slash command
• /ff-follow-up slash command
• Same-session Feature Factory phase state machine
• User-editable phase definitions in ff-phases/
• Native Pi and ACP-backed phase runtime support
• Skill loading from assets/skills

Architecture

Module	Purpose
index.ts	Extension entry point and lifecycle hooks
phase-definitions.ts	Loads deployed phase markdown and builds phase prompts
state-machine.ts	Persists phase state and selects next phase
acp-provider.ts	Delegates ACP phase execution to acpx and streams output into Pi

Asset sync

npm run sync:assets          # from ~/.config/opencode
npm run sync:assets:source   # from packages/opencode-plugin

npm run build runs sync:assets:source first and then type-checks the extension.