ai-spector 0.1.0

package/scaffold/.ai-spector/.docflow/config/completeness-rules.detail-design.json

@@ -0,0 +1,57 @@
+{
+  "version": 1,
+  "defaultChecks": {
+    "disallowPlaceholders": [
+      "<",
+      "TODO",
+      "TBD"
+    ],
+    "requireNonEmptyTables": true,
+    "validateMarkdownLinks": true
+  },
+  "rules": [
+    {
+      "target": "feature-list.md",
+      "requiredHeadings": [
+        "# Detail Design: Feature List",
+        "## 1. List of Features"
+      ]
+    },
+    {
+      "target": "common/architecture-overview.md",
+      "requiredHeadings": [
+        "# Architecture Overview"
+      ]
+    },
+    {
+      "target": "common/security-patterns.md",
+      "requiredHeadings": [
+        "# Security Patterns"
+      ]
+    },
+    {
+      "target": "common/error-handling-patterns.md",
+      "requiredHeadings": [
+        "# Error Handling Patterns"
+      ]
+    },
+    {
+      "target": "common/performance-standards.md",
+      "requiredHeadings": [
+        "# Performance Standards"
+      ]
+    },
+    {
+      "target": "common/integration-patterns.md",
+      "requiredHeadings": [
+        "# Integration Patterns"
+      ]
+    },
+    {
+      "target": "common/deployment-infrastructure.md",
+      "requiredHeadings": [
+        "# Deployment and Infrastructure"
+      ]
+    }
+  ]
+}

package/scaffold/.ai-spector/.docflow/config/completeness-rules.srs.json

@@ -0,0 +1,72 @@
+{
+  "version": 1,
+  "defaultChecks": {
+    "disallowPlaceholders": [
+      "<",
+      "TODO",
+      "TBD"
+    ],
+    "requireNonEmptyTables": true,
+    "validateMarkdownLinks": true
+  },
+  "rules": [
+    {
+      "target": "1-introduction.md",
+      "requiredHeadings": [
+        "## 1. Introduction",
+        "### 1.1 Document Purpose",
+        "### 1.3 Project Scope"
+      ]
+    },
+    {
+      "target": "2-overall-description.md",
+      "requiredHeadings": [
+        "## 2. Overall Description"
+      ]
+    },
+    {
+      "target": "3-use-cases.md",
+      "requiredHeadings": [
+        "## 3. Use Cases",
+        "### 3.1 Use Case Diagrams",
+        "### 3.2 List Use Case"
+      ]
+    },
+    {
+      "target": "4-system-features.md",
+      "requiredHeadings": [
+        "## 4. System Features"
+      ]
+    },
+    {
+      "target": "5-data-requirements.md",
+      "requiredHeadings": [
+        "## 5. Data Requirements"
+      ]
+    },
+    {
+      "target": "6-external-interfaces.md",
+      "requiredHeadings": [
+        "## 6. External Interface Requirements"
+      ]
+    },
+    {
+      "target": "7-quality-attributes.md",
+      "requiredHeadings": [
+        "## 7. Quality Attributes"
+      ]
+    },
+    {
+      "target": "8-internationalization.md",
+      "requiredHeadings": [
+        "## 8. Internationalization and Localization"
+      ]
+    },
+    {
+      "target": "9-other-requirements.md",
+      "requiredHeadings": [
+        "## 9. Other Requirements"
+      ]
+    }
+  ]
+}

package/scaffold/.ai-spector/.docflow/config/dag.basic-design.json

@@ -0,0 +1,38 @@
+{
+  "version": 1,
+  "root": "docs/basic-design",
+  "nodes": [
+    {
+      "id": "bd.db-design",
+      "template": "basic_design/db-design-template.md",
+      "output": "db-design.md",
+      "dependsOn": []
+    },
+    {
+      "id": "bd.list-api",
+      "template": "basic_design/list-api-template.md",
+      "output": "api-list.md",
+      "dependsOn": []
+    },
+    {
+      "id": "bd.detail-api",
+      "template": "basic_design/detail-api-template.md",
+      "output": "api/",
+      "dependsOn": ["bd.list-api"],
+      "mode": "perEndpoint"
+    },
+    {
+      "id": "bd.list-screen",
+      "template": "basic_design/list-screen-template.md",
+      "output": "screens/list-screens.md",
+      "dependsOn": []
+    },
+    {
+      "id": "bd.detail-screen",
+      "template": "basic_design/detail-screen-template.md",
+      "output": "screens/",
+      "dependsOn": ["bd.list-screen"],
+      "mode": "perScreen"
+    }
+  ]
+}

