siesa-agents 2.1.80 → 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/claude/skills/sa-init-observability/SKILL.md

@@ -73,7 +73,7 @@ Parse the JSON object printed to stdout. The `status` field selects the next bra
 
 Proceed straight to Step 2 with `proposed_slug` and `recommended_dir`. Do **not** ask the user to confirm — the user has already accepted the auto-detection policy by invoking this skill.
 
-**`status: "single-repo"`** — The repo name has no `docs`/`backend`/`frontend` segment, so the git remote already produces an unambiguous `project_id`. Stop and tell the user no `.siesa-project` is needed (mention the `fallback_project_id` value so they know what GCP will see). Do not write anything. If they later say "no, write one anyway with slug X", run Step 2 with that explicit slug and the directory they specify.
+Single-repo projects also return `status: "ready"` (with `convention_match: false`). The proposed slug is the repo name lowercased and sanitized to kebab-case (e.g. `Siesa-Agents` → `siesa-agents`) and `recommended_dir` is the git root itself. Proceed to Step 2 the same way — no separate branch.
 
 **`status: "already-configured"`** — A `.siesa-project` exists above the current git root. Stop and report `existing_siesa_project.path` and `existing_siesa_project.value` to the user. Do not overwrite implicitly. If the user replies that they want it changed, run `--write` with `--force`, the new slug, and the same directory.
 
@@ -95,7 +95,9 @@ Parse the JSON response:
 - **`status: "exists"`** — A file is already there with a different value (the detect step missed it because the user pointed at a non-default dir, or a race). Show `current_value` vs `requested_slug` and ask the user whether to overwrite. If yes, re-run with `--force`.
 - **`status: "error"`** — Surface the error message verbatim and stop.
 
-For the `single-repo`, `already-configured` and `no-remote` branches where the user explicitly opts into writing, gather slug + directory inline and run the same `--write` command.
+For the `already-configured` and `no-remote` branches where the user explicitly opts into writing, gather slug + directory inline and run the same `--write` command.
+
+The file body written by `--write` is always `project_id=<slug>\n` (key=value form). `sa-emit.js` accepts both this format and a legacy bare-slug line for backward compatibility, so existing `.siesa-project` files keep working.
 
 ### Step 3 — Verify (optional)
 
@@ -129,7 +131,7 @@ business-<module>-<role>-<rest>
 
 The logical slug collapses `<role>` away: `business-pos-backend-pdv` → `pos-pdv`.
 
-For repo names that do not contain `docs`/`backend`/`frontend`, the script returns `single-repo` and no `.siesa-project` is needed.
+For repo names that do not contain `docs`/`backend`/`frontend`, the script still returns `status: "ready"` but with `convention_match: false`. The slug is derived from the repo name (lowercased, sanitized to kebab-case) and the file is written at the git root of that single repo.
 
 ## Examples
 
@@ -157,11 +159,11 @@ Model: <runs sa-init-env.js — status "created">
 
 ```
 User: Set up .siesa-project for Siesa-Agents.
-Model: <runs --detect from Siesa-Agents/>
-       Repo name "Siesa-Agents" has no docs/backend/frontend segment, so the git remote already produces an unambiguous project_id ("SiesaTeams/Siesa-Agents"). No .siesa-project is needed.
-       Want to set a custom slug anyway?
-User: no, thanks
-Model: Nothing written. Existing fallback (SiesaTeams/Siesa-Agents) will continue to be reported.
+Model: <runs sa-init-env.js — silent>
+       <runs --detect from Siesa-Agents/>
+       <reads proposed_slug="siesa-agents", recommended_dir=C:\…\Siesa-Agents, convention_match=false>
+       <runs --write --slug siesa-agents --dir C:\…\Siesa-Agents>
+       Wrote C:\…\Siesa-Agents\.siesa-project (project_id=siesa-agents). sa-emit.js will now report project_id="siesa-agents" instead of "SiesaTeams/Siesa-Agents".
 ```
 
 **Example 3 — Already configured**

package/package.json

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

package/siesa-agents/observability/scripts/sa-emit.js

@@ -134,17 +134,38 @@ const stateDir = path.join(os.homedir(), '.claude', 'observability')
 const epicIdMatch = story.match(/^(\d+)-/)
 const epicId      = epicIdMatch ? epicIdMatch[1] : 'unknown'
 
