Case study 02
StackBrief
The architectural brief before a code change. An offline, source-cited CLI for developers and coding agents.
Problem
The hard part of a change is rarely typing the code. It is rebuilding enough of the system in your head to change it safely. READMEs drift, and architecture is spread across routes, services, manifests and someone's memory. Coding agents have the same problem, only faster.
Product direction
Start from a concrete file, not an abstract question about the whole repository. Trace observable evidence (imports, routes, services, databases, external APIs) and report it with file and line citations. Say plainly what static analysis cannot prove.
My role
Creator and maintainer: product, architecture, all seven packages, documentation and website.
Engineering approach
stackbrief scanwritesstackbrief.json, a deterministic, schema-versioned model of the repository. Every later capability builds on this one model rather than keeping a parallel view.stackbrief brief --filetraces from the selected file: route and service boundaries, reached local files, direct dependents, database and API integrations, connected tests and static unknowns.- A typed intelligence layer answers queries over the model. The renderer keeps briefs short enough to read before an edit.
stackbrief agent installgives Claude, Codex and others portable pre-change instructions, without tying the tool to any vendor.
Stack and constraints
- Packages
- scannerknowledgeintelligencebriefclicoretypes
- Runtime
- TypeScriptNode.js ≥ 16.7npm
- Contract
- stackbrief.json · schemaVersion 2
- Agents
- Portable pre-change skill (Claude, Codex)
- No account, API key, hosted model or network connection.
- Must never execute application code.
- Output must be useful to a human in under a minute and parseable by an agent.
Design decisions
Local-first as a privacy boundary
Scanning, the knowledge model and brief rendering make no telemetry or AI requests, so the tool is safe to run on private code.
Unknowns are first-class output
Dynamic imports, runtime configuration and missing test links are reported as unknowns. That is more honest than confident prose.
One canonical model
A single versioned JSON contract keeps scan, query and brief consistent, and makes the output usable offline and in CI.
System
Outcome and status
- v1.1.2 published on npm (2026-07-18); live download figures in the tools section.
- Built for OpenAI Build Week 2026, with a reproducible judge guide (JUDGES.md). The result was not published.
- Used on real repositories: the lab's constellation is drawn from StackBrief output on mojeebdev/outship.