fluencyloop

name

fluencyloop

description

FluencyLoop — stay fluent in code as AI writes it. Router/overview for the per-feature loop (design → build+teach → review), the optional up-front planning stage for large chunks, the woven-in constitution that grows from decisions, plus post-merge backfill. Use when the user mentions FluencyLoop, "fluency", the .fluencyloop/ directory, or wants to set up / understand the workflow but hasn't named a specific stage.

FluencyLoop

The code and your fluency in it are produced together, or not at all.

Literal CLI Fast Path (Codex)

This section takes priority over every later workflow instruction. If the developer gives a literal fluencyloop CLI command, such as fluencyloop init, fluencyloop -v, or fluencyloop check, they requested only that command.

1. For fluencyloop init, request sandbox elevation for that exact command before its first execution. It may create Codex-protected .git metadata; do not first attempt it in the standard sandbox.
2. Invoke fluencyloop immediately.
3. Do not send an interim update, inspect the workspace, read state, search the web, check PATH, or explain what the command will do.
4. Do not route to a stage or run a follow-up command after it succeeds. In particular, fluencyloop init must not automatically start a feature or plan.
5. Return the command's result concisely. If Codex requires approval for another write, request it before running the command; do not add setup narration.

Bundled CLI (Codex)

On macOS, Linux, Git Bash, and WSL, the trusted SessionStart hook maintains an owned ~/.local/bin/fluencyloop shim for this installed plugin. Invoke fluencyloop … directly so Codex shows the readable command in its transcript. Do not resolve its path, check PATH, or describe the shim to the developer.

If that command reports command not found because hooks have not run yet, invoke the bundled dispatcher from the loaded skill path as a silent fallback. On native Windows, invoke the adjacent fluencyloop.ps1 with pwsh.

Question delivery

FluencyLoop's stage skills use AskUserQuestion in Claude Code for genuine prompts. Codex has no equivalent question-form tool, so they ask a concise standalone question in chat and pause for the answer before continuing.

FluencyLoop keeps the people behind a codebase fluent in it as AI writes more of it. At its core is a per-feature loop — design → build (teach) → review — driven by whoever is building. Nothing gates a merge; work that skips the loop is caught after merge by backfill.

PER BIG CHUNK (optional)     REPEATS, PER FEATURE (contributor-driven)
( plan )                  →  design    →  build (teach)   →  review
architecture + roadmap       diagrams     session journal    PR view assembles itself

Planning is optional — reach for it only when a chunk of work is too big for one feature/branch and needs an architecture + roadmap first. Small work goes straight to $fluencyloop:feature.

The constitution (the project's checkable principles) is load-bearing — plan and feature both check designs against it — but it is not a stage you sit down and author. It's born from your first real intent (a plan, or the first feature as backstop) and grows as features harvest repeatable stances from real decisions. Same law as the journal and the calibration profile: it accretes from building, never authored cold unless you explicitly choose to.

Route to the right stage

The user wants to…	Skill
Plan a large chunk — architecture, task breakdown, roadmap	$fluencyloop:plan
Start building something, stay fluent as they go	$fluencyloop:feature
Prepare a PR / summarise a feature for a reviewer	$fluencyloop:review
Document work that shipped without the loop	$fluencyloop:backfill

For a conversational request to "set up FluencyLoop" (not a literal CLI command), initialise an absent .fluencyloop/ scaffold, then continue with $fluencyloop:feature (or $fluencyloop:plan for a big chunk). The constitution fills itself in from there.

Initialise a project

fluencyloop init   # initialises Git if needed, then scaffolds .fluencyloop/

This creates .fluencyloop/ (scripts, templates, constitution stub). Agent skills are activated through the agent's installation mechanism and are never copied into the project. A feature is a branch (feature/<slug>); sessions are committed journals; the per-developer calibration profile lives globally in ~/.fluencyloop/ and is never committed.

Minimal generation — scripts assemble, the model writes the why

FluencyLoop is cheap to run because the deterministic scripts do everything mechanical and the model spends tokens only on the irreducible rationale. The split, per stage:

Stage	The scripts assemble (deterministic)	The model writes (irreducible)
Declare / design	feature branch, design.md stub, state.json (slug / branch / stage / base)	the design diagrams (the shapes), the constitution check
Build (per slice)	slice-context (diff + metadata + likely_decision), the session skeleton, the decision blocks (fluencyloop decision), calibration signal / compact, state.json updates	the code, the taught why, knowledge-transfer prose, the decision field values
Review	assemble-pr-view (sessions inlined, commit range, base), PR creation	the reviewer-facing distillation
Backfill	feature + session scaffold, state.json, decision blocks, check drift	the reconstructed rationale (marked unverified)

The rule: if a stage asks the model to produce something a script could assemble deterministically — a file skeleton, a commit range, a formatted block, a state read — that's a bug; move it to a script. The model's tokens go to the why, never to plumbing.

The four standing principles

• Evidence over pitch — probe demand cheaply before building.
• Stay out of the way — never block the fast path; flag exposure, don't gate.
• The developer stays the architect — the tool serves their authorship.
• Honest about tradeoffs — no claim of free comprehension.