specflow-cc 1.11.1 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.12.0] - 2026-02-10
+
+### Added
+
+- **Language Profiles** — optional, per-language configuration in PROJECT.md that adapts all agents to language-specific needs
+  - `/sf:init` auto-detects language from `Cargo.toml` (Rust), `go.mod` (Go), `tsconfig.json` (TypeScript), `pyproject.toml` (Python)
+  - Generates `## Language Profile` section in PROJECT.md with build/lint/test commands, max files per spec, compilation gate, and trait-first settings
+  - Projects without a detected language remain fully language-agnostic (backward-compatible)
+
+- **Compilation gates** — incremental build verification during implementation (Rust, Go)
+  - `spec-executor` and `spec-executor-worker` run `build_check` command after each file or tightly coupled group
+  - Build failures auto-fixed before proceeding (Rule 3: blocking issues)
+  - Lint check runs at end of implementation scope
+  - New `build_check` field in worker JSON result protocol
+
+- **Trait-first enforcement** — compiled languages require type/trait design before implementation
+  - `spec-creator` mandates G1/Wave 1 as types-only when `Trait-first: Yes`
+  - `spec-auditor` validates trait-first compliance (Critical if G1 mixes traits and implementation)
+  - Prevents cascading rework from wrong trait boundaries in Rust/Go
+
+- **Language-aware spec sizing** — file count limits adapted per language
+  - Rust: 3-5 files max (borrow checker errors cascade)
+  - Go: 5-8 files max
+  - TypeScript/Python: 8-10 files max
+  - `spec-auditor` raises Warning/Critical when file count exceeds language profile limit
+
+- **Language-specific review gates** in `impl-reviewer`
+  - Runs build, lint, and test commands from profile as review gates
+  - Rust idiom checks: no unnecessary `.clone()`, `?` operator over `.unwrap()`, `unsafe` documentation, `Send + Sync` bounds
+  - Go idiom checks: error returns over panics, interfaces accepted/structs returned, context propagation
+
+### Changed
+
+- `templates/project.md` — added optional Language Profile section
+- `spec-auditor` — added Step 3.10 (Language Profile Check) with 5 sub-checks and scope threshold override
+- `spec-creator` — added language-specific sizing table and trait-first override in task group generation
+
+---
+
 ## [1.11.1] - 2026-02-10
 
 ### Fixed

package/agents/impl-reviewer.md

@@ -165,6 +165,54 @@ During code review, watch for signals that the specification itself may have bee
 
 **Note:** This is a safety net, not a primary check. Strategic issues should be caught earlier by `spec-auditor`.
 
+### 4.9 Language Profile Check
+
+**Detection:** Check if PROJECT.md contains a `## Language Profile` section.
+
+**If no Language Profile:** Skip this check.
+
+**If Language Profile exists:** Run configured verification commands and check results.
+
+**4.9.1 Build Check:**
+Run `Build check` command from profile (e.g., `cargo check`, `go build ./...`):
+```bash
+{build_check_command}
+```
+- Exit 0 → ✓ Passed
+- Non-zero → **Critical**: "Build check failed: {error output}"
+
+**4.9.2 Lint Check:**
+Run `Lint` command from profile (e.g., `cargo clippy -- -D warnings`):
+```bash
+{lint_command}
+```
+- Exit 0 → ✓ Passed
+- Non-zero → **Major**: "Lint check failed: {warning count} warnings/errors"
+
+**4.9.3 Test Check:**
+Run `Test` command from profile (e.g., `cargo test`):
+```bash
+{test_command}
+```
+- Exit 0 → ✓ Passed
+- Non-zero → **Critical**: "Tests failed: {failure summary}"
+
+**4.9.4 Language-Specific Idiom Check:**
+
+For **Rust** (Language = Rust):
+- [ ] No unnecessary `.clone()` calls — prefer borrowing
+- [ ] Error handling uses `?` operator and `Result<T, E>` — not `.unwrap()` or `.expect()` in production code
+- [ ] `unsafe` blocks have safety invariant comments
+- [ ] Proper `Send + Sync` bounds on trait objects
+- [ ] No `Box<dyn Any>` type erasure where concrete types work
+
+For **Go** (Language = Go):
+- [ ] Errors returned, not panicked
+- [ ] Interfaces accepted, structs returned
+- [ ] Context propagation (`ctx context.Context` as first param)
+
+If idiom violations found: add as **Major** issues with specific file:line references.
+
 ## Step 5: Categorize Findings
 
 Organize into:

