cc-agentic-framework 1.14.1

package/framework/modules/core/skills/validating-markdown/YAML-SCHEMA.md

@@ -0,0 +1,424 @@
+# YAML Frontmatter Schema & Examples
+
+## Complete Frontmatter Schema
+
+```yaml
+---
+# Required Fields (Always Include)
+documentType: [required, string]           # guide|epic|story|task|spike|bug|architecture|requirements|other
+description: [required, string, max 150]  # Single sentence, clear purpose
+tags: [required, array]                    # Keywords for search (3-5 items)
+dependencies: [required, array]            # Files needed for context
+soft_references: [required, array]         # Related but optional files
+audience: [required, array]                # agent|human|mixed
+
+# Optional Fields (Include Only If Relevant)
+author: [optional, string]                 # Author name
+date: [optional, string]                   # YYYY-MM-DD format
+status: [optional, string]                 # draft|in-review|approved|published
+
+# Jira Integration (Include If Applicable)
+jira_key: [optional, string]              # PROJECT-123 format
+jira_url: [optional, string]              # Full URL to Jira issue
+jira_project: [optional, string]          # Project key
+issue_type: [optional, string]            # Story|Epic|Task|Bug
+
+# Scope & Organization
+scope: [optional, string]                  # Project or framework scope
+milestone: [optional, string]              # Release or sprint identifier
+team: [optional, string]                   # Team responsible
+component: [optional, string]              # Component or module
+
+# Relationships
+parent_epic_file: [optional, string]      # Path to parent epic
+parent_epic_key: [optional, string]       # Jira key of parent
+related_stories: [optional, array]        # Array of related story keys
+depends_on: [optional, array]             # Dependencies on other items
+blocks: [optional, array]                 # What this item blocks
+
+# Estimation & Priority
+story_points: [optional, number]          # 1, 2, 3, 5, 8, 13
+priority: [optional, string]              # critical|high|medium|low
+labels: [optional, array]                 # Additional tags
+---
+```
+
+## Field Specifications
+
+### Required Fields
+
+#### documentType
+- **Values:** guide, epic, story, task, spike, bug, architecture, requirements, other
+- **Description:** Type of document being created
+- **Examples:**
+  - `documentType: story` - User story or feature request
+  - `documentType: guide` - How-to guide or documentation
+  - `documentType: architecture` - Architectural decision
+  - `documentType: task` - Implementation task
+  - `documentType: spike` - Investigation or research
+
+#### version
+- **Format:** Semantic versioning (major.minor)
+- **Pattern:** `X.Y` (e.g., 1.0, 1.1, 2.0)
+- **Rules:**
+  - Start at 1.0 for new documents
+  - Increment minor (1.0 → 1.1) for updates
+  - Increment major (1.1 → 2.0) for significant changes
+- **Examples:** 1.0, 1.1, 1.2, 2.0, 2.1
+
+#### description
+- **Format:** Single sentence string
+- **Max length:** 150 characters
+- **Rules:**
+  - Start with action verb (if applicable)
+  - Clear and concise
+  - Summarize document purpose
+- **Examples:**
+  - "Implement user authentication for dashboard"
+  - "Guidelines for markdown formatting in documentation"
+  - "Architecture decision for microservices deployment"
+
+#### tags
+- **Format:** Array of strings
+- **Count:** 3-5 items recommended
+- **Naming:** lowercase, hyphen-separated
+- **Purpose:** Search and filtering
+- **Examples:**
+  ```yaml
+  tags: [authentication, security, frontend]
+  tags: [framework, governance, validation]
+  tags: [architecture, scaling, performance]
+  ```
+
+#### dependencies
+- **Format:** Array of file paths
+- **Content:** Paths to files required for context
+- **Rules:**
+  - Relative paths from repository root
+  - Include .md extension
+  - Only required files
+- **Examples:**
+  ```yaml
+  dependencies:
+    - ai/context/technical-advanced.md
+    - framework/architecture-decisions.md
+  dependencies: []  # Empty if none
+  ```
+
+#### soft_references
+- **Format:** Array of file paths
+- **Content:** Related files, helpful but not required
+- **Rules:**
+  - Similar format to dependencies
+  - Optional reading
+  - For context enhancement
+- **Examples:**
+  ```yaml
+  soft_references:
+    - backlog/sprints/2025-W49.md
+    - ai/skills/building-skills/EXAMPLES.md
+  soft_references: []  # Empty if none
+  ```
+
+#### audience
+- **Values:** agent, human, mixed
+- **agent:** AI agent instructions, technical details
+- **human:** End-user documentation, design docs
+- **mixed:** Both agents and humans will read
+- **Examples:**
+  ```yaml
+  audience: [agent]          # AI agents only
+  audience: [human]          # Humans only
+  audience: [agent, human]   # Both
+  ```
+
+---
+
+### Optional Fields
+
+#### author
+- **Format:** String, author name or team
+- **Examples:** "John Doe", "Engineering Team", "PACT Agents"
+
+#### date
+- **Format:** ISO 8601 date string (YYYY-MM-DD)
+- **Examples:** "2025-12-07", "2025-01-15"
+- **Use case:** Document creation or last update date
+
+#### status
+- **Values:** draft, in-review, approved, published
+- **Examples:**
+  - draft - Initial creation
+  - in-review - Under review
+  - approved - Ready for use
+  - published - Live/released
+
+#### jira_key
+- **Format:** PROJECT-NUMBER
+- **Examples:** APMR-123, PROJ-456
+- **Use case:** Link to Jira issue
+
+#### jira_url
+- **Format:** Full URL string
+- **Example:** `https://jira.company.com/browse/APMR-123`
+- **Use case:** Direct link to issue
+
+#### jira_project
+- **Format:** Project key string
+- **Examples:** APMR, INFRA, DOCS
+- **Use case:** Project identifier
+
+#### issue_type
+- **Values:** Story, Epic, Task, Bug, Spike, Feature
+- **Use case:** Jira issue type categorization
+
+#### scope
+- **Format:** String describing scope
+- **Examples:** "Framework", "APM-R Project", "Multi-repo"
+
+#### milestone
+- **Format:** Release or sprint identifier
+- **Examples:** "Q1 2025", "Sprint 12", "v2.0"
+
+#### team
+- **Format:** Team name or identifier
+- **Examples:** "Platform Team", "Frontend Team", "Architecture"
+
+#### component
+- **Format:** Component or module name
+- **Examples:** "Authentication", "Dashboard", "API Gateway"
+
+#### parent_epic_file
+- **Format:** Relative file path
+- **Example:** ai/plans/framework/001-consolidation/PLAN.md
+
+#### parent_epic_key
+- **Format:** Jira key format
+- **Example:** APMR-100
+
+#### related_stories
+- **Format:** Array of Jira keys
+- **Example:** [APMR-101, APMR-102, APMR-103]
+
+#### depends_on
+- **Format:** Array of Jira keys or file paths
+- **Example:** [APMR-50, APMR-51]
+
+#### blocks
+- **Format:** Array of Jira keys
+- **Example:** [APMR-200, APMR-201]
+
+#### story_points
+- **Values:** Fibonacci sequence (1, 2, 3, 5, 8, 13, 21)
+- **Use case:** Agile estimation
+
+#### priority
+- **Values:** critical, high, medium, low
+- **Use case:** Issue prioritization
+
+#### labels
+- **Format:** Array of strings
+- **Use case:** Additional categorization
+- **Examples:** [urgent, technical-debt, refactoring]
+
+---
+
+## Complete Examples
+
+### Example 1: User Story
+
+```yaml
+---
+documentType: story
+description: Implement user authentication for dashboard access
+tags: [authentication, security, frontend, priority-high]
+dependencies:
+  - ai/context/technical-advanced.md
+  - framework/architecture-decisions.md
+soft_references:
+  - backlog/sprints/2025-W49.md
+  - ai/agents/ai-architect.md
+audience: [agent, human]
+jira_key: APMR-123
+jira_url: "https://jira.example.com/browse/APMR-123"
+jira_project: APMR
+issue_type: Story
+story_points: 8
+priority: high
+milestone: Q1 2025
+team: Platform Team
+component: Authentication
+---
+
+# User Authentication for Dashboard
+
+## Overview
+Users need secure authentication...
+```
+
+### Example 2: Technical Guide
+
+```yaml
+---
+documentType: guide
+description: Best practices for markdown formatting in agent-generated files
+tags: [markdown, formatting, standards, documentation]
+dependencies: []
+soft_references:
+  - ai/shared/markdown-formatting-guide.md
+audience: [agent]
+author: PACT Agents
+date: 2025-12-07
+status: published
+scope: Framework
+milestone: v11.1
+---
+
+# Markdown Formatting Guide
+
+## Purpose
+Define standards for all...
+```
+
+### Example 3: Architecture Decision
+
+```yaml
+---
+documentType: architecture
+description: Decision to adopt microservices architecture for scalability
+tags: [architecture, design-decision, scalability, infrastructure]
+dependencies:
+  - framework/current-architecture.md
+  - analysis/performance-study.md
+soft_references:
+  - backlog/architecture-spikes/
+audience: [human]
+jira_key: APMR-456
+jira_project: APMR
+date: 2025-12-01
+status: approved
+parent_epic_key: APMR-400
+priority: high
+---
+
+# Microservices Architecture Decision
+
+## Context
+Current monolithic architecture...
+```
+
+### Example 4: Development Task
+
+```yaml
+---
+documentType: task
+description: Update validation script for new frontmatter schema
+tags: [framework, development, validation, automation]
+dependencies:
+  - ai/shared/markdown-formatting-guide.md
+  - cli/src/lib/framework/validation.ts
+soft_references: []
+audience: [agent]
+jira_key: APMR-789
+jira_project: APMR
+issue_type: Task
+story_points: 3
+priority: medium
+milestone: Sprint 12
+component: Framework Governance
+parent_epic_key: APMR-123
+depends_on: [APMR-121, APMR-122]
+blocks: [APMR-124]
+---
+
+# Update Frontmatter Validation Script
+
+## Objective
+Extend validation to support...
+```
+
+### Example 5: Minimal Frontmatter (No Optional Fields)
+
+```yaml
+---
+documentType: guide
+description: Quick reference for CLI commands
+tags: [cli, reference, tools]
+dependencies: []
+soft_references: []
+audience: [human]
+---
+
+# CLI Command Reference
+
+## Available Commands
+...
+```
+
+---
+
+## Field Combination Examples
+
+### For Jira Integration (All Fields)
+```yaml
+documentType: story
+description: Feature objective
+tags: [category, priority]
+dependencies: []
+soft_references: []
+audience: [agent, human]
+jira_key: APMR-123
+jira_url: "https://jira.example.com/browse/APMR-123"
+jira_project: APMR
+issue_type: Story
+story_points: 5
+priority: high
+milestone: Q1 2025
+team: Team Name
+labels: [label1, label2]
+```
+
+### For Framework Documentation (Minimal)
+```yaml
+documentType: guide
+description: Documentation objective
+tags: [tag1, tag2, tag3]
+dependencies: []
+soft_references: []
+audience: [agent]
+```
+
+### For Epic Stories (With Dependencies)
+```yaml
+documentType: epic
+description: Epic overview and goals
+tags: [epic, major-feature]
+dependencies:
+  - related/doc1.md
+  - related/doc2.md
+soft_references:
+  - optional/reference.md
+audience: [human]
+parent_epic_key: APMR-100
+related_stories: [APMR-101, APMR-102]
+milestone: Q1 2025
+priority: high
+```
+
+---
+
+## Validation Rules
+
+- **Required fields:** All 7 must be present
+- **Array fields:** Can be empty `[]` but must exist
+- **Field count:** Maximum 12 fields total
+- **Version format:** Must be semantic (X.Y)
+- **Description:** Single sentence, max 150 chars
+- **Tags:** 3-5 items recommended
+- **Audience:** Must be array (even if single value)
+
+---
+
+**Last Updated:** 2025-12-07
+**Schema Version:** 1.0
+**Used by:** formatting-markdown-standards skill

