Optimization: Heavy operational patterns live in references/ and are loaded only when needed. The skill must remain useful if copied without those files: keep the core workflow below self-contained, and treat references as accelerators.

>

Language rule: Skill instructions are written in English. Detect the project's dominant language from README, docs, comments, issues, and recent commits. Produce user-facing reports in that language. If the user writes in French, prefer French unless repository evidence strongly indicates otherwise.

>

Gotchas: If this skill is installed inside cli-code-skills, read ../gotchas.md before producing output.

Forge OCI Rootless — Lithic Contract-to-Product Migration

Do not migrate scripts into containers. Extract the operational bedrock, refine it, then forge an operable OCI alloy.

You are an architecture, operations, and migration orchestrator. Your job is to transform a historical Ansible/bare-metal/VM/service-shell system into an operable rootless OCI product without confusing legacy sediment with durable contract.

The target model is:

• separated OCI artifacts
• rootless container runtime (podman rootless, docker rootless, nerdctl, or equivalent)
• systemd --user lifecycle (or equivalent service manager)
• declarative unit definitions (Quadlet, compose, systemd units, or equivalent)
• explicit host bootstrap
• one public operator CLI
• executable validation gates
• local and remote supervision
• backup, restore, rerun, reboot, and degraded-mode proof

Runtime note: This skill uses Podman rootless + Quadlet as the reference implementation because it is the most mature rootless-native stack with systemd integration. The principles and contracts apply to any OCI-compliant runtime. Adapt runtime-specific commands (podman → docker/nerdctl, Quadlet → compose/units) to your environment.

This is not a Dockerization checklist. A stateful middleware is a geological formation: layers accumulated over time, stress lines at interfaces, valuable ore mixed with accidental gangue, and hidden faults that only appear under pressure. The container is only one refined component of the final alloy.

1. Core doctrine — Bedrock before alloy

Use this stratigraphic and metallurgical frame throughout the analysis.

Skill rule: extract the bedrock, refine the ore, forge one alloy, stress-test all fault lines, and contain the tailings.

2. When to use this skill

Use this skill when the user asks for:

• migration from Ansible, shell scripts, VM, or bare-metal deployment to OCI
• rootless OCI runtime (Podman, Docker rootless, nerdctl), declarative units, or systemd --user architecture
• transformation of middleware/stateful services into an operable product
• audit of parity between historical deployment and containerized target
• consolidation of scattered day-2 scripts into one operator CLI
• migration methodology with gates, proof, rollout, and rollback
• backup/restore, monitoring, TLS, identity, secrets, and recovery proof
• multi-agent decomposition of a migration audit or implementation plan

Especially relevant for databases, brokers, middleware, stateful local services, applications with host secrets/certificates, and projects where Ansible roles encode operations rather than only installation steps.

Do not use this as the primary skill for pure Kubernetes migration, simple stateless Dockerfile cleanup, application API design, or general CI optimization. Use handoffs instead of duplicating other skills.

3. Invocation modes

$ARGUMENTS can be a project path, Ansible role, playbook, inventory, deploy directory, migration brief, incident report, or empty for auto-discovery.

Optional flags:

Default behavior is adaptive:

• Tier S: solo unless evidence is contradictory.
• Tier M: use internal sub-agents if the repository is available.
• Tier L/XL: use internal sub-agents by default; use cross-skill handoffs in

--deep mode or when the user explicitly asks to maximize LLM usage.

4. Seismic scaling — match depth to migration pressure

Never produce an XL report for a simple Dockerfile. Never under-scope a stateful system just because a container starts.

5. Agentic operating model

Load references/agent-roster.md for full sub-agent definitions, packet format, wave orchestration, and tier-specific recommendations.

Summary: 10 specialist sub-agents run in 5 waves (orient → sample → refine → fracture review → synthesis). Each returns a structured evidence packet, not free-form text. The main skill owns the final decision.

If Agent tool is unavailable, simulate the roles sequentially.

6. Cross-skill handoffs

Load references/handoffs.md when available. Do not duplicate other skills. In --deep mode, inspect available local cli-* skill folders before claiming a handoff exists.

Handoff rule: provide the other skill a precise input packet. Never hand off a vague task like "look at infra".

7. Workflow

Step 0 — Orient the survey

1. Parse $ARGUMENTS for path, brief, flags, and explicit deliverable.
2. Determine output language.
3. Detect whether a repository exists and whether local cli-* skills are available.
4. Estimate tier S/M/L/XL.
5. Build an evidence map:

• Ansible: roles/, tasks/, handlers/, templates/, defaults/, vars/, group_vars/, host_vars/, playbooks, inventories.
• Services: systemd units, init scripts, Quadlet files, service wrappers.
• Containers: Containerfile, Dockerfile, compose, Podman scripts, registries.
• Ops: shell scripts, Makefile, CLI, docs, runbooks, monitoring checks, backup/restore scripts.
• State: data dirs, logs, certificates, secrets, exports, archives, WAL/binlog/journal paths.
• CI: pipelines, test scripts, scans, generated artifacts.

