22 posts
Run a monthly drill with a deliberate violation. Verify which controls reject it, report failures, and confirm cleanup. The drill attempts real merges, including an administrator override; use a disposable test repository and inspect the…
Run the task queue on a schedule. Separate urgent failures, requests for your decision, and routine logs. Detect missed runs, and understand why a watch on the same machine cannot detect that machine's complete failure.
Add a separate reviewer, require automated checks before merging, and verify the deployed result before marking a task complete. Configure a runner, a GitHub workflow, and command restrictions, with explicit limits on what each can verify.
Give each task acceptance criteria, dependencies, and a status. Define how the agent selects the next eligible task and when it must stop. Includes a queue template and a five-item exercise.
Write down the actions agents may take, the actions requiring your approval, and the evidence they must provide before reporting completion. Includes a permission template and exercises that check whether an agent follows it.
Document which repository owns each part of the project. Assign each agent a specific scope and a separate checkout to prevent overlapping edits. Includes layout instructions and a repository-splitting exercise.
Turn a project rule into a script that detects violations. Run it before each push and test it with a deliberately invalid change. Learn what a local Git hook checks and how it can be bypassed.
Write a decision record documenting what you chose, which alternatives you rejected, and when to reconsider. Instruct agents to read relevant decisions before proposing changes, then test whether they retrieve them.
The third post in the SDD numbers series is not about velocity. Since June the platform's effort moved into four quiet systems: an externalized memory, a statistical screen that refuses to flatter me, a point-in-time data floor, and a pr…
The full path to an agent platform that edits its own instructions is already published, scattered across seven articles that never mention each other. I run that architecture as one person: supervisor and worker tiers, verification guar…
Record what a feature must do, what is outside its scope, and how you will verify it. Create a specs directory and template, then give the agent an approved spec to implement.
SpecSelf looks like a set of features: coherence checks, persona rotation, review cadences, an audit trail. Every one of them was implied by ten frontmatter fields decided on day one. A life-OS is not a feature list. It is a schema decis…
I built a method as a public repo and the product that runs it as two private ones, and none of them treated the others as a source of truth. The domain enum lived in four places. A persona drifted between its lens file and its API contr…
Three months ago I laid out spec-driven development and the folder architecture that makes it work. Most of the playbook held up in daily production use. Three ideas that essay never mentioned turned out to matter more than anything in i…
Spec-driven development, pointed at a life. Why my principles and goals live as markdown an AI agent reasons over, and the one rule that makes handing an agent your life safe: it can challenge the record, but it never writes it.
I handed a backlog to Claude Fable, told it once it could merge, and let it run. It shipped seventeen items across five repos. The line that mattered was not in the work it finished. It was in the work it refused to touch.
Dumping the whole corpus into an AI agent makes it worse, not better. The fix is architectural: each task loads a curated slice, not everything you have. Here is the method, and the same move at three different layers: specs, sensor data…
Anthropic published a guide on building a session-level orchestration mode. I built it two ways, on the CLI and on the API, and then hit the part the guide does not cover: an orchestrator that fans out is useless without a backlog of rea…
Two weeks after I shipped a post about a scoring engine I'd built, I rewrote the spec it was based on. Here's what I learned, and why I had an AI agent do the literature review.
Spec-driven development reads like a methodology for controlling AI agents. It isn't. It's a methodology for managing context across stateless sessions. The spec is the persistent memory.
Two production sites, a blog, and two personal AI projects, shipped this week from a phone. The chain is voice dictation into Perplexity Computer, a spec, then Claude Code on the web. The interaction model is the story.
Why spec-driven development and structured folder architecture are the missing infrastructure for AI-assisted engineering: methodology, common mistakes, and where to start.