@magic-spells/constellation 0.1.0

package/schemas/component.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "component.json",
+  "title": "COMPONENT card frontmatter",
+  "description": "Reusable UI component.",
+  "type": "object",
+  "properties": {
+    "framework": {
+      "type": "string",
+      "description": "e.g. svelte, react, web-component"
+    },
+    "props": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "type": "string" },
+          "required": { "type": "boolean" }
+        },
+        "required": ["name"]
+      }
+    },
+    "slots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "accepts": { "type": "array", "items": { "type": "string" } }
+        },
+        "required": ["name"]
+      }
+    },
+    "variants": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/datatype.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "datatype.json",
+  "title": "DATATYPE card frontmatter",
+  "description": "Data type schema. No structured fields: the type declaration lives in the body as a fenced code block (```ts, ```sql, etc.).",
+  "type": "object",
+  "properties": {}
+}

package/schemas/db.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "db.json",
+  "title": "DB card frontmatter",
+  "description": "Database table or collection. Suggested kinds: sql-table, document-collection, kv, time-series, graph.",
+  "type": "object",
+  "properties": {
+    "table_name": {
+      "type": "string",
+      "description": "Physical table/collection name, e.g. tickets"
+    },
+    "columns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "sql_type": { "type": "string" },
+          "primary_key": { "type": "boolean" },
+          "not_null": { "type": "boolean" },
+          "unique": { "type": "boolean" },
+          "default": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    },
+    "indexes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "columns": { "type": "array", "items": { "type": "string" } },
+          "unique": { "type": "boolean" }
+        }
+      }
+    },
+    "foreign_keys": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "columns": { "type": "array", "items": { "type": "string" } },
+          "references_table": { "type": "string" },
+          "references_columns": { "type": "array", "items": { "type": "string" } },
+          "on_delete": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/diagram.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "diagram.json",
+  "title": "DIAGRAM card frontmatter",
+  "description": "Architecture diagram. Default: a ```mermaid block in the body (handles as node IDs). These structured fields are the pinned-layout escape hatch for curated diagrams where positions carry meaning.",
+  "type": "object",
+  "properties": {
+    "nodes": {
+      "type": "array",
+      "maxItems": 300,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "$ref": "#/$defs/slug" },
+          "label": { "type": "string", "maxLength": 200 },
+          "shape": {
+            "enum": [
+              "rounded_rectangle", "rectangle", "pill", "cylinder", "queue",
+              "hexagon", "cloud", "actor", "diamond", "circle", "note"
+            ]
+          },
+          "group": {
+            "enum": [
+              "client", "service", "middleware", "gateway",
+              "datastore", "queue", "external", "infra"
+            ]
+          },
+          "position": {
+            "type": "object",
+            "properties": {
+              "x": { "type": "number" },
+              "y": { "type": "number" }
+            },
+            "required": ["x", "y"]
+          },
+          "size": {
+            "type": "object",
+            "properties": {
+              "w": { "type": "number", "exclusiveMinimum": 0 },
+              "h": { "type": "number", "exclusiveMinimum": 0 }
+            }
+          },
+          "phase": { "$ref": "#/$defs/slug" },
+          "description": { "type": "string", "maxLength": 2000 },
+          "refs": {
+            "type": "array",
+            "maxItems": 50,
+            "items": { "$ref": "card.json#/$defs/handle" },
+            "description": "Handles of the cards this diagram node depicts."
+          }
+        },
+        "required": ["id", "label", "position"]
+      }
+    },
+    "edges": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": {
+        "type": "object",
+        "properties": {
+          "from": { "$ref": "#/$defs/slug" },
+          "to": { "$ref": "#/$defs/slug" },
+          "label": { "type": "string", "maxLength": 200 },
+          "direction": { "enum": ["from_to", "to_from", "both", "none"] },
+          "style": { "enum": ["solid", "dashed"] },
+          "from_side": { "enum": ["top", "right", "bottom", "left"] },
+          "to_side": { "enum": ["top", "right", "bottom", "left"] },
+          "phase": { "$ref": "#/$defs/slug" }
+        },
+        "required": ["from", "to"]
+      }
+    },
+    "phases": {
+      "type": "array",
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "$ref": "#/$defs/slug" },
+          "label": { "type": "string", "maxLength": 120 },
+          "order": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["id", "label", "order"]
+      }
+    }
+  },
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]*$",
+      "minLength": 1,
+      "maxLength": 64
+    }
+  }
+}

package/schemas/doc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "doc.json",
+  "title": "DOC card frontmatter",
+  "description": "Documentation card. No structured fields: prose lives in the body. Suggested kinds: guide, rule, decision, meta.",
+  "type": "object",
+  "properties": {}
+}

