cc-agentic-framework 1.14.1

package/framework/modules/core/skills/verifying-quality/QUALITY-CHECKLIST.md

@@ -0,0 +1,181 @@
+# Quality Checklist
+
+Domain-specific quality checklists for pre-submission validation.
+
+---
+
+## Universal Quality Criteria
+
+### Completeness
+- ✅ All required sections present
+- ✅ No placeholders or TODOs
+- ✅ Dependencies identified and linked
+- ✅ Acceptance criteria defined (where applicable)
+
+### Clarity
+- ✅ Purpose clearly stated
+- ✅ Context provided (background, rationale)
+- ✅ Technical scope defined
+- ✅ Success metrics identified
+
+### Conciseness
+- ✅ No unnecessary verbosity
+- ✅ Focused on essentials
+- ✅ Appropriate level of detail for audience
+- ✅ No redundant information
+
+### Format Compliance
+- ✅ Follows template structure
+- ✅ Proper markdown formatting
+- ✅ YAML frontmatter complete (if required)
+- ✅ Cross-references valid
+
+---
+
+## Stories & Tasks Checklist
+
+Before submitting a story or task:
+
+- ✅ User story format (AS/WANT/SO THAT) or clear task description
+- ✅ Context section (2-3 paragraphs)
+- ✅ Requirements list (4-6 bullets)
+- ✅ Technical notes (3-5 bullets, high-level)
+- ✅ 8-12 acceptance criteria (specific, testable)
+- ✅ Story points assigned (1-8)
+- ✅ Parent epic linked
+
+---
+
+## Epics Checklist
+
+Before submitting an epic:
+
+- ✅ Business value clearly stated (2-3 sentences)
+- ✅ Technical scope with implementation steps
+- ✅ Concise (30-50 lines total)
+- ✅ Child stories listed
+- ✅ Minimal acceptance criteria (epic-level only)
+
+---
+
+## Reports & Documentation Checklist
+
+Before submitting reports or documentation:
+
+- ✅ Executive summary present
+- ✅ Key metrics highlighted
+- ✅ Sections logically organized
+- ✅ Actionable insights provided
+- ✅ Sources/references included
+
+---
+
+## Code & Implementation Checklist
+
+Before submitting code:
+
+- ✅ Follows SOLID and DRY principles
+- ✅ Comprehensive tests written
+- ✅ Error handling included
+- ✅ Security considerations addressed
+- ✅ Documentation/comments where needed
+
+---
+
+## CLI Tools Checklist
+
+Before submitting CLI commands:
+
+### Test Layers
+- ✅ Unit tests for isolated logic (path resolution, data transformation)
+- ✅ Integration tests for library functions
+- ✅ CLI surface tests (actual command execution)
+- ✅ Environment variation tests (no TTY, outside project, paths with spaces)
+
+### User Context
+- ✅ Tests run from simulated user project, not CLI source
+- ✅ Path resolution tested from user's perspective
+- ✅ Templates found when running as npm package
+
+### State Verification
+- ✅ Side effects verified (manifest updates, file creation)
+- ✅ Round-trip tests (create → verify → use)
+- ✅ Cross-command path consistency
+
+### Output Quality
+- ✅ No "undefined", "null", "Invalid Date" in output
+- ✅ No stack traces for expected user errors
+- ✅ Paths shown are user-relevant
+
+### Feature Completeness
+- ✅ All documented flags actually work
+- ✅ All documented commands implemented
+- ✅ Error messages are actionable
+
+---
+
+## Defensive Coding Checklist
+
+Before submitting user-facing code:
+
+### Null-Safe Display
+- ✅ All displayed values handle undefined/null
+- ✅ Dates default to "Unknown" if missing
+- ✅ Versions default to "(version unknown)" if missing
+- ✅ Irregular plurals have explicit mappings
+
+### Path Context
+- ✅ PathContext interface defines all path types
+- ✅ No ambiguous "root" or "basePath" variables
+- ✅ Related commands use shared path constants
+
+### Data Normalization
+- ✅ Parsers have normalization at boundary
+- ✅ Date objects converted to strings before validation
+- ✅ Tests use realistic input
+
+### Error Quality
+- ✅ User errors show clean message (no stack trace)
+- ✅ Error messages contain user-relevant paths
+- ✅ Error messages suggest fix when possible
+
+### Environment
+- ✅ TTY checked before interactive prompts
+- ✅ Project context errors handled gracefully
+- ✅ Paths quoted in shell commands
+
+---
+
+## Pre-Submission Validation
+
+**Before finalizing any deliverable, run this 8-point checklist:**
+
+1. ✅ **Read through completely** - Does it make sense end-to-end?
+2. ✅ **Check against template** - All required sections present?
+3. ✅ **Verify cross-references** - All links valid and not broken?
+4. ✅ **Validate format** - Markdown/YAML syntax correct?
+5. ✅ **Test acceptance criteria** - Specific, measurable, and testable?
+6. ✅ **Review for clarity** - Would someone unfamiliar understand it?
+7. ✅ **Check conciseness** - Can anything be removed without losing value?
+8. ✅ **Confirm completeness** - All requirements covered end-to-end?
+
+---
+
+## Common Quality Issues & Fixes
+
+| Issue | Why It Matters | How to Fix |
+|-------|----------------|-----------|
+| Vague acceptance criteria ("Make it work", "Improve performance") | Undefined done, impossible to verify | Make criteria specific and measurable (e.g., "API returns 200 status for valid requests") |
+| Missing context/rationale (no "why") | Reader doesn't understand importance | Add 2-3 sentences explaining background and business value |
+| Excessive verbosity (>100 lines for stories) | Too much detail, loses focus | Trim unnecessary details, focus on essentials only |
+| Code snippets in tickets | Tickets become implementation details | Replace code with pattern references instead |
+| Broken cross-references | Documentation becomes unreliable | Validate all cross-references before submitting |
+| Metadata in body instead of YAML | Inconsistent structure | Move metadata to YAML frontmatter |
+| Horizontal slices (API/UI/DB layers) | Can't deploy or deliver value independently | Create vertical slices with complete features |
+| Stories >8 points | Too large for sprint, high risk | Break large stories into smaller ones (≤8 points) |
+
+---
+
+**Source:** Consolidated from ai/shared/quality-standards.md + CLI QA findings
+**Version:** 2.0
+**Updated:** 2025-12-30

