cc-agentic-framework 1.14.1

package/framework/modules/core/skills/building-skills/ANTI-PATTERNS-MCP.md

@@ -0,0 +1,119 @@
+# Building Claude Skills: MCP Integration Anti-Patterns
+
+## Anti-Pattern 4: Hardcoded MCP Dependencies
+
+### ❌ The Problem
+
+```markdown
+## Instructions
+
+This skill requires the **atlassian MCP** to work.
+
+1. Load atlassian MCP: `mcp__MCP_DOCKER__code-mode ...`
+2. Search for issues
+3. Create new issue
+4. Update issue fields
+```
+
+**Issues:**
+- If MCP unavailable → Skill fails completely
+- No graceful fallback
+- Tight coupling to MCP
+- User can't use skill without MCP
+
+### ✅ Correct Approach: Optional MCP
+
+```markdown
+## MCP Integration (Optional)
+
+This skill works with OR without the **atlassian MCP**:
+
+**With atlassian MCP (Batch Operations):**
+- Faster: Bulk operations in single API call
+- Requires: `atlassian` MCP available
+- Command: `mcp__MCP_DOCKER__code-mode "task" --servers ["atlassian"]`
+
+**Without MCP (Graceful Fallback):**
+- Uses Python scripts: `src/jira/create_jira_story.py`
+- Speed: Slower for large batches
+- Availability: Always works
+- No additional setup needed
+
+## Instructions
+
+1. [Perform task with whatever is available]
+2. If MCP loaded: Use batch operations
+3. If no MCP: Use Python script fallback
+4. Result is the same either way
+```
+
+### Key Principle
+**Never make skill unusable if MCP unavailable. Always provide fallback.**
+
+---
+
+## Preventing Anti-Patterns: Checklist
+
+### Before Creating a Skill
+
+- [ ] Read building-claude-skills (this entire skill)
+- [ ] Review EXAMPLES.md in building-claude-skills
+- [ ] Check ANTI-PATTERNS.md (this file)
+- [ ] Decide scope: Generic or Project-Specific?
+- [ ] Plan directory: .claude/skills/{generic|apmr}/
+- [ ] Plan supporting files needed
+
+### While Creating SKILL.md
+
+- [ ] YAML frontmatter correct
+- [ ] Description < 1024 chars, answers WHEN
+- [ ] Scope declared (generic | project-specific)
+- [ ] Name in gerund form (verb + -ing)
+- [ ] Main file target: < 500 lines
+- [ ] Instructions: 3-5 numbered steps
+- [ ] Common Patterns: 2-4 patterns
+- [ ] See Also: Links to supporting files
+- [ ] No MCP hardcoding
+
+### After Creating Supporting Files
+
+- [ ] EXAMPLES.md exists and is concrete
+- [ ] STANDARDS.md exists if needed
+- [ ] ANTI-PATTERNS.md exists if complex
+- [ ] All referenced files exist (no broken links)
+- [ ] No circular references
+- [ ] Link validator passes
+- [ ] Consistent file organization
+
+### Before Submitting
+
+- [ ] Syntax validation: YAML, markdown
+- [ ] Scope validation: Correct declaration
+- [ ] Link validation: All references work
+- [ ] Tested: Syntax, scope, invocation
+- [ ] Model tested: Claude 3.5 Sonnet, Opus, Haiku
+- [ ] Checklist complete
+
+---
+
+## Quick Reference: Common Anti-Pattern Fixes
+
+| Anti-Pattern | Fix |
+|---|---|
+| Monolithic SKILL.md | Split into supporting files, keep main < 500 lines |
+| Vague description | Describe WHEN to use, include key features, be specific |
+| Missing scope | Add scope field to YAML frontmatter (generic\|project-specific) |
+| No applicable-projects | Add applicable-projects field (any or apmr) |
+| Hardcoded MCP | Make MCP optional, provide graceful fallback |
+| Project details in generic | Move to separate project-specific skill in apmr/ |
+| Wrong naming | Use gerund form (verb + -ing), lowercase-hyphens |
+| No See Also links | Create supporting files and link from SKILL.md |
+| Circular references | Check links point forward only, not backward |
+| No testing guide | Include testing checklist and example invocations |
+
+---
+
+**Anti-Patterns Category:** MCP Integration & Validation
+**Status:** Phase 1A - Supporting file for building-claude-skills
+**Last Updated:** Dec 6, 2025
+**See Also:** [Structure Anti-Patterns](ANTI-PATTERNS-STRUCTURE.md), [Naming Anti-Patterns](ANTI-PATTERNS-NAMING.md), [Content Anti-Patterns](ANTI-PATTERNS-CONTENT.md)

