Skip to content

About

Joint AI behavioral architecture. Agentic AI for software development made right, effectively and productive, for problems at any scale

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

πŸ¦€ JAIBA

Joint-operations Artificial Intelligence Behavioral Architecture

A framework for AI agent-assisted software development, designed to keep the human always in the loop.


Framework Paradigm Human in the loop Greenfield


πŸš€ Getting Started

Adoption happens in two independent runs, because setup itself is split in two: one skill sets up your machine, another instruments each repository.

1. Configure your machine (once)

Install the machine-setup skill, then run it:

npx skills add atlasfoo/jaiba-framework#v3.5.0 --skill jaiba-configure -g

The 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 what assets/skillset.txt lists) 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 -g

Benefits 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)

2. Initialize JAIBA in your repository

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.md marker 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-brain initialize mode to populate the long-term memory β€” an internal mode switch, not a hand-off to another skill
  • Hands off to jaiba-doctor for 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.

Alternative: Project-scoped installation

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.


Installation modes

Global installation (Recommended βœ…)

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:

  1. Run /jaiba-configure once β€” contract, skillset and subagents land in your agent's global config
  2. In each project, run /jaiba-init to instrument the repo (AGENTS.md marker + .ai/ brain + .atl/)
  3. All skills automatically activate in every project you work on

Project-scoped installation (Legacy)

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

Pluggable memory surfaces architecture

JAIBA provides a pluggable memory-surface layer with a strict three-tier separation of concerns:

  1. 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 the executive-journal capability), with schema validation across both bundle and legacy flat layouts. Owned by skills/create-memory/references/memory-surface-contract.md.
  2. 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-in filesystem). Realizes patch as in-place document edits without delta chains or context heads; compact with no deltas is a no-op success.
    • record-store: The backend stores discrete records or observations (e.g. jaiba-engram-memory). Realizes executive-journal via an explicit base (exec-base at seq: 0), ordered journal deltas (exec-delta at seq: 1, 2, ...), and a context head (context-head).
  3. Physical adapter protocol: Derived concrete serialization and wire mapping matching backend guarantees (e.g., jaiba-engram-storage/4 / JAIBA4 single-observation envelope for Engram, posix-file/1 one-file-per-object for file vaults, or the directory tree for filesystem).

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.

Installing the optional adapter

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-memory

Add -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.

Selection, instrumentation and migration guarantees

  • Step 0 Binding-First discovery and portable binding v2: JAIBA checks ~/.jaiba/memory/bindings/<sha256(canonical-work-root)>.yaml before testing for .ai/ or assuming filesystem. A valid binding v2 record governs unless AGENTS.md carries an explicit jaiba-memory-surface: override. When external, identity is $O(1)$ from project.project-id and executive.context-id without touching .ai/.
  • Selection precedence: explicit project AGENTS.md data 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.md and .ai/ are completely omitted β€” zero files are written to or tracked in the repository. Local toolchain metadata (.atl/) is kept out of git status by registering .atl/ in .git/info/exclude (via git 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 via patch): Under jaiba-memory-surface/1.1.0, iterative SDD drafting, plan approval, task execution waves, and criteria validation emit surgical patch operations (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 (refusing remove-criterion). Journal compaction (compact) collapses deltas into an exec-base at seq: 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, or agent-relay.
  • Reference adapter protocol JAIBA4 (jaiba-engram-storage/4): The first-party jaiba-engram-memory adapter realizes the record-store archetype using protocol JAIBA4. Legacy JAIBA3 stores remain strictly read-only (decode accepts legacy records without relabeling, while mutations fail closed). Migration from JAIBA3 to JAIBA4 converts monolithic executive objects into exec-base at seq: 0 and writes initial context-head slots 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 binding v2) 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).
  • Verified migration and limits: Surface migration (jaiba-init:migrate-surface) was verified lossless across multi-hop trials (filesystem ↔ Engram JAIBA3/JAIBA4 ↔ external vault posix-file/1 under trial 6c90b698-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,000 raw bytes and chunked objects > 30,000 raw bytes maintain exact byte round-trips.
    • Native CAS is absent (absent / not-assumed); application single-writer serialization is mandatory.
    • MCP judgment_required notifications are treated as advisory metadata without calling judgment tools or blocking execution.
    • Fail-closed guards: corrupt chunks trigger digest-mismatch without writing, and symlink traversals trigger symlink-root rejection before modifying storage.

Uninstalling JAIBA from a machine

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.

1. Remove the global behavioral contract

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

2. Uninstall the workflow/meta skillset

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 -g

If you additionally chose the optional Engram adapter, remove it too:

npx skills remove jaiba-engram-memory -g

Or delete the skill folders directly from your agent's global config (e.g. ~/.claude/skills/, ~/.agents/skills/).

3. Remove the subagent battery

Delete the following files from your agent's global agents/ folder:

  • executor-high.md
  • executor-medium.md
  • executor-low.md
  • code-analyst.md
  • business-analyst.md
  • verify.md

For example, if using Claude Code, delete these files from ~/.claude/agents/.

4. Remove the contract reference from your global instructions

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.

Per-repository cleanup (optional)

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 layer
  • AGENTS.md β€” the repository marker

These are optional; delete them per-project only if you want to fully decouple that repository from JAIBA.


What is 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.

Core principles

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.

System architecture

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

🧭 Routing: one chain, two lanes

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.


🧠 Memory structure: the agent's brain

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/.

The behavioral contract: global + repo marker

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.

memory/ β€” Constitutive memory

.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.

Concept bundle (current default)

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's description:) per concept, grouped by type:.
  • identity/ β€” project.md, architecture.md, purpose.md, scope.md, quality-gate.md, conventions.md, and units/<slug>.md for monorepos / multi-project solutions.
  • decisions/<NNN>-<slug>.md β€” one file per Architecture Decision Record. Superseded decisions stay in place, flipped to status: superseded with a superseded-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), carrying tier, kind, role and its consultation point; when vendored, the local copy path.

