// § 01

/* the wall */ three problems every agent workflow hits

walls.md · 3 entries

WALL.01stateless

Agents have no memory.

Every session starts from zero. You explain the conventions, the file layout, the gotchas — the context fills, the next message forgets. You become the persistent memory, and it doesn't scale past the second feature.

// err: context_lost at boot+0s

WALL.02drift

Long sessions rot.

Early mistakes calcify as "the way we do things here." Tangents pollute the working set. The agent starts quoting its own hallucinations back. Past 85% context usage, success rate falls off a cliff.

// warn: context_pressure ≥ 85%

WALL.03no-project-memory

No project memory.

Agent A learns a lesson. Agent B, an hour later, in a fresh session, learns it again. No accumulation, no transfer. The gap between "AI can write code" and "AI can maintain a codebase" is project memory — and most tools don't have any.

// err: no_accumulation ∀ agent ∈ project

// § 02

/* the shape */ thin agent · fat platform

architecture.md

agent layer

Under 150 lines of prompt.

A stateless worker. It reads a task, does the task, reports back, dies. A new one spawns clean for the next task. Drift can't accumulate because there's nowhere for it to live.

+fresh context every iterationanti-rot

+tool restrictions per roleedit · write · bash

+no shared mutable stateplatform owns it

+any agent can die mid-taskresumable

platform layer

The platform holds it all.

Task board, skill library, enforcement hooks, state machine, file locks, compaction gates, feedback loops, progress log. The agent just asks the platform what to do next.

+MANIFEST.yaml — phase trackingpersistent

+16-phase orchestrationtriage-routed

+deterministic Pre/Post hookscode, not prompts

+dirty-bit feedback loopper domain

+compaction gate > 85%hard block

+file locks for parallel agentsfirst-writer-wins

— the pipeline is the quality gate

Every feature, every time, the same shape.

hooks · always on · veto power

— hooks Always on. Guards every tool call, file edit, and exit.

enforces invariants in real-time

01 Plan Intent → structured tasks. Human review before code.

→

02 Implement ⟲ Fresh context per task. Hooks block premature exit. loops until quality
gates pass

→

03 Simplify Reduce complexity without changing behavior.

→

04 Test Part of done — not appended at the end.

→

05 Review Read as a future maintainer would.

// § 03

/* the pipeline */ one command, ceremony on demand

plan → triage → approve

plan("description", { deep: true })

One entry point: jonggrang plan. The first thing that happens is Triage — Phase 02 — a quick classify into bugfix, small, medium, or large.

If it's bugfix or small, you take the short path: a single AI call condenses the description into plan.md in seconds.

If it's medium or large, you take the deep path: Discovery → SkillMap → Complexity → Brainstorm → Architect — five phases of real work, all condensed into the same plan.md format.

Both paths converge at the same artifact. You review by hand, run approve, and Phase 08 decomposes the plan into atomic developer tasks.

$ jonggrang plan "JWT auth" --deep │ ▼ ┌──────────────────────────────────────┐ │ PHASE 02 triage classify │ │ bugfix · small · medium · large │ └──────────────────────────────────────┘ │ ├──── short path ──────────────────┐ │ │ │ bugfix · small │ │ → 1 AI call │ │ → plan.md │ │ │ └──── deep path ───────────────────┤ │ medium · large │ → 03 Discovery │ → 04 SkillMap │ → 05 Complexity │ → 06 Brainstorm │ → 07 Architect │ → plan.md │ ▼ ┌──────────────────────┐ │ human reviews │ │ plan.md │ └──────────────────────┘ │ ▼ $ jonggrang approve → atomic tasks → ready to work

// § 04

/* the assembly line */ five roles, hard boundaries

ls -la .jonggrang/agents

$ ls -la .jonggrang/agents5 entries · readonly

role · agent	perms	produces	output
Lead*-lead	r-- Task · Read · Todo	Designs architecture. Decomposes into tasks. Never writes code.	architecture-plan.json
Developer*-developer	rwx Edit · Write · Bash	Implements specific tasks. Writes tests alongside.	source + tests
Reviewer*-reviewer	r-x Read · Bash	Validates design, compliance, quality. Rejects non-compliant work.	review-report.json
Test Leadtest-lead	r-- Task · Read · Todo	Analyzes implementation. Designs the test strategy.	test-plan.json
Tester*-tester	rwx Edit · Write · Bash	Writes and runs tests from the plan.	test-results.json

— enforced by tool access

Coordinators plan.
Executors implement. Never both.

// § 05

/* the skill system */ core loads first · library on demand

tree skills/

tier 01 — BIOS12 skills · always loaded

