foundation

name	Foundation
description	Create and maintain the project foundation document at /directive/foundation.md with automatic domain detection, codebase analysis, semantic versioning, and consistency propagation. USE WHEN foundation, project foundation, create foundation, update foundation, project principles, governance, foundation document, amend foundation.

Foundation

Maintain the authoritative project foundation document. Automatically detects the project's technology domain, creates from codebase analysis or user input, updates with semantic versioning, and propagates changes to dependent artifacts.

Customization

Before executing, check for user customizations at: ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/Foundation/

If this directory exists, load and apply any PREFERENCES.md configurations. If not, proceed with defaults.

Prerequisites

PAI must be installed. Check ~/.buddy/.pai-version. If missing, inform user: "PAI is required. Run /pai:setup to install."

Workflow Routing

Workflow	Trigger	File
CreateFoundation	No /directive/foundation.md exists	Workflows/CreateFoundation.md
UpdateFoundation	Foundation exists, user wants changes	Workflows/UpdateFoundation.md
CreateDomain	User wants to create a new domain	Workflows/CreateDomain.md
DetectDomain	Called by CreateFoundation during setup	Workflows/DetectDomain.md

Auto-Detection

1. Check if user input contains "create domain", "new domain", or "add domain"
   • If yes -> route to Workflows/CreateDomain.md
2. Check if /directive/foundation.md exists
   • If no -> route to Workflows/CreateFoundation.md
     • CreateFoundation automatically detects the project domain via DetectDomain.md
     • Delegates to the domain's analyze.md for deep analysis
   • If yes -> route to Workflows/UpdateFoundation.md

Domain Architecture

Technology-specific knowledge lives in Domains/, where each subdirectory is a self-contained domain definition. Domains are auto-discovered — no registration needed.

Available Domains

Domain	Type Key	Description
default	default	Generic fallback for any project type
react	react	React.js frontend applications
jhipster	jhipster	JHipster full-stack (Angular + Spring Boot)
mulesoft	mulesoft	MuleSoft integration and API development

Domain Directory Structure

Domains/{domain-name}/
  profile.md          # Identity: type key, priority, dependencies, keywords, reference index
  detect.md           # Detection rules with confidence scoring
  analyze.md          # Deep analysis workflow fragment
  Templates/          # Domain-specific templates for downstream skills
    Spec.md           # Specification template
    Plan.md           # Implementation plan template
    Tasks.md          # Task breakdown template
    Docs.md           # Documentation template
  Reference/          # Large reference materials (loaded on-demand)
    README.md         # Index of reference files
    *.md              # Domain-specific reference documentation

Adding a New Domain

Interactive wizard (recommended):

/buddy:foundation create domain

The CreateDomain workflow guides you through creating all required files interactively, with intelligent defaults and technology-aware generation. Domains created this way are stored in your user customization directory:

~/.buddy/PAI-USER/SKILLCUSTOMIZATIONS/Foundation/Domains/{domain-name}/

Manual creation:

1. Create a directory under Domains/ or ~/.buddy/PAI-USER/SKILLCUSTOMIZATIONS/Foundation/Domains/
2. Add the required files: profile.md, detect.md, analyze.md
3. Add templates in Templates/: Spec.md, Plan.md, Tasks.md, Docs.md
4. Optionally add reference materials in Reference/
5. Use Domains/_domain-template/ as a starting point

No changes to Foundation, DetectDomain, or any downstream skill workflows are needed. The new domain is automatically discovered and available.

Domain Search Order

DetectDomain scans domains from two locations:

1. User domains: ~/.buddy/PAI-USER/SKILLCUSTOMIZATIONS/Foundation/Domains/ (takes precedence)
2. Built-in domains: skills/Foundation/Domains/

User domains can override built-in domains by using the same type_key.

Template Resolution

Downstream skills (Spec, Plan, Tasks, Docs) resolve templates dynamically:

1. Try: skills/Foundation/Domains/{foundation-type}/Templates/{Skill}.md
2. Fallback: The skill's own Templates/DefaultSpec.md (etc.)

Reference Material Loading

Domain reference materials are large and loaded on-demand. Each domain's profile.md includes a Reference Materials table with a Load When column indicating which workflow phases should load each file.

Examples

Example 1: Initialize foundation (auto-detect React project)

User: "/buddy:foundation"
-> No foundation exists
-> DetectDomain scans Domains/, finds package.json with "react" -> score 90
-> Selects react domain
-> Executes Domains/react/analyze.md for deep analysis
-> Derives 5 core principles (including React-specific)
-> Creates /directive/foundation.md with Foundation Type: react

Example 2: Initialize foundation (auto-detect MuleSoft project)

User: "/buddy:foundation"
-> No foundation exists
-> DetectDomain finds mule-artifact.json -> score 90
-> Selects mulesoft domain
-> Executes Domains/mulesoft/analyze.md
-> Creates /directive/foundation.md with Foundation Type: mulesoft

Example 3: Create a new domain

User: "/buddy:foundation create domain"
-> Asks for domain name and description
-> Gathers technology stack details (runtime, framework, config files, etc.)
-> Generates profile.md, detect.md, analyze.md with intelligent defaults
-> Generates 4 customized templates (Spec, Plan, Tasks, Docs)
-> Writes to ~/.buddy/PAI-USER/SKILLCUSTOMIZATIONS/Foundation/Domains/{name}/
-> Domain immediately available for detection

Persona System

12 specialized personas provide expert perspectives during workflow execution. Personas are loaded on-demand by downstream workflows based on task context.

Available Personas

Persona	Type Key	Expertise
architect	Systems design	Architecture patterns, scalability, dependency management
security	Threat modeling	Vulnerability assessment, compliance, secure coding
qa	Quality assurance	Test strategy, quality gates, coverage analysis
frontend	UI/UX specialist	Accessibility, responsive design, component patterns
backend	API specialist	Database optimization, microservices, authentication
devops	Infrastructure	CI/CD, containerization, monitoring, deployment
performance	Optimization	Profiling, bottleneck analysis, performance budgets
refactorer	Code quality	Technical debt, clean code, design patterns
analyzer	Investigation	Root cause analysis, debugging, diagnostics
mentor	Education	Knowledge transfer, explanations, tutorials
scribe	Documentation	Writing, commit messages, changelogs, style
po	Product owner	Requirements, user stories, acceptance criteria

Persona Directory Structure

Personas/{persona-name}/
  persona.md          # Full persona definition with identity, principles, and frameworks

How Personas Are Used

Downstream workflows load relevant personas to enhance their output:

• Spec generation loads po for requirement perspective
• Plan generation loads architect for design decisions
• Task generation loads qa for testing strategy
• Implementation loads context-dependent personas (e.g., frontend for UI tasks)
• Commit loads scribe for message quality
• Docs loads scribe for writing quality

Loading a Persona

Workflows load personas by reading:

skills/Foundation/Personas/{persona-name}/persona.md

The persona definition provides identity, core principles, decision frameworks, auto-activation triggers, collaboration patterns, and response patterns that guide the workflow's output.

Example 4: Add a principle

User: "/buddy:foundation add security review principle"
-> Foundation exists
-> Adds new security principle
-> Bumps version (MINOR: new principle)
-> Propagates changes to dependent artifacts