claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-core/rules/definition-of-done.md

@@ -0,0 +1,272 @@
+# 🎯 Definition of Done (DoD)
+
+> **A feature is not DONE until ALL criteria are met. No exceptions.**
+
+## Universal DoD Checklist
+
+A feature/task is **DONE** when:
+
+### ✅ Code Quality
+
+- [ ] Code complete and follows all coding standards
+- [ ] No commented-out code or debug statements
+- [ ] No hardcoded values (use config/env variables)
+- [ ] DRY principle applied (no duplication)
+- [ ] SOLID principles followed
+- [ ] Error handling implemented
+- [ ] Logging added for debugging
+
+### 🧪 Testing
+
+- [ ] Unit tests written and passing (>80% coverage)
+- [ ] Integration tests written and passing
+- [ ] E2E tests for critical paths
+- [ ] Visual regression tests passing (UI changes)
+- [ ] Performance tests passing
+- [ ] Security tests passing
+- [ ] All tests run in CI/CD
+
+### 🎨 UI/UX (if applicable)
+
+- [ ] Responsive design verified (mobile, tablet, desktop)
+- [ ] Cross-browser testing completed
+- [ ] Dark mode supported (if applicable)
+- [ ] Loading states implemented
+- [ ] Error states handled
+- [ ] Empty states designed
+- [ ] Animations smooth (<60fps)
+- [ ] Screenshots captured for documentation
+
+### ♿ Accessibility
+
+- [ ] WCAG 2.1 AA compliance verified
+- [ ] Keyboard navigation functional
+- [ ] Screen reader tested
+- [ ] Color contrast ratios met
+- [ ] ARIA labels appropriate
+- [ ] Focus indicators visible
+- [ ] Alt text for images
+
+### 🔒 Security
+
+- [ ] Security scan completed (no critical/high vulnerabilities)
+- [ ] Input validation implemented
+- [ ] SQL injection prevention verified
+- [ ] XSS protection in place
+- [ ] Authentication/authorization correct
+- [ ] Sensitive data encrypted
+- [ ] No secrets in code
+
+### ⚡ Performance
+
+- [ ] Performance requirements met
+- [ ] Database queries optimized
+- [ ] Caching implemented where appropriate
+- [ ] Bundle size within limits
+- [ ] Memory leaks checked
+- [ ] Load testing passed (if applicable)
+
+### 📝 Documentation
+
+- [ ] Code comments added where necessary
+- [ ] README updated (if needed)
+- [ ] API documentation updated
+- [ ] CHANGELOG updated
+- [ ] Architecture docs updated (if applicable)
+- [ ] User documentation created (if needed)
+- [ ] Inline JSDoc/docstrings complete
+
+### 👥 Review & Collaboration
+
+- [ ] Code reviewed and approved by peer
+- [ ] Design reviewed (for UI changes)
+- [ ] Product owner acceptance (if applicable)
+- [ ] No unresolved comments in PR
+- [ ] Branch conflicts resolved
+- [ ] Commit messages follow convention
+
+### 🚀 Deployment Readiness
+
+- [ ] CI/CD pipeline passing (all checks green)
+- [ ] Feature flags configured (if applicable)
+- [ ] Database migrations ready and tested
+- [ ] Rollback plan documented
+- [ ] Monitoring/alerts configured
+- [ ] Deployment notes written
+
+### 🛠️ Technical Debt
+
+- [ ] No new technical debt introduced
+- [ ] Existing debt not increased
+- [ ] Refactoring opportunities documented
+- [ ] TODO comments have associated tickets
+
+## DoD by Feature Type
+
+### API Endpoint
+
+```markdown
+- [ ] OpenAPI/Swagger spec updated
+- [ ] Request validation implemented
+- [ ] Response format consistent
+- [ ] Rate limiting configured
+- [ ] Authentication required (if needed)
+- [ ] Integration tests for all methods
+- [ ] Error responses documented
+- [ ] Performance < 200ms
+```
+
+### Database Change
+
+```markdown
+- [ ] Migration script created
+- [ ] Rollback script created
+- [ ] Migration tested on staging
+- [ ] Indexes optimized
+- [ ] Constraints defined
+- [ ] Backup plan documented
+- [ ] Data integrity verified
+```
+
+### UI Component
+
+```markdown
+- [ ] Storybook story created
+- [ ] Props documented with types
+- [ ] Default props defined
+- [ ] Error boundaries implemented
+- [ ] Accessibility audit passed
+- [ ] Visual regression tests
+- [ ] Theme variables used
+- [ ] RTL support (if required)
+```
+
+### Bug Fix
+
+```markdown
+- [ ] Root cause identified
+- [ ] Regression test written
+- [ ] Fix verified in multiple scenarios
+- [ ] Related code reviewed
+- [ ] No side effects introduced
+- [ ] Performance not degraded
+```
+
+### Infrastructure Change
+
+```markdown
+- [ ] Terraform/IaC updated
+- [ ] Change tested in staging
+- [ ] Rollback procedure documented
+- [ ] Cost impact assessed
+- [ ] Security review completed
+- [ ] Monitoring updated
+- [ ] Runbook updated
+```
+
+## DoD Verification Process
+
+### Self-Check (Developer)
+
+1. Review entire DoD checklist
+2. Mark completed items
+3. Document any exceptions with justification
+4. Attach evidence (screenshots, test results)
+
+### Peer Review
+
+1. Verify developer's checklist
+2. Spot-check critical items
+3. Run tests locally
+4. Review documentation updates
+
+### Automated Verification
+
+```yaml
+# CI/CD Pipeline Checks
+- Linting and formatting
+- Unit test coverage
+- Integration tests
+- Security scanning
+- Performance benchmarks
+- Build success
+- Docker image scan
+```
+
+### Final Verification (Team Lead/PO)
+
+1. Acceptance criteria met
+2. Business value delivered
+3. No blockers for deployment
+4. Stakeholder sign-off (if needed)
+
+## Exceptions Process
+
+### When Exceptions Are Allowed
+
+- Emergency hotfixes (document debt)
+- Proof of concepts (marked clearly)
+- Experimental features (behind flags)
+
+### Exception Requirements
+
+1. Document reason for exception
+2. Create follow-up ticket for completion
+3. Get approval from team lead
+4. Set deadline for resolution
+5. Track in technical debt log
+
+## DoD Evolution
+
+### Quarterly Review
+
+- Review DoD effectiveness
+- Add new criteria based on incidents
+- Remove outdated criteria
+- Adjust based on team feedback
+
+### Continuous Improvement
+
+- Track DoD violations and patterns
+- Automate more checks
+- Simplify where possible
+- Share learnings across teams
+
+## Quick Reference Card
+
+```bash
+# Minimum DoD (cannot skip)
+✓ Tests written and passing
+✓ Code reviewed
+✓ Documentation updated
+✓ Security scan clean
+✓ CI/CD passing
+
+# Additional for UI
++ Responsive design
++ Accessibility verified
++ Visual tests passing
+
+# Additional for API
++ API docs updated
++ Integration tests
++ Performance verified
+
+# Additional for Database
++ Migration tested
++ Rollback ready
++ Backup verified
+```
+
+## Remember
+
+**"Done" means DONE—not "mostly done" or "done except for..."**
+
+The Definition of Done protects:
+
+- **Users** from broken features
+- **Team** from technical debt
+- **Product** from quality issues
+- **Company** from reputation damage
+
+**Quality is not negotiable. Done is not debatable.**

