ai-spector 0.1.0

package/scaffold/.cursor/skills/ai-spector/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ai-spector
+description: "Cursor-first docs: user runs slash commands; agent runs CLI; on CLI failure stop and help fix — no manual bypass."
+---
+
+# AI Spector Skill
+
+**Workflow:** `.cursor/commands/_workflow.md` — user only runs `npx ai-spector init` once, then slash commands.
+
+## CLI failure rule (non-negotiable)
+
+When `ai-spector` exits non-zero or required `--json` is missing/invalid:
+
+1. **Stop** — no generate, no bulk `docs/srs/**` reads, no hand-editing the whole graph.
+2. **Report** using the format in `.cursor/commands/_cli-failures.md` (verbatim CLI output + plain fix steps).
+3. **Fix** the root cause, then **re-run the same CLI** and continue the slash command.
+
+Never ignore CLI errors and “work around” with index files, manual BFS, or inventing graph content. See `_cli-failures.md` for forbidden fallbacks.
+
+## Slash commands (user)
+
+| Command | Agent runs CLI |
+|---------|----------------|
+| `/analyze` | `analyze` → Graphify → `graph merge --from-knowledge` → `graph validate` |
+| `/validate-graph` | `graph validate` |
+| `/visualize-graph` | `graph visualize --open` |
+| `/generate-srs` | `graph validate` + `graph query <seed> --json` per target |
+| `/graph-impact` | `graph impact <id> --json` |
+| `/generate-basic-design`, `/generate-detail-design` | `graph query` per target |
+
+Run CLI from **project workspace root**; prefer `npx ai-spector` if the binary is not on PATH.
+
+## Heart of the system
+
+`.ai-spector/graph/traceability.graph.json`
+
+Context: **`ai-spector graph query <seedId> --json`** — only after validate passes; use `projectionPaths` from stdout. Details: `_graph.md`.
+
+Templates: `node_modules/ai-spector/templates/` (monorepo `example/`: `../templates/`).

package/scaffold/docs/data-source/README.md

@@ -0,0 +1,7 @@
+# Data source
+
+Default input folder for AI Spector. Place materials here before running `/analyze`, `/generate-srs`, or `/generate-basic-design`.
+
+Examples: product briefs, meeting notes, API exports, ERDs, wireframes, legacy SRS fragments, spreadsheets, or code-adjacent reference docs.
+
+Override the default by passing explicit paths to `/analyze`.

package/schemas/rules.impact.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "description": "Impact propagation rules (P1+). P0 stub for future /graph-impact.",
+  "edgePropagation": {
+    "partOf": { "direction": "out", "depth": "unbounded" },
+    "contains": { "direction": "in", "depth": "unbounded" },
+    "satisfies": { "direction": "in", "depth": 1 },
+    "dependsOn": { "direction": "out", "depth": "unbounded" },
+    "definedIn": { "direction": "in", "depth": 1 },
+    "listedIn": { "direction": "in", "depth": 1 }
+  },
+  "buckets": {
+    "regenerate": ["section", "document"],
+    "review": ["useCase", "feature", "requirement"],
+    "downstream": ["document"]
+  }
+}

package/schemas/rules.traceability.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "id": "SCHEMA",
+      "severity": "error",
+      "description": "Graph must validate against schema.graph.json"
+    },
+    {
+      "id": "REGISTRY-COMPLETE",
+      "severity": "error",
+      "description": "Every registry document and section must exist in the graph"
+    },
+    {
+      "id": "SECTION-TREE",
+      "severity": "error",
+      "description": "Each section has exactly one partOf parent"
+    },
+    {
+      "id": "DOC-SECTION-COVERAGE",
+      "severity": "error",
+      "description": "Each document contains at least one section"
+    },
+    {
+      "id": "DOMAIN-ANCHORED",
+      "severity": "error",
+      "description": "Domain nodes must link to sections via listedIn, definedIn, or describedIn"
+    }
+  ]
+}

