claude-flow-novice 2.15.3 → 2.15.5

package/claude-assets/skills/workflow-codification/DEPLOY_QUICK_REFERENCE.md

@@ -0,0 +1,106 @@
+# Deploy Approved Skill - Quick Reference
+
+## One-Line Usage
+
+```bash
+./.claude/skills/workflow-codification/deploy-approved-skill.sh PATTERN_ID SKILL_NAME FILE [CATEGORY] [AGENTS]
+```
+
+## Common Commands
+
+### Deploy Domain Skill
+```bash
+./.claude/skills/workflow-codification/deploy-approved-skill.sh \
+  42 "jwt-auth" ".claude/skills/auth/jwt.md" "domain" "backend-developer,security-specialist"
+```
+
+### Deploy Coordination Skill (Auto-Approved)
+```bash
+./.claude/skills/workflow-codification/deploy-approved-skill.sh \
+  43 "redis-pattern" ".claude/skills/coordination/redis.md" "coordination" "cfn-orchestrator"
+```
+
+### Deploy without Agent Mappings
+```bash
+./.claude/skills/workflow-codification/deploy-approved-skill.sh \
+  44 "utility" ".claude/skills/utils/utility.md" "foundation"
+```
+
+## Parameters
+
+| Parameter | Required | Example | Default |
+|-----------|----------|---------|---------|
+| PATTERN_ID | Yes | 42 | - |
+| SKILL_NAME | Yes | jwt-authentication | - |
+| CONTENT_PATH | Yes | .claude/skills/auth/jwt.md | - |
+| CATEGORY | No | domain | domain |
+| TEAM_IDS | No | backend-developer,api-designer | (empty) |
+
+## Categories & Approval Levels
+
+| Category | Approval Level |
+|----------|---------------|
+| coordination | auto |
+| foundation | auto |
+| testing | auto |
+| infrastructure | escalate |
+| domain | human |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Invalid parameters |
+| 2 | File not found |
+| 3 | Database error |
+
+## Environment Setup
+
+```bash
+export CFN_SKILLS_DB_PATH="./.claude/skills-database/skills.db"
+```
+
+## Test Deployment
+
+```bash
+bash tests/integration/test-deploy-approved-skill.sh
+```
+
+## Verify Deployment
+
+```bash
+sqlite3 .claude/skills-database/skills.db "SELECT id, name, approval_level FROM skills WHERE name = 'skill-name';"
+```
+
+## Check Agent Mappings
+
+```bash
+sqlite3 .claude/skills-database/skills.db "SELECT agent_type FROM agent_skill_mappings WHERE skill_id = 1;"
+```
+
+## View Approval History
+
+```bash
+sqlite3 .claude/skills-database/skills.db "SELECT decision, approver, timestamp FROM approval_history WHERE skill_id = 1;"
+```
+
+## Troubleshooting
+
+**Database not found**:
+```bash
+ls -la .claude/skills-database/skills.db
+```
+
+**Permission denied**:
+```bash
+chmod 644 .claude/skills-database/skills.db
+```
+
+**Skill already exists**:
+- Re-running is safe (updates existing skill)
+- Check uniqueness if needed
+
+---
+
+**Full Documentation**: `docs/PHASE7_1_DEPLOYMENT_GUIDE.md`

package/claude-assets/skills/workflow-codification/PROPAGATE_UPDATE_QUICK_REFERENCE.md

