John Madrid · Banka
Reliable context for AI-assisted development.
An architectural blueprint that gave projects structured memory: proportional context tiers, bounded skills, and durable state preservation across sessions.
Archived · release-2.0.3 · Superseded by Galleon
The Philippine bangka: an outrigger boat engineered for stability across open swells.
01 · The problem
Stateless sessions drift and forget.
Large Language Models are inherently stateless. Each coding session starts fresh, devoid of the hard-won architectural decisions, domain constraints, and subtle tradeoffs negotiated in previous sessions.
Without a structured, durable context harness, developers spend recurring session effort re-supplying the same explanations: which libraries are forbidden, how state flows, and where new files belong. As projects grow, ad-hoc prompts inevitably degrade, leading to hallucinations, broken invariants, and costly regressions.
SESSION TIMELINE WITHOUT DURABLE CONTEXT
Session 01 Greenfield build
└── Architecture decided in chat # ephemeral
Session 05 Feature expansion
├── Chat history expired
└── Agent hallucinates competing library # drift
Session 12 Refactoring
├── Context window exhausted
└── Core architectural invariants violated # failure
────────────────────────────────────────────────────
RESULT Continuous manual context reconstruction02 · Adoption and scope intake
Structure begins before code.
Banka did not allow immediate code generation. Stage 0 evaluated two mandatory adoption conditions before any files were created:
- Decision-ready scope: Purpose, target users, feature boundaries, and an explicit Definition of Done; producible through routes like the Adaptive Scope Mapping Protocol (ASMP), which Banka treats as optional, not a dependency.
- Readiness evidence: For existing projects, Docking verified that tests and builds were passing so Banka never adopted broken foundations.
Once verified, Stage 1 generated the project’s immutable origin record: IDEA-SCOPE.md. Banka validated this record with the Cold Agent Test: a simulated session with zero memory that proved an agent could read the document and immediately execute without human re-briefing.
STAGE 0: ADOPTION GATES
├── ① Decision-Ready Scope (ASMP or direct)
│ ├── Purpose & target users
│ ├── Feature boundaries & constraints
│ └── Checkable Definition of Done
└── ② Readiness Evidence (Docking)
├── Existing test suite passing
└── No uncommitted architectural debt
│
▼ Verified
STAGE 1: IMMUTABLE ORIGIN RECORD
└── IDEA-SCOPE.md
├── Fixed reference point for all sessions
└── Verified via Cold Agent Test03 · Proportional tiers
Structure sized to project complexity.
Banka rejected one-size-fits-all context setups. Under Schema 2, Banka resolved structure through a five-question complexity rubric rather than guessing at arbitrary thresholds. The rubric recommends; the user decides:
- Minimal Tier (0 yes): For scripts, single-purpose utilities, and lightweight tools. Keeps purpose, stack invariants, and session memory inline inside a single root
AGENTS.mdblock with aCLAUDE.mdimport shim. - Core Tier (1–2 yes, or borderline 3): For products needing architectural rules and progress tracking without nine-file overhead. Provides four dedicated files in
/core/:overview.md,architecture.md,design.md, andprogress.md. - Standard Tier (4–5 yes): For complex builds spanning multi-phase roadmaps, custom design systems, and third-party API patterns. Partitions context into nine specialized files in
/context/.
When a project grew past measured word-count thresholds (~4,000 words in Core), the /scale command promoted the structure upward while preserving all historical records.
MINIMAL TIER # 0 yes on rubric
├── AGENTS.md # Inline state & rules
└── CLAUDE.md # Import shim: @AGENTS.md
CORE TIER # 1–2 yes on rubric (or borderline 3)
├── AGENTS.md # Router pointing to /core/
├── CLAUDE.md # Import shim: @AGENTS.md
└── core/
├── overview.md # Purpose, users, data
├── architecture.md # Stack & invariants
├── design.md # UI tokens & registry
└── progress.md # Memory & milestones
STANDARD TIER # 4–5 yes on rubric
├── AGENTS.md # Router pointing to /context/
└── context/
├── project-overview.md ├── ui-tokens.md
├── architecture.md ├── ui-rules.md
├── build-plan.md ├── ui-registry.md
├── code-standards.md └── progress-tracker.md
└── library-docs.md04 · The build loop & skills kit
Nine bounded methods.
Banka installed a permanent kit of nine specialized skills on the developer’s machine. Each skill held a single verb, a strict boundary, and an explicit prohibition against overstepping its mandate.
| Skill | Role & Job | Explicit Boundary |
|---|---|---|
| charter | Senior planning & intent alignment | Implement code or bypass review |
| watershed | 5-perspective isolated architectural review | Force consensus or write files |
| delegate | Three-tier task splitting (Junior/Senior/Owner) | Execute implementation |
| survey | Plan alignment & production verification | Repair issues or invent approval |
| dredge | 4-mode build failure diagnosis | Apply automatic code patches |
| remember | Session state capture with bloat control | Permit unbounded state growth |
| scale | Tier promotion (Minimal → Core → Standard) | Overwrite records or lose overflow |
| moor | UI pattern & engineering outcome capture | Modify existing design tokens |
| linis | Milestone narrative cleanup and archiving | Discard unrecorded decisions |
The execution lifecycle
Every feature followed a disciplined cadence. Work was scoped in charter, critiqued through watershed, divided into clear ownership slices in delegate, verified against invariants in survey, and saved cleanly via remember.
If a failure occurred during execution, dredge activated in one of four diagnostic modes (Mode 0: Cannot reproduce; Mode 1: A specific thing is broken; Mode 2: The session has gone wrong; Mode 3: The foundation is wrong) to explain the breakdown without applying uninspected patches.
THE BANKA BUILD LOOP
┌─────────────────────────────────────────────────────────┐
│ 1. ALIGN /charter (Intent, constraints, tickets) │
│ /watershed (5-perspective isolated review) │
│ │
│ 2. DISPATCH /delegate (Junior / Senior / Owner split) │
│ │
│ 3. EXECUTE Targeted agent implementation │
│ │
│ 4. VERIFY /survey (Check against plan & tests) │
│ /dredge (Diagnose failure if broken) │
│ │
│ 5. PRESERVE /remember (Capture verified session state) │
│ /linis (Milestone cleanup & archive) │
└─────────────────────────────────────────────────────────┘05 · Durability & bloat prevention
Two tracks to prevent context decay.
Context files that grow without limits quickly overwhelm LLM attention windows, causing models to drop instructions and produce erratic code. Banka engineered a dual-track defense system:
- Track A (Write-time prevention): Enforced single-source ownership (one home per fact), bulleted atomic statements instead of conversational prose, and banned narrative logs inside active context files.
- Track B (Correction at thresholds): Implemented automated overflow mechanics. When decisions exceeded ~1,500 words or Core files exceeded ~4,000 words, settled history was archived into
overflow/directories.
Release 2.0.3 solved a critical durability flaw: scale now counts core/overflow/ toward the promotion threshold and migrates the directory intact when promoting to Standard, ensuring multi-month project history is never discarded.
DURABILITY ARCHITECTURE (v2.0.3)
Track A: Write-Time Invariants
├── Atomic bullet points # no narrative drift
├── Single-source authority # one home per fact
└── Cold Agent Test verified on resume
Track B: Overflow Sweeps & Thresholds
├── Decisions > 1,500 words ──> Move to overflow/decisions/
├── Core tier > 4,000 words ──> Trigger /scale promotion
└── Promotion gate (v2.0.3) ──> Migrate core/overflow/ intact
────────────────────────────────────────────────────────
DESIGN OUTCOME Active context stays lean; history stays preserved06 · The inversion
Why Galleon succeeded Banka.
Banka was a major milestone: nine skills, multi-tier templates, automated integrity gates, and verified bloat control. But evaluating Banka against Interpretable Context Methodology (ICM, Van Clief & McDermott 2026) revealed a foundational lesson:
Banka fitted the project to the tool’s shape. The framework assumed ownership of directory structures, skill invocations, and session protocols. If a developer did not have Banka installed, the repository’s conventions became opaque.
Galleon completely inverted this relationship. In Galleon, the project’s file architecture is the framework. The project defines its own contracts, boundaries, and routes. Skills are lightweight, portable visitors that inspect the project’s entry files first; designed so the project remains intelligible and self-governing if Galleon is removed.
A galleon carries cargo and manifests across voyages too long to return for what was forgotten. Galleon is named for what it does: help a project carry its own understanding from one session to the next.
BANKA (Tool-centric harness)
┌─────────────────────────────────────────────────────────────────┐
│ Banka Framework # owns workflow & structure │
│ ├── skills-kit/ # machine-installed dependencies │
│ └── full-context-templates/ │
│ └── Your Project # fitted into Banka schemas │
└─────────────────────────────────────────────────────────────────┘
GALLEON (Project-centric harness)
┌──────────────────────────────────────────────────────────────────┐
│ Your Project # owns meaning, routes & authority │
│ ├── AGENTS.md & CONTEXT.md # self-contained routers │
│ ├── work/ & design/ # project-defined records │
│ └── [Optional skills: read project first, obey rules] │
└──────────────────────────────────────────────────────────────────┘07 · Contact
Building reliable systems for AI engineering?
Available for full-time, contract, or part-time work. Remote PH/APAC or US/EU hours.
Book a call
Choose a 20-minute slot that works for you. The calendar below shows my current availability.
If the calendar does not load, open the booking page directly.