apply-template

What this skill does

# Apply ai-env Template

Apply the agentic development environment template to the current repository.

**Argument:** optional path to ai-env clone. No argument = clone from GitHub (primary path).

---

## Phase 0 — Pre-flight

### Clean working tree check
Run `git status --porcelain`. If there are uncommitted changes, warn the user and ask whether to proceed or stash first. A dirty tree makes it hard to review what the template changed.

---

## Phase 1 — Source Resolution & Discovery

### Locate template source
1. If an argument was provided, use that path and verify it's a clean git checkout
2. If NO argument was provided, clone from GitHub:
   `git clone --depth 1 https://github.com/camacho/ai-env.git /tmp/ai-env-template` and use that
3. If the default local path `~/projects/camacho/ai-env` exists and no argument was given, prefer the GitHub clone (ensures latest version)
4. If all fail, tell the user and stop

### Read manifest
Read `apply-template.manifest.json` from the template source directory. This classifies every file as `copy_if_absent`, `smart_merge`, or `skip`.

### Scan target
Check which `copy_if_absent` and `smart_merge` files already exist in the current repo (cwd).

For `copy_if_absent` files that already exist in the target: these will be smart-merged (not skipped) to pick up any new template additions while preserving target customizations.

### Present plan
Show the user a summary:
```
Template Application Plan:
  Source: <path>
  Target: <cwd>

  Copy (new):        N files — <list>
  Smart merge (new): N files — <list of smart_merge files not in target>
  Smart merge (both): N files — <list of smart_merge files in both>
  Merge (existing copy_if_absent): N files — <list>
  Skipped:           N files (template-specific)

Proceed?
```
Wait for confirmation before continuing.

---

## Phase 2 — Copy

For each entry in `copy_if_absent`:
- **Directories** (entries ending with `/`): `mkdir -p` the target directory, then copy all files recursively. Skip individual files that already exist.
- **Files**: if the file does NOT exist in the target, copy it verbatim. If it exists, apply the same smart merge logic as Phase 3 (the file has diverged from template — preserve target intent while adding template additions).

Also ensure these directories exist even if empty:
- `ai-workspace/plans/`
- `ai-workspace/decisions/`

---

## Phase 3 — Smart Merge

For each file in `smart_merge`, read BOTH the template version and the target version (if it exists). If the target file doesn't exist, just copy the template version. If both exist, merge according to the rules below.

### AGENTS.md — Semantic Merge
- **Understand intent:** read both versions completely. Identify the purpose of each section.
- **Keep from target:** `## Stack`, `## Commands`, `## Architecture`, `## Gotchas` — preserve these sections entirely
- **Add from template if missing:** `## Agent Roles & Dispatch`, `## Protected Files`, `## Conventions`, `## Workflow Reference`, `## Context Loading Rules`
- **Resolve duplicates:** if both have a section with the same heading, favor the template version for structural/convention sections, favor the target for project-specific sections
- **Update:** the title line — replace the project name with the target repo's directory name
- **Preserve:** any custom sections the target has that aren't in the template
- **Cohesion check:** after merge, read the result and verify sections don't contradict each other

### tsconfig.json — Deep Merge
- **Start from template base** as the foundation
- **Deep merge `compilerOptions`:** overlay target's compilerOptions on top of template's. Target wins on collision.
- **Preserve from target:** `include`, `exclude`, `references`, and any other top-level keys
- **Inject if missing:** these strict options from the template: `strict`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `noFallthroughCasesInSwitch`
- **Surface conflicts:** if template and target have contradictory values for the same option (e.g., `strict: true` vs `strict: false`), present the conflict to the user for resolution
- **Cohesion test:** after merge, verify `compilerOptions` don't have contradictory flags (e.g., `module: "commonjs"` with `verbatimModuleSyntax: true`)

### .claude/settings.json
- **Preserve from target:** all existing `permissions.allow` and `permissions.deny` entries, `defaultMode`
- **Union merge:** `permissions.deny` arrays — add template entries not already present (deduplicate)
- **Union merge hooks:** for each hook event (PreToolUse, PostToolUse, etc.), keep all target hooks. Add template hooks only if no hook with the same `matcher` already exists in the target
- **Preserve:** any other keys the target has (disabledMcpjsonServers, enabledPlugins, etc.)

### package.json
- **Preserve from target:** `name`, `version`, `description`, `main`, `type`, `dependencies`, `repository`, `license`, `author` — everything except scripts and devDependencies
- **Merge scripts:** add any scripts from template that don't exist in target. Target wins on collision.
- **Merge devDependencies:** add packages from template that aren't in target's devDependencies (commitlint packages, lefthook, @biomejs/biome, typescript). Never remove or downgrade existing deps.
- **Add if missing:** `engines`, `packageManager`

### biome.json
- **Preserve from target:** all existing rules, `files` config, `formatter` config
- **Add if missing:** linter rules from template that don't exist in target
- **Never remove** any rule the target already has

### .gitignore
- **Union merge:** combine every unique line from both files, deduplicated
- **Preserve:** section comments (lines starting with `#`) and blank line groupings from both files
- **Order:** target's lines first, then new lines from template appended at the end under a `# ai-env template` comment

### skills-lock.json — Union Merge
- **Union merge `.skills` object:** combine all skill entries from both template and target. Each entry has `source` (git URL or local path, depending on `sourceType`), `sourceType` (`"git"` or `"local"`), and `computedHash` (SHA-256 integrity hash).
- **Template wins on conflict:** if the same skill name exists in both, use the template's entry (`source`, `sourceType`, `computedHash` all come from the template)
- **Never remove:** target skills not in the template are always preserved — projects may have custom skills
- **Top-level `version`:** keep the higher integer from either side (this is the lockfile schema version, not a skill version — individual skills do not have version fields)
- **Post-merge:** after writing the merged lockfile, instruct: "Run `npx skills install -a claude-code -a codex` to materialize any newly added skills for both agents"

Example merge logic:
```
Template:                                Target:
{ "version": 1, "skills": {             { "version": 1, "skills": {
    "validate": {                            "validate": {
      "source": "[email protected]",       "source": "[email protected]",
      "sourceType": "git",                     "sourceType": "git",
      "computedHash": "abc..."                 "computedHash": "abc..."
    },                                       },
    "reflect": {                             "custom-lint": {
      "source": "[email protected]",       "source": "local",
      "sourceType": "git",                     "sourceType": "local",
      "computedHash": "def..."                 "computedHash": "xyz..."
    }                                        }
}}                                       }}

                    ↓ merged result:
{ "version": 1, "skills": {
    "validate":    { ... },  ← kept (same in both)
    "custom-lint": { ... },  ← preserved (target-only)
    "reflect":     { ... }   ← added from template
}}
```

### Directories: `.claude/agents/`, `.claude/rules/`, `.claude/skills/`
- **Recurse** into each directory
- **New fi