Imported from xwings/eatmycode (SKILL.md). Install upstream with npx skills add xwings/eatmycode. Copyright stays with the author.

eatmycode

Maintain architecture docs that help agents locate, understand, change, and verify code. Repository code, configuration, and explicit project requirements remain authoritative.

Use the Development Loop for every task. Run the freshness gate before relying on architecture docs; use the Output Contract, Root Contract, Module Template, and Architecture Verification when creating or updating them. Read the root's cross-cutting rules and Index, then only the owning modules, relevant interaction partners, and cited source and tests.

Version and Freshness Gate

On every invocation, read metadata.version from the active skill and eatmycode_version from YAML frontmatter in ARCHITECTURE.md and every ARCHITECTURE/<module>.md. Read module metadata first; load full bodies only when relevant or stale. Compare stable SemVer (MAJOR.MINOR.PATCH) as integer components, never strings, timestamps, or remembered releases.

A newer recorded version takes precedence over all migration actions. An invalid or missing active version also prevents migration certification. In either case, finish independently verifiable requested work from source without claiming that the architecture contract or full gate passed.

Refresh content before stamps: reconcile source facts, required sections, shared rules, links, and content scope; preserve durable guidance and justified deviations. Never rely on a stale claim during migration. After Architecture Verification passes, stamp each refreshed file. Stamp the root only after all modules satisfy the contract, then verify stamp agreement. Keep old stamps during edits and new files unstamped until verified; a partial migration must not claim completion.

Verified root and module files start with this YAML, replacing the placeholder with the active version:

---
eatmycode_version: "<active SKILL.md metadata.version>"
---

metadata.version is the single release-version source. Bump major for incompatible contracts, minor for compatible requirements or capabilities, and patch for clarifications or fixes. Every older stamp triggers refresh, including a patch difference; unversioned docs are legacy docs to migrate.

Output Contract

• Keep only coding context in ARCHITECTURE.md and ARCHITECTURE/: facts needed to locate, understand, write, review, debug, test, improve, or refactor code. Use concise facts, commands, ownership links, and source references.
• Exclude deployment/publishing guides, production runbooks, infrastructure operations, business plans, project administration, and human onboarding or tutorials. Remove excluded content encountered during maintenance, files devoted to it, and obsolete Index entries; repair links. Retain coding context in mixed files. A full refresh or content-scope audit inspects the whole set.
• Judge by purpose: implemented runtime behavior, failure handling, configuration contracts, infrastructure/tooling code, and build/test prerequisites belong here when they inform code changes. A deployment tooling subsystem may own a module doc; live inventories and deployment procedures belong elsewhere.
• The root owns cross-cutting facts and an Index routing tasks to one owning module per real subsystem. Modules own local detail; cross-link it instead of duplicating prose or source inventories.
• Populate contracts from manifests, build/CI and formatter/linter configs, representative code, tests, and existing design decisions. Cite configs or file:line precedents. Distinguish required rules, observed behavior, and proposals. State inspected evidence and unknowns; never invent facts, rationale, standards, or milestones. Explain not applicable topics.
• Migrate durable coding guidance from regular AGENT.md, AGENTS.md, and CLAUDE.md; preserve useful non-coding guidance elsewhere and drop stale boilerplate. Only then replace those files with symlinks to ARCHITECTURE.md. If absent, create names used by the project or harness.
• Update the root, affected modules, and Index in the same change when language/toolchain, conventions, design, ownership, data flow, integration, module/function contracts, or public behavior changes.
• Project-specific exceptions go under ### Project-Specific Deviations after the affected shared section. They may strengthen the Definition of Done; never weaken or edit the shared text.

Root Contract

After version frontmatter and the project title, include these level-two sections in order. Keep project-wide facts here and link local detail.

Then copy this skill's complete ## Development Loop, ## Coding Discipline, and ## Review Checks sections verbatim and in that order, followed by ## Index. Modules do not repeat these shared sections. Each Index row links the owning module doc and lists its source paths, responsibility, task/change triggers, and relevant integration partners.

Module Template

After version frontmatter, use these exact headers in order. Keep content local to the owner and link root rules and partner modules.

# <Subsystem name>

## Goal

Ownership, non-goals, and established roadmap milestone (`M1`..`Mx`) when
one exists. Identify infrastructure or scaffolding without inventing work.

## Status

Choose one; explain missing/replacement work and cite supporting evidence:

- `done`: implemented and **How to Test** passes.
- `in progress (Mx)`: partially implemented.
- `pending (Mx)`: not started.
- `scaffolding`: works now; state its replacement and timing.

Omit milestone suffixes when none is established; state unverified behavior.

