agileflow 2.76.0 → 2.78.0

package/src/core/skills/_learnings/README.md

@@ -0,0 +1,91 @@
+# Skill Learnings
+
+This directory contains learnings files for self-improving skills. Each skill can have a corresponding `.yaml` file that stores user preferences and corrections learned over time.
+
+## Purpose
+
+Just like agents have `expertise.yaml` files that accumulate codebase knowledge, skills have learnings files that accumulate **user preferences**.
+
+| Component | Agents | Skills |
+|-----------|--------|--------|
+| **What they learn** | Codebase knowledge | User preferences |
+| **Learning file** | `expertise.yaml` | `learnings.yaml` |
+| **Example learning** | "sessions table uses UUID primary keys" | "User prefers conventional commits" |
+
+## How It Works
+
+1. **On skill invocation**: Skill reads its learnings file (if exists)
+2. **Apply preferences**: Skill output follows learned preferences
+3. **On correction**: Skill extracts signal and updates learnings file
+4. **Persist**: Changes saved for next session
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Skill Execution Flow                                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. Read _learnings/{skill}.yaml                            │
+│  2. Execute skill with learned preferences                  │
+│  3. User provides output                                    │
+│  4. If correction detected:                                 │
+│     - Extract signal (what was wrong)                       │
+│     - Determine confidence (high/medium/low)                │
+│     - Update learnings file                                 │
+│  5. Continue with corrected output                          │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## File Naming
+
+Learnings files are named after their skill:
+
+| Skill | Learnings File |
+|-------|----------------|
+| `commit-message-formatter` | `commit.yaml` |
+| `agileflow-story-writer` | `story-writer.yaml` |
+| `code-review` | `code-review.yaml` |
+
+## Schema
+
+See `_template.yaml` for the full schema. Key sections:
+
+```yaml
+skill: commit-message-formatter
+version: 1
+last_updated: 2026-01-06
+
+preferences:
+  - signal: "User said 'no AI attribution'"
+    learning: "Never add AI footers"
+    confidence: high
+    captured: 2026-01-06
+
+conventions:
+  - "Use imperative mood"
+  - "Keep subject under 50 chars"
+
+anti_patterns:
+  - "Don't add emojis"
+```
+
+## Confidence Levels
+
+| Level | Trigger | Example |
+|-------|---------|---------|
+| **high** | Explicit correction ("never do X", "always do Y") | "Never include AI footers" |
+| **medium** | Approval or pattern that worked | "User approved conventional commit format" |
+| **low** | Observation to review | "User seemed to prefer shorter messages" |
+
+## Version Control
+
+Learnings files are version-controlled in git. This allows:
+- **History**: See how preferences evolved over time
+- **Rollback**: Revert if learning was incorrect
+- **Sharing**: Team can share learned preferences
+
+## Related
+
+- [Agent Expert System](../../agents/experts/README.md) - Same pattern for agents
+- [20260106-self-improving-skills-claude-code.md](../../../../../../../docs/10-research/20260106-self-improving-skills-claude-code.md) - Research
+- [20251216-agent-experts-self-improving-agents.md](../../../../../../../docs/10-research/20251216-agent-experts-self-improving-agents.md) - Original pattern

package/src/core/skills/_learnings/_template.yaml

