claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-core/rules/frontmatter-operations.md

@@ -0,0 +1,64 @@
+# Frontmatter Operations Rule
+
+Standard patterns for working with YAML frontmatter in markdown files.
+
+## Reading Frontmatter
+
+Extract frontmatter from any markdown file:
+
+1. Look for content between `---` markers at start of file
+2. Parse as YAML
+3. If invalid or missing, use sensible defaults
+
+## Updating Frontmatter
+
+When updating existing files:
+
+1. Preserve all existing fields
+2. Only update specified fields
+3. Always update `updated` field with current datetime (see `/rules/datetime.md`)
+
+## Standard Fields
+
+### All Files
+
+```yaml
+---
+name: {identifier}
+created: {ISO datetime}      # Never change after creation
+updated: {ISO datetime}      # Update on any modification
+---
+```
+
+### Status Values
+
+- PRDs: `backlog`, `in-progress`, `complete`
+- Epics: `backlog`, `in-progress`, `completed`  
+- Tasks: `open`, `in-progress`, `closed`
+
+### Progress Tracking
+
+```yaml
+progress: {0-100}%           # For epics
+completion: {0-100}%         # For progress files
+```
+
+## Creating New Files
+
+Always include frontmatter when creating markdown files:
+
+```yaml
+---
+name: {from_arguments_or_context}
+status: {initial_status}
+created: {current_datetime}
+updated: {current_datetime}
+---
+```
+
+## Important Notes
+
+- Never modify `created` field after initial creation
+- Always use real datetime from system (see `/rules/datetime.md`)
+- Validate frontmatter exists before trying to parse
+- Use consistent field names across all files

package/packages/plugin-core/rules/git-strategy.md

