dsb-117/brainblast/codex-skill

Brainblast

Research every external component in a requirements file before an agent starts coding. Produces .agent-research/runs/YYYYMMDD-HHMMSS/ with per-component notes and a final handoff report.

Incremental runs (caching). Research is cached per component, keyed by name@version, in

.agent-research/cache/. A re-run reuses cached components whose version is unchanged and

re-researches only what changed. Components with no resolvable version are always re-researched.

Pass --fresh (or set BRAINBLAST_FRESH=1) to ignore the cache. The cache is documentation only

and safe to delete.

Preamble (run first)

# Browse setup — Codex gstack path
GSTACK_ROOT="$HOME/.codex/skills/gstack"
_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
[ -n "$_REPO_ROOT" ] && [ -d "$_REPO_ROOT/.agents/skills/gstack" ] && GSTACK_ROOT="$_REPO_ROOT/.agents/skills/gstack"
B="$GSTACK_ROOT/browse/dist/browse"
if [ -x "$B" ]; then
  echo "BROWSE_READY: $B"
else
  echo "BROWSE_MISSING"
fi
 
# Run directory + persistent component cache
_RUN_DIR="$(pwd)/.agent-research/runs/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$_RUN_DIR/components"
_CACHE_DIR="$(pwd)/.agent-research/cache"
mkdir -p "$_CACHE_DIR"
_FRESH="${BRAINBLAST_FRESH:-0}"   # set to 1 if the invocation included --fresh
_CI="${BRAINBLAST_CI:-0}"         # set to 1 if the invocation included --ci
echo "RUN_DIR: $_RUN_DIR"
echo "CACHE_DIR: $_CACHE_DIR  (fresh=$_FRESH)"
echo "DATE: $(date +%Y-%m-%d)  (ci=$_CI)"

CI mode + gate. In --ci mode (_CI=1, or BRAINBLAST_CI=1) run non-interactively: never ask a question or wait. On multiple requirement-file matches, pick the highest-precedence one deterministically (requirements > prd > spec > brief > rfc > product > design-doc > overview > scope > functional, then lexicographic) and say which; if none, stop BLOCKED and write no report.json. Don't prompt for inventory confirmation. The pipeline's exit code comes from the deterministic gate scripts/brainblast-gate.sh (Brainblast repo), which fails when a risk at/above --fail-on (default critical) remains or the verdict is blocked; state PASS/FAIL yourself after writing the report.

If BROWSE_MISSING: tell the user Brainblast requires gstack for Codex. Run: git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.codex/skills/gstack && cd ~/.codex/skills/gstack && ./setup --host codex Do not proceed without browse.

Set $B and $_RUN_DIR from preamble output. Use them throughout.

Step 0 — Locate requirements

Args: If invoked with a file path (e.g. brainblast prd.md), use it directly. Ignore control tokens (--fresh, --ci, --fail-on=…) when resolving the path — they are flags, not filenames. (See CI mode in the preamble for --ci behavior.)

Otherwise, auto-detect:

find . -maxdepth 2 \( \
  -iname "requirements*" -o -iname "prd*" -o -iname "spec*" -o -iname "brief*" \
  -o -iname "product*" -o -iname "design-doc*" -o -iname "rfc*" \
  -o -iname "overview*" -o -iname "scope*" -o -iname "functional*" \
\) -not -path '*/node_modules/*' -not -path '*/.git/*' \
   -not -path '*/.agent-research/*' 2>/dev/null | sort

Decision rules:

1. Exactly one file found → use it, tell the user which file was picked
2. Multiple files found → output the list and ask the user to reply with the correct file before continuing
3. Nothing found → list any .md files in the project root, ask the user which to use; if none, ask the user to create a spec file or pass a path

Save a copy to $_RUN_DIR/requirements.md.

Step 1 — Component inventory

Read the requirements. Identify every external system involved:

• REST APIs and GraphQL endpoints
• SDKs and client libraries (any language)
• Authentication providers (OAuth, API keys, JWT issuers)
• Databases (if a specific managed service or third-party DB is named)
• Payment processors
• Messaging and queueing services
• Cloud platforms and deployment targets
• Storage services
• Blockchain networks and on-chain programs
• Third-party analytics, monitoring, or logging services
• Any named external protocol or standard with a versioned spec

Do not include: generic language features, the standard library, or internal modules.

For each component: Name, Type (API / SDK / Auth / Database / Infra / Blockchain / Other), Version, Role (one sentence), Confidence (High = explicitly named / Medium = strongly implied / Low = inferred).

Resolve the version (it keys the cache in Step 3): exact pinned version from a repo lockfile (package-lock.json, poetry.lock, Cargo.lock, go.mod, …) if present; else the latest version number on the package registry; else an API version string (dated version, v2 path, version header); else unversioned.

Write to $_RUN_DIR/component-inventory.md:

# Component Inventory
 
| Component | Type | Version | Role | Confidence |
|---|---|---|---|---|
| [name] | [type] | [version or `unversioned`] | [role] | [High/Medium/Low] |

Output the inventory to the user. If corrections are needed, wait for a reply before continuing. If no reply is possible, proceed and note the inventory as an assumption.

Step 2 — Research plan

For each component, list exact URLs to check:

• Any: official docs homepage, changelog
• SDK/library: package registry (npm, PyPI, crates.io…), GitHub releases
• API: auth docs, rate limits page, versioning/migration guide
• Auth provider: OAuth flow docs, token expiry and refresh docs
• Blockchain: program ID page, mainnet vs devnet availability
• Cloud/infra: pricing page (for quota limits), region constraints

Write to $_RUN_DIR/research-plan.md.

Step 3 — Research (one component at a time)

For each component, check the cache first — only browse on a miss.