@@ -0,0 +1,106 @@
+# Skill Learnings Template
+# Copy this file and rename to match your skill (e.g., commit.yaml)
+#
+# This file stores learned user preferences for a skill.
+# It mirrors the expertise.yaml pattern used by agent experts.
+
+# Skill identifier (matches the skill filename without extension)
+skill: skill-name
+
+# Schema version for migrations
+version: 1
+
+# Last time this file was updated
+last_updated: 2026-01-06T00:00:00.000Z
+
+# =============================================================================
+# PREFERENCES
+# =============================================================================
+# Explicit preferences learned from user corrections.
+# Each entry captures: what triggered the learning, what was learned, and confidence.
+
+preferences:
+  # Example: High confidence from explicit correction
+  # - signal: "User said 'no AI attribution in commits'"
+  #   learning: "Never add AI footers or Co-Authored-By lines"
+  #   confidence: high
+  #   captured: 2026-01-06T10:30:00.000Z
+
+  # Example: Medium confidence from approval
+  # - signal: "User approved 'feat(api): add user endpoint'"
+  #   learning: "Use conventional commits with scope in parentheses"
+  #   confidence: medium
+  #   captured: 2026-01-06T11:00:00.000Z
+
+  # Example: Low confidence from observation
+  # - signal: "User shortened message from 60 to 45 chars"
+  #   learning: "User may prefer shorter commit messages"
+  #   confidence: low
+  #   captured: 2026-01-06T11:30:00.000Z
+
+# =============================================================================
+# CONVENTIONS
+# =============================================================================
+# Established patterns this skill should always follow.
+# These are high-confidence learnings that have been validated.
+
+conventions:
+  # - "Use imperative mood in commit subject"
+  # - "Keep subject line under 50 characters"
+  # - "Separate subject from body with blank line"
+
+# =============================================================================
+# ANTI-PATTERNS
+# =============================================================================
+# Things this skill should never do.
+# These are typically from explicit "never do X" corrections.
+
+anti_patterns:
+  # - "Don't add emojis unless user explicitly requests"
+  # - "Don't use past tense in commit messages"
+  # - "Don't include issue numbers without prefix"
+
+# =============================================================================
+# CONTEXT
+# =============================================================================
+# Project-specific context the skill has learned.
+# This helps the skill understand the environment it's operating in.
+
+context:
+  # project_type: nodejs
+  # primary_language: typescript
+  # framework: next.js
+  # style_guide: conventional-commits
+
+# =============================================================================
+# EXAMPLES
+# =============================================================================
+# Good examples the skill has learned from.
+# Can be referenced when generating new output.
+
+examples:
+  # good:
+  #   - "feat(auth): add OAuth2 login flow"
+  #   - "fix(api): handle null response from external service"
+  #
+  # bad:
+  #   - "Added stuff"  # Too vague
+  #   - "fixed bug"    # No scope, past tense
+
+# =============================================================================
+# METADATA
+# =============================================================================
+# Tracking information for the learnings file.
+
+metadata:
+  # Total number of corrections captured
+  corrections_count: 0
+
+  # Total number of approvals captured
+  approvals_count: 0
+
+  # When the file was first created
+  created: 2026-01-06T00:00:00.000Z
+
+  # Sessions that contributed to learnings
+  sessions: []

package/src/core/skills/_learnings/commit.yaml

@@ -0,0 +1,69 @@
+# Learnings for commit-message-formatter skill
+# This file accumulates user preferences for commit message generation.
+
+skill: commit-message-formatter
+version: 1
+last_updated: 2026-01-06T00:00:00.000Z
+
+# =============================================================================
+# PREFERENCES
+# =============================================================================
+preferences:
+  # From CLAUDE.md project settings
+  - signal: "Project CLAUDE.md specifies no AI attribution"
+    learning: "Never add AI footers, Co-Authored-By, or robot emojis to commits"
+    confidence: high
+    captured: 2026-01-06T00:00:00.000Z
+
+# =============================================================================
+# CONVENTIONS
+# =============================================================================
+conventions:
+  - "Use conventional commits format (feat/fix/chore/docs/refactor/test/style)"
+  - "Include scope in parentheses when applicable"
+  - "Use imperative mood in subject line"
+  - "Keep subject under 50 characters"
+  - "Separate subject from body with blank line"
+  - "Wrap body at 72 characters"
+
+# =============================================================================
+# ANTI-PATTERNS
+# =============================================================================
+anti_patterns:
+  - "Don't add AI attribution (footers, Co-Authored-By, emojis)"
+  - "Don't use past tense (use 'add' not 'added')"
+  - "Don't use vague messages ('fix stuff', 'update code')"
+  - "Don't include emojis unless explicitly requested"
+
+# =============================================================================
+# CONTEXT
+# =============================================================================
+context:
+  style_guide: conventional-commits
+  attribution: none
+
+# =============================================================================
+# EXAMPLES
+# =============================================================================
+examples:
+  good:
+    - "feat(auth): add OAuth2 login flow"
+    - "fix(api): handle null response from external service"
+    - "chore: update dependencies to latest versions"
+    - "docs: add API endpoint documentation"
+    - "refactor(db): extract query builder to separate module"
+
+  bad:
+    - "Added stuff"
+    - "fixed bug"
+    - "WIP"
+    - "feat: add feature 🚀"
+
+# =============================================================================
+# METADATA
+# =============================================================================
+metadata:
+  corrections_count: 0
+  approvals_count: 0
+  created: 2026-01-06T00:00:00.000Z
+  sessions: []

