@ydtb/specsmd 0.1.22

package/flows/fire/agents/builder/skills/code-review/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: code-review
+description: Review code written during a run, auto-fix no-brainer issues, and suggest improvements requiring confirmation. Invoked after tests pass.
+version: 1.0.0
+---
+
+<objective>
+Review code written during a run, auto-fix no-brainer issues, and suggest improvements requiring confirmation.
+</objective>
+
+<triggers>
+  - Invoked by run-execute after tests pass (Step 6b)
+  - Receives: files_created, files_modified, run_id, intent context
+</triggers>
+
+<degrees_of_freedom>
+
+- **AUTO-FIX**: LOW — Only mechanical, non-semantic changes
+- **SUGGESTIONS**: MEDIUM — Present options, let user decide
+</degrees_of_freedom>
+
+<llm critical="true">
+  <mandate>REVIEW all files created/modified in current run</mandate>
+  <mandate>AUTO-FIX only mechanical, non-semantic issues</mandate>
+  <mandate>ALWAYS CONFIRM security, architecture, and behavioral changes</mandate>
+  <mandate>RESPECT project coding standards from .specs-fire/standards/</mandate>
+  <mandate>NEVER break working code — if tests passed, be conservative</mandate>
+  <mandate>RE-RUN tests after auto-fixes — revert if tests fail</mandate>
+</llm>
+
+<input_context>
+  The skill receives from run-execute:
+
+  ```yaml
+  files_created:
+    - path: src/auth/login.ts
+      purpose: Login endpoint handler
+    - path: src/auth/login.test.ts
+      purpose: Unit tests for login
+
+  files_modified:
+    - path: src/routes/index.ts
+      changes: Added login route
+
+  run_id: run-001
+  intent_id: user-auth
+  ```
+
+</input_context>
+
+<references_index>
+  <reference name="review-categories" path="references/review-categories.md" load_when="analyzing code"/>
+  <reference name="auto-fix-rules" path="references/auto-fix-rules.md" load_when="classifying findings"/>
+</references_index>
+
+<flow>
+  <step n="1" title="Gather Context">
+    <action>Receive files_created and files_modified from parent workflow</action>
+    <action>Load project standards:</action>
+    <substep>.specs-fire/standards/coding-standards.md</substep>
+    <substep>.specs-fire/standards/testing-standards.md</substep>
+
+    <action>Detect project tooling:</action>
+    <substep>Check for .eslintrc, eslint.config.js (JavaScript/TypeScript)</substep>
+    <substep>Check for .prettierrc (formatting)</substep>
+    <substep>Check for golangci.yml (Go)</substep>
+    <substep>Check for pyproject.toml, ruff.toml (Python)</substep>
+
+    <action>Read each file to be reviewed</action>
+
+    <output>Reviewing {file_count} files...</output>
+  </step>
+
+  <step n="2" title="Run Project Linters (if available)">
+    <check if="eslint config exists">
+      <action>Run: npm run lint --fix 2>&1 || npx eslint --fix {files}</action>
+      <action>Parse output for remaining issues</action>
+    </check>
+
+    <check if="golangci config exists">
+      <action>Run: golangci-lint run --fix {files}</action>
+      <action>Parse output for remaining issues</action>
+    </check>
+
+    <check if="ruff/pyproject config exists">
+      <action>Run: ruff check --fix {files}</action>
+      <action>Parse output for remaining issues</action>
+    </check>
+
+    <check if="no linter configured">
+      <action>Use built-in review rules from references/review-categories.md</action>
+    </check>
+  </step>
+
+  <step n="3" title="Analyze Code">
+    <action>For each file, check against review categories:</action>
+    <substep>Code Quality — unused imports, console statements, formatting</substep>
+    <substep>Security — hardcoded secrets, injection vulnerabilities, missing validation</substep>
+    <substep>Architecture — code placement, coupling, error handling</substep>
+    <substep>Testing — coverage gaps, edge cases, brittle patterns</substep>
+
+    <action>Classify each finding using references/auto-fix-rules.md:</action>
+    <substep>AUTO-FIX: Mechanical, non-semantic, reversible, tests won't break</substep>
+    <substep>CONFIRM: Behavioral change, security implication, judgment required</substep>
+
+    <action>Group findings by category and severity</action>
+  </step>
+
+  <step n="4" title="Apply Auto-Fixes">
+    <check if="auto-fix issues found">
+      <action>Apply all AUTO-FIX changes</action>
+      <action>Track each change made (file, line, before, after)</action>
+
+      <critical>Re-run tests to verify no breakage</critical>
+      <action>Run project test command</action>
+
+      <check if="tests fail after auto-fix">
+        <output>Auto-fix caused test failure. Reverting...</output>
+        <action>Revert all auto-fix changes</action>
+        <action>Move failed fixes to CONFIRM category</action>
+      </check>
+
+      <check if="tests pass">
+        <output>Auto-fixed {count} issues. Tests still passing.</output>
+      </check>
+    </check>
+  </step>
+
+  <step n="5" title="Generate Review Report">
+    <action>Create review report using template: templates/review-report.md.hbs</action>
+    <action>Write to: .specs-fire/runs/{run-id}/review-report.md</action>
+    <action>Include: auto-fixed issues, pending suggestions, skipped items</action>
+  </step>
+
+  <step n="6" title="Present Suggestions">
+    <check if="no suggestions requiring confirmation">
+      <output>
+        ## Code Review Complete
+
+        Auto-fixed {auto_count} issues. No additional suggestions.
+
+        Review report: .specs-fire/runs/{run-id}/review-report.md
+      </output>
+      <return>success</return>
+    </check>
+
+    <check if="suggestions exist">
+      <template_output section="suggestions">
+        ## Code Review Complete
+
+        **Auto-fixed ({auto_count} issues)**:
+        {for each auto_fixed}
+        - {description} ({file}:{line})
+        {/for}
+
+        **Suggestions requiring approval ({suggest_count} issues)**:
+
+        {for each suggestion with index}
+        {index}. **[{category}]** {title}
+           - File: {file}:{line}
+           - Suggestion: {description}
+           - Risk: {risk_level}
+        {/for}
+
+        ---
+        Apply suggestions?
+        [a] Apply all suggestions
+        {for each suggestion with index}
+        [{index}] Apply #{index} only ({category})
+        {/for}
+        [s] Skip all suggestions
+        [r] Review each individually
+      </template_output>
+
+      <checkpoint>Wait for user response</checkpoint>
+    </check>
+  </step>
+
+  <step n="7" title="Process User Choice">
+    <check if="response == a">
+      <action>Apply all suggestions</action>
+      <action>Re-run tests</action>
+      <action>Update review-report.md with applied status</action>
+    </check>
+
+    <check if="response == s">
+      <action>Skip all suggestions</action>
+      <action>Update review-report.md with skipped status</action>
+    </check>
+
+    <check if="response == r">
+      <iterate over="suggestions" as="suggestion">
+        <template_output section="individual_suggestion">
+          **[{suggestion.category}]** {suggestion.title}
+
+          File: {suggestion.file}:{suggestion.line}
+
+          Current code:
+          ```
+          {suggestion.current_code}
+          ```
+
+          Suggested change:
+          ```
+          {suggestion.suggested_code}
+          ```
+
+          Rationale: {suggestion.rationale}
+
+          Apply this change? [y/n]
+        </template_output>
+        <checkpoint>Wait for response</checkpoint>
+        <check if="response == y">
+          <action>Apply this suggestion</action>
+        </check>
+      </iterate>
+      <action>Re-run tests if any changes applied</action>
+    </check>
+
+    <check if="response is number">
+      <action>Apply only the numbered suggestion</action>
+      <action>Re-run tests</action>
+      <action>Update review-report.md</action>
+    </check>
+  </step>
+
+  <step n="8" title="Return to Parent">
+    <action>Return summary to run-execute workflow:</action>
+    <return_value>
+      {
+        "success": true,
+        "auto_fixed_count": {count},
+        "suggestions_applied": {count},
+        "suggestions_skipped": {count},
+        "tests_passing": true,
+        "report_path": ".specs-fire/runs/{run-id}/review-report.md"
+      }
+    </return_value>
+  </step>
+</flow>
+
+<output_artifact>
+  Creates `.specs-fire/runs/{run-id}/review-report.md` with:
+
+- Summary table (auto-fixed, suggested, skipped by category)
+- Detailed list of auto-fixed issues with diffs
+- Applied suggestions with approval timestamps
+- Skipped suggestions with reasons
+</output_artifact>
+
+<success_criteria>
+  <criterion>All files created/modified in run reviewed</criterion>
+  <criterion>Auto-fixes applied without breaking tests</criterion>
+  <criterion>Suggestions presented for user approval</criterion>
+  <criterion>review-report.md created in run folder</criterion>
+  <criterion>Return status to parent workflow</criterion>
+</success_criteria>

