Lisa Loop

Lisa Loop - REPL-Driven Autonomous Development

Lisa Loop is forj's native autonomous development loop. It spawns fresh Claude instances for each iteration, using LISA_PLAN.edn for state and REPL for validation.

Key Concepts

1. Fresh Context Per Iteration: Each checkpoint gets a fresh Claude instance (no context bloat)
2. LISA_PLAN.edn as State: Checkpoints persist progress across instances
3. REPL as Ground Truth: Query REPL for actual state, not LLM memory
4. Signs for Learnings: Failures are recorded so future iterations don't repeat mistakes

Commands

/lisa-loop

Start an autonomous development loop:

/lisa-loop "Build a REST API for users with CRUD operations" --max-iterations 20

Arguments:

• <prompt> - The task description (required)
• --max-iterations N - Maximum iterations before stopping (default: 20)
• --prd <path> - Path to PRD or specification document

/cancel-lisa

Stop the loop:

/cancel-lisa

/lisa-loop watch

Monitor the loop and get notified on completion:

/lisa-loop watch
/lisa-loop watch --interval 60

Arguments:

• --interval N - Check every N seconds (default: 30)

This will:

1. Show current status immediately via lisa_watch
2. Spawn a background monitor agent that polls at intervals
3. Notify you when the loop completes with a full summary
4. Tell you the log file path for live tailing

Example output:

[Lisa Watch] Current Status:

┌────────────┬─────────────────────────────────┬────────┐
│ Checkpoint │           Description           │ Status │
├────────────┼─────────────────────────────────┼────────┤
│ 1          │ Create password hashing         │ ✅ Done │
│ 2          │ Create JWT tokens               │ ✅ Done │
│ 3          │ Create auth middleware          │ 🔄 In Progress │
│ 4          │ Integration test                │ ⏳ Pending │
└────────────┴─────────────────────────────────┴────────┘
Progress: 2/4 (50%)

Background monitor started (checking every 30s).
You'll be notified when the loop completes.

For live updates, tail the log in another terminal:
  tail -f .forj/logs/lisa/orchestrator-20260128-102332.log

On completion, the monitor reports:

Lisa Loop complete!

Final Status: COMPLETE
Checkpoints: 4/4 (100%)
Signs/Learnings: None

All checkpoints:
  1. Create password hashing - Done
  2. Create JWT tokens - Done
  3. Create auth middleware - Done
  4. Integration test - Done

How to implement /lisa-loop watch

When user runs /lisa-loop watch:

Step 1: Show immediate status

lisa_watch  → Display current checkpoint table

Step 2: Find orchestrator log

Glob for: .forj/logs/lisa/orchestrator-*.log
Get the most recent one for the tail command

Step 3: Tell user about live tailing option

Tell user:
- For live updates: tail -f <log-path>
- You'll also get periodic status updates here

Step 4: Spawn ONE-SHOT background check agent

IMPORTANT: The agent does ONE check and exits. It does NOT loop internally.

Task({
  subagent_type: "general-purpose",
  run_in_background: true,
  prompt: """
    1. Sleep for {interval} seconds using Bash: `sleep {interval}`
    2. Read the file LISA_PLAN.edn using Read tool
    3. Report: How many checkpoints are :done vs total? What's the current :status? Is it :complete?

    That's it - just those 3 steps then exit.
  """
})

Step 5: When agent completes, react

When the background agent completes and notifies you:

1. Read the agent's result (it contains the status report)
2. Tell the user the current status (X/Y checkpoints, current checkpoint name)
3. If status is :complete → announce "Lisa Loop complete!" and stop
4. If status is :in-progress → spawn another identical agent (go to Step 4)

Example flow:

Agent completes → "Status: 5/10 (50%) - wait-30s-6 in progress"
                → Spawn another agent
                → Wait...
Agent completes → "Status: 8/10 (80%) - wait-30s-9 in progress"
                → Spawn another agent
                → Wait...
Agent completes → "Status: 10/10 (100%) - COMPLETE!"
                → Announce completion, stop spawning

Why this approach:

• Claude Code can't truly loop (no timers/schedulers)
• Background Task agents notify when they complete
• ONE-SHOT agents are reliable - they sleep, check, report, exit
• The "loop" happens at the orchestration level (you spawn new agents)
• User can continue working between status updates

How It Works

/lisa-loop "Build user auth"
         │
         ▼
┌─────────────────────┐
│ 1. PLANNING PHASE   │  ◄── Current Claude session
│                     │
│ - Read PRD if exists│
│ - Propose checkpoints│
│ - Get user approval │
│ - Create LISA_PLAN.edn│
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 2. RUN ORCHESTRATOR │  ◄── Calls lisa_run_orchestrator
│                     │
│ Spawns fresh Claude │
│ instance for each   │──────┐
│ checkpoint          │      │
└─────────────────────┘      │
                             │
    ┌────────────────────────┘
    │
    ▼
