/feature

name: feature
description: 'FluencyLoop Stage 2–3. Declare a feature and build it while staying fluent: creates the feature branch, frames its concepts and relationships, then builds in slices, teaching the why of each real decision at the slice boundary and journaling it. Probes the concepts the work needs up front, adapts explanation depth to the developer''s knowledge, and builds/maintains a per-developer knowledge base in ~/.fluencyloop. Use when starting a new unit of work in a repo that has a .fluencyloop/ directory, or when the user says "fluencyloop feature", "start a feature", or describes something they want to build with FluencyLoop.'

Feature — declare a feature, build it fluent

This is the contributor's entry point. A **feature is a branch** (`feature/<slug>`); it owns its design reasoning and session journals. You will: (1) declare the feature, (2) frame its concepts and relationships, (3) build it in slices — teaching and journaling one or two real decisions at each slice boundary. Never block a build or merge; pause only for a required learning response. Never lecture. Keep the developer the author.

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`.

Local site — open once

Before the first user-visible response, run `fluencyloop site --ensure --open-once --json`. This ensures the reader for every workflow entry, but opens a browser tab only once while that managed reader is alive. If it reports `running: true` and no earlier assistant message in this session starts with `FluencyLoop site:`, say `FluencyLoop site: <url> (opened in browser).` once, using its returned URL. Do not mention an unavailable site or repeat the announcement.

Generated prose — ASD-STE100

Write generated user-facing technical prose in ASD-STE100 style: use short, direct sentences, active voice, one main action per sentence, and stable, unambiguous terms. Preserve product names, code identifiers, CLI commands, field names, and exact recorded values. Do not claim formal ASD-STE100 compliance: that requires checking the official controlled dictionary and rules. Apply this style to live decision-boundary teaching as well as generated Markdown and PR prose. It makes the required explanation clearer; it does not shorten, skip, or replace that explanation.

Question delivery — preserve the pause

When this workflow needs a real answer, choice, confirmation, or knowledge probe, use **`AskUserQuestion` in Claude Code**. **Codex has no equivalent question-form tool:** ask the question concisely in chat, then **stop**. Do not implement, write the decision, or move to the next step until the developer has answered. A chat question is a portability fallback, not permission to bury a real question in prose.

**Understanding checks are self-report, never quizzes.** After teaching, the only permitted check is to ask the developer directly whether they understand and whether anything needs clarification: *"Do you understand this explanation, or should I clarify anything?"* Then trust their answer. Never ask them to prove understanding by restating the mechanism, explaining it "in your own words," predicting behavior, selecting an answer, or answering any other topic-specific question. A pre-teaching familiarity probe and a real technical choice are still valid questions, but neither may be repurposed as verification of what the developer learned.

0. Preconditions

Run `fluencyloop check --json`. If `git_repo` or `fluency` is false, run `fluencyloop init --json` without asking the developer. It initialises Git in the current project directory when needed, then creates FluencyLoop's state. Only stop if `init` itself fails.

**Report real entry points after a fresh init.** Say that a larger initiative starts with `fluencyloop plan "<intent>"` or `/fluencyloop:plan`; one buildable unit starts with `fluencyloop feature "<intent>"` or `/fluencyloop:feature`. Never recommend the retired prose names `fluencyloop-plan`, `fluencyloop-feature`, `fluencyloop-review`, or `fluencyloop-backfill`.

For that `fluencyloop init --json` command in Codex, request sandbox elevation before its first execution. It may create or update Codex-protected `.git` metadata; do not first attempt it in the standard sandbox.

**Reattach a safe detached checkout.** If `branch` is `HEAD`, `state_matches_branch` is `true`, and `state_branch` is nonempty, the detached commit is on the recorded feature's history, not a split. Run `git status --porcelain`. If it is empty, run `git checkout <state_branch>`, then rerun `fluencyloop check --json` before any work. If it is not empty, stop and state that the detached checkout has changes which must be resolved before it can be reattached. Do not write records or start a new feature while detached. `check` deliberately accepts only a commit reachable from the recorded feature branch; a descendant or divergent detached commit remains a split.

**Refuse split state.** Parse `state_matches_branch` from `fluencyloop check --json` before any calibration, feature declaration, session, or writer command. If it is `false`, stop immediately: state the checkout branch and `state_branch`, and ask the developer which existing feature context to preserve. Do not create a new feature, switch branches, or overwrite state to guess a repair.

**Resume preconditions after the answer.** The developer's answer settles the split for this run. If they select the saved feature, switch to its recorded branch; if