create-qa-architect 5.0.0

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.github/CLAUDE_MD_AUTOMATION.md

@@ -0,0 +1,248 @@
+# CLAUDE.md Maintenance Automation
+
+This document describes the automated CLAUDE.md validation and maintenance system implemented for this project.
+
+## Overview
+
+The CLAUDE.md file is critical for Claude Code's understanding of project context, commands, and conventions. To ensure it stays current and accurate, we've implemented a multi-layered automation system that validates CLAUDE.md consistency across multiple checkpoints.
+
+## Components
+
+### 1. Validation Script
+
+**Location**: `scripts/validate-claude-md.js`
+
+**Purpose**: Core validation logic that checks CLAUDE.md for:
+
+- Required sections (Project Information, Commands, Features, etc.)
+- Package name and CLI command references
+- Script documentation completeness
+- Outdated patterns (old version references)
+- Node.js version alignment with package.json
+
+**Usage**:
+
+```bash
+npm run validate:claude
+# or directly:
+node scripts/validate-claude-md.js
+```
+
+### 2. GitHub Actions Workflow
+
+**Location**: `.github/workflows/claude-md-validation.yml`
+
+**Triggers**:
+
+- Push to main/master/develop branches
+- Pull requests to main/master/develop branches
+- Changes to CLAUDE.md, package.json, or validation scripts
+- Manual workflow dispatch
+
+**Checks**:
+
+- ✅ Structure and required sections
+- ✅ Package references accuracy
+- ✅ Script documentation
+- ✅ Prettier formatting
+- ✅ No TODO markers
+- ✅ Cross-validation with package.json
+
+**View**: [GitHub Actions](../../actions/workflows/claude-md-validation.yml)
+
+### 3. Pre-commit Hook
+
+**Location**: `package.json` (lint-staged configuration)
+
+**Behavior**: When CLAUDE.md is staged for commit:
+
+1. Runs validation script to check consistency
+2. Runs Prettier to ensure proper formatting
+3. Blocks commit if validation fails
+
+**Configuration**:
+
+```json
+"lint-staged": {
+  "CLAUDE.md": [
+    "node scripts/validate-claude-md.js",
+    "prettier --write"
+  ]
+}
+```
+
+### 4. Integration with Quality Checks
+
+**Location**: `package.json` scripts
+
+**Integration Points**:
+
+- `npm run validate:claude` - Manual validation
+- `npm run validate:all` - Includes CLAUDE.md in comprehensive validation
+- Pre-commit hooks via Husky + lint-staged
+
+## Validation Rules
+
+### Required Sections
+
+The following sections MUST be present in CLAUDE.md:
+
+1. **Project Information** - Package name, CLI command, purpose
+2. **Project-Specific Commands** - npm scripts for linting, formatting, etc.
+3. **Development Workflow** - Setup, prepare, and development commands
+4. **Quality Automation Features** - ESLint, Prettier, Stylelint, Husky, etc.
+5. **Development Notes** - Important context for development
+
+### Package Reference Checks
+
+- ✅ Package name from package.json mentioned
+- ✅ CLI command (if exists) documented
+- ✅ Critical npm scripts documented (lint, format, test, setup)
+
+### Pattern Detection
+
+Outdated patterns that trigger warnings:
+
+- ❌ References to ESLint 8 (should be ESLint 9)
+- ❌ References to Husky 8 (should be Husky 9)
+- ❌ Outdated Node.js version formats
+- ❌ TODO/FIXME markers
+
+## Workflow
+
+### Development Workflow
+
+```mermaid
+graph LR
+    A[Edit CLAUDE.md] --> B[Stage Changes]
+    B --> C[Pre-commit Hook]
+    C --> D{Validation}
+    D -->|Pass| E[Commit]
+    D -->|Fail| F[Fix Issues]
+    F --> A
+    E --> G[Push]
+    G --> H[GitHub Actions]
+    H --> I{CI Validation}
+    I -->|Pass| J[Merge]
+    I -->|Fail| K[Review & Fix]
+    K --> A
+```
+
+### Manual Validation
+
+For manual checks or CI integration:
+
+```bash
+# Validate CLAUDE.md only
+npm run validate:claude
+
+# Comprehensive validation (includes CLAUDE.md)
+npm run validate:all
+
+# Pre-release validation (includes everything)
+npm run prerelease
+```
+
+## Maintenance
+
+### When to Update CLAUDE.md
+
+Update CLAUDE.md whenever:
+
+1. **Package metadata changes**: Name, version, CLI command
+2. **New npm scripts added**: Especially critical workflows
+3. **Dependencies upgraded**: ESLint, Husky, Node.js versions
+4. **Project structure changes**: New directories, workflows
+5. **Development practices change**: New conventions, patterns
+
+### Keeping Validation Current
+
+The validation script should be updated when:
+
+1. **New required sections identified**: Add to `REQUIRED_SECTIONS`
+2. **New outdated patterns emerge**: Add to `OUTDATED_PATTERNS`
+3. **New critical scripts**: Add to `criticalScripts` array
+4. **Validation rules evolve**: Update check functions
+
+### Best Practices
+
+1. **Always validate before committing**: Let pre-commit hooks catch issues
+2. **Review warnings**: Even non-blocking warnings indicate maintenance needs
+3. **Keep sections updated**: Don't let documentation drift from reality
+4. **Remove TODO markers**: Resolve them before committing
+5. **Test after package.json changes**: Ensure references stay accurate
+
+## Troubleshooting
+
+### Validation Fails on Commit
+
+```bash
+# See what failed
+npm run validate:claude
+
+# Common issues:
+# 1. Missing sections - Add required sections to CLAUDE.md
+# 2. Package name mismatch - Update references in CLAUDE.md
+# 3. TODO markers - Resolve or remove TODOs
+# 4. Formatting - Run: prettier --write CLAUDE.md
+```
+
+### GitHub Actions Failing
+
+1. Check workflow runs in Actions tab
+2. Review validation errors in job logs
+3. Fix locally and test with `npm run validate:claude`
+4. Commit and push fixes
+
+### Pre-commit Hook Not Running
+
+```bash
+# Reinstall Husky hooks
+npm run prepare
+
+# Verify hook exists
+ls -la .husky/pre-commit
+
+# Test lint-staged
+npx lint-staged
+```
+
+## Implementation Checklist
+
+When setting up this automation in a new project:
+
+- [ ] Copy `scripts/validate-claude-md.js`
+- [ ] Copy `.github/workflows/claude-md-validation.yml`
+- [ ] Add `validate:claude` script to package.json
+- [ ] Add CLAUDE.md to lint-staged configuration
+- [ ] Update `validate:all` to include `validate:claude`
+- [ ] Test locally: `npm run validate:claude`
+- [ ] Test pre-commit: Stage CLAUDE.md and commit
+- [ ] Verify GitHub Actions runs on push
+
+## Future Enhancements
+
+Potential improvements to consider:
+
+1. **Auto-fixing**: Automatically update some references from package.json
+2. **Version sync**: Auto-update version references when package.json changes
+3. **Link checking**: Validate internal and external links
+4. **Schema validation**: JSON Schema for CLAUDE.md structure
+5. **Diff analysis**: Suggest updates based on package.json changes
+6. **Integration tests**: Ensure CLAUDE.md matches actual project state
+
+## Related Documentation
+
+- [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) - Pre-release validation steps
+- [Quality Workflow](.github/workflows/quality.yml) - General quality checks
+- [Main CLAUDE.md](../../CLAUDE.md) - The file being validated
+
+## Support
+
+For issues or questions about CLAUDE.md automation:
+
+1. Check validation output for specific errors
+2. Review this documentation
+3. Test with `npm run validate:claude`
+4. Check GitHub Actions logs
+5. Open an issue if automation has bugs

