etymology — candi prambanan, c. 850 ce

Built overnight. Meant to last a thousand years.

In the Javanese legend, Princess Jonggrang demanded a thousand temples built in a single night. The suitor coordinated an army of spirits to pull it off. He failed — at 999 — and she was turned to stone as the thousandth.

The Prambanan temple complex near Yogyakarta is the physical remnant. Named for the principle, not the curse: large works get built when many small workers coordinate well. We ship sixteen phases, not one thousand.

[ photo — candi prambanan silhouette at dusk ]

JONGGRANG§00 OVERTURE01

philosophy

AI writes code fast. Too fast.
The bottleneck is no longer writing — it's knowing when to stop.

A codebase shaped by a disciplined process is cleaner than one shaped by raw speed. Every feature passes through the same pipeline — not because every step is always necessary, but because skipping steps is how complexity accumulates silently.

JONGGRANG§00 PHILOSOPHY02

why this matters

A codebase made of layers looks finished — until it doesn't.

An AI agent without structure produces work that looks done but is layered: subtly different naming conventions, duplicated logic, tests that assert the wrong thing. The pipeline is the minimum structure required to keep the output coherent over time. Jonggrang is opinionated because it has to be — the agent will always take the shortest path; the framework's job is to make sure the shortest path is also the right one.

JONGGRANG§00 PHILOSOPHY03

problem 01

Agents have no memory. Projects need one.

Every session starts from zero. Conventions, file layout, the gotchas — you explain them, the context fills, the next message forgets.

You become the persistent memory. That doesn't scale past the second feature.

JONGGRANG§01 PROBLEM03

problem 02

85%where context collapses

Long sessions don't just forget — they decay. Early mistakes calcify as "the way we do things here." Tangents pollute the working set. The agent starts quoting its own hallucinations.

Past 85% context usage, success rate falls off a cliff. Past 90%, you're burning tokens watching it drift.

JONGGRANG§01 PROBLEM04

problem 03

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.

JONGGRANG§01 PROBLEM05

the premise

Thin agents. Fat platform.

— AGENT

Under 150 lines
of prompt.

Stateless worker. Reads a task, does the task, reports back. Dies. A new one spawns clean for the next task.

— PLATFORM

Everything else.

Task board. Skill library. Enforcement hooks. State machine. File locks. Compaction gates. Feedback loops. Progress log.

The agent is disposable. The platform is durable. Any agent can die, time out, or get compacted — the next picks up exactly where the last stopped.

JONGGRANG§02 IDEA07

the pipeline is the quality gate

Every feature, every time, the same shape.

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

JONGGRANG§02 IDEA08

architecture at a glance

Five layers. The agent is only one of them.

L1 — Agent Stateless workers Lead · Developer · Reviewer · TestLead · Tester

L2 — Skill Two-tier, JIT loaded Core (BIOS) · Library (via Gateway)

L3 — Orchestration 16-phase state machine MANIFEST.yaml · work-type phase skipping

L4 — Hook Deterministic enforcement Claude · OpenCode · Codex · Jonggrang (Pi)

L5 — Infra Compaction · feedback · locks Token gates · dirty bits · file ownership

JONGGRANG§02 IDEA08

how it compares

Where the others stop, we keep going.

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

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

JONGGRANG§02 IDEA09

one entry · triage-routed

plan → triage → short path or deep path → approve.

$ jonggrang plan "description" --deep

[ Phase 02 — Triage ] quick classify: BUGFIX · SMALL · MEDIUM · LARGE

— BUGFIX / SMALL

single AI call → plan.md

— MEDIUM / LARGE

Phase 03 Discovery (explore codebase)
Phase 04 SkillMap
Phase 05 Complexity analysis
Phase 06 Brainstorm (alternatives)
Phase 07 Architect
→ condensed → plan.md

[ Human reviews plan.md ]

$ jonggrang approve (Phase 08 — decompose to tasks)

JONGGRANG§03 FLOW10

the pipeline

One pipeline. Sixteen phases.

01Setup

02Triage

03Codebase discovery

04Skill discovery

05Complexity

06Brainstorming

07Architecture plan

08Developer tasks

09Design review

10Domain review

11Quality review

12Test strategy

13Test execute

14Coverage

15Test quality

16Commit + PR

run always skipped for bugfix / small

JONGGRANG§03 MODES11

triage routes the flow

Same command. Different ceremony.

Work type	Trigger	Plan path	Runs
Bugfix	"fix", "bug", "issue", "error"	short — 1 AI call → plan.md	~5 phases
Small	< 100 lines, single concern	short — 1 AI call → plan.md	~6 phases
Medium	multi-file, some design	deep — phases 03–07 → plan.md	all 16
Large	new subsystem, architectural	deep — phases 03–07 → plan.md	all 16

One command: jonggrang plan "…" --deep. Phase 02 triages, routes to short or deep, then both paths converge at plan.md for human review.

