ai-template-sync

UPSERT the smooth-ai-stockanalysis agentic scaffold into an existing repo. Asks which tools (Claude Code, Codex, Copilot) to configure, whether to copy .NET solutioning, and whether to overwrite exist

SKILL.md

GitHub

AI Template Sync — Skill

Sync the smooth-ai-stockanalysis agentic scaffold into a landing repo (UPSERT — safe merge, not destructive replace).

TL;DR

  1. If the template isn't checked out locally (running as a skill via web / hosted agent), clone it to a temp dir first.
  2. Ask which AI tools to configure.
  3. Optionally copy .NET solutioning.
  4. Pre-flight: if .agents/rules isn't a symlink to .github/instructions, ask whether to move the rules.
  5. Detect conflicts; ask for overwrite scope.
  6. Copy files per tool selection.

Phase 0 — Acquire Template (remote / web runs)

Run this ONLY when the template repo is not already checked out at the current location — i.e. the skill is invoked as a landing-repo skill (web / hosted agent / a repo that doesn't contain the template). If you are already inside a checkout of the template repo, skip Phase 0 and let --template default to the current git toplevel.

The sync scripts copy from the template tree (.agents/, .github/instructions/, copilot-instructions.md, optional src//tests/). None of that lives under the skill folder, so pulling just the skill is not enough. The script self-acquires the whole template: pass --template-url <git-url> (-TemplateUrl on Windows) instead of --template and it shallow-clones to a temp dir and cleans up on exit. Add --template-ref <tag|sha> to pin for reproducibility.

bash sync.sh --template-url https://github.com/generic-automation-and-it/smooth-ai-stockanalysis \
  --landing "$PWD" --tools <claude,codex,copilot> --overwrite <global|none> [--dotnet]

Caveats (one line): the runner needs Bash + git + network; a private template needs gh-auth or a token embedded in the clone URL.

The interactive phases below (1–3) still apply — gather intent and run the pre-flight before invoking the cloned script. Phase 0 only solves getting the files, not the decisions.


Phase 1 — Gather Intent (ask, then stop for answers)

Ask the user all questions in one message:

1. Which AI tools to configure? (comma-separate any combo)
   a) Claude Code   b) OpenAI Codex   c) GitHub Copilot

2. Copy .NET solutioning? (only asked if the landing repo has no *.slnx / *.sln)
   Includes: smooth-ai-stockanalysis.slnx · Directory.Build.props · Directory.Packages.props
             NuGet.Config · src/ · tests/
   [y/n]

3. Overwrite mode for agentic files?
   A) Global overwrite — replace every agentic file without further prompting
   B) Selective — show me a conflict table first; I'll pick what to overwrite
   (Dotnet files are never overwritten regardless of choice.)

Wait for user answers before proceeding.


Phase 2 — Rules-Layout Pre-flight (ALWAYS run, even in Global mode)

The template's contract is: .github/instructions/ is the real directory that holds the rule files, and .agents/rules is a symlink pointing to it. A landing repo may not follow this — it may keep .agents/rules as a real directory of its own rules, or symlinked somewhere else.

This matters because Section D of the sync (scripts/sync.sh) unconditionally runs rm -rf .agents/rules and re-points the symlink — in both overwrite modes. If .agents/rules is a real directory, that step destroys the repo's own rules. So this check runs regardless of the Phase 1 overwrite choice, and only when copilot is among the selected tools (Section D runs only then).

Inspect the landing repo:

readlink "<LANDING_REPO>/.agents/rules"   # prints ../.github/instructions in a conforming repo; empty/non-zero exit if it's a real dir

If .agents/rules exists but is not a symlink resolving to .github/instructions (i.e. it is a real directory, or a symlink pointing elsewhere), stop and ask before running the sync:

Your repo's `.agents/rules` is NOT a symlink to `.github/instructions`
(it is <a real directory | a symlink to X>).

The template keeps rule files in `.github/instructions/`, with `.agents/rules`
symlinked to it. The sync would otherwise delete `.agents/rules` and re-point it,
losing your existing rules.

