feat: brownkit v0.2.1 — legacy code remediation toolkit

Complete implementation of brownkit, a spec-kit plugin for legacy code
assessment, remediation, and graduation workflows.

Core features:
- Phase-based workflow engine (assessment → structure → testing → quality
  → validation → graduation) with state machine transitions
- Language detection and plugin system (Python, JavaScript, Rust, Go)
- Orchestrators for each phase with checkpoint/interruption recovery
- Metrics collection, complexity analysis, and graduation gates
- Speckit integration module with workflow enforcement
- CLI with slash commands for all workflow phases
- Comprehensive test suite (unit, contract, integration)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jacopone

.claude/commands/brownkit.assess.md

@@ -0,0 +1,82 @@
+# BrownKit: Assess
+
+**Execute comprehensive brownfield project assessment.**
+
+This command initiates the BrownKit workflow by analyzing the current project's structure, test coverage, code quality, and technical debt. This is the **entry point** for the brownfield-to-Spec-Kit transformation workflow.
+
+## What This Command Does
+
+1. **Enforces Workflow**: Validates this is the correct phase to execute
+2. **Project Analysis**: Scans codebase for structure, tests, and quality metrics
+3. **Baseline Metrics**: Establishes baseline for future regression detection
+4. **Planning Foundation**: Generates data needed for remediation planning
+5. **State Initialization**: Creates `.specify/memory/state.json` with results
+
+## Workflow Position
+
+```
+[YOU ARE HERE] → PLANNING → REMEDIATION → VALIDATION → GRADUATION → SPEC-KIT READY
+  ASSESSMENT
+```
+
+This phase can always be executed, even if state doesn't exist (it initializes the workflow).
+
+## Assessment Dimensions
+
+### 1. Structure Analysis
+- File organization and directory structure
+- Module dependencies and coupling
+- Dead code detection
+- Duplicate code identification
+
+### 2. Testing Analysis
+- Test coverage percentage
+- Test types present (unit, integration, e2e)
+- Test quality and assertions
+- Missing test areas
+
+### 3. Quality Analysis
+- Cyclomatic complexity (functions, classes, modules)
+- Code smells and anti-patterns
+- Linting violations
+- Security vulnerabilities
+
+### 4. Build & CI Analysis
+- Build system configuration
+- CI/CD pipeline status
+- Deployment readiness
+- Documentation quality
+
+## Expected Output
+
+After completion, you'll see:
+- **Assessment summary** with key metrics
+- **Baseline metrics** recorded in state
+- **Recommended next steps** for planning
+- **State file** created at `.specify/memory/state.json`
+
+## Next Steps
+
+After assessment completes successfully:
+1. Review the assessment report
+2. Run `/brownkit.plan` to create remediation plan
+3. The workflow enforcer will guide you through remaining phases
+
+## Technical Details
+
+- **Command**: `brownfield assess` (CLI) or orchestrator
+- **Output**: `.specify/memory/state.json`
+- **Prerequisites**: None (entry point)
+- **Duration**: 2-5 minutes depending on codebase size
+
+## Error Handling
+
+If this command fails:
+- Check that you're in a project root directory
+- Ensure basic language tools are available (pytest, jest, cargo, go, etc.)
+- Review error output for specific issues
+- Re-run after addressing issues
+
+---
+
+**Note**: This command can be re-run multiple times. Each run updates the state with latest metrics, allowing you to track improvement over time.

.claude/commands/brownkit.graduate.md