@@ -0,0 +1,237 @@
+# Unified Git Strategy for ClaudeAutoPM
+
+This document defines the **SINGLE, AUTHORITATIVE** Git workflow for ClaudeAutoPM projects.
+
+## Core Principle: Branch-Based Development
+
+ClaudeAutoPM uses a **branch-based strategy** for all development work. This ensures simplicity, compatibility, and consistency across all environments and tools.
+
+## Branch Hierarchy
+
+```
+main (or master)
+├── epic/authentication
+├── epic/dashboard
+├── feature/issue-123
+└── hotfix/critical-bug
+```
+
+## Creating Branches
+
+Always create branches from a clean, updated main branch:
+
+```bash
+# Ensure main is up to date
+git checkout main
+git pull origin main
+
+# Create branch for epic
+git checkout -b epic/{epic-name}
+git push -u origin epic/{epic-name}
+
+# Create branch for standalone issue
+git checkout -b feature/issue-{number}
+git push -u origin feature/issue-{number}
+```
+
+## Working in Branches
+
+### Commit Standards
+
+- **Small, focused commits**: Each commit should represent one logical change
+- **Format**: `{type}(scope): {description} #{issue}`
+- **Examples**:
+  - `feat(auth): Add JWT validation #123`
+  - `fix(api): Handle null response #456`
+  - `docs(readme): Update installation steps #789`
+
+### Daily Workflow
+
+```bash
+# Start your day - get latest changes
+git pull origin epic/{name}
+
+# Make changes
+git add {files}
+git commit -m "feat(scope): Description #issue"
+
+# Push changes regularly
+git push origin epic/{name}
+```
+
+### Parallel Agent Work
+
+When multiple agents work on the same epic:
+
+```bash
+# Agent A completes work
+git add src/api/*
+git commit -m "feat(api): Add user endpoints #123"
+git push origin epic/{name}
+
+# Agent B starts work - MUST PULL FIRST
+git pull origin epic/{name}
+git add src/ui/*
+git commit -m "feat(ui): Add dashboard #124"
+git push origin epic/{name}
+```
+
+## Merging Strategy
+
+### Pull Request Workflow
+
+1. **Create PR when epic is ready**:
+   ```bash
+   gh pr create --base main --head epic/{name} \
+     --title "Epic: {name}" \
+     --body "Closes #{epic-issue}"
+   ```
+
+2. **Review and merge via GitHub/Azure DevOps UI**
+
+3. **Clean up after merge**:
+   ```bash
+   git checkout main
+   git pull origin main
+   git branch -d epic/{name}
+   git push origin --delete epic/{name}
+   ```
+
+### Direct Merge (for automated workflows)
+
+```bash
+# Update main
+git checkout main
+git pull origin main
+
+# Merge epic
+git merge --no-ff epic/{name} -m "Merge epic: {name}"
+git push origin main
+
+# Clean up
+git branch -d epic/{name}
+git push origin --delete epic/{name}
+```
+
+## Conflict Resolution
+
+### Prevention is Key
+
+1. **Pull frequently**: Always pull before starting work
+2. **Communicate**: Use issue comments to coordinate file changes
+3. **Small PRs**: Merge often to reduce conflict surface
+
+### When Conflicts Occur
+
+```bash
+# During pull
+git pull origin epic/{name}
+# If conflicts occur, Git will notify you
+
+# View conflicts
+git status
+
+# Resolve conflicts in your editor
+# Then mark as resolved
+git add {resolved-files}
+git commit -m "resolve: Merge conflicts in {files}"
+git push origin epic/{name}
+```
+
+## Branch Management
+
+### Naming Conventions
+
+- **Epics**: `epic/{epic-name}` (e.g., `epic/authentication`)
+- **Features**: `feature/issue-{number}` (e.g., `feature/issue-123`)
+- **Bugs**: `bugfix/issue-{number}` (e.g., `bugfix/issue-456`)
+- **Hotfixes**: `hotfix/{description}` (e.g., `hotfix/security-patch`)
+
+### Housekeeping
+
+```bash
+# List all branches
+git branch -a
+
+# Delete merged branches locally
+git branch --merged | grep -v main | xargs -n 1 git branch -d
+
+# Prune remote tracking branches
+git remote prune origin
+```
+
+## Best Practices
+
+1. **One branch per epic**: Keep epics isolated
+2. **Update before work**: Always pull latest changes
+3. **Commit frequently**: Small commits are easier to review
+4. **Push regularly**: Keep remote in sync
+5. **Clean up after merge**: Delete branches promptly
+6. **Use descriptive names**: Clear branch names help everyone
+
+## Integration with Providers
+
+This Git strategy integrates seamlessly with:
+
+- **GitHub**: Native branch support, PR workflows
+- **Azure DevOps**: Branch policies, PR requirements
+- **CI/CD**: All pipelines trigger on branch pushes
+
+## Common Issues and Solutions
+
+### Cannot push to branch
+
+```bash
+# Ensure you have the latest changes
+git pull origin epic/{name} --rebase
+
+# Force push if necessary (use with caution!)
+git push origin epic/{name} --force-with-lease
+```
+
+### Accidentally committed to main
+
+```bash
+# Create a new branch with your changes
+git branch epic/{name}
+
+# Reset main to origin
+git reset --hard origin/main
+
+# Switch to your new branch
+git checkout epic/{name}
+```
+
+### Need to switch context quickly
+
+```bash
+# Stash current changes
+git stash save "WIP: Description"
+
+# Switch branches
+git checkout other-branch
+
+# Later, restore changes
+git checkout original-branch
+git stash pop
+```
+
+## Migration Notice
+
+**⚠️ IMPORTANT**: Git worktrees are NO LONGER SUPPORTED in ClaudeAutoPM. All development must use the branch strategy described in this document.
+
+If you have existing worktrees:
+1. Complete or stash any uncommitted work
+2. Remove worktrees: `git worktree remove {path}`
+3. Switch to branch-based workflow
+
+## Summary
+
+The branch-based Git strategy provides:
+- ✅ Simplicity and familiarity
+- ✅ Full tool compatibility
+- ✅ Efficient CI/CD integration
+- ✅ Clear, predictable workflows
+- ✅ Minimal learning curve
+
+This is the ONLY approved Git workflow for ClaudeAutoPM projects.

package/packages/plugin-core/rules/golden-rules.md