3·0 — Cache check (incremental runs)

Build a filename-safe key from name@version:

_key="$slug@$ver"
_safe=$(printf '%s' "$_key" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9.@_-' '-')
_cache_file="$_CACHE_DIR/$_safe.md"

• _FRESH=1, or $ver is unversioned → MISS (re-research; overwrite cache on a versioned miss).
• $_cache_file exists → HIT: cp "$_cache_file" "$_RUN_DIR/components/$slug.md", tell the user it was reused (with the fetched date from the file's <!-- BRAINBLAST:CACHE --> header), and skip 3a–3d.
• Otherwise → MISS: browse it fresh below.

Record the disposition (HIT / MISS-new / MISS-changed / MISS-fresh / MISS-unversioned) for the report and summary. This is how only what changed gets re-researched: an unchanged name@version is reused; a bumped version or new component is a new key.

3a — Browse (cache MISS only)

Check [domain]/llms.txt first if it exists — it indexes all doc pages. Then browse auth, core workflow, rate limits, SDK install/version, breaking changes, and migration notes.

Use $B goto URL and $B text to fetch and read pages.

3b — Extract

Facts — from official docs, each with a source URL. Assumptions — likely true but not explicitly stated. Inferences — derived from facts; note which facts they follow from. Risks — CRITICAL / HIGH / MEDIUM / LOW. CRITICAL = failure is invisible until too late (zero-revenue config, immutable wrong choice, deprecated endpoint that still accepts requests).

3c — Answer every question

For each question that surfaces: browse to answer it before recording it. If unanswerable after 2 sources: record as "Unresolvable from public sources — [where you looked]".

3d — Write component file

Write to $_RUN_DIR/components/[slug].md:

# Component: [Name]
 
**Date checked:** [YYYY-MM-DD]
**Sources:**
-[description]: [URL]
 
---
 
## Facts
[bullet list — each fact cites a source URL]
 
## Assumptions
[bullet list]
 
## Inferences
[bullet list — notes which facts each follows from]
 
## Risks
**[CRITICAL/HIGH/MEDIUM/LOW] — [title]**
[one paragraph: the failure mode, why it's hard to detect, correct behavior]
 
## Resolved questions
**[Question]**
[Answer with source URL]

Then, unless $ver is unversioned, write the cache file so the next run can reuse it:

if [ "$ver" != "unversioned" ]; then
  { printf '<!-- BRAINBLAST:CACHE slug=%s version=%s fetched=%s -->\n' "$slug" "$ver" "$(date +%Y-%m-%d)"
    cat "$_RUN_DIR/components/$slug.md"; } > "$_cache_file"
fi

Tell the user when each component is done: one line — "Done: [name] — [key fact or risk]".

Step 4 — Coverage review

For each component, verify the notes cover: auth method, install command and version, rate limits, breaking changes in the last 12 months, at least one risk. Address gaps before continuing.

Write to $_RUN_DIR/coverage-review.md.

Step 5 — Requirements re-review

Re-read the original requirements with everything learned. Flag:

• Missing constraints — things assumed but not stated
• Wrong assumptions — things implied that are not true
• Underspecified decisions — choices the implementer will face that are not covered
• Immutable choices — things that cannot be changed after deploy that are not mentioned
• Sound — requirements confirmed correct

Write to $_RUN_DIR/requirements-rereview.md.

Step 6 — Final report

Write $_RUN_DIR/final-report.md:

# Brainblast Research Report
 
**Run:** [YYYYMMDD-HHMMSS]
**Requirements:** [one-line summary]
**Date:** [YYYY-MM-DD]
 
---
 
## Executive Summary
 
*The 30-second version.*
 
-**Building:** [one line — what the integration does]
-**Verdict:** [Ready to build / Build with caution / Blocked] — [half-sentence why]
-**Top risk:** [the single most important CRITICAL/HIGH item, one line]
-**Must decide first:** [the one irreversible pre-coding decision, or "none"]
-**Watch out for:** [the biggest spec gap or effort surprise, or "none"]
 
---
 
## Risk Heatmap
 
| Component | 🔴 Critical | 🟠 High | 🟡 Medium | 🟢 Low |
|---|---|---|---|---|
| [name] | [n] | [n] | [n] | [n] |
| **Total** | **[n]** | **[n]** | **[n]** | **[n]** |
 
**Critical & High, by name:**
1.**[CRITICAL] [component] — [title]** — one-line failure mode
2.**[HIGH] [component] — [title]** — one-line failure mode
 
Counts come straight from the per-component `## Risks` sections.
 
---
 
## Components researched
 
| Component | Version | Source found | Status |
|---|---|---|---|
| [name] | [version] | [URL] | Fresh this run / Reused from cache (fetched [date]) / Partially verified / Official source not found |
 
---
 
## What a coding agent must know before starting
[Numbered list — concrete, actionable facts. Lead with silent failures and irreversible mistakes.]
 
---
 
## Pre-coding decisions required
[Anything that must be decided before coding because it cannot be changed after deploy.]
 
---
 
## Requirements corrections
[What the requirements got wrong, missed, or underspecified.]
 
---
 
## What this report prevents
[2-4 bullets on specific failure modes the research caught.]

Step 6b — Machine-readable report (report.json)

Also write $_RUN_DIR/report.json — the same findings as structured data for tools and CI gates. Stable, versioned contract (schemaVersion: "1.0"; schema at schema/report.schema.json in the Brainblast repo). All enums lowercase: verdict ∈ ready|caution|blocked; severity ∈ critical|high|medium|low; component status ∈ fresh|cached|partial|not_found (use cached for Step-3 HITs); type ∈ API|SDK|Auth|Database|Infra|Blockchain|Other.