{
  "markdown": "# Z80 Skills — Adaptive Research\n\n**Languages:** English · [Español](README.es.md)\n\nCodex plugin with one standalone adaptive workflow, one thin domain selector,\neight complementary engineering skills, and guarded BridgeZX file delivery for\nZ80 projects, especially ZX Spectrum software written in assembly, C, or a\nmixture of both using z88dk or SDCC.\n\nThe goal is not to produce generic lists of tricks. The skills inspect the\ncurrent code and artifacts, adapt depth and parallelism to the actual risk, and\nclearly distinguish proven evidence, estimates, and hypotheses.\n\n> Adaptive execution plus specification-driven development, root-cause\n> debugging, evidence-first auditing, repository documentation, organization,\n> size reduction, and multi-objective optimization for\n> Z80 and ZX Spectrum projects.\n\n## Contents\n\n- [What is included](#what-is-included)\n- [What it adds beyond generic analysis](#what-it-adds-beyond-generic-analysis)\n- [Adaptive and multi-agent execution](#adaptive-and-multi-agent-execution)\n- [Targeted external research](#targeted-external-research)\n- [Skill details](#skill-details)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Recommended artifacts](#recommended-artifacts)\n- [Safety and limitations](#safety-and-limitations)\n- [Repository structure](#repository-structure)\n- [Validation](#validation)\n- [License](#license)\n\n## What is included\n\n| Skill | Primary question | Result |\n|---|---|---|\n| `workflow` | What is the smallest sufficient execution level for this engineering task? | Direct Light or Medium execution in the main thread, or flat Heavy coordination with bounded built-in workers. |\n| `route-z80` | Which single Z80 specialist, if any, owns the requested result? | One domain route, or plain `workflow` for ordinary engineering work. |\n| `send-bridgezx` | Which named files or directories should be delivered to a ZX or Next? | A guarded BridgeZX transfer using the explicit or last-known IP, optional destination, and requested sequence. |\n| `develop-z80` | How does this ZX or Next idea become a buildable, verifiable project? | Concept brief, specification, technical plan, task backlog, implementation, and criterion-by-criterion evidence. |\n| `document-z80` | How should this repository's public documentation be structured and kept accurate across languages? | An evidence-grounded README and documentation hierarchy with verified commands, hardware requirements, and EN/ES parity. |\n| `port-spectranext` | How does an existing ZX program move through the Spectranext cartridge's consumer pipeline? | Canonical intake, bounded implementation, artifact-bound gates, physical evidence, and final handoff. |\n| `debug-z80` | What causes this observed failure, and which component owns the repair? | One falsifiable causal explanation and, when requested, one verified root-cause fix. |\n| `audit-z80` | Are there latent defects or broad correctness risks? | Read-only findings prioritized by severity and confidence, with evidence, verification, and residual risk. |\n| `organize-z80` | Which ownership, dependency, source, and runtime-placement boundaries need a change? | Proportional map, design, reversible migration slice, or explicit no-change decision. |\n| `shrink-z80` | How can storage, linked size, resident memory, BSS/stack, banks, or overlays be reduced? | Net reductions classified by safety and quality of evidence. |\n| `optimize-z80` | What is the real bottleneck, and which changes offer the best balance among size, speed, RAM, rendering, and latency? | Up to three prioritized experiments with impact, risk, rollback, and validation plans. |\n\n`workflow` is independent of Z80 and routes execution effort. `route-z80` is\nthe sole implicit entry point for natural-language Z80 domain selection,\nincluding unambiguous specialist matches. The routed skills overlap only where\nuseful:\n\n- Use `workflow` directly for adaptive planning, implementation, and verification.\n- Use `route-z80` to choose one specialist, without loading all candidates.\n- Use `send-bridgezx` to deliver named files or directories through the official\n  BridgeZX client without maintaining another IP or protocol implementation.\n- Use `develop-z80` only for an explicit product initiative or an existing SDD\n  dossier, not for routine fixes or isolated repository features.\n- Use `document-z80` to create, restructure, review, or synchronize public\n  repository documentation without flattening the project's identity.\n- Use `port-spectranext` for an existing ZX program's consumer port to the\n  Spectranext cartridge, not for ZX Spectrum Next targets or backend work.\n- Use `debug-z80` for an observed failure whose causal owner remains unknown.\n- Use `audit-z80` for preventive or broad read-only correctness review.\n- Use `organize-z80` to map or safely improve ownership, dependencies, source layout, and runtime placement.\n- Use `shrink-z80` for an exhaustive search focused exclusively on size.\n- Use `optimize-z80` to decide among competing objectives and prioritize the\n  next experiments.\n\n## What it adds beyond generic analysis\n\n### Local evidence before folklore\n\n- Only the current code and demonstrably fresh artifacts can confirm a finding\n  or improvement.\n- Maps, symbols, listings, generated ASM, and linked binaries count as evidence\n  only when they correspond to the same revision, configuration, and target.\n- Scanners, agents, prior knowledge, forums, and repositories generate\n  candidates; they do not replace local verification.\n- A stale artifact explicitly lowers confidence to states such as\n  `NEEDS BUILD`, `REQUIERE BUILD`, or `SPECULATIVE`.\n- In multi-target projects, a proposal passes the promotion gate only when\n  every target satisfies its own limits.\n\n### Progressive loading\n\nEach `SKILL.md` acts as a compact dispatcher. Codex first loads the shared\ncontract and then only the references and scripts relevant to the observed\nproblem. This avoids adding manuals, techniques, or logs to the context when\nthey cannot change the result.\n\n### Deterministic tools\n\nThe plugin includes dependency-free Python analyzers for profiling the project,\nsummarizing maps, detecting patterns, inventorying ABI boundaries, assessing\nartifact freshness, locating library pulls, and estimating candidates. Their\nresults are reproducible signals, not automatic verdicts.\n\n## Adaptive and multi-agent execution\n\nThe standalone `workflow` skill is the shared execution core:\n\n| Level | Strategy |\n|---|---|\n| **Light** | The main thread handles a bounded task directly. |\n| **Medium** | The main thread handles one ordered multi-step stream directly. |\n| **Heavy** | The main thread coordinates bounded independent workers in a flat topology. |\n\nIn `auto`, each Z80 skill contributes `Focused`, `Standard`, or `Deep` domain\nsignals after preflight. Workflow owns the route, dispatch, repair, verification,\nand integration; the domain skill keeps its evidence gates, lane definitions,\noutput contract, and write restrictions. An explicit workflow level wins, but\nnever grants an operation forbidden by the project or domain skill.\nBefore dispatch, workflow classifies each surface as primary-tree read-only,\ndisposable-worktree-only, or authorized primary-tree mutation and selects only\nroles that fit that boundary.\n\n## Targeted external research\n\nExternal research is activated to resolve a specific uncertainty, not to\ndecorate the report or repeat a list of well-known sites.\n\n### When it is activated\n\n- The user requests deep research across forums, blogs, repositories, or the\n  demoscene.\n- A compiler version, ABI, firmware, emulator, hardware model, or timing detail\n  can change a primary finding.\n- The code, generated artifacts, and documentation contradict one another.\n- A deep analysis retains a material blind spot.\n- An instruction sequence, helper, codec, renderer, loader, or banking scheme\n  requires code archaeology.\n\n### How it searches\n\n1. Formulate a question from a minimal local signature: opcode, symbol, emitted\n   fragment, version, address, symptom, or constraint.\n2. Search for exact fragments and concepts using alternative terminology.\n3. Expand terms across English, Spanish, Polish, Russian, Czech, and other\n   relevant regional communities.\n4. Diversify sources: code, tests, commits, issues, forks, emulators, hardware\n   measurements, mailing lists, archived forums, personal blogs, small\n   repositories, disassemblies, generators, and demoscene material.\n5. Follow authors, citations, forks, related issues, and archived links.\n6. Try to refute each finalist by looking for bugs, regressions, closed or\n   rejected issues, and model-specific failures.\n7. Verify the CPU, Spectrum model, ABI, interrupts, paging, memory, toolchain,\n   and timing before transferring a technique.\n\nResearch has a budget and stopping rules: it retains only the few sources that\ncan change a decision. A popular technique without a project-local anchor\nremains a hypothesis.\n\nTo protect private projects, searches use only minimal normalized signatures;\nthey must never upload private code or project identifiers.\n\n## Skill details\n\n### `route-z80`\n\nThin implicit domain dispatch for natural-language Z80 requests. It routes an\nunambiguous specialist match immediately and asks a focused question only when\nmultiple primary outcomes remain. Ordinary known-cause fixes, source-code\ncomments, agent instructions, refactors, tests, and builds go to plain\n`workflow`. It does not choose Light, Medium, or Heavy or load every candidate\nskill.\n\n### `send-bridgezx`\n\nGuarded delivery of named local files or directories through the official\nBridgeZX Python client. It uses an explicit IP or BridgeZX's last-known host,\nprobes and locks Classic/Next before sending, passes an optional relative remote\ndestination, and turns an explicit order into sequential operations that stop\nat the first failure. It never retries an uncertain transfer automatically.\n\n### `document-z80`\n\nEvidence-grounded creation, restructuring, synchronization, and review of\npublic GitHub documentation for Z80 and ZX projects. It treats the root README\nas the landing page, keeps tutorials, goal-oriented guides, exact reference,\narchitecture explanations, and release history in their smallest useful homes,\nand avoids duplicating facts.\n\nIt verifies commands, paths, artifact names, target machines, peripherals, and\ntoolchain requirements against the repository. Maintained language variants\nkeep the same topology and facts without forcing literal translation or a new\nfilename convention. Existing branding, screenshots, and retro voice remain\nproject-specific.\n\n### `develop-z80`\n\nSpecification-driven development from an initial idea to verified code. It\nshapes the concept, defines observable behavior, chooses the ZX/Next platform\nprofile, plans runnable milestones, creates dependency-aware tasks, implements\nready tasks, and reconciles every acceptance criterion with evidence.\n\nThe user does not operate those stages. The skill infers where to begin,\nadvances automatically, and asks only for material product decisions or missing\nauthorization before product-code mutation.\n\nSmall work keeps one SDD dossier in the conversation. Multi-session projects\ncan persist the same single dossier in the repository instead of scattering\nidea, requirements, plan, tasks, and status across several files.\n\n`auto` remains the normal experience; optional `idea`, `spec`, `plan`, `tasks`,\n`implement`, and `verify` ceilings support targeted work. Evidence, platform\ndecisions, dossier format, and milestone verification load progressively from\nseparate references.\n\n### `port-spectranext`\n\nThin orchestration for an existing ZX program's port to the Spectranext\ncartridge. It discovers and re-reads the current external Spectranext checkout,\nruns its absolute `tools/dev port request` entry point from the consumer root,\nand follows the state and next command emitted by that fail-closed gate.\n\nThe consumer owns its manifest, seam, artifacts, reports, worktree, and Git\nhistory. The Spectranext checkout remains the authority for cartridge code,\ndocumentation, and pipeline mechanics. The skill adds workflow effort routing,\nauthorization boundaries, progressive context loading, hardware checkpoints,\nand evidence reporting without copying the manifest schema or pipeline.\n\n### `debug-z80`\n\nEvidence-bounded root-cause debugging for one observed failure whose cause is\nnot yet established. It accepts crashes, wrong output, build/link failures,\nnondeterminism, regressions, hardware/emulator divergence, and failed repairs;\nit rejects known-cause fixes, speculative audits, and improvement work without\na failing behavior.\n\nThe skill preserves the request's modality: diagnosis stays read-only, while a\nrequest to diagnose and fix may cross the repair gate only after a falsifiable\nhypothesis identifies the owner and narrow acceptance check. Builds, probes,\nmeasurements, and candidate repairs run in a verified disposable worktree.\nPrimary-tree edits are limited to the proven repair and require prior user\nauthorization.\n\nIts Z80 symptom router starts from the smallest relevant boundary: first build\ndiagnostic, C/ASM ABI and stack, ISR ordering, bank/page restoration, generated\ncode, target delta, or hardware/emulator assumption. It returns\n`NOT_DEBUGGING`, `READY_TO_FIX`, `NEEDS_EVIDENCE`, `EXTERNAL`, or `FIXED` rather\nthan a catalogue of plausible causes.\n\n### `audit-z80`\n\nPreventive or broad read-only auditing for finding real defects and\nreproducible risks without turning one observed failure into a general scan.\n\n**Coverage**\n\n- C/ASM boundaries, calling conventions, registers, flags, and stack;\n- ISRs, `DI`/`EI`, reentrancy, and shared state;\n- memory maps, BSS, stack gap, banks, and overlays;\n- firmware, ROM, RST 8, esxDOS, divMMC, and differences among models;\n- C semantics, buffers, promotion, signedness, and lifetime;\n- generated ASM/listings, copt rules, and z88dk/SDCC behavior;\n- ULA, contention, ports, timing, and user-visible regressions.\n\n**Modes**\n\n- `auto`: preflight and adaptive depth.\n- `preflight`: profile and escalation signals without a full audit.\n- `full` / `diverge`: broad coverage with the same evidence gates.\n- Focus areas: `asm`, `c`, `abi`, `isr`, `memory`, `spectrum-hw`, `esxdos`,\n  `toolchain`, `copt`, and `map`.\n\n**Primary helpers**\n\n- `preflight_scan.py`: inventory of sources, artifacts, and risk signals.\n- `z80_pattern_scan.py`: structural ASM/C patterns.\n- `abi_inventory.py`: declarations, conventions, and C/ASM boundaries.\n- `map_summary.py`: symbols, addresses, and stack-gap approximation.\n- `smoke_test.py`: reproducible checks for the analyzers.\n\nThe output puts findings that pass the promotion gate first. If none survive,\nit says so and identifies the most important residual risk instead of padding\nthe report with weak observations.\n\n### `organize-z80`\n\nEvidence-first architecture and reorganization workflow for Z80 projects.\n\n**Coverage**\n\n- ownership, dependencies, mutable state, source layout, and runtime placement;\n- an optional persistent current, recommended, and verified-final project map;\n- pure ASM and mixed C/ASM seams, maps, symbols, generated inputs, and targets;\n- incremental migrations that preserve ABI, timing, banking, formats, and build contracts.\n\n**Modes**\n\n- `map`, `design`, `plan`, `apply`, and `review`, plus `help`.\n- Demand scales as `Focused`, `Standard`, or `Deep`; `apply` executes one approved, reversible slice only.\n\nIt reports severity, confidence, organizational cost, validation evidence, and\n`NO REORGANIZATION NEEDED` when the current structure is already proportionate.\n\n### `shrink-z80`\n\nSize optimizer based on measurement and net accounting.\n\n**Separate objectives**\n\n- storage size;\n- linked CODE/DATA;\n- resident memory;\n- BSS and stack headroom;\n- bank or overlay ceiling;\n- minimum reserve per target.\n\n**Modes**\n\n- `scan`: complete adaptive analysis.\n- `preflight`: artifact and pressure profile.\n- Focus areas: `deadcode`, `dedup`, `micro`, `data`, `compress`, `refactor`,\n  `arch`, `libpull`, `blackbelt`, and `reserve`.\n- `diverge`: broad exploration without relaxing the proof requirements.\n\n**Order of attack**\n\n1. Architecture, residency, data, and linked libraries.\n2. Generated code, helpers, and repeated representations.\n3. Compression with net cost and peak RAM accounted for separately.\n4. Micro-optimizations and higher-risk techniques only when they can matter.\n\nIt does not add together proposals that are dependent, subsumed, incompatible,\nor not yet built. It distinguishes safety (`SAFE`, `AGGRESSIVE`,\n`EXPERIMENTAL`) and measurement quality (`EXACTO`, `ESTIMADO`,\n`REQUIERE BUILD`).\n\n**Primary helpers**\n\n- `preflight_scan.py` and `artifact_freshness.py`;\n- `map_summary.py`, `deadcode_scan.py`, and `libpull_scan.py`;\n- `generated_helper_scan.py` and `literal_dup_scan.py`;\n- `z80_pattern_scan.py`;\n- `net_compression_check.py`, which separates storage savings from peak RAM.\n\n### `optimize-z80`\n\nMulti-objective strategy engine for deciding what to optimize first and how to\nvalidate it.\n\n**Areas**\n\n- size, cycles, and latency;\n- RAM, stack, and data layout;\n- rendering, contention, and I/O;\n- banks, overlays, and transitions;\n- C-to-ASM, ABI, libraries, code generation, and toolchain;\n- model- and hardware-specific constraints.\n\n**Modes**\n\n- `Triage`: read-only inspection without a build. Stale artifacts limit\n  confidence.\n- `Measurement`: reproducible baseline in a disposable worktree.\n- `Experiment`: requires explicit approval, changes a single variable, and is\n  deleted unless the user asks to keep it.\n\nIt first identifies the dominant bottleneck. It then applies policy and target\nvetoes, merges duplicates, audits the finalists, and recommends no more than\nthree next experiments.\n\nEach candidate includes:\n\n- evidence anchor and freshness;\n- area, mechanism, and expected impact;\n- effect on size, cycles/latency, RAM/stack, and UX where applicable;\n- risk, targets, constraints, rollback, and validation;\n- confidence (`PROVEN`, `LIKELY`, or `SPECULATIVE`);\n- the reason it currently outranks the alternatives.\n\nStatic cycle, map, or pattern estimators do not constitute proof by themselves.\n\n## Installation\n\n### Requirements\n\n- Codex with plugin and skill support.\n- `workflow` Light and Medium run directly; Heavy uses subagents when available.\n  Roles and model selection follow the canonical\n  [workflow policy](skills/workflow/references/roles.md), which checks runtime\n  capabilities and discloses model or effort fallbacks.\n- Git to clone and update the repository.\n- Python 3.9 or later for general helpers; Python 3.11 or later is required\n  whenever `optimize-z80` must parse or enforce a TOML policy.\n- z88dk or SDCC only when required by the project or a reproducible measurement.\n\n### Initial installation\n\nClone the repository anywhere under your home directory. The checkout is the\ncanonical source for all eleven skills.\n\n```sh\ngit clone https://github.com/IgnacioMonge/z80-skills.git ~/plugins/z80-skills\ncd ~/plugins/z80-skills\npython3 scripts/install_personal_marketplace.py\ncodex plugin add z80-skills@personal\n```\n\n`install_personal_marketplace.py` creates or updates\n`~/.agents/plugins/marketplace.json`, points `z80-skills` at the actual checkout,\npreserves all other entries, and replaces only the entry named `z80-skills`.\nDo not maintain authored copies, symlinks, or junctions for any bundled skill\nunder `~/.agents/skills/<skill-name>` or the legacy\n`~/.codex/skills/<skill-name>`.\nThose copies can shadow the namespaced plugin and omit package-level files such\nas `scripts/run_in_worktree.py`; copying individual directories from `skills/`\nis not a complete installation. The plugin already bundles all eleven skills,\nincluding `route-z80` and `workflow`. The installer warns when\nit finds one of these duplicate locations; move or disable it before opening a\nnew Codex task.\n\nOnly `route-z80` participates in implicit Z80-domain selection. The nine\nrouted skills remain available through explicit `$send-bridgezx`, `$develop-z80`,\n`$document-z80`, `$port-spectranext`, `$debug-z80`, `$audit-z80`,\n`$organize-z80`, `$shrink-z80`, and `$optimize-z80` invocations; after routing,\n`route-z80` loads only the selected sibling. Natural-language requests do not\nneed to be ambiguous to enter the router. This keeps routine repository work on\nplain `workflow` and avoids injecting every specialist description.\n\nOpen a new Codex task after installing: the skill catalog is loaded when the\ntask starts and does not update dynamically within an already open task.\n\n### Updating\n\n```sh\ncd /path/to/z80-skills\ngit pull --ff-only\npython3 scripts/install_personal_marketplace.py\ncodex plugin add z80-skills@personal\n```\n\nPlugin changes update the committed manifest version so Codex creates a fresh\ninstalled copy. Never edit `~/.codex/plugins/cache` directly. After updating,\nopen a new task again.\n\n### Grok Build and Claude sync\n\nOn Windows, install all eleven skills into Grok Build with the host adaptations\nderived from the canonical `workflow` sources:\n\n```powershell\npwsh -File .\\scripts\\install-for-grok.ps1\n```\n\nThe installer includes `route-z80`, preserves existing destination skills in a\ntimestamped backup by default, bundles the disposable-worktree runner, and\npatches only the installed copies. Add `-SyncClaude` to also copy the same eleven\ncanonical skill trees, without Grok adaptations, into `~/.claude/skills`:\n\n```powershell\npwsh -File .\\scripts\\install-for-grok.ps1 -SyncClaude\n```\n\nUse `-SkipBackup` only for disposable test destinations. Open a new Grok or\nClaude task after installation so its skill catalog reloads.\n\n## Usage\n\nThe skills are invoked through natural language. The more specific the target,\nobjective, and available artifacts are, the more precise the prioritization\nwill be.\n\n### Adaptive workflow\n\n```text\nUse workflow in auto mode to implement this change with the smallest sufficient\nexecution level and preserve the repository's existing contracts.\n```\n\n### Z80 domain routing\n\n```text\nUse route-z80 to choose the single relevant specialist for this Z80 repository\nrequest, or use plain workflow if no specialist evidence contract is needed.\n```\n\n### BridgeZX delivery\n\n```text\nUse send-bridgezx to send build/game.nex to my Spectrum Next with the last\nknown BridgeZX IP, under GAMES/DEMO.\n```\n\n### Repository documentation\n\n```text\nUse document-z80 to restructure this project's README as the landing page,\nverify every build and hardware claim, and keep the English and Spanish files\nstructurally aligned without losing the project's voice.\n```\n\n### Specification-driven development\n\n```text\nUse develop-z80 to lead this ZX Spectrum Next game idea from concept to verified\nimplementation. Choose and run the SDD stages for me; ask only when a material\nproduct decision is missing.\n```\n\n### Spectranext cartridge porting\n\n```text\nUse port-spectranext to resume this existing ZX program's port to the\nSpectranext cartridge. Begin with the canonical port request gate, preserve the\nconsumer seam, and stop for real hardware evidence when required.\n```\n\n### Root-cause debugging\n\n```text\nUse debug-z80 to isolate why this 128K build crashes after returning from the\nISR. Do not edit until one discriminating check identifies the causal owner;\nthen apply and verify the minimal fix.\n```\n\n### Auditing\n\n```text\nUse audit-z80 in auto mode to review this mixed ASM/C project.\nPrioritize ABI, ISR, and memory; report only findings anchored in the current code.\n```\n\n```text\nUse audit-z80 in full mode. Review the differences between the 48K and 128K targets,\nincluding paging, ROM, stack, interrupts, and generated artifacts.\n```\n\n### Organization\n\n```text\nUse organize-z80 in design mode to map ownership, dependencies, and placement in\nthis mixed ASM/C project, then propose only the smallest justified boundary change.\n```\n\n```text\nUse organize-z80 in apply mode to execute this approved phase only; preserve\nsymbol scopes, maps, ABI, and the existing rollback point.\n```\n\n### Size reduction\n\n```text\nUse shrink-z80 in scan mode. I need to recover at least 512 bytes of CODE/DATA\nwithout changing behavior, and keep exact savings separate from estimated savings.\n```\n\n```text\nUse shrink-z80 in compress mode to compare the net size and peak RAM of\nthe codecs applied to these specific assets.\n```\n\n### Multi-objective optimization\n\n```text\nUse optimize-z80 in Triage mode to identify the real bottleneck and return\nthe three experiments with the best balance of impact, risk, and cost.\n```\n\n```text\nUse optimize-z80 in Measurement mode to obtain a fresh baseline without\nmodifying my main working tree.\n```\n\n## Recommended artifacts\n\nThe skills can start with source files alone, but these artifacts increase\nconfidence:\n\n| Evidence | Usefulness |\n|---|---|\n| `.asm`, `.s`, `.c`, `.h` | Current semantics, ABI boundaries, patterns, and reachability. |\n| `.map`, `.sym` | Layout, symbols, sections, banks, library pulls, and stack gap. |\n| `.lst` or generated ASM | Actual compiler behavior and code-generation cost. |\n| Binaries, TAP files, and assets | Final size, compression, and reproducible comparisons. |\n| Build recipe and flags | Reproducibility, toolchain, ABI, and configuration. |\n| Explicit targets and limits | Vetoes, reserves, compatibility, and correct ranking. |\n\nA recent timestamp alone does not prove correspondence. The revision,\nconfiguration, and recipe must belong to the same baseline.\n\n## Safety and limitations\n\n- Normal analyses are read-only.\n- `workflow` never widens the permissions granted by a project or domain skill.\n- `develop-z80` keeps idea, specification, planning, and task breakdown\n  read-only; its first greenfield product-code edit also requires explicit spec\n  acceptance. Any multi-milestone auto-advance is bounded to the current session.\n- `port-spectranext` keeps the external Spectranext checkout authoritative and\n  consumer state isolated; source edits stay inside the authorized consumer\n  seam and physical results require explicit user observation.\n- `debug-z80` keeps diagnosis and candidate repairs in a disposable worktree;\n  it edits the primary tree only for a requested, causally supported repair.\n- `document-z80` edits only the public human-facing documentation in scope; it\n  does not change code, build configuration, releases, or agent instructions.\n- `audit-z80` and `shrink-z80` do not edit the project.\n- `organize-z80` edits source only in `apply` mode after an explicit request,\n  frozen baseline, approved boundary, one named slice, and rollback point; an\n  explicitly requested persistent-map update may edit only that document and\n  its routing pointer.\n- `optimize-z80` modifies only a disposable copy in `Experiment` mode and\n  requires explicit approval.\n- The included scripts use the Python standard library, work with local files,\n  and do not perform network searches.\n- Tests write to temporary directories and remove them when finished.\n- The plugin does not include z88dk, SDCC, emulators, or profiling tools.\n- It is not a compiler, hardware profiler, or automatic optimizer.\n- It does not confirm linked savings, timings, or compatibility without\n  appropriate evidence.\n- SMC, SP abuse, `DI`/`EI`, undocumented opcodes, floating bus behavior, and\n  other hardware-dependent techniques require risk labels and target-specific\n  validation.\n- External research must never publish private source code, paths, sensitive\n  symbols, or project identifiers.\n\n## Repository structure\n\n```text\nLICENSE\nREADME.md\nREADME.es.md\n.codex-plugin/\n  plugin.json\nevals/\n  baseline.json\n  routing.jsonl\n  evidence.jsonl\n  fixtures/\n  schemas/\nscripts/\n  install-for-grok.ps1\n  install_personal_marketplace.py\n  run_behavior_evals.py\n  run_in_worktree.py\n  test_behavior_evals.py\nskills/\n  workflow/\n    SKILL.md\n    agents/openai.yaml\n    references/\n  route-z80/\n    SKILL.md\n    agents/openai.yaml\n  send-bridgezx/\n    SKILL.md\n    agents/openai.yaml\n    scripts/\n  document-z80/\n    SKILL.md\n    agents/openai.yaml\n  develop-z80/\n    SKILL.md\n    agents/openai.yaml\n    references/\n  port-spectranext/\n    SKILL.md\n    agents/openai.yaml\n    references/\n  debug-z80/\n    SKILL.md\n    agents/openai.yaml\n    references/\n  audit-z80/\n    SKILL.md\n    agents/openai.yaml\n    references/\n    scripts/\n  organize-z80/\n    SKILL.md\n    agents/openai.yaml\n    references/\n  shrink-z80/\n    SKILL.md\n    agents/openai.yaml\n    references/\n    scripts/\n    tests/\n  optimize-z80/\n    SKILL.md\n    agents/openai.yaml\n    references/\n    scripts/\n```\n\nEach skill keeps its core instructions in `SKILL.md` and selective-loading\ndetails in `references/`; skills with reproducible analyzers keep them in\n`scripts/`.\n\n## Validation\n\nIncluded tests:\n\n```sh\npython3 scripts/test_workflow_integration.py\npython3 scripts/test_workflow_context_efficiency.py\npython3 scripts/test_personal_marketplace.py\npython3 scripts/test_run_in_worktree.py\npython3 skills/audit-z80/scripts/smoke_test.py\npython3 skills/shrink-z80/tests/run_smoke.py\npython3 -m unittest discover -s skills/optimize-z80/scripts -p 'test_*.py'\npython3 scripts/test_behavior_evals.py\npython3 skills/send-bridgezx/scripts/test_bridgezx_transfer.py\n```\n\nThe plugin manifest and the front matter of each skill should also be validated\nbefore publishing a new version.\n\nBehavior evals are intentionally separate from unit tests. Validate their\ndatasets without using a model:\n\n```sh\npython3 scripts/run_behavior_evals.py --dry-run\n```\n\nAfter installing the same plugin version shown in `.codex-plugin/plugin.json`,\nrun the labelled routing and evidence suites in fresh, read-only Codex sessions:\n\n```sh\npython3 scripts/run_behavior_evals.py --suite evals/routing.jsonl\npython3 scripts/run_behavior_evals.py --suite evals/evidence.jsonl\n```\n\nThe runner refuses a stale installed plugin version unless explicitly\noverridden, records per-route precision and recall, and writes ignored JSON\nresults under `evals/results/`. `evals/baseline.json` keeps the small,\nnon-sensitive verified summary and distinguishes full runs from targeted\nrepair replays.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\nCopyright © 2026 M. Ignacio Monge García.\n\n## Author\n\nM. Ignacio Monge García\n",
  "bytes": 30298,
  "sha": "9951150749349ce408423e704d413cf196f613468cf2f74f04d7288d08ae6949",
  "repo_slug": "ignaciomonge/z80-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ignaciomonge_z80_skills_e3d1eaca/readme"
}