package/flows/fire/agents/builder/skills/code-review/references/auto-fix-rules.md

@@ -0,0 +1,218 @@
+# Auto-Fix Rules
+
+This reference defines the criteria for determining whether an issue can be auto-fixed or requires user confirmation.
+
+---
+
+## Decision Framework
+
+```
+CAN AUTO-FIX if ALL of these are true:
+├── Change is mechanical (not semantic)
+├── Change follows existing pattern in codebase
+├── Change has no functional impact
+├── Change is universally agreed best practice
+├── Reverting is trivial if wrong
+└── Tests will still pass (verified after fix)
+
+MUST CONFIRM if ANY of these are true:
+├── Change affects behavior/functionality
+├── Change requires judgment call
+├── Change involves security implications
+├── Change affects public API
+├── Multiple valid approaches exist
+├── Change is significant (>10 lines affected)
+└── Change could break dependent code
+```
+
+---
+
+## Auto-Fix Criteria by Category
+
+### 1. Removal Operations (SAFE)
+
+These can be auto-fixed because removal of unused code has no functional impact:
+
+| Operation | Criteria | Safe Because |
+|-----------|----------|--------------|
+| Remove unused import | Import not referenced anywhere | No runtime effect |
+| Remove unused variable | Variable never read | No runtime effect |
+| Remove console.log | Debug statement | No production effect |
+| Remove console.debug | Debug statement | No production effect |
+| Remove debugger | Debug statement | No production effect |
+| Remove trailing whitespace | Whitespace only | No code effect |
+| Remove empty lines (excess) | >2 consecutive blank lines | Formatting only |
+
+### 2. Formatting Operations (SAFE)
+
+These can be auto-fixed because they don't change semantics:
+
+| Operation | Criteria | Safe Because |
+|-----------|----------|--------------|
+| Sort imports | Reorder import statements | No runtime effect |
+| Standardize quotes | Use project's quote style | String value unchanged |
+| Add missing semicolons | Project uses semicolons | Parser handles both |
+| Fix indentation | Match project indent style | Whitespace only |
+| Add trailing newline | File doesn't end with newline | POSIX standard |
+
+### 3. Simple Substitutions (SAFE with verification)
+
+These can be auto-fixed but require test verification:
+
+| Operation | Criteria | Verify |
+|-----------|----------|--------|
+| `var` → `const` | Variable never reassigned | Run tests |
+| `var` → `let` | Variable is reassigned | Run tests |
+| `==` → `===` | Comparing same types | Run tests |
+| `!=` → `!==` | Comparing same types | Run tests |
+
+---
+
+## Must-Confirm Criteria
+
+### 1. Behavioral Changes
+
+Any change that could affect runtime behavior:
+
+| Change | Why Confirm |
+|--------|-------------|
+| Add null check | Changes control flow |
+| Add try/catch | Changes error handling |
+| Add validation | May reject valid input |
+| Change function signature | Affects callers |
+| Add/remove async | Changes execution model |
+| Modify return value | Affects callers |
+
+### 2. Security Changes
+
+All security-related changes require confirmation:
+
+| Change | Why Confirm |
+|--------|-------------|
+| Add input validation | May have false positives |
+| Add authentication | May break intended access |
+| Add authorization | May be too restrictive |
+| Change crypto | May have compatibility issues |
+| Add rate limiting | May affect legitimate users |
+
+### 3. Architectural Changes
+
+Changes affecting code structure:
+
+| Change | Why Confirm |
+|--------|-------------|
+| Extract function | Multiple valid ways |
+| Move code to different file | Affects imports |
+| Add abstraction layer | Judgment on necessity |
+| Change dependency injection | Affects instantiation |
+| Modify error propagation | Affects error handling chain |
+
+### 4. Size Threshold
+
+Changes affecting many lines:
+
+| Threshold | Action |
+|-----------|--------|
+| 1-5 lines | Can auto-fix if mechanical |
+| 6-10 lines | Prefer confirmation |
+| >10 lines | Must confirm |
+
+---
+
+## Rollback Protocol
+
+If auto-fix causes test failure:
+
+```
+1. Immediately revert ALL auto-fix changes
+2. Move the fix to CONFIRM category
+3. Report: "Auto-fix for X caused test failure, moved to suggestions"
+4. Continue with remaining auto-fixes
+5. Re-run tests after each batch
+```
+
+---
+
+## Project-Specific Overrides
+
+The project can customize auto-fix behavior in `.specs-fire/standards/coding-standards.md`:
+
+```yaml
+# In coding-standards.md frontmatter
+auto_fix:
+  allow:
+    - unused_imports
+    - console_statements
+    - trailing_whitespace
+  deny:
+    - quote_style  # Team prefers manual control
+    - semicolons   # Mixed codebase
+
+  # Custom patterns to auto-remove
+  remove_patterns:
+    - "// TODO: remove"
+    - "// DEBUG"
+```
+
+If `auto_fix` section exists, respect project preferences.
+If not specified, use default rules from this document.
+
+---
+
+## Examples
+
+### Auto-Fix Example
+
+**Before:**
+
+```javascript
+import { unused } from './module';  // unused import
+import { used } from './other';
+
+function process() {
+  console.log('debug');  // debug statement
+  const result = used();
+  return result;
+}
+```
+
+**After (auto-fixed):**
+
+```javascript
+import { used } from './other';
+
+function process() {
+  const result = used();
+  return result;
+}
+```
+
+**Report:**
+
+- Removed unused import `unused` from `./module`
+- Removed console.log statement
+
+### Confirm Example
+
+**Issue Detected:**
+
+```javascript
+function getUser(id) {
+  return db.query(`SELECT * FROM users WHERE id = ${id}`);
+}
+```
+
+**Suggested Fix:**
+
+```javascript
+function getUser(id) {
+  return db.query('SELECT * FROM users WHERE id = ?', [id]);
+}
+```
+
+**Why Confirm:**
+
+- Security fix (SQL injection)
+- Changes how query is constructed
+- May have edge cases with ID format
+- Requires understanding of db.query API

