Jonggrang — AI Agent Instructions

You are working inside a project managed by Jonggrang, a deterministic AI development workflow orchestrator. This file is your operating manual. Read it completely before doing anything.

---

How to Run Jonggrang

Use npx — no global installation required:

npx jonggrang <command>

If Jonggrang is already installed globally, you can also use jonggrang <command> directly. To check:

npx jonggrang version

---

Your Role in This Project

Jonggrang runs in two modes. Know which one you are in:

Mode 1 — Work Loop

You are a single agent executing tasks from .jonggrang/jonggrang-tasks.json one at a time. Each invocation is stateless — a fresh context window per task.

Mode 2 — Orchestrate (16-Phase Pipeline)

You are a specialist agent assigned to a specific phase and role. You receive a crafted prompt that tells you your role, the current phase, and what the previous agent produced. You must emit a completion signal at the end of your output.

Check .jonggrang/jonggrang-tasks.json for your current task's "role" field, or look for role instructions in your prompt.

---

Context Files — Read These First

File	Purpose	Action
AGENTS.md	Project conventions, patterns, gotchas	Read first. Follow all conventions.
.jonggrang/progress.txt	Learnings from previous iterations	Read. Avoid repeating mistakes.
.jonggrang/jonggrang-tasks.json	Task board with current state	Read. Find your assigned task.
.jonggrang/jonggrang.json	Project config (stack, testing, tool)	Read. Know your test command and stack.
skills/core/<name>/SKILL.md	Core skill for your task type	Read if task has "skill" field.
.jonggrang/.output/features/<id>/MANIFEST.yaml	Orchestration phase state	Read in orchestrate mode.

---

Skill System — Two Tiers

Skills are prompt templates that encode expert knowledge. There are two tiers:

Tier 1: Core Skills (skills/core/)

Always available. Loaded into your prompt for every task. Contains foundational patterns:

• How to orchestrate a feature
• How to dispatch parallel agents
• How to invoke the Gateway
• Domain gateway pointers (backend, frontend, api, testing, database)
• Scaffold templates (scaffold-api, scaffold-webapp, component, migration, auth, etc.)

Tier 2: Library Skills (skills/library/)

Loaded on demand via the Gateway when you need deep domain knowledge.

Domain	Available Skills
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

Using the Gateway

Before implementing, resolve the right library skill for your task:

node -e "
const gw = require('./lib/gateway');
const r = gw.buildGatewayResponse('YOUR TASK DESCRIPTION HERE', './skills');
console.log(r);
"

The Gateway returns { domain, skill_paths, instruction }. Read each file in skill_paths before implementing.

---

Work Loop — Task Execution Protocol

Step 1: Understand

• Read all context files listed above
• Read the task description carefully — it contains acceptance criteria
• If the task has "skill": "scaffold-api", read skills/core/scaffold-api/SKILL.md
• Check blocked_by — dependencies must already be completed

Step 2: Invoke Gateway

Resolve the right library skills for your task domain:

node -e "
const gw = require('./lib/gateway');
const r = gw.buildGatewayResponse('<task description>', './skills');
r.skill_paths.forEach(p => console.log('Read:', p));
"

Read each returned skill file before proceeding.

Step 3: Plan

• Identify which files to create or modify
• Check existing code patterns before writing new code
• Follow conventions in AGENTS.md
• Keep changes atomic — only touch files relevant to this task

Step 4: Implement

• Write clean, working code
• Follow existing patterns in the codebase
• Use the project's existing dependencies (don't add unnecessary packages)
• Include proper types (no any in TypeScript)

Step 5: Validate

# Typecheck
npm run typecheck    # or: tsc --noEmit, go vet, mypy, etc.

# Tests
npm test             # or: the command in .jonggrang/jonggrang.json -> testing.command

# Lint (if configured)
npm run lint

If validation fails: read the error, fix it, re-run. If stuck after 2 attempts, stop and report clearly.

Step 6: Update State

Update .jonggrang/jonggrang-tasks.json — mark task completed:

{
  "status": "completed",
  "passes": true,
  "completed_at": "<ISO timestamp>"
}

Append to .jonggrang/progress.txt — log learnings:

## task-XXX: Task Title
- What was implemented
- What was surprising or non-obvious
- Patterns discovered in the codebase
- Gotchas for future iterations

Step 7: Commit

git add <specific files only>
git commit -m "type(scope): description"

Types: feat, fix, refactor, test, docs, chore

Never: git add . or git add -A, commit node_modules/ or .env, amend previous commits.

---

Orchestrate Mode — Role-Specific Instructions

In orchestrate mode you are assigned one of five roles. Your role determines what tools you have and what signal you must emit.

Role Summary

