spec-framework

Specification Framework

Detailed structure for each layer of a specification.

Applicability Rubric

Condition	Pass	Fail
Structuring new spec	Writing a spec from scratch	Spec structure already established
Layer completeness check	Need to verify all layers are addressed	Layers are already complete
Element selection	Deciding which elements to include	Elements already chosen
Multi-layer coordination	Ensuring layers align with each other	Single-layer change only

Apply when: Any condition passes

Core Principles

Intent Layer

Provides context for judgment calls:

Element	Role	Core
Purpose	What problem the system solves	✓
Users	Who uses it, what they accomplish	✓
Impacts	What behavior changes indicate success (drives priority)
Success criteria	What defines "done" and "working"
Non-goals	What is explicitly out of scope

Without intent, implementers make technically correct but misaligned decisions.

Design Layer

Defines observable behaviors and boundaries:

Element	Role	Format	Core
System boundary	What's inside vs outside	See Boundary types
User journeys	Task flows achieving impacts	Context → Action → Outcome
Interfaces	Contracts between internal modules	-
Presenter	How system presents to users	UI: colors, layout / CLI: output format / API: response structure
Behaviors	Outcomes for each state × operation	State + Operation → Result	✓
Error scenarios	How failures are handled	-	✓

Boundary types:

Type	Defines	Example
Responsibility	What system does / does not do	"Validates input; does not store history"
Interaction	Input assumptions / Output guarantees	"Assumes authenticated user; Returns JSON only"
Control	What system controls / depends on	"Controls order state; Depends on payment service"

Consistency Layer

Establishes patterns for uniform implementation (all items enhance quality, none required for minimal spec):

Concept	Role	Example
Context	Shared understanding	"This is event-driven"
Terminology	Same concept uses same name throughout	"Order" not "Purchase/Transaction/Request"
Pattern	Recurring situation → approach	"State changes via events"
Form	Expected structure	"Events have type, payload", "Primary: #FF0000", "Errors to stderr"
Contract	Interaction agreement	"Handlers must be idempotent"

Weave these into relevant sections rather than listing separately.

Implementation Standards (Optional)

For projects requiring code-level consistency across multiple contributors or extended development periods.

Category	Purpose	Examples
Architecture	Module boundaries and dependencies	Clean Architecture, Hexagonal, Layered
Design Patterns	Reusable solutions	Repository, Factory, Strategy
Testing Style	Test structure and conventions	Given-When-Then, Arrange-Act-Assert
Code Organization	Directory structure and naming	Feature-based, layer-based, naming conventions

When to include:

• Multiple contributors work on the codebase
• Development spans extended periods
• Codebase requires shared conventions

When to skip:

• Simple scripts or single-file utilities
• Prototypes or proof-of-concept
• Short-lived projects

Layer Selection Guide

Project Characteristic	Intent	Design	Consistency	Implementation Standards
Solo prototype	Core only	Core only	Skip	Skip
Small team (2-5)	Full	Full	Terminology + Patterns	Optional
Multi-team	Full	Full	Full	Recommended
External API / Public contract	Full	Full	Full	Required

Element Completeness Guide

Design Element	When to Include	When to Skip
System boundary	External dependencies exist	Self-contained utility
User journeys	Multiple user-facing flows	Single-purpose tool
Interfaces	Multiple internal modules	Monolithic implementation
Presenter	User-facing output matters	Internal service
Behaviors	Always (Core)	Never skip
Error scenarios	Always (Core)	Never skip

Completion Rubric

Before Applying Framework

Criterion	Pass	Fail
Scope understanding	Know what the system does	Scope unclear
Layer necessity evaluated	Determined which layers needed per project type	Blindly applying all layers
Existing content assessed	Reviewed any existing spec content	Starting without context

During Application

Criterion	Pass	Fail
Intent before Design	Intent layer completed before Design details	Design written without Intent
Core elements present	All Core-marked elements addressed	Core elements missing
Boundaries explicit	System boundaries clearly defined	Boundaries implied or missing
Layer selection justified	Layer depth matches project characteristic	Over/under-layered for context

After Application

Criterion	Pass	Fail
Intra-layer consistency	Elements within each layer do not contradict	Internal contradictions
Cross-layer alignment	Design serves Intent; Consistency supports Design	Layers misaligned
Element completeness	Included elements fully specified	Partial elements left incomplete