You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,15 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9
9
10
10
### Added
11
11
12
-
-**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.
13
-
-Custom template documentation (`specs/_template.spec.md`) explaining how teams control generated spec structure.
14
-
-JSON output shape reference for `check` and `coverage`commands.
15
-
-Integration patterns table (pre-commit hooks, PR bots, CI coverage gates).
12
+
-**`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.
13
+
-**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.
14
+
-**Flat file module detection** — `generate` and `coverage`now detect single-file modules (e.g., `src/config.rs`) in addition to subdirectory-based modules.
15
+
-`aiCommand` and `aiTimeout` config options in `specsync.json`.
16
16
17
17
### Changed
18
18
19
19
- Rewrote README for density — every line carries new information, no filler.
20
-
-Elevated "For AI Agents" from a bullet list to a full "Spec Generation" section with usage examples and workflow guidance.
20
+
-Documented `generate --ai` workflow, AI command configuration, and LOC coverage in README and docs site.
21
21
- Streamlined docs site pages to complement rather than duplicate the README.
22
22
- Updated CHANGELOG with previously missing 1.1.1 and 1.1.2 entries.
| `aiTimeout` | `number?` | `120` | Seconds before AI command times out per module |
330
335
331
336
---
332
337
333
338
## Spec Generation
334
339
335
-
`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.
340
+
`specsync generate`scans your source directories, finds modules without spec files, and scaffolds `*.spec.md` files for each one.
336
341
337
342
```bash
338
-
specsync generate # Scaffold specs for all unspecced modules
343
+
specsync generate # Scaffold template specs for all unspecced modules
344
+
specsync generate --ai # Use AI to generate filled-in specs from source code
339
345
specsync coverage # See what's still missing
340
346
```
341
347
342
-
### How it works
348
+
### Template mode (default)
343
349
344
-
1. Runs coverage analysis to find modules with no corresponding spec
345
-
2. For each unspecced module, discovers all source files (excluding tests)
346
-
3. Generates a spec using your custom template (`specs/_template.spec.md`) or the built-in default
Uses your custom template (`specs/_template.spec.md`) or the built-in default. Generates frontmatter + stubbed sections with TODOs.
348
351
349
-
### Custom templates
352
+
### AI mode (`--ai`)
350
353
351
-
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.
354
+
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.
Copy file name to clipboardExpand all lines: docs/ai-agents.md
+43-32Lines changed: 43 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,56 +19,62 @@ SpecSync is built for LLM-powered coding tools — structured output, machine-re
19
19
20
20
---
21
21
22
-
## Generate Specs Automatically
22
+
## AI-Powered Generation (`--ai`)
23
23
24
-
`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.
24
+
`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.
For each unspecced module, you get a ready-to-fill spec:
37
+
The AI command is resolved in order:
38
+
1.`"aiCommand"` in `specsync.json`
39
+
2.`SPECSYNC_AI_COMMAND` environment variable
40
+
3.`claude -p --output-format text` (default, requires Claude CLI)
35
41
36
-
```yaml
37
-
---
38
-
module: auth
39
-
version: 1
40
-
status: draft
41
-
files:
42
-
- src/auth/service.ts
43
-
- src/auth/middleware.ts
44
-
db_tables: []
45
-
depends_on: []
46
-
---
42
+
Any command that reads a prompt from stdin and writes markdown to stdout works:
43
+
44
+
```json
45
+
{
46
+
"aiCommand": "claude -p --output-format text",
47
+
"aiTimeout": 300
48
+
}
47
49
```
48
50
49
-
Plus all required sections (Purpose, Public API, Invariants, Behavioral Examples, Error Cases, Dependencies, Change Log) with TODO placeholders.
51
+
```json
52
+
{
53
+
"aiCommand": "ollama run llama3",
54
+
"aiTimeout": 60
55
+
}
56
+
```
57
+
58
+
If AI generation fails for a module, it falls back to template generation automatically.
50
59
51
-
### Custom templates
60
+
### Template mode (no `--ai`)
52
61
53
-
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.
62
+
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.
54
63
55
64
---
56
65
57
-
## End-to-End AI Workflow
66
+
## End-to-End Workflow
58
67
59
68
```bash
60
-
# 1. Bootstrap: scaffold specs for all unspecced modules
61
-
specsync generate
62
-
63
-
# 2. Fill: LLM reads source code, fills in each spec's content
64
-
# (Purpose, Public API tables, Invariants, etc.)
69
+
# One command: AI reads code, writes specs
70
+
specsync generate --ai
65
71
66
-
#3. Validate: check specs against code, get structured errors
Use `modules` with `has_spec: false` to identify what `generate` would scaffold.
130
+
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.
121
131
122
132
---
123
133
@@ -178,6 +188,7 @@ None
178
188
|---------|---------|-----|
179
189
|**Pre-commit hook**|`specsync check --strict`| Block commits with spec errors |
180
190
|**PR review bot**|`specsync check --json`| Parse output, post as PR comment |
181
-
|**Bootstrap coverage**|`specsync generate`| Scaffold after adding new modules |
191
+
|**Bootstrap coverage**|`specsync generate --ai`| AI writes specs from source code |
192
+
|**Template scaffold**|`specsync generate`| Scaffold templates after adding new modules |
182
193
|**AI code review**|`specsync check --json`| Feed errors to LLM for spec updates |
183
194
|**Coverage gate**|`specsync check --strict --require-coverage 100`| CI enforces full coverage |
0 commit comments