Architecture Graph Skill

Overview

Cartographer enables spec-driven development where architecture specifications in .graph/ define the source of truth for entities, relations, and code structure. The code follows the spec, not the other way around.

Core Concepts

Entities

Entities are defined in .graph/entities/*.yaml:

name: User
description: Application user account
fields:
  - name: id
    type: uuid
    primary: true
  - name: email
    type: string
    unique: true
  - name: name
    type: string
relations:
  - name: todos
    entity: Todo
    type: has_many
code_refs:
  model:
    anchor: "@graph:User.model"
  schema:
    anchor: "@graph:User.schema"

Key properties:

• •name: PascalCase entity identifier
• •description: Human-readable purpose
• •fields: Typed fields with constraints (primary, unique, nullable)
• •relations: Connections to other entities
• •code_refs: Links to implementation code via anchors

Relations

Relations define how entities connect:

Code References (code_refs)

Code is linked to specs via anchor comments in source files:

// @graph:User.model
export interface User {
  id: string;
  email: string;
  name: string;
}
// @end:User.model

Anchor syntax:

• •Start: // @graph:EntityName.refType
• •End: // @end:EntityName.refType
• •Works in any language with comments

Spec-Driven Workflow

When implementing or modifying code, always follow this workflow:

1. Check the Spec First

Before writing any code, read the entity YAML in .graph/entities/:

# Use /graph:entity command
/graph:entity User

Or read the file directly to understand:

• •What fields are expected
• •What relations exist
• •Where code should be anchored

2. Follow the Spec

Implement exactly what's specified:

• •Use the same field names and types
• •Implement all defined relations
• •Place code in the anchored locations

3. Add Anchors

Wrap implementations with @graph: comments:

// @graph:User.model
// Implementation here
// @end:User.model

4. Verify Sync

Run /graph:check to validate that code matches spec.

Available Commands

MCP Tools

The Cartographer MCP server provides these tools:

Best Practices

1. Spec-First Development

Always define in .graph/ before implementing:

1. Create/update .graph/entities/new-entity.yaml
2. Implement code with anchors
3. Run /graph:check

2. Atomic Anchors

One anchor per logical unit:

• •model - Data structure/interface
• •schema - Validation rules
• •handler - API endpoint handler
• •repository - Database access layer

3. Keep in Sync

Run /graph:check after every modification to catch drift early.

4. Document Relations

Make entity connections explicit in both entities:

# user.yaml
relations:
  - name: todos
    entity: Todo
    type: has_many

# todo.yaml
relations:
  - name: user
    entity: User
    type: belongs_to

Common Tasks

Adding a New Entity

1. •Create .graph/entities/new-entity.yaml with all fields
2. •Add relations to connected entities
3. •Create code files with anchor comments
4. •Run /graph:check to verify

Adding a Relation

1. •Update both entity YAML files
2. •Add foreign key field if needed
3. •Update both code_refs sections
4. •Verify with /graph:check

Modifying a Field

1. •Run /graph:impact Entity.field first
2. •Update the entity YAML
3. •Modify all code_refs locations
4. •Run /graph:check

Checking Impact Before Changes

Before modifying an entity:

/graph:impact User.email

This shows:

• •All code locations that need updates
• •Related entities affected
• •Suggested action items

Field Types Reference

Common field types in entity definitions:

Troubleshooting

Anchor Not Found

If /graph:check reports missing anchors:

1. •Verify the anchor comment syntax is correct
2. •Check that start and end tags match
3. •Ensure the file path in code_refs is correct

Orphaned Anchor

If code has an anchor but spec doesn't reference it:

1. •Add the code_ref to the entity YAML, or
2. •Remove the anchor comment from code

Type Mismatch

If field types don't match:

1. •Check the entity YAML for the expected type
2. •Update the implementation to match
3. •Consider if spec needs updating instead