Joint-operations Artificial Intelligence Behavioral Architecture
A framework for AI agent-assisted software development, designed to keep the human always in the loop.
- π¦ JAIBA
- π Getting Started
- Installation modes
- Pluggable memory surfaces architecture
- Uninstalling JAIBA from a machine
- What is JAIBA?
- System architecture
- π§ Routing: one chain, two lanes
- π§ Memory structure: the agent's brain
- βοΈ Skills: the workflows
- πΌ
conductβ the SDD chain - β‘
fastβ implicit inline lane - π¬
askβ implicit read-only lane - π§°
jaiba-configureβ machine setup - ποΈ
jaiba-initβ repo bootstrap and brain maintenance - π§
create-memoryβ memory-surface generator - π©Ί
jaiba-doctor - π§©
jaiba-engram-memoryβ optional Engram adapter
- πΌ
- π€ The subagent battery
- Typical workflow
- Design philosophy
- Usage examples
- Migrating from the pre-conduct layout
- Glossary
Adoption happens in two independent runs, because setup itself is split in two: one skill sets up your machine, another instruments each repository.
Install the machine-setup skill, then run it:
npx skills add atlasfoo/jaiba-framework#v3.5.0 --skill jaiba-configure -gThe release-tag suffix pins the install to that git tag β the tag is the framework's version, and jaiba-configure/commitizen keep it in lockstep on every release.
/jaiba-configure
Or simply: "configure jaiba on this machine"
jaiba-configure owns three core setup responsibilities; skill destinations may be explicitly global or project-local, and it never changes a project's brain or bindings:
- Installs the global JAIBA Behavioral Contract (
jaiba-contract.md) into your agent's user-level config - Installs the workflow/meta skillset (
conduct,ask,fast,jaiba-init,create-knowledge,create-memory,jaiba-doctorβ seven core skills, exactly whatassets/skillset.txtlists) globally β or project-locally, if you want one project's versions pinned - Installs the subagent battery (executors + specialists) into your agent's global
agents/folder
As a separate, explicitly chosen extra β never part of the core install β jaiba-configure can also offer the optional first-party jaiba-engram-memory adapter (see Memory surfaces). Declining it is a successful core-only setup.
It is safe to re-run: that is how a machine gets refreshed after a framework upgrade. Anything already present but different is a question, never a silent overwrite.
Prefer to install the skillset yourself? This still works, and jaiba-configure will simply report everything as already current:
npx skills add -y atlasfoo/jaiba-framework#v3.5.0 -gBenefits of the global skillset:
- Skills are available instantly in any project without per-project setup
- Consistent behavior across all your projects
- Automatic updates apply to all projects
- Reduced repository clutter (no
.agents/folder needed per project)
Navigate to the root of the project you want to adopt and run:
/jaiba-init
Or simply: "set up jaiba in this project" or "bootstrap jaiba"
jaiba-init instruments that one repo, end to end:
- Creates the
.ai/brain skeleton (memory/+memory/log/,work/,vendored/) and its.gitignore, plus the gitignored.atl/for machine-local state - Drops the minimal
AGENTS.mdmarker at the repo root (offering replace / coexist if you already have one) - Checks that the global contract and subagent battery exist β and only checks: if they're missing it names
jaiba-configure, it never installs them itself - Continues into its own
update-braininitialize mode to populate the long-term memory β an internal mode switch, not a hand-off to another skill - Hands off to
jaiba-doctorfor the first health check and toolchain probe (.atl/tool-layout.md)
Run it once per repository. On an already-instrumented repo it resumes or routes instead of bootstrapping.
If you prefer JAIBA's skills scoped to individual projects rather than to your machine (not recommended), answer project-local when jaiba-configure asks where the missing skills should go; only jaiba-configure itself needs to stay global. Step 2 is unchanged either way β jaiba-init is always repo-scoped.
Skills are installed globally using npx skills add and are available across all your projects:
| Aspect | Global |
|---|---|
| Command | npx skills add -y atlasfoo/jaiba-framework#v3.5.0 --skill <skill-name> |
| Location | ~/.agents/skills/ (user home directory) |
| Availability | All projects automatically have access |
| Setup per project | Only instrument the repo with /jaiba-init |
| Disk footprint | Minimal β skills are stored once |
| Updates | npx skills update applies to all projects |
| Recommended for | Teams, multi-project workflows, clean repositories |
How it works:
- Run
/jaiba-configureonce β contract, skillset and subagents land in your agent's global config - In each project, run
/jaiba-initto instrument the repo (AGENTS.mdmarker +.ai/brain +.atl/) - All skills automatically activate in every project you work on
Skills are installed locally in each project under .agents/ or .claude/skills/:
| Aspect | Project-scoped |
|---|---|
| Command | jaiba-configure installs the missing skills locally when you choose project-local |
| Location | .agents/ or project skill folder |
| Availability | Only in that specific project |
| Setup per project | A jaiba-configure run per project, plus the jaiba-init run |
| Disk footprint | Each project has its own copy of skills |
| Updates | Must re-run jaiba-configure, or update manually, per project |
| Recommended for | Legacy setups, isolated environments |
JAIBA provides a pluggable memory-surface layer with a strict three-tier separation of concerns:
- Canonical logical contract (
jaiba-memory-surface/1.1.0): Defines canonical memory invariants, concept categories (constitutive vs executive), core operations (catalogue,get,put,append-log,archive-context,clear-work), and additive 1.1 operations (patch,compact, and theexecutive-journalcapability), with schema validation across both bundle and legacy flat layouts. Owned byskills/create-memory/references/memory-surface-contract.md. - Storage-nature profile (
references/storage-nature.md): Characterizes empirical backend guarantees through a finite native experiment (persistence, single-writer serialization, operating thresholds, absent capabilities like native CAS, and error boundaries) and classifies the backend into one of two storage-nature archetypes:document-tree: The backend represents each logical object as an editable document (e.g. built-infilesystem). Realizespatchas in-place document edits without delta chains or context heads;compactwith no deltas is a no-op success.record-store: The backend stores discrete records or observations (e.g.jaiba-engram-memory). Realizesexecutive-journalvia an explicit base (exec-baseatseq: 0), ordered journal deltas (exec-deltaatseq: 1, 2, ...), and a context head (context-head).
- Physical adapter protocol: Derived concrete serialization and wire mapping matching backend guarantees (e.g.,
jaiba-engram-storage/4/JAIBA4single-observation envelope for Engram,posix-file/1one-file-per-object for file vaults, or the directory tree forfilesystem).
The framework distributes this layer as two skills, split core vs optional exactly as defined in the configure manifest (skills/jaiba-configure/assets/skillset.txt): seven core skills plus one optional package. The install examples below are pinned to the packaged release; each package must actually be present at that release tag:
| Skill | Status | What it is |
|---|---|---|
create-memory |
Core β installed with the workflow/meta skillset | The memory-surface generator: it builds a memory-surface skill for a user-selected backend from the canonical jaiba-memory-surface contract 1.1.0 β and ships that canonical contract plus its resolution.md, storage-nature.md, executive-journal.md, and filesystem-surface.md, which jaiba-configure, jaiba-init and jaiba-doctor resolve surface semantics from. Requires only git: no MCP tool, no backend service, no automatic installation, and no change to any consumer or binding. |
jaiba-engram-memory |
Optional β deliberately kept out of the core skillset | The first-party Engram adapter (Engram MCP). Its own operations require mcp:engram, which affects only this adapter. Implements contract 1.1.0, archetype record-store, and protocol JAIBA4 (jaiba-engram-storage/4). Conformance is verified on finite trial evidence (efc16e3a-3764-4ae6-9454-4d9fd8bc7ac0); selecting it is strictly opt-in and requires an explicit binding, and installing it changes no consumer or active binding. |
jaiba-configure offers jaiba-engram-memory only after core setup, only as an explicit choice (decline / inspect the existing copy / install for inspection), pinned to the same release as everything else and using the same documented per-skill pattern β no new CLI syntax:
npx skills add atlasfoo/jaiba-framework#v3.5.0 --skill jaiba-engram-memoryAdd -g for a global install, or choose project-local for one repository. Declining is a successful core-only configuration: no optional adapter installed β and no Engram MCP available β is normal core setup, never a core failure. Repositories stay on the built-in filesystem surface by default.
-
Step 0 Binding-First discovery and portable binding
v2: JAIBA checks~/.jaiba/memory/bindings/<sha256(canonical-work-root)>.yamlbefore testing for.ai/or assuming filesystem. A valid bindingv2record governs unlessAGENTS.mdcarries an explicitjaiba-memory-surface:override. When external, identity is$O(1)$ fromproject.project-idandexecutive.context-idwithout touching.ai/. -
Selection precedence: explicit project
AGENTS.mddata field (jaiba-memory-surface: filesystem, or an exact adapter ID) β host-visible installed project-local adapter β host-visible installed global adapter β built-in filesystem. Multiple different candidates at the winning level require an explicit human choice; there is no silent fallback to a lower level, to another project, or to a new empty brain. -
The filesystem default is unchanged: it preserves both supported
.ai/memory/layouts β concept bundle and legacy flat β exactly as described in Memory structure. -
Traceless mode (zero files in repo): On an external memory surface, a valid binding plus a real, complete, readable constitutive catalogue is the instrumentation.
AGENTS.mdand.ai/are completely omitted β zero files are written to or tracked in the repository. Local toolchain metadata (.atl/) is kept out ofgit statusby registering.atl/in.git/info/exclude(viagit rev-parse --git-path info/exclude), leaving the worktree pristine. JAIBA creates no hidden.ai/mirror or cache for external surfaces. -
Executive journal (
$O(\delta)$ mutations viapatch): Underjaiba-memory-surface/1.1.0, iterative SDD drafting, plan approval, task execution waves, and criteria validation emit surgicalpatchoperations (replace-section,append-section,append-to-section,set-frontmatter,add-criterion,update-criterion,remove-criterion,check,set-criterion-status) proportional to the change delta$O(\delta)$ , avoiding quadratic write amplification. At plan approval, criterion ID permanence is enforced (refusingremove-criterion). Journal compaction (compact) collapses deltas into anexec-baseatseq: 0. Package scripts implement operations using pure Python 3 standard library with zero pip dependencies, declared in one of three transport modes:local-cli,local-http, oragent-relay. -
Reference adapter protocol
JAIBA4(jaiba-engram-storage/4): The first-partyjaiba-engram-memoryadapter realizes therecord-storearchetype using protocolJAIBA4. LegacyJAIBA3stores remain strictly read-only (decode accepts legacy records without relabeling, while mutations fail closed). Migration fromJAIBA3toJAIBA4converts monolithic executive objects intoexec-baseatseq: 0and writes initialcontext-headslots losslessly. -
Issue #17 onboarding & migration enhancements:
-
Single cutover gate (
MSV-011): Migration cutover (jaiba-init:migrate-surface) presents a single questionnaire with two distinct decisions: an activation decision (switching active authority and updating bindingv2) and a retirement decision (separate consent for retiring source memory), preventing split-brain or accidental data loss. -
C0 (
MSV-013): Grouped concept verification pass before catalogue/index publication, guaranteeing integrity while eliminating roundtrip latency. -
C1 & C5βC6 (
MSV-014): Full vs minimal initial inventory choice, coupled with external adapter cost disclosures (estimated storage and token usage) and reminders of the zero-cost filesystem default. -
C2 (
MSV-016): Contractless downstream consumers are consolidated into a single reference concept (references/downstream-consumers.md,role: downstream,resource: [MISSING]) instead of speculative empty stubs. -
C3 (
MSV-014): Single onboarding questionnaire of at most 4 questions (adapter, namespace, project/context, inventory depth) asked in one turn. -
C4 (
MSV-015): Automatic suggestion of default namespace from existing sibling bindings (matching host/group or shared parent directory).
-
Single cutover gate (
-
Verified migration and limits: Surface migration (
jaiba-init:migrate-surface) was verified lossless across multi-hop trials (filesystem β EngramJAIBA3/JAIBA4β external vaultposix-file/1under trial6c90b698-39ba-441e-9c63-35ba9f9055c3). Operational limits and constraints verified:- Single-catalogue observation per
(namespace, project)avoids full-text search dependency; in-session retrieval uses deterministic rendering (MSV-008). - Direct payload objects
β€ 30,000raw bytes and chunked objects> 30,000raw bytes maintain exact byte round-trips. - Native CAS is absent (
absent / not-assumed); application single-writer serialization is mandatory. - MCP
judgment_requirednotifications are treated as advisory metadata without calling judgment tools or blocking execution. - Fail-closed guards: corrupt chunks trigger
digest-mismatchwithout writing, and symlink traversals triggersymlink-rootrejection before modifying storage.
- Single-catalogue observation per
To remove JAIBA from your machine, undo what jaiba-configure installed. Per-repository instrumentation (.ai/, .atl/, AGENTS.md) is separate and optional β this section covers machine-level uninstall only.
Delete jaiba-contract.md from your agent's global config folder:
~/.claude/jaiba-contract.md(Claude Code)~/.agents/jaiba-contract.md(neutral default)~/.cursor/jaiba-contract.md(Cursor)- Or equivalent for your agent vendor
Remove each skill using the skills CLI:
npx skills remove conduct -g
npx skills remove ask -g
npx skills remove fast -g
npx skills remove jaiba-init -g
npx skills remove create-knowledge -g
npx skills remove create-memory -g
npx skills remove jaiba-doctor -gIf you additionally chose the optional Engram adapter, remove it too:
npx skills remove jaiba-engram-memory -gOr delete the skill folders directly from your agent's global config (e.g. ~/.claude/skills/, ~/.agents/skills/).
Delete the following files from your agent's global agents/ folder:
executor-high.mdexecutor-medium.mdexecutor-low.mdcode-analyst.mdbusiness-analyst.mdverify.md
For example, if using Claude Code, delete these files from ~/.claude/agents/.
Open your agent's global instructions file (e.g. ~/.claude/CLAUDE.md, ~/.agents/CLAUDE.md) and locate the line jaiba-configure added:
See jaiba-contract.md for the global JAIBA behavioral contract.
Remove that single line, leaving the rest of your own instructions intact.
This uninstall removes only what jaiba-configure touched on your machine. If you want to remove JAIBA instrumentation from a specific repository, delete:
.ai/β the agent brain (memory, work, vendored).atl/β the machine-local toolchain layerAGENTS.mdβ the repository marker
These are optional; delete them per-project only if you want to fully decouple that repository from JAIBA.
JAIBA is an agile development framework designed for teams that work with AI agents as co-pilots in building software. It is not a tool, an AI model, or a collection of loose prompts: it is a behavioral architecture that defines how to organize context, how to orchestrate workflows, and how to keep the human as the central decision-maker at every significant stage of development.
JAIBA starts from a simple premise: the code is the context, and the agent must understand the project the way a senior developer who has been working on it for weeks would.
| Principle | Description |
|---|---|
| π§ Code as context | The agent works on the real foundation of the project: architecture, decisions, dependencies, and conventions living in the repository. Context is not improvised β it is built and maintained. |
| π€ Human in the loop | No significant change happens without human validation. The agent proposes, reasons, and executes bounded tasks; the developer approves, redirects, and decides. |
| π Continuous learning | The system is designed to capture knowledge: every architectural decision, every integration, every relevant change is recorded to feed future cycles. |
| π± Greenfield and brownfield | JAIBA works on brand-new projects and on existing legacy systems. The brain-building process allows the agent to adapt to any codebase. |
JAIBA organizes its operation in three layers: the memory structure (the agent's brain), the skills library (the executable workflows), and the subagent battery (delegated execution).
~/.claude/ (or your agent's global config)
βββ jaiba-contract.md β Global behavioral contract (one per machine)
βββ skills/ β JAIBA skills, installed globally
βββ agents/ β Subagent battery: executor-high/-medium/-low,
code-analyst, business-analyst, verify
project/
βββ AGENTS.md β Minimal marker: points at the global contract
βββ .ai/ β Agent brain
β βββ memory/ β Constitutive memory (versioned)
β β βββ index.md β Bundle entry point (current default β see below)
β β βββ identity/ β project, architecture, purpose, scope, quality-gate, conventions
β β βββ decisions/ β one file per ADR: <NNN>-<slug>.md
β β βββ references/ β one file per external surface: <slug>.md
β β β (legacy flat: constitution.md / adr-log.md / reference-index.md β still supported, no index.md)
β β βββ log/ β Append-only: closed work + brain changelog
β β βββ YYYY-MM-DD-slug.md
β βββ work/ β Executive memory (gitignored)
β β βββ PRD.md β Only when triage demands spec depth
β β βββ plan.md β Active design
β β βββ tasks.md β T-NNN task graph (depends-on, load)
β β βββ walkthrough.md β Change-by-change narrative
β βββ vendored/ β Local copies of external references
βββ .atl/ β Toolchain layer (gitignored)
β βββ tool-layout.md β Machine probe written by jaiba-doctor
βββ src/ ... β Your project
Since the conduct unification, the developer does not choose between commands. The global contract defines a routing rule the agent applies to every message:
| Your message is⦠| The framework routes to |
|---|---|
| A continuation cue with active work ("continue", "next", "go") | conduct, phase execute |
| A question (code, active work, past decisions) | ask β read-only |
| A small contained change ("quick fix", "bump X") | fast β inline lane |
| New work to shape or plan | the conduct chain (entry phase per triage) |
ask and fast are implicit-only: they have no slash commands. conduct keeps /conduct [phase] as a deterministic override for when routing misfires or you want to force a phase. The meta-skills (/jaiba-configure, /jaiba-init, /jaiba-doctor) remain explicit.
A single triage (shared by the chain and fast) maps each change's blast radius to a depth on the continuum inline β design β spec: an atomic edit executes on the spot; a bounded change gets a plan; a multi-faceted requirement gets a PRD and a plan. A critical-library bump or a performance fix does not produce a PRD β depth follows blast radius, not ceremony.
The .ai/ folder is the core of JAIBA. Memory collapses into two categories:
- Constitutive β who the project is: identity, decisions, external surfaces. Stable, versioned, in
.ai/memory/. - Executive β what is being done right now: PRD (if any), plan, tasks, walkthrough. Ephemeral per piece of work, gitignored, in
.ai/work/.
Behavior does not live per-repo anymore. jaiba-configure installs the JAIBA Behavioral Contract (jaiba-contract.md) once per machine into the agent's global config: the brain map, the numbered behavioral rules, the routing rule, security and toolchain discipline. Each repo keeps only a minimal AGENTS.md marker β dropped by jaiba-init β that confirms instrumentation and defers to the global contract for behavior and to the constitution for project facts. The split is the same one that separates the two setup skills: jaiba-configure owns the machine half, jaiba-init the repo half.
jaiba-doctor checks the contract's presence and drift against the packaged version on every health check.
.ai/memory/ comes in two supported layouts β a repo holds one or
the other, resolved by whether index.md exists (both existing at once
is treated as ambiguous and surfaced to the human, never silently
picked). Neither is a fallback: the flat layout is a fully supported,
warning-free state, not drift toward the bundle. Converting one to the
other is optional and human-triggered (jaiba-init:update-brain:migrate)
β it is never offered unprompted.
What jaiba-init:update-brain:initialize builds today: one file per
concept, of a closed type: (project, architecture, purpose,
scope, sub-unit, quality-gate, convention, decision,
reference, snippet, log-entry, plus the index type below), all
reachable in one hop from .ai/memory/index.md. Relations are
file-relative markdown links, never section-number citations. The
closed vocabulary and per-type frontmatter live in
jaiba-init/references/okf-pattern.md.
index.mdβ the bundle's only entry point: one link and one line (each concept'sdescription:) per concept, grouped bytype:.identity/βproject.md,architecture.md,purpose.md,scope.md,quality-gate.md,conventions.md, andunits/<slug>.mdfor monorepos / multi-project solutions.decisions/<NNN>-<slug>.mdβ one file per Architecture Decision Record. Superseded decisions stay in place, flipped tostatus: supersededwith asuperseded-by:link β never deleted, never renumbered.references/<slug>.mdβ one file per external surface (APIs, packages, services) or internal cross-component contract (event schemas, APIs between sub-units), carryingtier,kind,roleand its consultation point; when vendored, the local copy path.
Projects instrumented before the concept bundle, or that simply haven't converted, keep three files instead β same content, one file each:
constitution.mdβ the project's executive summary: what the system does and for whom, stack and architecture, team conventions, sub-unit scopes, and the Quality Gate.adr-log.mdβ the curated decision memory: ADRs currently in force. Superseded entries are marked, never deleted.reference-index.mdβ the index of external surfaces and internal cross-component contracts, one entry each.
The chronological memory: an append-only record fusing closed work and the brain's changelog, one dated file per entry (YYYY-MM-DD-slug.md, kinds work-closure and brain-change). Where the decision concepts (or adr-log.md in the legacy flat layout) answer "what do we hold true today", log/ answers "what happened, in order" β identical in both layouts. Written by conduct:summarize (work closures) and jaiba-init:update-brain (brain changes) β the framework's one sanctioned carve-out to the "only jaiba-init:update-brain writes memory" rule.
The active piece of work, gitignored (multi-session; plan phases are the checkpoints):
| File | Produced by | Purpose |
|---|---|---|
PRD.md |
spec phase (only at spec depth) |
The what/why: business problem + acceptance criteria <PREFIX>-NNN in Given/When/Then happy/sad, serialized as a parseable schema the verify subagent consumes. |
plan.md |
spec phase (design) |
The approved design: objective, scope, technical approach, amendments. |
tasks.md |
tasks phase |
The work graph: tasks with IDs T-NNN, depends-on, cognitive load (high/medium/low), and covered criteria β the input for parallel execution waves. |
walkthrough.md |
execute phase |
Change-by-change narrative: what, why, deviations, ADR candidates. |
When the work closes, conduct:summarize distills the essence into .ai/memory/log/ and cleans work/ β in a single, human-confirmed step.
Not a memory category, but a store backing the reference concepts (or reference-index.md in the legacy flat layout). When an external reference can't (or shouldn't) be fetched live β an OpenAPI contract, a Repomix bundle of a dependency β a copy lives here and the reference's resource: (or index entry) points at it. Versioned alongside the code; jaiba-doctor warns when a vendored copy goes stale (older than a month by git date).
The unified workflow (it absorbed the former planning and specification skills). One chain of Spec Driven Development phases; the triage decides how deep each change enters:
| Phase | Artifact | What happens |
|---|---|---|
propose (optional) |
β (conversational) | Shape a fuzzy requirement: questions, ambiguities, scope. Persists nothing; flows into spec. |
spec |
PRD.md (spec depth only) + plan.md (always) |
Define: PRD with numbered, parseable acceptance criteria β only when triage demands it. Design: the plan. Ends at explicit human approval of the design. |
tasks |
tasks.md |
Decompose the design into a task graph: T-NNN, depends-on, load, covered criteria. Phases act as multi-session checkpoints with their own gate. |
execute (implicit) |
walkthrough.md |
Advance the work through load-matched executor task waves when callable; inline work requires a named dispatch blocker. Triggered by continuation cues; no command needed. |
validate |
β | Run the plan's quality gate and dispatch verify for PRD criteria or approved design scope when callable, reporting met / not met / not verifiable with evidence. |
summarize |
log entry in .ai/memory/log/ |
Single closing step: present the final summary, propose ADRs/constitution changes for jaiba-init:update-brain, archive the essence, clean work/ β one confirmation. |
Golden rules: the human approves the design before anything executes; execution pauses at phase boundaries; the plan never silently drifts β structural deviations amend
plan.mdexplicitly.
Direct execution for small, well-scoped, low-risk changes β the sanctioned exception to "no blind coding". Not user-invocable: the routing rule triggers it on "quick fix" / "bump X" / "rename this" style requests.
- Shares conduct's triage with default and floor
inline: if the change triagesdesignor deeper,fastrefuses and routes into the chain. - Free-standing: delegates the code diff to a callable executor (inline fallback after alert if none is callable), writes nothing to
.ai/work/; git history plus a one-line recap is the record. - Plan adjustment: with an active plan, a change outside the current tasks routes here even if the message does not say
fast. Delegates the out-of-band change to a callable executor and β after developer confirmation β records it into the plan artifacts (fastremains the only writer of that amendment). - Big out-of-band change during an active plan: surfaces it and offers exactly two exits β fold it in as a new plan phase, or park-and-replan. Never builds a second plan silently.
Pure query mode, triggered by interrogative messages (including a side question the agent receives, such as /btw). Strictly read-only: dispatches researcher when callable (with no model: pin; inline fallback after alert if unavailable), reads, searches, explains; never edits code, never writes artifacts.
- Answers cold β orients from the repository, so questions about the active work (
.ai/work/) or past decisions (.ai/memory/) work on a session's first message. - Four domains: code, active plan, active PRD, decisions (
decisionconcepts, oradr-log.mdin the legacy flat layout, plusmemory/log/). - Hands off to action: a continuation cue routes to
conduct:execute; new work enters the chain; a contained change goes tofastβ carrying the context it already gathered.
The machine half of setup, and nothing else: the global behavioral contract, the workflow/meta skillset, the subagent battery. It never touches a repository β no .ai/, no .atl/, no AGENTS.md β and carries no brain templates at all. Run from anywhere, once per machine, and safe to re-run as the upgrade path: every divergence from the packaged version is a question, never a silent overwrite. It names jaiba-init as the next step for a specific project, but never invokes it.
The repo half of setup, and the framework's long-term memory owner. Two modes:
- Bootstrap (bare
jaiba-init) β instrument this repository: theAGENTS.mdmarker, the.ai/skeleton and.atl/, then the constitutive memory, then the firstjaiba-doctorcheckup. It checks for the global contract and battery and routes tojaiba-configureif they're absent; it never installs them. - Maintain (
jaiba-init:update-brain) β the constitutive-memory workflow, and the only skill that writes.ai/memory/(log appends excepted). Itsinitializesub-mode builds the brain from repository analysis (essential for brownfield onboarding), producing the concept bundle by default;updateapplies proposed decisions, references and identity changes (bundle) or ADRs, reference-index entries and constitution changes (legacy flat), or reconciles the brain after structural drift;migrateconverts an existing flat brain to the bundle, human-triggered only. Every brain change leaves abrain-changeentry inmemory/log/.
Bootstrap ends inside initialize: laying the skeleton and filling the brain are two modes of the same skill, so there is no hand-off between them β jaiba-init owns the templates and the initialize logic outright.
The core memory-surface meta-skill, part of the pinned skillset: it interviews the requirements, discovers the tool schemas the current host actually has, and generates a declarative memory-surface skill β mappings, configuration, evals β for a user-selected backend, then verifies conformance against the canonical jaiba-memory-surface contract 1.1.0 and offers an explicit local or global install of the generated package. It owns and ships the canonical contract the rest of the framework resolves, requires only git, installs no service and activates no backend; a generated adapter is a user-chosen extension, never an automatic addition to JAIBA's first-party distribution.
The framework health check β a pre-flight before entering the conduct chain. Diagnoses and routes; never repairs. Three diagnostics, one severity-ordered report:
| Diagnostic | What it checks | Where the fix routes |
|---|---|---|
| Memory coherence | Behavioral contract present and drift-free (repo marker + global copy vs packaged version); resolves the .ai/memory/ layout first (concept bundle vs legacy flat, per the dual-resolution rule) and checks it β bundle graph integrity (no broken links, every concept carries type:) or the three flat files β complete, mutually consistent, and not drifting from the repo; curated-vs-chronological separation intact. |
jaiba-init (brain, repo marker) / jaiba-configure (global contract) |
| Tool state | Are the CLI tools that installed skills, subagents, and hooks declare (requires:) actually present? Refreshes .atl/tool-layout.md with provenance. |
install the tool |
| External-reference health | Every reference concept (or reference-index.md entry, legacy flat) reachable: MCP/CLI installed, remote spec live, vendored copy present and fresh. |
install Β· fix endpoint Β· re-vendor via jaiba-init:update-brain |
The first-party memory-surface adapter for the Engram MCP β developed in the same source stage but outside the core skillset: jaiba-configure offers it after core setup as a separate, explicitly chosen install pinned to the packaged release β reported unavailable if absent at that pin, never fetched unpinned (Memory surfaces). It declares category: memory-surface with verified conformance (on bounded trial evidence efc16e3a-3764-4ae6-9454-4d9fd8bc7ac0) and a mcp:engram requirement scoped to itself alone; selecting or operating it requires explicit configuration, and installing it changes no consumer, binding or workflow. Consult it only when explicitly reviewing, validating or operating the selected surface.
jaiba-configure installs seven native subagent definitions into the agent's global agents/ folder. Conduct, ask, and fast must dispatch applicable roles when the host permits it, the roles are runtime-callable, and prerequisites are verified. The invocation contract (conduct/references/subagents.md) governs runtime and toolchain checks, concurrency, and fallback accounting. An exposed role is runtime evidence; doctor's detected files alone do not prove invocation support. Authorized first-party role calls need no separate approval.
| Subagent | Role | Used in phase / lane |
|---|---|---|
executor-high |
Design-heavy, multi-file tasks (load: high) |
execute, fast |
executor-medium |
Bounded implementation tasks (load: medium) |
execute, fast |
executor-low |
Mechanical, repetitive tasks (load: low) |
execute, fast |
code-analyst |
Code survey without loading conduct's context | spec (both depths), propose when code facts are needed |
business-analyst |
Contrasts the requirement against the identity/decision/reference concepts (or constitution / adr-log / reference-index, legacy flat) | propose, spec |
verify |
Checks PRD criteria or approved design scope; reports met / not met / not verifiable with evidence | validate (both depths) |
researcher |
Read-only codebase, memory, and artifact investigation without a model pin | ask |
Parallelism: independent read-only business and code analyses launch before either is awaited, within host capacity; current reports can be reused. execute launches file-disjoint tasks in waves from the depends-on graph, capped at min(3, available host child slots). A single task still uses its executor; overlapping tasks serialize through executors. Each invocation names file ownership and concurrent workers. Conduct alone writes .ai/work/ and reintegrates results before the next wave.
Fallback: name and record a concrete blocker per role/task: no spawn support, inaccessible role, explicit host/user restriction, missing/unverified prerequisites, or an actual dispatch error. Review child state and partial writes before retrying or safe inline work. Continue delegating unaffected roles; convenience never justifies fallback. Verification retains the Plan gate and command provenance safeguards at both depths.
ββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββ
β Your machine (once) β β New or legacy project β
βββββββββββββββ¬βββββββββββββββ ββββββββββββββββ¬βββββββββββββββ
β β
/jaiba-configure /jaiba-init
(contract + skillset + subagents) (AGENTS.md marker + .ai/ + .atl/)
β β
β independent: neither β
β invokes the other; init βΌ
βββ only *checks* for it ββΆ update-brain:initialize
β (internal mode switch)
βΌ
jaiba-doctor
(first checkup + probe)
β
ββββββββββββββββββ
β
ββββββββββββββββΌβββββββββββββββ
β Brain ready β
ββββββββββββββββ¬βββββββββββββββ
β
ββ routing rule per message ββ
β
ββββββββββββββββ¬ββββββββββββ΄βββββββββββ¬ββββββββββββββββββ
β β β β
New work Continuation Question Small change
β β β β
conduct conduct: ask (read- fast (inline;
chain: propose? β execute only lane) refuses > inline
spec (PRD? + plan (waves of and routes into
β approval) β subagents) the chain)
tasks β execute β
validate β summarize
β
ββββ .ai/memory/log/ entry + proposed ADRs β jaiba-init:update-brain
β
ββββββΌβββββ
β repeat β
βββββββββββ
JAIBA does not seek to automate development. It seeks to amplify the developer's capacity while maintaining human authorship over the decisions that matter. The agent is an extraordinarily productive collaborator that needs direction, context, and validation.
The source code and the .ai/ files are equally part of the project. The agent's memory is not a temporary file or a throwaway prompt: it is a team artifact that lives in the repository, evolves with the project, and is readable by any human collaborator.
Each skill defines clear expectations for both the agent and the human. Knowing which phase conduct is operating in eliminates ambiguity and reduces errors from context misunderstandings.
The following examples are based on TripNest, a travel planning application built with Python and Django.
π€ "I want users to be able to create itineraries and share them with other people so they can edit them together."
The routing rule reads this as new work; the triage scores a cross-cutting blast radius β spec depth. The chain enters at propose: the agent dispatches a memory contrast to business-analyst when callable and asks the narrowing questions β real-time or asynchronous editing? roles? conflict policy?
In spec, it drafts .ai/work/PRD.md with numbered, parseable criteria:
## Acceptance criteria
β```yaml
criteria:
- id: COL-001
kind: happy
given: an itinerary owner with a collaborator's email
when: they send an invitation
then: the collaborator receives edit access with the assigned role
- id: COL-002
kind: sad
given: a reader-role collaborator
when: they attempt to modify an activity
then: the change is rejected and the UI explains the missing permission
β```β¦then the design (plan.md). The human approves the design; tasks produces the graph (T-001 β¦ T-014, each with depends-on, load, and covers: pointing at criteria IDs).
π€ "continue"
Routing: continuation cue β conduct:execute. Conduct checks .atl/tool-layout.md against each subagent's requires:, builds the first wave from the depends-on graph, and fans out: T-003 (model, load: high) to executor-high, T-004 (serializer, load: medium) to executor-medium β in parallel, because they share no files. Each executor returns a diff + report; conduct reviews, logs the walkthrough entry, flips the checkboxes, and runs the phase gate before the next wave.
At the end, validate hands the PRD's criteria schema to verify, which reports per criterion:
COL-001 β
met β invitation flow test green (test_invite_by_email)
COL-002 β
met β permission rejection covered (test_reader_cannot_edit)
COL-003 β not met β change history endpoint returns 404; T-012 unchecked
summarize then closes in one step: final summary presented, 2026-07-05-collaborative-itineraries.md appended to .ai/memory/log/, an ADR proposed (object permissions via django-guardian) for jaiba-init:update-brain, and work/ cleaned β after one confirmation.
π€ "We have an N+1 problem in the itinerary list view. We need to optimize the queries."
New work, but the triage scores it design depth β bounded blast radius, no business dimension. No PRD is produced: the chain enters at spec's design half, writes a short plan.md (profiling phase + fix phase), gets approval, and executes. A performance fix never pays the ceremony of a spec.
(Had the developer instead said "bump requests to 2.32", the routing rule would have sent it to fast: triage inline, executed on the spot, no executive artifacts at all.)
Not to be confused with converting
.ai/memory/from the legacy flat layout to the concept bundle β that'sjaiba-init:update-brain:migrate, optional and human-triggered. This section covers an older, unrelated migration: off the pre-conductskillset entirely.
Projects instrumented before the conduct unification use planning/specification skills and an older brain layout. There is no automatic migration; the manual route:
.ai/session/β.ai/work/(rename; addwork/to.ai/.gitignore, removesession/from tracking if needed)..ai/memory/archive/plans/andarchive/specs/β.ai/memory/log/(move files; keep their dated names)..ai/specs/<name>/β fold any active spec's PRD into.ai/work/PRD.md(user stories become the PRD's criteria section); delivered specs go tomemory/log/.- Replace the full per-repo
AGENTS.mdwith the minimal marker (jaiba-initbootstrap step 3 offers replace/coexist) and runjaiba-configureto install the global contract (its step 2). - Uninstall the
planningandspecificationskills; installconduct. - Run
/jaiba-doctorβ it detects leftover old-layout directories and contract drift, and routes the remainder.
| Term | Definition |
|---|---|
| Brain | The set of files in .ai/ that make up the agent's persistent context |
| Constitutive memory | .ai/memory/: identity, decision and reference concepts reachable from index.md (or constitution / curated ADR log / reference index, legacy flat) plus the chronological log β who the project is |
| Concept bundle | The current-default .ai/memory/ layout: one file per constitutive concept, closed type: vocabulary, all reachable from index.md |
| Legacy flat layout | The pre-bundle .ai/memory/ layout β three files (constitution.md, adr-log.md, reference-index.md) plus log/. Still fully supported; converting to the bundle is optional and human-triggered |
| Executive memory | .ai/work/: PRD (if any), plan, tasks, walkthrough β what is being done right now (gitignored) |
| Behavioral contract | jaiba-contract.md, installed once per machine in the agent's global config; each repo keeps a minimal AGENTS.md marker pointing at it |
| Triage | The shared blast-radius β depth mapping (inline β design β spec) that decides how deep a change enters the chain |
| Chain | Conduct's SDD phases: propose β spec β tasks β execute β validate β summarize |
| Lane | An implicit, routing-triggered skill: ask (read-only) or fast (inline execution) |
| Wave | A set of file-disjoint tasks execute fans out to executor subagents in parallel (cap 3) |
| Skill | An executable workflow with defined phases/modes and human validation checkpoints |
| Subagent battery | The seven globally-installed agents: three executors by cognitive load + code-analyst, business-analyst, verify, researcher |
| Human in the loop | The principle that the human validates and approves before each significant stage |
JAIBA Β· Joint-operations Artificial Intelligence Behavioral Architecture π¦
AI-assisted development should not be black magic. It should be engineering.