quadlet-lens

Imported from Strukturpiloten/quadlet-lens (AGENTS.md). Install upstream with npx skills add Strukturpiloten/quadlet-lens. Copyright stays with the author.

Repository guidance for coding agents

This file applies to the entire QuadletLens repository.

Read before changing code

1. Read README.md and the task map in docs/README.md.
2. Read only the guide selected for the task: architecture, typed model, generation, capabilities, generators, testing, dependencies, or releases.
3. Read docs/decisions/README.md and only the ADRs relevant to an architectural boundary being changed.

Architectural changes require documentation and an ADR update in the same change.

Scope

QuadletLens owns native Quadlet syntax, typed models, document-set relationships, rendering, diagnostics, and capability evidence for supported Podman and systemd targets.

It does not own Compose, Kubernetes semantics, runtime inspection, BoxFerry's neutral model, or cross-format conversion decisions. It must not depend on BoxFerry.

Origin policy

QuadletLens is implemented from scratch. Do not copy or mechanically translate source from Podlet, Podman, systemd, or another parser. Public documentation, released source behavior, and commands from identified versions may inform independent implementation and differential tests.

External fixtures and behavior-oracle results record source, version, command, environment, license, and expected result.

Non-negotiable behavior

• Unknown keys and generic systemd sections are never silently discarded.
• Repeated keys and order remain explicit; a map is not a syntax representation.
• Systemd specifiers remain distinct from shell or Compose substitutions.
• Source syntax, typed values, and target validation remain separate layers.
• A capability claim has evidence and a test or an explicit test gap.
• Invalid input returns structured diagnostics and never panics.
• Rendering is deterministic for the same document, target, and options.
• Parsing and rendering never install, enable, start, or otherwise mutate units.

Development rules

• Use the data-driven catalogue instead of a closed Podman version enum in application logic.
• Model Quadlet features needed by the library contract, not every Podman feature.
• Keep target evaluation independent of the parser.
• Add parser, renderer, capability-boundary, and generator tests where behavior changes.
• Record exact upstream source and observed behavior for capability updates.
• Update compatibility guidance with the implementation.
• Start repository-owned complete YAML documents with ---.
• Keep release notes concise and link to canonical technical documentation.
• Pin GitHub Actions to full commit SHAs with exact release-tag comments.

Canonical commands

./scripts/check-all.sh
./scripts/check-files.sh --check
cargo ci-check
cargo ci-catalogue
cargo ci-generators
cargo ci-model
cargo ci-policy
cargo ci-clippy
cargo ci-test
cargo ci-doctest
RUSTDOCFLAGS="-D warnings" cargo ci-doc
cargo +1.85.0 ci-check
cargo +1.85.0 ci-policy
cargo deny check

The ci-* aliases use locked resolution and all workspace features and targets where applicable. Local generator execution and the real-world corpus are opt-in tiers. Every Release automatically and fail-closed runs the reusable full pinned generator matrix plus the tracked-current application-generator lane; validation_only runs the identical gate. This is dry-run generator evidence only: it never installs, enables, starts, or otherwise executes systemd units or workloads.

GitHub issue-to-PR workflow

When the user authorizes issue, branch, commit, push, and pull-request writes:

1. Inspect status and the complete diff; preserve unrelated changes.
2. Search for a duplicate issue and create one focused issue if needed.
3. Fetch origin/main, verify local main, and create TheRealBecks/issue<NUMBER>.
4. Implement and review without staging unrelated paths.
5. Run ./scripts/check-all.sh. This is a hard gate against commit, push, or pull-request creation. Any later source, test, configuration, or documentation edit invalidates the run.
6. Stage explicit paths, run git diff --cached --check, review the staged diff, and create one intentional commit.
7. Push and open a ready pull request containing Closes #<NUMBER>.
8. Use release-worthy Conventional Commit types only for shipped behavior. Use docs, test, ci, build, style, or chore for maintenance so release-plz ignores it.
9. Read the pull request back and report the issue, branch, commit, validation, URL, and checks.

Opening and reading back the ready pull request is the default stopping point. Authorization to run the Git workflow or perform GitHub writes does not authorize a merge.

Merge only when the user explicitly authorizes merging the specific pull request or the scoped set of pull requests in the current request. Immediately before merging, read back the exact head commit and verify that the pull request is ready, mergeable, and has every required check successful. Never bypass branch protection, use an administrator override, or infer authority for an out-of-scope release, publication, or deployment pull request.

Use the repository's normal merge method with an exact-head safeguard, then read back and report the merged state and merge commit.

The primary agent runs this workflow with high reasoning effort. The primary agent owns Git and GitHub writes, integration review, the final complete gate, staging, and pull-request readback.

Worker subagents never execute the Git or GitHub write steps. They may perform bounded research, implementation, review, or non-mutating verification. The final formatting and complete gate remains the primary agent's responsibility. Subagents never commit, push, publish, tag, or release.

Multi-agent coordination

• Delegate only bounded tasks with independently verifiable results.
• Never run two writing agents in this checkout concurrently.
• Run read-only review or verification after writing finishes.
• The primary agent reviews every diff and owns cross-repository API decisions.

Agent roles and verification

Model defaults belong in .codex/config.toml; task-specific models and reasoning belong in .codex/agents/. Use the repository's high-effort primary default for normal work; explicitly request xhigh for unusually difficult architecture or migration analysis. These are defaults, not permission grants.

• Delegate only when the user or applicable instructions request it, and assign a bounded task.
• Use at most three subagents. Define the shared contract and file ownership before delegation.
• Never run two writers in one checkout. Research and review remain read-only.
• The reviewer checks the original requirements and independent expected results, not just agreement between the implementation and its tests.
• After writing finishes, the verifier runs ./scripts/check-all.sh --check. It reports failures without formatting or editing tracked files; ignored build artifacts and caches are allowed.
• Avoid concurrent full gates or heavy runtime tests. The primary agent owns integration, the final complete gate, and every authorized Git or GitHub write.

The default ./scripts/check-all.sh still formats before checking. --check runs the same complete gate without source formatting; it is not a reduced test tier. A later edit invalidates either result. Neither mode grants release, publication, or deployment authority.

Code discovery

For code discovery, use an available codebase-memory graph first; otherwise use CodeGraph only if the repository already has a usable index. Do not create an index without user authorization. If neither graph is available or a query cannot answer the question, use rg and targeted reads. For string literals, configuration, scripts, and documentation, start with rg directly.

After an authorized merge

Read back the merged state and exact merge commit, then synchronize the primary checkout with origin/main. Preserve unrelated files. Remove only the recorded task worktree with git worktree remove <recorded-path>, delete the verified merged local issue branch with git branch --delete --force TheRealBecks/issue<NUMBER>, and run git worktree prune --verbose. Read back git worktree list --porcelain and git status --short --branch; do not leave stale task worktree registrations.