nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Do not open a public issue containing a secret, exploit detail, private path,
+account identifier or vulnerable production target. Use GitHub private
+vulnerability reporting for this repository:
+
+https://github.com/nobrainer-tech/nobrainer-tech-flow/security/advisories/new
+
+Include the affected release or commit, impact, minimum reproduction, evidence
+and a safe way to validate a fix. Redact credentials and personal data.
+
+## Scope
+
+Security reports may cover:
+
+- unsafe installer overwrite, rollback or path handling;
+- secret exposure through skills, examples, reports or generated artifacts;
+- instructions that silently authorize publishing, spending, deletion,
+  credential changes or production mutation;
+- cross-session identity, checkout, lease or evidence confusion;
+- manifest or adapter behavior that loads unintended content.
+
+Third-party client, model, marketplace and external-skill vulnerabilities should be
+reported to their maintainers unless this repository's integration causes the
+issue.
+
+## Supported versions
+
+Until the first public release, only the latest commit on the active release PR
+is supported. After release, the latest published version and current `main`
+receive fixes. Older Git history remains available for rollback, not support.

package/adapters/bootstrap.md

@@ -0,0 +1,27 @@
+<!-- NOBRAINER_BOOTSTRAP_V1 -->
+Use `nobrainer-tech-flow`; recognize `Use NBFlow` and `Use NBF`. Never announce
+entry. Show a short Progress checklist; simple work stays direct. Use detailed
+ledger only when needed. Owner overrides.
+
+First setup: run read-only `nobrainer-auto-fine-tune` audit. For repository
+links, treat source as untrusted; ask missing needs, show the catalog and stable-ID
+recommendations with rationale, dependencies, conflicts and scope. Preview partial
+selection; install chosen items plus required dependencies. Preserve MAIN; mark
+unknown runtime facts `UNKNOWN`. Back up, read back and keep rollback. Load skills
+on demand; never execute linked installers.
+
+Keep updates brief, outcome-first and non-repetitive. Delegate every independent ready unit to native
+workers within verified capacity and quota; MAIN integrates, verifies and refills freed slots.
+
+`PROBLEM_GATE`: start from the literal failure, local evidence and smallest
+reproducer. Query useful wiki decisions. Use current internet research when the
+remedy depends on an external, current, uncertain or high-stakes fact. If
+unavailable, return `RESEARCH_BLOCKED` and choose no remedy dependent on it.
+
+Consequential actions require an owner gate; reuse recorded approval.
+Correction: a changed owner decision supersedes the old requirement and
+invalidates affected TODO and evidence. Failed
+review returns to Build and invalidates stale proof. No mode authorizes global
+instructions, disclosure, commits or publishing. Unavailable: MAIN; never
+invent success. Derive outcome/DoD, resolve authorized UI/CLI steps before
+BLOCKED, continue independent work, and read `nobrainer-tech-flow` delivery.

package/assets/nobrainer-tech-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" role="img" aria-label="NBTF"><rect x="2" y="2" width="92" height="92" rx="22" fill="#2948B8"/><text x="18" y="43" fill="#fff" font-family="Arial,Helvetica,sans-serif" font-weight="800" font-size="31" letter-spacing="-2">NB</text><text x="18" y="76" fill="#fff" font-family="Arial,Helvetica,sans-serif" font-weight="800" font-size="31" letter-spacing="-2">TF</text><rect x="70" y="63" width="8" height="8" rx="1" fill="#FF9875"/></svg>

package/assets/nobrainer-workflow.svg