package/src/core/templates/damage-control-patterns.yaml

@@ -0,0 +1,234 @@
+# AgileFlow Damage Control - Security Rules
+# Protects your codebase from destructive agent commands
+#
+# Configuration: /agileflow:configure → Damage Control
+# Documentation: See research/20260106-claude-code-damage-control-hooks.md
+#
+# Schema Version: 1.0.0
+
+version: "1.0.0"
+
+# =====================================================
+# BLOCKED BASH COMMANDS - Always blocked (exit code 2)
+# =====================================================
+# Regex patterns matched against the full bash command
+# These commands are considered too dangerous to ever run
+
+bashToolPatterns:
+  # ─── File System Destruction ───
+  - pattern: '\brm\s+(-[rRf]+\s+)*/'
+    reason: "rm with absolute path - could delete system files"
+
+  - pattern: '\brm\s+-[rRf]*\s+\.\.'
+    reason: "rm with parent directory - could escape project"
+
+  - pattern: '\brm\s+-rf\s+'
+    reason: "Recursive force delete - extremely dangerous"
+
+  - pattern: '\brmdir\s+(-p\s+)*/'
+    reason: "rmdir with absolute path"
+
+  # ─── Git Destructive Operations ───
+  - pattern: '\bgit\s+push\s+.*--force'
+    reason: "Force push can destroy remote history"
+
+  - pattern: '\bgit\s+push\s+.*-f\b'
+    reason: "Force push can destroy remote history"
+
+  - pattern: '\bgit\s+reset\s+--hard'
+    reason: "Hard reset discards uncommitted changes"
+
+  - pattern: '\bgit\s+clean\s+-fd'
+    reason: "Git clean with force deletes untracked files"
+
+  - pattern: '\bgit\s+branch\s+-D'
+    reason: "Force delete branch without merge check"
+
+  # ─── Database Destructive Operations ───
+  - pattern: 'DROP\s+(TABLE|DATABASE|INDEX|VIEW|SCHEMA)'
+    reason: "DROP commands are destructive"
+    flags: "i"
+
+  - pattern: 'TRUNCATE\s+TABLE'
+    reason: "TRUNCATE removes all data without logging"
+    flags: "i"
+
+  - pattern: 'DELETE\s+FROM\s+\w+\s*;'
+    reason: "DELETE without WHERE clause deletes all rows"
+    flags: "i"
+
+  # ─── System Modification ───
+  - pattern: '\bsudo\s+'
+    reason: "Sudo commands require manual execution"
+
+  - pattern: '\bchmod\s+777'
+    reason: "World-writable permissions are dangerous"
+
+  - pattern: '\bchown\s+-R'
+    reason: "Recursive ownership change"
+
+  - pattern: '\bchmod\s+-R'
+    reason: "Recursive permission change"
+
+  # ─── Disk Operations ───
+  - pattern: '\bdd\s+if='
+    reason: "dd can overwrite disks"
+
+  - pattern: '\bmkfs\.'
+    reason: "Filesystem creation"
+
+  - pattern: '\bfdisk\b'
+    reason: "Disk partitioning"
+
+  # ─── Process Control ───
+  - pattern: '\bkill\s+-9'
+    reason: "Force kill processes"
+
+  - pattern: '\bkillall\b'
+    reason: "Kill all matching processes"
+
+  - pattern: '\bpkill\s+-9'
+    reason: "Force kill by pattern"
+
+  # ─── Network/System ───
+  - pattern: '\biptables\s+'
+    reason: "Firewall modification"
+
+  - pattern: '\bsystemctl\s+(stop|disable|mask)'
+    reason: "System service modification"
+
+  # ─── Credential Exposure ───
+  - pattern: '\bcat\s+.*\.pem'
+    reason: "Displaying private keys"
+
+  - pattern: '\bcat\s+.*id_rsa'
+    reason: "Displaying SSH private keys"
+
+# =====================================================
+# ASK PATTERNS - Require user confirmation
+# =====================================================
+# Risky but sometimes valid - ask first before executing
+
+askPatterns:
+  - pattern: 'DELETE\s+FROM\s+\w+\s+WHERE'
+    reason: "Deleting specific records - please confirm"
+    flags: "i"
+
+  - pattern: '\bnpm\s+publish'
+    reason: "Publishing to npm - please confirm"
+
+  - pattern: '\bgit\s+push\s+origin\s+(main|master)'
+    reason: "Pushing to main branch - please confirm"
+
+  - pattern: '\brm\s+-[rRf]*\s+node_modules'
+    reason: "Removing node_modules - please confirm"
+
+  - pattern: '\baws\s+.*delete'
+    reason: "AWS delete operation - please confirm"
+    flags: "i"
+
+  - pattern: '\bgcloud\s+.*delete'
+    reason: "GCloud delete operation - please confirm"
+    flags: "i"
+
+  - pattern: '\baz\s+.*delete'
+    reason: "Azure delete operation - please confirm"
+    flags: "i"
+
+  - pattern: '\bnpx\s+.*--force'
+    reason: "Force npx operation - please confirm"
+
+  - pattern: 'UPDATE\s+\w+\s+SET.*WHERE'
+    reason: "Database update - please confirm"
+    flags: "i"
+
+# =====================================================
+# PATH PROTECTION - File/directory access controls
+# =====================================================
+
+# Zero access - cannot read, write, edit, or delete
+# These paths are completely off-limits
+zeroAccessPaths:
+  - "~/.ssh/"
+  - "~/.aws/"
+  - "~/.gnupg/"
+  - "~/.config/gh/"
+  - ".env.production"
+  - ".env.local"
+  - ".env.secrets"
+  - "credentials.json"
+  - "secrets.yaml"
+  - "secrets.json"
+  - "*.pem"
+  - "*.key"
+  - "id_rsa"
+  - "id_ed25519"
+
+# Read-only - can read but not modify
+# Safe to view, but changes should be manual
+readOnlyPaths:
+  - "~/.bashrc"
+  - "~/.zshrc"
+  - "~/.gitconfig"
+  - "/etc/"
+  - "package-lock.json"
+  - "yarn.lock"
+  - "pnpm-lock.yaml"
+
+# No delete - can read and modify but not delete
+# Important files that shouldn't be removed
+noDeletePaths:
+  - ".claude/"
+  - ".agileflow/"
+  - "docs/09-agents/status.json"
+  - ".git/"
+  - "CLAUDE.md"
+  - "README.md"
+  - "package.json"
+  - "tsconfig.json"
+
+# =====================================================
+# AGILEFLOW-SPECIFIC PROTECTIONS
+# =====================================================
+# Additional rules specific to AgileFlow projects
+
+agileflowProtections:
+  - pattern: '\brm\s+.*status\.json'
+    reason: "status.json tracks story progress - protected"
+
+  - pattern: '\brm\s+.*\.claude/'
+    reason: "Claude Code configuration - protected"
+
+  - pattern: '\brm\s+.*\.agileflow/'
+    reason: "AgileFlow installation - protected"
+
+  - pattern: '\brm\s+.*session-state\.json'
+    reason: "Session state tracking - protected"
+
+  - pattern: '\brm\s+.*expertise\.yaml'
+    reason: "Agent expertise files - protected"
+
+# =====================================================
+# NOTES
+# =====================================================
+#
+# Exit Codes:
+#   0 = Allow command to proceed
+#   2 = Block command (show error message)
+#
+# Ask Pattern JSON Output:
+#   { "result": "ask", "message": "Confirm this action?" }
+#
+# Flags:
+#   "i" = case-insensitive matching
+#
+# Customization:
+#   Add project-specific patterns below this line
+#   Run /agileflow:configure → Damage Control to reconfigure
+#
+# =====================================================
+
+# ─── Project-Specific Patterns (add yours below) ───
+# customPatterns:
+#   - pattern: 'your-pattern-here'
+#     reason: "Your reason"