+function parseSiesaProject(content) {
+  // Preferred format: a single `project_id=<slug>` line. For backward compatibility a bare
+  // slug on its own line is also accepted. `#` introduces a comment. Returns the resolved
+  // slug, or null if nothing usable was found.
+  if (!content) return null
+  let firstBare = null
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq !== -1) {
+      const key = line.slice(0, eq).trim()
+      const val = line.slice(eq + 1).trim()
+      if (key === 'project_id' && val) return val
+      continue
+    }
+    if (firstBare === null) firstBare = line
+  }
+  return firstBare
+}
+
 function findSiesaProject(startDir) {
-  // Walk up from startDir looking for a `.siesa-project` file. Returns its first non-empty
-  // line trimmed, or null. Lets a parent dir override the git-remote-derived project_id —
+  // Walk up from startDir looking for a `.siesa-project` file. Returns the project_id slug
+  // it declares, or null. Lets a parent dir override the git-remote-derived project_id —
   // useful when several sub-repos (docs/backend/frontend) belong to the same logical project.
   let cur = path.resolve(startDir)
   for (let i = 0; i < 40; i++) {
     const candidate = path.join(cur, '.siesa-project')
     if (fs.existsSync(candidate)) {
       try {
-        const first = fs.readFileSync(candidate, 'utf8').split(/\r?\n/)[0].trim()
-        if (first) return first
+        const slug = parseSiesaProject(fs.readFileSync(candidate, 'utf8'))
+        if (slug) return slug
       } catch (_) {}
     }
     const parent = path.dirname(cur)

package/siesa-agents/observability/scripts/sa-init-project.js

@@ -63,6 +63,27 @@ function tryExec(cmd, opts) {
   }
 }
 
+// Parse a `.siesa-project` file body. Preferred format is `project_id=<slug>` (one key=value
+// line, optional `#` comments). For backward compatibility a bare slug on its own line is
+// also accepted. Returns the resolved slug, or null if nothing usable was found.
+function parseSiesaProject(content) {
+  if (!content) return null
+  let firstBare = null
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq !== -1) {
+      const key = line.slice(0, eq).trim()
+      const val = line.slice(eq + 1).trim()
+      if (key === 'project_id' && val) return val
+      continue
+    }
+    if (firstBare === null) firstBare = line
+  }
+  return firstBare
+}
+
 // Walk up from `startDir` looking for an existing `.siesa-project`. Returns
 // { path, value } of the first match found, or null.
 function findExistingSiesaProject(startDir) {
@@ -71,8 +92,8 @@ function findExistingSiesaProject(startDir) {
     const candidate = path.join(cur, '.siesa-project')
     if (fs.existsSync(candidate)) {
       try {
-        const first = fs.readFileSync(candidate, 'utf8').split(/\r?\n/)[0].trim()
-        return { path: candidate, value: first }
+        const value = parseSiesaProject(fs.readFileSync(candidate, 'utf8'))
+        return { path: candidate, value }
       } catch (_) {
         return { path: candidate, value: null }
       }
@@ -186,15 +207,38 @@ function runDetect() {
   const derived = deriveLogicalSlug(repoName)
 
   if (!derived.matched) {
+    // Single-repo project: still write a `.siesa-project` so the project_id is explicit
+    // and self-documented. The slug is derived from the repo name, sanitized to kebab-case,
+    // and the file lands at the git root of the current project.
+    const singleRepoSlug = (repoName || '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+    if (!singleRepoSlug || !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(singleRepoSlug)) {
+      emit({
+        status: 'no-remote',
+        message: 'Could not derive a valid kebab-case slug from the repo name. Pass --slug explicitly to write a .siesa-project.',
+        git_root: gitRoot,
+        remote_url: remoteUrl,
+        remote_repo: repoName,
+      })
+      process.exit(2)
+    }
     emit({
-      status: 'single-repo',
-      message: 'This repo name does not match the multi-repo convention (no docs|backend|frontend segment). sa-emit.js will report project_id based on the git remote, which is already unambiguous for single-repo projects. No .siesa-project is required.',
+      status: 'ready',
+      message: 'Single-repo project detected. The .siesa-project file will be written at the git root with a slug derived from the repo name.',
       git_root: gitRoot,
       remote_url: remoteUrl,
       remote_repo: repoName,
+      convention_match: false,
+      proposed_slug: singleRepoSlug,
+      convention_breakdown: null,
+      parent_candidates: [{ path: gitRoot, label: 'git root', levelsUp: 0 }],
+      recommended_dir: gitRoot,
       fallback_project_id: remoteParsed ? `${remoteParsed.org}/${remoteParsed.repo}` : null,
+      next_step_example: `node sa-init-project.js --write --slug "${singleRepoSlug}" --dir "${gitRoot}"`,
     })
-    process.exit(2)
+    process.exit(0)
   }
 
   const candidates = listParentCandidates(gitRoot)
@@ -256,7 +300,7 @@ function runWrite(args) {
   const target = path.join(resolvedDir, '.siesa-project')
   if (fs.existsSync(target) && !force) {
     let current = null
-    try { current = fs.readFileSync(target, 'utf8').split(/\r?\n/)[0].trim() } catch (_) {}
+    try { current = parseSiesaProject(fs.readFileSync(target, 'utf8')) } catch (_) {}
     emit({
       status: 'exists',
       message: '.siesa-project already exists at this location. Pass --force to overwrite.',
@@ -268,7 +312,7 @@ function runWrite(args) {
   }
 
   try {
-    fs.writeFileSync(target, normalizedSlug + '\n', { encoding: 'utf8' })
+    fs.writeFileSync(target, `project_id=${normalizedSlug}\n`, { encoding: 'utf8' })
   } catch (err) {
     emit({ status: 'error', message: `Failed to write ${target}: ${err.message}` })
     process.exit(3)

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))
+}