Role	Can Edit Files	Can Spawn Agents	Completion Signal
Lead	no	YES (Task tool)	ARCHITECTURE_PLAN_COMPLETE
Developer	YES	no	IMPLEMENTATION_COMPLETE
Reviewer	no (read-only)	no	REVIEW_COMPLETE
TestLead	no	YES (Task tool)	TEST_PLAN_COMPLETE
Tester	YES	no	ALL_TESTS_PASSING

Phase → Role Mapping

Phases	Role	What You Do
1–4	(orchestrator)	Setup, triage, discovery — handled automatically
5–7, 16	Lead	Assess complexity, brainstorm, architect, finalise
8	Developer	Implement the feature end-to-end
9–11, 15	Reviewer	Verify design, compliance, quality, test quality
12	TestLead	Write the test plan
13–14	Tester	Execute tests, verify coverage

Completion Signal Protocol

Your last output line must be your role's completion signal. The orchestration engine waits for this signal before advancing to the next phase.

# Developer — after all code is written, typechecked, and tests pass:
IMPLEMENTATION_COMPLETE

# Tester — after all tests pass and coverage threshold met:
ALL_TESTS_PASSING

# Reviewer — after completing your review:
REVIEW_COMPLETE

# Lead — after producing architecture plan:
ARCHITECTURE_PLAN_COMPLETE

# TestLead — after producing test plan:
TEST_PLAN_COMPLETE

Reading the MANIFEST

In orchestrate mode, the MANIFEST tracks phase state. Read it to understand context:

cat .jonggrang/.output/features/<feature-id>/MANIFEST.yaml

Key fields: work_type, current_phase, phases (per-phase status and output), validation.

---

Rules

DO

• Read all context files before starting
• Follow conventions in AGENTS.md exactly
• Invoke the Gateway to load the right library skill
• Keep changes minimal and focused on the task
• Write tests when the task requires them
• Run validation before committing
• Log learnings in .jonggrang/progress.txt
• Emit your completion signal as the final output line (orchestrate mode)

DO NOT

• Modify files not related to your task
• Add dependencies without clear justification
• Change AGENTS.md directly — propose changes in .jonggrang/progress.txt instead
• Skip validation steps
• Make multiple commits per task (one atomic commit per task)
• Ignore errors — fix them or report them clearly
• Write .md files outside .jonggrang/, AGENTS.md, .jonggrang/progress.txt, README.md, CHANGELOG.md, or docs/

---

File Ownership

Each task in .jonggrang/jonggrang-tasks.json has a "files" array listing the files it owns. Do not modify files owned by other tasks — this prevents merge conflicts in team mode.

---

Jonggrang Commands Reference

# Setup
npx jonggrang init                               # Interactive setup wizard
npx jonggrang init --name x --type api --tool claude --autonomy balanced --force

# Work Loop
npx jonggrang plan "feature description"         # Decompose feature into tasks
npx jonggrang work                               # Run all pending tasks
npx jonggrang work --max-iterations 1            # Run one task only
npx jonggrang work --task task-003               # Run a specific task
npx jonggrang work --tool claude                 # Override AI tool
npx jonggrang work --dry-run                     # Preview prompt, no execution
npx jonggrang work --mode supervised             # Override autonomy

# Orchestrate (16-phase deterministic pipeline)
npx jonggrang orchestrate "description"          # Start full pipeline
npx jonggrang orchestrate --resume               # Resume interrupted pipeline
npx jonggrang orchestrate "..." --dry-run        # Preview all phase prompts
npx jonggrang orchestrate "..." --autonomy autonomous  # Skip human pauses

# Utilities
npx jonggrang status                             # Show task board
npx jonggrang review                             # Run code review
npx jonggrang version                            # Show version
npx jonggrang help                               # All commands and flags

---

Example: Completing a Work Loop Task

Given this task in .jonggrang/jonggrang-tasks.json:

{
  "id": "task-002",
  "title": "Add Todo CRUD endpoints",
  "description": "Create GET/POST/PUT/DELETE endpoints for /api/todos with in-memory storage",
  "skill": "scaffold-api",
  "files": ["src/routes/todos.ts", "src/types/todo.ts"],
  "blocked_by": ["task-001"]
}

Execution:

1. Read AGENTS.md, .jonggrang/progress.txt, .jonggrang/jonggrang-tasks.json, .jonggrang/jonggrang.json
2. Read skills/core/scaffold-api/SKILL.md
3. Run Gateway to resolve library skills for this task type
4. Read existing code (src/app.ts, other routes) to understand patterns
5. Create src/types/todo.ts with the Todo interface
6. Create src/routes/todos.ts with CRUD handlers
7. Register routes in src/app.ts
8. Run npm run typecheck && npm test
9. Update .jonggrang/jonggrang-tasks.json (status: completed, passes: true)
10. Append learnings to .jonggrang/progress.txt
11. git add src/routes/todos.ts src/types/todo.ts src/app.ts .jonggrang/jonggrang-tasks.json .jonggrang/progress.txt
12. git commit -m "feat(todos): add CRUD endpoints with in-memory storage"