Laying the Groundwork
Briefs as architectural roadmaps.
Repo In Review Merged
- master Class Booking App
- master Waitlist merged, after review
- feature/waitlist + waitlist.php + waitlist.js + ~ booking.php
- Audit 1 gap: the hold time. Fixed.
Skills
- reference/readme.txt Context for humans.
- skills/booking/skill.md Context for agents.
- briefs/waitlist.md Behavioral prompt, outlines the work.
- skills/waitlist/skill.md New skill for added feature.
-
Agents are efficient implementers, but they lack context. We write briefs to constrain their focus and keep track of the big picture for them.
The Brief An architectural document that defines the intended behavior, surrounding context, and implementation boundaries.
-
Briefs constrain the assumptions agents make. They’re eager little genius interns, and if left unchecked, they will make lots of assumptions that hurt the build. Vibe coding treats the agent as both the architect and the developer. That may work for a proof of concept, but becomes dangerous when the product encounters real customers.
Implementation An agent builds the bounded feature against that brief.
-
Local development environments are self-documenting: agents create new skills based on briefs I write, organize reference documents I share, and continually comment their own code. The project creates an enduring narrative about itself, so both humans and agents have useful context for the future.
Auditing Other roles, such as the Pentester or Tester, examine the result and report gaps or risks.
-
The environment documents itself: as code is written, new skills are generated to inform future agents. Nothing ships in one shot. That’s how we protect the legacy on the frontier.
Human Review I review the output, run tests, and direct revisions. The cycle repeats.
The approach is programming language-agnostic. Clear communications guide the implementation: tooling follows the requirements of the system.