create-coach

/create-coach

Scaffold a new domain-specific AI coach project.

Preflight

Before asking any questions, run these checks:

1. Run which qmd — if it fails, tell the user: "qmd is required. Install with: npm install -g @tobilu/qmd" and stop.
2. Run which uv — if it fails, tell the user: "uv is required. Install from: https://docs.astral.sh/uv/" and stop.

Interview

Ask these questions one at a time. Wait for the answer before asking the next.

1. "What domain is this coach for? (e.g., nutrition, learning, rehab, music practice)" → Save as DOMAIN (lowercase, hyphenated if multi-word, e.g., "music-practice") → Save a DOMAIN_TITLE (title case, e.g., "Music Practice")

2. "What are your goals and current level?" → Save the full answer for CLAUDE.md profile generation

3. "Any constraints the coach must never ignore? (e.g., allergies, injuries, time limits, equipment access)" → Save for CLAUDE.md constraints section. If user says "none", write "None currently listed."

4. "Anything else the coach should know? (philosophy, specific metrics you care about, preferences, approach)" → Save for filling remaining gaps. The LLM uses this plus the domain to infer sensible defaults for: log column headers, skill search queries, skill issue types, recommendation framing, phase names, baseline stats structure.

Suggest Project Location

Look at the current working directory. Suggest a sibling directory named ai-{{DOMAIN}}. For example, if cwd is ~/projects/something, suggest ~/projects/ai-{{DOMAIN}}.

Ask: "I'll create the project at [suggested path]. OK, or would you prefer somewhere else?"

Wait for approval. If the user gives an alternative path, use that instead. Save as TARGET_DIR.

Scaffold

Create directory structure

TARGET_DIR/
├── .claude/skills/
├── scripts/
├── resources/
├── context/

Write files

Read each template from this plugin's templates/ directory and write to TARGET_DIR.

Exact copies (no modification):

• templates/convert.py → TARGET_DIR/scripts/convert.py
• templates/gitignore.tmpl → TARGET_DIR/.gitignore

String replacement (replace {{DOMAIN}} with the DOMAIN value):

• templates/qmd-mcp.sh.tmpl → TARGET_DIR/scripts/qmd-mcp.sh (make executable: chmod +x)
• templates/mcp.json.tmpl → TARGET_DIR/.mcp.json
• templates/index.sh.tmpl → TARGET_DIR/scripts/index.sh (make executable: chmod +x)
  • Also replace {{CONTEXT_STRING}} — write a one-sentence description of the domain's knowledge base scope, derived from the interview answers. Example for training: "Strength and conditioning science library: periodization, programming, progressive overload, fatigue management, peaking, recovery."

LLM-generated from templates (read the template, keep all fixed text exactly as-is, fill only the marked slots):

• templates/CLAUDE.md.tmpl → TARGET_DIR/CLAUDE.md Fill these slots from interview answers:

  • {{DOMAIN}} — domain name
  • {{GOAL}} — from Q2
  • {{STARTING_PHASE}} — infer a sensible starting phase name for this domain
  • {{TODAY}} — today's date (YYYY-MM-DD)
  • {{PHASE_LENGTH}} — infer a sensible default (e.g., "4 weeks", "8 weeks")
  • {{BASELINE_STATS}} — generate 3-5 domain-appropriate metrics as bullet points with placeholder values
  • {{CONSTRAINTS}} — from Q3
  • {{PHILOSOPHY}} — from Q4, or infer sensible defaults
  • {{CONTEXT}} — from Q4, or infer sensible defaults (time available, stress level, etc.)

• templates/skill.md.tmpl → TARGET_DIR/.claude/skills/{{DOMAIN}}.md Fill these slots:

  • {{DOMAIN}} — domain name
  • {{ISSUE_TYPES}} — generate 5-7 bullet points of domain-specific failure modes (e.g., for nutrition: "missed macro targets", "binge episode", "energy crash")
  • {{SEARCH_QUERIES}} — generate 5-6 quoted example search strings relevant to the domain
  • {{RECOMMENDATION_FRAMING}} — generate 3 bullet points describing what a recommendation should cover for this domain (e.g., "what to adjust for this session", "whether a phase change is warranted")

• templates/log.md.tmpl → TARGET_DIR/log.md Fill these slots:

  • {{DOMAIN_TITLE}} — title case domain name
  • {{COL1}} through {{COL6}} — generate 6 domain-appropriate column headers (e.g., for nutrition: "Meal", "Planned", "Actual", "Calories", "Protein", "Notes")

Set up Python environment

Run in TARGET_DIR:

uv venv .venv
uv pip install docling

PDF Handling

Check if any .pdf files exist in TARGET_DIR/resources/ (recursively).

If PDFs found:

• Run: .venv/bin/python3 scripts/convert.py from TARGET_DIR
• Run: bash scripts/index.sh from TARGET_DIR
• Report how many PDFs were converted and indexed

If no PDFs found:

• Tell the user: "No PDFs found yet. Drop your reference materials into resources/ (any subfolder structure you like)."
• Tell them: "Then run .venv/bin/python3 scripts/convert.py && bash scripts/index.sh to build the knowledge base, or ask me to do it."

Summary

Print:

• What was created and where (TARGET_DIR)
• Whether the knowledge base was indexed (and how many documents)
• How to open: cd TARGET_DIR && claude
• How to start coaching: invoke /{{DOMAIN}}
• Reminder to fill in the [placeholder] values in CLAUDE.md with real stats before the first session