Build in Slices, Prove Behavior, Keep the Code Reversible

For addyosmani/agent-skills, implementation begins only after a task is bounded enough to produce evidence. This chapter focuses on the repository’s execution loop: how to choose a thin slice, make a behavioral claim fail before changing the code, verify the result with the project’s own tools, and preserve a point from which the change can be understood or undone. The aim is not to make every change ceremonial. It is to keep an agent from turning one uncertain task into a large, opaque commitment.

A complete slice is smaller than a feature and larger than a file

The repository defines an increment as the smallest complete piece of functionality that can be implemented, tested, verified, and committed. “Smallest” controls risk; “complete” prevents the team from mistaking a partial layer for working behavior. A new database table without a useful path through the service is not necessarily a meaningful slice. A UI shell with no tested data behavior may look finished while leaving the important uncertainty untouched.

That is why the preferred shape is vertical. A slice follows one user-relevant path through the layers it needs. It can include a narrow data change, an interface or handler, a basic client path, and focused tests, while leaving unrelated capabilities for later slices. Each slice should leave the system in a working state. The team can then ask a concrete question about behavior instead of holding a large collection of unfinished parts in its head.

Vertical slicing does not mean ignoring dependencies. Planning still follows the dependency graph, but it chooses a complete path through that graph rather than finishing one horizontal layer before allowing anything to work. The distinction matters for agents because a horizontal task often rewards local completion: every file in the layer looks polished even though no end-to-end condition can yet be observed.

The repository offers two useful variations. Contract-first slicing defines the interface before backend and client work proceeds in parallel. That gives both sides a shared shape and lets each be tested against the same expectation. Risk-first slicing tackles the uncertain or expensive element first. If a feature depends on a connection, migration, or external service whose behavior is unknown, proving that dependency before building the surrounding experience prevents the team from investing in a path that cannot operate.

The easiest code is not always the best first slice. A low-risk utility may be quick to finish, but it can postpone the uncertainty that determines whether the feature is viable. A risk-first slice may feel slower because it begins with the difficult question. Its value is that a failure arrives before the rest of the design depends on an assumption that has not survived contact with reality.

The increment cycle is a control loop

The repository’s implementation cycle is intentionally repetitive: implement, test, verify, commit, and move to the next slice. Each verb has a different meaning.

Implement means the smallest change that can answer the current task, not the most general framework that might support future variations.