cc-agentic-framework 1.14.1

package/framework/modules/core/skills/building-framework/SCOPE-DECISION-TREE.md

@@ -0,0 +1,284 @@
+# Scope Decision Reference
+
+## Generic vs Project-Specific Decision Framework
+
+### Step 1: Test for Generic Reusability
+
+**Question: Can this work in ANY project without modification?**
+
+```
+Test scenarios:
+├─ Different tech stack? (React vs Angular vs Vue)
+├─ Different domain? (E-commerce vs Healthcare vs Finance)
+├─ Different tools? (GitHub vs GitLab vs Bitbucket)
+└─ Different team? (No APM-R context needed)
+
+ALL YES → GENERIC
+ANY NO → Continue to Step 2
+```
+
+**Generic Indicators:**
+- No hardcoded project names
+- No project-specific field names
+- No project-specific workflow steps
+- No project-specific tool configurations
+- Pure patterns and best practices
+
+**Examples:**
+- ✅ `validating-links` - Works for any markdown
+- ✅ `formatting-markdown` - Universal markdown syntax
+- ✅ `enforcing-quality-standards` - Universal code quality
+- ✅ `managing-git-workflows` - Standard git operations
+
+---
+
+### Step 2: Test for APM-R Specificity
+
+**Question: Does this require APM-R knowledge to function?**
+
+```
+APM-R Dependencies Check:
+├─ Jira field mappings (customfield_*, APM-R labels)
+├─ Confluence space structure (WA space, page hierarchy)
+├─ APM-R workflow phases (milestones, sprint naming)
+├─ Framework governance rules (v11.x specific)
+├─ APM-R ticket structure (epic/story/task hierarchy)
+└─ MCP server configuration (APM-R Jira/Confluence instances)
+
+ANY YES → PROJECT-SPECIFIC
+ALL NO → GENERIC (back to Step 1)
+```
+
+**Project-Specific Indicators:**
+- References `customfield_*` Jira fields
+- Uses APM-R milestone codes (Jun2025, Dec2025)
+- Requires WA Confluence space knowledge
+- Implements framework v11.x governance
+- Uses APM-R specific MCP configurations
+
+**Examples:**
+- ✅ `maintaining-framework-governance` - v11.x rules
+- ✅ `integrating-jira-confluence` - APM-R MCP config
+- ✅ `managing-framework-phases` - APM-R workflow
+- ✅ `integrating-jira` - APM-R Jira workflows
+
+---
+
+### Step 3: Hybrid Approach Decision
+
+**Question: Is there a generic core with APM-R extensions?**
+
+```
+Skill structure analysis:
+├─ Core patterns/rules → Generic (90% of skill)
+├─ Configuration/mappings → APM-R specific (10% of skill)
+└─ Can they be separated cleanly?
+
+YES → HYBRID STRUCTURE
+NO → Back to Step 1 or 2 for pure decision
+```
+
+**Hybrid Structure Pattern:**
+
+```
+apmr-{name}-{capability}/
+├── SKILL.md (when to use, integration)
+├── PATTERNS.md (generic patterns - reusable)
+├── RULES.md (generic rules - reusable)
+├── APMR-CONFIG.md (APM-R specific configuration)
+└── EXAMPLES.md (mixed examples)
+```
+
+**Hybrid Example: Jira-Confluence Integration**
+- Generic: Markdown ↔ Jira ↔ ADF conversion rules (CONVERSION-RULES.md)
+- APM-R: Field mappings, MCP endpoints, space config (APMR-CONFIG.md)
+
+**Decision:** Use `apmr-` prefix (project-specific) but separate generic parts
+
+---
+
+## Scope Impact on Deployment
+
+### Generic Skills (`generic-shared-*`)
+
+**Source Location:**
+```
+ai/skills/{category}/generic-shared-{name}-{capability}/
+```
+
+**Deployment Locations (auto-synced):**
+```
+.claude/skills/generic-shared-{name}-{capability}/  (local)
+~/{project}/.claude/skills/generic-shared-{name}-{capability}/  (workspace)
+~/.claude/skills/generic-shared-{name}-{capability}/  (global, optional)
+```
+
+**Reusability:**
+- ✅ apm-r-ai-agentic-framework
+- ✅ apm-r-app
+- ✅ apm-r-be
+- ✅ Infrastructure
+- ✅ Any external project
+
+---
+
+### Project-Specific Skills (`apmr-*`)
+
+**Source Location:**
+```
+ai/skills/{category}/apmr-{name}-{capability}/
+```
+
+**Deployment Locations (auto-synced):**
+```
+.claude/skills/apmr-{name}-{capability}/  (local)
+~/{project}/.claude/skills/apmr-{name}-{capability}/  (workspace)
+```
+
+**Reusability:**
+- ✅ apm-r-ai-agentic-framework (framework repo)
+- ✅ apm-r-app (via workspace symlink)
+- ✅ apm-r-be (via workspace symlink)
+- ❌ External projects (APM-R specific)
+
+---
+
+## Common Scope Decision Scenarios
+
+### Scenario 1: Validation Skill
+
+```
+Skill: Link validation for markdown files
+
+Analysis:
+- Works for any markdown project? YES
+- Requires APM-R knowledge? NO
+- Project-specific config? NO
+
+Decision: GENERIC
+Name: generic-shared-validating-links-guard
+```
+
+---
+
+### Scenario 2: Framework Governance
+
+```
+Skill: Maintain framework governance rules
+
+Analysis:
+- Works for any project? NO (v11.x specific)
+- Requires APM-R knowledge? YES (framework structure)
+- Project-specific rules? YES (6 governance rules)
+
+Decision: PROJECT-SPECIFIC
+Name: building-framework
+```
+
+---
+
+### Scenario 3: Jira Integration (Hybrid)
+
+```
+Skill: Jira-Confluence integration patterns
+
+Analysis:
+- Core conversion rules? GENERIC (Markdown ↔ Jira ↔ ADF)
+- MCP configuration? APM-R SPECIFIC (endpoints, auth)
+- Field mappings? APM-R SPECIFIC (customfield_*)
+- Overall skill? 70% generic, 30% APM-R
+
+Decision: PROJECT-SPECIFIC (with hybrid structure)
+Name: apmr-integrating-integrating-jira
+Structure:
+  - CONVERSION-RULES.md (generic, reusable)
+  - APMR-CONFIG.md (APM-R specific)
+```
+
+---
+
+### Scenario 4: Quality Standards
+
+```
+Skill: Enforce code quality standards
+
+Analysis:
+- SOLID principles? GENERIC
+- DRY violations? GENERIC
+- Anti-patterns? GENERIC
+- APM-R specific rules? NO
+
+Decision: GENERIC
+Name: verifying-quality
+```
+
+---
+
+## Scope Decision Checklist
+
+Before creating a skill, answer these questions:
+
+**Generic Scope Indicators:**
+- [ ] No project names in content
+- [ ] No hardcoded paths/URLs
+- [ ] No project-specific field names
+- [ ] Works in any similar project
+- [ ] Pure patterns/best practices
+- [ ] Universal tool usage (git, markdown, etc.)
+
+**Project-Specific Scope Indicators:**
+- [ ] References APM-R concepts
+- [ ] Uses customfield_* or APM-R labels
+- [ ] Requires framework v11.x knowledge
+- [ ] Implements APM-R workflows
+- [ ] Uses APM-R MCP configurations
+- [ ] Tied to specific project structure
+
+**Hybrid Structure Indicators:**
+- [ ] Has generic core (patterns/rules)
+- [ ] Has APM-R extensions (config/mappings)
+- [ ] Can separate cleanly (70%+ generic)
+- [ ] Benefits from shared generic knowledge
+
+---
+
+## Naming Convention by Scope
+
+### Generic Shared Skills
+
+**Format:** `generic-shared-{name}-{capability}`
+
+**Examples:**
+- `generic-shared-validating-links-guard`
+- `validating-markdown`
+- `verifying-quality`
+- `generic-shared-loading-context-pattern-knowledge`
+- `building-skills`
+
+**Prefix:** `generic-shared-` signals reusability
+
+---
+
+### Project-Specific Skills
+
+**Format:** `apmr-{name}-{capability}`
+
+**Examples:**
+- `building-framework`
+- `apmr-integrating-integrating-jira`
+- `apmr-managing-framework-planning-phases`
+- `integrating-jira`
+- `apmr-managing-framework-versions-workflow`
+
+**Prefix:** `apmr-` signals APM-R specific
+
+---
+
+## Version History
+
+**Version:** 1.0
+**Created:** 2025-12-07 (v11.2 governance refactor)
+**Purpose:** Extract scope decision knowledge from main SKILL.md
+**Related Files:**
+- SKILL.md (main governance skill)
+- DECISION-TREES.md (general decision framework)

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