Legacy flat layout (still supported)

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.

log/

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.

work/ β€” Executive memory

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.

vendored/ β€” Local copies of external references

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).


βš™οΈ Skills: the workflows

🎼 conduct β€” the SDD chain

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.md explicitly.

⚑ fast β€” implicit inline lane

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 triages design or deeper, fast refuses 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 (fast remains 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.

πŸ’¬ ask β€” implicit read-only lane

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 (decision concepts, or adr-log.md in the legacy flat layout, plus memory/log/).
  • Hands off to action: a continuation cue routes to conduct:execute; new work enters the chain; a contained change goes to fast β€” carrying the context it already gathered.

🧰 jaiba-configure β€” machine setup

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.

πŸ—οΈ jaiba-init β€” repo bootstrap and brain maintenance

The repo half of setup, and the framework's long-term memory owner. Two modes:

  • Bootstrap (bare jaiba-init) β€” instrument this repository: the AGENTS.md marker, the .ai/ skeleton and .atl/, then the constitutive memory, then the first jaiba-doctor checkup. It checks for the global contract and battery and routes to jaiba-configure if 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). Its initialize sub-mode builds the brain from repository analysis (essential for brownfield onboarding), producing the concept bundle by default; update applies proposed decisions, references and identity changes (bundle) or ADRs, reference-index entries and constitution changes (legacy flat), or reconciles the brain after structural drift; migrate converts an existing flat brain to the bundle, human-triggered only. Every brain change leaves a brain-change entry in memory/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.

🧠 create-memory β€” memory-surface generator

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.

🩺 jaiba-doctor

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

🧩 jaiba-engram-memory β€” optional Engram adapter

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.


πŸ€– The subagent battery

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.


Typical workflow

    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
    β”‚   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  β”‚
                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Design philosophy

The agent as co-pilot, not pilot

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.

Memory as a first-class citizen

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.

Workflows as contracts

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.


Usage examples

The following examples are based on TripNest, a travel planning application built with Python and Django.


Example 1 β€” Deep requirement (spec depth: PRD + plan)

πŸ‘€ "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).

Example 2 β€” Executing with subagent waves

πŸ‘€ "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.

Example 3 β€” Shallow change (design depth: plan only)

πŸ‘€ "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.)


Migrating from the pre-conduct layout

Not to be confused with converting .ai/memory/ from the legacy flat layout to the concept bundle β€” that's jaiba-init:update-brain:migrate, optional and human-triggered. This section covers an older, unrelated migration: off the pre-conduct skillset entirely.

Projects instrumented before the conduct unification use planning/specification skills and an older brain layout. There is no automatic migration; the manual route:

  1. .ai/session/ β†’ .ai/work/ (rename; add work/ to .ai/.gitignore, remove session/ from tracking if needed).
  2. .ai/memory/archive/plans/ and archive/specs/ β†’ .ai/memory/log/ (move files; keep their dated names).
  3. .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 to memory/log/.
  4. Replace the full per-repo AGENTS.md with the minimal marker (jaiba-init bootstrap step 3 offers replace/coexist) and run jaiba-configure to install the global contract (its step 2).
  5. Uninstall the planning and specification skills; install conduct.
  6. Run /jaiba-doctor β€” it detects leftover old-layout directories and contract drift, and routes the remainder.

Glossary

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.

About

Joint AI behavioral architecture. Agentic AI for software development made right, effectively and productive, for problems at any scale

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages