spec-framework

Category: Content & Multimedia | Uploader: elct9620 | Downloads: 0 | Version: v1.0（Latest）
Structure specifications using the three-layer framework (Intent, Design, Consistency) with boundary types and implementation standards. Use when organizing spec content into layers or selecting elements.
Changelog: Source: GitHub https://github.com/elct9620/ai-spec-skills
Directory Structure

Current level: skills/spec-framework/
📄 SKILL.md 5.9 KB
SKILL.md

---
name: spec-framework
description: Structure specifications using the three-layer framework (Intent, Design, Consistency) with boundary types and implementation standards. Use when organizing spec content into layers or selecting elements.
---

# 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 |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
spec-framework

Directory Structure

SKILL.md

Report

Notice
