ai-spector 0.1.1

package/README.md

@@ -0,0 +1,169 @@
+# Spec Writer
+
+Spec Writer is an npm-installable bootstrapper for incremental documentation workflows in Cursor.
+
+1. Analyze project sources with Graphify MCP.
+2. Generate SRS documents in dependency order.
+3. Generate detail design documents in dependency order.
+
+It is designed for part-by-part generation with parallel subagents and merge/review loops.
+
+## What You Get
+
+After `init`, your project has:
+
+- Cursor commands: `/analyze`, `/generate-srs`, `/generate-detail-design`
+- Workflow skill + configs + state files
+- SRS/detail design templates
+- Output folders for generated docs
+- Graphify-backed knowledge loop for incremental generation
+
+## Quick Start
+
+```bash
+# in your target project
+npx ai-spector init
+```
+
+Then in Cursor chat:
+
+1. `/analyze` (or `/analyze src docs`)
+2. `/generate-srs`
+3. `/generate-detail-design`
+
+## Init Command
+
+```bash
+ai-spector init [--force] [--no-graphify] [--skip-index] [--yes]
+```
+
+Options:
+
+- `--force`: overwrite existing installed assets.
+- `--no-graphify`: skip Graphify bootstrap.
+- `--skip-index`: do not run initial Graphify index.
+- `--yes`: non-interactive mode.
+
+## Command Guide
+
+### `/analyze [paths...]`
+
+- No args: analyze current workspace folder.
+- With args: analyze only provided files/folders.
+- Produces:
+  - `docs/.docflow/analysis/knowledge.json`
+  - `docs/.docflow/analysis/gaps.json`
+  - `docs/.docflow/analysis/scope.json`
+
+Examples:
+
+```text
+/analyze
+/analyze src
+/analyze src services docs/requirements
+```
+
+### `/generate-srs [file]`
+
+- No file: generate all pending SRS nodes by DAG wave.
+- With file: generate/repair one target file.
+- Uses existing outputs + completeness checks before writing.
+
+Examples:
+
+```text
+/generate-srs
+/generate-srs 3-use-cases.md
+```
+
+### `/generate-detail-design [file]`
+
+- No file: generate all pending detail design nodes by DAG wave.
+- With file: generate/repair one target file.
+- Uses SRS outputs + Graphify context.
+
+Examples:
+
+```text
+/generate-detail-design
+/generate-detail-design feature-list.md
+```
+
+## Continue From Existing Files (Default Behavior)
+
+Generation commands always scan existing outputs first and classify files as:
+
+- `good`
+- `missing_content`
+- `missing_file`
+
+Default behavior:
+
+- keep `good` files unchanged
+- patch `missing_content`
+- create `missing_file`
+
+After each generated or patched file, content is synced back to Graphify so later files can use updated context.
+
+## Dependency Waves
+
+SRS and detail design are generated in dependency order. Independent nodes in the same wave can run in parallel, then main agent merges/reviews before moving to the next wave.
+
+## Publish to npm
+
+From this package repo:
+
+```bash
+npm login
+npm whoami
+chmod +x bin/spec-writer.js
+npm pack --dry-run
+npm publish --access public
+```
+
+For next releases:
+
+```bash
+npm version patch
+npm publish
+```
+
+## Installed Project Structure
+
+```text
+.cursor/
+  commands/
+    analyze.md
+    generate-srs.md
+    generate-detail-design.md
+  skills/
+    spec-writer/
+      SKILL.md
+
+docs/
+  _templates/
+    srs/
+    detail_design/
+    basic_design/
+  .docflow/
+    graph/
+      graphify-index/
+    analysis/
+      knowledge.json
+      gaps.json
+      scope.json
+    partials/
+      srs/
+      detail-design/
+    logs/
+    config/
+      dag.srs.json
+      dag.detail-design.json
+      analyze.graphify.json
+      completeness-rules.srs.json
+      completeness-rules.detail-design.json
+    state.json
+  output/
+    srs/
+    detail-design/
+```

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>
+

package/_templates/basic_design/detail-api-template.md