@@ -0,0 +1,366 @@
+# Propagate Skill Update - Quick Reference
+
+## Overview
+`propagate-skill-update.sh` enables Phase 4 Edge Case Tracker to propagate approved skill improvements back to the Skills Database with proper version management and audit trails.
+
+## Usage
+
+```bash
+./.claude/skills/workflow-codification/propagate-skill-update.sh \
+  SKILL_NAME \
+  NEW_VERSION \
+  UPDATE_PATH \
+  [CHANGE_TYPE] \
+  [NOTIFY_AGENTS]
+```
+
+## Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| SKILL_NAME | Yes | - | Skill identifier (e.g., "jwt-authentication") |
+| NEW_VERSION | Yes | - | Semantic version (e.g., "1.0.1", "1.1.0", "2.0.0") |
+| UPDATE_PATH | Yes | - | Path to updated skill markdown file |
+| CHANGE_TYPE | No | patch | Version change type: patch\|minor\|major |
+| NOTIFY_AGENTS | No | false | Notify affected agents: true\|false |
+
+## Change Types
+
+### Patch (Bug Fix)
+**Example:** 1.0.0 → 1.0.1
+
+```bash
+./.claude/skills/workflow-codification/propagate-skill-update.sh \
+  "jwt-authentication" \
+  "1.0.1" \
+  ".claude/skills/auth/jwt-auth-v1.0.1.md" \
+  "patch" \
+  "true"
+```
+
+**Use When:**
+- Fixing bugs or errors
+- Improving documentation clarity
+- Optimizing performance without API changes
+- Correcting edge case handling
+
+### Minor (New Feature)
+**Example:** 1.0.0 → 1.1.0
+
+```bash
+./.claude/skills/workflow-codification/propagate-skill-update.sh \
+  "jwt-authentication" \
+  "1.1.0" \
+  ".claude/skills/auth/jwt-auth-v1.1.0.md" \
+  "minor" \
+  "true"
+```
+
+**Use When:**
+- Adding new functionality
+- Enhancing existing features
+- Adding backward-compatible improvements
+- Expanding skill capabilities
+
+### Major (Breaking Change)
+**Example:** 1.0.0 → 2.0.0
+
+```bash
+./.claude/skills/workflow-codification/propagate-skill-update.sh \
+  "jwt-authentication" \
+  "2.0.0" \
+  ".claude/skills/auth/jwt-auth-v2.0.0.md" \
+  "major" \
+  "true"
+```
+
+**Use When:**
+- Breaking API compatibility
+- Fundamental architecture changes
+- Removing deprecated features
+- Complete skill redesigns
+
+## Exit Codes
+
+| Code | Meaning | Description |
+|------|---------|-------------|
+| 0 | Success | Skill updated successfully |
+| 1 | Invalid Parameters | Missing or invalid input parameters |
+| 2 | File Not Found | UPDATE_PATH file doesn't exist |
+| 3 | Skill Not Found | Skill doesn't exist in database |
+| 4 | Invalid Version | Version downgrade, same version, or type mismatch |
+| 5 | Content Unchanged | No actual content changes (hash identical) |
+| 6 | Database Error | SQLite operation failed |
+
+## Environment Variables
+
+```bash
+# Skills Database (SQLite - required)
+export CFN_SKILLS_DB_PATH="./.claude/skills-database/skills.db"
+
+# Phase 4 PostgreSQL Integration (optional)
+export PHASE4_POSTGRES_HOST="localhost"
+export PHASE4_POSTGRES_DB="workflow_codification"
+export PHASE4_POSTGRES_USER="cfn_user"
+export PHASE4_POSTGRES_PASS="secure_password"
+
+# Agent Notifications (optional)
+export ENABLE_AGENT_NOTIFICATIONS="true"
+```
+
+## Phase 4 Integration Workflow
+
+### 1. Edge Case Detection
+Phase 4 Edge Case Tracker detects skill improvement opportunity:
+```bash
+# Phase 4 detects pattern deviation in agent execution
+./.claude/skills/workflow-codification/track-edge-case.sh \
+  --skill-name "jwt-authentication" \
+  --issue "Missing refresh token validation" \
+  --severity "medium"
+```
+
+### 2. Expert Review & Approval
+Human expert reviews and approves the improvement:
+```bash
+# Expert approves edge case fix
+./.claude/skills/workflow-codification/approval-workflow.sh \
+  --edge-case-id 42 \
+  --decision "approved" \
+  --expert "security@example.com"
+```
+
+### 3. Skill Update Generation
+Phase 4 generates updated skill content:
+```bash
+# Generate updated skill with fix
+./.claude/skills/workflow-codification/generate-skill-update.sh \
+  --skill-name "jwt-authentication" \
+  --edge-case-id 42 \
+  --output ".claude/skills/auth/jwt-auth-v1.0.1.md"
+```
+
+### 4. Propagate to Skills DB
+**This script** propagates the approved update:
+```bash
+# Propagate approved update to Skills Database
+./.claude/skills/workflow-codification/propagate-skill-update.sh \
+  "jwt-authentication" \
+  "1.0.1" \
+  ".claude/skills/auth/jwt-auth-v1.0.1.md" \
+  "patch" \
+  "true"
+```
+
+### 5. Agent Reload
+Agents reload the updated skill on next invocation:
+```bash
+# Agent detects version update via SkillLoader
+# Automatically reloads skill content
+# No manual intervention required
+```
+
+## Validation Rules
+
+### Semantic Versioning
+- **Format:** MAJOR.MINOR.PATCH (e.g., 2.1.3)
+- **No downgrades:** 1.1.0 → 1.0.0 ❌
+- **No duplicates:** 1.0.0 → 1.0.0 ❌
+- **Type matching:** Major change requires change_type="major" ✅
+
+### Version Change Type Validation
+| Current | New | Expected Type | Valid? |
+|---------|-----|---------------|--------|
+| 1.0.0 | 1.0.1 | patch | ✅ |
+| 1.0.0 | 1.1.0 | minor | ✅ |
+| 1.0.0 | 2.0.0 | major | ✅ |
+| 1.0.0 | 2.0.0 | patch | ❌ Type mismatch |
+| 1.0.0 | 1.1.0 | major | ❌ Type mismatch |
+| 1.1.0 | 1.0.0 | any | ❌ Downgrade |
+
+### Content Hash Validation
+- **Must differ:** New content hash must be different from current
+- **SHA256:** Content integrity verified via SHA256 hash
+- **Idempotent:** Re-running with same content returns exit code 5
+
+## Database Changes
+
+### Skills Table Update
+```sql
+UPDATE skills
+SET version = '1.0.1',
+    content_hash = 'sha256_hash_of_new_content',
+    content_path = '.claude/skills/auth/jwt-auth-v1.0.1.md',
+    updated_at = datetime('now')
+WHERE name = 'jwt-authentication';
+```
+
+### Approval History Record
+```sql
+INSERT INTO approval_history (
+    skill_id, version, approval_level, approver, decision, reasoning
+) VALUES (
+    42,
+    '1.0.1',
+    'auto',
+    'phase4-edge-case-tracker',
+    'approved',
+    'Edge case update propagated from Phase 4 after expert review and validation'
+);
+```
+
+## Agent Notification
+
+When `NOTIFY_AGENTS=true`, the script lists all agents using the skill:
+
+```
+[INFO] Agents using this skill (3):
+  - backend-developer
+  - api-designer
+  - security-specialist
+
+[SUCCESS] Notification: Skill 'jwt-authentication' updated from 1.0.0 to 1.0.1 (patch)
+[INFO] Affected agents should reload skill content on next invocation
+```
+
+## Error Handling Examples
+
+### Invalid Version Format
+```bash
+$ propagate-skill-update.sh "skill-name" "1.0" "path.md" "patch"
+[ERROR] NEW_VERSION must follow semantic versioning (e.g., 1.2.3): 1.0
+Exit Code: 1
+```
+
+### File Not Found
+```bash
+$ propagate-skill-update.sh "skill-name" "1.0.1" "/missing/path.md" "patch"
+[ERROR] UPDATE_PATH file not found: /missing/path.md
+Exit Code: 2
+```
+
+### Skill Not Found
+```bash
+$ propagate-skill-update.sh "nonexistent" "1.0.1" "path.md" "patch"
+[ERROR] Skill not found in database: nonexistent
+Exit Code: 3
+```
+
+### Version Downgrade
+```bash
+$ propagate-skill-update.sh "skill-name" "0.9.0" "path.md" "patch"
+[ERROR] Version downgrade not allowed: 1.0.0 → 0.9.0
+Exit Code: 4
+```
+
+### Content Unchanged
+```bash
+$ propagate-skill-update.sh "skill-name" "1.0.1" "path.md" "patch"
+[WARNING] Content hash unchanged - no actual content changes detected
+[ERROR] Content hash unchanged - update not needed
+Exit Code: 5
+```
+
+## Testing
+
+Run comprehensive integration tests:
+```bash
+bash tests/integration/test-propagate-skill-update.sh
+```
+
+**Test Coverage:**
+- ✅ Patch version updates (1.0.0 → 1.0.1)
+- ✅ Minor version updates (1.0.0 → 1.1.0)
+- ✅ Major version updates (1.0.0 → 2.0.0)
+- ✅ Content hash validation
+- ✅ Approval history creation
+- ✅ Agent notification listing
+- ✅ Error handling (invalid version, missing file)
+- ✅ Idempotency (unchanged content detection)
+- ✅ Version type mismatch detection
+- ✅ Version downgrade rejection
+
+## Best Practices
+
+### 1. Always Specify Change Type
+```bash
+# Good - Explicit change type
+propagate-skill-update.sh "skill" "1.0.1" "path.md" "patch"
+
+# Risky - Relies on default (patch)
+propagate-skill-update.sh "skill" "1.0.1" "path.md"
+```
+
+### 2. Enable Notifications for Breaking Changes
+```bash
+# Major version - notify all agents
+propagate-skill-update.sh "skill" "2.0.0" "path.md" "major" "true"
+
+# Patch version - optional notification
+propagate-skill-update.sh "skill" "1.0.1" "path.md" "patch" "false"
+```
+
+### 3. Version Files Consistently
+```bash
+# Consistent naming pattern
+.claude/skills/auth/jwt-auth-v1.0.0.md
+.claude/skills/auth/jwt-auth-v1.0.1.md
+.claude/skills/auth/jwt-auth-v1.1.0.md
+.claude/skills/auth/jwt-auth-v2.0.0.md
+```
+
+### 4. Document Changes
+Update skill content with changelog:
+```markdown
+# JWT Authentication Skill
+
+**Version:** 1.0.1
+**Last Updated:** 2025-11-16
+
+## Changelog
+
+### v1.0.1 (2025-11-16)
+- **Bug Fix:** Added missing refresh token validation
+- **Improvement:** Enhanced error handling for expired tokens
+- **Documentation:** Clarified token rotation process
+
+### v1.0.0 (2025-11-01)
+- Initial release
+```
+
+## Troubleshooting
+
+### Database Locked
+```bash
+# Check for concurrent processes
+lsof .claude/skills-database/skills.db
+
+# Wait and retry
+sleep 2
+propagate-skill-update.sh ...
+```
+
+### Permission Denied
+```bash
+# Ensure script is executable
+chmod +x .claude/skills/workflow-codification/propagate-skill-update.sh
+
+# Check database permissions
+chmod 664 .claude/skills-database/skills.db
+```
+
+### Hash Calculation Failure
+```bash
+# Verify file exists and is readable
+ls -lh "$UPDATE_PATH"
+sha256sum "$UPDATE_PATH"
+
+# Check file permissions
+chmod 644 "$UPDATE_PATH"
+```
+
+## Related Documentation
+- Phase 4 Edge Case Tracking: `.claude/skills/workflow-codification/EDGE_CASE_TRACKING.md`
+- Approval Workflow: `.claude/skills/workflow-codification/APPROVAL_WORKFLOW.md`
+- Skill Deployment: `.claude/skills/workflow-codification/DEPLOY_QUICK_REFERENCE.md`
+- Skills Database Schema: `.claude/skills-database/schema-v2.sql`