The signal
Repo-local phase specs before agent code appears to be a candidate Spec-First Agentic Coding atom. The editor must prove it is a repeatable workflow, not just an interesting source.
Why it matters
Most AI-work failures now come from weak boundaries, not weak models. A repo-local or task-local phase spec gives the agent a narrow job, a source trail, and a review gate before it starts changing real work.
The old move is to hand an agent a task and hope the prompt is clear enough. Repo-local phase specs before agent code points to a better habit: define the phase before the agent starts moving.
A phase spec is not a giant requirements document. It is a small operating contract for one slice of work: what the agent should read, what it may touch, what it must prove, and when a human needs to decide.
The useful signal from holgerleichsenring/specification-first-agentic-development is that agent work gets safer when instructions live near the repo or task, not only inside the chat. yimwoo/agent-spec reinforces the same pattern: constraints, budgets, allowed paths, verification commands, and handoff evidence reduce scope drift.
This matters because AI work now fails less from lack of capability and more from weak boundaries. The agent can move quickly, but without a phase contract it may optimize the wrong thing, skip the boring check, or bury an important assumption in a confident answer.
Try repo-local phase specs before agent code on one small task before turning it into a team rule. If the phase spec cannot make the task clearer, safer, and easier to review, the workflow is not ready for your archive packet yet.
How to use it today
- Write the phase contract before asking the agent to code, research, or change anything.
- List the trusted context in the order the agent should read it: goal, constraints, source files, prior decisions, and known risks.
- Define the work boundary: allowed paths or sources, blocked actions, time or iteration budget, and the exact output shape.
- Define the verification path before the run: tests, source checks, rubric, review questions, and human stop/go gate.
- After the run, save the decision log and evidence so the next phase starts from a clean handoff instead of a foggy chat transcript.
What changes in real work
Coder
Before: Give the agent a broad task, then spend the rest of the session correcting scope drift and guessing which checks already ran.
After: Write a phase spec first, make the agent work only inside that contract, and require evidence before accepting the Spec-First Agentic Coding result.
Operator
Before: Ask an AI to improve a process with scattered notes and no acceptance rule.
After: Create a small task pack with trusted inputs, allowed changes, verification steps, and the human approval gate before any operational change happens.
Analyst
Before: Ask for a report and then manually check whether the sources, caveats, and calculations were handled correctly.
After: Define the source set, expected outputs, review checks, and stop condition before the model starts synthesizing.
Prompts to copy
Turn this task into a phase spec before any AI work begins. Include objective, trusted context, allowed files or sources, blocked actions, verification commands, acceptance criteria, stop condition, and the human approval gate.
Read this phase spec and return only gaps before implementation: missing context, risky assumptions, unclear acceptance checks, source issues, permissions problems, and the smallest fix to the spec.
Run the task inside the approved phase spec. At the end, return evidence: what changed, what you checked, what failed, what remains uncertain, and whether the result satisfies the acceptance criteria from holgerleichsenring/specification-first-agentic-development.
Where this goes wrong
- Do not publish if the signal cannot become a repeatable workflow.
- Do not rely on social proof without source evidence or a field test.
- Do not hide the human approval gate when the technique can affect real work.
Sources checked
- holgerleichsenring/specification-first-agentic-development: Specification-First Agentic DevelopmentOpen source
- yimwoo/agent-spec: AgentSpec: repo-local operating contract for AI coding agentsOpen source
- arXiv:2604.05278: Spec Kit Agents: Context-Grounded Agentic WorkflowsOpen source
What moves behind the paywall
Today's essay is the public sample. Once it moves into history, the downloadable packet becomes part of the paid archive.