package/src/core/templates/skill-template.md

@@ -23,19 +23,45 @@ Include:
 - Key capabilities
 - Expected outcomes
 
+## Self-Improving Learnings
+
+This skill learns from your corrections and preferences.
+
+**On invocation**:
+1. Check if `.agileflow/skills/_learnings/{skill-name}.yaml` exists
+2. If exists, read and apply learned preferences
+3. Follow conventions and avoid anti-patterns from learnings
+
+**On correction**:
+1. When user corrects output, extract the signal
+2. Determine confidence level:
+   - **high**: Explicit correction ("never do X", "always do Y")
+   - **medium**: User approved or pattern worked well
+   - **low**: Observation to review later
+3. Update the learnings file with new preference
+
+**Learnings file location**: `.agileflow/skills/_learnings/{skill-name}.yaml`
+
 ## Instructions
 
 Step-by-step guidance for Claude:
 
-1. **First step**: What to do first
-   - Detail A
-   - Detail B
+1. **Load learnings** (if exists):
+   - Read `.agileflow/skills/_learnings/{skill-name}.yaml`
+   - Apply preferences, conventions, and anti-patterns
+   - Skip if file doesn't exist (first run)
 
-2. **Second step**: What to do next
-   - Detail A
-   - Detail B
+2. **Execute skill**:
+   - Follow the instructions below with learned preferences applied
+   - [Your skill-specific step A]
+   - [Your skill-specific step B]
+
+3. **If user corrects**:
+   - Extract signal from correction
+   - Update learnings file
+   - Continue with corrected approach
 