Move your existing rules into `.github/instructions/` and re-point
`.agents/rules` at it as part of this update? [y/n]
  • y → before invoking the script, move the existing rule files into .github/instructions/ (merge, don't clobber the template rules), then let Section D re-point the .agents/rules symlink. The repo's own rules are preserved.
  • n → do not run with copilot in --tools (Section D would still rm -rf .agents/rules). Either drop copilot from the tools list, or sync the other tools first and handle Copilot's rules dir manually. Leave the existing layout untouched.

If .agents/rules already symlinks to .github/instructions, or neither path exists, take no action and proceed.


Phase 3 — Conflict Detection (Selective mode only)

Skip if user chose Global overwrite.

Agentic file inventory

Category Files / paths
Base scaffold .agents/** (all files recursively) · AGENTS.md
Claude Code .claude (symlink) · CLAUDE.md (symlink) · GEMINI.md (symlink)
Codex .codex (symlink)
Copilot .github/copilot-instructions.md · .github/instructions (real directory — holds the rule files; .agents/rules symlinks to it)
Setup scripts .agents/setup/scripts/agents-setup.sh · .agents/setup/scripts/agents-setup.ps1 · .agents/setup/scripts/agents-terminals.sh · .agents/setup/scripts/agents-terminals.ps1

Check each file/path against the landing repo. Build a conflict table for every item that already exists:

# Name Purpose Action
1 .agents/hooks/load-agents-context.sh PostToolUse hook — emits AGENTS.md context skip
… … … …

Print the table, then ask:

Enter IDs to overwrite (e.g. "1 3 5"), "all", or "none":

Collect the response before moving to Phase 4.


Phase 4 — Execute Sync

The mechanical copy/symlink work (Sections A–E) is performed by scripts/sync.sh (scripts/sync.ps1 on Windows). You decide the flags from the Phase 1–3 answers; the script executes them. It is idempotent and supports two overwrite modes — global (clobber) and none (additive, never clobber).

Never touch dotnet files (.slnx, .sln, Directory.*.props, NuGet.Config, src/, tests/) during agentic sync, even if the user requests it here. The script's --dotnet path only ever adds them when no solution exists, and never overwrites.

.agents/skills/ai-template-sync/scripts/sync.sh \
  --landing <LANDING_REPO> \
  --tools claude,codex,copilot \
  [--dotnet] \
  --overwrite global|none
.agents/skills/ai-template-sync/scripts/sync.ps1 `
  -Landing <LANDING_REPO> `
  -Tools claude,codex,copilot `
  [-Dotnet] `
  -Overwrite global|none
Flag Maps to Notes
--tools / -Tools Phase 1 Q1 Comma-separated subset of claude,codex,copilot. Drives Sections B/C/D.
--dotnet / -Dotnet Phase 1 Q2 Section E. Skipped automatically if a .slnx/.sln already exists.
--overwrite global Phase 1 Q3 = A Clobber every agentic file.
--overwrite none Phase 1 Q3 = B (after selection) Additive only — never clobber existing files.
--template / -Template (auto) Template repo root; defaults to the current git toplevel.
--template-url / -TemplateUrl Phase 0 Git URL of the template; the script shallow-clones it to a temp dir and cleans up on exit. Mutually exclusive with --template. Use for remote / web runs.
--template-ref / -TemplateRef (optional) Tag/branch/SHA to pin the --template-url clone to. Use for reproducible rule installs.
--rules-only / -RulesOnly (optional) Sync ONLY the rule system — see Rules-Only Distribution below.

What each section does (now inside the script):

  • A — .agents/ base tree: rsync (global = overwrite, none = --ignore-existing); never deletes landing-only files.
  • B — Claude Code: .claude→.agents, CLAUDE.md/GEMINI.md→AGENTS.md symlinks + git config core.symlinks true.
  • C — Codex: .codex→.agents symlink.
  • D — Copilot: copies the real .github/instructions/ dir, re-points .agents/rules symlink at it, copies copilot-instructions.md.
  • E — .NET: copies Directory.*.props, NuGet.Config, *.slnx, src/, tests/ only when absent. Rename SmoothAiStockAnalysis.* → <ActualProjectName> afterwards (the script prints this reminder; the rename itself is the agent's job).

Selective overwrite (Phase 1 Q3 = B): the script handles global and none only. For true per-file selection, copy the user-approved files manually first, then run the script with --overwrite none so it adds the remainder without clobbering anything.


Rules-Only Distribution (--rules-only)

Distribute or update the rule system as a package — .github/instructions/ (the real rules dir, shared by Claude/Cursor/Copilot via symlinks) plus the .agents/rules symlink — without touching skills, hooks, setup scripts, or dotnet files:

.agents/skills/ai-template-sync/scripts/sync.sh \
  --template-url https://github.com/generic-automation-and-it/smooth-ai-stockanalysis \
  --template-ref v1.2.0 \
  --landing "$PWD" \
  --rules-only \
  --overwrite global|none

Semantics:

  • --overwrite global updates same-named rule files to the pinned version; none only adds missing ones. Landing-only rule files are never deleted in either mode (UPSERT) — a consumer's own rules survive updates.
  • --tools / --dotnet are ignored; Phases 1 and 3 don't apply. The Phase 2 rules-layout pre-flight is built into the script here: it refuses (exit 65) if .agents/rules is a real directory.
  • Re-run with a newer --template-ref to upgrade — this is the supported way to consume this repo's rules from other repositories.

Phase 5 — Post-Sync Checklist

After all copies/symlinks are done, report:

✅ Sync complete. Next steps for the landing repo:

□ Run the setup script once:
    bash .agents/setup/scripts/agents-setup.sh   # Mac/Linux
    pwsh .agents/setup/scripts/agents-setup.ps1  # Windows

□ Update AGENTS.md — replace template placeholder content with real project context.

□ [Claude Code] Verify `.claude/` symlink resolves:  ls -la .claude

□ [Codex] Verify `.codex/` symlink resolves:  ls -la .codex

□ [Copilot] Verify `.github/instructions/` is a real dir and `.agents/rules` symlinks to it:  ls -la .github/instructions .agents/rules

□ [.NET] Rename SmoothAiStockAnalysis.* → <ActualProjectName> everywhere (if .NET was copied).

□ Commit the agentic scaffold with:  git add -A && git commit -m "chore: add smooth-devex agentic scaffold"

Guardrails

  • Never overwrite dotnet files (.slnx, .sln, Directory.*.props, NuGet.Config, src/, tests/) during agentic sync.
  • Never delete landing-repo files absent from the template.
  • Always confirm before executing file writes/copies; show the plan first.
  • In Selective mode, skip any file not explicitly approved by the user.
  • Symlinks require git config core.symlinks true; remind the user if the repo was cloned with symlinks off.