Architecture Graph Skill

Overview

Cartographer enables spec-driven development where architecture specifications in

.graph/

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:

has_many

belongs_to

has_one

has_many_through

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:

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

4. Verify Sync

Run

/graph:check

Available Commands

/graph:check

/graph:entity <name>

/graph:impact <entity>

MCP Tools

The Cartographer MCP server provides these tools:

scan

query

validate

impact

get_relations

Best Practices

1. Spec-First Development

Always define in

.graph/

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

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:

uuid

string

integer

float

boolean

timestamp

date

json

enum

array

Troubleshooting

Anchor Not Found

If

/graph:check

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