FluencyLoop – A lighter, developer-centric SpecKit alternative

FluencyLoop launches as a developer-centric alternative to SpecKit, offering a lightweight tool that documents AI-generated code by capturing design decisions, rationale, and reviewer-ready summaries within feature branches. The tool integrates with Claude Code and Codex, maintaining a private knowledge base to calibrate explanations based on developer familiarity, and stores documentation alongside code under docs/fluencyloop/. It aims to keep developers fluent in the code their AI agents write by producing documentation during delivery rather than after context is lost.

Stay fluent in the code your AI agent writes. FluencyLoop turns each feature into a documented design, teaches the decisions at your level, tracks the rationale, and produces a reviewer-ready summary. A private knowledge base keeps that teaching calibrated across features. The code and your fluency in it are produced together, or not at all. 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 and verify its design and decisions. 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. 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. Plans, Mermaid design diagrams, feature sessions, and review summaries live beside the code under docs/fluencyloop/ . They are created from the actual branch and its changes, so documentation is produced during delivery rather than reconstructed after context has been lost. Each real fork records what was chosen, where it applies, why it was chosen, which alternative was rejected, how it relates to the constitution and design, and whether the rationale was verified. Reviewers get the decisions that shaped the feature instead of only a list of changed files. docs/fluencyloop/ ├── constitution.md ├── plans/<initiative /plan.md └── features/<feature / ├── design.md └── sessions/ .md .fluencyloop/ contains project workflow state. The per-developer calibration profile lives in ~/.fluencyloop/ ; it controls teaching depth and is never committed. Session documents describe the work, never the person. /plugin marketplace add baokhang83/fluencyloop /plugin install fluencyloop@fluencyloop Use the namespaced slash commands shown above. The plugin bundles its deterministic CLI, so there is no separate system-wide FluencyLoop installation. Claude Code updates and Windows approvals FluencyLoop's startup hook checks its own marketplace on each new session and, when an update is available, installs it for the next session without changing the active one. Run /reload-plugins to activate it in the current session instead. The check runs at startup only; resuming, clearing, or compacting a session does not repeat it. To update at any time by hand, run /plugin marketplace update fluencyloop , then /plugin update fluencyloop@fluencyloop , and finally /reload-plugins . The startup check is best-effort and deliberately silent, because a session must never fail to start over an update it could not fetch. If the claude CLI is absent from the PATH , or the network or a policy blocks the marketplace, the session starts normally and reports nothing. Run claude plugin list to see the version you are actually running, and use the manual commands above if it looks stale. Claude Code's own Enable auto-update toggle /plugin → Marketplaces → fluencyloop is a separate control that stays off by default. FluencyLoop refreshes only its own package and does not read or change that setting. On native Windows, use the project-scoped setup in Claude Code approvals /baokhang83/fluencyloop/blob/main/docs/claude-code-permissions.md to reduce routine FluencyLoop, editing, and read-only Git prompts without granting broad Git or Bash access. codex plugin marketplace add baokhang83/fluencyloop codex plugin add fluencyloop@fluencyloop Use the $fluencyloop:<stage skills shown above. The plugin maintains its own fluencyloop command shim on macOS, Linux, Git Bash, and WSL; no separate runtime installation is required. Codex updates Codex asks you to review FluencyLoop's startup hook once. Approve it from /hooks to enable automatic updates. Each new session checks only FluencyLoop's marketplace and, when an update is available, installs it for the next session without changing the active one. Like the Claude Code check, this one is best-effort and silent: an unapproved hook, a missing codex CLI, or a blocked marketplace leaves the session running its current version without reporting anything. Run fluencyloop version to see the version the Codex install is actually running. To update by hand, run codex plugin marketplace upgrade fluencyloop , then codex plugin add fluencyloop@fluencyloop ; the next session picks it up. FluencyLoop requires Claude Code https://claude.com/claude-code or Codex https://developers.openai.com/codex/ , git , and either Bash on macOS/Linux/Git Bash/WSL or PowerShell pwsh on native Windows. Read MANIFESTO.md /baokhang83/fluencyloop/blob/main/MANIFESTO.md for the product principles, calibration and privacy model, and the boundary between deterministic tooling and agent reasoning. See CONTRIBUTING.md /baokhang83/fluencyloop/blob/main/CONTRIBUTING.md for the repository layout, test commands, and distribution notes.