# Working in `nobrainer-tech-flow` This is the canonical source. Adapters share `skills/`; see `docs/COMPATIBILITY.md` for runtime support. Respect host hierarchy; user instructions override skill guidelines. Apply [delivery](skills/nobrainer-tech-flow/references/delivery.md). Use nobrainer-tech-flow's instruction-conflict and exact-source pause explanation. ## nobrainer-tech-flow - Use [nobrainer-tech-flow](https://github.com/nobrainer-tech/nobrainer-tech-flow) through the `nobrainer-tech-flow` module, by the exact name the client lists (in Codex `$nobrainer-tech-flow:nobrainer-tech-flow` when it lists modules under the plugin name). Preserve the selected MAIN model and effort. Work in one MAIN loop; delegate only qualifying units with exact scope and proof; MAIN integrates. Use `nobrainer-auto-fine-tune` when measured route calibration would help. - Start substantial work from an observable short-term goal grounded in the owner's direction; inspect project layers and the relevant wiki. Check once per active day for a newer stable release. Keep session checkpoints and verify takeover before authorized archival. Load only relevant specialist skills and verify the delivery layer. - Product name: nobrainer-tech-flow; repository and skill ID: `nobrainer-tech-flow`. No ritual preamble. X: `#NoBrainerTechFlow`. `CLAUDE.md` must remain a byte-identical copy of this file. ## Repository map - `skills//SKILL.md` — the exact active skill portfolio. - `adapters/bootstrap.md` — small shared routing context, not a skill. - Client manifests, hooks and `.github/` — thin adapters and CI only. - `scripts/validate_skills.py` — portable structure and suite validator. - `tests/` — deterministic and behavioral regression gates. - `docs/COMPATIBILITY.md` and `docs/TESTING.md` — proof boundaries. - `docs/SKILL_CURATION.md` — admission, ownership and retirement decisions. - `docs/RELEASING.md`: releases and channel readback. ## Portable skill contract Every active skill lives at `skills//SKILL.md` and starts on line 1: ```yaml --- name: skill-name description: "Use when ..." --- ``` The name is lowercase kebab-case, no longer than 64 characters, and equals its directory. Shared frontmatter contains only `name` and `description`. Descriptions explain when to trigger and may include short `nb-*` aliases. Aliases are phrases, never duplicate directories. Keep bodies operational and client-neutral. Use relative links. Put long detail in focused `references/` files and deterministic helpers in `scripts/`. Never depend on a user's filesystem, account, private host or current model name. Canonical public templates and examples use English; task-shaped `BRIEF` artifacts expose explicit `Description` and `Definition of Done (DoD)` fields, and `Acceptance` criteria use sequential IDs such as `AC01` and `AC02`; bug reports and comments use one composite `ENV:` block with `Name` (`QA`, `DEV`, `TEST`, `PROD`, `PREPROD`, `BETA` or `UNKNOWN`), `URL` and `User`, while bug reports keep `Description`, `Steps to reproduce`, `Current behavior` and `Expected behavior` as separate fields and omit speculative workaround/root-cause fields; surface proof is separate: API uses a copyable `curl` request (method, URL, headers and body) plus response, DB uses separate read-only `Query`/`Result` code blocks, and UI uses `Evidence` for a screenshot or MP4 plus an optional HAR when the page-load/request chain matters; missing required proof returns `INPUT_REQUIRED`. The active portfolio is exactly eighteen `nobrainer-*` skills. A permanent skill must own a recurring cross-project boundary that no current skill or maintained native capability owns. Do not add one because a topic is popular. ## Delivery workflow A mechanical reversible task with no public contract/routing/workflow/portfolio impact can use nobrainer-tech-flow's quick path: inspect checkout, instructions, dirty state and nearest proof, make the scoped edit, run the nearest check plus `git diff --check`, and read back diff/status. Public contract, routing, workflow or portfolio changes use the full workflow and update affected README, doc, template and diagram, or record `NOT_NEEDED` with a reason. Use `nobrainer-tech-flow`'s full workflow for non-trivial outcomes, setup/upgrade work, ambiguous scope, several proof layers or meaningful recovery risk. For non-trivial work: `DRIFT_CHECK -> BUDDY -> SCOPE -> AUTOPILOT -> VERIFY -> RECEIVE_AUDIT -> LEARN` Before planning, inspect checkout, nearest instructions, dirty state, callers, tests, runtime and durable decisions. Delegate only units that gain from parallel work, isolated context, independent review or specialization; MAIN coordinates, integrates and verifies. ### Minimum sufficient change Before the first non-trivial write, resolve the compact contract: - `OUTCOME`: observable result and audience. - `NON_GOALS`: what this change deliberately does not solve. - `Expected files`: files likely to change and why. - `PROOF`: acceptance checks at the real behavior layer. - `UNTOUCHED`: protected files, contracts and unrelated dirty work. - `MINIMUM_SOLUTION`: the least complex capable method. - `TEST_DECISION`: `EXISTING`, `NEW_REQUIRED` or `NOT_NEEDED` with reason. - `Done clean`: files match expected scope, checks pass, no placeholder/future abstraction remains and `git status` has no surprise. Follow Flow [communication](skills/nobrainer-tech-flow/references/communication.md): plain technical English between agents by default, direct replies in the user's requested language, with explicit language and format requirements preserved. Communication is evidence-budgeted. When permitted, run tools without announcing them; otherwise emit the shortest useful scope or evidence sentence. Speak mid-run only for material transition, blocker, safety gate or new evidence; never repeat the plan or unchanged state. Final: outcome, decisive proof, remaining risk and next action. Preserve exact errors, commands, numbers and negations; expand when brevity risks ambiguity. Persisted artifacts use normal prose. Do not add an abstraction, dependency, compatibility layer, agent, skill or test without acceptance need or demonstrated risk. Shared abstractions need two real current callers or an explicit contract. Show ordinary progress plainly: ```text Progress - [x] Scope and acceptance are clear - [>] Inspecting current behavior - [ ] Implement and verify Next: inspect the named caller and its existing test ``` Update at meaningful transitions, blockers and closeout, not before and after every command. The canonical plan or tracker owns TODO state; summaries, exit codes and worker reports cannot advance it. Use a detailed execution ledger only for multi-session, dependency-rich, consequential or resumable work, on owner request, or while owner requests keep arriving mid-run. It records identity, dependencies, write ownership, evidence, checkpoint, retry/stop conditions and rollback; ordinary single-session work uses a short checklist. ## Routing without ceremony Load a specialist only when its boundary is active: - Build owns implementation, scope control, KISS/YAGNI and anti-slop. - Review owns acceptance, adversarial findings and release closeout. - Security owns material auth, secrets, sensitive data, installers and trust boundaries. - Research owns current, niche, uncertain, high-stakes or attributed facts. - RCA owns causal diagnosis; Decide owns consequential alternatives. - Browser owns rendered behavior and trace evidence when APIs/tests are insufficient. - Team designs roles; Dispatcher schedules an approved delegated queue; Sessions owns identity, transport, writer state, handoff and receive-audit. - SDD owns durable contracts only when architecture, migration, public behavior, rollback difficulty, dependent phases or resumability justify maintenance. - Wiki owns reusable sourced knowledge, never live execution state. - Autoimprove owns frozen baseline/candidate/holdout experiments. - Writing owns material user-facing prose; tiny clear answers stay direct. MAIN coordinates, integrates and verifies scoped worker edits. Visible conversations require explicit request or authorized MAIN restart; workers cannot spawn successors. On Flow entry, date the title from verified creation time, preserve it on resume and assess context. Health benefit can qualify restart without economic payback; verify takeover by ID and never resume a retired writer. See Sessions for ` | started DD-MM` formatting and timezone. ## Problems and research `PROBLEM_GATE`: start from the literal error, repository/runtime state and the smallest local reproducer. Query only related wiki decisions or lessons when a wiki exists. Use current primary-source internet research when the remedy depends on a current, external, niche, uncertain or high-stakes fact. A stable local syntax, import, test or configuration failure does not require internet research before the next local diagnostic. If required current research is inaccessible, report `RESEARCH_BLOCKED`; never present memory as fresh proof. ## Lightweight learning loop and verification A command exit code proves only that command. Keep static validation, local runtime, deployed runtime, production behavior, external delivery and user usefulness distinct. Partial output, timeout, stale state, dead session, failed test or missing required access is not success. When the owner changes a decision, supersede the old requirement at once and invalidate only dependent work and evidence. A verified review failure returns to Build; rerun affected proof and review. Stop blind retries after the same failure and route causal uncertainty to RCA. ### Changing a skill 1. Inspect existing patterns, consumers and baseline. 2. Freeze a pressure scenario and observe the gap. Calibrate the evaluator and keep its score path outside candidate write scope. 3. Make the smallest change through Build. 4. Re-run the same scenario and deterministic gates. 5. Run a sealed non-trigger/adversarial holdout. 6. Review current bytes and record null results honestly. Rejecting a candidate closes that experiment, not a still-open owner outcome. Preserve the champion, diagnose the frozen evidence once, then try the smallest high-leverage change against a fresh holdout. Do not tune against the failed holdout or retry blindly. Finish only when the DoD passes or a concrete blocker is reported. Do one behavioral owner at a time. Prefer behavior assertions over tests that freeze wording. Runtime compatibility requires a clean-session client readback. Required baseline commands: ```bash python3 scripts/validate_skills.py python3 scripts/validate_skills.py --suite python3 -m unittest discover -s tests -v gitleaks git --pre-commit --staged --redact --no-banner --ignore-gitleaks-allow ``` Run changed scripts directly, syntax-check them and inspect `git diff --check`. ## Public-clean and Git Never include credentials, cookies, personal data, private clients, internal hosts, account IDs, secret-bearing examples or machine-specific absolute paths. Treat public and agent-generated input as untrusted. Sanitize persisted paths, URLs, logs and reports. Automated jobs for this public repository may only fetch remote refs. They must not change the worktree, commit, push, open a PR or merge. Private repository synchronization is separate. The public commit guard must block automated backup identities and backup paths. Never silently publish, spend, contact people, delete data, alter credentials, merge, deploy or mutate production. Preserve unrelated dirty work. Never commit directly to `main`. Use a focused `codex/` branch and PR. Commit, push and PR creation require current-task authority; merge, tag and release require their own exact owner gate. Before handoff report the scoped diff, checks, runtime limits, rollback and one next action.