package/scaffold/.ai-spector/.docflow/config/dag.detail-design.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "root": "docs/detail-design",
+  "nodes": [
+    {
+      "id": "dd.common.architecture-overview",
+      "template": "detail_design/common/architecture-overview-template.md",
+      "output": "common/architecture-overview.md",
+      "dependsOn": []
+    },
+    {
+      "id": "dd.common.security-patterns",
+      "template": "detail_design/common/security-patterns-template.md",
+      "output": "common/security-patterns.md",
+      "dependsOn": []
+    },
+    {
+      "id": "dd.common.error-handling",
+      "template": "detail_design/common/error-handling-patterns-template.md",
+      "output": "common/error-handling-patterns.md",
+      "dependsOn": []
+    },
+    {
+      "id": "dd.common.performance-standards",
+      "template": "detail_design/common/performance-standards-template.md",
+      "output": "common/performance-standards.md",
+      "dependsOn": []
+    },
+    {
+      "id": "dd.common.integration-patterns",
+      "template": "detail_design/common/integration-patterns-template.md",
+      "output": "common/integration-patterns.md",
+      "dependsOn": []
+    },
+    {
+      "id": "dd.common.deployment",
+      "template": "detail_design/common/deployment-infrastructure-template.md",
+      "output": "common/deployment-infrastructure.md",
+      "dependsOn": []
+    },
+    {
+      "id": "dd.feature-list",
+      "template": "detail_design/feature-list-template.md",
+      "output": "feature-list.md",
+      "dependsOn": [
+        "dd.common.architecture-overview",
+        "dd.common.security-patterns",
+        "dd.common.error-handling",
+        "dd.common.performance-standards",
+        "dd.common.integration-patterns",
+        "dd.common.deployment"
+      ]
+    },
+    {
+      "id": "dd.feature-details",
+      "template": "detail_design/feature-detail-design-template.md",
+      "output": "features/",
+      "dependsOn": [
+        "dd.feature-list"
+      ],
+      "mode": "perFeature"
+    }
+  ]
+}

package/scaffold/.ai-spector/.docflow/config/dag.srs.json

@@ -0,0 +1,87 @@
+{
+  "version": 1,
+  "root": "docs/srs",
+  "nodes": [
+    {
+      "id": "srs.introduction",
+      "template": "srs/1-introduction.md",
+      "output": "1-introduction.md",
+      "dependsOn": []
+    },
+    {
+      "id": "srs.overall-description",
+      "template": "srs/2-overall-description.md",
+      "output": "2-overall-description.md",
+      "dependsOn": []
+    },
+    {
+      "id": "srs.use-cases",
+      "template": "srs/3-use-cases.md",
+      "output": "3-use-cases.md",
+      "dependsOn": [
+        "srs.introduction",
+        "srs.overall-description"
+      ]
+    },
+    {
+      "id": "srs.features-list",
+      "template": "srs/4-system-features-list-template.md",
+      "output": "4-system-features.md",
+      "dependsOn": [
+        "srs.use-cases"
+      ]
+    },
+    {
+      "id": "srs.feature-details",
+      "template": "srs/4-system-feature-detail-template.md",
+      "output": "features/",
+      "dependsOn": [
+        "srs.features-list"
+      ],
+      "mode": "perFeature"
+    },
+    {
+      "id": "srs.data-requirements",
+      "template": "srs/5-data-requirements.md",
+      "output": "5-data-requirements.md",
+      "dependsOn": [
+        "srs.feature-details"
+      ]
+    },
+    {
+      "id": "srs.external-interfaces",
+      "template": "srs/6-external-interfaces.md",
+      "output": "6-external-interfaces.md",
+      "dependsOn": [
+        "srs.feature-details"
+      ]
+    },
+    {
+      "id": "srs.quality-attributes",
+      "template": "srs/7-quality-attributes.md",
+      "output": "7-quality-attributes.md",
+      "dependsOn": [
+        "srs.data-requirements",
+        "srs.external-interfaces"
+      ]
+    },
+    {
+      "id": "srs.internationalization",
+      "template": "srs/8-internationalization.md",
+      "output": "8-internationalization.md",
+      "dependsOn": [
+        "srs.data-requirements",
+        "srs.external-interfaces"
+      ]
+    },
+    {
+      "id": "srs.other-requirements",
+      "template": "srs/9-other-requirements.md",
+      "output": "9-other-requirements.md",
+      "dependsOn": [
+        "srs.data-requirements",
+        "srs.external-interfaces"
+      ]
+    }
+  ]
+}