@@ -0,0 +1,189 @@
+# BrownKit: Graduate
+
+**Graduate to Spec-Kit readiness by generating project constitution.**
+
+This command marks the successful completion of the BrownKit workflow by generating a project constitution that encodes all quality standards, testing requirements, and architectural constraints. The constitution becomes the foundation for Spec-Kit's specification-driven development.
+
+## What This Command Does
+
+1. **Enforces Workflow**: Validates all readiness gates passed before graduation
+2. **Constitution Generation**: Creates `constitution.md` from graduation metrics
+3. **Spec-Kit Integration**: Verifies Spec-Kit compatibility and initializes integration
+4. **Workflow Completion**: Marks project as SPEC_KIT_READY
+5. **Monitoring Setup**: Establishes baseline for post-graduation regression detection
+
+## Workflow Position
+
+```
+ASSESSMENT → PLANNING → REMEDIATION → VALIDATION → [YOU ARE HERE] → SPEC-KIT READY
+                                                     GRADUATION
+```
+
+**Prerequisites**: All 7 readiness gates must pass validation.
+
+## Graduation Process
+
+### 1. Pre-Graduation Checks
+- ✅ All 7 readiness gates passed
+- ✅ Validation completed without regressions
+- ✅ Build and CI passing
+- ✅ No critical security issues
+
+### 2. Constitution Generation
+The constitution encodes your project's quality standards:
+
+**Structure Standards**:
+- Directory organization rules
+- Module coupling constraints
+- Dead code tolerance (0%)
+
+**Testing Requirements**:
+- Minimum coverage percentage (from achieved metrics)
+- Required test types (unit, integration, e2e)
+- Test quality standards (assertions per test)
+
+**Quality Gates**:
+- Maximum cyclomatic complexity (CCN threshold)
+- Linting rules and violation tolerance
+- Code smell detection rules
+
+**Security Standards**:
+- Vulnerability tolerance by severity
+- Secrets detection requirements
+- Dependency update policy
+
+**Build & CI Requirements**:
+- Build success criteria
+- CI pipeline requirements
+- Pre-commit hook configuration
+
+### 3. Spec-Kit Compatibility Check
+Verifies:
+- ✅ `.claude/commands/speckit.specify.md` exists (Spec-Kit installed)
+- ✅ `.specify/memory/` directory writable
+- ✅ Slash commands available
+- ⚠️ Warns if constitution already exists (offers backup)
+
+### 4. Constitution File Creation
+Generated file: `.specify/memory/constitution.md`
+
+**Content includes**:
+```markdown
+# Project Constitution
+
+Generated: YYYY-MM-DD
+Language: Python/JavaScript/Rust/Go
+Baseline: [graduation metrics]
+
+## Quality Standards
+[Encoded from validation metrics]
+
+## Testing Requirements
+[Coverage targets, test types, quality gates]
+
+## Security Requirements
+[Vulnerability thresholds, secrets policy]
+
+## Build & CI Requirements
+[Build configuration, pipeline requirements]
+
+## Regression Thresholds
+[Post-graduation monitoring thresholds]
+```
+
+## Expected Output
+
+After graduation, you'll see:
+- **✅ Graduation successful** message
+- **Constitution path**: `.specify/memory/constitution.md`
+- **Spec-Kit status**: Integration details
+- **Next steps**: Using Spec-Kit for new features
+- **Monitoring setup**: Regression detection active
+
+## Graduation Report
+
+```
+🎓 Graduation Report
+====================
+
+Phase: SPEC_KIT_READY
+Date: 2025-10-26
+
+Readiness Gates: 7/7 passed (100%)
+  ✅ Structure Gate
+  ✅ Testing Gate
+  ✅ Quality Gate
+  ✅ Security Gate
+  ✅ Build Gate
+  ✅ CI Gate
+  ✅ Documentation Gate
+
+Constitution: .specify/memory/constitution.md
+Spec-Kit: Installed (v1.2.3)
+
+Improvements Achieved:
+  Test Coverage: 45% → 85% (+40%)
+  Complexity Avg: 18.3 → 8.2 (-55%)
+  Critical Vulns: 3 → 0 (-100%)
+  Build Status: failing → passing
+
+Your project is now Spec-Kit ready!
+```
+
+## Next Steps
+
+After graduation:
+1. Review the generated constitution
+2. Use `/speckit.specify` to create feature specifications
+3. Monitor for regressions with `/brownkit.monitor`
+4. All new features follow Spec-Kit workflow
+
+## Spec-Kit Workflow
+
+With graduation complete, use Spec-Kit for new development:
+
+```
+/speckit.specify → /speckit.clarify → /speckit.plan → /speckit.implement
+```
+
+The constitution ensures all new code maintains quality standards.
+
+## Technical Details
+
+- **Command**: `brownfield graduate` (CLI) or orchestrator
+- **Input**: Validation results + graduation metrics
+- **Output**: `.specify/memory/constitution.md`
+- **Prerequisites**: All 7 readiness gates passed
+- **Duration**: 1-2 minutes
+
+## Error Handling
+
+If graduation fails:
+
+### Not All Gates Passed:
+- Review which gates failed
+- Return to `/brownkit.validate` to see detailed report
+- Address remaining issues via remediation
+- Validate again before graduating
+
+### Spec-Kit Not Installed:
+- Install Spec-Kit following documentation
+- Ensure `.claude/commands/speckit.specify.md` exists
+- Re-run graduation
+
+### Constitution Already Exists:
+- BrownKit will offer to backup existing constitution
+- Confirm overwrite or cancel
+- Review backup before proceeding
+
+## Post-Graduation Monitoring
+
+After graduation, BrownKit enters monitoring mode:
+- **Regression detection**: Tracks metrics against baseline
+- **Alert thresholds**: Warns when metrics degrade
+- **Re-entry triggers**: Critical regressions trigger workflow re-entry
+- **Use `/brownkit.monitor`** to check post-graduation health
+
+---
+
+**Note**: Graduation is the final step of BrownKit workflow. Once graduated, the project uses Spec-Kit for all new features while BrownKit monitors for quality regressions.