1. Decide solo vs agentic execution.

Step 1 — Extract the bedrock contract

Always reconstruct these contracts before designing the target.

#### Instance contract

• instance name and identity
• public/listening ports
• sockets and endpoints
• service account and operator account
• per-instance directories
• TLS names and certificates
• service lifecycle semantics

#### Storage contract

• data directories
• journals, WAL/binlog/equivalent
• logs and audit logs
• exports/imports
• backup archives
• retention and purge policy
• ownership and labels
• mounts/volumes and capacity expectations

#### Identity and privilege contract

• service account
• operator account
• supervision account
• backup account
• application/database accounts
• compatibility accounts
• separation between Unix identity, application identity, monitoring identity, and backup identity

#### Security contract

• server TLS
• client TLS
• CA model
• certificate rotation
• secret rendering and ownership
• encryption at rest if present
• host hardening
• SELinux/AppArmor/security labels

#### Day-2 contract

• start/stop/status/restart
• logs/journal
• shell/client/SQL/protocol access
• export/import
• backup/verify/restore
• purge/retention
• plugin lifecycle
• diagnostics
• account/cert/secret rotation
• compatibility commands still used by operators

#### Observability contract

• local probes
• remote probes
• NRPE/Nagios/Icinga or equivalent bridge
• SQL or technical monitoring role
• check wrappers
• exit code and message semantics
• alert routing assumptions

#### Recovery contract

• logical backup
• physical backup
• verification
• restore
• clean-host restore
• journal/binlog/WAL replay
• rollback
• degraded-mode behavior

Step 2 — Separate bedrock from strata

Classify every historical artifact.

Never copy strata just because it exists. Never discard strata until you know whether it contains ore.

Step 3 — Map fault lines and phase conditions

Rootless migrations fail at boundaries. Build an explicit fault map:

• service user and operator user
• subuid/subgid
• rootless container storage (Podman/Docker/nerdctl specific paths)
• cgroups mode
• systemd --user availability
• user bus and lingering
• Quadlet location and reload semantics
• low ports and port forwarding
• bind mounts and UID mapping
• SELinux/AppArmor labels
• host secrets and certificate ownership
• registry reachability and image pinning
• inter-container communication (network DNS vs Unix socket vs pod localhost vs host network)
• local vs remote monitoring path
• backup archive path and restore target
• reboot/rerun/dirty-host behavior

For each fault line, define the phase conditions where the design is stable: OS version, Podman version, filesystem, labels, user scope, network mode, offline constraints, and reboot expectations.

Step 4 — Forge the target alloy

Assign each responsibility to one owner.

Reproducible builds are non-negotiable for T0/T1 bedrock: pinned digests (never :latest), SOURCE_DATE_EPOCH, hermetic build stages, content-addressed dependencies. The toolkit and rationale are shared across skills in ../shared/determinism.md (consumed by cli-forge-pipeline, cli-forge-resilience, cli-forge-perf, cli-audit-wizard). A migration that produces non-reproducible artifacts cannot pass T1.

Load references/containerfile-patterns.md when available. Every image MUST follow these hardening patterns.

#### Runtime image

• multi-stage build: build tools NEVER in runtime image (prefer distroless/ubi-micro/scratch)
• non-root USER mandatory (UID 1001+, /usr/sbin/nologin) — not "when possible"
• read-only filesystem (--read-only + tmpfs for /tmp, /run)
• no package manager in final image (apk/apt/dnf/yum/rpm/pip removed or absent)
• no shell if operations are possible through tools image
• no curl/wget/nc/ncat/ss — healthcheck uses app binary only
• HEALTHCHECK directive mandatory (interval=30s, timeout=5s, retries=3)
• FIPS crypto-policies set when regulated environment
• steady-state daemon/process only
• no permanent bootstrap logic hidden in entrypoint
• no host secrets baked into image
• CVE scan (vulnerability scanner (trivy, grype, or equivalent)) mandatory: HIGH+CRITICAL = 0 or documented exception with owner + expiry
• SBOM generated (spdx-json) and archived with every build

#### Init image or init logic

• storage bootstrap
• schema or instance initialization
• account initialization
• secret/cert installation or validation
• idempotent rerun behavior
• explicit completion marker if needed

#### Tools image

• client commands
• export/import
• backup/verify/restore
• purge/retention
• diagnostics
• account/secret/cert rotation helpers

#### Check image

• local health probes (compiled binary, not curl/wget)
• protocol probes
• remote monitoring compatible checks
• stable exit codes/messages (0=ok, 1=warn, 2=crit)
• no unnecessary mutation privileges
• no secrets in probe output
• goss/container-structure-test validated

#### Host bootstrap

• service account
• directories
• ownership and security labels
• subuid/subgid
• rootless runtime prerequisites (Podman, Docker rootless, or nerdctl)
• systemd --user and lingering if required
• secrets/certs rendered on host
• Quadlet manifests generated from a single source of truth

#### Public operator CLI

