nobrainer-tech-flow git:20261104.e53f1a8A

Immutable. This exact content never changes and is served at /api/v1/blob/2e77b28a820cc7e0.

---
name: nobrainer-tech-flow
description: "Use when you want to set up, start, resume or complete a coding or non-coding task: scope the outcome, use native workers only where they help, and verify delivery. Aliases: NBFlow, NBF, nobrainer-tech-flow."
---

# nobrainer-tech-flow

Skill: `nobrainer-tech-flow`. `NBFlow` and `NBF` are natural-language
shortcuts; explicit skill loading remains client-dependent.
Use [communication](references/communication.md): plain technical English between agents; natural user-language replies.
Here "the user" owns the task; references call that person the owner and the main agent MAIN.

For non-trivial work read [routing](references/routing.md). Preserve host model/effort;
consult [model routing](references/model-routing.md) when selecting them.
Setup/upgrade/repair uses [setup](references/setup.md); corrections use
[correction hooks](references/correction-hooks.md); gated resumability uses
[long-run state](references/long-run-state.md).
Repository work follows the [task worktree lifecycle](references/worktrees.md).

## Automatic session care

For resumable, long or delegated work with `nobrainer-sessions` installed, run Sessions [startup and health](../nobrainer-sessions/references/session-restart.md#automatic-start-and-observation); otherwise stay in the main agent.
Restart or archive needs separate consent from the user and verified takeover.

## Current instructions

At first use per local calendar day, check the installed Flow version against
the latest stable published release using
[daily update](references/daily-update.md). Inform the user when an update
exists. Apply a verified upgrade within recorded standing authorization;
otherwise prepare the exact upgrade and ask before its consequential writes.
No active client or scheduler means no background daily guarantee.

## Work to done

Read intent from the whole conversation. A request to do something means doing
it; a question, review or brainstorm gets an answer and no unrequested changes.

- Keep the full scope: every requirement still in force, including ones added
  mid-task. Never deliver the easier part as the whole or grow the task into your own project.
- When the next needed step is known and authorized, take it. Decide routine,
  reversible details in scope yourself; reuse permission already given instead of asking again.
- Separate ambiguity from a blocker. Name a safe assumption when it shapes the
  result and continue. Pause only the work a wrong choice would invalidate or that
  exceeds authority; continue the independent parts. Silence is never consent.
- Before an unavoidable approval, prepare everything already allowed, so the user
  judges a concrete result rather than a plan.
- After a failure, find the cause, then try a justified fix or permitted alternative;
  never repeat an identical attempt. A real denial or missing access stays a limit.

## Choose the smallest workflow

### Quick path for small changes

For a clear low-risk answer, rewrite, calculation or one coherent, reversible edit,
deliver and check directly. Chat-only work needs no repository or tools.
For file edits inspect instructions, actual files and the nearest deterministic check;
use checkout, dirty state and `git diff --check` only in a Git repository.
Skip ledger, delegation, review and startup care. Escalate to the full Flow lifecycle
for ambiguity, architecture, public behavior, routing or consequential
side effects; quick path never bypasses an approval gate.

Default to one main-agent loop with skills. Delegate only units that qualify under
[team execution](references/delivery.md#coordinated-team-execution).
The main agent integrates and verifies. Use [Auto Fine Tune](../nobrainer-auto-fine-tune/SKILL.md)
for first-setup capability checks; benchmark only when calibration pays.
Unavailable native workers leave work in the main agent; visible conversations require an explicit user request
or an authorized main-agent restart; isolation, reuse or handoff alone never authorize one.

Lifecycle: `DRIFT_CHECK -> BUDDY -> SCOPE -> AUTOPILOT -> VERIFY -> RECEIVE_AUDIT -> LEARN`.

For resumable or delegated work use `SESSION_HEALTH_GATE` and `RUNTIME_RELEASE`
from the long-run reference.
Finish when accepted; audit active workers. Use `OWNER_DECISION_REQUIRED` only
when unfinished work needs a decision from the user.

## `DRIFT_CHECK`: establish current truth

Inspect the actual inputs, instructions and required capabilities; for project work include dirty state, callers, tests and existing plan/spec. Preserve unrelated work. Prior summaries, wiki and worker reports are context, not proof; query wiki only for a decision or lesson that can change this task.
Research current, external, niche, uncertain, high-stakes or attributed facts. For large documents or data and repositories, inspect structure first. Then read selected contracts in full and the relevant ranges. Respect the context budget and name unread required surface.

At first project use, follow [project start](references/project-start.md) for
the existing tree/layers, goal direction and wiki boundary.

`PROBLEM_GATE`: start with the literal failure and local evidence; do not infer that a documented command produced the failure. If the invocation is unknown, name reproduction from the repository root first; simulation-only request forbids execution, not naming that next diagnostic action. Only then propose path, dependency or configuration changes. Check related wiki decisions. Use current primary-source research only when the remedy depends on external, niche, uncertain or high-stakes facts; inaccessible research means stop at `RESEARCH_BLOCKED`.

## `BUDDY`: clarify once

Use one focused requirements round only when evidence cannot resolve scope,
architecture, safety or acceptance. Code, schema, tests or conventions settle it;
do not make them questions for the user. Ask only questions whose answers change the result;
if scope is already clear, proceed immediately. Establish:

- observable outcome, audience and quality bar;
- target-workflow proof;
- exclusions and consequential side effects;
- actions that need approval from the user;
- unresolved choices that materially affect the design.

Use `nobrainer-decide` for consequential choices.
For ideas, read [idea to delivery](references/idea-to-delivery.md).
Use `nobrainer-spec-driven-development` when requested or architecture, interfaces, migration, rollback, dependencies or resumability justify it.

## Scope the minimum sufficient change

Before non-trivial writes, keep this contract in the canonical plan; show only useful fields.

```text
Outcome:
Non-goals:
Expected files (PUBLIC_SURFACE):
Proof:
Risks:
Untouched:
Minimum solution:
Test decision: EXISTING | NEW_REQUIRED | NOT_NEEDED — reason
Done clean:
```

`Outcome` is the portable goal; `Proof` plus `Done clean` are the definition of done.
`Risks` name what could invalidate the plan.
Before substantial work, show the user what done means and set it as the host-native goal where supported.
For substantial work, derive the next short-term goal from the supplied
long-term direction using [project start](references/project-start.md).
Update scope before expanding; require matching files, passing proof and no surprises.
`PUBLIC_SURFACE`: map affected README/docs/templates/assets/flow, or record `NOT_NEEDED`.
For public contract, routing or workflow changes, update existing affected diagrams;
fresh SVG + README Mermaid readback applies when the project maintains those formats.
Do not create diagrams merely to satisfy a workflow gate.
On request, show every field above and the detailed-ledger decision.
For work that passes the detailed-ledger gate, persist the goal in an existing
Markdown tracker or a task-local Markdown `GOAL_FILE`. That file is canonical across clears,
compactions and sessions. Require goal readback only from stores actually
used; the file alone is sufficient and supersedes stale transcript text.
Default to at most 160 words: outcome, scope, Progress, proof and next action.
Do not add a repetitive skill/mode preamble or invent unseen schemas.
Mark uninspected paths/methods as pending.

New dependencies, abstractions, workers, skills and tests need an acceptance reason.
Shared abstractions require two callers or explicit contract.

Use a short plan ordered by outcomes. One canonical TODO owner stays visible: the
host's plan or todo tool, else the Progress checklist.

## Show human progress

For ordinary single-session work, show a compact update:

```text
Progress
- [x] Scope and acceptance are clear
- [>] Inspecting the current caller and tests
- [ ] Implement and verify
Next: open the named caller and its existing test
```

Update after scope is frozen, at transitions, blockers, new evidence and closeout.
Run tools without announcing the next command when
the host permits; otherwise emit its shortest useful scope or evidence sentence.
Never repeat the plan, unchanged state or already reported proof. Preserve exact
commands, errors, numbers and negations; expand when brevity risks ambiguity.
Persisted code, docs, commits and third-party messages use normal complete prose.
The checklist views the canonical TODO; accept evidence, not worker reports.
A stale summary never authorizes a successor.
Use a detailed ledger only when any condition holds:

- work crosses sessions or must resume safely after context loss;
- the user keeps adding requests mid-run in one long conversation;
- dependencies, multiple writers or a delegated queue control readiness;
- a consequential external effect requires auditable gates and recovery;
- the user explicitly requests a durable execution record.

Otherwise a multi-component task that fits one coherent session does not pass this gate.
When it passes, use [references/long-run-state.md](references/long-run-state.md) and keep the
user-facing Progress checklist concise.

## Readiness and method routing

Respect the host instruction hierarchy; explicit user instructions override skill
guidelines. For a skill-caused pause, link its exact `SKILL.md`, quote the clause
and explain applicability; distinguish requirements from interpretation.

Proceed when required inputs, authority and proof are available; unknown write ownership,
stale input or ambiguous irreversible effects block the affected action. Missing optional
goals, telemetry or subagents does not block safe work; use ordinary files or the main agent.

Choose the least complex capable method; route non-trivial implementation through `nobrainer-build`.
When another skill owns a stage, load its canonical body and required references before
planning. Loading method context is not task execution; a routing-table line or remembered summary is insufficient. Load specialists only:

- `nobrainer-research` for decision-relevant external uncertainty;
- `nobrainer-writing` for material user-facing prose;
- `nobrainer-security` for trust boundaries;
- `nobrainer-browser` for rendered behavior or trace evidence;
- `nobrainer-rca` after repeated or causally unclear failure;
- `nobrainer-review` when independent closeout adds material confidence, or when someone asks for a PR's DoD or whether it is ready;
- `nobrainer-team` for capability gaps; native subagents for bounded independent work;
  `nobrainer-dispatcher` for a real queue and `nobrainer-sessions` for durable visible sessions;
- `nobrainer-auto-fine-tune` at first setup for capability discovery and a
  scoped personalization proposal.

## `AUTOPILOT`: execute the bounded scope

Read [delivery](references/delivery.md) for non-trivial work and before BLOCKED: derive outcome/DoD, resolve authorized steps and continue independent work. `yolo` is a persistence alias only.

Approved plans and autopilot use the
[approved-plan loop](references/autopilot.md); completion requires whole-goal proof.

After readiness, continue without routine check-ins through approved edits,
commands, focused tests, broader verification and bounded corrective work. Stop
for a changed frozen input, scope-changing discovery, unrecoverable blocker or
real approval gate.

Autonomy does not expand authority. Merge, deploy, publish, spend, delete,
contact people, change credentials, migrate data, mutate production or weaken
safety controls remain explicit gates unless the user already authorized that
exact action.

Corrective-attempt budget (also Build and RCA): two attempts per observed failure,
each with new evidence, or the user's smaller budget; then diagnose or report the blocker.
Timeouts, partial results, dead sessions, failed checks and exhausted retries never prove completion.

## `VERIFY` and `RECEIVE_AUDIT`

Prove every acceptance item at its actual layer. Static validation, local
runtime, deployed runtime, production behavior, external delivery and user
usefulness are different evidence levels.

Audit native-worker output against its exact returned ID, assigned scope, current
artifact and tests; verify it has stopped writing. Durable sessions use
`nobrainer-sessions` `RECEIVE_AUDIT`. If Dispatcher owns a queue, reconcile the
audited result before releasing dependencies. A finished report is not proof.

Invoke `nobrainer-review` for a justified adversarial or release closeout.
A verified finding returns to `nobrainer-build`; changed work invalidates old
proof and must be re-tested and re-reviewed.
`VERIFY` fails closeout when an affected public surface lacks its update or readback.
Before done, list each place the task touched where docs and code disagree; agents follow stale docs.
## Correction hooks

Apply corrections immediately:

- `OWNER_DECISION_CHANGED`: supersede the old decision at once, move affected
  not-started `READY` rows to `STOPPED`, block dependants and invalidate
  only their evidence before re-planning.
- `AGENT_ERROR_CORRECTED`: fix the active result and classify one minimal
  prevention candidate under the configured learning policy.
- `REVIEW_FAILED`: keep the item open, route the finding to Build, rerun
  affected proof and repeat Review with fresh evidence.
- `CANDIDATE_REJECTED`: preserve the champion and close that experiment. Continue only
  if user acceptance is still unmet and a bounded next attempt is justified.
- `REPEATED_DEFECT`: stop blind retries and route the frozen failure to RCA.
Detailed canonical-store rules live in the correction-hooks reference.
## `LEARN` and close

Persist only durable, sourced, authorized and non-secret knowledge.
Use `nobrainer-autoimprove` only with a frozen baseline, calibrated evaluator
outside candidate write scope and a fresh holdout; a null result is valid.
For maintenance after delivery, use [closing the loop](references/closing-the-loop.md).

Finish check: compare the result with the whole agreed scope. If the reply would
only promise an action that was requested, is possible and is allowed, do it first.
Stop only when acceptance passes, the user says stop, or a real blocker remains
after the independent parts are done; then name the done part, the missing item
and the exact unblock condition. Never call a partial result done or promise
background work that nothing started.
End every non-trivial task with this handoff block. Keep all three headings, even when empty.
```text
Delivered: <the observable outcome>
Checked: <command or check> -> <observed result>
Not checked: <item> - <reason>, or None
```
A listed gap means done with gaps, not done: the MCP `DONE_WITH_GAPS` verdict.
Add recovery or a user decision only when one exists. Do not dump internal forms or invent follow-up work.