claude-autopm 2.8.1 → 2.8.3

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.

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.