JONGGRANG§03 MODES12

five roles in order

A Lead does not write code. A Developer does not design.

Role	Agent	Produces	Hard output
Lead	*-lead	Designs architecture. Decomposes into tasks.	architecture-plan.json
Developer	*-developer	Implements specific tasks. Writes tests alongside.	source + tests
Reviewer	*-reviewer	Validates design, compliance, quality. Rejects non-compliant.	review-report.json
Test Lead	test-lead	Analyzes implementation. Designs test strategy.	test-plan.json
Tester	*-tester	Writes and runs tests from the plan.	test-results.json

JONGGRANG§04 ROLES14

the separation

Coordinators plan.
Executors implement.
Never both.

A single agent playing every role confirms its own design as it builds. You lose the second set of eyes. Splitting the roles across fresh contexts turns a monologue into an audit trail.

JONGGRANG§04 ROLES15

permission model

The boundary is a permission boundary. Not a politeness.

Role	Can use	Cannot use
Lead, Test Lead	Task · Read · TodoWrite	Edit · Write · Bash
Developer, Tester	Edit · Write · Bash · Read	Task
Reviewer	Read · Bash	Edit · Write · Task

Leads literally do not have the tools to modify code. If you wanted them to, you couldn't. The role can't drift because the tool set won't let it.

JONGGRANG§04 ROLES16

progressive disclosure

Core loads first. Library loads on demand.

tier 01 — bios

Core

Small, always available. The standard vocabulary every agent can assume.

gateway-backend
gateway-frontend · gateway-api
gateway-testing · gateway-database
orchestrating-feature
iterating-to-completion
dispatching-parallel-agents
persisting-agent-outputs
scaffold-api · auth · testing · deploy

tier 02 — hard drive

Library

Deep domain knowledge. JIT-loaded when the gateway detects intent.

backend/developing-with-tdd
backend/debugging-systematically
frontend/debugging-react-hooks
frontend/optimizing-react-performance
testing/fixing-flaky-tests
database/safe-migrations
api/input-validation
security/rate-limiting

JONGGRANG§05 SKILLS18

the gateway pattern

Agents don't hardcode skill paths. They declare intent.

agent "I need to fix a React infinite loop." thin · stateless · declares intent

→

gateway-frontend Detects: "infinite loop", "useEffect" routing lives in the platform, not the prompt

→

skill file Read library/frontend/debugging-react-hooks/SKILL.md loaded JIT, only when needed

The skill library can grow without bound. The agent prompt stays stable. Skills become searchable knowledge, not prompt bloat.

JONGGRANG§05 SKILLS19

first principle

Never ask the model to enforce its own quality gates. It will always find a path that makes it look successful.

So we run the gates outside the model — as deterministic code in the tool layer. Claude Code calls them PreToolUse / PostToolUse. OpenCode calls them tool.execute.before / session.idle. Same idea, plain code, veto power.

JONGGRANG§06 ENFORCEMENT21

hook map

Seven gates. Same rules across backends.

L	Claude Code	OpenCode	Jonggrang (Pi)	Enforces
5	PreToolUse	tool.execute.before	tool_call	Block direct edits (agent-first)
5	PreToolUse	tool.execute.before	tool_call	Block agent spawn if context > 85%
6	PostToolUse	tool.execute.after	tool_result	Set dirty bit when files modified
6	PostToolUse	file.edited	tool_result	Track domain (backend/frontend/testing)
7	SubagentStop	session.updated	agent_end	Block exit if output in wrong location
8	Stop	session.idle	agent_end	Block exit until review + tests pass
8	Stop	session.idle	before_provider_request	Final quality / compaction gate

JONGGRANG§06 ENFORCEMENT22

the feedback loop

Dirty bits block premature exits. Per modified domain.

When a Developer touches a file, the platform sets a dirty bit for that domain.

That bit cannot be cleared until a Reviewer AND Tester pass for that same domain.

The agent literally cannot exit. The Stop hook blocks it. We don't ask the model to check. We block the exit until it's true.

feedback-loop-state.json

{
  "active": true,
  "modified_domains": ["backend", "frontend"],
  "domain_phases": {
    "backend":  { review: "PASS", testing: "PASS" },
    "frontend": { review: "PASS", testing: "FAIL" }
  }
}

> exit blocked — frontend.testing=FAIL
          

JONGGRANG§06 ENFORCEMENT23

the compaction gate

Check context before the heavy phases. Block if it's too full.

— < 75%

Go.

Proceed to the phase. No warning.

— 75 – 80%

Warn.

Soft warning in the log. Proceed.

— 80 – 85%

Must.

Strong warning. Proceeds, but flagged.

— > 85%

Block.

Hard stop. Run /compact first. Spawning at 90% is guaranteed failure.

Runs before phases 03, 08, 13 — discovery, implementation, testing. The three phases where an agent spawned into a full context window fails silently.

