From 0768d96c6a563dc3564c3eb0c62669edc2f57187 Mon Sep 17 00:00:00 2001 From: Corvid Agent <95454608+corvid-agent@users.noreply.github.com> Date: Thu, 19 Mar 2026 06:37:30 -0700 Subject: [PATCH 1/3] docs: feature specsync generate as the headline for v1.2.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The generate command and AI agent workflow were buried in a bullet list. Now they have a dedicated README section with usage examples, custom template docs, and a full generate→fill→validate→fix→enforce workflow. CHANGELOG updated to reflect the actual feature additions. Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 8 ++++ README.md | 44 ++++++++++++++++---- docs/ai-agents.md | 102 +++++++++++++++++++++++++++++++++++----------- 3 files changed, 123 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e148b4f..b6aaa5ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [1.2.0] - 2026-03-19 +### Added + +- **Spec generation documentation** — `specsync generate` now has a dedicated README section and expanded AI agents guide covering the full LLM workflow: generate → fill → validate → fix → enforce. +- Custom template documentation (`specs/_template.spec.md`) explaining how teams control generated spec structure. +- JSON output shape reference for `check` and `coverage` commands. +- Integration patterns table (pre-commit hooks, PR bots, CI coverage gates). + ### Changed - Rewrote README for density — every line carries new information, no filler. +- Elevated "For AI Agents" from a bullet list to a full "Spec Generation" section with usage examples and workflow guidance. - Streamlined docs site pages to complement rather than duplicate the README. - Updated CHANGELOG with previously missing 1.1.1 and 1.1.2 entries. diff --git a/README.md b/README.md index 8061e09a..ec6c11d1 100644 --- a/README.md +++ b/README.md @@ -330,15 +330,45 @@ Create `specsync.json` in your project root (or run `specsync init`): --- -## For AI Agents +## Spec Generation -- **`--json`** outputs structured results, no color codes to strip -- **Exit code 1** = needs fixing; **0** = all clear -- **`specsync generate`** bootstraps specs for existing codebases -- **Spec files are plain markdown** — any LLM can read and write them -- **Public API tables** use backtick-quoted names, unambiguous to parse +`specsync generate` scans your source directories, finds modules without spec files, and scaffolds `*.spec.md` files for each one — frontmatter populated, source files listed, all required sections stubbed. -### JSON shapes +```bash +specsync generate # Scaffold specs for all unspecced modules +specsync coverage # See what's still missing +``` + +### How it works + +1. Runs coverage analysis to find modules with no corresponding spec +2. For each unspecced module, discovers all source files (excluding tests) +3. Generates a spec using your custom template (`specs/_template.spec.md`) or the built-in default +4. Writes `specs//.spec.md` with `module`, `files`, `version: 1`, `status: draft` pre-filled + +### Custom templates + +Drop a `_template.spec.md` in your specs directory. The generator replaces `module`, `version`, `status`, `files`, and the `# Title` heading — everything else stays as-is. Use this to enforce your team's spec structure. + +### Designed for AI agents + +The generate command is the entry point for LLM-powered spec workflows. A coding agent can: + +```bash +specsync generate # scaffold specs for new modules +# LLM fills in Purpose, Public API, Invariants... # agent writes the content +specsync check --json # validate, get structured feedback +# LLM fixes errors from JSON output # iterate until clean +specsync check --strict --require-coverage 100 # enforce full coverage in CI +``` + +Every output format is designed for machine consumption: +- **`--json`** on any command → structured JSON, no ANSI codes +- **Exit code 0/1** → pass/fail, no parsing needed +- **Spec files are plain markdown** → any LLM can read and write them +- **Public API tables** use backtick-quoted names → unambiguous to extract + +### JSON output shapes ```json // specsync check --json diff --git a/docs/ai-agents.md b/docs/ai-agents.md index bf3b425d..752f789b 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -7,7 +7,7 @@ nav_order: 6 # For AI Agents {: .no_toc } -SpecSync is built to work well with LLM-powered coding tools. +SpecSync is built for LLM-powered coding tools — structured output, machine-readable specs, and automated scaffolding. {: .fs-6 .fw-300 }
@@ -19,30 +19,79 @@ SpecSync is built to work well with LLM-powered coding tools. --- -## Why It Works +## Generate Specs Automatically -- Specs are plain markdown — any LLM can read and write them -- `--json` outputs structured data, no terminal color codes -- Exit code 1 = needs fixing, 0 = all clear -- `specsync generate` bootstraps specs for existing codebases -- Public API tables use backtick-quoted names, unambiguous to parse +`specsync generate` is the starting point for AI-driven spec workflows. It finds every module without a spec file and scaffolds one — frontmatter populated, source files listed, required sections stubbed with TODOs. +```bash +specsync generate +# ✓ Generated specs/auth/auth.spec.md (3 files) +# ✓ Generated specs/payments/payments.spec.md (2 files) +``` + +### What gets generated + +For each unspecced module, you get a ready-to-fill spec: + +```yaml --- +module: auth +version: 1 +status: draft +files: + - src/auth/service.ts + - src/auth/middleware.ts +db_tables: [] +depends_on: [] +--- +``` -## Workflow +Plus all required sections (Purpose, Public API, Invariants, Behavioral Examples, Error Cases, Dependencies, Change Log) with TODO placeholders. + +### Custom templates + +Place `_template.spec.md` in your specs directory to control the generated structure. The generator replaces `module`, `version`, `status`, `files`, and the `# Title` heading — your template controls everything else. + +--- + +## End-to-End AI Workflow ```bash -specsync check --json # 1. assess current state -# fix errors in specs or source # 2. resolve issues -specsync generate # 3. scaffold missing specs -specsync check --strict --require-coverage 100 # 4. verify +# 1. Bootstrap: scaffold specs for all unspecced modules +specsync generate + +# 2. Fill: LLM reads source code, fills in each spec's content +# (Purpose, Public API tables, Invariants, etc.) + +# 3. Validate: check specs against code, get structured errors +specsync check --json + +# 4. Fix: LLM reads JSON errors, corrects specs or flags code issues + +# 5. Enforce: CI gate with full coverage +specsync check --strict --require-coverage 100 ``` +Each step produces machine-readable output. No human in the loop required (though humans can review at any step). + +--- + +## Why SpecSync Works for LLMs + +| Feature | Why it matters | +|---------|---------------| +| Plain markdown specs | Any LLM can read and write them — no custom format to learn | +| `--json` flag on every command | Structured output, no ANSI codes to strip | +| Exit code 0/1 | Pass/fail without parsing | +| Backtick-quoted names in API tables | Unambiguous extraction — first backtick-quoted string per row | +| `specsync generate` | Bootstrap from zero — LLM fills in content, not boilerplate | +| Deterministic validation | Same input → same output, no flaky checks | + --- -## JSON Shapes +## JSON Output Shapes -### Check +### `specsync check --json` ```json { @@ -53,11 +102,11 @@ specsync check --strict --require-coverage 100 # 4. verify } ``` -- **Errors**: spec references something that doesn't exist in code — must fix +- **Errors**: spec references something missing from code — must fix - **Warnings**: code exports something the spec doesn't mention — informational - **`--strict`**: promotes warnings to errors -### Coverage +### `specsync coverage --json` ```json { @@ -68,14 +117,16 @@ specsync check --strict --require-coverage 100 # 4. verify } ``` +Use `modules` with `has_spec: false` to identify what `generate` would scaffold. + --- ## Writing Specs Programmatically 1. Frontmatter requires `module`, `version`, `status`, `files` -2. Status: `draft`, `review`, `stable`, `deprecated` -3. Files: non-empty list, paths relative to project root -4. Public API tables: backtick-quoted names in first column +2. Status values: `draft`, `review`, `stable`, `deprecated` +3. `files` must be non-empty, paths relative to project root +4. Public API tables: first backtick-quoted string per row is the export name 5. Default required sections: Purpose, Public API, Invariants, Behavioral Examples, Error Cases, Dependencies, Change Log ### Minimal valid spec @@ -121,9 +172,12 @@ None --- -## Integration Ideas +## Integration Patterns -- **Pre-commit hook**: `specsync check --strict` -- **PR review bot**: parse `specsync check --json` output, post as PR comment -- **Spec generation**: run `specsync generate` after adding modules -- **AI code review**: feed JSON output to an LLM for spec update suggestions +| Pattern | Command | How | +|---------|---------|-----| +| **Pre-commit hook** | `specsync check --strict` | Block commits with spec errors | +| **PR review bot** | `specsync check --json` | Parse output, post as PR comment | +| **Bootstrap coverage** | `specsync generate` | Scaffold after adding new modules | +| **AI code review** | `specsync check --json` | Feed errors to LLM for spec updates | +| **Coverage gate** | `specsync check --strict --require-coverage 100` | CI enforces full coverage | From 1babff6cedf24916da20c8cd3d522ac9a6a1dc74 Mon Sep 17 00:00:00 2001 From: Corvid Agent <95454608+corvid-agent@users.noreply.github.com> Date: Thu, 19 Mar 2026 06:52:54 -0700 Subject: [PATCH 2/3] docs: document --ai flag, aiCommand/aiTimeout config, and LOC coverage from PR #19 Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 10 +++---- README.md | 47 +++++++++++++++++++---------- docs/ai-agents.md | 75 +++++++++++++++++++++++++++-------------------- 3 files changed, 80 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6aaa5ec..3ffb5663 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,15 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **Spec generation documentation** — `specsync generate` now has a dedicated README section and expanded AI agents guide covering the full LLM workflow: generate → fill → validate → fix → enforce. -- Custom template documentation (`specs/_template.spec.md`) explaining how teams control generated spec structure. -- JSON output shape reference for `check` and `coverage` commands. -- Integration patterns table (pre-commit hooks, PR bots, CI coverage gates). +- **`specsync generate --ai`** — AI-powered spec generation. Reads source code, sends it to an LLM, and generates specs with real content (Purpose, Public API tables, Invariants, Error Cases) instead of template stubs. Configurable via `aiCommand` and `aiTimeout` in `specsync.json`, or `SPECSYNC_AI_COMMAND` env var. Defaults to Claude CLI, works with any LLM that reads stdin and writes stdout. +- **LOC coverage tracking** — `specsync coverage` now reports lines-of-code coverage alongside file coverage. JSON output includes `loc_coverage`, `loc_covered`, `loc_total`, and `uncovered_files` with per-file LOC counts sorted by size. +- **Flat file module detection** — `generate` and `coverage` now detect single-file modules (e.g., `src/config.rs`) in addition to subdirectory-based modules. +- `aiCommand` and `aiTimeout` config options in `specsync.json`. ### Changed - Rewrote README for density — every line carries new information, no filler. -- Elevated "For AI Agents" from a bullet list to a full "Spec Generation" section with usage examples and workflow guidance. +- Documented `generate --ai` workflow, AI command configuration, and LOC coverage in README and docs site. - Streamlined docs site pages to complement rather than duplicate the README. - Updated CHANGELOG with previously missing 1.1.1 and 1.1.2 entries. diff --git a/README.md b/README.md index ec6c11d1..0537048c 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,7 @@ specsync init # Create specsync.json config specsync check # Validate specs against code specsync coverage # Show file/module coverage specsync generate # Scaffold specs for unspecced modules +specsync generate --ai # AI-powered specs (reads code, writes content) specsync watch # Re-validate on every file change ``` @@ -246,7 +247,7 @@ specsync [command] [flags] |---------|-------------| | `check` | Validate all specs against source code **(default)** | | `coverage` | File and module coverage report | -| `generate` | Scaffold specs for modules missing one | +| `generate` | Scaffold specs for modules missing one (`--ai` for AI-powered content) | | `init` | Create default `specsync.json` | | `watch` | Live validation on file changes (500ms debounce) | @@ -313,7 +314,9 @@ Create `specsync.json` in your project root (or run `specsync init`): "requiredSections": ["Purpose", "Public API", "Invariants", "Behavioral Examples", "Error Cases", "Dependencies", "Change Log"], "excludeDirs": ["__tests__"], "excludePatterns": ["**/__tests__/**", "**/*.test.ts", "**/*.spec.ts"], - "sourceExtensions": [] + "sourceExtensions": [], + "aiCommand": "claude -p --output-format text", + "aiTimeout": 120 } ``` @@ -327,36 +330,49 @@ Create `specsync.json` in your project root (or run `specsync init`): | `excludeDirs` | `string[]` | `["__tests__"]` | Directories excluded from coverage | | `excludePatterns` | `string[]` | Common test globs | File patterns excluded from coverage | | `sourceExtensions` | `string[]` | All supported | Restrict to specific extensions (e.g., `["ts", "rs"]`) | +| `aiCommand` | `string?` | `claude -p ...` | Command for `generate --ai` (reads stdin prompt, writes stdout markdown) | +| `aiTimeout` | `number?` | `120` | Seconds before AI command times out per module | --- ## Spec Generation -`specsync generate` scans your source directories, finds modules without spec files, and scaffolds `*.spec.md` files for each one — frontmatter populated, source files listed, all required sections stubbed. +`specsync generate` scans your source directories, finds modules without spec files, and scaffolds `*.spec.md` files for each one. ```bash -specsync generate # Scaffold specs for all unspecced modules +specsync generate # Scaffold template specs for all unspecced modules +specsync generate --ai # Use AI to generate filled-in specs from source code specsync coverage # See what's still missing ``` -### How it works +### Template mode (default) -1. Runs coverage analysis to find modules with no corresponding spec -2. For each unspecced module, discovers all source files (excluding tests) -3. Generates a spec using your custom template (`specs/_template.spec.md`) or the built-in default -4. Writes `specs//.spec.md` with `module`, `files`, `version: 1`, `status: draft` pre-filled +Uses your custom template (`specs/_template.spec.md`) or the built-in default. Generates frontmatter + stubbed sections with TODOs. -### Custom templates +### AI mode (`--ai`) -Drop a `_template.spec.md` in your specs directory. The generator replaces `module`, `version`, `status`, `files`, and the `# Title` heading — everything else stays as-is. Use this to enforce your team's spec structure. +Reads your source code, sends it to an LLM, and generates specs with real content — Purpose, Public API tables, Invariants, Error Cases, all filled in from the code. No manual filling required. + +The AI command is resolved in order: +1. `"aiCommand"` in `specsync.json` +2. `SPECSYNC_AI_COMMAND` environment variable +3. `claude -p --output-format text` (default, requires [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)) + +Any command that reads a prompt from stdin and writes markdown to stdout works: + +```json +{ "aiCommand": "claude -p --output-format text" } +{ "aiCommand": "ollama run llama3" } +``` + +Set `"aiTimeout"` in `specsync.json` to control per-module timeout (default: 120 seconds). ### Designed for AI agents -The generate command is the entry point for LLM-powered spec workflows. A coding agent can: +The generate command is the entry point for LLM-powered spec workflows: ```bash -specsync generate # scaffold specs for new modules -# LLM fills in Purpose, Public API, Invariants... # agent writes the content +specsync generate --ai # AI writes specs from source code specsync check --json # validate, get structured feedback # LLM fixes errors from JSON output # iterate until clean specsync check --strict --require-coverage 100 # enforce full coverage in CI @@ -375,7 +391,7 @@ Every output format is designed for machine consumption: { "passed": false, "errors": ["..."], "warnings": ["..."], "specs_checked": 12 } // specsync coverage --json -{ "file_coverage": 85.33, "files_covered": 23, "files_total": 27, "modules": [{"name": "helpers", "has_spec": false}] } +{ "file_coverage": 85.33, "files_covered": 23, "files_total": 27, "loc_coverage": 79.12, "loc_covered": 4200, "loc_total": 5308, "modules": [...] } ``` --- @@ -385,6 +401,7 @@ Every output format is designed for machine consumption: ``` src/ ├── main.rs CLI entry + output formatting +├── ai.rs AI-powered spec generation (prompt builder + command runner) ├── types.rs Data types + config schema ├── config.rs specsync.json loading ├── parser.rs Frontmatter + spec body parsing diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 752f789b..a466d4c5 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -19,56 +19,62 @@ SpecSync is built for LLM-powered coding tools — structured output, machine-re --- -## Generate Specs Automatically +## AI-Powered Generation (`--ai`) -`specsync generate` is the starting point for AI-driven spec workflows. It finds every module without a spec file and scaffolds one — frontmatter populated, source files listed, required sections stubbed with TODOs. +`specsync generate --ai` reads your source code, sends it to an LLM, and generates specs with real content — not just templates with TODOs. Purpose, Public API tables, Invariants, Error Cases — all filled in from the code. ```bash -specsync generate +specsync generate --ai +# Generating specs/auth/auth.spec.md with AI... +# │ --- +# │ module: auth +# │ ... # ✓ Generated specs/auth/auth.spec.md (3 files) -# ✓ Generated specs/payments/payments.spec.md (2 files) ``` -### What gets generated +### Configuring the AI command -For each unspecced module, you get a ready-to-fill spec: +The AI command is resolved in order: +1. `"aiCommand"` in `specsync.json` +2. `SPECSYNC_AI_COMMAND` environment variable +3. `claude -p --output-format text` (default, requires Claude CLI) -```yaml ---- -module: auth -version: 1 -status: draft -files: - - src/auth/service.ts - - src/auth/middleware.ts -db_tables: [] -depends_on: [] ---- +Any command that reads a prompt from stdin and writes markdown to stdout works: + +```json +{ + "aiCommand": "claude -p --output-format text", + "aiTimeout": 300 +} ``` -Plus all required sections (Purpose, Public API, Invariants, Behavioral Examples, Error Cases, Dependencies, Change Log) with TODO placeholders. +```json +{ + "aiCommand": "ollama run llama3", + "aiTimeout": 60 +} +``` + +If AI generation fails for a module, it falls back to template generation automatically. -### Custom templates +### Template mode (no `--ai`) -Place `_template.spec.md` in your specs directory to control the generated structure. The generator replaces `module`, `version`, `status`, `files`, and the `# Title` heading — your template controls everything else. +Without `--ai`, `specsync generate` scaffolds template specs — frontmatter populated, required sections stubbed with TODOs. Place `_template.spec.md` in your specs directory to control the generated structure. --- -## End-to-End AI Workflow +## End-to-End Workflow ```bash -# 1. Bootstrap: scaffold specs for all unspecced modules -specsync generate - -# 2. Fill: LLM reads source code, fills in each spec's content -# (Purpose, Public API tables, Invariants, etc.) +# One command: AI reads code, writes specs +specsync generate --ai -# 3. Validate: check specs against code, get structured errors +# Validate the generated specs against code specsync check --json -# 4. Fix: LLM reads JSON errors, corrects specs or flags code issues +# LLM fixes errors from JSON output, iterates until clean -# 5. Enforce: CI gate with full coverage +# CI gate with full coverage specsync check --strict --require-coverage 100 ``` @@ -113,11 +119,15 @@ Each step produces machine-readable output. No human in the loop required (thoug "file_coverage": 85.33, "files_covered": 23, "files_total": 27, - "modules": [{ "name": "helpers", "has_spec": false }] + "loc_coverage": 79.12, + "loc_covered": 4200, + "loc_total": 5308, + "modules": [{ "name": "helpers", "has_spec": false }], + "uncovered_files": [{ "file": "src/helpers/utils.ts", "loc": 340 }] } ``` -Use `modules` with `has_spec: false` to identify what `generate` would scaffold. +Use `modules` with `has_spec: false` to identify what `generate` would scaffold. `uncovered_files` shows LOC per uncovered file, sorted by size — prioritize the largest gaps. --- @@ -178,6 +188,7 @@ None |---------|---------|-----| | **Pre-commit hook** | `specsync check --strict` | Block commits with spec errors | | **PR review bot** | `specsync check --json` | Parse output, post as PR comment | -| **Bootstrap coverage** | `specsync generate` | Scaffold after adding new modules | +| **Bootstrap coverage** | `specsync generate --ai` | AI writes specs from source code | +| **Template scaffold** | `specsync generate` | Scaffold templates after adding new modules | | **AI code review** | `specsync check --json` | Feed errors to LLM for spec updates | | **Coverage gate** | `specsync check --strict --require-coverage 100` | CI enforces full coverage | From 4e24cfbb8941a98a4922373edddbdce0aacc64fd Mon Sep 17 00:00:00 2001 From: Corvid Agent <95454608+corvid-agent@users.noreply.github.com> Date: Thu, 19 Mar 2026 07:58:56 -0700 Subject: [PATCH 3/3] docs: add --ai flag to all docs pages, switch to Rust-themed orange color scheme - Add --ai flag, aiCommand, aiTimeout to CLI reference, configuration, and index pages - Add ai.rs to architecture diagram - Add LOC coverage fields to coverage JSON examples - Replace blue accent with Rust-themed orange color scheme Co-Authored-By: Claude Opus 4.6 --- docs/_config.yml | 2 +- docs/_sass/color_schemes/rust.scss | 30 ++++++++++++++++++++++++++++++ docs/architecture.md | 1 + docs/cli.md | 12 ++++++++++-- docs/configuration.md | 6 +++++- docs/index.md | 1 + 6 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 docs/_sass/color_schemes/rust.scss diff --git a/docs/_config.yml b/docs/_config.yml index 4ae37c6e..6704c9ba 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,7 +5,7 @@ baseurl: "/spec-sync" remote_theme: just-the-docs/just-the-docs@v0.10.0 -color_scheme: dark +color_scheme: rust aux_links: "GitHub": diff --git a/docs/_sass/color_schemes/rust.scss b/docs/_sass/color_schemes/rust.scss new file mode 100644 index 00000000..1790ab0b --- /dev/null +++ b/docs/_sass/color_schemes/rust.scss @@ -0,0 +1,30 @@ +// Rust-themed dark color scheme for SpecSync docs +// Based on just-the-docs dark scheme with orange/rust accents + +$body-background-color: #1e1e1e; +$sidebar-color: #171717; +$body-text-color: #e0e0e0; +$body-heading-color: #f0f0f0; + +// Rust orange accent colors +$link-color: #e87d2f; +$btn-primary-color: #e87d2f; +$feedback-color: darken($link-color, 3%); + +// Code blocks +$code-background-color: #2a2a2a; +$code-linenumber-color: #6e7681; +$border-color: #3d3d3d; + +// Search +$search-background-color: #2a2a2a; +$search-result-preview-color: #b0b0b0; + +// Tables +$table-background-color: #252525; + +// Navigation +$nav-child-link-color: #c0c0c0; + +// Footer +$footer-background-color: #171717; diff --git a/docs/architecture.md b/docs/architecture.md index cf60becd..5f5557a4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -24,6 +24,7 @@ How SpecSync is built. Useful for contributors and anyone adding language suppor ``` src/ ├── main.rs CLI entry point (clap) + output formatting +├── ai.rs AI-powered spec generation (prompt builder + command runner) ├── types.rs Core data types + config schema ├── config.rs specsync.json loading ├── parser.rs Frontmatter + spec body parsing diff --git a/docs/cli.md b/docs/cli.md index a386b408..7e584ec8 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -58,9 +58,12 @@ specsync coverage --json Scaffold spec files for modules that don't have one. Uses `specs/_template.spec.md` if present. ```bash -specsync generate +specsync generate # template mode — stubs with TODOs +specsync generate --ai # AI mode — reads code, writes real content ``` +With `--ai`, source code is piped to an LLM which generates filled-in specs (Purpose, Public API tables, Invariants, etc.). The AI command is resolved from: `aiCommand` in config → `SPECSYNC_AI_COMMAND` env var → `claude -p --output-format text`. See [Configuration](configuration) for `aiCommand` and `aiTimeout`. + ### `init` Create a default `specsync.json` in the current directory. @@ -86,6 +89,7 @@ specsync watch | `--strict` | Warnings become errors. Recommended for CI. | | `--require-coverage N` | Fail if file coverage < N%. | | `--root ` | Project root directory (default: cwd). | +| `--ai` | Use AI to generate filled-in specs instead of templates (with `generate`). | | `--json` | Structured JSON output, no color codes. | --- @@ -119,6 +123,10 @@ specsync watch "file_coverage": 85.33, "files_covered": 23, "files_total": 27, - "modules": [{ "name": "helpers", "has_spec": false }] + "loc_coverage": 79.12, + "loc_covered": 4200, + "loc_total": 5308, + "modules": [{ "name": "helpers", "has_spec": false }], + "uncovered_files": [{ "file": "src/helpers/utils.ts", "loc": 340 }] } ``` diff --git a/docs/configuration.md b/docs/configuration.md index c60cea3e..3ded63ca 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,7 +40,9 @@ Creates `specsync.json` with defaults. SpecSync also works without a config file "requiredSections": ["Purpose", "Public API", "Invariants", "Behavioral Examples", "Error Cases", "Dependencies", "Change Log"], "excludeDirs": ["__tests__"], "excludePatterns": ["**/__tests__/**", "**/*.test.ts", "**/*.spec.ts"], - "sourceExtensions": [] + "sourceExtensions": [], + "aiCommand": "claude -p --output-format text", + "aiTimeout": 120 } ``` @@ -58,6 +60,8 @@ Creates `specsync.json` with defaults. SpecSync also works without a config file | `excludeDirs` | `string[]` | `["__tests__"]` | Directory names skipped during coverage scanning | | `excludePatterns` | `string[]` | Common test globs | File patterns excluded from coverage (additive with language-specific test exclusions) | | `sourceExtensions` | `string[]` | All supported | Restrict to specific extensions (e.g., `["ts", "rs"]`) | +| `aiCommand` | `string?` | `claude -p ...` | Command for `generate --ai` (reads stdin prompt, writes stdout markdown) | +| `aiTimeout` | `number?` | `120` | Seconds before AI command times out per module | --- diff --git a/docs/index.md b/docs/index.md index 0f1a0a45..16d2ab9b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,6 +37,7 @@ specsync init # create specsync.json specsync check # validate specs against code specsync coverage # see what's covered specsync generate # scaffold specs for unspecced modules +specsync generate --ai # AI-powered specs (reads code, writes content) specsync watch # re-validate on file changes ```