fluencyloop

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

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:

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.