generic-automation-and-it/smooth-ai-stockanalysis / .agents/skills/ai-template-sync
ai-template-sync
VerifiedUPSERT 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 existing agentic files.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 2.3 KB |
| SKILL.md | skill md | 11.8 KB |
| agents/openai.yaml | config | 375 B |
| scripts/sync.ps1executable | script | 8.1 KB |
| scripts/sync.shexecutable | script | 7.5 KB |
SKILL.md
View on GitHub---
name: ai-template-sync
description: 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 existing agentic files.
allowed-tools:
- Bash(.agents/skills/ai-template-sync/scripts/sync.sh:*)
- Bash(git clone:*)
- Bash(mktemp:*)
- Bash(bash:*)
- Bash(rm:*)
models:
claude: opus # high-complexity; interactive multi-turn Q&A + conditional file sync across tools
copilot: auto
codex: gpt-5.5
---
# AI Template Sync — Skill
Sync the **smooth-ai-stockanalysis** agentic scaffold into a landing repo (UPSERT — safe merge, not destructive replace).
## TL;DR
0. If the template isn't checked out locally (running as a skill via web / hosted agent), clone it to a temp dir first.
1. Ask which AI tools to configure.
2. Optionally copy .NET solutioning.
3. Pre-flight: if `.agents/rules` isn't a symlink to `.github/instructions`, ask whether to move the rules.
4. Detect conflicts; ask for overwrite scope.
5. 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
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:
```bash
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.
```bash
.agents/skills/ai-template-sync/scripts/sync.sh \
--landing <LANDING_REPO> \
--tools claude,codex,copilot \
[--dotnet] \
--overwrite global|none
```
```powershell
.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:
```bash
.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |