/plan

name: plan
description: 'FluencyLoop planning stage. Plan a large chunk of work before building it: design and document the overall architecture, break it into task items, sequence them into a roadmap with a critical path, and (optionally) open GitHub issues under a milestone. Produces a committed plan.md that the per-feature loop then builds from — one feature per task item. Use when the work is too big for a single feature/branch, or when the user says "fluencyloop plan", "plan this", "design the architecture for", "break this down", or "make a roadmap".'

Plan — map a big chunk before you build it

Sits **upstream of `$fluencyloop:feature`**. A *feature* is one branch; a **plan** is an *initiative* that will spawn several features. You will: (1) frame the chunk, (2) analyse requirements and surface material gaps, (3) design and show the overall architecture, (4) break it into task items, (5) sequence them into a roadmap with a critical path, (6) offer to open GitHub tickets under a milestone, (7) hand each task off to `$fluencyloop:feature`. The plan is a **map you build against, not a spec to ratify** — do not over-invest. Keep the developer the architect.

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.

Question delivery — preserve the pause

For a real answer, choice, or confirmation, use **`AskUserQuestion` in Claude Code**. Codex has no equivalent question-form tool, so ask a concise standalone question in chat and stop; do not create issues, write a settled choice, or advance the workflow until the developer answers.

**Understanding checks are self-report, never quizzes.** After teaching, ask only whether the developer understands 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. Familiarity probes before teaching and real technical choices remain valid, but they are not learning verification.

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.

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.

**Migrate imported history before planning.** Parse `legacy_migration_pending` from `fluencyloop check --json` before reading the constitution, calibration, requirements, or the initiative intent. When it is `true`, do not ask the developer anything or scaffold a plan. This is an automatic, repository-wide migration:

**Do not probe writer commands.** During this migration, `fluencyloop import --semantic-status --json` is the only discovery command. Do **not** run bare `fluencyloop import`, `fluencyloop import --help`, or bare `fluencyloop concept`; the automatic importer already ran, and writers require complete evidence-backed arguments. Do not inspect the constitution, calibration, requirements, or Git status until the migration completes.

1. Run `fluencyloop import --semantic-status --json` and work through **every** `unassessed_features` entry in its stable order. For each one, read its imported store records and the matching `docs/fluencyloop/features/<slug>/` history—not just the feature title. Never create or switch historical feature branches. 2. In that same per-feature pass, add the evidence-backed architectural records and relations that it establishes or changes, using `fluencyloop concept --feature <slug> --session 000-legacy-import`. Do not invent one record per feature and do not repeat the already-imported decision/knowledge records. A feature with no product-level architectural effect is valid, but its assessment must say why. 3. Immediately record that same evidence pass with `fluencyloop import --assess <slug> --summary "<evidence-based outcome>" --record "<record name>"` (repeat `--record` for every architectural record it contributed; omit it only for a genuinely local feature). This is required for every imported feature; it is the completion coverage, not a substitute for the architectural records themselves. Do not collect 46 summaries and issue them later as one det