# Spec Graph — LLM Summary

> A declarative specification model for predictable agent-driven system manifestation.

Spec Graph is a formal framework for declarative, multi-dimensional software specifications. It extends behavior-only specs into a typed graph that captures everything required to predictably manifest a system: behavior, architecture, design, technology, domain concepts, and constraints.

## Core Concepts

- **Completeness**: the spec determines all decisions the designer cares about
- **Minimality**: every node is load-bearing; removing it causes manifestation ambiguity
- **Deterministic Manifestation**: same graph leads to logically equivalent systems
- **Progressive Adoption**: start with behavior nodes, then add dimensions as needed
- **Normative vs Informative**: `statement`/`expectation`/`constraints`/`verification` are binding; metadata is contextual

## Node Types

### Core (7)

- `feature` — grouping/namespace (non-normative)
- `layer` — grouping/namespace for shared horizontal capabilities (non-normative)
- `foundation` — repository scaffolding contracts
- `behavior` — observable behavior (`expectation` + `constraints[]` + `verification`)
- `decision` — architecture/technology decisions
- `domain` — business concepts and terms
- `policy` — non-functional requirements (`hard`/`soft` severity)

### Extension

- `design_token`
- `ui_contract`
- `api_contract`
- `data_model`
- `artifact`
- `equivalence_contract`
- `pipeline`

## Edge Types (7, forward-only)

- `contains`
- `depends_on`
- `constrains`
- `implements`
- `derived_from`
- `verified_by`
- `supersedes`

## Authoring Convention

- For behavior nodes, include the `constraints` field explicitly.
- If there are no node-local constraints, set `"constraints": []` instead of omitting the field.

## MCP Tools

- `init_specgraph`
- `validate_specgraph`
- `list_nodes`
- `get_node`
- `get_feature_subgraph`
- `list_edges`
- `search_nodes`
- `add_node`
- `update_node`
- `remove_node`
- `add_edge`
- `remove_edge`

## Key Links

- Docs home: `/docs/introduction`
- MCP guide: `/docs/guides/mcp-server`
- JSON Schemas: `/docs/reference/json-schemas`
- Normative definition: `/docs/reference/normative`
- Examples: `/docs/reference/examples`

## LLM Context Files

- Summary: `/llms.txt`
- Full bundle: `/llms-full.txt`
- Usage notes: `/docs/reference/llm-context-files`