├── core/
│   ├── gateway-backend// routes domain intent
│   ├── gateway-frontend
│   ├── gateway-api
│   ├── gateway-testing
│   ├── gateway-database
│   ├── orchestrating-feature
│   ├── iterating-to-completion
│   ├── dispatching-parallel-agents
│   ├── persisting-agent-outputs
│   ├── scaffold-api
│   ├── auth · testing · deploy
│   └── migration · component

tier 02 — hard driveJIT loaded · grows freely

└── library/
    ├── backend/
    │   ├── developing-with-tdd
    │   ├── debugging-systematically
    │   └── error-handling-patterns
    ├── frontend/
    │   ├── debugging-react-hooks
    │   └── optimizing-react-performance
    ├── testing/
    │   ├── unit-testing-patterns
    │   └── fixing-flaky-tests
    ├── database/ safe-migrations
    ├── api/ input-validation
    └── security/ rate-limiting

// gateway pattern

Agents declare intent.
Gateways resolve it.

agent

"I need to fix a React infinite loop."

→

gateway-frontend

Detects: "infinite loop", "useEffect"

→

skill file

Reads library/frontend/debugging-react-hooks/SKILL.md

// § 06

/* enforcement */ models drift · hooks don't

deterministic gates · veto power

HOOK.iPreToolUse

Hooks run outside the model.

PreToolUse, PostToolUse, SubagentStop, Stop — plain code wired into the tool layer with veto power. Same contract across OpenCode, Claude Code, Codex CLI, and the Jonggrang (Pi) engine.

// PreToolUse · pre-spawn if (ctx.tokens > 0.85) { block("compact_first") } // agent cannot spawn

HOOK.iiPostToolUse · Stop

Dirty bits block premature exits.

A Developer touches a file → the platform sets a dirty bit for that domain. The bit can't clear until a Reviewer AND a Tester pass per-domain. The Stop hook blocks the agent until they do.

// feedback-loop-state.json backend: review=PASS, test=PASS frontend: review=PASS, test=FAIL > exit blocked

HOOK.iiiPreToolUse · gate

Compaction gates keep context healthy.

Before Discovery, Implementation, and Testing — the three heavy phases — we check token usage. Under 75% goes; 75–85% warns; over 85% hard-blocks until compact.

// compaction gate < 75% → proceed 75–85% → warn > 85% → block, /compact

// § 07

/* head-to-head */ where the others stop, we keep going

diff competitors.md

$ diff --side-by-side agent-frameworks/4 cols · 4 features

feature	Ralph	Claude Code	Superpowers	Jonggrang
Scope	Single agent loop	Cross-session handoff	Skill framework	Multi-agent orchestration
State	None — loop only	YAML handoffs	Context-based	Dual — ephemeral + persistent
Control	Prompt-based	Prompt-based	Skill-based	Deterministic hooks
Feedback	None	None	Human-in-loop	Inter-phase loops + escalation advisor

// none = no mechanism for it // us = jonggrang's column · accent

— inspiration · contribution

Each predecessor solves one layer. Jonggrang pushes on all four at once.

inspired by Ralph Loop · Agent Orchestra (Addy Osmani) · the collapsed SDLC (Boris Tane) — extended into a multi-agent assembly line with deterministic enforcement.

// § 08

/* get started */ one line · three commands

no accounts · no cloud

Install once.
Plan, approve, work.

Runs locally on top of OpenCode, Claude Code, Codex CLI, or the multi-provider Jonggrang (Pi) engine. Generates project config, AGENTS.md skeleton, skill library, and enforcement hooks for whichever backend you pick.

01

jonggrang init — wizard or one-liner flags

02

jonggrang login & model — add a provider, pick a model (Pi backend)

03

jonggrang plan — add --deep for big work

04

jonggrang approve — decompose plan.md → atomic tasks

05

jonggrang work — fresh agent · per task · until done

06

jonggrang agent — or drive the whole pipeline from a TUI chat

$ jonggrang init

session — bash ~/my-app

# 1. install (pick a backend with --tool)
$ jonggrang init --tool jonggrang --type api
  ✓ wrote .jonggrang/jonggrang.json
  ✓ wrote AGENTS.md
  ✓ wrote .jonggrang/extensions/jonggrang.ts

# 2. auth + model (Pi backend)
$ jonggrang login   # OAuth or API key
$ jonggrang model   # pick provider/model

# 3. plan + approve + work
$ jonggrang plan "JWT auth flow" --deep
  → triage → deep → plan.md
$ jonggrang approve
  → 7 atomic tasks queued
$ jonggrang work
  → task-001  [OK]
  → task-002  [OK]

Stateless agents. Stateful platform.