package/flows/fire/agents/builder/skills/code-review/references/review-categories.md

@@ -0,0 +1,154 @@
+# Code Review Categories
+
+This reference defines what the code-review skill checks for in each category.
+
+---
+
+## 1. Code Quality
+
+Issues related to code cleanliness and maintainability.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Unused imports | Import not referenced in file | Remove import |
+| Unused variables | Variable declared but never used | Remove declaration |
+| Console statements | `console.log`, `console.debug`, `print()` | Remove statement |
+| Commented-out code | Large blocks of commented code | Remove comments |
+| Trailing whitespace | Whitespace at end of lines | Trim whitespace |
+| Missing semicolons | JS/TS without semicolons (if project uses them) | Add semicolons |
+| Inconsistent quotes | Mixed single/double quotes | Standardize |
+| Empty blocks | Empty if/else/try/catch with no comment | Add TODO comment |
+| Debugger statements | `debugger` keyword | Remove statement |
+
+### Requires Confirmation
+
+| Issue | Detection | Why Confirm |
+|-------|-----------|-------------|
+| Long functions | Function > 50 lines | Requires judgment on how to split |
+| Deep nesting | > 4 levels of nesting | Multiple valid refactoring approaches |
+| Duplicate code | Similar code blocks (>10 lines) | May be intentional |
+| Magic numbers | Hardcoded numbers without context | Need to understand meaning |
+| Complex conditionals | Complex boolean expressions | May need domain knowledge |
+
+---
+
+## 2. Security
+
+Issues that could lead to security vulnerabilities.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Hardcoded localhost | `localhost` or `127.0.0.1` in production code | Flag but usually intentional |
+
+### Requires Confirmation (ALWAYS)
+
+| Issue | Detection | Risk |
+|-------|-----------|------|
+| Hardcoded secrets | API keys, passwords, tokens in code | Critical - secrets exposure |
+| SQL injection | String concatenation in SQL queries | Critical - data breach |
+| XSS vulnerabilities | Unescaped user input in HTML | High - script injection |
+| Command injection | User input in shell commands | Critical - RCE |
+| Path traversal | User input in file paths | High - unauthorized access |
+| Missing input validation | User input used without validation | Medium - various attacks |
+| Insecure crypto | Weak algorithms (MD5, SHA1 for passwords) | High - broken encryption |
+| CORS misconfiguration | `Access-Control-Allow-Origin: *` | Medium - CSRF |
+| Missing auth checks | Endpoints without authentication | High - unauthorized access |
+| Sensitive data in logs | PII, passwords logged | Medium - data leak |
+
+---
+
+## 3. Architecture
+
+Issues related to code organization and design.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Import order | Imports not grouped/sorted | Sort imports |
+
+### Requires Confirmation (ALWAYS)
+
+| Issue | Detection | Why Confirm |
+|-------|-----------|-------------|
+| Wrong layer | Business logic in controller, DB in UI | Requires understanding architecture |
+| Missing error handling | No try/catch for async/IO operations | May be intentional propagation |
+| Tight coupling | Direct dependencies on concrete classes | Multiple valid solutions |
+| Missing abstraction | Repeated patterns that could be extracted | Judgment on when to abstract |
+| Circular dependencies | Module A imports B, B imports A | Requires refactoring design |
+| God class/function | Class/function doing too many things | Domain knowledge needed |
+| Inconsistent patterns | Different approaches for same problem | Need to pick canonical approach |
+| Missing logging | No logging for important operations | Need to understand what matters |
+| Synchronous blocking | Blocking calls in async context | May need architecture change |
+
+---
+
+## 4. Testing
+
+Issues related to test quality and coverage.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Console in tests | `console.log` in test files | Remove statement |
+
+### Requires Confirmation (ALWAYS)
+
+| Issue | Detection | Why Confirm |
+|-------|-----------|-------------|
+| Missing tests | New function without corresponding test | Need to understand what to test |
+| Missing edge cases | Tests only cover happy path | Need domain knowledge |
+| Brittle tests | Tests rely on implementation details | Multiple valid approaches |
+| Missing assertions | Test runs but doesn't assert | May be setup test |
+| Test coverage gaps | Lines not covered by tests | Need to prioritize |
+| Flaky test patterns | Random data, timing dependencies | Need to understand intent |
+| Missing error tests | No tests for error conditions | Need to identify error cases |
+| Mock overuse | Everything mocked, no integration | Judgment on test strategy |
+
+---
+
+## Language-Specific Checks
+
+### JavaScript/TypeScript
+
+| Issue | Category | Auto-Fix |
+|-------|----------|----------|
+| `var` instead of `let/const` | Quality | Yes |
+| `==` instead of `===` | Quality | Yes (with caution) |
+| Missing `await` | Quality | Confirm |
+| `any` type usage | Quality | Confirm |
+| Missing null checks | Security | Confirm |
+
+### Go
+
+| Issue | Category | Auto-Fix |
+|-------|----------|----------|
+| Ignored error returns | Quality | Confirm |
+| Naked returns | Quality | Confirm |
+| Empty interface{} | Quality | Confirm |
+| Missing context | Architecture | Confirm |
+
+### Python
+
+| Issue | Category | Auto-Fix |
+|-------|----------|----------|
+| Bare except | Quality | Confirm |
+| Mutable default args | Quality | Confirm |
+| Missing type hints | Quality | Confirm |
+| `import *` | Quality | Yes |
+
+---
+
+## Severity Levels
+
+| Level | Description | Action |
+|-------|-------------|--------|
+| **Critical** | Security vulnerability, data loss risk | MUST address |
+| **High** | Significant quality/maintainability issue | SHOULD address |
+| **Medium** | Best practice violation | CONSIDER addressing |
+| **Low** | Minor style/preference issue | OPTIONAL |