package/.github/PROGRESSIVE_QUALITY_IMPLEMENTATION.md

@@ -0,0 +1,408 @@
+# Progressive Quality Automation - Implementation Summary
+
+## Overview
+
+This implementation provides **adaptive quality checks** that automatically adjust based on project maturity, eliminating false failures in early-stage projects while maintaining strict quality standards for production-ready code.
+
+## What Was Delivered
+
+### 1. Project Maturity Detector (`lib/project-maturity.js`)
+
+A comprehensive Node.js module that analyzes your project and determines its maturity level.
+
+**Features:**
+
+- Counts source files, test files, and CSS files
+- Detects documentation presence
+- Checks for dependencies
+- Assigns maturity level: minimal → bootstrap → development → production-ready
+- Outputs GitHub Actions-compatible format
+- Provides human-readable reports
+
+**Usage:**
+
+```bash
+# Human-readable report
+node lib/project-maturity.js
+
+# Verbose output with analysis details
+node lib/project-maturity.js --verbose
+
+# GitHub Actions output format
+node lib/project-maturity.js --github-actions
+```
+
+**Example Output:**
+
+```
+📊 Project Maturity Report
+
+Maturity Level: Production Ready
+Description: Mature project - full quality automation
+
+Project Statistics:
+  • Source files: 23
+  • Test files: 29
+  • Documentation: Yes
+  • Dependencies: Yes
+  • CSS files: No
+
+Quality Checks:
+  ✅ Required: prettier, eslint, stylelint, tests, coverage, security-audit, documentation
+  🔵 Optional: lighthouse
+
+✅ Production-ready project - all quality checks enabled.
+```
+
+### 2. Progressive Workflow Example (`.github/workflows/quality-progressive.yml.example`)
+
+A complete GitHub Actions workflow that demonstrates adaptive quality checks.
+
+**Key Features:**
+
+- **Maturity Detection Job**: Analyzes project and sets outputs for conditional checks
+- **Core Checks**: Always run (Prettier) - even for minimal projects
+- **Conditional Linting**: Only runs if source files exist
+- **Conditional Security**: Only runs if dependencies exist
+- **Conditional Tests**: Only runs if test files exist
+- **Conditional Documentation**: Only runs for production-ready projects
+- **Summary Job**: Reports what checks ran and why
+
+**How It Works:**
+
+```yaml
+# Step 1: Detect maturity
+detect-maturity:
+  outputs:
+    maturity: production-ready
+    source-count: 23
+    test-count: 29
+    has-deps: true
+
+# Step 2: Conditional checks
+linting:
+  if: needs.detect-maturity.outputs.source-count > 0
+  # Only runs if source files exist ✅
+
+tests:
+  if: needs.detect-maturity.outputs.test-count > 0
+  # Only runs if test files exist ✅
+```
+
+### 3. Configuration Schema (`.qualityrc.json.example`)
+
+A JSON configuration file for manual overrides and progressive enablement tracking.
+
+**Features:**
+
+- `maturity: "auto"` - Auto-detect (default)
+- `maturity: "production-ready"` - Force all checks
+- `maturity: "minimal"` - Force minimal checks only
+- Per-check `enabled: "auto"` - Auto-enable based on project state
+- Per-check `required: true/false` - Mark as blocking or non-blocking
+
+**Example Use Cases:**
+
+```json
+{
+  "maturity": "auto",
+  "checks": {
+    "prettier": { "enabled": true, "required": true },
+    "eslint": { "enabled": "auto", "required": false },
+    "coverage": { "enabled": false, "threshold": 80 }
+  }
+}
+```
+
+### 4. Design Proposal (`.github/PROGRESSIVE_QUALITY_PROPOSAL.md`)
+
+A comprehensive 200+ line design document explaining:
+
+- Problem statement and user pain points
+- 4 different solution strategies
+- Maturity level definitions
+- Implementation approach
+- Benefits and trade-offs
+- Alternative approaches considered
+- Open questions for feedback
+
+## Maturity Levels Explained
+
+### Minimal (0 source files)
+
+**What it means:** Project just created, only package.json exists
+
+**Checks enabled:**
+
+- ✅ Prettier (basic formatting)
+
+**Checks disabled:**
+
+- ⏭️ ESLint, Stylelint, Tests, Security, Documentation
+
+**User experience:**
+
+```
+⚡ Minimal project - only basic formatting checks enabled.
+   Add source files to enable linting.
+```
+
+### Bootstrap (1-2 source files, no tests)
+
+**What it means:** Early development, writing first components
+
+**Checks enabled:**
+
+- ✅ Prettier
+- ✅ ESLint
+
+**Checks disabled:**
+
+- ⏭️ Tests, Coverage, Security (optional), Documentation
+
+**User experience:**
+
+```
+🚀 Bootstrap project - linting enabled.
+   Add tests to enable test coverage checks.
+```
+
+### Development (3+ source files, has tests)
+
+**What it means:** Active development with test infrastructure
+
+**Checks enabled:**
+
+- ✅ Prettier
+- ✅ ESLint
+- ✅ Stylelint (if CSS files exist)
+- ✅ Tests
+- 🔵 Security audit (optional)
+- 🔵 Coverage (optional)
+
+**Checks disabled:**
+
+- ⏭️ Documentation validation
+
+**User experience:**
+
+```
+🔨 Development project - most checks enabled.
+   Add documentation to enable doc validation.
+```
+
+### Production-Ready (10+ source files, 3+ tests, has docs)
+
+**What it means:** Mature project ready for production
+
+**Checks enabled:**
+
+- ✅ All checks enabled
+- ✅ Documentation validation
+- ✅ Security audits
+- ✅ Coverage requirements
+- 🔵 Lighthouse CI (if configured)
+
+**User experience:**
+
+```
+✅ Production-ready project - all quality checks enabled.
+```
+
+## Integration Guide
+
+### Option 1: Test the Maturity Detector Now
+
+```bash
+# Run on this project
+cd /home/user/create-qa-architect
+node lib/project-maturity.js --verbose
+```
+
+### Option 2: Use the Example Workflow
+
+```bash
+# Copy the example workflow
+cp .github/workflows/quality-progressive.yml.example \
+   .github/workflows/quality-progressive.yml
+
+# Test it locally (requires act or push to GitHub)
+git add .
+git commit -m "feat: add progressive quality automation"
+git push
+```
+
+### Option 3: Integrate Into Existing Workflow
+
+Replace your current `quality.yml` with the progressive version:
+
+```diff
+- name: ESLint
+-   run: npx eslint . --max-warnings=0
++ name: ESLint
++   if: needs.detect-maturity.outputs.source-count > 0
++   run: |
++     echo "🔍 Linting ${{ needs.detect-maturity.outputs.source-count }} source files..."
++     npx eslint . --max-warnings=0
+```
+
+## Testing Scenarios
+
+### Scenario 1: Brand New Project
+
+```bash
+mkdir new-project && cd new-project
+git init
+echo '{"name":"new-project","version":"1.0.0"}' > package.json
+
+# Run maturity detector
+node /path/to/lib/project-maturity.js
+# Output: "Minimal" - only Prettier runs ✅
+```
+
+### Scenario 2: First Source File Added
+
+```bash
+echo 'console.log("hello")' > index.js
+
+# Run maturity detector
+node /path/to/lib/project-maturity.js
+# Output: "Bootstrap" - ESLint now enabled ✅
+```
+
+### Scenario 3: Tests Added
+
+```bash
+mkdir __tests__
+echo 'test("example", () => {})' > __tests__/index.test.js
+
+# Run maturity detector
+node /path/to/lib/project-maturity.js
+# Output: "Development" - Test checks now enabled ✅
+```
+
+### Scenario 4: Production Ready
+
+```bash
+# Add 10+ source files, 3+ tests, documentation
+# ...
+
+node /path/to/lib/project-maturity.js
+# Output: "Production Ready" - All checks enabled ✅
+```
+
+## Benefits Summary
+
+### For New Projects ✨
+
+- ✅ **No false failures** - CI stays green during early development
+- ✅ **Clear progression** - See which checks activate as you add files
+- ✅ **Reduced noise** - Only see failures that matter for your project stage
+
+### For Existing Projects 🔄
+
+- ✅ **Backward compatible** - Auto-detection means no config changes needed
+- ✅ **Opt-in strictness** - Can force `production-ready` mode in config
+- ✅ **Gradual adoption** - Enable checks one at a time
+
+### For Maintainers 🛠️
+
+- ✅ **Better UX** - Reduces confusion and support requests
+- ✅ **Professional polish** - Shows thoughtful design
+- ✅ **Competitive advantage** - Most quality tools don't have this
+
+## Next Steps
+
+### Immediate (Ready to Use)
+
+1. **Test the detector:**
+
+   ```bash
+   node lib/project-maturity.js --verbose
+   ```
+
+2. **Review the proposal:**
+   - Read `.github/PROGRESSIVE_QUALITY_PROPOSAL.md`
+   - Provide feedback on the approach
+
+3. **Test the example workflow:**
+   - Copy `quality-progressive.yml.example` to test
+
+### Short Term (Implementation)
+
+4. **Integrate into setup.js:**
+   - Add `--check-maturity` CLI flag
+   - Auto-generate `.qualityrc.json` during setup
+   - Update workflow templates
+
+5. **Update documentation:**
+   - Add PROGRESSIVE_QUALITY.md user guide
+   - Update README with new feature
+   - Update CLAUDE.md with new commands
+
+6. **Add tests:**
+   - Unit tests for maturity detector
+   - Integration tests for each maturity level
+   - Test fixtures for all scenarios
+
+### Medium Term (Polish)
+
+7. **Add configuration support:**
+   - Read `.qualityrc.json` in maturity detector
+   - Support manual overrides
+   - Add validation for config file
+
+8. **Enhance GitHub Actions integration:**
+   - Add PR check summaries with maturity level
+   - Add maturity badges
+   - Add upgrade suggestions in PR comments
+
+9. **Community feedback:**
+   - Share with early adopters
+   - Gather feedback on maturity thresholds
+   - Iterate on auto-detection rules
+
+## Files Delivered
+
+```
+.github/
+├── PROGRESSIVE_QUALITY_PROPOSAL.md         # Full design proposal
+├── PROGRESSIVE_QUALITY_IMPLEMENTATION.md   # This file
+└── workflows/
+    └── quality-progressive.yml.example     # Example workflow
+
+lib/
+└── project-maturity.js                     # Maturity detector (working code)
+
+.qualityrc.json.example                     # Configuration schema
+```
+
+## Questions & Feedback
+
+This is a **working prototype** ready for testing and feedback. Key questions:
+
+1. **Are the maturity thresholds right?**
+   - Minimal: 0 source files
+   - Bootstrap: 1-2 source files
+   - Development: 3+ source files + tests
+   - Production-ready: 10+ source files + 3+ tests + docs
+
+2. **Should we add more maturity levels?**
+   - E.g., "alpha", "beta", "stable"?
+
+3. **Should checks be opt-in or opt-out by default?**
+   - Current: Auto-enable based on detection
+   - Alternative: Require manual enablement
+
+4. **What other project characteristics should we detect?**
+   - Framework (React, Vue, Angular)?
+   - Package manager (npm, yarn, pnpm)?
+   - Monorepo vs single package?
+
+5. **Should we integrate with existing tools?**
+   - Conventional commits for maturity detection?
+   - Semantic versioning (0.x = beta, 1.x = stable)?
+
+---
+
+**Ready to test?** Run `node lib/project-maturity.js --verbose` to see it in action! 🚀