Fluencyloop

FluencyLoop

FluencyLoop captures the decisions behind each feature while your agent builds it,so the codebase remains explainable.

Table of contents

• 🧭 The workflow
• ✨ What it gives you
• 🧱 What gets committed
• 📦 Install
• 🗑️ Uninstall
• 💬 Help shape FluencyLoop
• ✅ Requirements
• 📚 More detail
• 📄 License

🧭 The workflow

Initialize the project once, then run one feature loop per branch. Use plan only when the work is too large for a single feature.

Step	Claude Code	Codex	What it does
1. Initialize	fluencyloop init	fluencyloop init	Creates the project state and an empty constitution. Plan and feature also do this automatically if needed.
2. Plan (optional)	/fluencyloop:plan <initiative description>	$fluencyloop:plan <initiative description>	Designs the architecture and breaks a large initiative into feature-sized tasks.
3. Build + learn	/fluencyloop:feature <feature description>	$fluencyloop:feature <feature description>	Creates a feature branch and design, builds in slices, teaches each real decision, and journals it.
4. Review	/fluencyloop:review	$fluencyloop:review	Assembles the branch's sessions and decisions into a reviewer-facing PR view.

For normal-sized work, the practical path is init → feature → review. For a large initiative, run plan first, then repeat feature → review for each task in its roadmap.

If work was merged without the loop, use /fluencyloop:backfill in Claude Code or $fluencyloop:backfill in Codex to reconstruct its design and decisions. Reconstructed decisions are recorded as unverified by default; verification is optional and never blocks the backfill.

FluencyLoop also bundles diagram-design for architectural explanations. It is available to both clients after the normal plugin update; FluencyLoop uses it only when a diagram makes a record clearer than prose alone.

✨ What it gives you

📜 A living constitution

The constitution is a short set of checkable engineering principles for the project. It starts from the first real plan or feature and grows when a decision reveals a repeatable stance. Every later design and review is checked against it, but it never blocks a conventional merge.

🧠 Knowledge transfer, taught to your level

FluencyLoop teaches at the moment a meaningful decision is made. It explains the mechanism, the reason for the chosen path, and the rejected alternative, then checks that the explanation landed before continuing when the topic is unfamiliar.

It maintains a private, per-developer knowledge base of domain familiarity and demonstrated engagement. That profile carries across projects and features, keeping explanations concise on familiar ground and deeper where knowledge is still forming. It is never committed to a project; only person-neutral knowledge-transfer notes about the software enter the documentation.

🗂️ Project records that follow the code