package/framework/modules/core/skills/building-skills/ANTI-PATTERNS-NAMING.md

@@ -0,0 +1,129 @@
+# Building Claude Skills: Naming Anti-Patterns
+
+## Anti-Pattern 6: Imperative Naming (Violates Gerund Convention)
+
+### ❌ The Problem
+
+```yaml
+name: validate-links      # ← Imperative, wrong
+name: LinkValidator       # ← Class name, wrong
+name: link-validation     # ← Noun form, wrong
+name: link_validator      # ← Underscore, wrong
+```
+
+**Issues:**
+- Inconsistent with official convention
+- Hard to categorize (validate? noun? class?)
+- Doesn't match naming pattern across framework
+- Length check fails
+
+### ✅ Correct: Gerund Form (Verb + -ing)
+
+```yaml
+name: validating-links     # ✅ Correct
+name: formatting-markdown  # ✅ Correct
+name: updating-changelogs  # ✅ Correct
+name: maintaining-governance  # ✅ Correct
+```
+
+### Naming Checklist
+- [ ] Verb + -ing form (gerund)
+- [ ] Lowercase only
+- [ ] Hyphens for word separation
+- [ ] No underscores
+- [ ] No camelCase
+- [ ] Max 64 characters
+
+### Conversion Examples
+| Wrong | Correct |
+|-------|---------|
+| validate-links | validating-links |
+| LinkValidator | validating-links |
+| link-validation | validating-links |
+| checkLinks | validating-links |
+| link_checker | validating-links |
+
+---
+
+## Anti-Pattern 3: Missing or Incorrect Scope Declaration
+
+### ❌ The Problem
+
+**Skill with no scope:**
+```yaml
+---
+name: formatting-markdown
+description: Formats markdown files
+---
+```
+
+**Issues:**
+- Is this reusable in other projects?
+- Can it be shared globally?
+- Does it have dependencies on APM-R?
+- Where should directory be?
+
+**Skill with wrong scope:**
+```yaml
+---
+name: validating-appr-format  # ← Wrong: APM-R specific name
+description: Validates markdown
+scope: generic  # ← Wrong: Says generic but has APM-R dependency
+---
+```
+
+### ✅ Correct Approach
+
+**Generic Skill:**
+```yaml
+---
+name: validating-links
+description: Validates markdown links...
+scope: generic
+applicable-projects: any
+---
+```
+- Directory: `.claude/skills/generic/validating-links/`
+- Can be shared: `~/.claude/skills/generic/`
+- No project-specific code
+
+**Project-Specific Skill:**
+```yaml
+---
+name: ticket-structure-validator
+description: Validates APM-R ticket structure...
+scope: project-specific
+applicable-projects: apmr
+---
+```
+- Directory: `.claude/skills/apmr/ticket-structure-validator/`
+- Shared in: `~/.claude/skills/apmr/`
+- APM-R specific knowledge embedded
+
+### Scope Decision Tree (Use This!)
+
+```
+Is this skill reusable in a DIFFERENT project?
+│
+├─ YES → Generic skill
+│   Directory: .claude/skills/generic/
+│   Scope: generic
+│   Applicable-projects: any
+│
+└─ NO → Project-specific skill
+    Does it contain APM-R-specific knowledge?
+    │
+    ├─ YES → Project-specific skill
+    │   Directory: .claude/skills/apmr/
+    │   Scope: project-specific
+    │   Applicable-projects: apmr
+    │
+    └─ NO → Reconsider - should be generic
+```
+
+---
+
+**Anti-Patterns Category:** Naming Conventions
+**Status:** Phase 1A - Supporting file for building-claude-skills
+**Last Updated:** Dec 6, 2025
+**See Also:** [Structure Anti-Patterns](ANTI-PATTERNS-STRUCTURE.md), [Content Anti-Patterns](ANTI-PATTERNS-CONTENT.md)