package/scaffold/.ai-spector/.docflow/config/data-source.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "defaultRoot": "docs/data-source",
+  "description": "Primary input materials for /analyze, /generate-srs, and /generate-basic-design (specs, notes, exports, diagrams, legacy docs)."
+}

package/scaffold/.ai-spector/.docflow/config/index.docs.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "outputs": {
+    "srs": ".ai-spector/index/srs.md",
+    "basicDesign": ".ai-spector/index/basic-design.md"
+  },
+  "sources": {
+    "srs": {
+      "root": "docs/srs",
+      "dag": ".ai-spector/.docflow/config/dag.srs.json",
+      "glob": "**/*.md"
+    },
+    "basicDesign": {
+      "root": "docs/basic-design",
+      "glob": "**/*.md"
+    }
+  },
+  "entryFormat": {
+    "heading": "## File: {basename}",
+    "fields": ["location", "metadata", "summary"]
+  }
+}

package/scaffold/.ai-spector/.docflow/config/workflow.dependencies.json

@@ -0,0 +1,271 @@
+{
+  "version": 1,
+  "indexes": {
+    "srs": ".ai-spector/index/srs.md",
+    "basicDesign": ".ai-spector/index/basic-design.md"
+  },
+  "indexPlaceholderMarkers": ["not yet run", "No entries yet"],
+  "messageFormat": {
+    "title": "Cannot run {command}",
+    "sections": ["missing", "doFirst", "optionalNext", "why"]
+  },
+  "steps": {
+    "analyze": {
+      "command": "/analyze",
+      "requires": [],
+      "checks": [
+        {
+          "id": "data-source-dir",
+          "type": "pathExists",
+          "path": "docs/data-source",
+          "fail": "Directory docs/data-source/ does not exist."
+        },
+        {
+          "id": "data-source-inputs",
+          "type": "hasFiles",
+          "path": "docs/data-source",
+          "glob": "**/*",
+          "min": 1,
+          "ignore": ["README.md", ".gitkeep"],
+          "fail": "No input files in docs/data-source/ (only README or empty folder)."
+        }
+      ],
+      "onSuccess": {
+        "optionalNext": ["/validate-graph", "/generate-srs"]
+      }
+    },
+    "validate-graph": {
+      "command": "/validate-graph",
+      "requires": ["analyze"],
+      "checks": [
+        {
+          "id": "graph-file",
+          "type": "pathExists",
+          "path": ".ai-spector/graph/traceability.graph.json",
+          "fail": "Missing traceability graph — run ai-spector analyze first."
+        }
+      ],
+      "onSuccess": {
+        "optionalNext": ["/generate-srs"]
+      }
+    },
+    "generate-srs": {
+      "command": "/generate-srs",
+      "requires": ["analyze"],
+      "checks": [
+        {
+          "id": "analysis-last-run",
+          "type": "stateNotNull",
+          "field": "analysis.lastRunAt",
+          "fail": "Analysis has never completed (analysis.lastRunAt is null)."
+        },
+        {
+          "id": "graph-file",
+          "type": "pathExists",
+          "path": ".ai-spector/graph/traceability.graph.json",
+          "fail": "Missing traceability graph — run ai-spector analyze and /analyze."
+        },
+        {
+          "id": "graph-merged",
+          "type": "stateNotNull",
+          "field": "analysis.graphMergedAt",
+          "fail": "Knowledge not merged into graph — run /analyze and commit domain nodes to traceability.graph.json."
+        },
+        {
+          "id": "knowledge-file",
+          "type": "pathExists",
+          "path": ".ai-spector/.docflow/analysis/knowledge.json",
+          "fail": "Missing knowledge.json — run /analyze first."
+        }
+      ],
+      "usesGraph": true,
+      "onBlock": {
+        "doFirst": [
+          "Add or update files in docs/data-source/",
+          "Run ai-spector analyze",
+          "Run /analyze (merge into graph)",
+          "Run /validate-graph"
+        ]
+      },
+      "onSuccess": {
+        "optionalNext": ["/index-docs srs", "/generate-basic-design"],
+        "why": "Use graph_neighbors for downstream generate; index is optional fallback."
+      }
+    },
+    "index-docs-srs": {
+      "command": "/index-docs srs",
+      "requires": [],
+      "checks": [
+        {
+          "id": "srs-any-files",
+          "type": "hasFiles",
+          "path": "docs/srs",
+          "glob": "**/*.md",
+          "min": 0,
+          "warnIfBelow": 1,
+          "warn": "No SRS files under docs/srs/ yet — index will be empty."
+        }
+      ],
+      "onWarn": {
+        "doFirst": ["/generate-srs"],
+        "why": "Indexing is allowed but summaries need generated SRS files."
+      }
+    },
+    "generate-basic-design": {
+      "command": "/generate-basic-design",
+      "requires": ["analyze", "generate-srs-minimum"],
+      "checks": [
+        {
+          "id": "analysis-last-run",
+          "type": "stateNotNull",
+          "field": "analysis.lastRunAt",
+          "fail": "Analysis has never completed."
+        },
+        {
+          "id": "knowledge-populated",
+          "type": "jsonAnyNonEmpty",
+          "path": ".ai-spector/.docflow/analysis/knowledge.json",
+          "keys": ["actors", "useCases", "features", "functionalRequirements"],
+          "fail": "knowledge.json is empty or missing — run /analyze first."
+        },
+        {
+          "id": "srs-minimum",
+          "type": "allPathsExist",
+          "paths": [
+            "docs/srs/1-introduction.md",
+            "docs/srs/4-system-features.md"
+          ],
+          "fail": "Minimum SRS outputs missing (need introduction and system features list)."
+        },
+        {
+          "id": "srs-index-file",
+          "type": "pathExists",
+          "path": ".ai-spector/index/srs.md",
+          "fail": "SRS index missing at .ai-spector/index/srs.md — run /index-docs srs first."
+        },
+        {
+          "id": "srs-index-populated",
+          "type": "indexPopulated",
+          "path": ".ai-spector/index/srs.md",
+          "fail": "SRS index is empty or placeholder — run /index-docs srs after SRS files exist."
+        }
+      ],
+      "usesGraph": true,
+      "usesIndex": [".ai-spector/index/srs.md"],
+      "onBlock": {
+        "doFirst": [
+          "Run /validate-graph",
+          "Run /generate-srs until minimum SRS exists",
+          "Use graph_neighbors from target feature ids"
+        ],
+        "optionalNext": ["/index-docs basic-design"]
+      },
+      "onSuccess": {
+        "requiredNext": ["/index-docs basic-design"],
+        "why": "Refresh .ai-spector/index/basic-design.md before /generate-detail-design."
+      }
+    },
+    "index-docs-basic-design": {
+      "command": "/index-docs basic-design",
+      "requires": [],
+      "checks": [
+        {
+          "id": "basic-design-any-files",
+          "type": "hasFiles",
+          "path": "docs/basic-design",
+          "glob": "**/*.md",
+          "min": 0,
+          "warnIfBelow": 1,
+          "warn": "No basic design files under docs/basic-design/ yet."
+        }
+      ],
+      "onWarn": {
+        "doFirst": ["/generate-basic-design"],
+        "why": "Indexing is allowed but summaries need generated basic design files."
+      }
+    },
+    "generate-detail-design": {
+      "command": "/generate-detail-design",
+      "requires": ["analyze", "generate-srs-minimum"],
+      "checks": [
+        {
+          "id": "analysis-last-run",
+          "type": "stateNotNull",
+          "field": "analysis.lastRunAt",
+          "fail": "Analysis has never completed."
+        },
+        {
+          "id": "knowledge-populated",
+          "type": "jsonAnyNonEmpty",
+          "path": ".ai-spector/.docflow/analysis/knowledge.json",
+          "keys": ["features", "functionalRequirements"],
+          "fail": "knowledge.json lacks feature/requirement data — run /analyze first."
+        },
+        {
+          "id": "srs-minimum",
+          "type": "allPathsExist",
+          "paths": [
+            "docs/srs/1-introduction.md",
+            "docs/srs/4-system-features.md"
+          ],
+          "fail": "Required SRS files missing for detail design."
+        },
+        {
+          "id": "srs-index-populated",
+          "type": "indexPopulated",
+          "path": ".ai-spector/index/srs.md",
+          "fail": "SRS index not built — run /index-docs srs before detail design."
+        },
+        {
+          "id": "basic-design-index-when-outputs-exist",
+          "type": "indexPopulatedIfSourceHasFiles",
+          "indexPath": ".ai-spector/index/basic-design.md",
+          "sourcePath": "docs/basic-design",
+          "sourceGlob": "**/*.md",
+          "fail": "Basic design outputs exist but .ai-spector/index/basic-design.md is missing or placeholder — run /index-docs basic-design."
+        }
+      ],
+      "usesGraph": true,
+      "usesIndex": [
+        ".ai-spector/index/srs.md",
+        ".ai-spector/index/basic-design.md"
+      ],
+      "onBlock": {
+        "doFirst": [
+          "Run /validate-graph",
+          "Run /generate-srs",
+          "graph_neighbors from feature seeds",
+          "Run /generate-basic-design if needed"
+        ],
+        "optionalNext": []
+      }
+    },
+    "index-docs": {
+      "command": "/index-docs",
+      "requires": [],
+      "checks": [],
+      "onWarn": {
+        "note": "Runs even when outputs are empty; warns per collection when no files found."
+      }
+    }
+  },
+  "pipeline": [
+    "analyze",
+    "generate-srs",
+    "index-docs-srs",
+    "generate-basic-design",
+    "index-docs-basic-design",
+    "generate-detail-design"
+  ],
+  "graphUsage": {
+    "rule": "Before opening docs under docs/srs/ or docs/basic-design/, run graph_neighbors from the task seed id and load only projectionPaths and referenced sources from the result. See .cursor/commands/_graph.md.",
+    "validateBeforeGenerate": "/validate-graph",
+    "afterEdit": "/graph-impact",
+    "reconcileProjections": "/sync-graph"
+  },
+  "indexUsage": {
+    "rule": "Fallback only when graph domain nodes are missing or graph_neighbors returns an empty subgraph. Otherwise prefer graphUsage.rule.",
+    "afterGenerateSrs": "/index-docs srs",
+    "afterGenerateBasicDesign": "/index-docs basic-design"
+  }
+}

