/projects/piflux/index.md
Piflux
What is Piflux?
Piflux is an implementation workflow extension for Pi.
Things may be good or bad, but at least they are interesting
Regardless of personal opinions, it is clear at the time of writing that AI is becoming the norm for software development. Even that may be a tame statement; in many ways it already became the norm. From AI-assisted autocompletion in IDEs to vibe-coding entire applications, if you write software in the Year of Our Lord 2026, chances are you’ve had to use AI in some form.
One thing about it is definitely interesting: adoption is faster than standards can emerge. It feels like everyone is experimenting with it in one way or another. And so am I.
Trying out a new toy
In the spirit of experimentation, I recently started to use Pi as a coding harness. I was intrigued by the premise that I was meant to adapt it to my workflow, and decided to play with it following its own rules. In doing so, I found it better than trying to bend Claude Code to my will.
My workflow is based on a few core tenets:
- AI produces better code when planning, implementation and verification happen in separate sessions, each working from a clean slate.
- Plans should be immutable, but deviations are expected.
- Implementation and verification are iterative processes; returning to the implementation session to resolve verification findings is natural when writing software.
- The verification agent is a gatekeeper. It should never change the implementation, it only evaluates what was implemented.
- Code can only be shipped after it passes verification.
- Ideally, each stage should run a different model; they have different strengths, weaknesses, and blind spots.
Starting from these ideas, I envisioned a Pi extension that would allow me to execute this workflow through a handful of simple commands, allowing me to audit the execution of each step while automating session and model management based on configuration. It would also offer guardrails to prevent steps from being skipped or executed out of order.
Automation, more or less
The graph above is a representation of the workflow. The user executes each step and the extension creates a new session, sets the model configured for each step, and submits the prompt template so the agent can do its job. Usage instructions can be found in the repository. Instead of a boring and meandering description of each command, I want to explain the rationale behind the workflow.
It presumes a human is in the loop, overseeing the implementation. More than once, I’ve seen people talk about how using AI when coding feels like a superpower. I don’t exactly disagree, but there is some nuance to this claim; it only feels like a superpower when I actually understand what the AI is doing. The greater my expertise with the language and frameworks, and the greater my familiarity with the architecture and structure of the project, the better I can leverage AI.
For this reason, Piflux is purposefully not fully automated. Each step generates an artifact that serves as input for later steps; for example, /code starts the implementation in a new session, and all it knows is whatever is written on the plan. Likewise, /review only has the plan, the actual code changes, and an implementation report to understand what it should be verifying. While those artifacts exist so agents can communicate with one another, they are also meant for humans to read. Inspecting those artifacts and being able to interact with agents during each step was the centerpiece of this extension.
The iterative part of the workflow is something I would highlight; when the verification process has findings, a review report is generated. /icode sends a new prompt to the implementation session, as the previous implementation context is still relevant. The agent now reads the review report to address the review findings. It may require applying a fix, or it may be a case of explaining why it won’t be fixed. /ireview then sends the user back to the verification session, and the review agent now can read the new implementation report alongside the previous verification report while having the previous review context at hand. This process is supposed to be repeated until the verification comes out clean. It is possible to reach a state in which the implementation and verification disagree on one of the findings; but since the user is in the loop, no automated process is necessary to resolve the conflict.
“But humans are smelly and I want my agents to do everything”
I see AI as an excellent tool to automate laborious tasks, and writing code is no exception. But even as the act of writing code is automated away, it is important to not surrender the cognitive control of software. Otherwise how can one reason about what needs to be implemented? How to write better descriptions so a plan can be more robust, code more precise, and review more thorough? This extension exists to help with that.
That said, not all software is created equal. Throwaway code, prototypes, and experiments may demand faster iteration. Effort to keep cognitive control here may very well be wasted. There is a time and place for more automation, and I will most likely write a different extension that implements the same workflow in a fully automated fashion.
Cost and quality are not divorced after all
When I started to work on this, the pain point I was trying to solve was the notion that the agent did a worse job when the implementation happened in the same session where I was explaining the task to the agent. At that point ideas are still unfinished. Some points that sound really important at the start may be refined into something completely different or abandoned entirely. Things that emerge halfway through the planning may gain outsized importance. All this context is excellent during planning, but during implementation it becomes just trash polluting the context.
While Pi has excellent session management features, juggling sessions became a chore, and chores should be automated. At that point I was also experimenting with different models and thinking levels per session. For example, GLM-5.2 was an excellent model for planning, while DeepSeek-V4-Flash was an amazingly cheap workhorse for implementation. Tasks like shipping the code after review could be offloaded to less powerful models as well.
The outcome of all this was largely a positive one:
- Code comes out cleaner, as it starts from a defined scope.
- Implementation is more efficient in terms of tokens and cost; both for working from a cleaner context and for being able to offload work to cheaper models.
- Verification in particular is very efficient as it gets a lot of context from planning and implementation artifacts.
Nothing is ever truly done
I have some ideas in mind on how to expand this. Right now I really want to experiment with managing tasks through a Kanban board. A variation of /start that goes to the board to fetch the task and kicks off planning based on the task description would be really cool.
Was this vibe-coded?
To an extent, yes.
The prompt templates were strongly guided by me, but I had the LLM rewrite them in that obnoxious way that instructions for agents are usually written. I tried to make sure that the templates are generic enough to be used in any sort of software project, while still providing enough guidance for agents in a consistent manner.
The TypeScript that implements the extension itself was mostly vibe-coded (dogfooding this very workflow); I broadly reviewed the TypeScript to ensure it was not doing anything weird, but that was about it.