@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 lets each phase choose:

• native runtime with a Pi model only
• acp runtime with an ACP model/provider only, e.g. antigravity via agy-acp

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.

ACP-backed phases

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

ACP output is converted into Pi assistant stream events, so an ACP phase such as documenting through agy-acp appears in the same Pi transcript as native model output. The bridge serializes prior assistant tool calls plus tool-result metadata/content into the ACP prompt so ACP phases retain tool-context awareness.

Context Truncation

ACP providers 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	Streams ACP phase output into Pi as assistant events
adapter-acp.ts	ACP command mapping and legacy helper functions

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.