15. PATCHMD maintains Pixir customization against canonical upstream

Copy Markdown View Source

Date: 2026-06-04 Status: Accepted Implementation status: Initial repo integration

Context

Pixir is intentionally small compared with Codex, but it already has the primitives needed for user customization: repo law through AGENTS.md, progressively disclosed Skills, Skill-backed Workflow Templates, permissioned Tools, deterministic Workflows, and the Log as the source of truth.

The product risk is not that users customize Pixir. Customization is the point. The risk is that every customized Pixir checkout becomes an unmaintainable fork that cannot safely pull canonical improvements from main.

PATCHMD gives Pixir a maintenance protocol around customization. It records the current sync intent, classifies donor changes against target constraints, preserves local practice where appropriate, and keeps acceptance evidence separate from CI and external review.

Decision

Pixir will treat PATCHMD as the repo-local customization maintenance layer, not as a hidden autopatcher and not as a dependency of the core runtime.

The split is:

  • canonical Pixir upstream is the donor;
  • a customized Pixir repo or branch is the target;
  • AGENTS.md remains repo law;
  • patch.md records one active upstream-sync or customization charter;
  • .docs/patches/<patch-id>/ records classification, acceptance, status, proof, and handoff evidence;
  • .agents/skills/patch-operator/SKILL.md provides the generic PATCH operator loop;
  • .agents/skills/pixir-customization-operator/SKILL.md provides Pixir-specific judgment for preserving Skills, workflow templates, ADRs, and runtime customization;
  • Pixir Workflow Templates may orchestrate read-only audits and permission-gated sync steps, but deterministic validation remains in the UV-backed PATCH CLI.

The first command surface is direct because Pixir is a Mix project without package.json:

uv run scripts/patch_cli.py truth-check
uv run scripts/patch_cli.py classify --help
uv run scripts/patch_cli.py accept --help
uv run scripts/patch_cli.py status

Future Pixir-native wrappers such as mix pixir.patch.status are allowed, but they should wrap the same deterministic artifacts instead of creating a second evidence model.

Consequences

  • Users can keep local Skills, workflow templates, ADRs, and behavior customizations while still pulling canonical Pixir changes.
  • PATCH classification becomes the reviewable boundary between upstream code movement and user-owned customization.
  • Pixir's Skill primitive carries operator intelligence; the PATCH CLI carries validation and evidence writes.
  • Package-less repository support matters: docs and skills must show direct uv run commands, not package-script-only commands.
  • CodeRabbit remains an external CLI surface in the extended PATCH profile, not a Pixir dependency.

Non-goals

  • Do not make PATCHMD execute automatically on Skill Activation.
  • Do not bypass Pixir's permission model, Workspace confinement, or Log architecture.
  • Do not require Node package scripts for Pixir's PATCH workflow.
  • Do not make patch.md replace durable repo law in AGENTS.md.
  • Do not use PATCHMD for unbounded refactors or vague wishlist work.

Verification Direction

The initial integration is verified when:

uv run scripts/patch_cli.py --help
uv run scripts/patch_cli.py truth-check
uv run scripts/patch_cli.py status
mix test test/pixir/skills_test.exs test/pixir/workflows_test.exs
mix pixir.smoke.workflows --dry-run --json

If a future change adds Mix wrappers, the wrapper tests must prove that stdout, stderr, dry-run behavior, and structured errors remain aligned with ADR 0005.

References

  • ADR 0005: agent ergonomics, dry-run, help, structured errors, I/O discipline.
  • ADR 0010: Agent Skills use progressive disclosure with durable activations.
  • ADR 0013: Skills can provide Workflow Templates as installed practices.
  • ADR 0014: Workflow Checkpoint Bundles and honest partial outcomes.