package/scaffold/.ai-spector/.docflow/extract/patch.example.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "nodes": [
+    { "id": "UC-01", "type": "useCase", "title": "Place order", "priority": "High" },
+    { "id": "F-01", "type": "feature", "title": "Checkout" }
+  ],
+  "edges": [
+    {
+      "type": "listedIn",
+      "from": "UC-01",
+      "to": "sec.srs.3-use-cases.l3.3.32-list-use-case"
+    },
+    {
+      "type": "listedIn",
+      "from": "F-01",
+      "to": "sec.srs.4-system-features.l3.3.42-list-of-system-features"
+    },
+    { "type": "satisfies", "from": "F-01", "to": "UC-01" }
+  ]
+}

package/scaffold/.ai-spector/.docflow/state.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "initializedAt": null,
+  "analysis": {
+    "lastRunAt": null,
+    "graphPreparedAt": null
+  },
+  "index": {
+    "lastRunAt": null
+  }
+}

package/scaffold/.ai-spector/docflow.config.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "paths": {
+    "graph": ".ai-spector/graph/traceability.graph.json",
+    "registry": ".ai-spector/registry/section-registry.json"
+  }
+}

package/scaffold/.ai-spector/index/README.md

@@ -0,0 +1,18 @@
+# Document indexes
+
+Generated by `/index-docs` into this folder only. Do not edit by hand — re-run after SRS or basic design changes.
+
+| File | Source root | Required before |
+|------|-------------|-----------------|
+| `srs.md` | `docs/srs/` | `/generate-basic-design`, `/generate-detail-design` |
+| `basic-design.md` | `docs/basic-design/` | `/generate-detail-design` (when basic design outputs exist) |
+
+## How downstream commands use indexes
+
+1. Read the index file(s) here first.
+2. Choose relevant entries by `summary` and `metadata` (topics, `dependsOn`, `relatedSrs`).
+3. Open only the `location` paths listed — not the whole `docs/srs/` or `docs/basic-design/` tree.
+
+Placeholder text (`not yet run`, `No entries yet`) means `/index-docs` must be run before generation commands will proceed.
+
+Input materials live in `docs/data-source/` (not indexed here).