@@ -0,0 +1,181 @@
+# 🏆 Golden Rules of Development
+
+> **These are the fundamental truths that guide all development decisions.**
+
+## The 12 Golden Rules
+
+### 1. **If it's not tested, it's broken**
+
+Every piece of code must have tests. No exceptions.
+
+### 2. **If it's not documented, it doesn't exist**
+
+Undocumented features are unknown features. Document as you build.
+
+### 3. **If it's not in version control, it didn't happen**
+
+All work must be committed. No local-only changes.
+
+### 4. **If it's not monitored, it's not production-ready**
+
+You can't fix what you can't see. Monitor everything.
+
+### 5. **If it's not secure, it's not shippable**
+
+Security is not optional. Every release must be secure.
+
+### 6. **If it's not accessible, it's not complete**
+
+Accessibility is a requirement, not a nice-to-have.
+
+### 7. **If it's not performant, it's not acceptable**
+
+Performance is a feature. Slow is broken.
+
+### 8. **If it's not maintainable, it's technical debt**
+
+Write code for the next developer (it might be you).
+
+### 9. **If it's not reviewed, it's not ready**
+
+All code needs a second pair of eyes. No solo commits to main.
+
+### 10. **If it's not automated, it's not scalable**
+
+Manual processes don't scale. Automate everything.
+
+### 11. **If it's not responsive, it's not modern**
+
+Mobile-first is not optional in 2024+.
+
+### 12. **If it's not user-friendly, it's not finished**
+
+User experience trumps developer convenience.
+
+## Application of Golden Rules
+
+### During Development
+
+- Before writing code: Which rules apply?
+- During implementation: Am I violating any rules?
+- Before committing: Have I satisfied all rules?
+- During review: Check against all 12 rules
+
+### In Code Reviews
+
+Use golden rules as review criteria:
+
+```markdown
+## Review Checklist
+- [ ] Rule #1: Tests written and passing
+- [ ] Rule #2: Documentation updated
+- [ ] Rule #3: Changes committed properly
+- [ ] Rule #4: Monitoring in place
+- [ ] Rule #5: Security reviewed
+- [ ] Rule #6: Accessibility verified
+- [ ] Rule #7: Performance acceptable
+- [ ] Rule #8: Code is maintainable
+- [ ] Rule #9: Peer reviewed
+- [ ] Rule #10: Automation added
+- [ ] Rule #11: Responsive design
+- [ ] Rule #12: UX considered
+```
+
+### In Architecture Decisions
+
+Every architectural decision must:
+
+1. Not violate any golden rule
+2. Support multiple golden rules
+3. Make following rules easier
+
+## Rule Prioritization
+
+When rules conflict (rare but possible):
+
+### Priority 1: Safety & Security
+
+- Rule #5 (Security)
+- Rule #1 (Testing)
+
+### Priority 2: User Impact
+
+- Rule #12 (User-friendly)
+- Rule #6 (Accessibility)
+- Rule #7 (Performance)
+
+### Priority 3: Sustainability
+
+- Rule #8 (Maintainable)
+- Rule #2 (Documentation)
+- Rule #10 (Automation)
+
+### Priority 4: Process
+
+- Rule #3 (Version control)
+- Rule #9 (Review)
+- Rule #4 (Monitoring)
+- Rule #11 (Responsive)
+
+## Enforcement
+
+### Automatic Checks
+
+- CI/CD pipeline enforces rules #1, #3, #5, #7
+- Linters enforce rule #8
+- Accessibility tools enforce rule #6
+- Design tools enforce rule #11
+
+### Manual Verification
+
+- Code review enforces rules #2, #9, #12
+- Architecture review enforces rule #10
+- Security review enforces rule #5
+- UX review enforces rules #6, #11, #12
+
+## Consequences of Violation
+
+### Immediate Action Required
+
+- **Rule #1 violation**: Block deployment
+- **Rule #5 violation**: Security incident process
+- **Rule #6 violation**: Accessibility fix required
+
+### Fix in Current Sprint
+
+- **Rule #2 violation**: Documentation debt ticket
+- **Rule #7 violation**: Performance optimization ticket
+- **Rule #8 violation**: Refactoring ticket
+
+### Track and Improve
+
+- **Rule #4 violation**: Add monitoring
+- **Rule #10 violation**: Automation backlog
+- **Rule #11 violation**: Responsive design update
+
+## Quick Reference
+
+```bash
+# Before starting work
+"What rules apply to this task?"
+
+# During implementation
+"Am I following all applicable rules?"
+
+# Before committing
+"Have I validated against all 12 rules?"
+
+# During review
+"Does this PR satisfy the golden rules?"
+
+# In production
+"Are we monitoring rule compliance?"
+```
+
+## Remember
+
+**Excellence is not a skill, it's an attitude.**
+
+These rules are not suggestions—they are the foundation of quality software. Every line of code is an opportunity to uphold these standards. When in doubt, refer to the rules. When facing a decision, let the rules guide you.
+
+**Quality is everyone's responsibility.**

