Initiative: Claude Code/MPM APEX Artifacts Skill

The Bet

We believe that by creating a comprehensive APEX artifacts skill for Claude Code/MPM (.claude/skills/apex-artifacts), we can: - Eliminate 100% of frontmatter validation errors during artifact creation - Enable Claude to create valid APEX artifacts on first try - Provide the same level of APEX knowledge that Cursor has (19 skills) - Reduce friction when working with Initiatives, Experiments, PRDs, and Team Charters

Background

Current State

Cursor has comprehensive APEX skills (.cursor/skills/): - 19 APEX-specific skills: apex-validate, apex-initiative, apex-experiment, apex-prd, etc. - Full understanding of artifact schemas and validation rules - Rarely produces invalid frontmatter

Claude Code/MPM lacks APEX knowledge (.claude/skills/): - 50+ general skills (MPM, toolchains, universal patterns) - No APEX artifacts skill - relies on examples and trial-and-error - Produces validation errors (e.g., today's hypothesis format issue)

The Problem

Recent session creating E-2026-001 (Frontdoor POC1 experiment):

Error: hypothesis: 'string' is not of type 'object'

Root cause: Claude didn't know experiment hypothesis must be structured:

hypothesis:
  statement: "..."
  confidence: medium
  validation_method: prototype

Impact: 3 failed commits before getting it right (validation pre-commit hook caught errors)

The Opportunity

Create one comprehensive skill that gives Claude the same APEX artifact knowledge that Cursor has.

Skill location: .claude/skills/apex-artifacts/SKILL.md

Benefits: 1. ✅ Zero validation errors: Claude knows exact schemas 2. ✅ Faster artifact creation: No trial-and-error on frontmatter 3. ✅ Consistent quality: Same standards as Cursor sessions 4. ✅ Better AI assistance: Claude can proactively suggest improvements

Solution Design

Skill Structure

.claude/skills/apex-artifacts/
├── SKILL.md                  # Main skill file
└── manifest.json             # Skill metadata

Skill Content (apex-artifacts/SKILL.md)

Section 1: Overview - What APEX artifacts are - Why validation matters - Common use cases

Section 2: Artifact Types - Initiative (type: initiative) - Experiment (type: experiment) - PRD (type: prd) - Team Charter (type: team-charter)

Section 3: Frontmatter Schemas For each artifact type: - Required fields - Optional fields - Field types and formats - ID patterns (e.g., E-YYYY-NNN) - Cross-references (e.g., parent_initiative)

Section 4: Common Patterns - Hypothesis structure (object vs string) - Learning structure - Related artifacts arrays - Status transitions - Tag conventions

Section 5: Validation Rules - ID format regex patterns - Required field combinations - Status-dependent requirements - Cross-reference validation

Section 6: Common Mistakes - Hypothesis as string (should be object) - Wrong ID format (e.g., E-2026-ING-001 vs E-2026-001) - Missing required fields for status - Invalid cross-references

Section 7: Examples - Complete valid Initiative - Complete valid Experiment - Complete valid PRD - Complete valid Team Charter

Implementation Plan

Phase 1: Extract Schema Knowledge 1. Analyze .pre-commit-config.yaml for validation script 2. Study apex-frontmatter-validate hook logic 3. Extract JSON schemas or validation rules 4. Document all artifact type schemas

Phase 2: Create Skill File 1. Write comprehensive skill in .claude/skills/apex-artifacts/SKILL.md 2. Include all schemas, rules, and examples 3. Add common mistakes section (based on recent errors) 4. Create manifest.json with metadata

Phase 3: Validate 1. Test with Claude Code creating new artifacts 2. Verify zero validation errors 3. Compare quality with Cursor-created artifacts 4. Iterate based on feedback

Phase 4: Deploy 1. Merge to main 2. Document in APEX README 3. Update CLAUDE.md to mention the skill 4. Share with team

Success Metrics

Metric	Current	Target	Measurement
Validation errors per artifact	~30% (1 in 3 fail)	0%	Pre-commit hook pass rate
Commits to get valid artifact	2-4 attempts	1 (first try)	Git history analysis
Time to create artifact	5-10 min (with retries)	2-3 min	Session timing
Claude knowledge parity	0/19 skills	1 comprehensive	Skill count

Risks & Mitigation

Risk	Likelihood	Impact	Mitigation
Skill becomes outdated	Medium	Medium	Version skill with APEX, update when schemas change
Too verbose (context bloat)	Low	Medium	Use concise examples, focus on schemas
Missing edge cases	Medium	Low	Iterate based on real errors encountered

Timeline

Week 1: Extract schemas, write skill (2 days)
Week 2: Test and validate (1 day)
Week 3: Deploy and document (1 day)

Total: 4 days effort, 3 weeks elapsed (async work)

Dependencies

Access to validation script source
Examples of all 4 artifact types
Testing environment (Claude Code sessions)

Cursor APEX Skills (inspiration): - apex-validate - Validation rules - apex-initiative - Initiative creation - apex-experiment - Experiment creation - apex-prd - PRD creation

Our Approach: Consolidate into one comprehensive skill vs 19 separate skills

Acceptance Criteria

[ ] .claude/skills/apex-artifacts/SKILL.md created
[ ] All 4 artifact types documented with schemas
[ ] Common mistakes section includes today's error patterns
[ ] 10+ complete examples included
[ ] Validation rule documentation complete
[ ] Claude can create valid artifacts on first try (tested)
[ ] Zero pre-commit validation failures (tested)
[ ] README updated with skill documentation
[ ] CLAUDE.md updated to reference skill

Questions

Should this skill be loaded automatically or on-demand?
How do we keep it in sync with schema changes?
Should we version the skill with APEX framework releases?
Do we need separate skills for different artifact types or one unified?

Branch Naming Convention (New Standard)

This PR establishes: Branch names should match product path hierarchy

Pattern: feature/{domain}-{product}-{initiative-slug}

This initiative: - Path: products/apex/apex-framework/initiatives/claude-code-integration/ - Branch: feature/apex-apex-framework-claude-code-integration ✅

Previous convention (inconsistent): - feature/frontdoor ❌ - feature/claude-artifacts-skill ❌

See: docs/BRANCH-NAMING-CONVENTION.md for complete specification

APEX Developments Initiative
IDE Integration Tools
Branch Naming Convention ✨ NEW
.cursor/skills/ (Cursor APEX skills for reference)
.pre-commit-config.yaml (validation hook)

Claude Code/MPM APEX Artifacts Skill