package/packages/plugin-core/rules/development-environments.md

@@ -0,0 +1,19 @@
+# Rule: Development Environments & Workflow
+
+This document defines the two primary development environments for this project.
+
+## 1. Local Development Environment (Docker-First)
+
+The local development workflow MUST remain pure `docker-compose`. This ensures zero disruption for developers and maintains a fast, familiar iteration cycle.
+
+- **Tooling**: `docker compose up`, `docker build`, `docker run`.
+- **Configuration**: `docker-compose.yml` and `docker-compose.dev.yml`.
+- **Philosophy**: Developers should not need to learn `kubectl` or Kubernetes for local work. The experience is seamless and unchanged.
+
+## 2. CI/CD Environment (Kubernetes-Native)
+
+All automated testing and continuous integration processes run directly on our Kubernetes cluster which uses `containerd`. The Docker daemon is NOT available on these runners.
+
+- **Tooling**: `kubectl`, `nerdctl` (for building Dockerfiles).
+- **Philosophy**: CI/CD pipelines MUST mirror the production environment as closely as possible. We build and test in the same way we deploy.
+- **Artifacts**: The `Dockerfiles` from the repository are the source of truth and are used by `nerdctl` to build images within the CI/CD pipeline.

package/packages/plugin-core/rules/development-workflow.md