┌─────────────────────┐
│ ITERATION N         │  ◄── Fresh Claude instance
│ (Fresh Context)     │
│                     │
│ - Read LISA_PLAN.edn│
│ - Read embedded signs│
│ - Work on checkpoint│
│ - Validate via REPL │
│ - Mark done if pass │
└─────────┬───────────┘
          │
          ▼
    Checkpoint done?
    ├── Yes → Next iteration (fresh instance)
    └── No  → Retry (fresh instance)
          │
          ▼
    All done? → COMPLETE

Quick Start Instructions

When user runs /lisa-loop:

Step 1: Planning Phase (Current Session)

Check for existing plan:

lisa_get_plan

Check for PRD/documentation:

Glob for: PRD.md, SPEC.md, REQUIREMENTS.md, docs/*.md

Decision tree:

Step 2: Propose Plan to User

ALWAYS show the proposed checkpoints before creating:

I've analyzed the requirements and propose these checkpoints:

1. **Create password hashing module** (src/auth/password.clj)
   - Acceptance: `(verify-password "test" (hash-password "test")) => true`

2. **Create JWT token module** (src/auth/jwt.clj)
   - Acceptance: `(verify-token (create-token {:user-id 1})) => truthy`

Does this plan look right? I can adjust before starting the loop.

Wait for user approval before proceeding.

Step 3: Create Plan and Start Execution

After approval, create the plan:

lisa_create_plan with:
  title: "Build user authentication"
  checkpoints: [
    {description: "Create password hashing module",
     file: "src/auth/password.clj",
     acceptance: "(verify-password \"test\" (hash-password \"test\")) => true"},
    ...
  ]

Large plans (>10 checkpoints): Create the plan with the first few checkpoints, then use lisa_add_checkpoint to add the rest individually. This avoids payload size issues with lisa_create_plan.

Then start the orchestrator:

lisa_run_orchestrator with:
  max_iterations: 20

This spawns fresh Claude instances for each iteration. The orchestrator:

1. Reads LISA_PLAN.edn to find current checkpoint
2. Spawns claude -p <focused-prompt> for that checkpoint
3. Waits for completion
4. Repeats until all checkpoints done or max iterations

Step 4: Report Progress

The orchestrator logs to .forj/logs/lisa/. When it completes:

Lisa Loop complete!
- Iterations: 8
- All checkpoints: DONE
- Logs: .forj/logs/lisa/

LISA_PLAN.edn Format

{:title "Build user authentication"
 :status :in-progress
 :checkpoints
 [{:id :password-hashing
   :description "Create password hashing module"
   :file "src/auth/password.clj"
   :acceptance "(verify-password \"test\" (hash-password \"test\")) => true"
   :status :done
   :completed "2026-01-16T10:30:00Z"}
  {:id :jwt-tokens
   :description "Create JWT token module"
   :file "src/auth/jwt.clj"
   :acceptance "(verify-token (create-token {:user-id 1})) => {:user-id 1}"
   :status :in-progress
   :started "2026-01-16T10:35:00Z"}
  {:id :auth-middleware
   :description "Create auth middleware"
   :file "src/middleware/auth.clj"
   :acceptance "Middleware extracts user from valid token"
   :status :pending}]
 :signs []
 :created "2026-01-16T10:00:00Z"}

Tools Reference

Planning Tools

Signs (Learnings) Tools

Validation Tools

Loop Management

Signs (Guardrails)

Signs record failures that persist across iterations. When something goes wrong in iteration 3, future iterations can read it and avoid the same mistake. Signs are embedded directly in the LISA_PLAN.edn file.

Signs Format (embedded in LISA_PLAN.edn)

{:title "Build user authentication"
 :status :in-progress
 :checkpoints [...]
 :signs
 [{:checkpoint :jwt-tokens
   :iteration 3
   :timestamp "2026-01-16T10:30:00Z"
   :issue "Forgot to require clojure.string"
   :fix "Always check requires when adding string functions"
   :severity :error}]
 :created "2026-01-16T10:00:00Z"}

When to Append Signs

The spawned Claude instances should append signs when:

• REPL evaluation fails with a fixable error
• Validation check fails due to missing setup
• Common mistake that might recur

The Fresh Instance Advantage

Each iteration gets a fresh Claude context:

This prevents context bloat and hallucination from stale memory.

For /cancel-lisa

Call:

cancel_loop

Or manually kill the orchestrator process.

Example Session

> /lisa-loop "Build user authentication per PRD.md"

I found PRD.md. Let me analyze it for checkpoints...

I propose these checkpoints:
1. Create password hashing (src/auth/password.clj)
2. Create JWT tokens (src/auth/jwt.clj)
3. Create auth middleware (src/middleware/auth.clj)
4. Integration test

Does this look right?

> yes

Creating LISA_PLAN.edn and starting orchestrator...

[Lisa] Iteration 1: Checkpoint 1 - Create password hashing
[Lisa] Checkpoint 1 complete
[Lisa] Iteration 2: Checkpoint 2 - Create JWT tokens
[Lisa] Iteration 2 failed - adding sign
[Lisa] Iteration 3: Checkpoint 2 - Create JWT tokens (retry)
[Lisa] Checkpoint 2 complete
...
[Lisa] All checkpoints complete!

Lisa Loop finished in 6 iterations.