@magic-spells/constellation 0.1.0

package/docs/002-mcp.md

@@ -0,0 +1,109 @@
+# Constellation MCP (v2)
+
+The MCP server gives AI agents graph queries, hydrated retrieval, validated writes,
+and git-powered change tracking over a plan folder. It is a thin layer over
+`src/core/`: every tool call reloads the index from disk (tens of milliseconds at
+realistic plan sizes), so it is always correct while files are being edited in
+parallel — no watcher, no cache invalidation.
+
+Entry point: `constellation mcp` (stdio). Bootstrap is folder discovery: the server
+walks up from the working directory to find `constellation/`, **bounded by the repo
+root** (the first ancestor with `.git`) — it never crosses into another repo's plan,
+so a repo with no plan returns `NO_PLAN_FOUND` rather than silently adopting a
+sibling's. No accounts, no tokens, no settings handshake. When no plan exists yet,
+`init_plan` scaffolds `constellation/` + starter `plan.md` (same shared scaffold the
+CLI `constellation init` uses); every other tool works immediately after — no restart.
+
+## Vocabulary
+
+**Card** (a file in the plan), **connection** (an undirected link between two cards).
+Tool responses use `connected_cards`, never `connected_nodes`.
+
+## Hydrated retrieval (core requirement)
+
+Any read tool can return connected cards **with their full data** in one call. Three
+levels, chosen by the caller because the cost is context tokens, not compute:
+
+- `none` — the card(s) only
+- `summary` — connected cards as `{ handle, type, kind, name, status }`
+- `full` — connected cards with complete `frontmatter` and `body`
+
+The acceptance test: one `get_card` call returns an API card plus the complete
+content of every card connected to it (its datatypes, table, tests, docs).
+
+## Tools
+
+### Read
+
+| Tool | Input | Returns |
+|---|---|---|
+| `get_card` | `handle`, `connected?` (default `summary`) | `{ card, connected_cards }` |
+| `list_cards` | `types?`, `kind?`, `status?`, `connected?`, `limit?` | `{ cards: summary[], total }` (`connected:false` → orphans only) |
+| `search` | `q`, `types?`, `limit?` (20), `connected?` (default `none`) | `{ matches: [{ card, score, excerpt, connected_cards? }] }` |
+| `traverse` | `start` (handle or array), `depth?` (2, max 5), `types?`, `detail?` (`summary`/`full`) | `{ cards: [{ …, distance }], connections }` |
+
+`search` scoring: handle match ≫ name match > kind/type match > body occurrences;
+excerpt is the first matching body line. Seeding `traverse` with multiple handles
+(e.g. the output of `diff_plan`) is the impact-analysis pattern.
+
+### Write
+
+| Tool | Input | Notes |
+|---|---|---|
+| `create_card` | `handle`, `name?`, `kind?`, `status?`, `connections?`, `fields?`, `body?`, `validate?` | Writes `<folder>/<HANDLE>.md`; `fields` = type-specific frontmatter. `validate:false` skips lint (bulk import) |
+| `create_cards` | `cards: [...]` (1–500) | Bulk create: validates all up front, writes all, lints ONCE → intra-batch references resolve. `{ created, failed, cards, issues }` |
+| `update_card` | `handle`, `patch?`, `body?` | See merge semantics below |
+| `delete_card` | `handle` | Returns `referenced_by` so the caller can clean up |
+| `add_connection` | `from`, `to` | Appends to `from`'s connections (no-op if already connected from any source) |
+| `add_connections` | `connections: [{from,to}]` (1–1000) | Bulk connect, idempotent/undirected, one lint pass. `{ added, failed, errors }` |
+| `remove_connection` | `a`, `b` | Removes from either card's list; reports if the connection survives via other sources (frontmatter field, body link, mermaid) |
+
+Every write reloads the index, lints, and returns the issues touching the written
+file — an agent finds out immediately if it created a dangling reference. **A card
+is created even when issues are returned** — `issues` are the current lint state,
+not a failure. For migrations, prefer `create_cards` + `add_connections` (batched,
+one lint pass, no transient dangling-reference noise) or `create_card validate:false`
+followed by a single `check_integrity`.
+
+**Merge semantics for `update_card`:** `patch.name/kind/status` set (or delete with
+`null`); `patch.connections` replaces the list wholesale (use add/remove_connection
+for incremental edits); `patch.fields` deep-merges into type-specific frontmatter —
+objects merge recursively, arrays replace, `null` deletes a key. `body` replaces the
+whole body.
+
+**Formatting preservation:** a body-only update never touches frontmatter bytes.
+A frontmatter update re-serializes **only the top-level keys whose values
+changed** — unchanged keys keep their original text byte-for-byte (flow-style
+maps, comments, and all), so a status flip is a one-line diff. Key order is
+preserved; new keys append. Only a changed key's value normalizes to canonical
+YAML style.
+
+### Git
+
+| Tool | Input | Returns |
+|---|---|---|
+| `diff_plan` | `base?`, `head?` | `{ base, base_source, head, changes: [{ handle, file, change, changed_keys?, body_changed? }] }` |
+| `plan_log` | `handle`, `limit?` (20) | commits touching that card |
+| `set_sync_point` | `sha?` (default `HEAD`) | writes `constellation/.sync.json`; `warning` if the plan is uncommitted |
+| `check_integrity` | — | lint result + `orphans` (zero-connection cards) |
+
+`diff_plan` base resolution: explicit argument → sync marker (`.sync.json`) →
+`HEAD` (i.e. uncommitted plan changes). `head` defaults to the working tree.
+`change` is `added` / `modified` / `removed` / `renamed`; for modified cards the
+old and new versions are parsed and compared, yielding `changed_keys` (frontmatter)
+and `body_changed`.
+
+The sync workflow: a code-sync agent calls `diff_plan` (base = marker), traverses
+the changed handles for blast radius, updates code, then `set_sync_point` to move
+the marker. `.sync.json` is versioned, rides branches, and the indexer ignores
+dotfiles so it is never treated as a card.
+
+## What v1 tools deliberately died
+
+- `expand_handles` — handles ARE the identifiers; nothing to resolve.
+- `init_project` / `link_project` / `check_health` — bootstrap is finding a folder.
+  (`init_plan` exists for MCP-only environments, but it just creates the folder —
+  no server, no settings file, no linking.)
+- `read_plan` / `update_plan` — `get_card("PLAN-PROJECT")` / `update_card`.
+- Bulk variants — at in-memory speed, sequential calls are fine; revisit only if
+  real usage shows tool-call overhead matters.

