nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/docs/INSTALL.md

@@ -0,0 +1,626 @@
+# nobrainer-tech-flow installation
+
+All clients consume one canonical `skills/` tree. Prefer an immutable reviewed
+release, dry-run every local target and keep installation evidence separate from
+clean-session routing evidence.
+
+New public source links and package/plugin IDs use `nobrainer-tech-flow`.
+Existing `nobrainer-tech-skills` registrations need the reviewed
+[`nobrainer-tech-flow` migration guide](MIGRATION_TO_FLOW.md); do not call an old registration
+upgraded merely because the new source is installed nearby.
+
+## npm command
+
+Node 18+ and Python 3.11+ are prerequisites. Preview the setup first:
+
+```sh
+npx nobrainer-tech-flow@2.4.0 --client codex
+npx nobrainer-tech-flow@2.4.0 --client codex --apply
+npx nobrainer-tech-flow@2.4.0 --client codex --undo --apply
+```
+
+Use claude for Claude Code, opencode or copilot for those clients. Add --home PATH
+for an isolated profile. These commands become available once this version is
+published on npm; a source candidate is not registry availability.
+
+Application copies the release files into the chosen home directory's
+.nobrainer-tech-flow-npm/2.4.0 and verifies the copy. That folder sits beside
+~/.nobrainer-tech-flow, where the Git installation suggests a clone, so cleaning
+the clone cannot delete the files the skill links point to. Releases before 2.3.2
+kept their copy in .nobrainer-tech-flow/npm; undo such a setup with the command of
+the release that made it. The existing installer then
+links skills to that stable source and writes its managed instructions. This
+avoids links into npx's temporary cache. Unknown files and conflicting installs
+are preserved. Undo uses the same setup record as the Git installer. Retained
+release files remain available for other profiles; they are not disposable test
+artifacts. No postinstall script runs on npm installation.
+
+When switching from an existing Git or npm installation, preview first. If it
+reports a different source, use that installation's recorded undo command before
+applying the new source. The npm command preserves conflicts rather than replacing
+another installation automatically.
+
+For ChatGPT and Claude Chat, follow the [native plugin setup](CHAT_PLUGINS.md)
+rather than the coding-client command.
+
+### Publishing and trusted updates
+
+The first npm publication requires an authenticated package owner. After the
+package exists, configure its Trusted Publisher with GitHub owner
+`nobrainer-tech`, repository `nobrainer-tech-flow`, workflow `npm-publish.yml`,
+no environment name, and permission to run `npm publish`. A publisher configured
+for a different package or repository does not authorize this package.
+
+After the release PR's Validate checks pass and its commit is merged, create the
+matching stable tag. Run the manual Publish npm workflow from that tag. It checks
+the tag against package.json, verifies the packed installation and publishes
+with OIDC provenance. Its bounded registry readback compares the version and
+tarball integrity before reporting delivery. Inspect the registry before retrying
+a run that fails after publication; npm versions cannot be overwritten.
+
+See [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
+
+## Safe default
+
+```bash
+(
+  set -u
+  : "${NB_REVIEWED_COMMIT:?set a reviewed full 40-character commit SHA}"
+  test "${#NB_REVIEWED_COMMIT}" -eq 40 || exit 2
+  case "$NB_REVIEWED_COMMIT" in *[!0-9a-f]*) exit 2 ;; esac
+  git clone --no-checkout https://github.com/nobrainer-tech/nobrainer-tech-flow.git || exit 3
+  cd nobrainer-tech-flow || exit 3
+  git checkout --detach "$NB_REVIEWED_COMMIT" || exit 3
+  test "$(git rev-parse HEAD)" = "$NB_REVIEWED_COMMIT" || exit 3
+  python3 scripts/validate_skills.py --suite || exit 4
+  python3 scripts/install.py --client codex || exit 4          # preview: changes nothing
+  python3 scripts/install.py --client codex --apply || exit 4  # link the skills, add the block
+)
+```
+
+Set `NB_REVIEWED_COMMIT` to the exact full commit SHA you reviewed. The guarded
+subshell rejects unset values, tags, branches and malformed hashes, and stops on
+every failed command. The first installer command is a dry-run; stop the block
+there to read the plan, then run the `--apply` command.
+
+`scripts/install.sh` is the shortest path for one client (`claude`, `codex`,
+`opencode` or `copilot`). It needs no Python and asks nothing; it runs as `sh` on
+macOS, Linux and WSL (tested with dash, bash, busybox and zsh emulating sh), and in
+Git Bash on Windows. Run it where the agent runs: an install made inside WSL lands in the WSL
+home, which a Windows-native client does not read.
+
+```sh
+git clone https://github.com/nobrainer-tech/nobrainer-tech-flow ~/.nobrainer-tech-flow
+sh ~/.nobrainer-tech-flow/scripts/install.sh --client claude            # preview: changes nothing
+sh ~/.nobrainer-tech-flow/scripts/install.sh --client claude --apply    # link all skills, add the block
+sh ~/.nobrainer-tech-flow/scripts/install.sh --client claude --undo --apply
+```
+
+`scripts/install.py` does the same with Python (`python3 scripts/install.py`, same
+flags). The two share the setup record, so either one undoes what the other did.
+
+- The preview names the source commit, how many skills it would link and where,
+  and shows the exact text it would write to the client's global instruction file.
+- A canonical skill target that is not a link to this checkout is a conflict:
+  nothing is written and the command says which one.
+- Running `--apply` again when nothing needs to change prints `UP TO DATE` and no
+  restart hint. `INSTALLED` and the restart hint appear only when a link or the
+  instruction file was written.
+- It never grants a standing authorization. When the block in the instruction file
+  is the text of an earlier version, both scripts replace it with this version's
+  text, keep everything outside the two markers byte for byte and save the file as
+  it was as a `.bak` copy first. `install.py` also keeps earlier auto-update,
+  session-restart and wiki-root settings in the block as `--keep-options` keeps
+  them; `install.sh` leaves a block that carries one of those options, or whose
+  markers do not stand on lines of their own, exactly as it is and says so. Change
+  options with `install_personalization.py`.
+- `--undo` (a preview until `--apply` is added) removes exactly the links the setup
+  created and puts the managed block back as it was before the first setup:
+  removed, or the block that was there before. The rest of the instruction file
+  stays as it is now, so the file comes back byte for byte when nothing else
+  changed. It stops with the reason if the file changed since the last run. It is
+  the guided setup's rollback, so it also reverses a setup made by the guided setup
+  below, and the other way round.
+- `--undo` also removes the folders the setup had to create, such as `~/.agents`
+  for Codex or `~/.config/opencode` for a client that never ran, but only when they
+  are empty. A folder that was there before the setup, or holds anything else, stays.
+  A second undo, or an undo where no setup is recorded, prints `NOTHING TO UNDO`
+  with the client and the record it looked for, changes nothing and exits 0. A
+  damaged record is still an error.
+- It needs symbolic links. On Windows turn on Developer Mode or run from an
+  elevated shell; the command checks first and says so. Otherwise use
+  `install_skills.py --mode copy` (see Windows below).
+- `--home` and the client variables behave as described for the individual
+  scripts below. When a variable chose the location, the output says so; keep it
+  set when you undo.
+
+The setup record is `.nobrainer-flow-onboarding-<client>.json` (for example
+`.nobrainer-flow-onboarding-codex.json`) in the chosen home, next to the client's
+folders. Only you can read or write it (mode 0600), and it holds paths and hashes,
+never a secret: the skills folder, the links the setup created, the instruction file
+with its backup and the SHA-256 of what was written, and `created_dirs`, the folders
+the setup created. `--undo --apply` deletes it, so keep it until you no longer need
+to undo. `.nobrainer-flow-onboarding.json` without a client name is the older
+single-client record; `install.py` still reads it, and `install.sh` points you to it.
+A new instruction file the setup creates is owner-only (mode 0600) as well. An
+existing file keeps its mode, and its `.bak` copy has the same mode.
+
+The individual scripts remain the way to install a subset, use copies, target
+the shared `agents` folder or another client, and are documented next.
+
+An existing unmarked `nobrainer-tech-flow` instruction that still names the retired entry
+skill is a conflict: the personalization installer stops instead of appending
+contradictory rules. Preserve that file, prepare an exact merged replacement
+and review its diff before retrying. This matters for existing Codex and
+Claude profiles that already import personal instructions.
+
+`install_skills.py` installs exactly eighteen skills by default. Install an
+explicit subset by repeating `--skill`:
+
+```bash
+python3 scripts/install_skills.py \
+  --client agents \
+  --skill nobrainer-tech-flow \
+  --skill nobrainer-auto-fine-tune \
+  --skill nobrainer-sessions \
+  --skill nobrainer-spec-driven-development \
+  --skill nobrainer-build \
+  --skill nobrainer-review
+```
+
+The core skill links to `nobrainer-auto-fine-tune`, `nobrainer-sessions` and
+`nobrainer-spec-driven-development`, so a subset should keep all three to make
+those references available. The guided setup always adds the audit skill;
+Sessions and SDD remain explicit selections, not silently added modules.
+The installer prints a `NOTE:` for every selected skill that links to a skill
+which is neither selected nor already installed; the guided setup prints the same
+note once for its whole install set, with the selection ID to add.
+
+Supported local destinations are `claude`, `codex`, `opencode`, `copilot` and
+the shared `agents` path. `codex` and `agents` both target the current shared
+`~/.agents/skills` location documented by
+[Codex Agent Skills](https://developers.openai.com/codex/skills). Claude Code
+follows `CLAUDE_CONFIG_DIR` and OpenCode follows `XDG_CONFIG_HOME`; the installer
+honours both. An empty `XDG_CONFIG_HOME` (or `CODEX_HOME`) counts as unset, as the
+XDG specification (and Codex) say; any other value is used exactly as written. A
+value that is not an absolute path is an error for the client that reads it,
+spaces-only and an empty `CLAUDE_CONFIG_DIR` included: Claude Code resolves such a
+value against its own working directory and does not expand `~`, so the
+installer, which runs from the checkout, cannot know where it points. A variable
+the selected client does not read is ignored. Override a destination only when you
+have inspected it:
+
+```bash
+python3 scripts/install_skills.py \
+  --client agents \
+  --dest /path/to/controlled/skills \
+  --mode copy
+```
+
+`symlink` is the default and keeps one source of truth. `copy` is useful for an
+isolated release/archive test, or where the operating system does not allow
+symlinks (for example Windows without developer mode). Repeating a `copy`
+install over an identical copy reports it as current, whatever `__pycache__`
+directories or `.DS_Store` and `Thumbs.db` files have appeared in it since; any
+other difference, including a loose `.pyc` file that would shadow a module, is a
+conflict and the copy must be replaced by hand after review.
+
+Use one channel per client. Gemini CLI, Pi, OpenCode and Kimi Code also read
+`~/.agents/skills`, so installing there (`--client agents` or `codex`) on top of
+their own adapter can list every skill twice. Pick either the adapter or the
+shared folder.
+
+## Conflict and migration behavior
+
+`install_skills.py` and `install.sh` never overwrite an unknown directory, file
+or symlink. A foreign target at the retired name `nobrainer-reddit` is reported as
+`PRESERVED_FOREIGN` and left unchanged without blocking installation. A foreign
+target at a renamed alias such as `nb-flow`, a canonical name or an unresolved
+legacy name such as `nobrainer-fast-audit` still stops installation.
+
+Both installers use this conflict rule, including the Python/npm setups that
+call `install_skills.py`. An exact stale link from the same checkout still
+blocks installation and requires explicit migration through the Python helper:
+
+```bash
+python3 scripts/install_skills.py --client codex --migrate-legacy
+python3 scripts/install_skills.py --client codex --migrate-legacy --apply
+```
+
+A successful migration atomically moves the exact legacy link out of its public
+name and preserves it under a reported `.nobrainer-migration-*` recovery path.
+The installer prints `BACKUP_PRESERVED`; it never deletes a quarantined claim,
+because portable path deletion cannot be bound atomically to a previously
+verified inode. Inspect client readback before manually removing that exact
+backup. Copy mode builds and verifies the complete tree in a private
+`.nobrainer-install-*` staging directory, then publishes it with a native atomic
+no-replace rename. A failed staged copy remains at the reported private path for
+manual recovery; a concurrently created public target is never overwritten.
+
+For a blocking target from another repository, compare semantics, inbound
+references and runtime triggers before retiring it. A similar name is not proof
+of duplication. Back up or preserve an exact Git ref and remove only reviewed
+targets; never delete a whole shared skills directory.
+
+## Global personalization
+
+Installing the skills alone does not make the client route tasks through them.
+Preview and apply the managed global instruction block for each supported
+client after inspecting its current file:
+
+```bash
+python3 scripts/install_personalization.py --client codex
+python3 scripts/install_personalization.py --client codex --apply
+```
+
+Repeat with `--client claude`, `opencode` or `copilot` as supported. Without
+`--home` the installer follows the variables the clients read:
+`CLAUDE_CONFIG_DIR` for Claude Code, `CODEX_HOME` for Codex and
+`XDG_CONFIG_HOME` for OpenCode; an explicit `--home` selects the documented
+default locations under it and ignores them. Codex reads
+`AGENTS.override.md` instead of `AGENTS.md` whenever the override is not
+empty, so the installer refuses to write `AGENTS.md` next to one; remove or
+empty the override, or pass `--path` to target it on purpose.
+
+Claude Code may already import the Codex global file with `@~/.codex/AGENTS.md`.
+The installer skips the duplicate block only when the Claude file holds nothing
+but that import line and the imported file already carries the managed block;
+otherwise it writes the block to the Claude file. Whether an import inside a
+longer file is live depends on how Claude Code parses the whole file, and an
+independent review found ordinary files that looked like imports and were not.
+A second copy of the block is harmless; a missing one would leave Claude without
+the instructions. A guided setup recorded earlier for the Codex file asks for an
+undo before it writes the Claude file. `agents` needs an explicit verified
+`--path`. For a resolved global wiki,
+pass `--wiki-root PATH` pointing at a directory containing `WIKI.md`; this
+records the actual location in the personalization block. `--auto-update`
+opts into safe checked `nobrainer-tech-flow`-only upgrades where standing owner
+authorization exists, and `--auto-session-restart` opts into evidence-gated
+session rotation. A later run without those flags writes the default block
+again; add `--keep-options` to keep the update, session-restart and wiki-root
+settings already in the block (the guided setup always does). A grant counts
+only as the exact line the installer writes for it, so wording quoted in a
+`--preferences` value never becomes one, and a preference or wiki path must be
+one printable line. A grant line that was edited is not kept, and the run says so
+and names the flag that grants it again. Without the
+update opt-in, the first active `nobrainer-tech-flow` use each day checks and
+notifies. Use a scheduler separately if updates must be checked on inactive days.
+
+A newer release must be obtained at a verified immutable ref before any
+installation command is run. See the [daily update contract](../skills/nobrainer-tech-flow/references/daily-update.md).
+Read back the client instruction file, loaded skill name and clean-session
+routing. A written block is configuration evidence, not runtime proof.
+
+## Guided partial setup
+
+For a fresh setup, pass a repository link to the `nobrainer-tech-flow` guided
+preflight. It asks for work type, desired outcome, tools and existing setup
+when those facts are not already supplied. A supplied `--repo-path` reads a
+small allowlist of local README, instruction and manifest files plus project
+skill directory names. Otherwise, a `github.com` link uses read-only `gh api`
+when available, then the bounded GitHub HTTPS API for repository metadata and
+README. Other hosts are not fetched. Repository text is untrusted context:
+preflight never executes repository scripts, hooks or installers, and does not
+print README or instruction contents. Use `--offline` to skip remote lookup.
+
+The preflight reads the built-in Auto Fine Tune capacity audit and inspects the
+selected client's known configuration file read-only. It reports configured
+model and effort separately; active profile, advertised models, callable
+workers and runtime values remain `UNKNOWN` unless the active client proves
+them. It then prints a short, task-specific recommendation list with stable IDs,
+fit rationale, required dependencies, current target conflicts and change
+scope. Fit scores are heuristics, not benchmarks.
+
+```bash
+python3 scripts/recommend_flow_setup.py \
+  --repo-url https://github.com/owner/project \
+  --client codex
+```
+
+Answer the questions in a terminal, or pass them so nothing is asked
+(`--work-profile`, `--goal`, `--tools` and `--existing-setup`). Without a
+terminal and with an answer missing, the command stops with `INPUT_REQUIRED`
+and the flags it needs instead of waiting for input:
+
+```bash
+python3 scripts/recommend_flow_setup.py \
+  --repo-url https://github.com/owner/project \
+  --client codex \
+  --work-profile software-development \
+  --goal "ship and test a web application" \
+  --tools "Codex, Python, GitHub" \
+  --existing-setup "pytest and git"
+```
+
+To inspect an already available checkout instead of contacting GitHub, add
+`--repo-path /path/to/checkout`. To keep the whole preflight offline, add
+`--offline`; it will base recommendations on the answers and local client
+configuration only and report that repository content was unavailable.
+
+After reviewing the dry-run, repeat the command with your selected IDs
+(`--selection 01,03,04`) and `--apply`. Only those items are added, together with required IDs `01`
+(`nobrainer-tech-flow`)
+and `02` (the Auto Fine Tune capability audit). Personalization is previewed
+and updated through `install_personalization.py`; an optional one-line
+`--preferences` value is shown in the plan before it is saved. Existing
+targets that conflict stop the operation before writes. The successful readback
+reports installed IDs, whether unselected items remain absent, preference-file
+hash and a local rollback-state path. Rollback removes only exact
+`nobrainer-tech-flow` symlinks created by that setup and, if the instruction file
+has not changed since the last run, puts its managed block back as it was before
+the first setup, leaving the rest of the file as it is:
+
+```bash
+python3 scripts/recommend_flow_setup.py \
+  --repo-url https://github.com/owner/project \
+  --client codex \
+  --rollback --apply
+```
+
+The CLI cannot observe the running agent's effective MAIN model, effort, worker
+capacity or runtime context. Those remain `UNKNOWN` until the loaded Auto Fine
+Tune skill checks them in the active client. Do not treat the CLI preflight as
+that runtime proof.
+
+## Project setup
+
+After client discovery works, invoke `nobrainer-tech-flow` in the target project in
+setup mode. It will:
+
+1. inspect existing instructions, skills, specs, wiki, sessions, tests and dirty
+   state;
+2. classify each component `CURRENT`, `DRIFTED`, `MISSING`, `NOT_NEEDED` or
+   `OWNER_GATE`;
+3. add one marked project-instruction block only when equivalent routing is
+   absent;
+4. configure correction hooks for changed owner decisions, corrected agent
+   errors and failed review;
+5. add SDD, wiki or sessions only when the project earns their maintenance cost;
+6. verify the actual client and target workflow before reporting completion.
+
+The instruction block is portable behavior, not a copy of all skill bodies.
+Preserve client-managed markers and byte-equality requirements between files
+such as `AGENTS.md` and `CLAUDE.md`.
+
+## Client channels
+
+### Claude Code
+
+Use the repository as a plugin or install the canonical skill directories
+through the client-supported Agent Skills path. The checked adapter includes a
+`SessionStart` hook that injects only `adapters/bootstrap.md`.
+
+```bash
+claude plugin marketplace add /path/to/reviewed/nobrainer-tech-flow
+claude plugin install nobrainer-tech-flow@nobrainer-tech
+```
+
+The path is the checkout pinned to a reviewed commit in "Safe default" above.
+`claude plugin marketplace add nobrainer-tech/nobrainer-tech-flow` tracks the
+default branch instead, so prefer it only where that is acceptable. The same
+commands work inside a session as `/plugin marketplace add ...` and
+`/plugin install ...`. A plugin namespaces its skills, so the entry point is
+`/nobrainer-tech-flow:nobrainer-tech-flow`; skills installed with
+`--client claude` keep the plain `/nobrainer-tech-flow`. Either way the model
+can also load the skill by name. The `$` forms are Codex syntax; the Codex section
+below says which one to type.
+
+Claude Code lists every skill name but drops the descriptions of the least-used
+skills once the listing passes its budget (1% of the context window by default).
+In a session that already carries many skills the Flow descriptions may reach
+the model as names only. The bootstrap and the personalization block name the
+entry skill, so it can still be loaded by name; what is lost is routing to the
+specialists by their descriptions. The companion
+[`nobrainer-claude`](https://github.com/nobrainer-tech/nobrainer-claude)
+installer can raise the budget on request (`--raise-skill-budget`).
+
+After restart, verify:
+
+- `nobrainer-tech-flow` is discoverable without pasting its body;
+- the hook emits exactly one bootstrap context;
+- a simple task remains direct;
+- a non-trivial task starts with nobrainer-tech-flow and a compact Progress checklist.
+
+#### Optional guards
+
+Two opt-in hooks in your Claude Code user `settings.json`, never in the plugin:
+
+- before a shell command, Claude Code asks you first (it never denies) for
+  `rm -r` (also `/bin/rm`) outside the temporary folders (`$TMPDIR`, `/tmp`,
+  `/var/folders`), `git push --force` (also `-f`, `--force-with-lease` or a
+  `+branch` refspec), `git reset --hard`, `git clean -f`, `vercel --prod`,
+  `npm publish`, `terraform apply` or `destroy`, `kubectl delete` and
+  `gh release create`, also with global options before the subcommand
+  (`npm -w pkg publish`, `gh -R owner/repo release create`). A relative `rm`
+  target counts as temporary only when the working folder is temporary and the
+  command does not `cd` or `pushd` first, and a path counts by where its links
+  lead. An `rm -r` whose arguments it cannot read, and a command line over 2,000
+  characters that names one of these tools, are asked about as well;
+- when a turn that edited files or ran commands ends without a line starting
+  with `Proof:` or `Checked:` and without `UNVERIFIED`, the stop is blocked once
+  so the agent adds one. A read-only turn, a second stop and an unreadable
+  transcript are let through.
+
+This is a seatbelt, not a security boundary. It reads the command text, so
+`sh -c`, a variable or an alias gets past it, and a risky phrase inside a quoted
+string (`echo "git reset --hard"`) asks without need.
+
+```bash
+python3 scripts/install.py --client claude --guards            # preview the hooks it would add
+python3 scripts/install.py --client claude --guards --apply    # add them, with a backup
+python3 scripts/install.py --client claude --guards --undo --apply
+```
+
+`python3 scripts/install_guards.py` takes the same `--apply`, `--undo` and
+`--home` flags. The settings file is `$CLAUDE_CONFIG_DIR/settings.json`, or
+`~/.claude/settings.json` when the variable is unset. The preview lists only the
+hooks it would add or remove, never other settings; other hooks are kept, each
+change writes a new backup, readable only by you, without overwriting an older one, a second `--apply`
+changes nothing, and an invalid file is refused
+(exit 3) without being touched. The hooks run `flow_guard.py` through the
+skill link that `--client claude` created, so install the skills first. A
+plugin-only install, other clients, `scripts/install.sh` and Windows are not
+supported in this version (`UNSUPPORTED`, exit 3). Removing the skills leaves
+the hooks in place, where they do nothing; remove them with `--guards --undo
+--apply`. Restart Claude Code after a change.
+
+The hooks follow https://code.claude.com/docs/en/hooks (Claude Code 2.1.302):
+PreToolUse reads `tool_name`, `tool_input.command` and `cwd` and answers
+`hookSpecificOutput.permissionDecision: "ask"` with `permissionDecisionReason`;
+Stop and SubagentStop read `stop_hook_active`, `last_assistant_message`,
+`transcript_path` and `agent_transcript_path` and answer
+`{"decision": "block", "reason": ...}`.
+
+### Codex
+
+The `.codex-plugin/plugin.json` manifest exposes `./skills/` and declares no
+plugin hook; bootstrap comes from the personalization block or the skill's own
+trigger. Install through the native plugin channel or use the installer. The
+plugin channel needs a reviewed checkout:
+
+```bash
+codex plugin marketplace add /path/to/reviewed/nobrainer-tech-flow
+codex plugin add nobrainer-tech-flow@nobrainer-tech
+```
+
+The installer's `codex` destination is the shared `~/.agents/skills` path:
+
+```bash
+python3 scripts/install_skills.py --client codex
+python3 scripts/install_skills.py --client codex --apply
+```
+
+Restart Codex and test discovery in a fresh task. Repository instructions or the
+native skill trigger provide bootstrap; a file on disk is not routing proof.
+Use nobrainer-tech-flow for user-facing requests. For the technical explicit
+invocation, type the exact name Codex lists for the module, because on Codex
+0.157.1 (macOS) the other form adds no module text to the model input. Codex
+lists the module under the plugin name, so you type
+`$nobrainer-tech-flow:nobrainer-tech-flow`, when a plugin manifest sits above the
+folder a link resolves to: a plugin install, the npm package, or the links the
+installer makes into a git checkout. It lists the plain name, so you type
+`$nobrainer-tech-flow`, for a copy made with `install_skills.py --mode copy`.
+[COMPATIBILITY.md](COMPATIBILITY.md) records what was checked. Plain `NBFlow`,
+`NBF` and `nobrainer-tech-flow` are natural-language triggers whose recognition
+depends on the client. Existing legacy entries under `~/.codex/skills` are not
+deleted or rewritten automatically.
+
+### Cursor
+
+Use `.cursor-plugin/plugin.json`. Its session hook runs the shared bootstrap
+through `hooks/run-hook.cmd`, which uses Git Bash on Windows: from its install
+folders or beside the `git.exe` on PATH, never a `bash.exe` in the current folder.
+Without Git Bash the hook says so on stderr and exits 1, and the session continues
+without the bootstrap. Repository tests
+cover the manifest and the hook script; Cursor itself has not been read back, so
+confirm one injection and native skill discovery after restart.
+
+### OpenCode
+
+Pin the Git package to an immutable full commit in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "nobrainer-tech-flow@git+https://github.com/nobrainer-tech/nobrainer-tech-flow.git#NB_REVIEWED_COMMIT_SHA"
+  ]
+}
+```
+
+Replace the placeholder before use. The adapter registers `skills/` and puts
+the bootstrap in front of the first user message of each request, once; when
+that message has no text part (after a compaction) it adds a synthetic text part
+instead. Local checkout installation is also available with `--client opencode`.
+
+### GitHub Copilot CLI and shared Agent Skills
+
+Use `--client copilot` for `~/.copilot/skills` or `--client agents` for the
+shared `~/.agents/skills` convention. Copilot bootstrap depends on the client's
+current Agent Skills behavior and repository instructions; this package does
+not claim an automatic session hook without runtime readback.
+
+### Gemini CLI
+
+`gemini-extension.json` loads `GEMINI.md`, which includes the small bootstrap.
+Install through the current extension mechanism, restart and verify native skill
+discovery and first routing. Manifest parsing alone is `REPOSITORY_CHECKED`.
+
+### Kimi Code
+
+`.kimi-plugin/plugin.json` exposes `./skills/` and selects `nobrainer-tech-flow` at session
+start. Its instructions explicitly refuse invented visible-session transport.
+Verify the exact installed version and clean-session behavior.
+
+### Pi
+
+The package extension registers `skills/` during resource discovery and adds the
+bootstrap to every model request that does not carry it yet. The host rebuilds
+the message list for each request, so the bootstrap also survives compaction, and
+a marker keeps one request from receiving it twice. Repository tests cover the
+extension contract; a real client readback is still required.
+
+### Windows
+
+Run `scripts/install.sh` in Git Bash (it comes with Git for Windows), or the
+Python scripts with `py -3` or `python`. The hook adapters need Git Bash too, not
+the `bash.exe` launcher that Windows ships for WSL (Windows finds that one first
+when a command says just `bash`). The repository pins the hook scripts, the shell
+installer and the bootstrap to LF endings so a Git checkout with
+`core.autocrlf=true` still runs them. Creating symlinks needs developer mode or an
+elevated shell; without either, install with `install_skills.py --mode copy`. CI
+runs the structure validators, the adapter tests, a Windows smoke module and both
+one-command installers on a Windows runner; it does not run the whole suite
+there, and no client was read back on Windows.
+
+### Other Agent Skills clients
+
+Use the portable `plugin.json`, the canonical skill directories and explicit
+project instructions. Do not claim automatic bootstrap unless the target client
+actually exposes and passes that integration.
+
+## Dynamic specialists
+
+The eighteen curated skills are the stable base. When a concrete work unit still
+has a capability gap, `nobrainer-team` first inventories installed/project
+capabilities, then may evaluate one external skill temporarily. Source/ref,
+scripts, permissions, credentials, network behavior, trigger overlap and
+rollback must be inspected before use. Persistent or global installation is an
+owner gate.
+
+## Readback and acceptance
+
+After every install or upgrade:
+
+1. restart the client;
+2. list/read back the loaded source and skill count;
+3. start a clean task with no pasted skill body;
+4. issue one explicit canonical request and one semantic non-trivial request;
+   for Codex type the name the client lists for the module:
+   `$nobrainer-tech-flow:nobrainer-tech-flow` when it lists modules under the
+   plugin name, `$nobrainer-tech-flow` when it lists them plainly (the Codex
+   section above says which installs do which);
+5. confirm nobrainer-tech-flow asks no more than one ordinary requirements round, shows one
+   compact Progress checklist and routes a specialist only when needed;
+6. issue a one-step task and confirm it remains direct;
+7. simulate a correction and confirm affected TODO/evidence is invalidated;
+8. record client version, source ref, transcript/evidence and gaps.
+
+Use the proof ladder in [COMPATIBILITY.md](COMPATIBILITY.md). Installation is not
+`RUNTIME_VERIFIED` until the clean-session behavior passes.
+
+## Rollback
+
+Before applying, record existing target fingerprints and the source ref. To
+roll back:
+
+- remove only links/copies created by this exact run, or restore the recorded
+  prior targets;
+- inspect any reported `.nobrainer-migration-*` or `.nobrainer-rollback-*`
+  recovery path before deleting that exact entry manually;
+- return project instructions to their scoped preimage;
+- restart the client;
+- verify that the previous source and routing behavior are restored.
+
+Never remove a shared root recursively. A preserved recovery claim is evidence,
+not garbage: verify its fingerprint and the live client before exact manual
+cleanup. Failed or partial rollback is a blocker, not a warning to ignore.