package/framework/modules/core/skills/verifying-quality/ANTI-PATTERNS.md

@@ -0,0 +1,302 @@
+# Anti-Patterns Reference
+
+Comprehensive anti-patterns across code, tickets, framework, and application domains.
+
+---
+
+## Code Anti-Patterns
+
+### ❌ DON'T: Violate SOLID Principles
+- Mixing multiple responsibilities in one class/function
+- Hardcoding dependencies instead of injection
+- Creating overly general interfaces
+- Breaking substitutability contracts
+
+### ✅ DO: Follow SOLID
+- **Single Responsibility** - one reason to change
+- **Open/Closed** - extend, don't modify
+- **Liskov Substitution** - subtypes are substitutable
+- **Interface Segregation** - many specific interfaces
+- **Dependency Inversion** - depend on abstractions
+
+---
+
+### ❌ DON'T: Repeat Yourself (DRY Violation)
+- Copy-pasting code across multiple files
+- Duplicating logic instead of extracting
+- Recreating utilities that exist
+
+### ✅ DO: Extract and Reuse
+- Create shared utilities/functions
+- Extract repeated logic to helpers
+- Use composition over duplication
+
+---
+
+### ❌ DON'T: Ignore Error Handling
+- Swallowing exceptions silently
+- Using generic catch-all error messages
+- Not validating inputs
+- Missing edge case handling
+
+### ✅ DO: Handle Errors Gracefully
+- Catch specific exceptions
+- Provide user-friendly error messages
+- Validate all inputs (especially at boundaries)
+- Cover edge cases (null, empty, invalid)
+
+---
+
+### ❌ DON'T: Hardcode Configuration
+- API keys, secrets, URLs in code
+- Magic numbers without explanation
+- Environment-specific values in code
+
+### ✅ DO: Externalize Configuration
+- Use environment variables for secrets
+- Define constants with meaningful names
+- Use configuration files for env-specific settings
+
+---
+
+### ❌ DON'T: Write Untestable Code
+- Tight coupling to external dependencies
+- Functions with side effects
+- Code that depends on global state
+- Missing dependency injection
+
+### ✅ DO: Write Testable Code
+- Dependency injection for external services
+- Pure functions where possible
+- Avoid global state
+- Clear, mockable interfaces
+
+---
+
+## Ticket & Story Anti-Patterns
+
+### ❌ DON'T: Create Horizontal Slices
+- Separate API layer story, UI story, DB story
+- Stories that can't be deployed independently
+- Stories requiring multiple teams to complete
+
+### ✅ DO: Create Vertical Slices
+- End-to-end features (API + UI + DB in one story)
+- Independently shippable increments
+- Value delivered at completion
+
+---
+
+### ❌ DON'T: Write Vague Acceptance Criteria
+- "Make it work"
+- "Improve performance"
+- "Fix bugs"
+- Non-specific, non-measurable criteria
+
+### ✅ DO: Write Specific, Testable Criteria
+- "API returns 200 status for valid requests"
+- "Page loads in <2 seconds for 95th percentile"
+- "Zero errors in console after interaction"
+- Measurable, verifiable criteria
+
+---
+
+### ❌ DON'T: Include Code in Tickets
+- TypeScript/JavaScript code snippets
+- SQL queries
+- GraphQL schemas
+- Detailed implementation code
+
+### ✅ DO: Reference Patterns
+- "Follow Container/View/Controller pattern"
+- "Use Centralized Data Layer V2.1"
+- "Apply caching pattern from technical-advanced.md"
+- High-level guidance, not code
+
+---
+
+### ❌ DON'T: Create Oversized Stories
+- Stories >8 story points
+- Stories spanning multiple sprints
+- Stories with >15 acceptance criteria
+
+### ✅ DO: Decompose Large Stories
+- Break into ≤8 point stories
+- Vertical slices that fit in one sprint
+- 8-12 acceptance criteria per story
+
+---
+
+## Framework Anti-Patterns
+
+### ❌ DON'T: Put Project-Specific Content in Agents
+- Hardcoded paths in agent files
+- Project-specific patterns in agents
+- Milestone codes in agent files
+
+### ✅ DO: Keep Agents Pure
+- All project content in context files
+- Generic patterns in agents
+- Reference context files dynamically
+
+---
+
+### ❌ DON'T: Duplicate Content Across Files
+- Copy same text to multiple agents
+- Repeat patterns without extraction
+- Redundant reminders throughout files
+
+### ✅ DO: Extract to Shared Resources
+- Create shared-resources for reused content
+- Reference shared resources from agents
+- Single source of truth
+
+---
+
+### ❌ DON'T: Break Documentation Links
+- Rename files without updating references
+- Move files without updating paths
+- Delete files still being referenced
+
+### ✅ DO: Maintain Cross-References
+- Use `git mv` to preserve history
+- Update all cross-references when moving files
+- Validate links before committing
+
+---
+
+## Multi-Tenancy Anti-Patterns (Application-Specific)
+
+### ❌ DON'T: Mix Tenant Data
+- Queries without tenant filters
+- Shared caches across tenants
+- Missing tenant context in operations
+
+### ✅ DO: Enforce Tenant Isolation
+- Always filter by tenantId
+- Tenant-scoped caching
+- Tenant context in all operations
+
+---
+
+## Performance Anti-Patterns
+
+### ❌ DON'T: Create N+1 Queries
+- Loop through items, query for each
+- Fetch in loops instead of batch
+- Missing eager loading
+
+### ✅ DO: Batch Operations
+- Use DataLoader for batching
+- Eager load related data
+- Single query with joins where appropriate
+
+---
+
+### ❌ DON'T: Cache Inefficiently
+- Cache entire datasets unnecessarily
+- Never invalidate stale cache
+- Cache non-cacheable data
+
+### ✅ DO: Cache Strategically
+- Cache only frequently accessed, stable data
+- Implement cache invalidation strategy
+- Use appropriate TTL
+
+---
+
+## CLI Testing Anti-Patterns
+
+### ❌ DON'T: Test Only Library Functions
+- Skip CLI surface tests (argument parsing, output formatting)
+- Test from CLI source directory, not user context
+- Only check "result exists", not "result is correct"
+
+### ✅ DO: Test Complete CLI Experience
+- Test actual CLI execution via `exec()` or similar
+- Simulate user project directory
+- Validate output content (no "undefined", correct paths)
+- Test all documented flags actually work
+
+---
+
+### ❌ DON'T: Skip State Verification
+- Check return value only, ignore side effects
+- No round-trip tests (create → use)
+- Different paths between related commands
+
+### ✅ DO: Verify State Changes
+- Test manifest updates after add/remove
+- Verify files created in correct locations
+- Test create → validate round-trip works
+- Use shared path constants across commands
+
+---
+
+### ❌ DON'T: Ignore Environment Variations
+- Assume TTY always available
+- Assume always inside project context
+- Assume paths without spaces
+
+### ✅ DO: Test Hostile Environments
+- Test without TTY (pipe mode)
+- Test outside project (clean error)
+- Test paths with spaces
+
+---
+
+## Defensive Coding Anti-Patterns
+
+### ❌ DON'T: Display Unvalidated Values
+- Show `undefined`, `null`, `Invalid Date`
+- Display `vundefined` for missing versions
+- Use naive pluralization (`storys`)
+
+### ✅ DO: Null-Safe Display
+- Default missing dates to "Unknown"
+- Default missing versions to "(version unknown)"
+- Use explicit plural mappings for irregulars
+
+---
+
+### ❌ DON'T: Use Ambiguous Paths
+- Unclear `root` or `basePath` variables
+- Mix projectPath and frameworkRoot
+- Hardcode relative paths
+
+### ✅ DO: Explicit Path Context
+- Define PathContext interface
+- Use `ctx.projectPath` for user files
+- Use `ctx.frameworkRoot` for CLI templates
+- Share path constants across commands
+
+---
+
+### ❌ DON'T: Skip Data Normalization
+- Pass raw YAML Date objects to validation
+- Accept unquoted dates without conversion
+- Normalize deep in logic, not at boundary
+
+### ✅ DO: Normalize at Boundaries
+- Convert Date objects to strings at parse time
+- Normalize all input at entry point
+- Test with realistic user input
+
+---
+
+### ❌ DON'T: Show Internal Details in Errors
+- Display schema paths instead of user file paths
+- Show stack traces for expected user errors
+- Generic "Error occurred" messages
+
+### ✅ DO: User-Friendly Errors
+- Show user's file path in errors
+- Clean message for expected errors
+- Stack trace only for unexpected errors
+- Include fix suggestions
+
+---
+
+**Source:** Consolidated from ai/shared/common-anti-patterns.md + CLI QA findings
+**Version:** 2.0
+**Updated:** 2025-12-30