Getting Started with GRACE

What You’ll Learn

This guide introduces you to GRACE Protocol concepts:

What a unit is and how they’re identified
How contracts prevent silent drift
How fingerprints verify authenticity
How gates halt execution for approval

Five Unit Types

GRACE defines five canonical unit types:

Role

A persona and capabilities for an agent within a chain.

type: role
slug: code-reviewer
version: 1.0.0
lens: "Expert code reviewer evaluating for security, performance, and maintainability"
tone: "Constructive, specific, actionable"
behaviours:
  - Flag security vulnerabilities
  - Suggest performance optimizations
  - Identify maintainability issues
output_format: "JSON with findings array and severity levels"

Rule

A constraint or policy that applies within a scope.

type: rule
slug: no-hardcoded-secrets
version: 1.0.0
polarity: "never"  # Can be "always" or "never"
statement: "API keys, tokens, or passwords appear in source code"
scope: "global"  # Can be global, domain, chain, session

Task

A discrete unit of work with a typed contract and execution context.

type: task
slug: review-code
version: 1.0.0
council: pathfinder
contract:
  inputs:
    - name: code
      type: string
      required: true
    - name: context
      type: string
      required: false
  outputs:
    - name: review
      type: object
    - name: severity
      type: string
prompt_body: |
  Review this code for security issues:
  {code}

Chain

Composes multiple units into an orchestrated workflow.

type: chain
slug: code-review-workflow
version: 1.0.0
council: pathfinder
contract:
  inputs:
    - name: pull_request_code
      type: string
      required: true
  outputs:
    - name: final_review
      type: object
composition:
  - id: analyze
    unit: stratt://dev/role/code-reviewer@1.0.0
    agent: LEWIS-06
  - id: review
    unit: stratt://dev/task/review-code@1.0.0
    agent: LEWIS-06
    depends_on: [analyze]
    gate: true  # Requires manual approval

Supply

External data or configuration provided to chains.

type: supply
slug: security-policies
version: 1.0.0
supply_body: |
  - All API keys must be stored in secret manager
  - No logging of PII
  - Rate limits: 100 req/min

Contracts Prevent Silent Drift

A contract is a promise about inputs and outputs. Breaking a contract requires a major version bump.

Example: Adding an Output

Original contract (v1.0.0):

contract:
  inputs:
    - name: code
      type: string
  outputs:
    - name: review
      type: string

You add a new output (v1.1.0 — additive, non-breaking):

contract:
  inputs:
    - name: code
      type: string
  outputs:
    - name: review
      type: string
    - name: severity
      type: string  # NEW

Example: Changing Input Type

You change input type (v2.0.0 — breaking, requires major bump):

contract:
  inputs:
    - name: code
      type: object  # CHANGED from string
      required: true

Fingerprints Verify Authenticity

Every unit has a Blake3 fingerprint computed from its content. The fingerprint is your proof that production code matches the approved specification.

Computing a Fingerprint

bun packages/cli/src/index.ts fingerprint my-task.yaml

Output:

blake3:a7f3e2c1d9b5f6a8e4c2b1d9f7a3e5c7b2d4f6a8e9c1d3f5b7a9e2c4f6a8e

Storing the Fingerprint

Include the fingerprint in your unit file:

type: task
slug: review-code
version: 1.0.0
fingerprint: blake3:a7f3e2c1d9b5f6a8e4c2b1d9f7a3e5c7b2d4f6a8e9c1d3f5b7a9e2c4f6a8e
council: pathfinder
...

Verifying the Fingerprint

Verify that a unit hasn’t been tampered with:

bun packages/cli/src/index.ts verify my-task.yaml

Output:

✓ Verified: blake3 matches stored fingerprint

Lifecycle States Enable Safe Evolution

Units progress through a 9-state lifecycle. Not all transitions are allowed.

State Diagram

draft
  ↓ (submit for review)
review
  ↓ (approve)
approved
  ↓ (publish) — REQUIRES GATE APPROVAL
published
  ↓ (activate)
active
  ↓ (retire)
deprecated
  ↓ (archive)
archived
  ↓ (delete) — REQUIRES GATE APPROVAL
tombstoned

Draft Isolation Rule

A unit in draft status can ONLY import units also in draft status. This prevents immature units from polluting approved chains.

You can:

Draft → import from draft ✓
Review → import from draft or review ✓
Approved → import from approved, published, or active ✓

You cannot:

Draft → import from approved ✗
Review → import from published ✗

Gates Halt Execution for Approval

Gates are synchronisation checkpoints that pause chain execution until a human or agent explicitly approves.

Marking a Gate in Composition

composition:
  - id: analyze
    unit: stratt://dev/task/analyze@1.0.0
    agent: LEWIS-06
    gate: false  # No approval needed

  - id: approve_changes
    unit: stratt://dev/task/approve@1.0.0
    agent: LEWIS-06
    gate: true   # HALTS here, requires approval
    depends_on: [analyze]

Running a Chain with Gates

By default, gates pause execution:

bun packages/cli/src/index.ts run stratt://dev/chain/review@1.0.0 \
  --input '{"code": "..."}'

Output:

step[1] analyze: COMPLETED
step[2] approve_changes: GATED (waiting for approval)

Gate a resolution:

bun packages/cli/src/index.ts gate approve <trace-id> --reason "Changes look good"

Or skip gates (for dev/test only):

bun packages/cli/src/index.ts run stratt://dev/chain/review@1.0.0 \
  --input '{"code": "..."}' \
  --gate-mode auto

Council Stewardship

Every unit belongs to a council that governs it. Seven councils exist:

Council	Domain	Gate Authority
Pathfinder	dev	LEWIS-06
Hermes	ops	RETRO-04
Athena	docs	EDITOR-04
Bastion	security	COMMANDER-05
Compass	product	COURSE-05
Herald	marketing	CROWN-05
Terra	data	MANTLE-05

The gate authority agent for each council approves:

Promotion to published (moving to production)
Demotion to deprecated (removing from production)
Deletion to tombstoned

URI Format

All units are identified by canonical URIs. Learn to read and construct them:

stratt://{domain}/{type}/{slug}@{version}
        ↓         ↓      ↓      ↓
stratt://dev/role/code-reviewer@1.2.3

Part	Meaning	Example
domain	Which domain does it belong to?	`dev`, `ops`, `docs`, `shared`
type	What kind of unit?	`role`, `rule`, `task`, `chain`, `supply`
slug	Unique identifier (lowercase, hyphens)	`code-reviewer`, `health-check`
version	Semantic version (major.minor.patch)	`1.2.3`, `2.0.0`

Key Concepts You Now Know

✓ Five unit types: role, rule, task, chain, supply
✓ Contracts: Prevent silent drift through typed I/O
✓ Fingerprints: Blake3 hashes verify authenticity
✓ Lifecycle: 9-state machine with draft isolation
✓ Gates: Synchronisation checkpoints halt execution
✓ Councils: Stewardship domains with gate authorities
✓ URIs: Canonical identification format

Next Steps

Full Specification: GRACE Protocol v1.0 — Deep dive into all five specs
Protocol Overview: Five Specification Layers — Complete conceptual overview
CLI Reference: 21 Commands — How to validate, fingerprint, verify, publish
Unit Authoring: Complete Guide — Writing production-quality units