-3. **Final step**: How to complete the task
+4. **Final step**: Complete the task
    - Detail A
    - Detail B
 
@@ -50,9 +76,11 @@ Describe the expected output or deliverable:
 ## Quality Checklist
 
 Before completing, verify:
+- [ ] Loaded learnings file (if exists)
+- [ ] Applied learned preferences
 - [ ] Requirement 1 met
 - [ ] Requirement 2 met
-- [ ] Requirement 3 met
+- [ ] If corrected, updated learnings file
 
 ## Examples
 
@@ -68,8 +96,22 @@ Before completing, verify:
 [Example of what Claude should produce]
 ```
 
+### Example 2: Learning from Correction
+
+**User Correction:**
+```
+"Don't include emojis in the output"
+```
+
+**Self-Improve Action:**
+1. Extract signal: "User said 'Don't include emojis'"
+2. Learning: "Never include emojis in output"
+3. Confidence: high (explicit correction)
+4. Update `.agileflow/skills/_learnings/{skill-name}.yaml`
+
 ## Notes
 
-- Additional guidance or edge cases
-- Integration with other skills/commands
-- Important considerations
+- Learnings persist across sessions
+- First run has no learnings file - that's OK
+- High-confidence learnings are treated as rules
+- Git tracks learnings evolution over time

package/tools/cli/commands/list.js

@@ -10,7 +10,9 @@ const fs = require('fs-extra');
 const yaml = require('js-yaml');
 const { Installer } = require('../installers/core/installer');
 const { displayLogo, displaySection, success, warning, info } = require('../lib/ui');
-const { parseFrontmatter: parseYamlFrontmatter } = require('../../../scripts/lib/frontmatter-parser');
+const {
+  parseFrontmatter: parseYamlFrontmatter,
+} = require('../../../scripts/lib/frontmatter-parser');
 
 const installer = new Installer();