package/framework/modules/core/skills/verifying-quality/SKILL.md

@@ -0,0 +1,275 @@
+---
+id: verifying-quality
+name: enforcing-quality-standards
+description: Enforce quality standards via evaluation, anti-patterns, checklists. Use after task completion or during code review to validate work against universal quality criteria.
+scope: generic
+applicable-projects: all
+module: core
+capabilities-provided:
+  - quality-assurance
+# Claude Code v2.1 features
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+hooks:
+  PostToolUse: .claude/hooks/post-write-validate.sh
+---
+
+# Enforcing Quality Standards
+
+## When to Use This Skill
+
+Use this skill to enforce quality standards in three scenarios:
+
+1. **After task completion** - Before finalizing deliverables (tickets, code, documentation)
+2. **During code review** - Validate implementation against patterns and best practices
+3. **Framework maintenance** - Ensure framework artifacts follow governance standards
+
+This skill consolidates five quality frameworks:
+- **Anti-patterns detection** - Identify common mistakes across code, tickets, and framework
+- **Quality checklists** - Pre-submission validation for all deliverable types
+- **Self-evaluation protocol** - Post-task improvements and system refinements
+- **CLI testing standards** - Test layers, user context simulation, state verification
+- **Defensive coding patterns** - Null-safe output, path context, error quality
+
+---
+
+## Quick Start
+
+### For Code Review (3 min)
+1. Load [ANTI-PATTERNS.md](ANTI-PATTERNS.md) - Check code against SOLID, DRY, error handling
+2. Verify no hardcoded values, untestable code, or tight coupling
+3. Approve if anti-patterns absent
+
+### For Ticket/Story Validation (2 min)
+1. Load [QUALITY-CHECKLIST.md](QUALITY-CHECKLIST.md) - Run pre-submission checklist
+2. Verify acceptance criteria specific/testable, story points ≤8, proper structure
+3. Return feedback with required fixes
+
+### For Post-Task Self-Check (5 min)
+1. Load [EVALUATION-PROTOCOL.md](EVALUATION-PROTOCOL.md) - Run self-evaluation
+2. Identify root causes of issues or confusion
+3. Recommend specific improvements to prevent recurrence
+
+### For CLI Tool Testing (10 min)
+1. Load [CLI-TESTING.md](CLI-TESTING.md) - Test layer requirements
+2. Verify tests cover: unit logic, integration, CLI surface, state changes, environments
+3. Check for user-context testing (not just developer-context)
+
+### For Defensive Code Review (5 min)
+1. Load [DEFENSIVE-CODING.md](DEFENSIVE-CODING.md) - Defensive patterns checklist
+2. Verify null-safe output, path context awareness, error message quality
+3. Check data normalization at boundaries
+
+---
+
+## Core Quality Dimensions
+
+This skill enforces quality across four dimensions:
+
+### 1. Completeness
+- All required sections present
+- No placeholders or TODOs
+- Dependencies identified and linked
+- Acceptance criteria defined (where applicable)
+
+### 2. Clarity
+- Purpose clearly stated
+- Context provided (background, rationale)
+- Technical scope defined
+- Success metrics identified
+
+### 3. Conciseness
+- No unnecessary verbosity
+- Focused on essentials
+- Appropriate detail level for audience
+- No redundant information
+
+### 4. Format Compliance
+- Template structure followed
+- Markdown formatting correct
+- YAML frontmatter complete (if required)
+- Cross-references valid
+
+---
+
+## Instructions
+
+### Instruction 1: Identify Quality Category
+Determine what you're evaluating:
+- **Code:** Use code anti-patterns from ANTI-PATTERNS.md
+- **Tickets/Stories:** Use quality checklist from QUALITY-CHECKLIST.md
+- **Framework artifacts:** Use both anti-patterns and checklist
+- **Post-task reflection:** Use evaluation protocol from EVALUATION-PROTOCOL.md
+- **CLI tools/commands:** Use CLI testing standards from CLI-TESTING.md
+- **Defensive coding review:** Use defensive patterns from DEFENSIVE-CODING.md
+
+### Instruction 2: Load Supporting Material
+Based on category, load relevant file:
+- **Code review:** See [ANTI-PATTERNS.md](ANTI-PATTERNS.md) for SOLID, DRY, error handling, configuration, testability patterns
+- **Ticket validation:** See [QUALITY-CHECKLIST.md](QUALITY-CHECKLIST.md) for stories, epics, reports, code checklists
+- **Self-evaluation:** See [EVALUATION-PROTOCOL.md](EVALUATION-PROTOCOL.md) for post-task improvement process
+- **CLI testing:** See [CLI-TESTING.md](CLI-TESTING.md) for test layers, user context, state verification, environment variation
+- **Defensive coding:** See [DEFENSIVE-CODING.md](DEFENSIVE-CODING.md) for null-safe output, path context, error quality
+- **Real examples:** See [EXAMPLES.md](EXAMPLES.md) for concrete before/after scenarios
+
+### Instruction 3: Run Validation
+Apply standards against the deliverable:
+- Check all items from relevant checklist
+- Identify violations (anti-patterns present, checklist items missing)
+- Note severity (blocker vs. nice-to-have)
+
+### Instruction 4: Report Issues
+For each issue found:
+- **What:** Specific violation or missing element
+- **Why:** Impact on quality or effectiveness
+- **Fix:** Concrete action to resolve (file path, section, exact changes)
+
+### Instruction 5: Apply Improvements
+If user approves or issues are self-evident:
+- Update the artifact
+- Verify fix resolves the issue
+- Confirm changes with user
+
+---
+
+## Common Patterns
+
+### Pattern 1: Code Quality Review
+**Scenario:** Reviewing implementation PR for quality issues
+
+**Process:**
+1. Check ANTI-PATTERNS.md Code section
+2. Verify SOLID principles (Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion)
+3. Check DRY (no copy-paste, extract helpers)
+4. Verify error handling (specific exceptions, user-friendly messages, input validation)
+5. Confirm configuration externalized (no hardcoded secrets, magic numbers)
+6. Validate testability (dependency injection, pure functions, mockable interfaces)
+
+**Report format:** "Found 3 issues: [list each] → Recommendations: [fix for each]"
+
+### Pattern 2: Ticket Quality Validation
+**Scenario:** Reviewing ticket before export to Jira
+
+**Process:**
+1. Determine ticket type (story, epic, task, bug)
+2. Load relevant checklist from QUALITY-CHECKLIST.md
+3. Verify all required sections present and complete
+4. Confirm acceptance criteria specific/testable
+5. Check story points appropriate (≤8)
+6. Validate no code snippets (reference patterns instead)
+
+**Report format:** "Issues found: [missing sections] → Required fixes: [checklist items]"
+
+### Pattern 3: Post-Task Self-Improvement
+**Scenario:** After completing task, identify lessons learned
+
+**Process:**
+1. Load EVALUATION-PROTOCOL.md
+2. Answer: Did anything go wrong? (errors, warnings, unclear instructions)
+3. Identify root cause (missing info, outdated context, unclear workflow)
+4. Recommend specific fix (file path, section, exact changes)
+5. Apply fix if approved
+
+**Report format:** "Issue: [what went wrong] → Root cause: [why] → Fix: [specific file + section + changes]"
+
+### Pattern 4: Framework Governance Validation
+**Scenario:** Reviewing framework artifacts (agents, skills, context files)
+
+**Process:**
+1. Check against code anti-patterns (no project-specific content in agents)
+2. Verify agent purity (all project content in context files)
+3. Check for duplication (no copy-pasted content across files)
+4. Validate cross-references (links up-to-date, no broken references)
+5. Confirm structure follows standards (naming, frontmatter, organization)
+
+**Report format:** "Framework issues: [specific violations] → Corrections needed: [file path + changes]"
+
+### Pattern 5: CLI Tool Testing Validation
+**Scenario:** Reviewing tests for CLI tool or command implementation
+
+**Process:**
+1. Load CLI-TESTING.md for test layer requirements
+2. Verify test layers present: unit tests, integration tests, CLI surface tests
+3. Check for user-context testing (tests run from simulated user project, not CLI source)
+4. Verify state verification (tests check side effects: manifest updates, file creation)
+5. Check environment variation tests (no TTY, outside project, paths with spaces)
+6. Verify output validation (no "undefined", "Invalid Date", correct paths)
+
+**Report format:** "CLI testing gaps: [missing layers] → Required tests: [specific test scenarios]"
+
+### Pattern 6: Defensive Coding Review
+**Scenario:** Reviewing code for defensive patterns that prevent runtime bugs
+
+**Process:**
+1. Load DEFENSIVE-CODING.md for defensive patterns checklist
+2. Check null-safe display (all user-facing output handles missing values)
+3. Verify path context awareness (projectPath vs frameworkRoot explicit)
+4. Check data normalization at boundaries (YAML dates, JSON parsing)
+5. Verify error message quality (user-relevant paths, actionable messages)
+6. Check feature flag completeness (defined → passed → implemented → tested)
+
+**Report format:** "Defensive coding issues: [pattern violations] → Fixes: [specific code changes]"
+
+---
+
+## See Also
+
+### Supporting Files
+- [ANTI-PATTERNS.md](ANTI-PATTERNS.md) - Code, ticket, framework, CLI testing, defensive coding anti-patterns
+- [QUALITY-CHECKLIST.md](QUALITY-CHECKLIST.md) - Domain-specific checklists for stories, epics, reports, code, CLI testing
+- [EVALUATION-PROTOCOL.md](EVALUATION-PROTOCOL.md) - Post-task self-evaluation and improvement process
+- [CLI-TESTING.md](CLI-TESTING.md) - CLI test layers, user context simulation, state verification, environment variation
+- [DEFENSIVE-CODING.md](DEFENSIVE-CODING.md) - Null-safe output, path context, data normalization, error quality
+- [EXAMPLES.md](EXAMPLES.md) - Real scenarios with before/after comparisons (including CLI testing examples)
+
+### Related Framework Resources
+- `common-anti-patterns.md` - Original anti-patterns reference (source)
+- `quality-standards.md` - Original quality standards reference (source)
+- `agent-self-evaluation.md` - Original evaluation protocol reference (source)
+
+### Related Skills
+- `building-framework` - Framework-wide governance rules and standards
+
+---
+
+## Token Budget
+
+**Total skill size:** ~4,200 tokens
+- SKILL.md: ~600 tokens (this file)
+- ANTI-PATTERNS.md: ~400 tokens
+- QUALITY-CHECKLIST.md: ~250 tokens
+- EVALUATION-PROTOCOL.md: ~100 tokens
+- CLI-TESTING.md: ~500 tokens
+- DEFENSIVE-CODING.md: ~350 tokens
+- EXAMPLES.md: ~400 tokens
+
+**Loading profile:**
+- Initial load (SKILL.md): ~600 tokens
+- On-demand supporting files: ~300-900 tokens depending on scenario
+
+---
+
+## Key Takeaways
+
+1. **Five quality frameworks** - Anti-patterns, checklists, self-evaluation, CLI testing, defensive coding
+2. **Progressive disclosure** - Load supporting files based on scenario (code, ticket, CLI, post-task)
+3. **Domain-specific validation** - Different standards for code vs. tickets vs. CLI tools vs. documentation
+4. **User-context testing** - CLI tests must simulate real user environment, not developer context
+5. **Defensive patterns** - Prevent bugs through null-safe output, path awareness, data normalization
+6. **Continuous improvement** - Self-evaluation protocol identifies and fixes root causes
+7. **Universal applicability** - Works across all projects and artifact types
+
+---
+
+**Skill Version:** 2.0
+**Status:** Enhanced with CLI Testing & Defensive Coding
+**Created:** 2025-12-07
+**Updated:** 2025-12-30
+**Consolidated from:**
+- ai/shared/common-anti-patterns.md
+- ai/shared/quality-standards.md
+- ai/shared/agent-self-evaluation.md
+- CLI QA findings (21 bugs analysis)

