codex-skill

Name: codex-skill
Author: DSB-117

168stars2forks

How to install codex-skill?

dsb-117/brainblast/codex-skill

$npx -y skills add DSB-117/brainblast --skill codex-skill

Installs into the current project.

Summary

Research external APIs and SDKs before coding. Identifies every external component in a requirements file, browses official sources, and produces a structured handoff report with facts, risks, and answered questions.

Files · 1

View on GitHub

SKILL.md

1	# Brainblast
2
3	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.
4
5	> Incremental runs (caching). Research is cached per component, keyed by `name@version`, in
6	> `.agent-research/cache/`. A re-run reuses cached components whose version is unchanged and
7	> re-researches only what changed. Components with no resolvable version are always re-researched.
8	> Pass `--fresh` (or set `BRAINBLAST_FRESH=1`) to ignore the cache. The cache is documentation only
9	> and safe to delete.
10
11	## Preamble (run first)
12
13	```bash
14	# Browse setup — Codex gstack path
15	GSTACK_ROOT="$HOME/.codex/skills/gstack"
16	_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
17	[ -n "$_REPO_ROOT" ] && [ -d "$_REPO_ROOT/.agents/skills/gstack" ] && GSTACK_ROOT="$_REPO_ROOT/.agents/skills/gstack"
18	B="$GSTACK_ROOT/browse/dist/browse"
19	if [ -x "$B" ]; then
20	echo "BROWSE_READY: $B"
21	else
22	echo "BROWSE_MISSING"
23	fi
24
25	# Run directory + persistent component cache
26	_RUN_DIR="$(pwd)/.agent-research/runs/$(date +%Y%m%d-%H%M%S)"
27	mkdir -p "$_RUN_DIR/components"
28	_CACHE_DIR="$(pwd)/.agent-research/cache"
29	mkdir -p "$_CACHE_DIR"
30	_FRESH="${BRAINBLAST_FRESH:-0}" # set to 1 if the invocation included --fresh
31	_CI="${BRAINBLAST_CI:-0}" # set to 1 if the invocation included --ci
32	echo "RUN_DIR: $_RUN_DIR"
33	echo "CACHE_DIR: $_CACHE_DIR (fresh=$_FRESH)"
34	echo "DATE: $(date +%Y-%m-%d) (ci=$_CI)"
35	```
36
37	CI mode + gate. In `--ci` mode (`_CI=1`, or `BRAINBLAST_CI=1`) run non-interactively: never
38	ask a question or wait. On multiple requirement-file matches, pick the highest-precedence one
39	deterministically (`requirements` > `prd` > `spec` > `brief` > `rfc` > `product` > `design-doc` >
40	`overview` > `scope` > `functional`, then lexicographic) and say which; if none, stop BLOCKED and
41	write no `report.json`. Don't prompt for inventory confirmation. The pipeline's exit code comes from
42	the deterministic gate `scripts/brainblast-gate.sh` (Brainblast repo), which fails when a risk
43	at/above `--fail-on` (default `critical`) remains or the verdict is `blocked`; state PASS/FAIL
44	yourself after writing the report.
45
46	If `BROWSE_MISSING`: tell the user Brainblast requires gstack for Codex. Run:
47	`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.codex/skills/gstack && cd ~/.codex/skills/gstack && ./setup --host codex`
48	Do not proceed without browse.
49
50	Set `$B` and `$_RUN_DIR` from preamble output. Use them throughout.
51
52	---
53
54	## Step 0 — Locate requirements
55
56	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.)
57
58	Otherwise, auto-detect:
59
60	```bash
61	find . -maxdepth 2 \( \
62	-iname "requirements" -o -iname "prd" -o -iname "spec" -o -iname "brief" \
63	-o -iname "product" -o -iname "design-doc" -o -iname "rfc*" \
64	-o -iname "overview" -o -iname "scope" -o -iname "functional*" \
65	\) -not -path '/node_modules/' -not -path '/.git/' \
66	-not -path '/.agent-research/' 2>/dev/null \| sort
67	```
68
69	Decision rules:
70
71	1. Exactly one file found → use it, tell the user which file was picked
72	2. Multiple files found → output the list and ask the user to reply with the correct file before continuing
73	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
74
75	Save a copy to `$_RUN_DIR/requirements.md`.
76
77	---
78
79	## Step 1 — Component inventory
80
81	Read the requirements. Identify every external system involved:
82
83	- REST APIs and GraphQL endpoints
84	- SDKs and client libraries (any language)
85	- Authentication providers (OAuth, API keys, JWT issuers)
86	- Databases (if a specific managed service or third-party DB is named)
87	- Payment processors
88	- Messaging and queueing services
89	- Cloud platforms and deployment targets
90	- Storage services
91	- Blockchain networks and on-chain programs
92	- Third-party analytics, monitoring, or logging services
93	- Any named external protocol or standard with a versioned spec
94
95	Do not include: generic language features, the standard library, or internal modules.
96
97	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).
98
99	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 ver