## Code Structure

| File | Role |
| ---- | ---- |
| `src/<area>/<file>` | Owned responsibility. |

Use repository-root-relative paths; retain the table for a single file.

## Language and Conventions

Languages, applicable root toolchain/style rules, local exceptions,
canonical implementations, and formatter/linter/type-checker/test configs.
Cite sources and distinguish enforced rules from observed patterns.

## Design and Invariants

Decomposition, dependency direction, extension points, supported rationale,
and invariants: state ownership, validation, errors/recovery, compatibility,
and relevant concurrency, resources, performance budgets, and trust
boundaries. Cite enforcing code/tests and identify missing evidence.

## Key Types and Entry Points

Up to 10 types, functions, commands, or entry points an agent must inspect
to change this subsystem, with current `file:line` references. Give each
responsibility and caller-visible inputs, outputs, side effects, and
failure behavior. Do not pad small modules or copy implementations.

## Interactions

Cross-link callers, callees, producers, and consumers. Identify each API,
event, schema, or shared-state boundary, direction, compatibility duties,
and integration tests.

## How to Test

Exact build/test/static-check commands, working directories, prerequisites,
and observable evidence (output, exit code, or artifact). Map behavior and
invariants to tests; name coverage gaps and environment restrictions.

## Review and Refactor Guide

Map likely changes to symbols, dependent modules, and tests to inspect.
Record extension points, reusable patterns, forbidden coupling, and
compatibility/migration checks. Separate evidence-backed improvement
proposals with benefits and success checks from accepted work and design.

## Open Gaps / Roadmap

Coding TODOs, deferred work, platform gaps, and established implementation
milestones. Tag `Mx` only when known.

Architecture Verification

Use this checklist during Prove after every architecture write or fix. Verify the whole set for a missing, unversioned, invalid, or older root; otherwise verify the root and affected/stale modules. Retain prior verification for current modules unless changed source, shared rules, or interactions affect them. Apply the freshness gate's newer-version exception.

• Structure: Root sections and shared text match the Root Contract; modules use the Module Template headers in order. Every real subsystem has one owner; Index and partner links resolve and route tasks correctly.
• Evidence and scope: Paths and file:line references resolve to current source. Language, style, design, and architecture claims cite evidence; unknowns and inapplicable topics are explicit. Docs obey the Output Contract and guide agents to owners, constraints, and checks.
• Migration: Coding guidance was migrated and useful non-coding guidance preserved before managed agent files became symlinks to the root.
• Behavior: Each new or updated module's How to Test commands run and prove its stated Status; running a command alone is insufficient.

After these pass, apply the freshness gate's stamps and verify agreement. Then continue through Review and the Development Loop's completion gate.

Development Loop

Frame → Write → Prove → Review → Gate. Findings return to Write; uncertainty that changes the plan returns to Frame.

Use one subagent per role when available, otherwise distinct labeled passes. Tester and Verifier report findings and never edit; Coder repairs.

The loop

1. Frame: Inspect the request, code, docs, and conventions before planning. Give the goal and each plan step an observable check. When using eatmycode, run its Version and Freshness Gate before trusting architecture; include versions, migration scope, Index/agent-file changes, and verification commands in architecture plans. Resolve uncertainty from evidence and record the narrowest supported assumptions. Only Planner may ask one focused question, when a required decision cannot be discovered or safely inferred and guessing changes the result.
2. Write: Apply Coding Discipline. Make the planned change; for a repair, address only named findings. Update affected architecture with changes to its documented contracts.
3. Prove: Run relevant tests and structural checks, retaining observable evidence. For architecture work under eatmycode, apply its Architecture Verification. Failures and missing, duplicate, or obsolete coverage become Coder findings. Re-run affected checks after repairs; never send a red result to Review.
4. Review: Apply every Review Check as a separate pass over full affected files. Use an independent agent or isolated pass for Fit, Dependencies, and Security when available. Return findings to Coder, then re-prove and re-review the repairs.
5. Gate: Confirm completion only when the Definition of Done passes. Return unmet criteria to the responsible stage; continue until resolved. If an external constraint prevents verification, state the missing evidence and remaining work without claiming completion or readiness.

Handoffs are automatic. Continue without pauses for plan approval, permission to continue, or review/reporting ceremonies. Finish with the harness's normal concise completion handoff.

Definition of Done