@@ -0,0 +1,210 @@
+---
+id: building-framework
+name: maintaining-framework-governance
+description: Maintain APM-R framework governance, rules, and consistency. Use when making architectural decisions, creating skills, or validating framework improvements.
+scope: project-specific
+applicable-projects: apmr
+module: core
+capabilities-provided:
+  - framework-governance
+  - framework-development
+  - planning-phases
+# Claude Code v2.1 features
+context: fork
+tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Maintaining Framework Governance
+
+## When to Use This Skill
+
+You're working on **APM-R framework improvements** and need to:
+- Make architectural decisions (new skill vs update file)
+- Ensure skill scope is correct (generic vs project-specific)
+- Maintain framework governance rules
+- Keep registry.yml synchronized
+- Validate framework improvements before implementation
+- Consolidate scattered framework knowledge
+
+**This is the FOUNDATION meta-skill** - enables governance decisions for all skills and framework evolution.
+
+---
+
+## MCP Integration
+
+This skill uses **NO MCPs** - works with built-in tools only.
+- No dependencies required
+- No additional setup needed
+- Full functionality with built-in tools
+
+---
+
+## Quick Reference: APM-R v11.2 Governance Rules
+
+### Rule 1: Pure Agent Pattern
+**All generic project knowledge lives in context files, not agents.**
+- Agents generic, work with any project by changing context
+- No project-specific details in agent files
+
+### Rule 2: Skills as Single Source of Truth
+**When knowledge scattered in 3+ places, create a skill to consolidate it.**
+- Create skill when scattered in 3+ locations
+- Update existing file if only 1-2 locations
+
+### Rule 3: Scope Declaration (MANDATORY)
+**Every skill declares scope: generic | project-specific**
+- Generic: Reusable in any project (`generic-shared-*`)
+- Project-specific: APM-R only (`apmr-*`)
+
+### Rule 4: Symlink Strategy
+**Framework repo is single source of truth, symlinked at two layers**
+- Source: `ai/skills/`, auto-synced to `.claude/skills/`
+- Always edit source, never deployment
+
+### Rule 5: Token Budget
+**Skills optimized for lazy-loading and token efficiency**
+- Individual skill < 2,500 tokens
+- SKILL.md < 500 lines, supporting files on-demand
+
+### Rule 6: Quality Gates
+**Skills validate outputs and provide structured feedback**
+- Clear pass/fail criteria, actionable fix suggestions
+- Use `verifying-quality` for validation
+
+**See:** GOVERNANCE-RULES.md for complete rule definitions and implementation guidance
+
+---
+
+## Decision Framework: Should I Create a Skill?
+
+### Quick Decision Questions
+
+**Q1: Is knowledge scattered in 3+ locations?**
+- YES → Create skill | NO → Update file
+
+**Q2: Referenced by 2+ agents or quality gate needed?**
+- YES → Create skill | NO → Update file
+
+**Q3: Is it reusable outside APM-R?**
+- YES → Generic skill (`generic-shared-*`) | NO → Project-specific (`apmr-*`)
+
+**See:** DECISION-TREES.md for complete decision framework and visualization
+
+---
+
+## Instructions: Making Governance Decisions
+
+### Step 1: Analyze the Improvement
+1. What needs to improve?
+2. How many files/locations affected?
+3. Generic or project-specific scope?
+
+### Step 2: Apply Governance Rules
+- Rule 1: No project knowledge in agents
+- Rule 2: Scattered in 3+ places → skill
+- Rule 3: Scope declared explicitly
+- Rule 4: Source in `ai/skills/`, auto-synced
+- Rule 5: Token budget compliant
+- Rule 6: Quality gate if applicable
+
+### Step 3: Make Decision
+- **3+ locations** → Create skill
+- **Quality gate** → Create skill
+- **1-2 locations** → Update file
+- **Reusable outside APM-R** → Generic skill
+- **APM-R specific** → Project-specific skill
+
+### Step 4: Build the Skill
+Use `building-skills` for:
+- SKILL.md structure and formatting
+- Supporting file organization
+- Progressive disclosure pattern
+- Token budget compliance
+
+**Note:** This skill handles "Should I?" - building-claude-skills handles "How to?"
+
+---
+
+## Scope Decision: Generic vs Project-Specific
+
+**Generic (`generic-shared-*`):**
+- Works in ANY project without modification
+- No APM-R specific references
+- Examples: validating-links, formatting-markdown, enforcing-quality-standards
+
+**Project-Specific (`apmr-*`):**
+- Requires APM-R knowledge (Jira fields, Confluence spaces, framework rules)
+- Examples: maintaining-framework-governance, integrating-jira-confluence
+
+**See:** SCOPE-DECISION-TREE.md for complete decision framework, test scenarios, and examples
+
+---
+
+## Common Skill Creation Patterns
+
+**Pattern 1: Consolidation** - Same knowledge in 3+ places
+**Pattern 2: Quality Gate** - Automated validation needed
+**Pattern 3: Decision Authority** - Inconsistent decisions across framework
+**Pattern 4: Repetitive Work** - Same manual process repeated
+
+**See:** DECISION-TREES.md for detailed patterns and real-world scenarios
+
+---
+
+## Checklist: Before Creating New Skill
+
+**Governance:**
+- [ ] Knowledge scattered in 3+ places?
+- [ ] All 6 governance rules satisfied?
+- [ ] Scope correctly declared (generic or project-specific)?
+- [ ] Will be used by 2+ agents/files?
+
+**Implementation:**
+- [ ] Used decision tree (DECISION-TREES.md)?
+- [ ] Checked scope decision (SCOPE-DECISION-TREE.md)?
+- [ ] Using building-claude-skills for structure?
+- [ ] Token budget < 2,500 tokens?
+
+---
+
+## Related Skills & Supporting Files
+
+**How to Build Skills:**
+- `building-skills` - Skill structure, templates, patterns
+- This skill answers "Should I?" - building-claude-skills answers "How to?"
+
+**Quality Validation:**
+- `verifying-quality` - Quality gates and validation
+
+**Supporting Files (This Skill):**
+- GOVERNANCE-RULES.md - Complete 6 rules with implementation
+- DECISION-TREES.md - Decision frameworks and patterns
+- SCOPE-DECISION-TREE.md - Generic vs project-specific decision framework
+
+**Framework Documentation:**
+- ai/registry.yml - Single source of truth for metadata
+- ai/framework/framework-governance.md - Extended governance rules
+- routes.yml - Filesystem map
+
+---
+
+## Key Takeaways
+
+1. **Six Rules:** Pure agents, skills consolidate (3+ locations), scope declared, symlinks, token budgets, quality gates
+2. **Decision Framework:** 3+ locations OR quality gate → skill
+3. **Scope:** Generic (reusable) vs Project-specific (APM-R only)
+4. **Separation:** This skill ("Should I?") + building-claude-skills ("How to?") + quality-standards (validation)
+5. **Token Efficiency:** Progressive disclosure enables 25-35% session savings
+
+---
+
+**Skill Version:** 1.1
+**Last Updated:** 2025-12-07 (v11.2 refactor - reduced from 397 to ~180 lines)
+**Pair with:** building-claude-skills (how to build), quality-standards (validation)
+**Used by:** ai-framework-manager, ai-framework-developer

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