package/agents/spec-auditor.md

@@ -415,6 +415,57 @@ Check if spec includes items marked as "Out of Scope" or "Deferred" in PROJECT.m
 **If compliant:**
 - Add to audit output: "Project compliance: ✓ Honors PROJECT.md decisions"
 
+## Step 3.10: Language Profile Check
+
+**Detection:** Check if PROJECT.md contains a `## Language Profile` section.
+
+**If no Language Profile section:** Skip this check entirely.
+
+**If Language Profile exists:** Parse settings and validate spec compliance.
+
+### 3.10.1 File Count Check
+
+Extract `Max files per spec` from profile. Count total files to create + modify in spec.
+
+| Condition | Action |
+|-----------|--------|
+| Files ≤ max | ✓ OK |
+| Files = max + 1-2 | **Warning**: "File count ({N}) slightly exceeds language profile limit ({max}). Consider splitting." |
+| Files > max + 2 | **Critical**: "File count ({N}) significantly exceeds language profile limit ({max}). Must split with `/sf:split`." |
+
+### 3.10.2 Trait-First Check
+
+If `Trait-first: Yes` AND spec complexity is medium or large:
+
+- Check if Implementation Tasks section exists
+- If yes: verify G1 (Wave 1) contains ONLY types/traits/interfaces, not implementation
+- If G1 mixes traits and implementation: **Critical**: "Trait-first violation: G1 must contain only types/traits/interfaces. Implementation must be in Wave 2+."
+- If no Implementation Tasks: **Warning**: "Trait-first language requires explicit task grouping for medium/large specs. Recommend adding Implementation Tasks with types in G1."
+
+### 3.10.3 Compilation Gate Awareness
+
+If `Compilation gate: Yes`:
+
+- Verify task groups are small enough for incremental compilation checks
+- If any single task group modifies >3 files: **Warning**: "Large task group ({N} files) with compilation gate. Consider splitting into smaller groups for incremental `build_check` verification."
+
+### 3.10.4 Scope Threshold Override
+
+If Language Profile exists, override default Scope Sanity Thresholds:
+
+| Metric | Default | With Language Profile |
+|--------|---------|---------------------|
+| Files/plan (Blocker) | 15+ | `Max files per spec` from profile |
+| Tasks/plan (Warning) | 4 | 3 (if `Trait-first: Yes`) |
+
+### 3.10.5 Language Profile Verdict
+
+**If all checks pass:**
+- Add to audit output: "Language profile: ✓ Compliant with {Language} profile"
+
+**If warnings or critical issues found:**
+- Add issues to appropriate category (Critical/Recommendations)
+
 ## Step 4: Generate Implementation Tasks (for large specs)
 
 If scope is large, generate the Implementation Tasks section:
@@ -738,6 +789,7 @@ Tip: `/clear` recommended before `/sf:run` — executor needs fresh context
 - [ ] Specification fully read
 - [ ] PROJECT.md context loaded
 - [ ] All 10 dimensions evaluated (clarity, completeness, testability, scope, feasibility, architecture, duplication, cognitive load, strategic fit, project compliance)
+- [ ] Language profile checked (if present in PROJECT.md)
 - [ ] Assumptions extracted and impact assessed
 - [ ] Project alignment verified
 - [ ] Project compliance verified (decisions, constraints, out-of-scope)

package/agents/spec-creator.md

@@ -42,6 +42,26 @@ Good specifications are:
 | medium | 50-150k | Multiple files, moderate feature |
 | large | >150k | Many files, complex feature — needs /sf:split |
 
