siesa-agents 2.1.81 → 2.1.82

package/claude/skills/sa-init-devops/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: sa-init-devops
+description: 'Bootstrap the DevOps workspace and skills in Siesa-Agents in one shot: clones architecture-sa-devops into `_siesa-agents/devops/`, detects conflicts between local and upstream copies of the `sa-*` DevOps skills and the deploy workflows (asks the user via AskUserQuestion which side to keep when there are diffs), then MOVES the chosen versions into `.claude/skills/` (and `claude/skills/`) so `/sa-aplicar`, `/sa-nuevo-servicio`, `/sa-auditar-servicio`, etc. become immediately invocable, MOVES the workflows into `.github/workflows/`, deletes the now-empty `.claude/` and `.github/` directories from the clone, then mirrors the cleaned tree to `siesa-agents/devops/`. Use whenever the user wants to set up the DevOps workspace for the first time, refresh it after upstream changes, mentions needing terraform/k8s/environments files, or when any `sa-*` deploy skill is missing from Claude Code.'
+---
+
+# Init DevOps — clone the workspace + materialize the DevOps skills
+
+**Goal:** In a single invocation, populate Siesa-Agents with everything an engineer needs to run the Finance DevOps skills. After a successful run the layout is:
+
+| Location | Contents |
+|---|---|
+| `_siesa-agents/devops/` | Git working tree cloned from `architecture-sa-devops`. **Only** the deployment workspace: `terraform/`, `k8s/`, `environments/`, `scripts/`, `cicd-templates/`, `docs/`, `CLAUDE.md`, `README.md`, `.gitignore`. The `.claude/` and `.github/` directories from upstream are wiped from the clone after their contents are moved to Siesa-Agents level. |
+| `siesa-agents/devops/` | Flat snapshot mirror of the cleaned clone (no `.git/`, no `.claude/`, no `.github/`). The npm-publishable copy. |
+| `.claude/skills/sa-*/SKILL.md` | The 8 DevOps skills moved out of the clone: `sa-aplicar`, `sa-auditar-servicio`, `sa-nueva-transversal`, `sa-nuevo-ambiente`, `sa-nuevo-servicio`, `sa-onboard-db`, `sa-registrar-permisos`, `sa-agent-sre-sentinel`. |
+| `claude/skills/sa-*/SKILL.md` | Same skills, in the npm mirror. |
+| `.github/workflows/*.yml` | The 4 deploy workflow files moved out of the clone (`infra-pipeline-dev/qa/shared.yml`, `reconcile-geographic-projections.yml`). **These do not fire from Siesa-Agents** — gitignored, for visibility only. They fire from `architecture-sa-devops` where they originally live. |
+
+**Why this matters:** Without this skill, Siesa-Agents is missing every Finance DevOps capability. The DevOps skills cannot live statically in this repo because they evolve with the deploy workspace (`environments/`, `terraform/`, `k8s/`) — keeping them in sync would require a PR every time Finance bumps the workspace. Instead the upstream `architecture-sa-devops` repo is the single source of truth, and this skill pulls everything down on demand.
+
+## When to use this skill
+
+Trigger immediately when the user:
+
+- Says "init devops", "setup devops", "clone architecture-sa-devops", "trae el workspace de despliegue", or similar
+- Tries to invoke any deploy skill (`/sa-aplicar`, `/sa-nuevo-servicio`, etc.) and Claude Code reports the skill is not available
+- Tries to invoke a deploy skill and it complains about missing paths (`environments/shared.yaml`, `terraform/environments/`, `k8s/overlays/`, etc.)
+- Mentions wanting to refresh / pull latest from `architecture-sa-devops`
+- Has just cloned Siesa-Agents and is preparing to use the deploy skills
+
+Do **not** trigger for: editing the deploy skills themselves (those edits must go to `architecture-sa-devops`), modifying terraform/k8s contents (those go to `architecture-sa-devops` too), or anything unrelated to bootstrapping.
+
+## Prerequisites
+
+- `git` is on the PATH (`git --version` works).
+- The user has network access to GitHub.com.
+- The helper script lives at `_siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js` (source of truth) and is mirrored to `siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js` (npm copy). Prefer the source-of-truth path when both exist.
+
+If the script is missing or `git` is unavailable, stop and tell the user — do not improvise the work inline. The script handles all the edge cases (existing clone with wrong remote, partial state, conflicting local edits, skill/workflow copy overwrites) that an inline shell sequence would miss.
+
+## Workflow
+
+Two-phase orchestration. The helper does an initial conflict-detection pass; if any local file differs from upstream, the helper aborts and the model asks the user how to resolve, then re-runs with a policy flag.
+
+### Step 1 — Initial run
+
+From the project root (or any subdirectory of it — the script walks up to find both `_siesa-agents/` and `siesa-agents/`):
+
+```bash
+node _siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js
+```
+
+Default mode does:
+
+1. **Clone or update.** `git clone` (if `_siesa-agents/devops/` does not exist) **or** `git checkout HEAD -- .claude .github && git fetch && git checkout main && git pull --ff-only` (if it does). The `git checkout HEAD -- .claude .github` step restores files that the previous run wiped so the pull doesn't fail on "uncommitted deletions".
+2. **Dry-run conflict detection.** For each upstream `.claude/skills/sa-*/SKILL.md` and `.github/workflows/*.yml`, compare to the local copy in Siesa-Agents (`.claude/skills/`, `claude/skills/`, and `.github/workflows/`). The bootstrap skill `sa-init-devops` is always excluded from this comparison.
+3. **If any local file differs from upstream → abort.** Exit 4 with `status: "conflicts"` and lists `skill_conflicts` / `workflow_conflicts`. Nothing is mutated. The model proceeds to Step 2.
+4. **If no conflicts → apply.** Copy the upstream files into Siesa-Agents (creating new files, leaving identical ones alone), then delete `.claude/` and `.github/` from the clone working tree, then mirror the cleaned tree to `siesa-agents/devops/`. Exit 0.
+
+### Step 2 — Handle conflicts (only when `status: "conflicts"`)
+
+When the JSON output has `status: "conflicts"`, **ask the user which side to keep** before any local file is changed. Use `AskUserQuestion` with the list of conflicting items from `skill_conflicts` and `workflow_conflicts`.
+
+For most cases, one question with three options is enough:
+
+```
+question: "Estos N archivos locales difieren del upstream architecture-sa-devops:
+           <list with skill_conflicts + workflow_conflicts>
+           ¿Cómo resuelvo?"
+options:
+  - "Take all from upstream" (overwrite all conflicts with upstream version)
+  - "Keep all local versions" (preserve every local edit)
+  - "Resolve per file" (only if user wants per-item granularity)
+```
+
+If the user picks **"Take all from upstream"**, re-run with `--take-upstream`:
+
+```bash
+node _siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js --take-upstream
+```
+
+If the user picks **"Keep all local versions"**, re-run with `--keep-local`:
+
+```bash
+node _siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js --keep-local
+```
+
+If the user picks **"Resolve per file"**, ask one more question per conflicting item (with `AskUserQuestion`, max 4 items per call — chunk if needed) collecting which ones to keep local, then re-run with `--keep-local=<csv>`:
+
+```bash
+node _siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js --keep-local=sa-aplicar,infra-pipeline-qa.yml
+```
+
+The named items keep their local version; everything else takes upstream.
+
+### Step 3 — Interpret the final JSON status
+
+After the (possibly second) successful invocation, read the `status` field:
+
+- **`status: "cloned"`** — Fresh clone. Tell the user: "Cloned `architecture-sa-devops`. Created `<N>` skills + `<M>` workflows in Siesa-Agents. The deploy skills (`/sa-aplicar`, `/sa-nuevo-servicio`, etc.) are now available in Claude Code."
+- **`status: "updated"`** — Existing clone pulled new commits. Report `before_sha..after_sha` and the per-category counts (`skills_created`, `skills_overwritten`, `skills_kept_local`, `skills_unchanged`, same for workflows).
+- **`status: "already-cloned"`** — Local clone was already at the latest HEAD; no upstream change. The counts reflect what happened in the apply step (likely all `unchanged` if everything matched).
+- **`status: "conflicts"`** — Should only appear on the FIRST run when conflicts exist; never on a re-run with a policy flag. If you see this twice, surface it as a bug.
+- **`status: "invalid-source"`** — `_siesa-agents/devops/` exists but is not a git working tree. Surface the message verbatim and stop. Do not try to delete the directory automatically.
+- **`status: "wrong-remote"`** — Same directory is a clone of a different repo. Surface the message and stop.
+- **`status: "clone-failed"` / `"fetch-failed"` / `"pull-failed"` / `"checkout-failed"`** — Git operation failed. Surface the underlying git error verbatim. Common causes: no network, branch diverged, local edits blocking ff-pull.
+
+### Step 3 — Remind the user about cwd for the deploy skills
+
+After a successful run (any of `cloned`, `updated`, `already-cloned`), remind the user once:
+
+> Las skills de despliegue (`/sa-aplicar`, `/sa-nuevo-servicio`, etc.) asumen que el cwd está dentro de `_siesa-agents/devops/`. Cambia de directorio (`cd _siesa-agents/devops/`) antes de invocarlas, para que las rutas relativas (`environments/`, `terraform/`, `k8s/`) se resuelvan correctamente.
+
+If the user invokes one of those skills from elsewhere, the relative paths in their workflows won't resolve and they'll see confusing "file not found" errors.
+
+## Optional flags
+
+- `--check` — Read-only. Clones/pulls if needed, then reports current state plus a dry-run conflict list. Useful to preview what a real run would surface.
+- `--mirror-only` — Skip the git + move steps; rebuild `siesa-agents/devops/` from the existing clone. Useful when only the mirror is out of sync.
+- `--take-upstream` — Resolve all conflicts in favor of upstream (overwrite every conflicting local file). Use after the user confirms they want the upstream versions.
+- `--keep-local` — Keep every local file as-is; only create files that are entirely new in upstream. Use when the user wants to preserve all local edits.
+- `--keep-local=<csv>` — Keep these specific items local (comma-separated names matching `skill_conflicts` / `workflow_conflicts` entries); overwrite all other conflicts with upstream. Example: `--keep-local=sa-aplicar,infra-pipeline-qa.yml`.
+
+The three policy flags are mutually exclusive; passing more than one returns exit code 1.
+
+## Edge cases
+
+- **Skill conflicts.** The default run aborts on any conflict (local file differs from upstream) and lists them in `skill_conflicts` / `workflow_conflicts`. The model then asks the user with `AskUserQuestion` and re-runs with `--take-upstream`, `--keep-local`, or `--keep-local=<csv>`. Engineers who want their custom edits to survive automatic refresh should fork `architecture-sa-devops` and update `REMOTE_URL` at the top of the helper script — that keeps their fork as the upstream source of truth.
+- **The bootstrap skill is never overwritten.** `sa-init-devops/` is explicitly excluded from the copy loop in the helper, so re-running the skill cannot trash itself.
+- **The clone has 12 "deleted" files in `git status` after every run.** Expected. The script moves `.claude/skills/sa-*/SKILL.md` and `.github/workflows/*.yml` out of the clone and deletes those directories, but the files are still tracked in upstream HEAD. The next run restores them via `git checkout HEAD -- .claude .github` before pulling, then moves and deletes them again. Engineers should never `git add` or `git commit` those deletions inside `_siesa-agents/devops/` — they are intentional working-tree-only state.
+- **Workflows in Siesa-Agents `.github/workflows/`** — moved for inspection but gitignored (see `.gitignore`), so engineers can read them locally but they never fire on Siesa-Agents PRs. The same workflows fire on PRs / pushes to `architecture-sa-devops`, which is where they live.
+- **`_siesa-agents/devops/` exists from a previous run with local edits to non-managed paths.** The restore step touches only `.claude` and `.github`; edits to `environments/`, `terraform/`, `k8s/`, etc. survive the restore step but `git pull --ff-only` will fail if they conflict with upstream. The script surfaces the git error verbatim. The user should commit, stash, or discard their local changes and re-run.
+- **The directory exists but isn't a clone of `architecture-sa-devops`.** The script reports `invalid-source` or `wrong-remote` and refuses to delete. The user must move it aside manually.
+- **The mirror or local skills/workflows have manual edits.** The script overwrites them on every run — that is by design. If you need to preserve edits, make them in the upstream `architecture-sa-devops` repo, not locally.
+- **No `git` on PATH.** The first `tryGit` call fails; the script surfaces a `clone-failed` or `fetch-failed` status. Tell the user to install git or add it to PATH.
+
+## Upstream URL
+
+The script currently points at `https://github.com/ssancheze912/architecture-sa-devops.git` as a temporary location while SiesaTeams org-create permissions are being arranged. When the repo is transferred to `https://github.com/SiesaTeams/architecture-sa-devops.git`, update `REMOTE_URL` at the top of the helper script and ship the change.
+
+## Reminders
+
+- Step 1 is always safe to re-run. Idempotency is built into the script — on `already-cloned` it does nothing destructive other than refresh the mirror and re-copy the skills/workflows from upstream (which is the intended behavior — keeping local in sync with upstream).
+- Never delete `_siesa-agents/devops/` from this skill. The user owns that directory once cloned; they may have in-progress edits.
+- Do not modify the DevOps skills themselves from this skill. If a deploy skill's behavior needs to change, that is a PR to `architecture-sa-devops`, not a local edit (which would be wiped on the next run).
+- The script's JSON output is the contract. If a future field appears (e.g. a new status), surface it to the user rather than guessing what it means.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.81",
+  "version": "2.1.82",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/sa/sa-init-devops/scripts/sa-init-devops.js

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+// sa-init-devops.js — Bootstrap the DevOps workspace and skills in Siesa-Agents.
+//
+// In one invocation the script:
+//   1. Clones (or pulls) architecture-sa-devops into `_siesa-agents/devops/`.
+//   2. Detects conflicts: for each upstream `.claude/skills/sa-*/SKILL.md` and
+//      `.github/workflows/*.yml`, compares to the local copy in Siesa-Agents. If any local
+//      file differs from upstream and no policy flag was passed, aborts with `status:
+//      "conflicts"` and lists the conflicting items so the caller can ask the user how to
+//      resolve them.
+//   3. If there are no conflicts, or the caller passed `--take-upstream` / `--keep-local`
+//      / `--keep-local=<csv>`, moves the upstream files into Siesa-Agents according to the
+//      policy and deletes the `.claude/` and `.github/` directories from the clone.
+//   4. Mirrors the cleaned working tree to `siesa-agents/devops/`.
+//
+// Conflict policy flags (mutually exclusive):
+//   --take-upstream            Overwrite all conflicting local files with the upstream copy.
+//   --keep-local               Keep every local file as-is. Only create files that are
+//                              entirely new in upstream.
+//   --keep-local=<csv>         Keep these specific files (comma-separated names) local;
+//                              overwrite the rest. Example:
+//                              --keep-local=sa-aplicar,infra-pipeline-qa.yml
+//
+// Idempotency: between runs the clone's `.claude/` and `.github/` directories are gone from
+// the working tree but still tracked in upstream HEAD. The script restores those paths
+// (`git checkout HEAD -- .claude .github`) before the pull so it doesn't fail on
+// "uncommitted deletions". The move-and-delete cycle then repeats.
+//
+// Modes:
+//   <no args> or --clone   Default. Clone or update, detect conflicts, abort if any,
+//                          otherwise move + delete + mirror.
+//   --check                Read-only. Report the current state without mutating.
+//   --mirror-only          Skip the git + move steps; rebuild the mirror from the
+//                          current clone.
+//
+// Exit codes:
+//   0  Success
+//   1  Argument or usage error
+//   2  No-op (--check on a clean state)
+//   3  Git or filesystem mutation failed
+//   4  Conflicts detected; the caller should ask the user and re-run with a policy flag.
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+// TODO(siesa-admin): change to https://github.com/SiesaTeams/architecture-sa-devops.git
+// once the repo is transferred to the SiesaTeams organization.
+const REMOTE_URL = 'https://github.com/ssancheze912/architecture-sa-devops.git'
+const REMOTE_NAME = 'origin'
+const DEFAULT_BRANCH = 'main'
+
+function parseArgs(argv) {
+  const out = { _keepLocalList: null }
+  for (const a of argv) {
+    if (!a.startsWith('--')) continue
+    const eq = a.indexOf('=')
+    if (eq === -1) {
+      out[a.slice(2)] = true
+    } else {
+      const key = a.slice(2, eq)
+      const val = a.slice(eq + 1)
+      out[key] = val
+      if (key === 'keep-local') {
+        out._keepLocalList = val.split(',').map(s => s.trim()).filter(Boolean)
+      }
+    }
+  }
+  return out
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n')
+}
+
+function findProjectRoot(startDir) {
+  let cur = path.resolve(startDir)
+  for (let i = 0; i < 40; i++) {
+    if (fs.existsSync(path.join(cur, '_siesa-agents')) && fs.existsSync(path.join(cur, 'siesa-agents'))) {
+      return cur
+    }
+    const parent = path.dirname(cur)
+    if (parent === cur) return null
+    cur = parent
+  }
+  return null
+}
+
+function tryGit(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  return {
+    ok: r.status === 0,
+    code: r.status,
+    stdout: (r.stdout || '').trim(),
+    stderr: (r.stderr || '').trim(),
+  }
+}
+
+function isGitWorkingTree(dir) {
+  if (!fs.existsSync(path.join(dir, '.git'))) return false
+  const r = tryGit(['rev-parse', '--show-toplevel'], dir)
+  return r.ok && path.resolve(r.stdout) === path.resolve(dir)
+}
+
+function currentRemoteUrl(dir) {
+  const r = tryGit(['remote', 'get-url', REMOTE_NAME], dir)
+  return r.ok ? r.stdout : null
+}
+
+function rmDirSafe(dir) {
+  fs.rmSync(dir, { recursive: true, force: true })
+}
+
+function copyTreeWithoutGit(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true })
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+  for (const ent of entries) {
+    if (ent.name === '.git') continue
+    const srcPath = path.join(srcDir, ent.name)
+    const destPath = path.join(destDir, ent.name)
+    if (ent.isDirectory()) {
+      copyTreeWithoutGit(srcPath, destPath)
+    } else if (ent.isFile()) {
+      fs.copyFileSync(srcPath, destPath)
+    } else if (ent.isSymbolicLink()) {
+      const target = fs.readlinkSync(srcPath)
+      try { fs.symlinkSync(target, destPath) } catch (_) { /* Windows may need elevated perms */ }
+    }
+  }
+}
+
+// Compare two files for equality, normalizing CRLF→LF so Windows line-ending quirks don't
+// create spurious conflicts. Returns true if both files have the same logical content.
+function filesEqual(a, b) {
+  if (!fs.existsSync(a) || !fs.existsSync(b)) return false
+  try {
+    const ba = fs.readFileSync(a).toString('utf8').replace(/\r\n/g, '\n')
+    const bb = fs.readFileSync(b).toString('utf8').replace(/\r\n/g, '\n')
+    return ba === bb
+  } catch (_) {
+    return false
+  }
+}
+
+function refreshMirror(sourceDir, mirrorDir, status) {
+  const hadMirror = fs.existsSync(mirrorDir)
+  if (hadMirror) rmDirSafe(mirrorDir)
+  copyTreeWithoutGit(sourceDir, mirrorDir)
+  status.mirror_refreshed = true
+  status.mirror_dir = mirrorDir
+  status.mirror_existed_before = hadMirror
+}
+
+// Decide what to do with a single upstream item given the policy flags and the local state.
+// Returns one of: 'create' (no local copy yet), 'identical' (already matches upstream),
+// 'conflict' (differs and no policy says how to resolve), 'overwrite' (differs but policy
+// resolves it as upstream-wins), 'keep-local' (differs but policy says keep local).
+function decideAction(name, upstreamPath, localPaths, policy) {
+  const anyLocalExists = localPaths.some(p => fs.existsSync(p))
+  if (!anyLocalExists) return 'create'
+
+  // If every local copy matches upstream, nothing to do.
+  if (localPaths.every(p => filesEqual(p, upstreamPath))) return 'identical'
+
+  // At least one local copy differs from upstream — this is a conflict.
+  if (policy.keepLocalAll) return 'keep-local'
+  if (policy.keepLocalList && policy.keepLocalList.includes(name)) return 'keep-local'
+  if (policy.takeUpstream) return 'overwrite'
+  return 'conflict'
+}
+
+// MOVE `<sourceDir>/.claude/skills/sa-*/SKILL.md` into Siesa-Agents `.claude/skills/sa-*/`
+// (and `claude/skills/sa-*/`) according to the policy. Records conflicts in
+// status.skill_conflicts; the caller checks that before any mutation happens.
+function planAndApplySkills(sourceDir, projectRoot, status, policy, dryRun) {
+  const srcSkillsDir = path.join(sourceDir, '.claude', 'skills')
+  status.skills_created = []
+  status.skills_overwritten = []
+  status.skills_kept_local = []
+  status.skills_unchanged = []
+  status.skill_conflicts = []
+
+  if (!fs.existsSync(srcSkillsDir)) {
+    status.skills_source_missing = true
+    return
+  }
+
+  const dstA = path.join(projectRoot, '.claude', 'skills')
+  const dstB = path.join(projectRoot, 'claude', 'skills')
+
+  for (const entry of fs.readdirSync(srcSkillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    if (!entry.name.startsWith('sa-')) continue
+    if (entry.name === 'sa-init-devops') continue   // never overwrite the bootstrap itself
+    const srcSkill = path.join(srcSkillsDir, entry.name, 'SKILL.md')
+    if (!fs.existsSync(srcSkill)) continue
+
+    const dstSkillA = path.join(dstA, entry.name, 'SKILL.md')
+    const dstSkillB = path.join(dstB, entry.name, 'SKILL.md')
+
+    const action = decideAction(entry.name, srcSkill, [dstSkillA, dstSkillB], policy)
+
+    if (action === 'conflict') {
+      status.skill_conflicts.push(entry.name)
+      continue
+    }
+    if (action === 'identical') {
+      status.skills_unchanged.push(entry.name)
+      continue
+    }
+    if (dryRun) continue
+
+    if (action === 'create' || action === 'overwrite') {
+      fs.mkdirSync(path.dirname(dstSkillA), { recursive: true })
+      fs.mkdirSync(path.dirname(dstSkillB), { recursive: true })
+      fs.copyFileSync(srcSkill, dstSkillA)
+      fs.copyFileSync(srcSkill, dstSkillB)
+      if (action === 'create') status.skills_created.push(entry.name)
+      else status.skills_overwritten.push(entry.name)
+    } else if (action === 'keep-local') {
+      status.skills_kept_local.push(entry.name)
+    }
+  }
+}
+
+function planAndApplyWorkflows(sourceDir, projectRoot, status, policy, dryRun) {
+  const srcDir = path.join(sourceDir, '.github', 'workflows')
+  status.workflows_created = []
+  status.workflows_overwritten = []
+  status.workflows_kept_local = []
+  status.workflows_unchanged = []
+  status.workflow_conflicts = []
+
+  if (!fs.existsSync(srcDir)) {
+    status.workflows_source_missing = true
+    return
+  }
+
+  const dstDir = path.join(projectRoot, '.github', 'workflows')
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue
+    if (!(entry.name.endsWith('.yml') || entry.name.endsWith('.yaml'))) continue
+
+    const srcFile = path.join(srcDir, entry.name)
+    const dstFile = path.join(dstDir, entry.name)
+
+    const action = decideAction(entry.name, srcFile, [dstFile], policy)
+
+    if (action === 'conflict') {
+      status.workflow_conflicts.push(entry.name)
+      continue
+    }
+    if (action === 'identical') {
+      status.workflows_unchanged.push(entry.name)
+      continue
+    }
+    if (dryRun) continue
+
+    if (action === 'create' || action === 'overwrite') {
+      fs.mkdirSync(dstDir, { recursive: true })
+      fs.copyFileSync(srcFile, dstFile)
+      if (action === 'create') status.workflows_created.push(entry.name)
+      else status.workflows_overwritten.push(entry.name)
+    } else if (action === 'keep-local') {
+      status.workflows_kept_local.push(entry.name)
+    }
+  }
+}
+
+// After a successful apply (no conflicts left), wipe the .claude/ and .github/ directories
+// from the clone working tree. These remain tracked in upstream HEAD; restoreClonePaths()
+// brings them back before the next pull.
+function cleanCloneDirs(sourceDir) {
+  for (const sub of ['.claude', '.github']) {
+    const p = path.join(sourceDir, sub)
+    if (fs.existsSync(p)) rmDirSafe(p)
+  }
+}
+
+// Before pulling, restore `.claude/` and `.github/` paths in the clone working tree.
+// They are tracked in HEAD but get wiped at the end of every run. Without this restore,
+// `git pull --ff-only` would refuse to proceed because the working tree has uncommitted
+// deletions. `git checkout HEAD -- .claude .github` is a no-op if the paths already exist.
+function restoreClonePaths(sourceDir) {
+  tryGit(['checkout', 'HEAD', '--', '.claude', '.github'], sourceDir)
+}
+
+function resolveTargets(projectRoot) {
+  return {
+    sourceDir: path.join(projectRoot, '_siesa-agents', 'devops'),
+    mirrorDir: path.join(projectRoot, 'siesa-agents', 'devops'),
+  }
+}
+
+function buildPolicy(args) {
+  // Both --keep-local with no value (`--keep-local` alone, no `=`) AND with a value (`--keep-local=...`)
+  // need to be distinguished. parseArgs sets out['keep-local'] = true when no `=`, and = '<value>' when there is.
+  const keepLocalArg = args['keep-local']
+  return {
+    takeUpstream: Boolean(args['take-upstream']),
+    keepLocalAll: keepLocalArg === true,                       // bare `--keep-local`
+    keepLocalList: Array.isArray(args._keepLocalList) ? args._keepLocalList : null,
+  }
+}
+
+function validatePolicy(policy, status) {
+  const setCount = [policy.takeUpstream, policy.keepLocalAll, policy.keepLocalList !== null].filter(Boolean).length
+  if (setCount > 1) {
+    status.status = 'error'
+    status.message = 'Conflicting flags: pass at most one of --take-upstream, --keep-local, --keep-local=<csv>.'
+    return false
+  }
+  return true
+}
+
+function runCheck(projectRoot) {
+  const { sourceDir, mirrorDir } = resolveTargets(projectRoot)
+  const state = {
+    status: 'unknown',
+    project_root: projectRoot,
+    source_dir: sourceDir,
+    mirror_dir: mirrorDir,
+    remote_url: REMOTE_URL,
+  }
+
+  if (!fs.existsSync(sourceDir)) {
+    state.status = 'missing'
+    state.message = `${sourceDir} does not exist. Run without --check to clone ${REMOTE_URL}.`
+    emit(state)
+    return 2
+  }
+
+  if (!isGitWorkingTree(sourceDir)) {
+    state.status = 'invalid-source'
+    state.message = `${sourceDir} exists but is not a git working tree. Move it aside or delete it manually before re-running this skill.`
+    emit(state)
+    return 3
+  }
+
+  const actualRemote = currentRemoteUrl(sourceDir)
+  state.actual_remote_url = actualRemote
+  if (actualRemote !== REMOTE_URL) {
+    state.status = 'wrong-remote'
+    state.message = `${sourceDir} is a git clone but its origin points at ${actualRemote} (expected ${REMOTE_URL}). Move it aside manually before re-running.`
+    emit(state)
+    return 3
+  }
+
+  state.mirror_exists = fs.existsSync(mirrorDir)
+  state.clone_has_claude_dir = fs.existsSync(path.join(sourceDir, '.claude'))
+  state.clone_has_github_dir = fs.existsSync(path.join(sourceDir, '.github'))
+
+  // Dry-run conflict detection so callers can preview before running default mode.
+  restoreClonePaths(sourceDir)
+  const policy = { takeUpstream: false, keepLocalAll: false, keepLocalList: null }
+  planAndApplySkills(sourceDir, projectRoot, state, policy, true)
+  planAndApplyWorkflows(sourceDir, projectRoot, state, policy, true)
+
+  state.status = 'already-cloned'
+  const conflictCount = state.skill_conflicts.length + state.workflow_conflicts.length
+  state.message = `${sourceDir} is a clean clone of ${REMOTE_URL}. ${conflictCount} conflict(s) would be raised by a default run.`
+  emit(state)
+  return 0
+}
+
+function runClone(projectRoot, mirrorOnly, args) {
+  const { sourceDir, mirrorDir } = resolveTargets(projectRoot)
+  const status = {
+    status: 'unknown',
+    project_root: projectRoot,
+    source_dir: sourceDir,
+    mirror_dir: mirrorDir,
+    remote_url: REMOTE_URL,
+  }
+
+  const policy = buildPolicy(args)
+  status.policy = {
+    take_upstream: policy.takeUpstream,
+    keep_local_all: policy.keepLocalAll,
+    keep_local_list: policy.keepLocalList,
+  }
+  if (!validatePolicy(policy, status)) {
+    emit(status)
+    return 1
+  }
+
+  const sourceExists = fs.existsSync(sourceDir)
+
+  if (mirrorOnly) {
+    if (!sourceExists) {
+      status.status = 'error'
+      status.message = `--mirror-only requested but ${sourceDir} does not exist yet.`
+      emit(status)
+      return 3
+    }
+    refreshMirror(sourceDir, mirrorDir, status)
+    status.status = 'mirror-refreshed'
+    status.message = `Refreshed ${mirrorDir} from ${sourceDir} (skipped git + move steps).`
+    emit(status)
+    return 0
+  }
+
+  // --- Path 1: source dir does not exist → clone fresh ---
+  if (!sourceExists) {
+    fs.mkdirSync(path.dirname(sourceDir), { recursive: true })
+    const r = tryGit(['clone', '--branch', DEFAULT_BRANCH, REMOTE_URL, sourceDir], path.dirname(sourceDir))
+    if (!r.ok) {
+      status.status = 'clone-failed'
+      status.message = `git clone failed: ${r.stderr || r.stdout || 'unknown error'}`
+      emit(status)
+      return 3
+    }
+    return finalizeMoveAndMirror(sourceDir, projectRoot, mirrorDir, status, policy, 'cloned')
+  }
+
+  // --- Path 2: source exists, validate it's the right clone ---
+  if (!isGitWorkingTree(sourceDir)) {
+    status.status = 'invalid-source'
+    status.message = `${sourceDir} exists but is not a git working tree. Move it aside or delete it manually before re-running.`
+    emit(status)
+    return 3
+  }
+
+  const actualRemote = currentRemoteUrl(sourceDir)
+  status.actual_remote_url = actualRemote
+  if (actualRemote !== REMOTE_URL) {
+    status.status = 'wrong-remote'
+    status.message = `${sourceDir} is a git clone but origin points at ${actualRemote}. Expected ${REMOTE_URL}. Move it aside manually before re-running.`
+    emit(status)
+    return 3
+  }
+
+  // --- Path 3: existing clean clone → restore .claude/.github + fetch + pull --ff-only ---
+  restoreClonePaths(sourceDir)
+
+  const fetchR = tryGit(['fetch', REMOTE_NAME, DEFAULT_BRANCH, '--prune'], sourceDir)
+  if (!fetchR.ok) {
+    status.status = 'fetch-failed'
+    status.message = `git fetch failed: ${fetchR.stderr || fetchR.stdout || 'unknown error'}`
+    emit(status)
+    return 3
+  }
+
+  const beforeR = tryGit(['rev-parse', 'HEAD'], sourceDir)
+  const before = beforeR.ok ? beforeR.stdout : null
+
+  const checkoutR = tryGit(['checkout', DEFAULT_BRANCH], sourceDir)
+  if (!checkoutR.ok) {
+    status.status = 'checkout-failed'
+    status.message = `git checkout ${DEFAULT_BRANCH} failed: ${checkoutR.stderr || checkoutR.stdout}`
+    emit(status)
+    return 3
+  }
+
+  const pullR = tryGit(['pull', '--ff-only', REMOTE_NAME, DEFAULT_BRANCH], sourceDir)
+  if (!pullR.ok) {
+    status.status = 'pull-failed'
+    status.message = `git pull --ff-only failed: ${pullR.stderr || pullR.stdout}. Local edits or diverged branch may be the cause.`
+    emit(status)
+    return 3
+  }
+
+  const afterR = tryGit(['rev-parse', 'HEAD'], sourceDir)
+  const after = afterR.ok ? afterR.stdout : null
+  const moved = before && after && before !== after
+
+  status.before_sha = before
+  status.after_sha = after
+
+  return finalizeMoveAndMirror(sourceDir, projectRoot, mirrorDir, status, policy, moved ? 'updated' : 'already-cloned')
+}
+
+function finalizeMoveAndMirror(sourceDir, projectRoot, mirrorDir, status, policy, terminalStatus) {
+  // Phase A: dry-run to compute the action plan and conflicts.
+  planAndApplySkills(sourceDir, projectRoot, status, policy, true)
+  planAndApplyWorkflows(sourceDir, projectRoot, status, policy, true)
+
+  const totalConflicts = status.skill_conflicts.length + status.workflow_conflicts.length
+  if (totalConflicts > 0) {
+    // Abort without mutating. The caller (Claude/SKILL.md) asks the user and re-runs with
+    // a policy flag.
+    status.status = 'conflicts'
+    status.message = `Detected ${status.skill_conflicts.length} skill conflict(s) and ${status.workflow_conflicts.length} workflow conflict(s). Re-run with one of: --take-upstream (overwrite all), --keep-local (keep all local versions), or --keep-local=<csv> (keep specific ones).`
+    emit(status)
+    return 4
+  }
+
+  // Phase B: real apply (no conflicts left to resolve).
+  planAndApplySkills(sourceDir, projectRoot, status, policy, false)
+  planAndApplyWorkflows(sourceDir, projectRoot, status, policy, false)
+  cleanCloneDirs(sourceDir)
+  refreshMirror(sourceDir, mirrorDir, status)
+
+  status.status = terminalStatus
+  const created = status.skills_created.length + status.workflows_created.length
+  const over = status.skills_overwritten.length + status.workflows_overwritten.length
+  const kept = status.skills_kept_local.length + status.workflows_kept_local.length
+  const unch = status.skills_unchanged.length + status.workflows_unchanged.length
+  status.message = `${terminalStatus === 'cloned' ? 'Cloned' : (terminalStatus === 'updated' ? 'Pulled' : 'No upstream change')}. Created ${created}, overwrote ${over}, kept local ${kept}, unchanged ${unch}. Mirror refreshed.`
+  emit(status)
+  return 0
+}
+
+const args = parseArgs(process.argv.slice(2))
+const projectRoot = findProjectRoot(process.cwd())
+if (!projectRoot) {
+  emit({
+    status: 'error',
+    message: 'Could not locate the project root. Expected to find a parent directory containing both `_siesa-agents/` and `siesa-agents/`.',
+    cwd: process.cwd(),
+  })
+  process.exit(1)
+}
+
+if (args['check']) {
+  process.exit(runCheck(projectRoot))
+} else if (args['mirror-only']) {
+  process.exit(runClone(projectRoot, true, args))
+} else {
+  process.exit(runClone(projectRoot, false, args))
+}