@@ -0,0 +1,198 @@
+# Development Workflow Standards
+
+> **CRITICAL**: Systematic approach to every development task.
+
+## Before ANY Implementation
+
+### Required Preparation
+
+1. Check existing codebase for similar functions
+2. Read naming conventions from existing code
+3. Understand current architecture patterns
+4. Plan test cases first
+5. Identify which agents to use
+
+### Codebase Analysis
+
+- Search for existing implementations
+- Verify no duplication will occur
+- Understand dependencies
+- Check for related tests
+- Review error handling patterns
+
+## During Implementation
+
+### Mandatory Practices
+
+1. Follow TDD cycle religiously
+2. Use appropriate agents for context management
+3. Never bypass agent pipelines
+4. Maintain consistent naming
+5. Write verbose tests for debugging
+
+### Quality Checkpoints
+
+- After each test: Verify it fails correctly
+- After each implementation: Verify minimal code
+- After each refactor: Verify tests still pass
+- Before commit: Run full test suite
+
+## After Implementation
+
+### Required Verification
+
+1. Run full test suite via test-runner
+2. Use code-analyzer for final review
+3. Update documentation ONLY if requested
+4. Document patterns in CLAUDE.md if new
+5. Verify no resource leaks
+
+### Cleanup Tasks
+
+- Remove any debug code
+- Clean up test artifacts
+- Close any open resources
+- Update status tracking
+- Clear any temporary files
+
+## Development Patterns
+
+### Search Before Create
+
+```
+ALWAYS:
+1. Search for existing function
+2. Check for similar patterns
+3. Verify not duplicating
+4. Only then create new
+
+NEVER:
+- Assume function doesn't exist
+- Create without searching
+- Duplicate existing logic
+```
+
+### Test Before Code
+
+```
+ALWAYS:
+1. Write failing test first
+2. Run test to see failure
+3. Write minimal code
+4. Verify test passes
+5. Refactor if needed
+
+NEVER:
+- Write code without test
+- Skip test execution
+- Write complex code first
+- Assume test will pass
+```
+
+### Agent Before Direct
+
+```
+ALWAYS:
+1. Use file-analyzer for file reads
+2. Use code-analyzer for searches
+3. Use test-runner for tests
+4. Use parallel-worker for multi-file
+
+NEVER:
+- Use grep directly
+- Use cat/head/tail directly
+- Run tests manually
+- Process files sequentially
+```
+
+## Error Handling Patterns
+
+### When Error Occurs
+
+1. Stop immediately
+2. Activate ERROR HANDLING PIPELINE
+3. Write test to reproduce
+4. Fix with minimal change
+5. Verify all tests pass
+6. Document error pattern
+
+### Prevention Strategy
+
+- Defensive coding
+- Input validation
+- Resource cleanup
+- Error propagation
+- Graceful degradation
+
+## Performance Considerations
+
+### Optimization Rules
+
+- Profile before optimizing
+- Optimize algorithms first
+- Then optimize implementation
+- Cache expensive operations
+- Batch similar operations
+
+### Anti-Patterns
+
+- ❌ Premature optimization
+- ❌ Micro-optimizations
+- ❌ Ignoring algorithmic complexity
+- ❌ Not measuring impact
+
+## Continuous Improvement
+
+### Learn From Each Task
+
+1. Document new patterns discovered
+2. Update CLAUDE.md with learnings
+3. Create new agent if pattern repeats
+4. Improve pipeline efficiency
+5. Share knowledge in rules
+
+### Metrics to Track
+
+- Test coverage percentage
+- Agent utilization rate
+- Context efficiency ratio
+- Pipeline completion rate
+- Error frequency trends
+
+## Success Indicators
+
+### Task Completion
+
+- ✅ All tests passing
+- ✅ No code duplication
+- ✅ Consistent naming
+- ✅ Proper error handling
+- ✅ Resources cleaned up
+- ✅ Documentation current
+- ✅ Patterns documented
+
+### Quality Markers
+
+- ✅ TDD cycle followed
+- ✅ Agents used appropriately
+- ✅ Context optimized
+- ✅ Pipelines completed
+- ✅ No technical debt
+
+## Enforcement
+
+### Violation Response
+
+1. Stop current approach
+2. Identify violation type
+3. Correct using proper workflow
+4. Document lesson learned
+5. Update relevant rules
+
+### Prevention Focus
+
+- Checklists before starting
+- Agent delegation habits
+- TDD discipline
+- Regular rule review
+- Continuous learning

package/packages/plugin-core/rules/framework-path-rules.md

