John Madrid · Galleon

Your project should explain itself.

Galleon helps a project carry its own understanding: to the person directing the work, the coding agent working in it, and whoever picks it up next.

Public · early development · 9 skills

View on GitHub How it works

01 · The problem

Every new session starts behind.

Decisions and boundaries live in chat history, leaving the person directing the work to constantly re-supply context. Every new session, the agent has to reconstruct what matters, what is already settled, and what it is actually allowed to touch.

Installing another plugin, prompt library, or autonomous framework can help with a single task. But without a coherent, durable record of its purpose, decisions, and boundaries, the project itself stays silent. Each new session burns effort reconstructing understanding that should already belong to the codebase.

FIG_01 · A record that continues

02 · The inversion

The project’s file architecture is the agentic framework.

Skills carry portable method; the project owns its meaning, authority, boundaries, and state.

Instead of hiding orchestration inside proprietary sidecars or opaque prompt chains, Galleon organizes understanding into plain files in the repository. They are versioned in Git, readable by the person directing the work, and directly navigable by the agent executing it.

Built on Interpretable Context Methodology (Van Clief & McDermott, 2026). Galleon’s adaptations are its own.

FIG_02 · One shared record

03 · How it works

Make the work inspectable.

Find the job and existing rules.
Explain missing boundaries with a small example.
Agree on the work and checks.
Perform authorized work.
Review the result.
Preserve the next useful starting point.

Before implementation, the work becomes inspectable: what may change, what must stay intact, and how the result will be checked. The detail follows the job. A small correction may need only a clear instruction; a consequential change may call for exact file boundaries, baseline hashes, and a saved plan.

It does not require an approval ceremony at every step. Work already covered by the project’s rules and the person’s authorization proceeds directly. When the work expands or authority is unclear, Galleon asks for the decision that matters.

FIG_03 · Decisions between stages

04 · Bounded methods

Nine skills that refuse to overstep.

One verb and one boundary per skill; explicitly not a mandatory pipeline.
Skill	Job	Won’t
charter	Plan a real job	Implement it
scaffold	Create agreed structure	Overwrite existing work
import	Apply an agreed context mapping	Discard content or references
delegate	Write work items	Select models or dispatch work
survey	Explain a result	Repair or accept it
remember	Capture verified state	Overstep existing record owners
sync	Correct navigation from existing facts	Invent owners or rules
audit	Test a structure against its job	Repair live work
diagnose	Explain a failure	Repair it

The README describes two ways in: a plain request or a named skill. Both are designed to lead to the project’s own records and contracts.

05 · Under the hood

Method from Galleon. Authority from the project.

These diagrams show how the parts meet and what each helper does. Each is drawn from Galleon’s files at commit 325d0d7 and links to the lines it shows.

FIG_05 · Method and authority · Illustrative

Ask an agent to “use charter to plan” a change. Charter’s first instruction sends it to the project’s entry files, AGENTS.md and CONTEXT.md in this example, and on to the plan and records they route to. If no task agreement exists, charter can show Galleon’s blank form; once adapted and approved, the copy lives in the project, and the next session reads that copy. “Continue this project” is designed to reach the same records directly.

CONTEXT.md, lines 13–14

One real project, before and after

Before Galleon22 root files

game-project/
  README.md
  01-foundation.md
  IDEA-SCOPE.md
  design-map.md
  mechanics-brief.md
  RULES-DRAFT.md
  ENGINE-VALIDATION.md
  D05-PUBLIC-API-PLAN.md
  audit.md
  J2-PLAN.md
  J2-DECISIONS.md
  J2-TICKETS.md
  T21-ACCEPTANCE.md
  balance-results.json
  index.html
  package.json
  package-lock.json
  tsconfig.json
  tsconfig.app.json
  tsconfig.content.json
  tsconfig.node.json
  vite.config.ts
  authoring/
  content/
  research/
  rules/
  scripts/
  src/
  tests/
  workbook/

After Galleon13 root files