JONGGRANG§06 ENFORCEMENT24

persistent orchestration

MANIFEST survives the session. Resume at the exact phase.

.jonggrang/.output/features/auth/MANIFEST.yaml

feature_id: auth-jwt-flow
work_type: LARGE
current_phase: 09
phases:
  01_setup:     { status: DONE,         artifact: 01-setup.json }
  02_triage:    { status: DONE,         artifact: 02-triage.json }
  07_architect: { status: DONE,         artifact: 07-lead-plan.json }
  08_developer: { status: DONE,         artifact: 08-dev-task-003.json }
  09_reviewer:  { status: IN_PROGRESS,  started: 2026-04-18T09:12Z }
  12_test_lead: { status: PENDING }
  13_tester:    { status: PENDING }
          

No "remind the agent what we were doing."

The platform remembers.

$ jonggrang plan --resume
picks up at the exact phase you left.

JONGGRANG§07 STATE26

parallel safety

File locks keep parallel agents honest. No two writers on the same path.

— DISPATCH

Fan out by file ownership.

Developer tasks declare the paths they'll touch. The platform dispatches disjoint sets in parallel.

— LOCK

First agent wins.

.jonggrang/locks/dev-a.lock claims src/auth/*.ts. Agent B gets a different task or waits.

— RELEASE

On stop, not drift.

Locks are released by the Stop hook — not by the agent claiming it's done. No silent clobbers.

Parallelism without the usual agent-orchestra horror of "two agents wrote the same file. One won. Silently."

JONGGRANG§07 STATE27

one contract · four runtimes

Pick your agent. The platform doesn't care.

— --tool opencode

OpenCode

Plugin at .opencode/plugins/jonggrang.js. Hooks: tool.execute.before / .after, session.idle.

— --tool claude

Claude Code

Settings at .claude/settings.json. Hooks: PreToolUse / PostToolUse, Stop.

— --tool codex

Codex CLI

OpenAI's coding CLI. Same skills, same enforcement contract. --effort low|medium|high.

— --tool jonggrang

Jonggrang (Pi)

Built on the Pi SDK. Multi-provider — Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter and more. TypeScript-extensible.

--model and --effort compose freely with --tool. Resolution: flag → env → tools.<tool>.model in config → top-level default.

JONGGRANG§08 USING29

one-line install

Install once. Plan, approve, work.

~/projects/my-app

# 1. install
$ npx jonggrang init --tool jonggrang

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

# 3. plan (add --deep for large work)
$ jonggrang plan "JWT auth" --deep
  → triage → (short or deep) → plan.md

# 4. review, approve, grind
$ jonggrang approve
$ jonggrang work
  → fresh agent, per task, until done
          

— SHORTHAND

One-shot mode.

jonggrang work "feature" --yes

Plan → approve → execute in one command. Skips every interactive prompt.

— FOR BIG WORK

Go deep.

jonggrang plan "…" --deep

Full pipeline: Discovery → SkillMap → Complexity → Brainstorm → Architect.

JONGGRANG§08 USING29

interactive mode

jonggrang agent — the whole pipeline, from a chat.

jonggrang agent — Pi TUI

$ jonggrang agent
Pi · anthropic/claude-sonnet-4-5 · balanced

› /plan add JWT auth + password reset
  → .jonggrang/plan.md written

› /approve
  → 7 tasks queued

› /work
  → task-001  developer  JWT issuance
  → task-002  reviewer   Domain review
  ...

› /status   # task board
› /model    # swap provider live
          

— SLASH COMMANDS

Everything the CLI does.

/plan · /approve · /work
/status · /review · /config
/login · /logout · /model

Plus Pi built-ins: /compact, /help, Ctrl+P to cycle models.

— AUTO-LOADED

Hooks always on.

The Pi extension at hooks/jonggrang/jonggrang-extension.ts loads on every agent session. Secret blocking, output sanitization, feedback gate — no install step.

JONGGRANG§08 USING31

autonomy modes

Autonomy is a dial. Not a switch.

Supervised

Pauses at brainstorming (Phase 06) for human design input.

best for — critical systems

Balanced

Auto-runs. Pauses only on failures or ambiguity.

best for — daily development

Autonomous

Full loop — plans, implements, commits. Human reviews at the end.

best for — well-defined tasks

Most teams start on supervised, graduate to balanced in a week, and move specific task categories to autonomous as trust builds.

JONGGRANG§08 USING30

the whole shape

Everything the model is bad at, we moved to code.

— REASONING

Thin agents

Under 150 lines of prompt. Stateless. Disposable. Replaceable. The only thing they're asked to do is the work.

— INFRASTRUCTURE

Fat platform

Skills. State. Enforcement. Routing. Locks. Manifests. Compaction. Feedback loops. Everything the model is bad at, handled in plain code.

JONGGRANG§09 RECAP31