Cli Forge Oci Rootless

> 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.

| Model | Nature | Migration meaning | |---|---|---| | Bedrock | Stable foundation below surface layers | Durable operational contract: actors, accounts, ports, paths, secrets, day-2 commands, monitoring, recovery | | Strata | Historical layers deposited over time | Ansible roles, VM layout, scripts, systemd units, manual conventions, operator habits | | Ore vs gangue | Valuable mineral mixed with waste rock | Contractual behavior to preserve vs accidental mechanics to discard | | Core sample | Small but traceable evidence sample | File/path/line/command evidence supporting a migration claim | | Fault line | Boundary where stress concentrates | Host/container, rootless user, UID mapping, TLS, storage, SELinux/AppArmor, network, registry, monitoring bridge | | Metamorphism | Transformation under heat/pressure without losing material identity | Rewriting deployment mechanics while preserving operational meaning | | Phase diagram | Map of stable states under conditions | Compatibility matrix across OS, Podman, cgroups, lingering, SELinux, storage, reboot, air-gap constraints | | Alloy | Engineered combination with target properties | Runtime image + init logic + tools image + check image + host bootstrap + CLI + Quadlet | | Heat treatment | Controlled hardening to avoid brittleness | Phased rollout, compatibility adapters, rollback, repeated rerun/reboot hardening | | Fracture surface | Place where cracks initiate or propagate | Failure modes: missing secret, bad volume label, broken user bus, corrupt backup, stale wrapper, port conflict | | Tailings | Residual waste after extraction | Legacy scripts, duplicate truth, old units, undocumented manual paths, obsolete wrappers | | Stratigraphic memory | Record of past events in layers | Runbook deltas, blackbox entries, anti-regression tests, incident lessons |

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:

| Flag | Meaning | |---|---| | --solo | One-agent analysis only. Use for small scopes or when Agent tool is unavailable. | | --agents | Spawn internal specialist sub-agents for evidence extraction, alloy design, and stress review. | | --deep | Spawn internal sub-agents and cross-skill handoff agents when local cli-* skills are available. | | --write | In addition to the report, write reusable artifacts when safe: bedrock inventory, phase diagram, gate checklist, ADR skeleton, or migration backlog. Never mutate runtime files without explicit user intent. |

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

| Signal | Tier | Behavior | |---|---:|---| | Mostly stateless service, no persistent local state | S | Focus on image/runtime/CLI basics and T0-T2 proof | | One stateful service or middleware on one host | M | Full bedrock extraction, storage, identity, rootless, Quadlet, day-2 proof | | Multiple instances, monitoring, backup/restore, TLS, prod-like constraints | L | Full agentic report, architecture, migration phases, T0-T4/M0 gates | | Regulated, air-gapped, HA, multi-environment, strict recovery/SLOs | XL | Add compliance, supply chain, rollback, disaster recovery, clean-host restore, acceptance criteria |

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.

| Wave | Agents | Purpose | |---|---|---| | 0 | Main | Detect scope, tier, evidence inventory | | 1 | Bedrock, Stratigraphy, Fault-Line, Reservoir, Operator, Observability | Core sampling (parallel) | | 2 | Alloy, Assay, Tailings + optional cross-skill handoffs | Refining and design (parallel) | | 3 | Fracture Risk | Adversarial review | | 4 | Main | Synthesis and convergence 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.

| Trigger | Prefer handoff | What this skill still owns | |---|---|---| | Legacy stack pays compensations (wait loops, chown chains, run-once guards) across layers | /cli-audit-hanoi | Displacement catalog: what to fix at source in the target alloy vs consolidate in one layer | | Complex shell wrappers or unsafe scripts | /cli-audit-shell | Classify contract vs legacy; decide adapter/removal | | Podman/systemd/host bootstrap design details | /cli-forge-infra | Rootless migration verdict and bedrock preservation | | Prod-parity/runbook/failure-injection needed | /cli-forge-resilience | Migration-specific fault map and acceptance gates | | Test suite coverage audit | /cli-audit-test | T0-T4/M0 migration proof matrix | | CI/CD pipeline creation | /cli-forge-pipeline | Which gates must exist and why | | Repository structure redesign | /cli-forge-tree | OCI/rootless responsibility boundaries | | Config/manifest/schema design | /cli-forge-schema | Operational contract semantics | | HLD/LLD needed | /cli-forge-hld or /cli-forge-lld | Migration contract and proof requirements | | Docs/runbooks needed | /cli-forge-doc | What must be documented as contract | | Multi-agent implementation sprint | /cli-forge-chef | Migration backlog, work packages, gate owners | | High-stakes multi-agent governance | /cli-forge-quorum | Evidence packets, invariants, acceptance criteria | | Drift/invariant audit | /cli-audit-drift or /cli-audit-sync | T0 bedrock drift gates |

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.

| Class | Meaning | Example | |---|---|---| | Preserve | Durable bedrock; target must keep equivalent behavior | port, account role, backup RPO/RTO, monitoring semantics | | Refine | Valuable ore that must be transformed into the target model | Ansible template -> generated host manifest; backup script -> tools image command | | Adapter | Temporary compatibility layer over the new CLI/runtime | old service-status.sh calls mycli status | | Tailings | Legacy waste to remove or quarantine | interactive install wizard, duplicate root unit, stale wrapper mutating state | | Unknown | Not enough evidence | undocumented script used by cron maybe |

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
• accou

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Destynova2
• Source: Destynova2/cli-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.