+## Language Profile Awareness
+
+If PROJECT.md contains a `## Language Profile` section, adapt behavior:
+
+**Max files per spec:** If `Max files per spec` is set (e.g., 5 for Rust), use it for complexity estimation. A spec exceeding this limit should be flagged as needing `/sf:split`.
+
+**Trait-first:** If `Trait-first: Yes`, for medium and large specs:
+- First task group (G1, Wave 1) MUST be types/traits/interfaces only
+- Implementation groups depend on G1
+- This ensures trait design is audited before implementation begins
+
+**Language-specific sizing:**
+
+| Language | Max Files | Trait-First | Notes |
+|----------|-----------|-------------|-------|
+| Rust | 3-5 | Yes | Borrow checker errors cascade; smaller specs essential |
+| Go | 5-8 | Yes | Interface design drives implementation |
+| TypeScript | 8-10 | No | Dynamic typing allows larger specs |
+| Python | 8-10 | No | Dynamic typing allows larger specs |
+
 </philosophy>
 
 <process>
@@ -136,6 +156,12 @@ Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 - **Medium** and **large** complexity specs: Always include Implementation Tasks section
 - **Small** complexity specs: Optional (skip if only 1-2 files or simple change)
 
+**Language Profile Override:**
+If PROJECT.md has `Trait-first: Yes` in Language Profile:
+- G1 (Wave 1) MUST contain ONLY types/traits/interfaces — no implementation
+- All implementation groups MUST depend on G1
+- This is mandatory, not a suggestion — trait design errors cascade in compiled languages
+
 **Task Groups:**
 
 1. Group related work logically:

package/agents/spec-executor-worker.md

@@ -122,6 +122,22 @@ After implementing, verify:
 - Follows project conventions
 - Meets task requirements
 
+### 3.2.1 Compilation Gate (Language Profile)
+
+If PROJECT.md has `Compilation gate: Yes` in Language Profile:
+
+After implementing each file or tightly coupled group, run the `Build check` command:
+
+```bash
+# Example for Rust: cargo check
+# Example for Go: go build ./...
+```
+
+**If build fails:** fix immediately (Rule 3: Auto-fix blocking issues). Do NOT proceed until current file compiles.
+**If build passes:** continue to next file.
+
+At end of all tasks in this group: run `Lint` command if specified in profile (e.g., `cargo clippy -- -D warnings`).
+
 ### 3.3 Commit
 
 Create atomic commit:
@@ -189,10 +205,13 @@ Output structured JSON for orchestrator:
   ],
   "deviations": [],
   "self_check": "passed",
+  "build_check": "passed",
   "error": null
 }
 ```
 
+**Note:** `build_check` field is only included when Language Profile has `Compilation gate: Yes`. Values: `"passed"`, `"fixed"` (had to fix compilation errors), `"skipped"` (no language profile).
+
 **For segmented execution, add segment fields:**
 
 ```json

package/agents/spec-executor.md

@@ -131,6 +131,28 @@ After implementing, verify:
 - Meets relevant acceptance criteria
 - Follows project conventions
 
+### 4.2.1 Compilation Gate (Language Profile)
+
+If PROJECT.md has `Compilation gate: Yes` in Language Profile:
+
+After implementing each file or tightly coupled group of files, run the `Build check` command from the profile:
+
+```bash
+# Example for Rust:
+cargo check
+# Example for Go:
+go build ./...
+```
+
+**If build fails:**
+- Fix the compilation error immediately (Rule 3: Auto-fix blocking issues)
+- Do NOT proceed to next file until current file compiles
+- Track as: `[Rule 3 - Compilation] Fixed {error} in {file}`
+
+**If build passes:** continue to next file.
+
+This prevents cascading errors — especially critical for Rust where borrow checker errors in file A can mask the real issue in file B.
+
 ### 4.3 Commit
 
 Create atomic commit:
