baokhang83 · baokhang83 · Jul 15, 2026 · Jul 15, 2026
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "fluencyloop",
+  "interface": {
+    "displayName": "FluencyLoop"
+  },
+  "plugins": [
+    {
+      "name": "fluencyloop",
+      "source": {
+        "source": "local",
+        "path": "./plugins/fluencyloop"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -14,13 +14,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: ShellCheck (scripts, CLI, installer, plugin launcher)
+      - name: ShellCheck (bundled runtime and Claude launcher)
         # shellcheck is preinstalled on the ubuntu runner. -P SCRIPTDIR lets it follow the
         # `# shellcheck source=common.sh` directives so sourced helpers are analysed too.
-        run: shellcheck -x -P SCRIPTDIR scripts/bash/*.sh fluencyloop install.sh bin/fluencyloop
+        run: shellcheck -x -P SCRIPTDIR plugins/fluencyloop/scripts/bash/*.sh plugins/fluencyloop/fluencyloop bin/fluencyloop
       - name: Ban eval (shell=True-equivalent footgun)
         run: |
-          if grep -rnE '(^|[^[:alnum:]_])eval[[:space:]]' scripts/bash fluencyloop install.sh bin/fluencyloop; then
+          if grep -rnE '(^|[^[:alnum:]_])eval[[:space:]]' plugins/fluencyloop/scripts/bash plugins/fluencyloop/fluencyloop bin/fluencyloop; then
             echo "::error::eval is banned in FluencyLoop shell — it runs arbitrary strings as code."
             exit 1
           fi
@@ -86,11 +86,10 @@ jobs:
           Install-Module PSScriptAnalyzer -Force -Scope CurrentUser
       - name: PSScriptAnalyzer
         run: |
-          $set = 'scripts/powershell/PSScriptAnalyzerSettings.psd1'
+          $set = 'plugins/fluencyloop/scripts/powershell/PSScriptAnalyzerSettings.psd1'
           $r = @()
-          $r += Invoke-ScriptAnalyzer -Path scripts/powershell -Recurse -Settings $set -Severity Warning, Error
-          $r += Invoke-ScriptAnalyzer -Path fluencyloop.ps1 -Settings $set -Severity Warning, Error
-          $r += Invoke-ScriptAnalyzer -Path install.ps1 -Settings $set -Severity Warning, Error
+          $r += Invoke-ScriptAnalyzer -Path plugins/fluencyloop/scripts/powershell -Recurse -Settings $set -Severity Warning, Error
+          $r += Invoke-ScriptAnalyzer -Path plugins/fluencyloop/fluencyloop.ps1 -Settings $set -Severity Warning, Error
           if ($r) { $r | Format-Table -AutoSize | Out-String | Write-Host; throw "PSScriptAnalyzer found $($r.Count) issue(s)" }
           Write-Host 'PSScriptAnalyzer: clean'
       - name: Pester

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,15 @@
 
 All notable changes to FluencyLoop are documented here.
 
+## Unreleased
+
+### Changed
+
+- FluencyLoop is now distributed as both a Claude Code marketplace plugin and a Codex marketplace
+  plugin. The canonical runtime lives in `plugins/fluencyloop/`.
+- Retired `install.sh`, `install.ps1`, and `fluencyloop self upgrade`; agent plugin managers now
+  own installation and updates.
+
 ## 0.2.0
 
 ### Added

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,10 +7,10 @@ actively dogfooded, so expect rough edges and fast-moving changes.
 
 The scripts switch branches and write files in your repo, so they're tested. CI runs
 [`shellcheck`](https://www.shellcheck.net/) + a [`bats`](https://github.com/bats-core/bats-core)
-suite on every push and PR; run them locally with `shellcheck -x -P SCRIPTDIR scripts/bash/*.sh`
-and `bats tests`.
+suite on every push and PR; run them locally with
+`shellcheck -x -P SCRIPTDIR plugins/fluencyloop/scripts/bash/*.sh` and `bats tests`.
 
 <a id="distribution-roadmap"></a>
-> **Distribution roadmap:** today it's clone + `install.sh`. Packaging the skills as a Claude
-> Code **plugin/marketplace** entry (one-click install for others) and publishing the CLI
-> (homebrew/npm) are the next distribution steps — not required to use.
+> **Distribution:** FluencyLoop ships through its Claude Code and Codex marketplace plugins.
+> The canonical runtime lives in `plugins/fluencyloop/`; do not add a machine-wide installer or
+> copy skills into a user's agent directory.
diff --git a/MANIFESTO.md b/MANIFESTO.md
@@ -126,24 +126,21 @@ file skeletons that a script can create, and does not repeatedly ask a question
 private preferences. The journal is more reliable because its structure is deterministic; the
 model spends its tokens on the reasoning a script cannot supply.
 
-## Command surface
-
-```bash
-fluencyloop init                         # scaffold FluencyLoop in this repository
-fluencyloop plan "split the monolith"    # optional initiative map
-fluencyloop feature "add rate limiting"  # branch + design + active feature state
-fluencyloop session "wire Redis store"   # open a build session
-fluencyloop review                       # assemble the reviewer-facing view
-fluencyloop backfill                     # reconstruct skipped work after merge
-fluencyloop check                        # inspect state and un-journaled drift
-fluencyloop calibration init             # initialise private teaching calibration
-fluencyloop calibration show             # inspect the profile
-fluencyloop version                      # print the installed release
-fluencyloop self upgrade                 # refresh an installed copy from its source checkout
-```
+## Agent command surface
+
+FluencyLoop is activated through its agent plugins, not a global installer. Start an explicit
+stage command in the agent you use:
+
+| Goal | Claude Code | Codex |
+|---|---|---|
+| Plan a large initiative | `/fluencyloop:plan` | `$fluencyloop-plan` |
+| Build a feature | `/fluencyloop:feature` | `$fluencyloop-feature` |
+| Assemble its PR view | `/fluencyloop:review` | `$fluencyloop-review` |
+| Backfill skipped work | `/fluencyloop:backfill` | `$fluencyloop-backfill` |
 
-The CLI is useful on its own. Agent skills supply the interactive loop and are installed through
-the relevant agent's distribution mechanism.
+The skills invoke the bundled deterministic CLI for `init`, feature/session scaffolding, review
+assembly, and private calibration. The CLI is deliberately not a separate machine-wide install:
+the agent's plugin manager owns installation and updates.
 
 ## What FluencyLoop refuses to be
 
@@ -173,11 +170,11 @@ The design has real costs.
 
 ## Status: 0.2.0
 
-0.2.0 is a working cross-platform loop, not a manifesto-only concept: the Bash and PowerShell
-CLIs scaffold and inspect state, construct feature and session records, assemble review context,
-maintain private calibration, and support self-upgrade. The next measure of success is not a more
-elaborate process; it is whether real contributors stay more fluent with a cost they are willing to
-pay.
+0.2.0 is a working cross-agent loop, not a manifesto-only concept: its Claude Code and Codex
+plugins ship the same deterministic runtime to scaffold and inspect state, construct feature and
+session records, assemble review context, and maintain private calibration. The next measure of
+success is not a more elaborate process; it is whether real contributors stay more fluent with a
+cost they are willing to pay.
 
 ## Standing principles
 

diff --git a/README.md b/README.md
@@ -41,9 +41,9 @@ principles from real decisions. Nothing gates a merge — work that skips the lo
 **after** merge by `backfill`.
 
 **Requires:** a coding agent ([Claude Code](https://claude.com/claude-code) or
-[Codex](https://developers.openai.com/codex/)) plus `git`, and a
-shell to run the CLI — `bash` (macOS/Linux/Git Bash/WSL) or **PowerShell 7** (Windows). The
-`fluencyloop` CLI runs standalone; the interactive skills need the agent.
+[Codex](https://developers.openai.com/codex/)), `git`, and `bash` (macOS/Linux/Git Bash/WSL).
+The deterministic CLI is bundled inside the agent plugins; there is no separate machine-wide
+installer or project skill vendoring step.
 
 ## Teaches to your level
 
@@ -74,91 +74,35 @@ The plugin includes the interactive skills and a bundled `fluencyloop` command f
 Bash tool. Its skills are intentionally namespaced, for example
 `/fluencyloop:feature`, so they cannot collide with another plugin's skills.
 
-### Codex or a standalone terminal CLI
+### Codex
 
-Clone and install the CLI. Use `--agent codex` to install the current Codex skills as well; omit
-that flag (or pass `--no-skills`) when you only want the terminal command.
+Install FluencyLoop from the same repository marketplace:
 
 ```bash
-git clone https://github.com/baokhang83/fluencyloop && cd fluencyloop
-./install.sh --agent codex
+codex plugin marketplace add baokhang83/fluencyloop
+codex plugin add fluencyloop@fluencyloop
 ```
 
-This copies the tool into `~/.fluencyloop/lib` and puts `fluencyloop` on your PATH
-(`~/.local/bin` — make sure that's on your `$PATH`).
-
-### Initialise a project
-
-Inside a repository you want to use FluencyLoop on:
-
-```bash
-fluencyloop init
-```
-
-This scaffolds that repo's `.fluencyloop/` state (scripts, templates, a constitution stub) and
-adds the calibration `.gitignore` guard.
-
-### On Windows
-
-Two ways to run it:
-
-**Native PowerShell CLI** ([PowerShell 7](https://aka.ms/powershell)). Use this when you want the
-CLI outside Claude Code. From a clone:
-
-```powershell
-./install.ps1 -NoSkills
-```
-
-This copies the tool into `%USERPROFILE%\.fluencyloop\lib` and adds it to your user PATH. Then
-`fluencyloop <verb>` works from PowerShell **and** cmd (via a `.cmd` shim), with the same verbs
-and `--json` output as the bash CLI — `fluencyloop version` and `fluencyloop self upgrade`
-included. Use `./install.ps1 -Agent codex` for Codex; install Claude Code through the marketplace
-above.
-
-**Git Bash / WSL.** The bash tool also runs unchanged in **Git Bash** (bundled with
-[Git for Windows](https://git-scm.com/download/win)) or **WSL** — use `./install.sh` there.
-
-Both shells are verified on a Windows CI runner: the bash suite via Git Bash, and the PowerShell
-port via `PSScriptAnalyzer` + a `Pester` suite that mirrors the bash tests.
+The plugin makes the `$fluencyloop-*` skills available. Its bundled CLI stays private to the
+plugin and is run by those skills, so it never needs to be copied onto your PATH.
 
 ## Quickstart
 
-From inside the repository you want to work on:
-
-```bash
-# Scaffold the project once.
-fluencyloop init
+Inside the repository you want to work on, invoke the workflow stage in your installed agent.
+The plan and feature stages initialise `.fluencyloop/` automatically when needed.
 
-# Choose one path. For a large initiative, make its architecture and roadmap first.
-fluencyloop plan "revamp the checkout flow"
-
-# For a normal-sized change, start a feature: this creates its branch, design stub, and session journal.
-fluencyloop feature "add rate limiting to the API"
-```
-
-Use **one** of the last two commands: `plan` is optional and is for work too large for one
-feature; it creates an architecture + roadmap under `docs/fluencyloop/plans/`. Build each roadmap
-item as a feature. `feature` creates the `feature/add-rate-limiting` branch and drops a design doc
-and a session journal under `docs/fluencyloop/`. As you build, your agent teaches the *why* of each
-real decision at the slice boundary and records it in the journal. When you're ready to open a PR:
-
-```bash
-fluencyloop review
-```
-
-…assembles the reviewer-facing PR view straight from those journals — no manual linking,
-because a feature *is* its branch. Shipped something without the loop? `fluencyloop backfill`
-reconstructs the journal after merge.
-
-### Useful commands
+| Goal | Claude Code | Codex |
+|------|-------------|-------|
+| Plan a large initiative — architecture + roadmap | `/fluencyloop:plan revamp the checkout flow` | `$fluencyloop-plan revamp the checkout flow` |
+| Build a normal-sized feature — design → build + teach | `/fluencyloop:feature add rate limiting to the API` | `$fluencyloop-feature add rate limiting to the API` |
+| Assemble the feature's PR view | `/fluencyloop:review` | `$fluencyloop-review` |
+| Document merged work that skipped the loop | `/fluencyloop:backfill` | `$fluencyloop-backfill` |
 
-```bash
-fluencyloop check              # inspect the active feature and un-journaled drift
-fluencyloop version            # print the installed release
-fluencyloop self upgrade       # refresh an installed copy from its source checkout
-fluencyloop calibration show   # inspect your private teaching profile
-fluencyloop calibration edit   # adjust it yourself, if you want to
-```
+Use **plan** only for work too large for one feature branch. It creates an architecture + roadmap
+under `docs/fluencyloop/plans/`; build each roadmap item as a feature. A feature creates its
+branch, design, and session journal under `docs/fluencyloop/`, teaches the *why* of each real
+decision at the slice boundary, and records it. Review assembles the reviewer-facing view from
+those journals, because a feature *is* its branch.
 
 ### Calibration
 
@@ -177,18 +121,6 @@ slice diff rather than whole files, asks only what the calibration profile does
 records rationale at the moment it is still grounded in the change. See [the efficiency
 principle](MANIFESTO.md#efficiency-is-a-product-principle).
 
-## Use it
-
-| Step | Claude Code | Codex |
-|------|-------------|-------|
-| *(optionally)* Plan a big chunk — architecture + roadmap | `/fluencyloop:plan` | `$fluencyloop-plan` |
-| Build a feature — design → build + teach *(per feature)* | `/fluencyloop:feature` | `$fluencyloop-feature` |
-| Review — the PR view assembles itself *(per feature)* | `/fluencyloop:review` | `$fluencyloop-review` |
-| Backfill — document work that skipped the loop *(post-merge)* | `/fluencyloop:backfill` | `$fluencyloop-backfill` |
-
-You can also describe the task naturally, but invoking the stage skill explicitly makes the
-workflow unmistakable.
-
 The **skills** carry the interactive, calibrated behaviour (teaching at slice boundaries,
 one-question-at-a-time constitution authoring). The **scripts** carry the deterministic
 plumbing (branches, files, PR-view assembly) so the journal is reliable rather than
@@ -197,16 +129,11 @@ left to the model.
 ## Layout
 
 ```
-install.sh / install.ps1    machine install (bash / PowerShell): CLI on PATH; `--agent codex` adds Codex skills
 .claude-plugin/             Claude Code plugin manifest + self-hosted marketplace catalog
+.agents/plugins/            Codex marketplace catalog
 claude-skills/              Claude-only aliases: `plan`, `feature`, `review`, `backfill`
 bin/                        the plugin's bundled `fluencyloop` launchers
-fluencyloop{,.ps1,.cmd}     CLI dispatcher — verbs: init / plan / feature / session / decision / review / check / slice-context / calibration / version / self upgrade
-VERSION                     the current version (0.2.0); `fluencyloop version` prints it
-scripts/bash/               deterministic plumbing — bash (the reference implementation)
-scripts/powershell/         the same plumbing, ported to PowerShell (Windows-native)
-templates/                  .fluencyloop state templates (constitution, design, session)
-skills/                     the interactive skills (activated for Claude Code or Codex)
+plugins/fluencyloop/        Codex plugin and canonical runtime: CLI, skills, scripts, templates
 tests/                      bats suite (bash) + tests/powershell Pester suite (mirror)
 MANIFESTO.md                the why
 ```

diff --git a/bin/fluencyloop b/bin/fluencyloop
@@ -3,4 +3,4 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-exec "$ROOT/fluencyloop" "$@"
+exec "$ROOT/plugins/fluencyloop/fluencyloop" "$@"
diff --git a/bin/fluencyloop.cmd b/bin/fluencyloop.cmd
@@ -1,2 +1,2 @@
 @echo off
-pwsh -NoProfile -ExecutionPolicy Bypass -File "%~dp0..\fluencyloop.ps1" %*
+pwsh -NoProfile -ExecutionPolicy Bypass -File "%~dp0..\plugins\fluencyloop\fluencyloop.ps1" %*
diff --git a/claude-skills/feature/SKILL.md b/claude-skills/feature/SKILL.md
@@ -20,8 +20,9 @@ permission to bury a real question in prose.
 
 ## 0. Preconditions
 
-Confirm `.fluencyloop/` exists (`fluencyloop check` reports it). If it does not, tell
-the user to run `fluencyloop init` first, and stop.
+Confirm `.fluencyloop/` exists (`fluencyloop check --json` reports it). If it is absent, run
+`fluencyloop init` yourself, say that the repository is now initialised, and continue. Only stop
+if `init` itself fails (for example, because the directory is not a Git repository).
 
 **Read the loop state.** If `.fluencyloop/state.json` exists, read it *first* — it is the loop's
 single source of truth for the active feature (`feature` slug, `branch`, `stage`, `last_session`,

diff --git a/claude-skills/plan/SKILL.md b/claude-skills/plan/SKILL.md
@@ -20,8 +20,9 @@ create issues, write a settled choice, or advance the workflow until the develop
 
 ## 0. Preconditions
 
-Confirm `.fluencyloop/` exists (`fluencyloop check` reports it). If not, tell the user
-to run `fluencyloop init` first, and stop.
+Confirm `.fluencyloop/` exists (`fluencyloop check --json` reports it). If it is absent, run
+`fluencyloop init` yourself, say that the repository is now initialised, and continue. Only stop
+if `init` itself fails (for example, because the directory is not a Git repository).
 
 **Read the constitution up front** — `docs/fluencyloop/constitution.md`, and **if it's a pointer**
 (a `Source of truth:` line naming another file, e.g. `.specify/memory/constitution.md`), read