Skip to main content

bootstrap

Idempotent first-run setup that creates project directories, copies seed data, and detects legacy installations.

When It Runs​

  • Type: SessionStart
  • Trigger: Every session start
  • Matches: All sessions (empty matcher)

What It Does​

  1. Loads config system — Sources scripts/lib/config-loader.sh to resolve customizable paths for templates, learn, context, and outputs. Falls back to defaults if missing.
  2. Migrates legacy directory — Renames .jaan-to/ to jaan-to/ if the old directory exists and the new one doesn't.
  3. Creates directories — Ensures all required project directories exist:
    • jaan-to/outputs/
    • jaan-to/outputs/research/
    • jaan-to/learn/
    • jaan-to/context/
    • jaan-to/templates/
    • jaan-to/config/
    • jaan-to/docs/
  4. Seeds config — Copies settings.yaml from scripts/seeds/ to jaan-to/config/ if not present.
  5. Copies context files — Copies .md seed files from scripts/seeds/ to jaan-to/context/ (skips existing).
  6. Copies skill templates — Copies skills/*/template.md to jaan-to/templates/{skill-name}.template.md (skips existing).
  7. Copies docs — Copies STYLE.md and create-skill.md to jaan-to/docs/ (skips existing).
  8. Creates research README — Generates jaan-to/outputs/research/README.md with index scaffold if not present.
  9. Copies LEARN.md seeds — Copies skills/*/LEARN.md to jaan-to/learn/{skill-name}.learn.md (skips existing).
  10. Detects old standalone skills — Scans .claude/skills/ for legacy naming conventions (pre-v3.16 names).
  11. Checks context seeds — Verifies expected seed files (tech.md, team.md, integrations.md, config.md, boundaries.md) exist in the plugin.
  12. Suggests detect skills — If tech.md still contains {project-name} placeholder, suggests running /jaan-to:pack-detect to perform full repo analysis.

Behavior​

ResultConditionAction
Migrates directory.jaan-to/ exists, jaan-to/ doesn'tRenames .jaan-to/ → jaan-to/
Creates directoriesAny missingCreates all 7 directories listed above
Seeds configjaan-to/config/settings.yaml missingCopies from plugin seeds
Seeds contextContext .md files missingCopies from scripts/seeds/
Seeds templatesTemplate files missingCopies from skills/*/template.md
Seeds docsSTYLE.md or create-skill.md missingCopies from plugin docs
Seeds research indexoutputs/research/README.md missingGenerates scaffold README
Seeds learn files{skill-name}.learn.md missingCopies from skills/*/LEARN.md
Skips copyAny destination file already existsPreserves existing files
Suggests detect skillstech.md contains {project-name}Sets suggest_detect: true
WarnsOld standalone skills detectedReports migration_needed: true
WarnsContext seed files missing from pluginLists missing files

What You See​

First run (new project — files are seeded):

{
  "status": "complete",
  "config_loaded": true,
  "output_dir": "jaan-to/outputs",
  "learn_dir": "jaan-to/learn",
  "context_dir": "jaan-to/context",
  "templates_dir": "jaan-to/templates",
  "config_dir": "jaan-to/config",
  "paths_customized": false,
  "files_copied": {
    "config": 1,
    "context": 5,
    "templates": 12,
    "docs": 2,
    "learn": 8
  },
  "missing_context": [],
  "old_standalone_skills": [],
  "migration_needed": false,
  "suggest_detect": true
}

Subsequent runs (everything already exists):

{
  "status": "complete",
  "config_loaded": true,
  "output_dir": "jaan-to/outputs",
  "learn_dir": "jaan-to/learn",
  "context_dir": "jaan-to/context",
  "templates_dir": "jaan-to/templates",
  "config_dir": "jaan-to/config",
  "paths_customized": false,
  "files_copied": {
    "config": 0,
    "context": 0,
    "templates": 0,
    "docs": 0,
    "learn": 0
  },
  "missing_context": [],
  "old_standalone_skills": [],
  "migration_needed": false,
  "suggest_detect": false
}

With old standalone skills:

{
  "old_standalone_skills": ["pm-prd-write", "jaan-to-pm-prd-write"],
  "migration_needed": true
}

Config-Driven Paths​

All directory paths are resolved through scripts/lib/config-loader.sh, which reads from jaan-to/config/settings.yaml. This allows projects to customize where files are stored:

# jaan-to/config/settings.yaml
paths_outputs: "artifacts/generated"
paths_templates: "my-templates"
paths_learning: "knowledge/learn"
paths_context: "knowledge/context"

When custom paths are active, the output includes "paths_customized": true.

Why It Exists​

The plugin needs project-local directories for config, context, templates, outputs, docs, and learning data. Bootstrap creates these on first use and seeds them with starter files so skills work immediately. It's idempotent — running it multiple times is safe and only creates what's missing. Existing project files are never overwritten.