package/examples/constellation/agent/AGENT-CODE-STYLE.md

@@ -0,0 +1,14 @@
+---
+name: Code style rules
+status: built
+scope: src/**
+applies_to: all-agents
+priority: 1
+---
+
+# Code style
+
+- TypeScript strict mode; no `any` without a comment explaining why.
+- Route handlers validate input with the shapes from [[DATATYPE-TICKET]] and
+  [[DATATYPE-CREATE-TICKET-INPUT]] — never hand-rolled checks.
+- Errors return the shared envelope `{ error: { code, message } }`.

package/examples/constellation/api/API-TICKETS.md

@@ -0,0 +1,24 @@
+---
+name: List & create tickets
+status: built
+path: /api/v1/tickets
+methods:
+  GET:
+    query_params:
+      - { name: status, type: string }
+      - { name: assignee_id, type: string }
+    response_schema: DATATYPE-TICKET
+  POST:
+    request_schema: DATATYPE-CREATE-TICKET-INPUT
+    response_schema: DATATYPE-TICKET
+connections:
+  - DB-TICKETS
+  - ROLE-SUPPORT-AGENT
+---
+
+# Tickets API
+
+GET returns tickets filtered by status and assignee; requires
+[[ROLE-SUPPORT-AGENT]]. POST is the public intake endpoint (no auth) and emits
+[[EVENT-TICKET-CREATED]] after insert — see [[FLOW-CREATE-TICKET]] for the full
+sequence.

package/examples/constellation/component/COMPONENT-TICKET-CARD.md

@@ -0,0 +1,16 @@
+---
+name: Ticket card
+status: building
+framework: svelte
+props:
+  - { name: ticket, type: DATATYPE-TICKET, required: true }
+  - { name: selected, type: boolean }
+variants: [default, compact]
+connections:
+  - PAGE-INBOX
+---
+
+# Ticket card
+
+One ticket in the inbox list: subject, requester, status chip, age. The status
+chip colors follow [[STATE-TICKET]].

package/examples/constellation/datatype/DATATYPE-CREATE-TICKET-INPUT.md

@@ -0,0 +1,15 @@
+---
+name: Create ticket input
+status: built
+---
+
+Request body for creating a ticket. Server assigns `id`, `status`, and timestamps —
+see [[API-TICKETS]].
+
+```ts
+interface CreateTicketInput {
+  subject: string;
+  body: string;
+  requester_email: string;
+}
+```

package/examples/constellation/datatype/DATATYPE-TICKET.md

@@ -0,0 +1,20 @@
+---
+name: Ticket
+status: built
+connections:
+  - DB-TICKETS
+---
+
+The canonical ticket shape, returned by every ticket endpoint.
+
+```ts
+interface Ticket {
+  id: string;
+  subject: string;
+  body: string;
+  status: 'open' | 'assigned' | 'resolved' | 'closed';
+  requester_email: string;
+  assignee_id: string | null;
+  created_at: string; // ISO 8601
+}
+```

package/examples/constellation/db/DB-TICKETS.md

@@ -0,0 +1,21 @@
+---
+name: tickets table
+kind: sql-table
+status: built
+table_name: tickets
+columns:
+  - { name: id, sql_type: UUID, primary_key: true, default: gen_random_uuid() }
+  - { name: subject, sql_type: TEXT, not_null: true }
+  - { name: body, sql_type: TEXT, not_null: true }
+  - { name: status, sql_type: TEXT, not_null: true, default: "'open'" }
+  - { name: requester_email, sql_type: TEXT, not_null: true }
+  - { name: assignee_id, sql_type: UUID }
+  - { name: created_at, sql_type: TIMESTAMPTZ, not_null: true, default: now() }
+indexes:
+  - { name: tickets_status_idx, columns: [status] }
+connections:
+  - DATATYPE-TICKET
+---
+
+One row per ticket. `status` values mirror [[STATE-TICKET]]; rows are never
+deleted, only moved to `closed`.

package/examples/constellation/diagram/DIAGRAM-SYSTEM-OVERVIEW.md

@@ -0,0 +1,19 @@
+---
+name: System overview
+status: built
+---
+
+# System overview
+
+```mermaid
+flowchart LR
+  PAGE-INBOX --> API-TICKETS
+  API-TICKETS --> DB-TICKETS
+  API-TICKETS --> EVENT-TICKET-CREATED
+  EVENT-TICKET-CREATED --> JOB-AUTO-ASSIGN
+  JOB-AUTO-ASSIGN --> DB-TICKETS
+  JOB-AUTO-ASSIGN --> EXTERNAL-EMAIL-PROVIDER
+```
+
+Intake is synchronous down the left edge; everything after the event is
+asynchronous. The job is the only component that talks to the email provider.

package/examples/constellation/doc/DOC-TICKET-LIFECYCLE.md

@@ -0,0 +1,22 @@
+---
+name: How tickets move through the system
+kind: guide
+status: built
+---
+
+# Ticket lifecycle
+
+A ticket is born when the public form posts to [[API-TICKETS]] — the whole
+sequence is [[FLOW-CREATE-TICKET]]. From there it walks the state machine in
+[[STATE-TICKET]]: `open → assigned → resolved → closed`, with one loop back when
+a requester reopens.
+
+Two invariants the code must never break:
+
+1. State transitions happen only in the API layer. Nothing writes the `status`
+   column directly.
+2. Every state change that matters to the requester produces an email through
+   [[EXTERNAL-EMAIL-PROVIDER]] — silence is a bug.
+
+Assignment is asynchronous: [[EVENT-TICKET-CREATED]] decouples intake from
+[[JOB-AUTO-ASSIGN]] so a slow assignment never blocks the requester's submit.

package/examples/constellation/event/EVENT-TICKET-CREATED.md

@@ -0,0 +1,13 @@
+---
+name: Ticket created
+status: built
+emitter: API-TICKETS
+payload_schema: DATATYPE-TICKET
+delivery_semantics: at-least-once
+ordering: none
+idempotency_key_field: id
+version: 1
+---
+
+Fired after a ticket row is committed. Consumers must dedupe on the ticket `id`
+— delivery is at-least-once. Currently the only consumer is [[JOB-AUTO-ASSIGN]].

package/examples/constellation/external/EXTERNAL-EMAIL-PROVIDER.md

@@ -0,0 +1,13 @@
+---
+name: Email provider
+kind: saas-vendor
+status: built
+vendor: Postmark
+purpose: Transactional email (ticket confirmations, assignment notices)
+docs_url: https://postmarkapp.com/developer
+credentials_envs:
+  - POSTMARK_SERVER_TOKEN
+---
+
+All outbound email goes through Postmark. Templates live in the Postmark
+dashboard; this app only sends template IDs and variables, never raw HTML.

package/examples/constellation/file/FILE-TICKETS-ROUTE.md

@@ -0,0 +1,12 @@
+---
+name: tickets route handler
+status: built
+path: src/api/tickets.ts
+language: typescript
+summary: Express route handlers for the tickets API
+connections:
+  - API-TICKETS
+---
+
+Implements [[API-TICKETS]]. Validation lives here; persistence is in the
+repository module it imports.

package/examples/constellation/flow/FLOW-CREATE-TICKET.md

@@ -0,0 +1,16 @@
+---
+name: Create ticket
+status: built
+triggers:
+  - { kind: manual }
+---
+
+# Create ticket
+
+1. Requester submits the public ticket form
+2. [[API-TICKETS]] POST validates the body against [[DATATYPE-CREATE-TICKET-INPUT]]
+   - invalid → 422 with per-field errors
+3. Row inserted into [[DB-TICKETS]] with status `open`
+4. [[EVENT-TICKET-CREATED]] fires
+5. [[JOB-AUTO-ASSIGN]] picks an agent and sends the confirmation email via
+   [[EXTERNAL-EMAIL-PROVIDER]]

package/examples/constellation/job/JOB-AUTO-ASSIGN.md

@@ -0,0 +1,15 @@
+---
+name: Auto-assign tickets
+status: planned
+trigger: event
+max_retries: 3
+connections:
+  - EVENT-TICKET-CREATED
+---
+
+# Auto-assign
+
+Listens for [[EVENT-TICKET-CREATED]], picks the support agent with the fewest
+open tickets, writes the assignment to [[DB-TICKETS]], and sends the requester a
+confirmation email through [[EXTERNAL-EMAIL-PROVIDER]]. Idempotent per ticket `id` —
+re-delivery must not reassign.

package/examples/constellation/page/PAGE-INBOX.md

@@ -0,0 +1,19 @@
+---
+name: Inbox
+status: building
+route: /inbox/:ticket_id?
+path_params:
+  - { name: ticket_id, type: string, required: false }
+query_params:
+  - { name: status, type: string }
+connections:
+  - API-TICKETS
+  - COMPONENT-TICKET-CARD
+  - ROLE-SUPPORT-AGENT
+---
+
+# Inbox
+
+The agent-facing ticket list. Loads tickets from [[API-TICKETS]] and renders each
+as a [[COMPONENT-TICKET-CARD]]. Selecting a ticket opens it inline (the optional
+`ticket_id` path param).

package/examples/constellation/plan.md

@@ -0,0 +1,23 @@
+---
+name: Ticketing example — project plan
+---
+
+# Project Plan
+
+A minimal support-ticket app used as the golden example for the Constellation v2
+format. One card of every type, fully connected.
+
+## Current state
+
+- Core ticket loop is specced: [[FLOW-CREATE-TICKET]], [[STATE-TICKET]],
+  [[API-TICKETS]], [[DB-TICKETS]].
+- Auto-assignment ([[JOB-AUTO-ASSIGN]]) is planned but not built.
+
+## Conventions
+
+- All ticket payloads use [[DATATYPE-TICKET]]; never inline ticket shapes.
+- Email goes through [[EXTERNAL-EMAIL-PROVIDER]] only.
+
+## Last synced
+
+Code was last reconciled against plan commit `<sha>` (maintained by the sync agent).

package/examples/constellation/role/ROLE-SUPPORT-AGENT.md

@@ -0,0 +1,12 @@
+---
+name: Support agent
+status: built
+permissions:
+  - tickets:read
+  - tickets:write
+  - tickets:assign
+issued_by: app
+---
+
+A human agent working the inbox. Can read, update, and assign any ticket.
+Cannot delete tickets — nothing can; see [[DB-TICKETS]].

package/examples/constellation/state/STATE-TICKET.md

@@ -0,0 +1,31 @@
+---
+name: Ticket lifecycle
+status: built
+states:
+  - { name: open, initial: true }
+  - { name: assigned }
+  - { name: resolved }
+  - { name: closed, terminal: true }
+transitions:
+  - { from: open, to: assigned, action: notify assignee }
+  - { from: assigned, to: resolved }
+  - { from: resolved, to: assigned, guard: requester reopens }
+  - { from: resolved, to: closed, guard: requester confirms or 7 days pass }
+connections:
+  - DB-TICKETS
+---
+
+# Ticket lifecycle
+
+```mermaid
+stateDiagram-v2
+  [*] --> open
+  open --> assigned: agent assigned
+  assigned --> resolved: agent resolves
+  resolved --> assigned: requester reopens
+  resolved --> closed: confirmed / 7 days
+  closed --> [*]
+```
+
+The `status` column in the tickets table holds the current state; transitions are
+enforced in the API layer, never by direct column updates.

package/examples/constellation/test/TEST-CREATE-TICKET.md

@@ -0,0 +1,17 @@
+---
+name: Create ticket — integration
+kind: integration
+status: verified
+framework: vitest
+connections:
+  - API-TICKETS
+  - FLOW-CREATE-TICKET
+---
+
+# Create ticket integration test
+
+Covers the full [[FLOW-CREATE-TICKET]] happy path plus the 422 branch:
+
+- valid input → 201, row in [[DB-TICKETS]], event emitted
+- missing subject → 422, no row, no event
+- duplicate delivery of the created event → no double-assignment

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@magic-spells/constellation",
+  "version": "0.1.0",
+  "description": "Files-first architecture planning for AI-assisted development. Your project plan as markdown cards in the repo — typed, connected, queryable, and diffable with git.",
+  "type": "module",
+  "license": "GPL-3.0-or-later",
+  "author": "Cory Schulz <coryschulz@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magic-spells/constellation.git"
+  },
+  "homepage": "https://github.com/magic-spells/constellation#readme",
+  "bugs": "https://github.com/magic-spells/constellation/issues",
+  "files": [
+    "dist",
+    "schemas",
+    "skill",
+    "docs",
+    "examples",
+    "viewer/dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "constellation": "./dist/cli/index.js"
+  },
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "keywords": [
+    "architecture",
+    "planning",
+    "documentation",
+    "markdown",
+    "diagram",
+    "knowledge-graph",
+    "mcp",
+    "cli",
+    "ai",
+    "llm"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build && npm run build:viewer",
+    "dev": "tsx src/cli/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:examples": "tsx src/cli/index.ts lint examples",
+    "build:viewer": "vite build viewer",
+    "demo": "tsx scripts/demo.ts",
+    "dev:viewer": "vite viewer",
+    "serve:examples": "tsx src/cli/index.ts serve examples --no-open"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.17.1",
+    "commander": "^15.0.0",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.2.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@tailwindcss/vite": "^4.3.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.3",
+    "marked": "^18.0.5",
+    "mermaid": "^11.15.0",
+    "svelte": "^5.56.3",
+    "tailwindcss": "^4.3.1",
+    "tsx": "^4.22.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.8"
+  }
+}

package/schemas/agent.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agent.json",
+  "title": "AGENT card frontmatter",
+  "description": "AI agent instructions/policy. The instruction text lives in the body.",
+  "type": "object",
+  "properties": {
+    "scope": {
+      "type": "string",
+      "description": "Glob or directory the instructions apply to, e.g. src/api/**"
+    },
+    "applies_to": {
+      "type": "string",
+      "description": "Which agents this binds, e.g. all-agents or a specific role."
+    },
+    "priority": {
+      "type": "integer",
+      "description": "Higher priority instructions are loaded first."
+    }
+  }
+}

package/schemas/api.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "api.json",
+  "title": "API card frontmatter",
+  "description": "HTTP/RPC endpoint. Schema references are handles of DATATYPE cards.",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "URL pattern, e.g. /api/v1/tickets/:id"
+    },
+    "path_params": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/param" }
+    },
+    "methods": {
+      "type": "object",
+      "propertyNames": {
+        "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "query_params": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/param" }
+          },
+          "request_schema": { "$ref": "card.json#/$defs/handle" },
+          "response_schema": { "$ref": "card.json#/$defs/handle" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "param": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "required": { "type": "boolean" },
+        "default": { "type": "string" },
+        "notes": { "type": "string" }
+      },
+      "required": ["name"]
+    }
+  }
+}

package/schemas/card.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "card.json",
+  "title": "Constellation card — reserved frontmatter keys",
+  "description": "The four reserved keys every card may use. All other frontmatter keys are type-specific fields defined in the per-type schemas.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "maxLength": 200,
+      "description": "Display name. The handle (filename) is the identity; this is the human label."
+    },
+    "kind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "maxLength": 64,
+      "description": "Subtype discriminator, lowercase slug (e.g. sql-table, e2e, decision)."
+    },
+    "status": {
+      "enum": ["planned", "building", "built", "verified"],
+      "description": "Lifecycle state. Orthogonal to git history: 'what changed' comes from git, not from this field."
+    },
+    "connections": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/handle" },
+      "description": "Plain list of handles this card is connected to. Undirected; declare on whichever card you are editing."
+    }
+  },
+  "$defs": {
+    "handle": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$",
+      "minLength": 3,
+      "maxLength": 135
+    }
+  }
+}