package/packages/plugin-core/rules/naming-conventions.md

@@ -0,0 +1,111 @@
+# Naming Conventions and Code Standards
+
+> **CRITICAL**: Consistent naming and zero technical debt. No exceptions.
+
+## Absolute Naming Prohibitions
+
+### NEVER USE These Suffixes
+
+- ❌ `_advanced`, `_fixed`, `_improved`, `_new`, `_old`
+- ❌ `_v2`, `_v3`, `_backup`, `_copy`, `_temp`
+- ❌ `_updated`, `_modified`, `_changed`
+- ❌ Generic suffixes that don't describe function
+- ❌ Version numbers in names (use git for versioning)
+
+### NEVER CREATE These Documentation Files
+
+- ❌ `CHANGES_[DATE]_[FEATURE].md`
+- ❌ `SUMMARY_OBJECTIVE_[N].md`
+- ❌ `WORKFLOW_SETUP_GUIDE.md`
+- ❌ One-off documentation files for single changes
+- ❌ Documentation files unless explicitly requested
+- ❌ Temporary explanation files
+
+## Required Naming Patterns
+
+### Before ANY Implementation
+
+1. Check existing codebase for naming patterns
+2. Read naming conventions from existing code
+3. Follow established patterns exactly
+4. When in doubt, search for similar functions
+
+### Function/Variable Naming
+
+- Use descriptive names that explain purpose
+- Follow language-specific conventions (camelCase, snake_case)
+- Maintain consistency with existing codebase
+- Prefer clarity over brevity
+
+### File Naming
+
+- Match existing file naming patterns
+- Use semantic names that describe content
+- No temporary or versioned file names
+- Keep extensions consistent
+
+## Code Quality Standards
+
+### NEVER TOLERATE
+
+- ❌ Partial implementations
+- ❌ "Simplified" code with TODOs
+- ❌ Duplicate functions (always search first)
+- ❌ Mixed concerns (UI with DB, validation with API)
+- ❌ Resource leaks (unclosed connections, listeners)
+- ❌ Dead code (unused functions, imports)
+- ❌ Inconsistent formatting
+
+### ALWAYS ENFORCE
+
+- ✅ Single responsibility principle
+- ✅ Proper separation of concerns
+- ✅ Resource cleanup (close connections, clear timeouts)
+- ✅ Consistent error handling
+- ✅ Meaningful variable names
+- ✅ DRY principle (Don't Repeat Yourself)
+
+## Anti-Pattern Prevention
+
+### Over-Engineering
+
+- Don't add unnecessary abstractions
+- Don't create factory patterns when simple functions work
+- Don't add middleware for trivial operations
+- Don't think "enterprise" when you need "working"
+
+### Under-Engineering
+
+- Don't skip error handling
+- Don't ignore edge cases
+- Don't hardcode values that should be configurable
+- Don't assume happy path only
+
+## Code Review Checklist
+
+Before ANY commit:
+
+1. No naming convention violations
+2. No duplicate code
+3. No resource leaks
+4. No mixed concerns
+5. No partial implementations
+6. No unnecessary complexity
+7. All tests passing
+
+## Enforcement
+
+### Discovery of Violation
+
+1. Stop current work immediately
+2. Fix naming to match conventions
+3. Remove any duplicate code
+4. Clean up resources properly
+5. Document pattern in CLAUDE.md
+
+### Prevention Strategy
+
+- Always search before creating new functions
+- Always read existing code for patterns
+- Always use agents for code analysis
+- Never assume, always verify