package/framework/modules/core/templates/agent/agent.template.md

@@ -0,0 +1,97 @@
+---
+agent: ai-{{name}}
+role: {{role}}
+capability-needs:
+  - {{capability}}
+context-category-needs:
+  business: {{businessLevel}}
+  technical: {{technicalLevel}}
+  process: {{processLevel}}
+variant: {{variant}}
+delegates-to: {{delegatesTo}}
+token-budget: {{tokenBudget}}
+---
+
+# {{title}} Agent
+
+**Agent:** ai-{{name}}
+**Capability:** {{capability}} ({{description}})
+**Framework:** v12.0 (Discovery-Driven Architecture)
+
+> **Auto-Discovery:** Required skills are automatically discovered and loaded by the Discovery Engine based on this agent's `capability-needs`. See `{project}/ai/registries/agents.json` and `{project}/ai/registries/discovery-map.json` for capability mappings.
+
+---
+
+## Purpose
+
+{{description}}
+
+**Core Responsibilities:**
+1. <!-- TODO: Add first responsibility -->
+2. <!-- TODO: Add second responsibility -->
+3. <!-- TODO: Add third responsibility -->
+
+---
+
+## Skill Routing Table
+
+| Task Category | Primary Skill | Notes |
+|--------------|---------------|-------|
+| {{capability}} | Auto-loaded via capability-needs | Primary agent function |
+| Quality Validation | `verifying-quality` | Quality checks |
+| Git Workflow | `committing-code` | Commits, branches, PRs |
+
+**Pattern:** Route to skills for detailed workflows. Agent orchestrates, skills execute.
+
+---
+
+## Required Reading
+
+### Context Files
+
+> **Registry:** Context requirements defined in `{project}/ai/registries/agents.json` under `ai-{{name}}.context-category-needs`
+
+Load these context files before starting work:
+
+1. **business-{{businessLevel}}** - Business context at {{businessLevel}} level
+2. **technical-{{technicalLevel}}** - Technical context at {{technicalLevel}} level
+3. **process-{{processLevel}}** - Process context at {{processLevel}} level
+
+> **Auto-Discovery Note:** All required skills are automatically discovered and loaded by the Discovery Engine. No manual skill loading required.
+
+---
+
+## Workflow
+
+### Standard Workflow
+
+1. **Understand Task**
+   - Read relevant context files
+   - Identify required skills from routing table
+   - Clarify requirements if needed
+
+2. **Execute Task**
+   - Follow skill guidance for detailed steps
+   - Apply quality standards
+   - Track progress
+
+3. **Complete Task**
+   - Validate output against success criteria
+   - Update relevant documentation
+   - Commit changes following git workflow
+
+---
+
+## Success Criteria
+
+- [ ] Task requirements met
+- [ ] Quality standards applied
+- [ ] Documentation updated
+- [ ] Changes committed
+
+---
+
+**Version:** 12.0 (Discovery-Driven Architecture)
+**Token Budget:** ~{{tokenBudget}} tokens
+**Context Loading:** Auto-discovered via context-category-needs in agents.json
+**Created:** {{date}}