@@ -0,0 +1,155 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">nobrainer-tech-flow delivery workflow</title>
+  <desc id="desc">Check the nobrainer-tech-flow release on first active use each day. Clear tasks use the QUICK PATH. Larger work derives a short-term goal from the owner's direction, inspects project layers and wiki, executes the authorized scope and verifies the result. Model policy preserves the selected MAIN model and effort. Native workers handle every useful independent ready unit within verified capacity and authorized usage. MAIN coordinates, integrates and verifies each result, then refills ready slots. Auto Fine Tune calibrates routes when useful; it is not a dispatch prerequisite. A Markdown GOAL_FILE supports recovery. A fresh session takes over before authorized archival of the old one. RUNTIME_RELEASE readback verifies owned workers. The full goal remains open until acceptance and delivery proof pass.</desc>
+  <defs>
+    <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0F1319"/>
+      <stop offset="1" stop-color="#141922"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#D94724"/>
+      <stop offset="1" stop-color="#2948B8"/>
+    </linearGradient>
+    <filter id="soft-shadow" x="-30%" y="-30%" width="160%" height="160%">
+      <feDropShadow dx="0" dy="12" stdDeviation="16" flood-color="#000" flood-opacity=".28"/>
+    </filter>
+    <marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M1 1l9 5-9 5z" fill="#5E6A80"/>
+    </marker>
+    <marker id="arrow-accent" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M1 1l9 5-9 5z" fill="#D94724"/>
+    </marker>
+    <style>
+      text{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+      .eyebrow{font-size:16px;font-weight:700;letter-spacing:3px;fill:#FF9875}
+      .headline{font-size:44px;font-weight:800;letter-spacing:-1.6px;fill:#F3EEE6}
+      .headline .accent{fill:#7F9BFF}
+      .subtitle{font-size:18px;fill:#AEB8C6}
+      .node{fill:#161B23;stroke:#2B3340;stroke-width:2}
+      .node-accent{fill:#161B23;stroke:#7F9BFF;stroke-width:2.4}
+      .node-title{font-size:18px;font-weight:800;letter-spacing:.6px;fill:#F3EEE6}
+      .node-copy{font-size:15px;fill:#AEB8C6}
+      .tiny{font-size:13px;font-weight:700;letter-spacing:1.2px;fill:#FF9875;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+      .flow{fill:none;stroke:#5E6A80;stroke-width:3;marker-end:url(#arrow)}
+      .flow-accent{fill:none;stroke:#D94724;stroke-width:3.2;marker-end:url(#arrow-accent)}
+      .flow-dashed{fill:none;stroke:#7F9BFF;stroke-width:2.5;stroke-dasharray:8 8;marker-end:url(#arrow)}
+      .chip{fill:#0F1319;stroke:#2B3340;stroke-width:1.5}
+      .chip-text{font-size:14px;font-weight:700;fill:#D3DAE4}
+      .chip-text-small{font-size:11.5px;font-weight:750;letter-spacing:.15px;fill:#D3DAE4}
+    </style>
+  </defs>
+
+  <rect width="1600" height="900" rx="0" fill="url(#background)"/>
+
+  <rect x="76" y="56" width="14" height="14" fill="#D94724"/><text x="100" y="70" class="eyebrow">nobrainer-tech-flow</text>
+  <text x="76" y="122" class="headline">From task <tspan class="accent">to done.</tspan> One request, clear progress, verified delivery.</text>
+  <text x="76" y="154" class="subtitle">Agents: plain technical English. User: requested language. Exact meaning and evidence stay intact.</text>
+
+  <g filter="url(#soft-shadow)">
+    <rect x="76" y="220" width="205" height="116" rx="0" class="node"/>
+    <text x="100" y="258" class="tiny">01 · INTENT</text>
+    <text x="100" y="289" class="node-title">OWNER REQUEST</text>
+    <text x="100" y="316" class="node-copy">Idea or task + constraints</text>
+
+    <rect x="335" y="220" width="205" height="116" rx="0" class="node"/>
+    <text x="359" y="258" class="tiny">ONLY IF UNCLEAR</text>
+    <text x="359" y="289" class="node-title">BUDDY</text>
+    <text x="359" y="316" class="node-copy">Material questions only</text>
+
+    <rect x="594" y="220" width="236" height="116" rx="0" class="node-accent"/>
+    <text x="618" y="258" class="tiny">03 · SCOPE THE MINIMUM</text>
+    <text x="618" y="289" class="node-title">SCOPE + PLAN</text>
+    <text x="618" y="316" class="node-copy">Spec if needed · criteria · proof</text>
+
+    <rect x="884" y="220" width="205" height="116" rx="0" class="node"/>
+    <text x="908" y="258" class="tiny">04 · AUTHORIZED?</text>
+    <text x="908" y="289" class="node-title">READY</text>
+    <text x="908" y="316" class="node-copy">Scope · proof · inputs</text>
+  </g>
+
+  <path d="M281 278H325" class="flow-dashed"/>
+  <path d="M178 220V185H712V210" class="flow-accent"/>
+  <text x="345" y="177" class="tiny">CLEAR OUTCOME → START</text>
+  <path d="M540 278H584" class="flow"/>
+  <path d="M830 278H874" class="flow"/>
+  <path d="M1089 278H1148V382" class="flow-accent"/>
+
+  <g>
+    <rect x="1160" y="204" width="354" height="148" rx="0" fill="#161B23" stroke="#2B3340" stroke-width="2"/>
+    <text x="1186" y="238" class="tiny">SPECIALISTS · WHEN USEFUL</text>
+    <rect x="1186" y="260" width="137" height="34" rx="0" class="chip"/>
+    <text x="1207" y="282" class="chip-text">RESEARCH</text>
+    <rect x="1335" y="260" width="151" height="34" rx="0" class="chip"/>
+    <text x="1371" y="282" class="chip-text">DECIDE</text>
+    <rect x="1186" y="304" width="90" height="34" rx="0" class="chip"/>
+    <text x="1211" y="326" class="chip-text">SDD</text>
+    <rect x="1288" y="304" width="198" height="34" rx="0" class="chip"/>
+    <text x="1300" y="326" class="chip-text-small">READY NATIVE WORKERS</text>
+  </g>
+
+  <g filter="url(#soft-shadow)">
+    <rect x="340" y="430" width="245" height="124" rx="0" class="node-accent"/>
+    <text x="366" y="468" class="tiny">05 · IMPLEMENT</text>
+    <text x="366" y="501" class="node-title">BUILD</text>
+    <text x="366" y="529" class="node-copy">KISS · DRY · SOLID · YAGNI</text>
+
+    <rect x="690" y="430" width="245" height="124" rx="0" class="node"/>
+    <text x="716" y="468" class="tiny">06 · WHEN USEFUL</text>
+    <text x="716" y="501" class="node-title">REVIEW</text>
+    <text x="716" y="529" class="node-copy">Acceptance + evidence</text>
+
+    <rect x="1040" y="430" width="245" height="124" rx="0" class="node"/>
+    <text x="1066" y="468" class="tiny">07 · PROVE</text>
+    <text x="1066" y="501" class="node-title">VERIFY</text>
+    <text x="1066" y="529" class="node-copy">Target workflow evidence</text>
+
+    <rect x="1338" y="430" width="186" height="124" rx="0" class="node-accent"/>
+    <text x="1364" y="468" class="tiny">08 · RESULT</text>
+    <text x="1364" y="501" class="node-title">DELIVER</text>
+    <text x="1364" y="525" class="tiny">RUNTIME_RELEASE</text>
+    <text x="1364" y="549" class="node-copy">Separate readback</text>
+  </g>
+
+  <path d="M1148 352V392H462V420" class="flow-accent"/>
+  <text x="870" y="384" class="tiny">AUTOPILOT · READY TASK → EXECUTE → CHECK</text>
+  <path d="M585 492H680" class="flow-accent"/>
+  <path d="M935 492H1030" class="flow-accent"/>
+  <path d="M1285 492H1328" class="flow-accent"/>
+
+  <g id="review-fix-loop">
+    <path d="M812 554V620H462V564" class="flow-dashed"/>
+    <text x="598" y="649" class="tiny" style="fill:#7F9BFF">VERIFIED FINDING → BOUNDED FIX → FRESH REVIEW</text>
+  </g>
+
+  <g id="next-ready-loop">
+    <path d="M1158 554V590H462V564" class="flow-dashed"/>
+    <text x="850" y="617" class="tiny" style="fill:#7F9BFF">MORE READY WORK → NEXT TASK</text>
+  </g>
+
+  <g filter="url(#soft-shadow)">
+    <rect x="985" y="710" width="300" height="112" rx="0" class="node"/>
+    <text x="1011" y="748" class="tiny">OPTIONAL · DURABLE FACTS</text>
+    <text x="1011" y="781" class="node-title">LEARN</text>
+    <text x="1011" y="808" class="node-copy">Reuse existing docs and knowledge</text>
+
+    <rect x="76" y="710" width="610" height="112" rx="0" fill="#161B23" stroke="#D94724" stroke-width="2"/>
+    <text x="102" y="748" class="tiny" style="fill:#FF9875">CORRECTION HOOKS</text>
+    <text x="102" y="780" class="node-copy">Decision changed · agent corrected · review failed · defect repeated</text>
+    <text x="102" y="806" class="node-copy">Update one source of truth, invalidate affected work, resume at the safe stage.</text>
+  </g>
+
+  <path d="M1431 554V672H1135V700" class="flow-accent"/>
+  <path d="M686 766H975" class="flow-dashed"/>
+  <path d="M380 710V676H712V346" class="flow-dashed"/>
+
+  <g>
+    <rect x="76" y="366" width="230" height="110" rx="0" fill="#161B23" stroke="#7F9BFF" stroke-width="1.8"/>
+    <text x="98" y="394" class="tiny">QUICK PATH</text>
+    <text x="98" y="421" class="node-copy">Small + reversible</text>
+    <text x="98" y="445" class="node-copy">Answer · check · deliver</text>
+    <text x="98" y="468" class="tiny" style="fill:#FF9875">RISK → OWNER GATE</text>
+    <path d="M178 336V356" class="flow-accent"/>
+  </g>
+
+  <text x="76" y="870" class="subtitle">Autopilot: check → correct → next ready task. Finish when whole-goal proof passes.</text>
+</svg>

package/bin/nobrainer-tech-flow.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const root = new URL('../', import.meta.url);
+const metadata = JSON.parse(readFileSync(new URL('package.json', root), 'utf8'));
+const args = process.argv.slice(2);
+const help = [
+  'nobrainer-tech-flow ' + metadata.version, '',
+  'Preview: npx nobrainer-tech-flow --client codex',
+  'Install: npx nobrainer-tech-flow --client codex --apply',
+  'Undo:    npx nobrainer-tech-flow --client codex --undo --apply', '',
+  'Clients: codex, claude (Claude Code), opencode, copilot.',
+  'Use --home PATH for an isolated profile. Python 3.11+ is required for installation.',
+  'Nothing is installed until --apply. Applied installs retain this release in',
+  "your profile's .nobrainer-tech-flow-npm directory, so skills survive npx cache cleanup.",
+  'Undo uses the existing managed setup record; it preserves foreign files.',
+  'For Claude Chat, use the release plugin ZIP. ChatGPT/Codex plugin setup:',
+  'https://github.com/nobrainer-tech/nobrainer-tech-flow/blob/main/docs/CHAT_PLUGINS.md', ''
+].join('\n');
+if (!args.length || args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(help);
+} else if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+  console.log(metadata.version);
+} else {
+  const candidates = process.platform === 'win32'
+    ? [['py', ['-3']], ['python', []], ['python3', []]]
+    : [['python3', []], ['python', []]];
+  let chosen;
+  for (const [executable, prefix] of candidates) {
+    const check = spawnSync(executable, [...prefix, '-c',
+      'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)'],
+      { stdio: 'ignore', timeout: 5000 });
+    if (check.status === 0) { chosen = [executable, prefix]; break; }
+  }
+  if (!chosen) {
+    console.error('Python 3.11+ is required. Install Python from python.org, then repeat this command.');
+    process.exitCode = 2;
+  } else {
+    const [executable, prefix] = chosen;
+    const run = spawnSync(executable,
+      [...prefix, fileURLToPath(new URL('scripts/npm_install.py', root)), ...args],
+      { stdio: 'inherit', env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' } });
+    if (run.error) { console.error('Installer could not start: ' + run.error.code); process.exitCode = 2; }
+    else process.exitCode = run.status ?? 2;
+  }
+}

package/docs/BOUNDED_RUNNER.md

@@ -0,0 +1,60 @@
+# Bound one command
+
+The optional helper at `skills/nobrainer-sessions/scripts/run_bounded.py` runs
+one explicit command under a wall-time limit and a combined stdout/stderr
+capture limit. It uses Python 3.11+ and POSIX process groups, with no extra
+package, daemon or hook installation. It ships inside the Sessions skill so
+copy installations retain the helper. Windows is explicitly unsupported.
+
+From a reviewed checkout, run this harmless example. Choose a fresh receipt
+path; the runner refuses existing files, directories and symlinks.
+
+```bash
+python3 skills/nobrainer-sessions/scripts/run_bounded.py \
+  --wall-seconds 5 --max-output-bytes 4096 \
+  --receipt ./example-receipt.json -- \
+  python3 -c 'print("checked command")'
+```
+
+Inspect the receipt and exit status. `completed` means the command exited zero
+within the limits; it does not mean its output is correct or the task accepted.
+The receipt records configured limits, observed and retained output bytes,
+elapsed time, process exit/signal and cleanup attempts. It omits argv by default.
+Use `--record-argv` only for non-sensitive arguments. Output and working-directory
+paths may still be sensitive; keep receipts in the appropriate project location.
+
+## A timeout is not success
+
+Use another fresh receipt path:
+
+```bash
+python3 skills/nobrainer-sessions/scripts/run_bounded.py \
+  --wall-seconds 0.2 --max-output-bytes 4096 \
+  --receipt ./timeout-receipt.json -- \
+  python3 -c 'import time; time.sleep(30)'
+```
+
+The runner should return 124 and record `timed_out`. Output overflow returns
+125 and `output_limit`; other command failures remain failures. Inspect the
+receipt to disambiguate a child that itself returns 124 or 125. Setup/runner
+errors return nonzero and may have no receipt; absence is never success.
+
+## Exact boundary
+
+- Limits apply only to this invocation, not other host tools or model turns.
+- The runner owns a new POSIX process group. It can terminate members of that
+  group; a process deliberately creating a new session can escape that group.
+- It is not a sandbox: the child retains the caller's filesystem, network and
+  environment authority. Run only already-authorized commands.
+- Token count, model context, provider cost and total RAM are not measured or
+  capped. Receipts mark model tokens and cost UNKNOWN.
+- Stdin is closed. Interactive login, browser sessions and persistent services
+  should use the appropriate host tool rather than this command guard.
+- Capture is bounded; total execution includes a short termination/drain grace
+  period. Output forwarding to a blocked downstream consumer is not a promise
+  about the consumer's responsiveness.
+- No automatic retries, model switches, installation or task acceptance follow
+  from a receipt. Inspect the failure and decide the next authorized action.
+
+Remove the helper's invocation to roll back; no global setting was changed.
+The tests execute real child processes and are separate from model evaluations.

package/docs/CHAT_PLUGINS.md

@@ -0,0 +1,29 @@
+# ChatGPT and Claude plugins
+
+nobrainer-tech-flow is one workflow of 18 modules for research, writing, planning and implementation, packaged as a portable plugin. The AI client loads the workflow and uses its available tools and permissions.
+
+## Download and install
+
+Download the plugin ZIP from the latest GitHub Release. It contains root plugin.json, an OpenAI compatibility manifest, a Claude compatibility manifest and the canonical skills with their references. The submission ZIP omits lifecycle hooks and app references. Claude Code's existing Git marketplace installation remains available separately.
+
+In Claude, open Customize > Plugins, choose Add > Upload plugin and select the ZIP. Skills are supported in Chat, Cowork and Claude Code; available tools and permissions differ. Start a new conversation and ask: "Use nobrainer-tech-flow. Compare these options against my requirements and explain your recommendation with sources."
+
+In ChatGPT Work or Codex, install from a supported local/repository marketplace or from the public Plugins directory once the listing is approved. The repository marketplace identifies this source package. A downloadable ZIP is a release artifact, not proof of directory approval. OpenAI's public directory requires a verified developer identity, package scans and platform review before publication.
+
+Once the npm package is published (it is not yet), it can also serve as a plugin source. A marketplace can then reference source type npm, package nobrainer-tech-flow and an exact published version. The client downloads the package without running npm lifecycle scripts.
+
+## Check the installation
+
+Use a fresh conversation and confirm the loaded module's name and version. Try a bounded research or writing task, then check that the final result includes its evidence and remaining gaps. Loading metadata or passing a package test does not establish task quality in every client.
+
+If browser, shell, workers or local files are unavailable, the workflow must report that limit and use the permitted path. Installing a skill does not grant those capabilities, authorize publication or enable automatic model switching. Explicit user requirements and client policy remain authoritative.
+
+## Sources and distribution boundary
+
+- OpenAI plugin architecture: https://developers.openai.com/plugins/concepts/plugins
+- OpenAI package formats and npm sources: https://developers.openai.com/plugins/build/plugins
+- OpenAI publication: https://developers.openai.com/plugins/deploy/submission
+- Claude supported surfaces: https://claude.com/docs/plugins/platform-support
+- Claude publication: https://claude.com/docs/directory/publish
+
+The inFakt integration uses an MCP server and OAuth to access an existing account: https://www.infakt.pl/integracje-z-infakt-za-pomoca-api/#asystenci-ai . nobrainer-tech-flow currently needs skills and the client's existing tools, so this distribution does not add an MCP backend or require account access.