Specifications

Specification-driven development in the SHAPE Framework does not mean asking stakeholders to sign off on a detailed requirements document before an agent can write code. Its purpose is to preserve product intent in an agent-readable form so coding agents can implement, extend, and independently verify the software. The Product Engineer and stakeholders primarily inspect working behavior and provide feedback until the product is satisfactory. The working product, not the specification document, is what humans ultimately accept.

Agentic implementation can shorten the interval from a request to functioning software dramatically for suitable tasks. That changes the economics of an intermediate approval step: a stakeholder may be able to inspect a prototype sooner than they could review and interpret a comprehensive written specification. SHAPE therefore favors direct product feedback over universal specification sign-off.

Product intent must still be retained accurately. Agents should maintain specification context as changes are made, rather than treating a conversation transcript or the implementation itself as the only durable record. A separate verification context can derive tests from that intended behavior and execute them against the application.

Specification organization is a project choice. Feature documents, grouped functional areas, and an experimental consolidated product description can all preserve intent. SHAPE does not mandate one file per feature, a filename, a section template, or acceptance-ID notation. This website currently uses specifications/requests/ for human change requests and specifications/current/ for maintained requirements; it has no master specification. Whether specifications/ remains a universal convention as this practice evolves is open, not a new decision made by this website.

Use the specification lifecycle: specifications/requests/ holds human-authored requests awaiting implementation; specifications/archive/ preserves implemented human-authored requests as historical records; specifications/current/ contains agent-maintained descriptions of currently required product behavior. Move implemented requests to the archive without rewriting their historical content, and update current-state specifications. Direct prompts and conversations can authorize development without a formal specification file; maintain the current-state record regardless of request format.

At a useful minimum, record the feature's purpose and scope, actors or permissions, triggering actions, expected behavior, business rules, meaningful failure or exception behavior, dependencies or constraints, and acceptance conditions. Where data is involved, describe the information visible or changed and any important validation or access expectations.

Use concrete language. “The system should be intuitive” is difficult to verify. “A reviewer can reject a request only by providing a reason; the requester can then see the recorded reason” expresses observable behavior.

A coding agent may fill a gap with a plausible assumption that the business did not approve. The Product Engineer should resolve consequential ambiguity with stakeholders and update the specification. Noncritical details may be discovered through working-software iteration, but accepted behavioral decisions still need to become part of the durable corpus.

Early specs can focus on the initially agreed workflows. Stakeholder feedback, UAT findings, maintenance changes, and new features may revise them. The important discipline is that the corpus represents current intended behavior. A specification that describes last year's product while the implementation has changed is no longer a reliable reference.

A separate verification agent derives checks from the committed corpus, exercises the implementation where feasible, and reports outcomes against requirements. Acceptance criteria improve that process, but do not imply that every requirement can be perfectly evaluated by automation. Human evaluation and specialist assurances remain important.

Purpose, actors, permissions, workflows, exceptions, and observable outcomes are useful prompts, not mandatory headings. The sample templates and SPEC-001/AC-05 identifiers illustrate one technique. A PE can start with a conversation or demonstrated correction; agents turn that intent into maintained context while implementing. Human decisions settle material policy, and working product receives acceptance. Enterprises may separately require preimplementation approval for high-risk work.

One possible evolution is to let the agent consolidate the product's intended behavior into a detailed master specification as changes accumulate, instead of creating and maintaining a separate feature document for every request. Such a file could become the primary context for agent-led maintenance and independent tests, including browser automation where applicable.

This approach remains under discussion in the SHAPE Framework. Its exact format, granularity, update rules, organization, and verification boundaries have not yet been decided. Projects may experiment with it, but a master specification file, its filename, and its sign-off process are not mandatory standards.

Open questions: How do agent updates preserve genuine human intent? How is unintended behavior detected? How are conflicts between conversation, code, and specification resolved? How can independent verification avoid implementation assumptions? When should a large document be partitioned? How are changed requirements distinguished from defect fixes?