package/framework/modules/core/skills/building-skills/ANTI-PATTERNS-STRUCTURE.md

@@ -0,0 +1,139 @@
+# Building Claude Skills: Structural Anti-Patterns
+
+## Anti-Pattern 1: Monolithic SKILL.md Files
+
+### ❌ The Problem
+```
+SKILL.md: 2,500 lines
+├── Official guidelines (200 lines)
+├── 20 detailed examples (800 lines)
+├── Complete standards (600 lines)
+├── Advanced patterns (500 lines)
+└── Common mistakes (400 lines)
+
+User loads skill → Gets 2,500 lines of context
+```
+
+### Why This Fails
+- **Token waste:** Loads everything even if only needed 20%
+- **Cognitive overload:** User can't find relevant section
+- **Slower discovery:** Takes longer to get to the point
+- **Hard to maintain:** Changes require editing massive file
+
+### ✅ Correct Approach: Progressive Disclosure
+```
+SKILL.md: 400 lines (overview + key instructions)
+├── Official guidelines (quick reference)
+├── When to use section
+├── Instructions (3-5 steps)
+├── Common patterns (summary)
+└── "See Also" links to supporting files
+
+EXAMPLES.md: 200 lines (on-demand)
+STANDARDS.md: 150 lines (on-demand)
+ANTI-PATTERNS.md: 150 lines (on-demand)
+PATTERNS.md: 200 lines (on-demand)
+
+User loads skill → Gets 400 lines
+→ Loads EXAMPLES.md only if needed (+200 lines)
+→ Loads STANDARDS.md only if needed (+150 lines)
+```
+
+### Key Rule
+**SKILL.md < 500 lines. Everything else in supporting files.**
+
+---
+
+## Anti-Pattern 9: Insufficient Supporting File Organization
+
+### ❌ The Problem
+
+```
+validating-links/
+├── SKILL.md (50 lines) ← Too brief
+├── EXAMPLES.md (1,200 lines) ← Too detailed, should split
+└── [No STANDARDS.md, ANTI-PATTERNS.md]
+```
+
+**Issues:**
+- SKILL.md too brief to be useful
+- EXAMPLES.md too monolithic
+- Missing standards documentation
+- No anti-patterns guide
+
+### ✅ Correct Approach: Balanced Structure
+
+```
+validating-links/
+├── SKILL.md (300 lines)
+│   ├── Overview and when to use
+│   ├── Quick instructions (4 steps)
+│   ├── Key patterns (3 patterns)
+│   └── Links to supporting files
+├── EXAMPLES.md (150 lines)
+│   ├── Example 1: Relative paths (30 lines)
+│   ├── Example 2: External URLs (30 lines)
+│   └── Example 3: Handling typos (30 lines)
+├── STANDARDS.md (100 lines)
+│   ├── Link validation rules
+│   ├── Supported URL types
+│   └── Error categories
+└── ANTI-PATTERNS.md (100 lines)
+    ├── Wrong: Ignoring relative paths
+    ├── Right: Resolve relative to file
+    └── Common mistakes
+```
+
+### Sizing Guidelines
+- SKILL.md: 200-500 lines (overview, quick reference)
+- EXAMPLES.md: 100-300 lines (2-5 concrete examples)
+- STANDARDS.md: 50-200 lines (rules, specifications)
+- ANTI-PATTERNS.md: 50-200 lines (mistakes and fixes)
+- Total: 400-1,200 lines progressive loading
+
+---
+
+## Anti-Pattern 10: Not Following the building-claude-skills Template
+
+### ❌ The Problem
+
+Creating skill without referencing building-claude-skills:
+- Inconsistent structure across skills
+- Different naming in different skills
+- Different supporting file organizations
+- Quality varies widely
+
+### ✅ Correct Approach
+
+**Always use building-claude-skills as template:**
+
+1. Copy SKILL.md structure:
+   - Exact YAML frontmatter format
+   - "When to Use" section
+   - "Quick Start" section
+   - "Instructions" (numbered steps)
+   - "Common Patterns"
+   - "See Also" with supporting files
+
+2. Validate against building-claude-skills checklist:
+   - [ ] SKILL.md < 500 lines
+   - [ ] Description answers WHEN to use
+   - [ ] Scope declared
+   - [ ] Gerund naming
+   - [ ] Progressive disclosure
+   - [ ] No hardcoded MCPs
+   - [ ] All supporting files exist
+
+3. Test against building-claude-skills:
+   - Syntax check
+   - Scope validation
+   - Invocation test
+   - Multiple models
+   - Link validation
+
+---
+
+**Anti-Patterns Category:** Structure & Organization
+**Status:** Phase 1A - Supporting file for building-claude-skills
+**Last Updated:** Dec 6, 2025
+**See Also:** [Naming Anti-Patterns](ANTI-PATTERNS-NAMING.md), [Content Anti-Patterns](ANTI-PATTERNS-CONTENT.md)