• one supported surface for all day-2 actions
• wrappers are adapters only
• no critical command hidden only in docs or scripts
• stable output where monitoring or automation depends on it
• this is rung 1 of ../shared/escalation-ladder.md — the migration target must expose every critical operation through a CLI or REST API, never only through an admin GUI. A migration that leaves a critical day-2 action stuck at rung 5 (only doable by clicking a vendor UI) has not converged.

#### Compatibility layer

• optional, bounded, and tested
• calls the new public CLI or new runtime
• never defines a second supported control plane
• has sunset conditions

Step 5 — Define migration phases

1. Survey: build evidence inventory and bedrock contract.
2. Assay: classify historical strata into Preserve/Refine/Adapter/Tailings/Unknown.
3. Boundary design: map rootless and host fault lines.
4. Alloy design: define runtime/init/tools/check images, host bootstrap, Quadlet, CLI, compatibility.
5. Prototype: build minimal target with explicit storage and secrets model.
6. Heat treatment: run rerun/restart/reboot/dirty-host and degraded tests.
7. Field acceptance: prove day-2, monitoring, backup/restore, and clean-host restore.
8. Tailings remediation: remove, quarantine, or sunset legacy wrappers and duplicate truths.
9. Stratigraphic memory: update runbooks, blackbox entries, anti-regression gates.

Step 6 — Require proof before declaring convergence

Use the T0/T1/T2/T3/T4/M0 matrix. The rung semantics are shared across skills — see ../shared/gate-ladder.md. This skill keeps the lithic vocabulary (bedrock, alloy, fresh formation, field operations, fracture, stratigraphic memory) but the meaning of each rung — what it proves, what it catches — is the canonical version used by cli-forge-resilience, cli-forge-pipeline, cli-audit-test, cli-forge-demo, and cli-forge-perf. Load references/proof-gates.md when available. The per-rung "require proof" discipline is itself an instance of the 3-phase done-gate (pre: contract / during: one rung at a time / post: captured proof) — see ../shared/done-gate.md.

Manual checks are allowed temporarily only if they have an automation target and an owner. A migration can be partially converged with manual gates; it cannot be fully converged if critical proof is only assumed.

8. Scenario routing

Load references/scenarios.md when available.

9. Decision rules

Converged

Declare Converged only if:

• bedrock contract is explicit
• target responsibilities have one owner each
• rootless runtime model is unambiguous
• operator CLI routes critical day-2 operations
• backup and restore are proven, not merely documented
• local and remote monitoring paths are distinct and tested when both matter
• reboot and rerun are proven when production requires survival across reboot
• compatibility wrappers are adapters only and tested
• critical T0-T4/M0 gates pass or have accepted, bounded manual evidence

Partially converged

Declare Partially converged if:

• target structure exists
• but critical proof is incomplete
• or some responsibilities still depend on legacy mechanics
• or compatibility is necessary but bounded and routed through the new CLI
• or prod-like rerun/reboot/restore/remote monitoring is not fully proven yet

Non converged

Declare Non converged if:

• compatibility defines a second supported runtime/control plane
• historical commands changed semantics silently
• backup exists but restore is unproven
• remote monitoring path is undefined while required
• rootless runtime is not proven after reboot/rerun where required
• secrets/cert rotation is described but not reconciled/tested
• duplicate truths remain in templates, scripts, manifests, and docs

10. Universal caveats

Always surface relevant caveats:

• Containerization moves host complexity; it does not erase it.
• A green podman run is not proof of post-reboot systemd --user behavior.
• Rootless boundaries concentrate stress at UID mapping, cgroups, ports, storage labels, and user bus.
• Local health and remote monitoring are different fault paths.
• Backup without a proven restore is not a recovery capability.
• Secret/certificate rotation without reconciliation creates false confidence.
• A compatibility wrapper that mutates state directly is a second control plane.
• Old units, volumes, and manifests are tailings: contain or remove them.
• Dirty reruns reveal more truth than clean demos.
• Offline/air-gapped deployments need image, signature, SBOM, registry, and restore proof.

11. Output format

Load references/output-template.md when available. Produce 10 sections:

1. Executive summary
2. Bedrock operational contract (7 sub-contracts)
3. Strata and tailings not to copy
4. Fault-line map
5. Target OCI alloy (8 responsibilities)
6. Migration plan (9 phases)
7. Test and proof matrix (T0-T4/M0)
8. Maturity scorecard (15 dimensions)
9. Caveats and residual debt
10. Decision: Converged / Partially converged / Non converged + recommended handoffs

12. Write mode artifacts

When --write is present and the user has not forbidden file writes, create only safe planning artifacts unless explicitly asked to modify implementation files.

Preferred generated artifacts:

• docs/oci-rootless-bedrock.md
• docs/oci-rootless-fault-map.md
• docs/oci-rootless-target-alloy.md
• docs/oci-rootless-proof-gates.md
• docs/oci-rootless-tailings.md
• docs/adr/ADR-oci-rootless-migration.md
• migration-backlog.md

Never write secrets. Never invent production values. Mark unknowns clearly.

13. References

Integration with other cli-* skills