game-project/
  README.md                    updated  introduction and current work
  AGENTS.md                    new      boundaries and human approval
  CLAUDE.md                    new      @AGENTS.md
  CONTEXT.md                   new      root router: 8 grouped routes
  WORKFLOW.md                  new      plan, hand off, review, accept
  memory/
    CONTEXT.md                 new      capture; read-only resume
  work/
    CONTEXT.md                 new      routes each job to its records
    j2/
      current.md               new      current job and next action
      J2-PLAN.md               updated  reviewed build agreement
      J2-DECISIONS.md          updated  decisions and history
      J2-TICKETS.md            updated  bounded tickets and acceptance
      T21-ACCEPTANCE.md        updated  checks; sign-off pending
    j1/                        updated  engine validation and sweep
    d05-public-api/            updated  earlier API plan and audit
    bootstrap/                 new      first setup record
    galleon-adoption/          new      adoption and cleanup records
  design/
    CONTEXT.md                 new      scope, rules and history
    pilot-contract.md          new      live pilot requirements
    IDEA-SCOPE.md              updated  declared purpose and scope
    RULES-DRAFT.md             updated  approved engine rules
    01-foundation.md           moved    design decisions and history
    design-map.md              moved    proposals, not approvals
  research/mechanics-brief.md  moved    reference mechanics
  authoring/                   updated  content format and review
  workbook/                    updated  routes only; owner’s words kept
  rules/ content/ src/ tests/           game code and tests
  index.html, package.json, …           build configuration

The same game project and the same game code. Before: 22 files at the root, 13 of them Markdown, with only a README to start from. After: five short entry documents at the root, and every other record in a routed folder. Markers: new, created; updated, edited in place or on the move; moved, relocated unchanged.

Galleon did this reorganization inside the project. It set up the entry files, routers, and procedures; charter proposed each structural change and the owner approved it; import moved fifteen records into work/ and design/; sync repaired the links; survey reviewed the result; and remember recorded where work stands in work/j2/current.md. The game code and the owner’s notes stayed byte-identical.

What every skill does first

Each skill names one job and one boundary, as the table above shows. Between the two, all nine carry the same ten lines, starting with: read the project’s entry and relevant records, inspect the current files, and treat an invocation as no permission to overwrite files or invent approval. Each skill’s text also says to read a bundled resource only when a stated condition holds.

Limit: Instructions, not enforcement: the skills guide an agent and do not block edits.

charter/SKILL.md, lines 10–19

FIG_06 · One opening, nine skills

Four optional helpers

Four short Python scripts sit beside the skills that use them. Each answers one mechanical question about files it is given, prints a short report, and exits with a code the agent can act on. None writes, moves, or deletes a file, and the skills work without them. Their 43 tests ran on macOS with Python 3.9.6.

FIG_07 · count_tokens.py · charter · 7 tests

skills/charter/scripts/count_tokens.py

Problem: Routine files grow until each session reads more than its job needs, and nobody can see how much.
Check: Counts whitespace-separated words in each named file and multiplies by 1.3, rounding up. In its test, “one two three” estimates 4 and an empty file 0, so the read set totals 4. Duplicate paths and hard links count once.
Why a script: The estimate is arithmetic, so the same files give the same number every time. The agent gets one line per file, not the files themselves. Exit 0 means measured; 2 means a bad input, with nothing partial printed.
In the lifecycle: Agreeing on the work: charter runs it when file size bears on a proposed split or route. A project can also run it at session start or closing capture.

Limit: A rough estimate, not a model tokenizer count; it does not measure token savings.

token-count.md, lines 21–33

FIG_08 · check_collisions.py · scaffold · 11 tests

skills/scaffold/scripts/check_collisions.py

Problem: A new README.md can collide with an existing Readme.md: some filesystems treat similar spellings as one name.
Check: Compares proposed names with the folder’s current names after Unicode normalization and case folding. In its test, README.md matches Readme.md, and a decomposed café matches a precomposed one: both occupied, exit 1. A clear preview exits 0; invalid names or an incomplete check exit 2.
Why a script: Name matching is mechanical and easy to get wrong by eye. The script lists one folder and prints only the conflicts; it creates, adopts, and renames nothing.
In the lifecycle: Performing authorized work: scaffold previews its agreed names before creating anything, and rechecks just before creation.

Limit: A conservative policy, not an emulation of every filesystem; a clear preview reserves nothing.

test_collision_checking.py, lines 64–70

FIG_09 · check_links.py · sync · 13 tests

skills/sync/scripts/check_links.py

Problem: A route such as [setup](docs/setup.md) is useful only while its target exists. After files move, routes can point nowhere.
Check: Reads the named Markdown files and tests each local link’s path. In a sample run, ../good.md exists and absent.md does not, so line 4 is reported missing and the run exits 1. Web links are skipped and #setup is reported as unverified. Exit 2 means the check could not finish.
Why a script: Whether a path exists is a mechanical fact. The script settles it and prints findings, not document bodies, so the agent can spend its attention on whether a route points to the right owner.
In the lifecycle: Preserving the next starting point: after a move, sync confirms the routes the next session will follow.