People who liked this also viewed

6 picks

Type

codex-skill

168stars2forks

View on GitHub

How to install codex-skill?

dsb-117/brainblast/codex-skill

$npx -y skills add DSB-117/brainblast --skill codex-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Brainblast
2
3	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.
4
5	> Incremental runs (caching). Research is cached per component, keyed by `name@version`, in
6	> `.agent-research/cache/`. A re-run reuses cached components whose version is unchanged and
7	> re-researches only what changed. Components with no resolvable version are always re-researched.
8	> Pass `--fresh` (or set `BRAINBLAST_FRESH=1`) to ignore the cache. The cache is documentation only
9	> and safe to delete.
10
11	## Preamble (run first)
12
13	```bash
14	# Browse setup — Codex gstack path
15	GSTACK_ROOT="$HOME/.codex/skills/gstack"
16	_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
17	[ -n "$_REPO_ROOT" ] && [ -d "$_REPO_ROOT/.agents/skills/gstack" ] && GSTACK_ROOT="$_REPO_ROOT/.agents/skills/gstack"
18	B="$GSTACK_ROOT/browse/dist/browse"
19	if [ -x "$B" ]; then
20	echo "BROWSE_READY: $B"
21	else
22	echo "BROWSE_MISSING"
23	fi
24
25	# Run directory + persistent component cache
26	_RUN_DIR="$(pwd)/.agent-research/runs/$(date +%Y%m%d-%H%M%S)"
27	mkdir -p "$_RUN_DIR/components"
28	_CACHE_DIR="$(pwd)/.agent-research/cache"
29	mkdir -p "$_CACHE_DIR"
30	_FRESH="${BRAINBLAST_FRESH:-0}" # set to 1 if the invocation included --fresh
31	_CI="${BRAINBLAST_CI:-0}" # set to 1 if the invocation included --ci
32	echo "RUN_DIR: $_RUN_DIR"
33	echo "CACHE_DIR: $_CACHE_DIR (fresh=$_FRESH)"
34	echo "DATE: $(date +%Y-%m-%d) (ci=$_CI)"
35	```
36
37	CI mode + gate. In `--ci` mode (`_CI=1`, or `BRAINBLAST_CI=1`) run non-interactively: never
38	ask a question or wait. On multiple requirement-file matches, pick the highest-precedence one
39	deterministically (`requirements` > `prd` > `spec` > `brief` > `rfc` > `product` > `design-doc` >
40	`overview` > `scope` > `functional`, then lexicographic) and say which; if none, stop BLOCKED and
41	write no `report.json`. Don't prompt for inventory confirmation. The pipeline's exit code comes from
42	the deterministic gate `scripts/brainblast-gate.sh` (Brainblast repo), which fails when a risk
43	at/above `--fail-on` (default `critical`) remains or the verdict is `blocked`; state PASS/FAIL
44	yourself after writing the report.
45
46	If `BROWSE_MISSING`: tell the user Brainblast requires gstack for Codex. Run:
47	`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.codex/skills/gstack && cd ~/.codex/skills/gstack && ./setup --host codex`
48	Do not proceed without browse.
49
50	Set `$B` and `$_RUN_DIR` from preamble output. Use them throughout.
51
52	---
53
54	## Step 0 — Locate requirements
55
56	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.)
57
58	Otherwise, auto-detect:
59
60	```bash
61	find . -maxdepth 2 \( \
62	-iname "requirements" -o -iname "prd" -o -iname "spec" -o -iname "brief" \
63	-o -iname "product" -o -iname "design-doc" -o -iname "rfc*" \
64	-o -iname "overview" -o -iname "scope" -o -iname "functional*" \
65	\) -not -path '/node_modules/' -not -path '/.git/' \
66	-not -path '/.agent-research/' 2>/dev/null \| sort
67	```
68
69	Decision rules:
70
71	1. Exactly one file found → use it, tell the user which file was picked
72	2. Multiple files found → output the list and ask the user to reply with the correct file before continuing
73	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
74
75	Save a copy to `$_RUN_DIR/requirements.md`.
76
77	---
78
79	## Step 1 — Component inventory
80
81	Read the requirements. Identify every external system involved:
82
83	- REST APIs and GraphQL endpoints
84	- SDKs and client libraries (any language)
85	- Authentication providers (OAuth, API keys, JWT issuers)
86	- Databases (if a specific managed service or third-party DB is named)
87	- Payment processors
88	- Messaging and queueing services
89	- Cloud platforms and deployment targets
90	- Storage services
91	- Blockchain networks and on-chain programs
92	- Third-party analytics, monitoring, or logging services
93	- Any named external protocol or standard with a versioned spec
94
95	Do not include: generic language features, the standard library, or internal modules.
96
97	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).
98
99	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 ver

People who liked this also viewed

6 picks

Type