pi-architect

Architect a feature with Pi before you build it.

The agent walks through six phases: Frame, Explore, Decide, Design, Slice and Blueprint. You approve each phase before it moves on. The result is a plan that another agent can build from.

Work in progress. See DESIGN.md for the plan.

Install

pi install npm:@jordyvanvorselen/pi-architect

Use

/architect Dedupe panel events

This switches the session to architect mode and names the feature. The agent waits for your first message. Give it what it needs to frame the feature, like a ticket link, a description or the files involved.

Each Pi session has a mode. Build is normal Pi and the default. Architect is for designing:

• The agent is told to change nothing yet. That means no file edits, no commands that write, and no changes to tickets or other systems unless you ask. It puts each change in the design instead.
• Nothing is blocked. Every tool stays on, including MCP servers, web search and other extensions, so the agent can read a ticket, search the docs or run the tests.
• The agent records the design with architect_update.
• The agent draws components, data flow and sequences as Unicode diagrams with architect_diagram. Each diagram is checked for alignment before you see it, with [new], [changed] and [removed] parts highlighted.
• The agent raises each open question with architect_decide. A decision card shows the options side by side. You pick one, add a comment, write your own option or ask a question first.
• The agent calls architect_advance when a phase is done. A review screen shows the phase. You approve it or ask for changes with a comment.
• The agent splits the work into slices with architect_slice. Each slice has files, concrete steps and verify commands.

When you approve the Blueprint, the plan is written to docs/plans/<feature>.md. An existing file is never overwritten: the name gets -2, -3 and so on. Change the directory with pi --architect-plan-dir <dir>.

In build mode a line above the editor shows the progress: ▸ BUILD plan: dedupe-panel-events ✓1 ✓2 ●3 ○4 slice 3/4 · Store dedup key. The builder ticks the boxes in the plan file as it works, so the plan file is where progress lives.

build, board, review, plan and reset are reserved. A first word that only starts with one, like Builder, asks whether you meant the command. Put a feature name in quotes to use it as written: /architect "Build pipeline". Every question that discards work starts on No. /architect plan alone also offers to build the plan in this session or to copy its path.

On the decision card: ←/→ or ↑/↓, tab and shift+tab, or 1–4 move, ↵ chooses, c chooses with a comment, n adds your own option, ? asks a question, b opens the board, esc closes. On a review screen: ↑/↓ or j/k, PgUp/PgDn, space, Home and End scroll, ↵ approves, r requests changes, b opens the board, esc closes. Closing a card or a review without an answer stops the agent, so esc asks first. /architect review opens a closed review again.

The board shows the whole design on one screen, with a tab for the brief, the code map, decisions, diagrams, risks, slices and the plan. Switch tabs with 1–7, tab and shift+tab, or ←/→. Move with ↑/↓ or j/k, open an item with ↵, and step back from it with esc or backspace. Press c on anything to comment on it. When you close the board with comments, it asks whether to send them. ↵ sends them to the agent as one message, with the decision, diagram or slice each one is about. d discards them and esc goes back to the board. In build mode the board is read-only, for reading the approved design. So is the board you open with b from a decision card or review screen. Closing it takes you back to where you were.

The footer always shows the mode. In architect mode a stepper above the editor shows the phases, open decisions and risks.

The mode and the design live in the session. They survive reload and resume. Fork the session to try another answer.

What works so far

• Architect and build mode, with the switch in the transcript and in the footer.
• Decision cards, and a review screen for every phase with approve and request changes.
• Decisions and verdicts as small cards in the transcript.
• The brief, modules, findings and risks.
• Unicode diagrams, checked for alignment and highlighted.
• Slices with a checked dependency graph, the plan file and build progress.
• The board, with comments for the agent.

Develop

npm install
npm run lint
npm run typecheck
npm test
npm run test:coverage

License

MIT