Lessons from building a coding agent package

Brief Context started from a small annoyance: every AI coding session begins a little cold.

A project may already have clear conventions, risky files, deployment rules, and known unknowns, but a new agent does not know that yet. It has to rediscover the same facts before it can make a safe change. That repeated setup cost is easy to ignore until you switch between Pi, Claude Code, Codex, terminal workflows, and fresh sessions often enough.

The package is intentionally simple. It scans safe project metadata, writes a concise PROJECT_CONTEXT.md, and gives different coding agents the same factual handoff layer before any edits happen.

Building it taught me a few lessons about agent tooling.

Agent tools need a handoff layer

Most coding agents are good at reading files once they know where to look. The problem is the first few minutes.

A fresh session needs answers to basic questions:

• What stack is this?
• Which commands matter?
• Where is the app entry point?
• Which files are important?
• What should not be touched casually?
• What is unknown and needs inspection?

Those facts do not need a large vector index or a complex memory system. They need a small, boring document that the next agent can read before planning.

That became the core product shape: generate a project brief that is factual, short, and safe to keep in the repository.

Start with facts, not intelligence

It is tempting to make an agent package feel smart. You can add inference, semantic search, embeddings, and long summaries very quickly.

For Brief Context, the better choice was to stay mechanical.

The scanner reads allowlisted metadata such as package.json, selected config files, and top-level project shape. It detects stack, commands, key files, risks, conventions, and unknowns. If it cannot prove something, it says so.

That constraint matters. A bad brief is worse than no brief because it gives the agent confidence in the wrong direction. For coding tools, uncertainty should be visible instead of smoothed over.

One core, many adapters

The package supports different surfaces: a CLI, Pi extension, prompt templates, and adapters for agent workflows.

The important architectural decision was to keep the product logic in a host-agnostic TypeScript core. The core handles detection, rendering, output path safety, cache writing, and orchestration. Adapters should mostly translate host input into core options and present the result back to the user.

That separation keeps the package easier to test and easier to port. It also prevents every integration from becoming a slightly different product.

The lesson: if you are building a coding-agent library, treat each agent host as a delivery channel, not as the center of the architecture.

Safety is part of the feature

A tool that scans a repository has to be conservative by default.

Brief Context avoids real environment files, ignores noisy or generated directories, caps reads and walks, and rejects unsafe output paths. It writes a human-readable PROJECT_CONTEXT.md plus a small .pi/brief.json cache for stable detection data and change hints.

Those choices are not polish. They are the difference between a helpful tool and a tool that accidentally teaches agents to read secrets, trust generated noise, or overwrite the wrong path.

For agent infrastructure, safety is not a separate hardening phase. It is product behavior.

Small context beats full context

The goal was never to give the agent everything.

Full context sounds useful, but it creates two problems. First, it can drown the agent in irrelevant files. Second, it encourages planning from stale summaries instead of inspecting the specific code that will change.

A better brief says just enough to orient the session:

• here is the stack
• here are the commands
• here are likely important files
• here are risks
• here are unknowns
• inspect task-relevant files before editing

That shape keeps responsibility in the right place. The brief gives orientation; the agent still has to read the actual files before changing behavior.

Package validation matters for agent tools

Developer tools are trust products. If the package install is broken, the CLI entry point fails, or the adapter payload is missing from the published package, the whole experience feels unreliable.

That is why Brief Context validates with typecheck, tests, and npm pack --dry-run in CI. The package metadata matters as much as the code because the installation path is part of the product.

This is especially true for coding-agent tooling. Users often try the tool in the middle of another task. The first run has to work.

Humans still own the plan

The most useful output from Brief Context is not a command result. It is a better first plan.

A generated brief should help the agent say:

• this is the stack
• these files are likely involved
• these areas are risky
• this is the smallest safe implementation path
• these things are unknown and need inspection

That keeps the human in control. The package does not try to replace judgment; it tries to make the first conversation less repetitive and less dangerous.

The broader lesson

A good coding-agent package does not have to be dramatic.

The best parts of Brief Context are deliberately boring: safe scanning, allowlisted reads, short Markdown, host-agnostic core logic, adapter boundaries, visible unknowns, and CI validation.

That is the pattern I would reuse for other agent libraries. Start with a small piece of durable context. Make it safe. Keep the core portable. Treat adapters as thin shells. Prefer honest uncertainty over impressive guesses.

Agents are more useful when they begin with the right facts and the right constraints. Sometimes the best agent feature is not another prompt. It is a clear handoff before the prompt even starts.