GameCult/repixelizer
Watch
9
0
Fork
You've already forked repixelizer
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
repixelizer/AGENTS.md
Meta Vens f2b62bc25c Trim victory-lap docs language
2026-04-29 11:43:17 +01:00

5.6 KiB
Raw Permalink Blame History

Repixelizer Instructions

Project Purpose

Repixelizer is a standalone Python CLI for forcing fake pixel art onto a real pixel lattice with a lean, inspectable solver.

The live machine is intentionally lean: infer a lattice, analyze structure, optimize one displacement field, sample real source pixels, then write diagnostics that make the result inspectable.

Canonical State

  • Treat state/map.yaml as the canonical current project map.
  • Treat state/scratch.md as disposable working memory for one bounded subgoal.
  • Treat state/evidence.jsonl as the durable distilled ledger of decisions, regressions, verified findings, and rejected paths.
  • Treat state/branches.json as hypothesis tracking, not phase/status prose.
  • Treat notes/fresh-workspace-handoff.md as the compact re-entry packet.
  • Treat docs/implementation-plan.md as the forward plan.
  • Treat docs/lean-optimizer-algorithm-map.md as the source-grounded live algorithm map.
  • Treat E:\Projects\Heimdall\docs\architecture.md as the canonical future shared access architecture for GameCult-hosted experiments, not as proof that auth machinery already exists here already.
  • Treat E:\Projects\Heimdall\docs\app-profiles\repixelizer.md as the canonical Repixelizer-specific binding onto that future shared access architecture.
  • Treat local docs/gamecult-hosted-access-architecture.md and docs/repixelizer-hosted-access-profile.md as redirect stubs, not the real design notes.
  • Update state/map.yaml when project understanding changes.
  • Add evidence after meaningful research, implementation, verification, or rejected paths, but keep it distilled. Routine "I just did this" proof belongs in git history, diagnostics, benchmark artifacts, or commit messages unless it changes what the next agent should believe.

Important Paths

  • Project root: E:\Projects\repixelizer
  • Implementation plan: E:\Projects\repixelizer\docs\implementation-plan.md
  • Algorithm map: E:\Projects\repixelizer\docs\lean-optimizer-algorithm-map.md
  • Shared hosted access architecture: E:\Projects\Heimdall\docs\architecture.md
  • Repixelizer hosted access profile: E:\Projects\Heimdall\docs\app-profiles\repixelizer.md
  • Handoff summary: E:\Projects\repixelizer\notes\fresh-workspace-handoff.md
  • State CLI: E:\Projects\repixelizer\tools\repixelizer_state.py
  • Pre-compaction helper: E:\Projects\repixelizer\tools\repixelizer_prepare_compaction.py
  • Live pipeline: E:\Projects\repixelizer\src\repixelizer\pipeline.py
  • Live solver: E:\Projects\repixelizer\src\repixelizer\phase_field.py
  • Metrics: E:\Projects\repixelizer\src\repixelizer\metrics.py

Useful Commands

Use the repo virtualenv when available:

.\.venv\Scripts\python .\tools\repixelizer_state.py status
.\.venv\Scripts\python .\tools\repixelizer_state.py add-evidence --type research --status ok --note "..."
.\.venv\Scripts\python .\tools\repixelizer_prepare_compaction.py
.\.venv\Scripts\python -m pytest -q

Fallback if the virtualenv is unavailable:

python .\tools\repixelizer_state.py status
python .\tools\repixelizer_prepare_compaction.py

Session Bootstrap And Re-entry Protocol

On fresh session load, do this before editing:

  1. read:
    • state/map.yaml
    • notes/fresh-workspace-handoff.md
    • docs/lean-optimizer-algorithm-map.md
    • docs/implementation-plan.md
  2. run:
    • .\.venv\Scripts\python .\tools\repixelizer_state.py status
    • git status --short --branch
    • git log --oneline -5
  3. restate the current next action from persisted state before touching code

After compaction, resume, or suspicious continuity loss:

  1. rerun repixelizer_state.py status
  2. reread state/map.yaml and notes/fresh-workspace-handoff.md
  3. treat the persisted next action as authoritative unless fresh repo evidence contradicts it

When context pressure is rising:

  1. stop broad exploration
  2. narrow the active move to one bounded landing zone
  3. persist map/handoff updates plus distilled evidence before continuity gets atomized

Do not wait for the blackout and then act surprised.

When the user says to prepare for imminent compaction:

  1. run tools/repixelizer_prepare_compaction.py before editing persistence surfaces
  2. use its warnings as the checklist for map, handoff, scratch, evidence, and git hygiene
  3. update only the state that actually changed
  4. run tools/repixelizer_prepare_compaction.py again after edits
  5. fix errors, address warnings, and commit the completed persistence pass unless the work is deliberately mid-surgery

Operating Discipline

  • Before substantial edits, restate the current mechanism and intended change.
  • Prefer one clear hypothesis per pass.
  • Validate against the real objective: pinned badge runs, focused crops, visual diffs, and source_structure, not just a convenient proxy metric.
  • Revert failed regression or benchmark fixes immediately before trying the next idea.
  • If the diff grows while understanding shrinks, stop implementation and switch to diagnosis, mapping, or simplification.
  • Keep prose and maps grounded in concrete source paths.
  • Keep trays, portrait layers, candidate sets, and multi-stage solver stacks out of the code unless the design has changed and the map says so.
  • Keep documentation focused on the current machine. Avoid victory-lap prose about removed approaches; put historical context only in evidence, changelogs, or compact rejected-path notes when it changes future decisions.
  • Before handoff or compaction, sync state/map.yaml, refresh notes/fresh-workspace-handoff.md, add distilled evidence when future belief changed, and make the next action explicit.