StackBrief

The architectural brief before a code change.

Comment

StackBrief

Inspiration

StackBrief didn't begin as StackBrief.

It started as a much smaller idea called stack.md.

The original goal was simple: generate a concise summary of an unfamiliar repository so developers could quickly understand the technology stack.

As I kept iterating on the idea, I realized the real problem wasn't documentation.

Documentation already exists. READMEs exist. Architecture diagrams exist. AI can summarize repositories.

Yet developers still spend hours trying to answer questions like:

  • What happens if I change this file?
  • Which services does this route depend on?
  • Does this touch a database?
  • Am I about to break an API?
  • What should I understand before making this change?

That realization completely changed the direction of the project.

Instead of generating another markdown document, I wanted to build something that helps developers understand software architecture before they change code.

That became StackBrief.

Its philosophy is simple:

Understand the architecture before you change the code.

What it does

StackBrief is an open-source, offline-first CLI that generates an architectural brief directly from a repository.

Instead of producing pages of documentation, it creates a concise, source-cited view of the change surface around a file.

It detects:

  • repository languages
  • frameworks
  • routes
  • services
  • databases
  • dependencies
  • external APIs
  • local imports
  • architectural boundaries

Every result is backed by file paths and line-level evidence so developers can inspect the repository instead of trusting a black box.

Everything runs locally.

No hosted service.

No vector database.

No embeddings.

No repository code leaves your machine.

How I built it

One of the most interesting parts of this project wasn't writing TypeScript—it was designing the product itself.

I didn't use ChatGPT as a tool to generate an application from a prompt.

Instead, I used it as an engineering and architecture partner.

GPT-5.6 became the place where I challenged assumptions before implementation.

Rather than immediately writing code, I spent a significant amount of time discussing questions like:

  • Should this feature exist?
  • What problem am I actually solving?
  • Is this architecture modular enough?
  • What responsibilities belong in the CLI?
  • What belongs in the knowledge layer?
  • What should become the canonical representation of a repository?

Those conversations eventually led to the idea of stackbrief.json, a versioned repository knowledge model that became the foundation of the project.

Once the architecture became clear, I switched to Codex for implementation.

Instead of asking Codex to build the entire project, I intentionally divided development into milestones.

Every milestone began with architectural planning before implementation started.

Codex then accelerated:

  • TypeScript implementation
  • package structure
  • repository scanning
  • knowledge model development
  • CLI commands
  • testing
  • refactoring
  • documentation
  • release preparation

Throughout the project, I remained responsible for the product direction, architecture, and engineering decisions.

AI accelerated the engineering process.

It did not replace engineering judgment.

Challenges

The biggest challenge wasn't technical.

It was deciding what StackBrief should become.

Originally, I planned to make StackBrief an AI-powered repository assistant using the OpenAI Responses API.

Halfway through OpenAI Build Week, I discovered that the credits I received were Codex credits, not API credits.

At first, this felt like a blocker.

Instead of forcing AI into the runtime, I stepped back and reconsidered the product.

That constraint ultimately made StackBrief stronger.

I decided to embrace an offline-first philosophy.

Today, StackBrief works without:

  • API keys
  • hosted AI
  • embeddings
  • vector databases
  • cloud infrastructure

The result is a developer tool that works entirely from local repository analysis while remaining provider-neutral for future integrations.

Sometimes constraints produce a better product than the original plan.

What I learned

This project fundamentally changed how I think about collaborating with modern reasoning models.

The biggest lesson wasn't about repository analysis or TypeScript.

It was learning that the highest value of models like GPT-5.6 isn't simply writing code.

It's helping you think.

The best conversations were rarely implementation prompts.

They were discussions about:

  • architecture
  • trade-offs
  • product strategy
  • software design
  • long-term maintainability

GPT-5.6 helped me challenge ideas before they became code.

Codex then helped translate those decisions into production-ready implementation.

That workflow allowed me to spend more time making deliberate engineering decisions and less time on repetitive implementation work.

It also reinforced something I now strongly believe:

AI should amplify engineering judgment—not replace it.

Looking Ahead

Today, StackBrief generates architectural briefs directly from source code.

The long-term vision is to become a foundational layer for repository understanding that developers can use before making changes, reviewing pull requests, onboarding into unfamiliar projects, or integrating with future developer workflows.

StackBrief started as a small developer skill called stack.md.

The rest, as they say, is history.

Built for OpenAI Build Week 2026

StackBrief was designed and implemented during OpenAI Build Week 2026.

It was built with ChatGPT (GPT-5.6) and Codex, using AI as an engineering collaborator throughout product design, architecture exploration, implementation, testing, documentation, and release preparation.

Open source:

Created by Mojeeb Titilayo, AI Product Engineer and Founder of BlindspotLab.

Built With

Share this project:

Updates

Submission history