package/framework/modules/core/templates/agent/template.config.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "../../registries/schemas/template.schema.json",
+  "version": "1.0",
+  "templates": {
+    "agent.template": {
+      "output": "ai-{{name}}.md",
+      "description": "Create a new agent markdown file with standard structure",
+      "variables": {
+        "required": ["name", "capability", "description"],
+        "optional": ["role", "title", "variant", "delegatesTo", "tokenBudget", "businessLevel", "technicalLevel", "processLevel"],
+        "computed": ["date"]
+      },
+      "defaults": {
+        "role": "Agent Role",
+        "title": "Agent Title",
+        "variant": "full",
+        "delegatesTo": "[]",
+        "tokenBudget": "2500",
+        "businessLevel": "basic",
+        "technicalLevel": "basic",
+        "processLevel": "basic"
+      },
+      "validation": {
+        "name": {
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "minLength": 2,
+          "maxLength": 30
+        },
+        "capability": {
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "variant": {
+          "enum": ["interactive", "autonomous"]
+        },
+        "businessLevel": {
+          "enum": ["basic", "advanced", "expert"]
+        },
+        "technicalLevel": {
+          "enum": ["basic", "advanced", "expert"]
+        },
+        "processLevel": {
+          "enum": ["basic", "advanced", "expert"]
+        }
+      }
+    }
+  }
+}

package/framework/modules/core/templates/config/agentic-framework.json.template

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "type": "project",
+  "modules": {},
+  "framework": {
+    "version": "{{frameworkVersion}}",
+    "source": "npm",
+    "deployedAt": "{{timestamp}}",
+    "lastSyncAt": null
+  },
+  "paths": {
+    "deployed": ".claude/",
+    "projectData": "ai/"
+  }
+}
+F