@@ -0,0 +1,278 @@
+# API Detail: <Project Name>
+
+> This document specifies detailed request/response schemas, path/query parameters, and error handling for each API endpoint. For the endpoint list and overview, see the API List document.
+
+**Source Requirements:** SRS Section 4 (System Features), Section 6.2 (Software Interfaces)
+
+---
+
+## 1. Detailed Endpoint Specifications
+
+### 1.1 `POST /resource`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `createResource`
+
+**Source Requirement:** SRS Section <X.X> - <Feature Name>
+
+**Authentication:** Required
+
+**Request:**
+
+**Headers:**
+```
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Body Schema:**
+```json
+{
+  "field1": "<type>",
+  "field2": "<type>",
+  "field3": "<type>"
+}
+```
+
+**Field Descriptions:**
+
+| Field | Type | Required | Validation | Description |
+|-------|------|----------|------------|-------------|
+| `field1` | `<type>` | Yes | <Validation rules> | <Description> |
+| `field2` | `<type>` | No | <Validation rules> | <Description> |
+
+**Example Request:**
+```json
+{
+  "field1": "value1",
+  "field2": "value2"
+}
+```
+
+**Responses:**
+
+**201 Created:**
+```json
+{
+  "id": 123,
+  "status": "success",
+  "message": "<Message>"
+}
+```
+
+**400 Bad Request:**
+```json
+{
+  "error": "validation_error",
+  "message": "<Error message>",
+  "details": [
+    {
+      "field": "field1",
+      "message": "<Field-specific error>"
+    }
+  ]
+}
+```
+
+**401 Unauthorized:**
+```json
+{
+  "error": "unauthorized",
+  "message": "Authentication required"
+}
+```
+
+**500 Internal Server Error:**
+```json
+{
+  "error": "internal_error",
+  "message": "<Error message>"
+}
+```
+
+---
+
+### 1.2 `GET /resource/{id}`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `getResource`
+
+**Source Requirement:** SRS Section <X.X>
+
+**Authentication:** Required
+
+**Path Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | integer | Yes | Resource identifier |
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `include` | string | No | Related resources to include |
+| `fields` | string | No | Fields to return |
+
+**Responses:**
+
+**200 OK:**
+```json
+{
+  "id": 123,
+  "field1": "value1",
+  "field2": "value2",
+  "created_at": "2025-01-01T00:00:00Z"
+}
+```
+
+**404 Not Found:**
+```json
+{
+  "error": "not_found",
+  "message": "Resource not found"
+}
+```
+
+---
+
+### 1.3 `PUT /resource/{id}`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `updateResource`
+
+**Authentication:** Required
+
+**Path Parameters:**
+- `id`: Resource identifier
+
+**Request Body:**
+> Similar structure to POST
+
+**Responses:**
+> Similar structure to GET/POST
+
+---
+
+### 1.4 `DELETE /resource/{id}`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `deleteResource`
+
+**Authentication:** Required
+
+**Path Parameters:**
+- `id`: Resource identifier
+
+**Responses:**
+
+**204 No Content:**
+> Success response with no body
+
+**404 Not Found:**
+> Error response
+
+---
+
+## 2. Data Models
+
+### 2.1 Resource Model
+
+**Description:** <Description of the data model>
+
+**Schema:**
+```json
+{
+  "id": "integer",
+  "field1": "string",
+  "field2": "integer",
+  "created_at": "datetime",
+  "updated_at": "datetime"
+}
+```
+
+**Field Details:**
+
+| Field | Type | Description | Constraints |
+|-------|------|-------------|-------------|
+| `id` | integer | Unique identifier | Auto-generated |
+| `field1` | string | <Description> | Max 255 chars |
+| `field2` | integer | <Description> | Min 0, Max 100 |
+
+---
+
+## 3. Error Handling
+
+**Standard Error Response Format:**
+```json
+{
+  "error": "<error_code>",
+  "message": "<Human-readable message>",
+  "details": {
+    "<additional_info>": "<value>"
+  }
+}
+```
+
+**Error Codes:**
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `validation_error` | 400 | Request validation failed |
+| `unauthorized` | 401 | Authentication required |
+| `forbidden` | 403 | Insufficient permissions |
+| `not_found` | 404 | Resource not found |
+| `conflict` | 409 | Resource conflict |
+| `internal_error` | 500 | Server error |
+
+---
+
+## 4. Rate Limiting
+
+**Limits:**
+- <Limit description>
+
+**Headers:**
+```
+X-RateLimit-Limit: <number>
+X-RateLimit-Remaining: <number>
+X-RateLimit-Reset: <timestamp>
+```
+
+**Response when limit exceeded:**
+```json
+{
+  "error": "rate_limit_exceeded",
+  "message": "Too many requests",
+  "retry_after": 60
+}
+```
+
+---
+
+## 5. Webhooks (if applicable)
+
+**Events:**
+- `<event_name>`: <Description>
+
+**Payload Format:**
+```json
+{
+  "event": "<event_name>",
+  "timestamp": "<ISO 8601>",
+  "data": {
+    "<resource_data>": "..."
+  }
+}
+```
+
+---
+
+## 6. Future Enhancements
+
+- <Enhancement 1>
+- <Enhancement 2>