Joint-operations Artificial Intelligence Behavioral Architecture
A framework for AI agent-assisted software development, designed to keep the human always in the loop.
- 🦀 JAIBA
To adopt JAIBA in your project, follow these steps:
Install all JAIBA skills globally so they are available across all your projects:
npx skills add atlasfoo/jaiba-framework --skill jaiba-scaffold -g
npx skills add atlasfoo/jaiba-framework --skill conduct -g
npx skills add atlasfoo/jaiba-framework --skill update-brain -g
npx skills add atlasfoo/jaiba-framework --skill fast -g
npx skills add atlasfoo/jaiba-framework --skill ask -g
npx skills add atlasfoo/jaiba-framework --skill doctor -gOr install them all at once:
npx skills add -y atlasfoo/jaiba-framework -gBenefits of global installation:
- 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 your project and invoke the scaffold skill to set up the framework:
/jaiba-scaffold
Or simply: "set up jaiba in this project" or "bootstrap jaiba"
The scaffold will:
- Create the
.ai/brain skeleton (memory/+memory/log/,work/,vendored/) and its.gitignore - Install the global JAIBA Behavioral Contract (
jaiba-contract.md) into your agent's user-level config — once per machine - Drop the minimal
AGENTS.mdmarker at the repo root - Install the subagent battery (executors + specialists) into your agent's global
agents/folder - Hand off to
update-brain:initializeto populate the long-term memory, and then tojaiba-doctorfor the first health check and toolchain probe (.atl/tool-layout.md)
If you prefer to keep JAIBA skills scoped to individual projects (not recommended), the jaiba-scaffold skill will install them locally during initialization. In this case, you only need to install the scaffold skill globally in step 1.
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 --skill <skill-name> |
| Location | ~/.agents/skills/ (user home directory) |
| Availability | All projects automatically have access |
| Setup per project | Only initialize .ai/ brain with /jaiba-scaffold |
| 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:
- Install skills once globally
- In each project, run
/jaiba-scaffoldto initialize only the brain (.ai/) - 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 | Skills auto-install during scaffold if not global |
| Location | .agents/ or project skill folder |
| Availability | Only in that specific project |
| Setup per project | Full scaffold including skill installation |
| Disk footprint | Each project has its own copy of skills |
| Updates | Must re-scaffold or manually update per project |
| Recommended for | Legacy setups, isolated environments |
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)
│ │ ├── constitution.md ← Project identity, stack, quality gate
│ │ ├── adr-log.md ← Curated decisions in force
│ │ ├── reference-index.md ← External surfaces + internal cross-component contracts
│ │ └── 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-scaffold, /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-scaffold 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 that confirms instrumentation and defers to the global contract for behavior and to the constitution for project facts.
jaiba-doctor checks the contract's presence and drift against the packaged version on every health check.
The project's executive summary: what the system does and for whom, stack and architecture, team conventions, sub-unit scopes (for monorepos / multi-project solutions), and the Quality Gate. Authoritative on project specifics.
The curated decision memory: Architecture Decision Records currently in force — decision, context, alternatives, consequences. Superseded entries are marked, never deleted.
The index of external surfaces — APIs, packages, services — plus internal cross-component contracts (event schemas, APIs between sub-units). Each entry documents purpose, consultation method, and, when vendored, its local copy path.
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 adr-log.md answers "what do we hold true today", log/ answers "what happened, in order". Written by conduct:summarize (work closures) and update-brain (brain changes) — the framework's one sanctioned carve-out to the "only 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 reference-index.md. 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 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 — directly or by delegating task waves to the executor subagents. Triggered by continuation cues; no command needed. |
validate |
— | Run the plan's quality gate and check acceptance criteria one by one (delegating to the verify subagent when available), reporting met/unmet per criterion. |
summarize |
log entry in .ai/memory/log/ |
Single closing step: present the final summary, propose ADRs/constitution changes for 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: acts directly, writes nothing to
.ai/work/; git history plus a one-line recap is the record. - Plan adjustment: with an active plan, executes the out-of-band change and — after developer confirmation — records it into the plan artifacts.
- 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. Strictly read-only: 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 (
adr-log.md+memory/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 constitutive-memory maintenance workflow — the only skill that writes .ai/memory/ (log appends excepted). initialize builds the brain from repository analysis (essential for brownfield onboarding); update applies proposed ADRs, reference-index entries, and constitution changes, or reconciles the brain after structural drift. Every brain change leaves a brain-change entry in memory/log/.
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); constitution / adr-log / reference-index complete, mutually consistent, and not drifting from the repo; curated-vs-chronological separation intact. | update-brain / jaiba-scaffold |
| 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-index.md entry reachable: MCP/CLI installed, remote spec live, vendored copy present and fresh. |
install · fix endpoint · re-vendor via update-brain |
The one-time bootstrap: lays the .ai/ skeleton, installs the global contract + repo marker, installs skills (global or project-local) and the subagent battery, then hands off to update-brain:initialize and jaiba-doctor. Never runs on an already-instrumented repo.
scaffold installs six native subagent definitions into the agent's global agents/ folder. The invocation contract (conduct/references/subagents.md) governs delegation: which operations delegate, the requires: tool convention, a pre-invocation toolchain check against .atl/tool-layout.md (a missing tool surfaces before invocation, never as a mid-run failure), and the concurrency policy.
| Subagent | Role | Used in phase |
|---|---|---|
executor-high |
Design-heavy, multi-file tasks (load: high) |
execute |
executor-medium |
Bounded implementation tasks (load: medium) |
execute |
executor-low |
Mechanical, repetitive tasks (load: low) |
execute |
code-analyst |
Code survey without loading conduct's context | spec (define/design) |
business-analyst |
Contrasts the requirement against constitution / adr-log / reference-index | propose, spec |
verify |
Consumes the PRD's criteria schema; reports met/unmet per criterion | validate |
Parallelism: execute builds waves from the tasks.md depends-on graph — fan-out capped at 3, two tasks run in parallel only if they don't share files, subagents write source only (conduct is the single writer of .ai/work/), and results reintegrate into the walkthrough before the next wave. Hosts without subagent support fall back to sequential execution under the same contract.
┌─────────────────────────────┐
│ New or legacy project │
└──────────────┬──────────────┘
│
/jaiba-scaffold
(skeleton + contract + skills + agents)
│
update-brain:initialize → jaiba-doctor
│
┌──────────────▼──────────────┐
│ 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 → 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 (optionally delegating a memory contrast to business-analyst) 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 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.)
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 and letjaiba-scaffoldinstall the global contract (step 3 of its sequence handles both). - 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/: constitution, curated ADR log, reference index, chronological log — who the project is |
| 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 six globally-installed agents: three executors by cognitive load + code-analyst, business-analyst, verify |
| 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.