package/framework/modules/core/skills/building-skills/EXAMPLES.md

@@ -0,0 +1,330 @@
+# Building Claude Skills: Real-World Examples
+
+## Example 1: Creating validating-links Skill (Generic)
+
+### Planning Phase
+```
+Question: Is this skill reusable across any project?
+Answer: YES - Link validation is universal
+
+Question: Does it require project-specific knowledge?
+Answer: NO - It's pure validation logic
+
+Decision: GENERIC skill
+Directory: .claude/skills/generic/validating-links/
+```
+
+### File Structure
+```
+validating-links/
+├── SKILL.md (300 lines)
+│   ├── YAML frontmatter
+│   ├── When to Use section
+│   ├── Quick Start
+│   ├── Instructions (4 steps)
+│   └── Common Patterns (3 patterns)
+├── EXAMPLES.md (150 lines)
+│   ├── Example 1: Fixing broken relative paths
+│   ├── Example 2: Validating external URLs
+│   └── Example 3: Handling typos in links
+└── STANDARDS.md (100 lines)
+    ├── Link validation rules
+    ├── Supported link types
+    └── Error categories
+```
+
+### SKILL.md Frontmatter
+```yaml
+---
+name: validating-links
+description: Validates markdown links by checking file existence,
+  syntax, and patterns. Use when reviewing documentation or markdown
+  files for broken links, typos, or incorrect URL formats. Returns
+  detailed error report with fix suggestions.
+scope: generic
+applicable-projects: any
+---
+```
+
+### Implementation Timeline
+1. **Design:** 30 minutes (planning, naming, scope decision)
+2. **SKILL.md:** 2 hours (main content, instructions, patterns)
+3. **EXAMPLES.md:** 1 hour (3 detailed examples)
+4. **STANDARDS.md:** 1 hour (rules, specifications)
+5. **Testing:** 1 hour (syntax, scope, invocation, models)
+6. **Total:** ~6 hours for a complete skill
+
+---
+
+## Example 2: Creating ticket-structure-validator (Project-Specific)
+
+### Planning Phase
+```
+Question: Is this skill reusable across any project?
+Answer: NO - Specific to APM-R ticket structure
+
+Question: Does it require project-specific knowledge?
+Answer: YES - Jira field structure, APM-R YAML frontmatter
+
+Decision: PROJECT-SPECIFIC skill
+Directory: .claude/skills/apmr/ticket-structure-validator/
+```
+
+### File Structure
+```
+ticket-structure-validator/
+├── SKILL.md (350 lines)
+│   ├── YAML frontmatter (scope: project-specific)
+│   ├── When to Use section
+│   ├── Quick Start (ticket validation checklist)
+│   ├── Instructions (5 steps)
+│   ├── Common Patterns (4 patterns)
+│   └── See Also (governance rules, registry guide)
+├── EXAMPLES.md (200 lines)
+│   ├── Example 1: Fixing missing YAML frontmatter
+│   ├── Example 2: Validating required fields
+│   └── Example 3: Checking acceptance criteria
+├── STANDARDS.md (150 lines)
+│   ├── APM-R ticket structure requirements
+│   ├── YAML field specifications
+│   └── Validation rules
+└── ANTI-PATTERNS.md (100 lines)
+    ├── Common mistakes
+    ├── Why they fail
+    └── Correct alternatives
+```
+
+### SKILL.md Frontmatter
+```yaml
+---
+name: ticket-structure-validator
+description: Validates APM-R Jira ticket structure, YAML frontmatter,
+  and content format. Use when creating or reviewing tickets before
+  export to Jira. Checks required fields, validates story points,
+  ensures acceptance criteria clarity. Returns validation report with
+  specific fixes.
+scope: project-specific
+applicable-projects: apmr
+---
+```
+
+### Key Differences from Generic Skills
+- References APM-R specific field names (story points, acceptance criteria)
+- Uses APM-R ticket template from framework governance
+- Links to APM-R validation rules
+- NOT reusable in other projects without modification
+
+---
+
+## Example 3: Creating maintaining-framework-governance (Meta-Skill)
+
+### Purpose
+Meta-skill that teaches Claude how to maintain APM-R framework governance while developing all other skills.
+
+### Planning Phase
+```
+Question: Is this skill reusable across any project?
+Answer: PARTIALLY - Governance concept is universal, APM-R rules are specific
+
+Question: Does it require project-specific knowledge?
+Answer: YES - It teaches APM-R governance rules
+
+Decision: PROJECT-SPECIFIC meta-skill (Phase 1A priority)
+Directory: .claude/skills/apmr/maintaining-framework-governance/
+```
+
+### File Structure
+```
+maintaining-framework-governance/
+├── SKILL.md (350 lines)
+│   ├── YAML frontmatter (scope: project-specific)
+│   ├── When to Use section
+│   ├── Quick Start (governance checklist)
+│   ├── Instructions (4 steps for framework decisions)
+│   └── Common Patterns (3 governance patterns)
+├── GOVERNANCE-RULES.md (150 lines)
+│   ├── 6 rules for v11.0
+│   ├── Severity levels
+│   └── Validation procedures
+├── SCOPE-DECISION-TREE.md (100 lines)
+│   ├── Generic vs Project-Specific decision
+│   └── When to create new skills vs update files
+├── REGISTRY-GUIDE.md (100 lines)
+│   ├── Registry.yml structure
+│   ├── Skill metadata
+│   └── Validation
+├── SYMLINK-GUIDE.md (80 lines)
+│   ├── Two-layer symlink strategy
+│   ├── Setup commands
+│   └── Verification
+├── VALIDATION-CHECKLIST.md (100 lines)
+│   ├── Pre-implementation checklist
+│   ├── Mid-implementation validation
+│   └── Post-implementation verification
+└── EXAMPLES.md (150 lines)
+    ├── Governance decision examples
+    ├── Common scenarios
+    └── Framework improvement procedures
+```
+
+### SKILL.md Frontmatter
+```yaml
+---
+name: maintaining-framework-governance
+description: Teach Claude APM-R framework governance rules, scope
+  decisions, registry management, and symlink strategy. Use when
+  improving framework architecture, creating new skills, updating
+  governance, or making architectural decisions. Ensures consistency
+  and quality across all 21 framework skills.
+scope: project-specific
+applicable-projects: apmr
+---
+```
+
+### Why This is Phase 1A Priority
+1. **Foundation for all 20 other skills** - Ensures consistency
+2. **Governance authority** - Teaches how to make framework decisions
+3. **Scope clarity** - Ensures generic vs project-specific distinction
+4. **Quality gate** - Validates framework improvements before implementation
+5. **Future evolution** - Blueprint for maintaining framework as it grows
+
+---
+
+## Example 4: Building Multiple Skills in Sequence (Phase 1B)
+
+### Sequence: Building 3 Skills in Parallel (Weeks 1-2)
+
+#### Skill 1: validating-links (Generic)
+```
+Skill Type: Validation skill
+Dependencies: building-claude-skills (meta-skill)
+Timeline: 6 hours
+Status: Phase 1B, Week 1
+```
+
+#### Skill 2: formatting-markdown (Generic)
+```
+Skill Type: Formatting skill
+Dependencies: building-claude-skills (meta-skill)
+Timeline: 8 hours
+Status: Phase 1B, Week 1-2
+```
+
+#### Skill 3: updating-changelogs (Generic)
+```
+Skill Type: Maintenance skill
+Dependencies: building-claude-skills (meta-skill)
+Timeline: 7 hours
+Status: Phase 1B, Week 2
+```
+
+### Workflow for Each Skill
+
+1. **Plan (30 min):** Use building-claude-skills to design structure
+2. **Write SKILL.md (2 hours):** Follow template from building-claude-skills
+3. **Write Supporting Files (2 hours):** EXAMPLES.md, STANDARDS.md
+4. **Test (1 hour):** Syntax, scope, invocation, multiple models
+5. **Validate (30 min):** Against building-claude-skills checklist
+6. **Commit (15 min):** Git commit with phase info
+
+### Progress Tracking
+
+**Week 1:**
+- Monday: Finish planning all 3 skills
+- Tuesday-Wednesday: Build validating-links
+- Thursday: Build formatting-markdown (50%)
+
+**Week 2:**
+- Monday: Finish formatting-markdown
+- Tuesday-Wednesday: Build updating-changelogs
+- Thursday-Friday: Integration testing, documentation
+
+---
+
+## Example 5: Testing a Skill Across Models
+
+### Test Matrix for validating-links
+
+```
+Invocation: "Use validating-links skill to validate README.md"
+
+Model 1: Claude 3.5 Sonnet
+├─ Request: Basic link validation
+├─ Response: ✅ Works, detailed error report
+├─ Speed: Fast
+└─ Quality: Excellent
+
+Model 2: Claude 3 Opus
+├─ Request: Complex link patterns with regex
+├─ Response: ✅ Works, handles edge cases
+├─ Speed: Medium
+└─ Quality: Excellent
+
+Model 3: Claude 3 Haiku
+├─ Request: Simple link check
+├─ Response: ✅ Works, summary format
+├─ Speed: Very fast
+└─ Quality: Good (appropriate for lightweight checks)
+```
+
+### Expected Outcomes
+- All models can invoke the skill
+- All models follow SKILL.md structure
+- All models provide value at different levels
+- No model-specific failures
+
+---
+
+## Common Scenarios: When to Build New Skills
+
+### Scenario 1: Framework Governance Rule is Scattered
+
+**Problem:** Rule appears in 3 different files
+**Solution:** Create a skill that consolidates the rule
+
+**Example:** "Markdown formatting" rule is in:
+- ai/shared/markdown-formatting-guide.md
+- ai/agents/ai-jira-manager.md
+- README.md
+
+**Create:** `formatting-markdown` skill that becomes single source of truth
+
+### Scenario 2: Quality Gate Needed
+
+**Problem:** No automated validation for common mistakes
+**Solution:** Create a validation skill
+
+**Example:** Tickets often have missing acceptance criteria
+**Create:** `ticket-structure-validator` skill
+
+### Scenario 3: Repetitive Knowledge Work
+
+**Problem:** Same manual process done repeatedly
+**Solution:** Create a skill that automates it
+
+**Example:** Updating changelog requires manual format changes
+**Create:** `updating-changelogs` skill
+
+---
+
+## Directory Organization: Final Checklist
+
+### Generic Skill Checklist
+- [ ] Directory: `.claude/skills/generic/skill-name/`
+- [ ] SKILL.md contains: `scope: generic` and `applicable-projects: any`
+- [ ] No APM-R specific references
+- [ ] Reusable in any project
+- [ ] Can be symlinked globally: `~/.claude/skills/`
+
+### Project-Specific Skill Checklist
+- [ ] Directory: `.claude/skills/apmr/skill-name/`
+- [ ] SKILL.md contains: `scope: project-specific` and `applicable-projects: apmr`
+- [ ] APM-R governance and knowledge embedded
+- [ ] Not reusable without project context
+- [ ] Symlinked only within APM-R: `~/.claude/skills/apmr/`
+
+---
+
+**Example Status:** Last updated Dec 4, 2025
+**Reference:** building-claude-skills SKILL.md
+**Next Step:** Use these examples when building Phase 1B skills