Limit: Checks paths only: not headings, external sites, descriptions, or who owns a route.

link-checking.md, lines 58–74

FIG_10 · file_inventory.py · audit · 12 tests

skills/audit/scripts/file_inventory.py

Problem: After a job, or when resuming, a project needs to know whether the files it relied on are still the same bytes.
Check: capture prints each named file’s size and SHA-256; compare checks the same list later. In a sample run, a rate edit kept rules/pricing.py the same size but changed its hash, so the run exits 1. A full match exits 0.
Why a script: A hash answers “did these bytes change?” exactly, without reading file bodies into the agent’s response. The project decides where to save the baseline.
In the lifecycle: Agreeing and reviewing: capture when a job’s checks are agreed, compare when the result is reviewed, or before trusting remembered state on resume.

Limit: Only listed files are compared; extra files, modes, Git state, and meaning are not.

file-inventories.md, lines 83–99

06 · Evidence and honest limits

Published proof. Stated limits.

9Markdown skills

4optional read-only checks

43focused tests for the optional helpers, on macOS

Piloted on real projects, including a fresh session resuming from project records.

This portfolio is maintained under Galleon contracts; adoption preserved every existing site file.

Not yet established

No versioned release yet; this is an early-development edition.
An independent trial by an unfamiliar user is the stated gate before v1 and is still pending.
The skills are instructions: they guide an agent and do not block edits or authenticate approval.
Helper tests ran on macOS; discovery in other agents (for example, Claude Code) and on Windows is not yet checked.

Read the verification record

07 · Origin

From Banka to Galleon.

I built a framework that told projects how to be structured. Testing it against its own theory showed that was backwards. So I rebuilt it to help each project define itself, and published it with its evidence and limits stated.

The seed. A JavaScript Mastery Pro tutorial showed durable context files as a fix for AI context drift: nine context files and five command skills, built for one project and one stack. I kept the principle and rebuilt both, so the files could fit any project and the skills could fit the framework around them.
Banka. That rebuild became Banka, a public, versioned framework: nine skills, project tiers sized to real complexity, and a protocol for carrying purpose, decisions, and state between sessions. ICM shaped its later rules, such as one home per fact and a cold-agent test.
Assessment against ICM. I renamed and extended Banka’s protocol, then assessed it against ICM itself. The research returned nine findings and one uncomfortable conclusion: the framework had been fitting projects to the tool’s shape, the reverse of what ICM teaches.
The inversion. From late September I rebuilt it around the project: the project’s files form the harness, and skills are only entry points. Pilots on my own projects tested the idea.
A guarded engine. The first v1 candidate added a guarded engine and installers, with 99 automated tests, recovery from interrupted operations, and a Windows installer sequence. But its guards blocked only operations run through its own commands; an edit made any other way went straight past them.
The lean public edition. So I cut the engine. If the project’s files are the framework, the project should not need Galleon’s machinery to work. The public edition is nine Markdown skills that need no Python, engine, or acceptance database, plus four optional, tested helpers. The engine’s results stayed with the engine; this edition publishes its own, smaller evidence.

A bigger engine looked like the obvious next step. It would have moved the project’s process back into the tool, which is the mistake Banka made. Mechanics still matter, but they should serve the project’s own contracts, stay optional, and earn their place with tests.

Galleon is still in development, and the engine will return in that form. The four helpers are the first pieces: small, read-only, and tested on their own. Installation, recovery, and deeper checks will come back the same way, each proving itself before it ships, ahead of the independent trial that gates any v1.

Banka was a small boat. Galleon is named for what it does: help a project carry its own understanding from one session to the next.

Archived Banka case study Banka on GitHub

Designed and directed by John Madrid, built with AI coding assistance (for example, Codex).

FIG_04 · The direction reverses

08 · Built to outlast the tool

Let tools evolve. Keep the project intelligible.

Readable contracts and recorded state are designed to give whatever tool comes next something coherent to inherit.

Models, runtimes, and IDEs will continue to shift. The project’s purpose, decisions, and boundaries should remain readable through those changes.

09 · Contact

Have a process that depends too much on memory, workarounds, or one person?

Available for full-time, contract, or part-time work. Remote PH/APAC or US/EU hours.

Book a call

Try it on one small job