organize-z80
Map Z80 ownership and dependencies, design boundaries, or plan and apply an approved reorganization. Use for structural work and persistent project maps in ASM/C, z88dk/SDCC, banked or overlay project
SKILL.mdskills/organize-z80/SKILL.md
GitHubOrganize Z80
Design the smallest sustainable organization justified by the current project. Treat source structure, runtime placement, ownership, and dependency direction as separate decisions: on Z80, a tidy directory tree can still produce a worse binary, extra calls, bank switches, duplicated state, or an unsafe memory map. Cover applications, ROMs, games, tools, and drivers, including RAM, rendering, storage, input, audio, protocols, hardware, resources, and application logic. Preserve binary, storage, and multi-target contracts without imposing a framework.
Workflow Core
Apply the sibling $workflow skill at ../workflow/SKILL.md as the execution
control plane. Workflow owns effort, agent topology, dispatch, repair,
verification, and integration; this skill owns organization modes, evidence,
the S–V domain flow, persistent-map rules, and mutation permissions. A workflow
route never widens those permissions or bypasses the apply gate. If the sibling
skill is unavailable, report the exact limitation and continue directly
without claiming delegated execution.
Modes
help: explain modes, demand, evidence required, and the smallest safe next step; do not inspect or propose a target structure.map: establish current topology, ownership, placement, and risks; do not prescribe moves or a target tree; keep it read-only unless the user explicitly requests the persistent-map exception below.design(default): define proportional boundaries and their rationale; do not order migration work, edit source, or imply approval.plan: turn an approved or clearly stated design into reversible slices; do not edit source.apply: execute exactly one approved slice; do not widen scope, redesign, combine behavior changes, or start without all apply gates.review: assess an existing architecture or proposal against this skill's contracts; do not edit or silently turn findings into a migration plan.
Domain Demand
Classify after the initial map and pass the result to $workflow when it is in
auto:
- Focused: one component, state owner, dependency cycle, memory region, or proposed move. Analyze only the affected boundary; light is normally enough.
- Standard: several coupled components or one cross-cutting responsibility. Map the relevant execution and data paths before designing; medium can own a cohesive multi-file slice.
- Deep: whole project, several targets, mixed C/ASM, interrupts, banking, overlays, generated assets, or a requested migration. Heavy can split independent surfaces; cover every active responsibility and runtime placement class, or state what remains unmapped.
An explicit workflow level wins. Do not turn a small project into a layered framework. A single file with clear sections and contracts may be the correct organization.
Routing and progressive disclosure
Except in help mode, read references/hard-contract.md first. Read
references/project-model.md when mapping more than a named local boundary.
Load only the references selected by the following signals:
| Signal | Read |
|---|---|
| Target boundaries, dependency direction, or layout | references/organization-patterns.md |
| Planned or applied move, split, include change, or validation | references/migration-and-validation.md |
| C/ASM, z88dk, SDCC, assembler scope, linker, CRT, or toolchain seam | references/toolchain-layout.md |
| Persistent current, recommended, final, or stale project map | references/persistent-project-map.md |
| Formal/durable deliverable, or Standard/Deep report | references/reporting.md |
Use these workflow steps, stopping once the selected mode and demand are satisfied: S scope; B baseline; E execution map; M state, placement, and dependency map; C seam/contract; D design; P one-way slice plan; V verify and report.
| Mode | Focused | Standard | Deep |
|---|---|---|---|
help |
Explain S–V only | Explain S–V only | Explain S–V only |
map |
S, local M, report | S, E/M/C, report | S/B/E/M/C, report gaps |
design |
S, local M/C/D | S/E/M/C/D | S/B/E/M/C/D across active classes |
plan |
S/B/C/P/V gate | S/B/E/M/C/D/P/V gate | S/B/E/M/C/D/P/V by approved phases |
apply |
S/B/C, one P slice, V | S/B/C, one P slice, V | S/B/C, one P slice, V; never the whole plan |
review |
S, local M/C, report | S/E/M/C, report | S/B/E/M/C, report gaps |
Do not build merely to decorate a read-only proposal. For Focused, inspect
only the affected boundary. For Standard, map coupled execution and data
paths. For Deep, cover every active responsibility and placement class or
name the unmapped remainder.
For a non-durable Focused result, do not load references/reporting.md.
Return only the decision or finding, its current anchor, the preserved boundary,
the narrow check or next step, and material residual risk.
Apply gate
Enter apply only when all conditions hold:
- Receive an explicit request to edit.
- Freeze a relevant baseline, including repository state when available and the cheapest applicable build, map, symbol, artifact, emulator, or hardware evidence.
- Have an approved design or boundary contract.
- Name one phase or slice, its acceptance gate, and its rollback point.
If any condition is absent, remain read-only and state the missing gate.
Persistent project map
When a canonical project map already exists, read the sections relevant to the
requested ownership, dependencies, placement, or migration. For a named local
boundary, do not load the full map unless unresolved dependencies or an explicit
project requirement make it necessary. In help, do not load it. Verify volatile
claims used in the answer against current source; routed context is not proof.
Create or update it only after an explicit request. A map-only write may edit
the approved map and routing pointer without authorizing source, build, or
configuration changes. Follow references/persistent-project-map.md for its
location, lifecycle, drift rules, and current/recommended/final contract.
Decision Rules
- Split by ownership and reason to change, not file length or noun count.
- Keep one authoritative owner for mutable state; expose operations or snapshots instead of writable globals.
- Point dependencies from application orchestration toward capabilities and from capabilities toward explicit platform adapters. Keep hardware-specific details at the edge unless timing or placement requires deliberate colocation.
- Keep memory layout authoritative in one place even when data users live in several modules.
- Keep generated files derivative. Edit their source, generator, schema, or manifest rather than the generated output.
- Preserve a stable boundary across targets; isolate target differences behind assembly-time selection or narrow adapters only when multiple variants exist.
- Prefer direct calls and explicit data over factories, registries, service locators, generic managers, or function-pointer frameworks.
- Accept duplication when sharing would introduce bank traffic, long calls, unstable ABI, lifetime coupling, or larger linked output; record the reason.
- Reject a move whose only benefit is aesthetic and whose runtime or validation cost is material.
Relationship to Other Z80 Skills
- Use
audit-z80separately when the map exposes a correctness, ABI, ISR, memory-corruption, or hardware-risk question. - Use
shrink-z80separately for size claims andoptimize-z80separately for speed, RAM, rendering, latency, or multi-objective claims. - Do not claim that reorganization improves bytes or cycles without fresh local evidence. Maintainability evidence may justify a design even when runtime metrics remain neutral.
Core Rules
- Preserve behavior, public APIs, file and wire formats, target support, build entry points, and user data unless the user explicitly authorizes a break.
- Never mix unrelated modernization, renaming, formatting, optimization, or bug fixes into a structural migration.
- Never infer safety from compilation alone; validate runtime placement and hidden contracts appropriate to the changed boundary.
- Produce no empty directories, placeholder modules, speculative interfaces, or abstractions for hypothetical future targets.
- State
NO REORGANIZATION NEEDEDwhen current ownership and dependencies are already proportionate to the project.