package/schemas/event.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "event.json",
+  "title": "EVENT card frontmatter",
+  "description": "Domain event or signal. References are handles.",
+  "type": "object",
+  "properties": {
+    "emitter": {
+      "$ref": "card.json#/$defs/handle",
+      "description": "Handle of the card that emits this event."
+    },
+    "payload_schema": {
+      "$ref": "card.json#/$defs/handle",
+      "description": "Handle of the DATATYPE card describing the payload."
+    },
+    "delivery_semantics": {
+      "enum": ["at-least-once", "at-most-once", "exactly-once"]
+    },
+    "ordering": {
+      "enum": ["per-aggregate", "total", "none"]
+    },
+    "idempotency_key_field": {
+      "type": "string",
+      "description": "Payload field consumers dedupe on, e.g. event_id."
+    },
+    "version": { "type": "integer", "minimum": 1 }
+  }
+}

package/schemas/external.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "external.json",
+  "title": "EXTERNAL card frontmatter",
+  "description": "External service or integration. Suggested kinds: saas-vendor, cloud-infra, external-microservice, hardware-peripheral.",
+  "type": "object",
+  "properties": {
+    "vendor": {
+      "type": "string",
+      "description": "Vendor or platform name, e.g. Stripe."
+    },
+    "purpose": {
+      "type": "string",
+      "description": "What this service is used for."
+    },
+    "docs_url": { "type": "string" },
+    "status_url": { "type": "string" },
+    "credentials_envs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Environment variable NAMES holding credentials. Never values."
+    }
+  }
+}

package/schemas/file.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "file.json",
+  "title": "FILE card frontmatter",
+  "description": "Source file reference. The only card type with a required field: a file reference without a path refers to nothing.",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "Path relative to the repo root, e.g. src/api/tickets.ts"
+    },
+    "language": {
+      "type": "string",
+      "description": "e.g. typescript, python, go"
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line description of what the file does."
+    }
+  },
+  "required": ["path"]
+}

package/schemas/flow.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "flow.json",
+  "title": "FLOW card frontmatter",
+  "description": "Multi-step sequenced process. Steps live in the BODY as a numbered markdown list (with nested items for edge cases), not in frontmatter.",
+  "type": "object",
+  "properties": {
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kind": { "enum": ["cron", "event", "manual"] },
+          "schedule": { "type": "string" },
+          "event": { "$ref": "card.json#/$defs/handle" }
+        }
+      }
+    }
+  }
+}

package/schemas/job.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "job.json",
+  "title": "JOB card frontmatter",
+  "description": "Background, scheduled, or queue-triggered work.",
+  "type": "object",
+  "properties": {
+    "trigger": {
+      "enum": ["cron", "queue", "event", "manual"]
+    },
+    "schedule": {
+      "type": "string",
+      "description": "Cron expression when trigger is cron, e.g. */15 * * * *"
+    },
+    "flow": {
+      "$ref": "card.json#/$defs/handle",
+      "description": "Handle of the FLOW this job executes, if any."
+    },
+    "max_retries": { "type": "integer", "minimum": 0 },
+    "idempotency_key": {
+      "type": "string",
+      "description": "Field or expression that makes runs idempotent."
+    }
+  }
+}

package/schemas/page.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "page.json",
+  "title": "PAGE card frontmatter",
+  "description": "Frontend route/screen. Route fields are flat (no nested route object).",
+  "type": "object",
+  "properties": {
+    "route": {
+      "type": "string",
+      "description": "URL pattern, e.g. /inbox/:ticket_id"
+    },
+    "parent": {
+      "$ref": "card.json#/$defs/handle",
+      "description": "Handle of the parent PAGE (layout/shell) this page nests under."
+    },
+    "path_params": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/param" }
+    },
+    "query_params": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/param" }
+    }
+  },
+  "$defs": {
+    "param": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "required": { "type": "boolean" }
+      },
+      "required": ["name"]
+    }
+  }
+}

package/schemas/plan.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "plan.json",
+  "title": "PLAN card frontmatter",
+  "description": "Plan document. constellation/plan.md is PLAN-PROJECT; scoped plans (PLAN-FRONTEND) live in plan/. Keep plans short — decisions belong in DOC cards (kind: decision), status on the cards themselves.",
+  "type": "object",
+  "properties": {
+    "scope": {
+      "type": "string",
+      "description": "Area this plan covers, e.g. frontend. Omit for the project plan."
+    }
+  }
+}

package/schemas/role.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "role.json",
+  "title": "ROLE card frontmatter",
+  "description": "User role or permission group.",
+  "type": "object",
+  "properties": {
+    "permissions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Permission strings, conventionally resource:action (e.g. tickets:read)."
+    },
+    "issued_by": {
+      "type": "string",
+      "description": "Who grants this role, e.g. app, org, tenant, os."
+    }
+  }
+}