@@ -191,7 +213,16 @@ For key modifications, verify the change is present:
 grep -q "expected_pattern" path/to/modified/file && echo "VERIFIED" || echo "NOT FOUND"
 ```
 
-**4. Report self-check result:**
+**4. Language profile checks (if Language Profile exists in PROJECT.md):**
+
+Run each configured command and verify it passes:
+- `Lint` command (e.g., `cargo clippy -- -D warnings`) → must exit 0
+- `Test` command (e.g., `cargo test`) → must exit 0
+- `Safety check` command if present (e.g., `cargo miri test`) → must exit 0
+
+If any check fails: fix the issue before proceeding (Rule 3).
+
+**5. Report self-check result:**
 
 - If ALL checks pass: continue to Execution Summary
 - If ANY check fails: **fix the issue** before proceeding, do NOT report success with missing artifacts

package/commands/sf/init.md

@@ -77,6 +77,83 @@ ls -d **/components/** 2>/dev/null | head -5
 ls tsconfig.json 2>/dev/null
 ```
 
+## Step 4.5: Detect Language Profile
+
+Based on Step 2 detection results, determine primary language and generate profile:
+
+**Rust** (if `Cargo.toml` found):
+```markdown
+## Language Profile
+
+| Setting | Value |
+|---------|-------|
+| Language | Rust |
+| Build check | `cargo check` |
+| Lint | `cargo clippy -- -D warnings` |
+| Test | `cargo test` |
+| Max files per spec | 5 |
+| Compilation gate | Yes — run `cargo check` after each implementation block |
+| Trait-first | Yes — trait/interface design must be in Wave 1 |
+
+### Rust-Specific Guidelines
+
+- Keep specs to 3-5 files max (borrow checker errors cascade across files)
+- Design traits/interfaces before implementation (wrong trait boundaries force rewrites)
+- Run `cargo check` after every file change, not just at the end
+- Prefer `Result<T, E>` over `unwrap()`/`expect()` in production code
+- Document `unsafe` blocks with safety invariants
+- Use `cargo clippy` as mandatory quality gate
+```
+
+**Go** (if `go.mod` found):
+```markdown
+## Language Profile
+
+| Setting | Value |
+|---------|-------|
+| Language | Go |
+| Build check | `go build ./...` |
+| Lint | `golangci-lint run` |
+| Test | `go test ./...` |
+| Max files per spec | 8 |
+| Compilation gate | Yes — run `go build ./...` after each implementation block |
+| Trait-first | Yes — interface design must be in Wave 1 |
+```
+
+**TypeScript** (if `tsconfig.json` found):
+```markdown
+## Language Profile
+
+| Setting | Value |
+|---------|-------|
+| Language | TypeScript |
+| Build check | `npx tsc --noEmit` |
+| Lint | `npx eslint .` |
+| Test | `pnpm test` |
+| Max files per spec | 10 |
+| Compilation gate | No |
+| Trait-first | No |
+```
+
+**Python** (if `pyproject.toml` or `setup.py` found):
+```markdown
+## Language Profile
+
+| Setting | Value |
+|---------|-------|
+| Language | Python |
+| Build check | — |
+| Lint | `ruff check .` |
+| Test | `pytest` |
+| Max files per spec | 10 |
+| Compilation gate | No |
+| Trait-first | No |
+```
+
+**If no recognized language detected:** omit Language Profile section entirely.
+
+Include the generated profile in Step 6 (Generate PROJECT.md) before the closing `---` line.
+
 ## Step 5: Create .specflow Directory
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"

package/templates/project.md

@@ -35,5 +35,19 @@
 - [Constraint 1: e.g., Must work offline]
 - [Constraint 2]
 
+## Language Profile
+
+[Optional — auto-generated by /sf:init based on detected language. Agents use this to adapt spec sizing, compilation gates, and review checks. Remove this section for language-agnostic behavior.]
+
+| Setting | Value |
+|---------|-------|
+| Language | [e.g., Rust, TypeScript, Python, Go] |
+| Build check | [e.g., `cargo check`, `npx tsc --noEmit`] |
+| Lint | [e.g., `cargo clippy -- -D warnings`, `npx eslint .`] |
+| Test | [e.g., `cargo test`, `pnpm test`] |
+| Max files per spec | [e.g., 5 for Rust, 10 for TypeScript] |
+| Compilation gate | [Yes/No — run build check after each implementation block] |
+| Trait-first | [Yes/No — require trait/interface design in Wave 1] |
+
 ---
 *Generated by SpecFlow on [date]*