workflow-agent-cli 1.1.2

package/templates/SELF_IMPROVEMENT_MANDATE.md

@@ -0,0 +1,298 @@
+# Self-Improvement Mandate
+
+> **Generated by**: @hawkinside_out/workflow-agent v{{VERSION}}  
+> **Project**: {{PROJECT_NAME}}  
+> **Last Updated**: {{DATE}}
+
+This document defines the **mandatory** self-improvement and evolution rules for {{PROJECT_NAME}}.
+
+---
+
+## 🎯 Mandatory Rule: Continuous Improvement Tracking
+
+### When This Applies
+
+ANY time a developer, AI agent, or team member receives an "ask" or suggestion to improve the workflow, this process MUST be followed:
+
+1. **Document the Request**
+   - Create a new file in `.workflow/improvements/YYYY-MM-DD-<id>.md`
+   - Use the template below
+   - Timestamp: ISO 8601 format
+   - Status: `proposed` (initial), `accepted`, `implemented`, `rejected`
+
+2. **Categorize the Suggestion**
+   - **validation**: Branch/commit/PR validation rules
+   - **scopes**: Scope definitions, scope organization
+   - **documentation**: Guideline updates, clarity improvements
+   - **performance**: Speed, efficiency, workflow optimization
+   - **security**: Security concerns, sensitive data handling
+   - **ux**: Developer experience, CLI usability, IDE integration
+
+3. **Prioritize Impact**
+   - **critical**: Blocking issue, security vulnerability, data loss risk
+   - **high**: Significant pain point affecting daily work
+   - **medium**: Noticeable improvement but not urgent
+   - **low**: Nice-to-have, minor enhancement
+
+4. **Generate Implementation Plan**
+   - Use the implementation plan template from `AGENT_EDITING_INSTRUCTIONS.md`
+   - Include affected files, testing requirements, rollback plan
+   - Estimate effort and impact
+
+### Improvement Suggestion Template
+
+\`\`\`markdown
+# Improvement Suggestion
+
+**ID**: <unique-id>
+**Date**: <ISO-8601-timestamp>
+**Status**: proposed | accepted | implemented | rejected
+**Category**: validation | scopes | documentation | performance | security | ux
+**Priority**: critical | high | medium | low
+**Reporter**: <name-or-github-handle>
+
+## Problem/Opportunity
+
+<Clear description of what needs improvement and why>
+
+## Proposed Solution
+
+<Specific, actionable suggestion for improvement>
+
+## Impact Analysis
+
+- **Who is affected**: <developers, teams, CI/CD, etc.>
+- **Frequency**: <how often is this encountered?>
+- **Current workaround**: <how do people handle this now?>
+- **Benefit if implemented**: <concrete improvements expected>
+
+## Implementation Plan
+
+### Changes Required
+- [ ] File/component to modify — `path/to/file.ts`
+- [ ] Update documentation — `docs/section.md`
+- [ ] Add tests — `tests/improvement.test.ts`
+
+### Testing
+- [ ] Unit tests added
+- [ ] Integration tests added
+- [ ] Manual testing completed
+
+### Rollback Plan
+
+<How to undo this change if it causes issues>
+
+## Notes
+
+<Additional context, related issues, alternative approaches>
+
+---
+
+*To submit this improvement to the workflow-agent community:*
+\`\`\`bash
+workflow suggest "$(cat .workflow/improvements/YYYY-MM-DD-<id>.md)"
+\`\`\`
+\`\`\`
+
+---
+
+## 💡 Proactive Suggestion Rule
+
+### Automatic Analysis Points
+
+The workflow system MUST proactively analyze usage patterns and offer suggestions during these commands:
+
+1. **`workflow validate`** - After validation errors
+   - Detect repeated validation failures
+   - Suggest scope aliases for common typos
+   - Recommend adding frequently-used but unlisted scopes
+
+2. **`workflow sync`** - When syncing team config
+   - Compare local vs remote scope usage
+   - Suggest consolidating duplicate/overlapping scopes
+   - Recommend preset upgrades if available
+
+3. **`workflow doctor`** - Health check analysis
+   - Analyze git history for patterns (scope usage frequency, branch naming consistency)
+   - Detect unused scopes (defined but never used in past 90 days)
+   - Identify scope fragmentation (similar scopes that could merge)
+   - Check for validation rule mismatches (rules too strict/loose based on failure rate)
+
+### Suggestion Output Format
+
+\`\`\`
+💡 Workflow Optimization Suggestion
+
+[CATEGORY: <category>] [PRIORITY: <priority>]
+
+<One-line summary of the issue>
+
+Details:
+  • <Specific observation or pattern detected>
+  • <Impact or frequency data>
+  • <Concrete example from git history>
+
+Recommendation:
+  <Actionable suggestion with exact command or config change>
+
+To apply automatically:
+  workflow apply-suggestion <id>
+
+To provide feedback:
+  workflow suggest "Alternative approach: ..."
+\`\`\`
+
+### Pattern Detection Examples
+
+**Example 1: Common Typo**
+```
+💡 Workflow Optimization Suggestion
+
+[CATEGORY: validation] [PRIORITY: medium]
+
+Detected 12 validation failures for scope 'task' (should be 'tasks')
+
+Details:
+  • 12 failed commits over past 30 days
+  • All from 'tasks' scope being typed as 'task'
+  • Affects 3 different team members
+
+Recommendation:
+  Add scope alias: 'task' → 'tasks' in workflow.config.ts
+
+  aliases: {
+    'task': 'tasks',
+    'ui-component': 'ui'
+  }
+
+To apply automatically:
+  workflow config add-alias task tasks
+```
+
+**Example 2: Scope Consolidation**
+```
+💡 Workflow Optimization Suggestion
+
+[CATEGORY: scopes] [PRIORITY: low]
+
+Both 'api' and 'backend' scopes exist but serve similar purposes
+
+Details:
+  • 'api' used in 45 commits (68%)
+  • 'backend' used in 21 commits (32%)
+  • Descriptions overlap: "Server actions, API patterns, data fetching"
+
+Recommendation:
+  Consolidate into single 'api' scope:
+  1. Update 'api' scope description to be comprehensive
+  2. Remove 'backend' scope
+  3. Update CHANGELOG with migration note
+
+To discuss with team:
+  workflow suggest "Should we keep both api and backend scopes separate?"
+```
+
+---
+
+## 📊 Evolution Tracking
+
+### Changelog Requirements
+
+ALL implemented improvements MUST be documented in `WORKFLOW_CHANGELOG.md` with:
+
+- **Date**: When improvement was implemented
+- **Version**: Semantic version bump (if using workflow-agent package)
+- **Category**: Same as suggestion category
+- **Summary**: One-line description
+- **Rationale**: Why this improvement was made
+- **Migration**: Any breaking changes or required actions
+- **Reporter**: Who suggested the improvement (credit!)
+
+### Changelog Template
+
+\`\`\`markdown
+## {{VERSION}} - {{DATE}}
+
+### {{CATEGORY}} Improvements
+
+**<One-line summary>**
+
+- **Rationale**: <Why this was needed>
+- **Changes**: <What changed>
+- **Migration**: <How to adapt (if breaking)>
+- **Reporter**: @<github-handle>
+- **Impact**: <Who benefits and how>
+
+\`\`\`
+
+---
+
+## 🔄 Workflow Agent Integration
+
+If using `@hawkinside_out/workflow-agent` package, improvements are:
+
+1. **Submitted** to central registry at `workflow-improvements.dev`
+2. **Moderated** using trust scores and content filtering
+3. **Voted** on by the community (upvote/downvote)
+4. **Prioritized** by AI analysis (impact score calculation)
+5. **Implemented** in future package releases
+6. **Synced** back to your project via `workflow sync`
+
+### Opting In to Community Improvements
+
+Edit `workflow.config.ts`:
+
+\`\`\`typescript
+export default {
+  projectName: '{{PROJECT_NAME}}',
+  scopes: [...],
+  
+  // Enable community improvement syncing
+  syncRemote: 'https://workflow-improvements.dev/registry',
+  analytics: {
+    enabled: true,
+    shareAnonymous: true, // Help improve the tool!
+  },
+};
+\`\`\`
+
+---
+
+## ✅ Pre-Commit Checklist Addition
+
+Before EVERY commit touching workflow configuration, verify:
+
+- [ ] **Improvement Documented**: If changing workflow rules, is there a corresponding improvement suggestion file?
+- [ ] **Changelog Updated**: Is WORKFLOW_CHANGELOG.md updated with the change?
+- [ ] **Team Notified**: For breaking changes, has the team been notified via Slack/Discord?
+- [ ] **Migration Guide**: For breaking changes, is there a clear migration path documented?
+
+---
+
+## 🚫 Prohibited Actions
+
+- ❌ Changing workflow rules without documenting rationale in improvement suggestion
+- ❌ Ignoring repeated validation failures without investigating root cause
+- ❌ Rejecting community improvement suggestions without feedback/rationale
+- ❌ Making breaking changes to scope definitions without team discussion
+- ❌ Bypassing validation in "strict" mode without documenting exception reason
+
+---
+
+## 🎓 Philosophy
+
+> "A workflow that doesn't evolve is a workflow that dies."
+
+The goal is **continuous improvement** driven by:
+
+1. **Real usage data** - What actually happens in practice
+2. **Developer feedback** - Pain points from the team
+3. **Community wisdom** - Insights from other projects
+4. **Automated analysis** - Pattern detection by AI
+
+Every suggestion makes the workflow better for everyone. Your feedback matters!
+
+---
+
+*Generated by @hawkinside_out/workflow-agent - a self-evolving workflow management system*  
+*Learn more: https://workflow.dev/docs/self-improvement*