package/schemas/state.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "state.json",
+  "title": "STATE card frontmatter",
+  "description": "State machine. Prefer a ```mermaid stateDiagram-v2 block in the body; structured states/transitions are optional for tooling that needs them.",
+  "type": "object",
+  "properties": {
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "initial": { "type": "boolean" },
+          "terminal": { "type": "boolean" }
+        },
+        "required": ["name"]
+      }
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "event": { "$ref": "card.json#/$defs/handle" },
+          "guard": { "type": "string" },
+          "action": { "type": "string" }
+        },
+        "required": ["from", "to"]
+      }
+    }
+  }
+}

package/schemas/test.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "test.json",
+  "title": "TEST card frontmatter",
+  "description": "Test spec. Use the reserved kind for the category (unit, integration, e2e). Connect to the cards the test covers.",
+  "type": "object",
+  "properties": {
+    "framework": {
+      "type": "string",
+      "description": "Test runner, e.g. vitest, jest, pytest, playwright."
+    }
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: constellation
+description: Author and edit Constellation plan cards — markdown files in a constellation/ folder that model a project's architecture as a typed, connected graph. Use when creating, updating, or querying cards (API endpoints, data types, DB tables, flows, pages, etc.) in any repo with a constellation/ directory.
+---
+
+# Constellation cards
+
+A Constellation plan is a folder of markdown files. Each file is one **card** — one
+typed piece of the plan, linked to other cards by **connections**. Filenames are
+identities, frontmatter is structure, the body is prose, and git is the
+change-tracking system.
+
+## The one rule that matters most
+
+**The filename is the handle.** `constellation/api/API-TICKETS.md` defines the card
+`API-TICKETS`. The prefix (before the first dash) determines the type. Never put
+`handle:` or `type:` in frontmatter.
+
+Handle grammar: `^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$` — uppercase letters, digits,
+dashes only. No underscores, no lowercase.
+
+## Types, prefixes, folders
+
+| Prefix       | Folder       | Use for                          | Reference            |
+|--------------|--------------|----------------------------------|----------------------|
+| `API-`       | `api/`       | HTTP/RPC endpoints               | `types/api.md`       |
+| `DB-`        | `db/`        | Tables / collections             | `types/db.md`        |
+| `DATATYPE-`  | `datatype/`  | Type schemas                     | `types/datatype.md`  |
+| `ROLE-`      | `role/`      | Roles / permissions              | `types/role.md`      |
+| `DOC-`       | `doc/`       | Documentation, rules, decisions  | `types/doc.md`       |
+| `FILE-`      | `file/`      | Source file references           | `types/file.md`      |
+| `TEST-`      | `test/`      | Test specs                       | `types/test.md`      |
+| `EXTERNAL-`  | `external/`  | External services                | `types/external.md`  |
+| `EVENT-`     | `event/`     | Domain events                    | `types/event.md`     |
+| `COMPONENT-` | `component/` | UI components                    | `types/component.md` |
+| `PAGE-`      | `page/`      | Routes / screens                 | `types/page.md`      |
+| `JOB-`       | `job/`       | Background / scheduled work      | `types/job.md`       |
+| `FLOW-`      | `flow/`      | Step-by-step processes           | `types/flow.md`      |
+| `STATE-`     | `state/`     | State machines                   | `types/state.md`     |
+| `DIAGRAM-`   | `diagram/`   | Architecture diagrams            | `types/diagram.md`   |
+| `AGENT-`     | `agent/`     | AI agent instructions            | `types/agent.md`     |
+| `PLAN-`      | `plan/`      | Plan docs (`plan.md` at root = `PLAN-PROJECT`) | `types/plan.md` |
+
+Read the matching `types/<type>.md` before writing a card of a type you haven't
+authored in this session — it has the field table and a golden example.
+
+## Frontmatter
+
+Four reserved keys, all optional. Everything else is a type-specific field (see the
+type reference). Don't invent fields when the type reference defines one for the
+purpose — but unknown extra fields are allowed (lint warns, doesn't fail).
+
+```yaml
+name: List & create tickets        # display label (handle is the identity)
+kind: sql-table                    # lowercase-slug subtype, when the type has variants
+status: built                      # planned | building | built | verified
+connections:                       # plain list of handles — no kinds, no direction
+  - DB-TICKETS
+```
+
+## Connections — how the graph gets wired
+
+Connections are undirected and come from four places; all count equally:
+
+1. The `connections:` list.
+2. Any handle-shaped value in other frontmatter fields (`response_schema: DATATYPE-TICKET`
+   connects automatically — don't repeat it in `connections`).
+3. `[[HANDLE]]` wiki-links in the body — use these freely in prose; they're the
+   cheapest way to connect cards.
+4. Handle-shaped node IDs inside ```mermaid blocks.
+
+Declare a connection on whichever card you're editing — the other card sees it via
+the index. Never edit two cards just to record one connection.
+
+**Frontmatter references must resolve** (lint error if the target card doesn't
+exist). Body `[[links]]` may point at cards not yet written (lint warning only) —
+that's how you mark future work.
+
+## Body conventions
+
+- DATATYPE: the type declaration as a fenced code block (```ts).
+- FLOW: a numbered markdown list of steps; nested items for error/edge branches.
+  If it genuinely branches, it's a Mermaid flowchart or a STATE card instead.
+- STATE: a ```mermaid stateDiagram-v2 block.
+- DIAGRAM: a ```mermaid flowchart with **handles as node IDs** so the diagram joins
+  the graph.
+- Everything else: prose with `[[links]]`. Put relationship nuance in prose, not
+  in structure.
+
+## Workflow
+
+1. Before creating a card, check it doesn't exist: the filename is deterministic,
+   so look up `constellation/<folder>/<HANDLE>.md`; grep for the handle to find
+   prose references.
+2. Write or edit the card.
+3. Verify: `npx constellation lint` (errors break the graph and must be fixed;
+   warnings are quality signals).
+4. Update `status` when reality changes: `planned → building → built`, and
+   `verified` only after checking the card against the actual code.
+5. Never bulk-rewrite `constellation/plan.md` — edit the relevant section.
+   Decisions go in DOC cards (`kind: decision`), one file each, not in the plan.
+
+"What changed in the plan" is never tracked in cards — that's
+`git diff -- constellation/`. Don't add dirty flags, changelogs, or timestamps to
+frontmatter.

package/skill/types/agent.md

@@ -0,0 +1,26 @@
+# AGENT cards (`AGENT-`, `agent/`)
+
+AI agent instructions/policies — the plan-level equivalent of a scoped CLAUDE.md.
+The instruction text is the body.
+
+| Field | Type | Notes |
+|---|---|---|
+| `scope` | string | glob/directory the rules apply to |
+| `applies_to` | string | `all-agents` or a specific role |
+| `priority` | integer | higher loads first |
+
+Example — `constellation/agent/AGENT-CODE-STYLE.md`:
+
+```markdown
+---
+name: Code style rules
+status: built
+scope: src/**
+applies_to: all-agents
+priority: 1
+---
+
+- TypeScript strict mode; no `any` without a comment explaining why.
+- Route handlers validate input with the shapes from [[DATATYPE-TICKET]] —
+  never hand-rolled checks.
+```

package/skill/types/api.md

@@ -0,0 +1,38 @@
+# API cards (`API-`, `api/`)
+
+One card per endpoint path (methods nest inside). Schema references are DATATYPE
+handles and connect automatically.
+
+| Field | Type | Notes |
+|---|---|---|
+| `path` | string | URL pattern, e.g. `/api/v1/tickets/:id` |
+| `path_params` | array | `{ name, type?, required?, default?, notes? }` |
+| `methods` | object | Keys: `GET POST PUT PATCH DELETE HEAD OPTIONS` |
+| `methods.<VERB>.query_params` | array | same param shape |
+| `methods.<VERB>.request_schema` | handle | DATATYPE card |
+| `methods.<VERB>.response_schema` | handle | DATATYPE card |
+
+Example — `constellation/api/API-TICKETS.md`:
+
+```markdown
+---
+name: List & create tickets
+status: built
+path: /api/v1/tickets
+methods:
+  GET:
+    query_params:
+      - { name: status, type: string }
+    response_schema: DATATYPE-TICKET
+  POST:
+    request_schema: DATATYPE-CREATE-TICKET-INPUT
+    response_schema: DATATYPE-TICKET
+connections:
+  - DB-TICKETS
+---
+
+# Tickets API
+
+GET returns tickets filtered by status. POST is the public intake endpoint and
+emits [[EVENT-TICKET-CREATED]] after insert — see [[FLOW-CREATE-TICKET]].
+```

package/skill/types/component.md

@@ -0,0 +1,30 @@
+# COMPONENT cards (`COMPONENT-`, `component/`)
+
+One card per reusable UI component. Prop types may be handles
+(`type: DATATYPE-TICKET`) — those connect automatically.
+
+| Field | Type | Notes |
+|---|---|---|
+| `framework` | string | `svelte`, `react`, `web-component`, … |
+| `props` | array | `{ name, type?, required? }` |
+| `slots` | array | `{ name, accepts? }` |
+| `variants` | string[] | |
+
+Example — `constellation/component/COMPONENT-TICKET-CARD.md`:
+
+```markdown
+---
+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
+---
+
+One ticket in the inbox list: subject, requester, status chip, age. The status
+chip colors follow [[STATE-TICKET]].
+```