• Correctness: The goal and named checks pass. Tests cover claimed behavior; bug fixes have a reproducing regression test. The project builds and tests from a fresh clone without local-only dependencies. Owning modules' How to Test commands pass with evidence.
• Review: Every Review Check ran and its completion threshold passes.
• Contract: Docs reflect source and let an agent locate owners, constraints, and verification commands. When using eatmycode, architecture satisfies its Output Contract, verification, and version rules. Public names, signatures, errors, and recovery are intelligible. Breaking changes, deprecations, dependencies, licenses, and attribution are handled; commit or PR text, when present, explains why.
• Scope: Changed lines serve the goal and follow Coding Discipline; no debugging remnants, commented-out code, secrets, tokens, or local paths remain. Test edits follow the inventory and coverage rules below.

Iterating without thrashing

• Each repair pass targets a named finding; nits alone do not trigger one.
• Two no-change passes force Gate re-evaluation. If Done still fails, return the surviving evidence to Frame.
• Three passes against the same finding return to Frame for a new approach.
• Never widen scope to satisfy a finding. Record coding follow-ups under Open Gaps / Roadmap and keep non-coding work outside architecture.

Coding Discipline

• Implement only the goal. Prefer the simplest approach that passes its checks; simplify code materially larger than the problem.
• Match local style. Avoid speculative features, flexibility, single-use abstractions, and checks for impossible conditions.
• Keep edits surgical: no unrelated refactoring, reformatting, or cleanup. Remove imports, variables, and functions made unused by this change; leave pre-existing dead code alone unless requested.
• Make success concrete: validation rejects invalid input in a named test; a regression test fails before a bug fix and passes after; behavior tests pass before and after a refactor.

Before editing tests

Before any test edit, including during Write, inventory the whole suite: enumerate every test file and case name, then read in full tests whose subject, fixtures, or assertions touch the change. Use a subagent for broad inventory when supported. Plan all additions, changes, merges, and removals from that evidence, citing file:line, before executing the test edits.

• Reuse first: Extend the test owning the behavior or sharing its setup, fixtures, and subject. Add a function/file only if no existing owner fits or merging would obscure which case failed.
• Add only required coverage: A bug fix needs its regression test; a capability needs a test of its claimed behavior. Avoid duplicates.
• Retire only what changed: Remove tests of deleted behavior and merge new duplicates, citing surviving coverage. Record unrelated suspected redundancy under Open Gaps / Roadmap.
• Preserve coverage: Never delete or weaken tests to turn red green. Removal needs evidence that behavior is gone or covered elsewhere; coverage of claimed behavior must not decrease.

Review Checks

Run every check against every change before confirming a code edit is complete, even when no commit or merge is requested. Keep checks separate.

• Evidence or no finding: Cite file:line for every finding.
• Repository authority: Demand only conventions supported by the tree.
• Full context: Read affected files, not only hunks; context can expose unreachable code, unused parameters, or hidden duplication.
• Code and impact: Review the change, never the author or how it was made.

1. Style and Naming

Check indentation and local conventions; leave machine-checkable formatting to existing formatters/linters and never demand unrelated reformatting. Mixed indentation is major; a consistent new file with the wrong local indent is nit. Compare names with nearby precedents. If the repository is inconsistent, demand nothing. A local naming mismatch is nit; an inconsistent public name is major.

2. Duplication

Search distinctive constants, errors, fields, and call sequences, beyond symbol names, for the same job. Cite both sites and a remedy. Cross-layer duplication is major; small local repetition is nit. Similar code with meaningfully different branches is not duplication.

3. Quality

Require followable control flow, errors handled where they occur, and proportionate abstractions. Swallowed errors, inappropriate prints, unexplained magic values, and dead branches are major. Remove unrequested configurability, one-caller wrappers, filler comments, debugging remnants, and unrelated formatting. Missing tests belong to Prove.

4. Fit

Read the root architecture and owning module before the diff. Check language/toolchain constraints, conventions, scope, layering, ownership, invariants, public-API growth, compatibility, and performance claims against source. A layering violation or unjustified public API is major. Architectural/public-behavior changes need matching docs in the same change.

5. Dependencies

Check manifests/imports, maintenance, supply-chain risk, advisories, install-time behavior, license, transitive cost, and standard-library alternatives. An unjustified top-level dependency is major; a live advisory or abandoned upstream is blocker. Incomplete evidence does not pass.

6. Security

Check defects and widened exposure: unsafe memory access, unchecked sizes or offsets, integer overflow, traversal, unsafe deserialization, command construction, committed secrets, and unbounded untrusted input. Trace input to impact; without a reachable path there is no finding. A real defect is major; a trust-boundary break is blocker. Describe fixes without exploit steps.

Severity and the completion threshold

Confirm completion or merge only with no blocker or unresolved major. A check that did not run does not pass; explain evidence-backed inapplicability. Findings feed Write and Gate directly.