§01Open Specification

Shapes

An open specification that captures what to build, why it matters, and what must hold true — one structured graph that AI agents and humans can read together.

shape:1 Platform [canonical]
├── shape:3 Auth Service [promoted]
│   ├── constraint:5 Security Policy
│   ├── shape:7 OAuth Login [promoted]
│   │   └── constraint:8 Rate Limiting
│   └── shape:8 MFA [proposed]
└── shape:4 API Gateway [promoted]
    └── constraint:6 Uptime SLA
Profile · Softwarev0.1.0 — Working Draft

§02Two Graphs

Shapes and Constraints
each form their own DAG.

Two independent graphs framed by one profile. Shapes compose work — features within services within systems. Constraints compose rules — invariants within policies. Every shape inherits the constraints of its ancestors, so the rules that govern any node are the rules of every node above it.

Shape DAGcomposition
shape:1 Platform [canonical]
├── shape:3 Auth Service [promoted]
│   ├── shape:7 OAuth Login [promoted]
│   └── shape:8 MFA [proposed]
└── shape:4 API Gateway [promoted]
Constraint DAGpolicy
constraint:1 Security Policy
├── constraint:5 Uptime SLA → shape:4
├── constraint:7 Rate Limiting → shape:7
└── constraint:8 MFA Required → shape:3
Amendment · Change historyOnce promoted, shapes evolve only through amendments.

§03In Practice

Structured intent

Every shape is a YAML file in your repository. The graph lives alongside your code — versionable, diffable, reviewable.

yaml
shape:
  id: 12
  name: User Authentication
  kind: feature
  status: promoted

  intent:
    summary: "OAuth2 login flow with MFA support"
    source: human
    acceptance:
      - Users can sign in with Google or GitHub
      - MFA is required for admin accounts

  parent: 3 # → Auth Service
  constraints:
    - 5            # → Security Policy
    - 8            # → Rate Limiting

  realization:
    - bindings:
        - scheme: path
          value: src/auth/oauth.rs
      role: primary

§04Install

Two commands.

Install the Rust CLI binary, then add the agent skills so Claude and other AI agents discover the graph automatically.

CLI binary
cargo install --git https://github.com/shapes-fyi/shapes
Agent skills
npx skills add shapes-fyi/shapes