@@ -0,0 +1,219 @@
+# Building Claude Skills: Content Anti-Patterns
+
+## Anti-Pattern 2: Vague or Missing Description Field
+
+### ❌ The Problem
+
+```yaml
+---
+name: formatting-markdown
+description: A skill for formatting markdown files.
+---
+```
+
+**Issues:**
+- When should user invoke this?
+- What counts as "formatting"?
+- Does it validate? Convert? Beautify?
+- Is it for documentation? Code? Tickets?
+
+### Real Examples of Bad Descriptions
+```yaml
+description: This skill helps with stuff.
+```
+→ What stuff? Too vague.
+
+```yaml
+description: Advanced markdown formatting with support for tables,
+  code blocks, headers, lists, and more including special characters...
+```
+→ Too detailed, exceeds 1024 char limit.
+
+```yaml
+description: Formats markdown.
+```
+→ Too brief, no context about when to use.
+
+### ✅ Correct Approach
+
+```yaml
+---
+name: formatting-markdown
+description: Standardizes markdown file formatting across the
+  framework. Use when reviewing or preparing markdown files to ensure
+  consistent header levels, list styles, code block syntax, and link
+  formatting. Returns detailed formatting report with automatic fixes.
+---
+```
+
+**Elements:**
+1. **What it does** (Standardizes markdown formatting)
+2. **When to use** (When reviewing or preparing markdown files)
+3. **Key standards** (Headers, lists, code blocks, links)
+4. **Output** (Formatting report with fixes)
+
+### Formula: Description Structure
+```
+{What} {aspect}. Use when {trigger condition}. {Key features}. {Output}.
+```
+
+Example:
+```
+{Validates} {markdown links}. Use when {reviewing documentation}.
+{Checks file existence, syntax, patterns}. {Returns error report with fixes}.
+```
+
+---
+
+## Anti-Pattern 5: Generic Skills with Project-Specific Details
+
+### ❌ The Problem
+
+```markdown
+# formatting-markdown
+
+Formats markdown files for APM-R framework.
+
+## APM-R Specific Rules
+
+- Ticket files go in backlog/_workflow/
+- Use YAML frontmatter per APM-R SKILL.md format
+- Context files in ai/context/ follow strict naming
+- Framework governance rules in ai/framework/
+```
+
+**Issues:**
+- Not reusable in other projects
+- References APM-R-specific directories
+- Can't be shared globally
+- Mislabeled as "generic"
+
+### ✅ Correct Approach: Separate Skills
+
+**Generic Skill:**
+```markdown
+# formatting-markdown
+
+Standardizes markdown file formatting across any project.
+
+## General Markdown Standards
+
+- Consistent header levels (H1 for title, H2 for sections)
+- Unified list markers (- for bullets, 1. for ordered)
+- Consistent code block syntax (markdown, python, etc.)
+- Link formatting ([text](url) style)
+```
+
+**APM-R Project-Specific Skill:**
+```yaml
+---
+name: formatting-markdown-apmr
+scope: project-specific
+applicable-projects: apmr
+---
+
+# Formatting Markdown for APM-R
+
+Uses generic formatting-markdown skill + APM-R specific rules.
+
+## APM-R Specific Rules
+
+- Ticket files use YAML frontmatter
+- Context files follow strict naming convention
+- Framework governance docs in ai/framework/
+```
+
+### Rule
+**Generic skills: No project references. APM-R variant: Separate skill in apmr/ directory.**
+
+---
+
+## Anti-Pattern 7: Circular or Missing "See Also" Links
+
+### ❌ The Problem
+
+```markdown
+## See Also
+- [Examples](EXAMPLES.md)     # ← File doesn't exist yet
+- [Standards](STANDARDS.md)   # ← File doesn't exist yet
+- [Self](SKILL.md)            # ← Circular reference
+```
+
+**Issues:**
+- Broken links block commits
+- User can't access referenced files
+- Circular references confuse navigation
+- Maintenance nightmare
+
+### ✅ Correct Approach
+
+**In SKILL.md:**
+```markdown
+## See Also
+- [Real-world examples](EXAMPLES.md) - Step-by-step walkthroughs
+- [Detailed standards](STANDARDS.md) - Validation rules and specs
+- [Common mistakes](ANTI-PATTERNS.md) - Anti-patterns and fixes
+```
+
+**Verification:**
+1. Every referenced file exists ✅
+2. No circular references (A → B → A) ✅
+3. Links use relative paths (../...) ✅
+4. Tested with link validator before commit ✅
+
+---
+
+## Anti-Pattern 8: No Testing Documentation
+
+### ❌ The Problem
+
+```markdown
+# validating-links
+
+Validates links.
+
+[No testing section]
+[No examples of invocation]
+[No expected outputs shown]
+[No failure scenarios documented]
+```
+
+**Issues:**
+- User doesn't know how to test the skill
+- Unclear expected behavior
+- Hard to debug failures
+- No validation checklist
+
+### ✅ Correct Approach: Include Testing Guidance
+
+```markdown
+## Testing This Skill
+
+### Test Checklist
+- [ ] Syntax validation: Valid YAML frontmatter
+- [ ] Scope validation: Correct scope declaration
+- [ ] Link validation: All references work
+- [ ] Invocation test: Works with Claude Code
+- [ ] Model testing: Test with Sonnet, Opus, Haiku
+
+### Example Invocation
+"Use validating-links skill to validate framework/README.md"
+
+### Expected Output
+- List of broken links (if any)
+- Suggested fixes
+- Summary statistics
+
+### Common Test Scenarios
+1. Valid file with no broken links → Returns ✅ all-good
+2. File with 1-2 broken links → Returns details and fixes
+3. File with complex relative paths → Handles correctly
+4. File with external URLs → Validates or skips appropriately
+```
+
+---
+
+**Anti-Patterns Category:** Content & Documentation
+**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), [MCP Anti-Patterns](ANTI-PATTERNS-MCP.md)