@@ -0,0 +1,180 @@
+# Framework Path Rules
+
+## Critical Path Convention
+
+**NEVER** hardcode the `autopm/` directory path in framework files. The `autopm/` directory only exists during development and is **NOT** present after installation in user projects.
+
+## The Problem
+
+During installation, files from `autopm/.claude/` are copied to user projects as `.claude/`. Any references to `autopm/.claude/` or `autopm/scripts/` will be broken after installation.
+
+```
+❌ WRONG (Development structure):
+autopm/
+├── .claude/
+│   ├── commands/
+│   ├── scripts/
+│   └── agents/
+
+✅ CORRECT (After installation):
+user-project/
+├── .claude/
+│   ├── commands/
+│   ├── scripts/
+│   └── agents/
+```
+
+## Rules
+
+### 1. Use Relative Paths from Project Root
+
+All paths in framework files must be relative to the **user's project root** (where `.claude/` will exist after installation).
+
+**✅ CORRECT:**
+```bash
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+node .claude/lib/commands/pm/prdStatus.js
+source .claude/scripts/lib/github-utils.sh
+```
+
+**❌ WRONG:**
+```bash
+bash autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+node autopm/.claude/lib/commands/pm/prdStatus.js
+source autopm/.claude/scripts/lib/github-utils.sh
+```
+
+### 2. Exception: Comments and Documentation References
+
+It's acceptable to reference `autopm/` in:
+- Code comments explaining migration history
+- Documentation describing the development structure
+- Git commit messages
+
+**✅ ACCEPTABLE:**
+```javascript
+/**
+ * Migrated from autopm/.claude/scripts/azure/validate.sh to Node.js
+ */
+```
+
+**✅ ACCEPTABLE:**
+```markdown
+## Development Structure
+During development, framework files are in `autopm/.claude/`, but after
+installation they are copied to the user project's `.claude/` directory.
+```
+
+### 3. Files That Must Follow These Rules
+
+- **Commands** (`autopm/.claude/commands/**/*.md`)
+- **Scripts** (`autopm/.claude/scripts/**/*.sh`, `**/*.js`)
+- **Agents** (`autopm/.claude/agents/**/*.md`)
+- **Rules** (`autopm/.claude/rules/**/*.md`)
+- **Templates** (`autopm/.claude/templates/**/*`)
+
+### 4. Environment Variables
+
+If you need to reference the framework location dynamically, use environment variables that work in both contexts:
+
+**✅ CORRECT:**
+```bash
+CLAUDE_DIR="${CLAUDE_DIR:-.claude}"
+bash "${CLAUDE_DIR}/scripts/pm/epic-sync/create-epic-issue.sh"
+```
+
+This allows:
+- Development: `CLAUDE_DIR=autopm/.claude`
+- Production: `CLAUDE_DIR=.claude` (default)
+
+## Validation
+
+### Pre-Commit Hook
+
+A pre-commit hook validates all framework files before commit:
+
+```bash
+# Checks for hardcoded autopm/ paths (excluding comments)
+grep -r "bash autopm" autopm/.claude --include="*.md" --include="*.sh"
+grep -r "node autopm" autopm/.claude --include="*.md" --include="*.sh"
+grep -r "source autopm" autopm/.claude --include="*.md" --include="*.sh"
+```
+
+### Manual Check
+
+Before committing changes to framework files:
+
+```bash
+# Run validation
+npm run validate:paths
+
+# Or manually
+./scripts/validate-framework-paths.sh
+```
+
+## Common Mistakes
+
+### Mistake 1: Copy-Paste from Development Environment
+
+```bash
+# ❌ Copying terminal command that worked in development
+bash autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh "feature-name"
+
+# ✅ Use project-relative path
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "feature-name"
+```
+
+### Mistake 2: Documentation Examples
+
+```markdown
+❌ WRONG:
+To run the script:
+`bash autopm/.claude/scripts/pm/issue-sync/preflight-validation.sh`
+
+✅ CORRECT:
+To run the script:
+`bash .claude/scripts/pm/issue-sync/preflight-validation.sh`
+```
+
+### Mistake 3: Relative Imports in Scripts
+
+```bash
+# ❌ WRONG - hardcoded framework path
+source autopm/.claude/scripts/lib/github-utils.sh
+
+# ✅ CORRECT - relative to project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../lib/github-utils.sh"
+
+# ✅ ALSO CORRECT - explicit project root
+source .claude/scripts/lib/github-utils.sh
+```
+
+## Enforcement
+
+This rule is enforced by:
+
+1. **Pre-commit hook** - Blocks commits with hardcoded `autopm/` paths
+2. **CI/CD validation** - GitHub Actions check on every PR
+3. **Installation tests** - Verify all paths work post-installation
+4. **Code review** - Reviewers check for path correctness
+
+## Quick Reference
+
+| Context | Use | Don't Use |
+|---------|-----|-----------|
+| Shell scripts | `.claude/scripts/` | `autopm/.claude/scripts/` |
+| Node.js scripts | `.claude/lib/` | `autopm/.claude/lib/` |
+| Command files | `.claude/commands/` | `autopm/.claude/commands/` |
+| Documentation | `.claude/agents/` | `autopm/.claude/agents/` |
+| Comments | `autopm/` ✅ OK | N/A |
+
+## Related Rules
+
+- `/rules/naming-conventions.md` - File and directory naming
+- `/rules/development-workflow.md` - Development best practices
+- `/rules/golden-rules.md` - Core framework principles
+
+---
+
+**Remember:** If a user installs this framework, the `autopm/` directory will not exist in their project. All paths must work from their project root where `.claude/` is located.