package/schemas/schema.extract-patch.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-spector.local/schemas/schema.extract-patch.json",
+  "title": "ExtractPatch",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "https://ai-spector.local/graph/schema.graph.json#/$defs/node" }
+    },
+    "edges": {
+      "type": "array",
+      "items": { "$ref": "https://ai-spector.local/graph/schema.graph.json#/$defs/edge" }
+    }
+  }
+}

package/schemas/schema.graph.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-spector.local/graph/schema.graph.json",
+  "title": "TraceabilityGraph",
+  "type": "object",
+  "required": ["version", "nodes", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/node" }
+    },
+    "edges": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/edge" }
+    }
+  },
+  "$defs": {
+    "nodeType": {
+      "type": "string",
+      "enum": [
+        "document",
+        "section",
+        "table",
+        "diagram",
+        "actor",
+        "useCase",
+        "feature",
+        "requirement",
+        "dataEntity"
+      ]
+    },
+    "edgeType": {
+      "type": "string",
+      "enum": [
+        "partOf",
+        "contains",
+        "follows",
+        "references",
+        "listedIn",
+        "definedIn",
+        "describedIn",
+        "satisfies",
+        "dependsOn",
+        "requires",
+        "tracesTo",
+        "derivedFrom",
+        "rendersTo"
+      ]
+    },
+    "node": {
+      "type": "object",
+      "required": ["id", "type"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "$ref": "#/$defs/nodeType" },
+        "template": { "type": "string" },
+        "output": { "type": "string" },
+        "outputPattern": { "type": "string" },
+        "perDomain": { "type": "string", "enum": ["useCase", "feature"] },
+        "documentId": { "type": "string" },
+        "heading": { "type": "string" },
+        "level": { "type": "integer", "minimum": 2, "maximum": 6 },
+        "order": { "type": "integer", "minimum": 0 },
+        "title": { "type": "string" },
+        "slug": { "type": "string" }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "required": ["type", "from", "to"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "$ref": "#/$defs/edgeType" },
+        "from": { "type": "string", "minLength": 1 },
+        "to": { "type": "string", "minLength": 1 },
+        "role": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/schema.knowledge.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-spector.local/schemas/schema.knowledge.json",
+  "title": "AnalysisKnowledge",
+  "type": "object",
+  "required": ["knowledgeVersion", "actors", "useCases", "features"],
+  "additionalProperties": true,
+  "properties": {
+    "knowledgeVersion": { "type": "integer", "minimum": 1 },
+    "generatedAt": { "type": ["string", "null"] },
+    "scope": { "type": "array", "items": { "type": "string" } },
+    "actors": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/actor" }
+    },
+    "useCases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/useCase" }
+    },
+    "features": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/feature" }
+    },
+    "functionalRequirements": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/requirement" }
+    },
+    "nfrs": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/requirement" }
+    },
+    "entities": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entity" }
+    },
+    "interfaces": { "type": "array" },
+    "constraints": { "type": "array" },
+    "openQuestions": { "type": "array" }
+  },
+  "$defs": {
+    "actor": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "listedInSection": { "type": "string", "minLength": 1 }
+      }
+    },
+    "useCase": {
+      "type": "object",
+      "required": ["id", "title"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string" },
+        "priority": { "type": "string" },
+        "description": { "type": "string" },
+        "listedInSection": { "type": "string", "minLength": 1 }
+      }
+    },
+    "feature": {
+      "type": "object",
+      "required": ["id", "title"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "listedInSection": { "type": "string", "minLength": 1 },
+        "satisfies": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "requirement": {
+      "type": "object",
+      "required": ["id", "title"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "listedInSection": { "type": "string", "minLength": 1 },
+        "tracesTo": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "entity": {
+      "type": "object",
+      "required": ["id", "name"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "listedInSection": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/templates/basic_design/db-design-template.md

@@ -0,0 +1,177 @@
+# Database Design: <Project Name>
+
+> This document explains the database structure and purpose of each table, helping developers, QA, and DBAs understand data relationships and design rationale.
+
+**Source Requirements:** SRS Section 5 (Data Requirements)
+
+---
+
+## 1. Overview
+
+**Database Management System:** <PostgreSQL/MySQL/Other>
+
+**Purpose:**
+> Describe the main purpose of the database and what business flows it supports.
+
+**Source Requirements:**
+> Reference SRS sections that informed this design.
+- SRS Section 4: <Functional Requirements>
+- SRS Section 5: <Data Requirements>
+- SRS Section 7: <Quality Attributes>
+
+---
+
+## 2. Entity-Relationship Diagram
+
+> Provide a visual representation of tables and their relationships.
+
+```mermaid
+erDiagram
+    ENTITY1 ||--o{ ENTITY2 : "relationship"
+    ENTITY1 {
+        int id PK
+        string name
+        datetime created_at
+    }
+    ENTITY2 {
+        int id PK
+        int entity1_id FK
+        string description
+    }
+```
+
+---
+
+## 3. Table List and Roles
+
+| Table Name | Purpose | Main Relationships |
+|------------|---------|-------------------|
+| `<table_name>` | <Purpose description> | <Relationship description> |
+| `<table_name>` | <Purpose description> | <Relationship description> |
+
+---
+
+## 4. Detailed Table Descriptions
+
+### 4.1 `<table_name>`
+
+**Purpose:**
+> Describe what this table stores and its role in the system.
+
+**Primary Key:** `<field_name>` (<data_type>)
+
+**Key Fields:**
+
+| Field Name | Data Type | Constraints | Description |
+|------------|-----------|-------------|-------------|
+| `<field_name>` | `<type>` | `<UNIQUE/NOT NULL/CHECK>` | <Description> |
+| `<field_name>` | `<type>` | `<constraints>` | <Description> |
+
+**Important Design Decisions:**
+- <Decision 1 and rationale>
+- <Decision 2 and rationale>
+
+**Foreign Keys:**
+- `<field_name>` → `<referenced_table>.<referenced_field>` (<relationship description>)
+
+**Indexes:**
+- `<index_name>` on `<field_name>` (<purpose>)
+
+**Business Rules:**
+- <Business rule 1>
+- <Business rule 2>
+
+---
+
+### 4.2 `<table_name>`
+
+**Purpose:**
+> Describe what this table stores.
+
+**Primary Key:** `<field_name>` (<data_type>)
+
+**Key Fields:**
+
+| Field Name | Data Type | Constraints | Description |
+|------------|-----------|-------------|-------------|
+| `<field_name>` | `<type>` | `<constraints>` | <Description> |
+
+**Foreign Keys:**
+- `<field_name>` → `<referenced_table>.<referenced_field>`
+
+**Indexes:**
+- `<index_name>` on `<field_name>`
+
+---
+
+## 5. Relationships Summary
+
+> Document all relationships between tables.
+
+| From Table | Relationship Type | To Table | Description |
+|------------|-------------------|----------|-------------|
+| `<table1>` | One-to-Many | `<table2>` | <Description> |
+| `<table1>` | Many-to-Many | `<table2>` | <Description> |
+
+---
+
+## 6. Data Integrity Rules
+
+**Constraints:**
+- <Constraint 1>
+- <Constraint 2>
+
+**Validation Rules:**
+- <Validation rule 1>
+- <Validation rule 2>
+
+**Referential Integrity:**
+- <Cascade/restrict/set null behavior>
+
+---
+
+## 7. Performance Considerations
+
+**Indexes:**
+> List indexes for query optimization.
+
+| Index Name | Table | Fields | Purpose |
+|------------|-------|--------|---------|
+| `<index_name>` | `<table>` | `<fields>` | <Purpose> |
+
+**Query Optimization Notes:**
+- <Note 1>
+- <Note 2>
+
+---
+
+## 8. Security Considerations
+
+**Access Control:**
+- <Access control requirement 1>
+- <Access control requirement 2>
+
+**Data Protection:**
+- <Protection measure 1>
+- <Protection measure 2>
+
+---
+
+## 9. Future Extensions
+
+> Document potential future enhancements or changes.
+
+- <Extension 1>
+- <Extension 2>
+
+---
+
+## 10. Notes
+
+**Migration Strategy:**
+> Reference migration tool or approach (e.g., Flyway, Liquibase).
+
+**Testing Considerations:**
+- <Testing note 1>
+- <Testing note 2>
+