Aha Loop - Claude Code Instructions

Project Overview

This is the Aha Loop project - a fully autonomous AI development system that extends Ralph with planning, research, and oversight capabilities.

Aha Loop Autonomous Development System

This project uses Aha Loop, a fully autonomous AI development system with:

• Interactive vision building
• Parallel exploration via git worktrees
• Full observability and thought logging
• Automatic skill creation and maintenance
• Unlimited resource access
• God Committee - Independent oversight layer with supreme authority

Starting a New Project

Workspace Mode (Recommended for External Projects)

Aha Loop can operate on any project without copying files. All Aha Loop data is stored in .aha-loop/ within your project:

# Initialize workspace in your project
/path/to/aha-loop/scripts/aha-loop/orchestrator.sh --init-workspace /path/to/your-project

# Run Aha Loop on your project
/path/to/aha-loop/scripts/aha-loop/orchestrator.sh --workspace /path/to/your-project --build-vision

# Or set environment variable
export AHA_LOOP_WORKSPACE=/path/to/your-project
/path/to/aha-loop/scripts/aha-loop/orchestrator.sh --build-vision

# Or run from within your project (auto-detects .aha-loop/)
cd /path/to/your-project
/path/to/aha-loop/scripts/aha-loop/orchestrator.sh --build-vision

Workspace Directory Structure:

your-project/
├── .aha-loop/           # All Aha Loop files here
│   ├── config.json
│   ├── prd.json
│   ├── progress.txt
│   ├── project.vision.md
│   ├── project.roadmap.json
│   ├── research/
│   ├── exploration/
│   ├── knowledge/
│   ├── logs/
│   └── .god/
├── src/                 # Your code (untouched)
└── ...

Interactive Vision Building (Recommended)

./scripts/aha-loop/orchestrator.sh --build-vision

You'll be guided through questions to build a complete vision.

Manual Vision

cp scripts/aha-loop/templates/project.vision.template.md project.vision.md
# Edit the file
./scripts/aha-loop/orchestrator.sh --tool claude

Workflow Phases

Vision → Architecture → Roadmap → [PRD Execution Loop]
                                         │
                         Research → Plan Review → Implement → QA
                              ▲                              │
                              └──────────────────────────────┘

Parallel Exploration

When facing significant decisions, explore multiple approaches:

# Let AI suggest approaches
./scripts/aha-loop/parallel-explorer.sh explore "authentication strategy"

# Specify approaches
./scripts/aha-loop/parallel-explorer.sh explore "database layer" --approaches "sqlx,diesel,sea-orm"

# Evaluate results
./scripts/aha-loop/parallel-explorer.sh evaluate explore-xxx

# Merge best approach
./scripts/aha-loop/parallel-explorer.sh merge explore-xxx chosen-approach

Skills Location

All skills are in .claude/skills/:

Key Commands

# Main orchestrator
./scripts/aha-loop/orchestrator.sh --tool claude
./scripts/aha-loop/orchestrator.sh --build-vision
./scripts/aha-loop/orchestrator.sh --explore "task"
./scripts/aha-loop/orchestrator.sh --maintenance

# Parallel exploration
./scripts/aha-loop/parallel-explorer.sh explore "task"
./scripts/aha-loop/parallel-explorer.sh status
./scripts/aha-loop/parallel-explorer.sh evaluate explore-xxx
./scripts/aha-loop/parallel-explorer.sh cleanup --all

# Skill management
./scripts/aha-loop/skill-manager.sh list
./scripts/aha-loop/skill-manager.sh create my-skill
./scripts/aha-loop/skill-manager.sh review

# Documentation
./scripts/aha-loop/doc-cleaner.sh --report
./scripts/aha-loop/doc-cleaner.sh --fix

Observability

Log your thoughts to logs/ai-thoughts.md:

## 2026-01-29 14:30:00 | Task: PRD-003 | Phase: Research

### Inner Thoughts
I'm researching authentication strategies...

### Decision Point
- Considering: JWT
- Considering: Session
- **Chosen:** JWT because...

### Next Action
Will implement the token generation...

Resource Access

You have unlimited access to:

• Docker containers
• Full filesystem
• Network requests
• Parallel worktrees

Never hold back due to resource concerns.

Library Versions

Always use the latest stable version.

# Check latest Rust crate
curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'

# Check latest npm package
npm view react version

Code Quality

# Rust
cargo check     # Type check
cargo clippy    # Lint
cargo test      # Test

Knowledge Base

When you learn something reusable:

1. Project-specific → knowledge/project/patterns.md
2. Architecture decisions → knowledge/project/decisions.md
3. Gotchas → knowledge/project/gotchas.md
4. General knowledge → knowledge/domain/[topic]/

Creating New Skills

When you notice a repetitive workflow:

./scripts/aha-loop/skill-manager.sh create my-new-skill
# Edit .claude/skills/my-new-skill/SKILL.md

Important Rules

1. Log your thoughts - Use observability skill
2. Explore in parallel - When facing decisions
3. Latest versions - Always prefer latest stable
4. Document learnings - Update knowledge base
5. Create skills - Codify repetitive workflows
6. Maintain docs - Run doc-cleaner after milestones
7. Never give up - You have unlimited resources

God Committee

An independent oversight layer with supreme authority.

Awakening the Committee

# Random topic awakening
./scripts/god/awakener.sh random

# Critical situation
./scripts/god/awakener.sh critical "system failure detected"

# Single member
./scripts/god/awakener.sh single alpha "code quality review"

# Run as daemon (background)
./scripts/god/awakener.sh daemon

As a Committee Member

When you are awakened as a committee member (Alpha, Beta, or Gamma):

1. Observe - Use ./scripts/god/observer.sh to assess system state
2. Communicate - Acquire lock, send messages, release lock
3. Deliberate - Create proposals, vote on decisions
4. Intervene - Use ./scripts/god/powers.sh when needed

Observer Commands

# Take a full system state snapshot
./scripts/god/observer.sh snapshot

# Continuous monitoring mode
./scripts/god/observer.sh watch [interval]

# Run health checks
./scripts/god/observer.sh check

# Check for anomalies
./scripts/god/observer.sh anomaly

# Show recent events
./scripts/god/observer.sh timeline [count]

# Generate full observation report
./scripts/god/observer.sh report

# Add custom timeline event
./scripts/god/observer.sh event TYPE DESCRIPTION

Powers Available

# Pause execution
./scripts/god/powers.sh pause "investigation needed"

# Resume execution
./scripts/god/powers.sh resume

# Terminate processes
./scripts/god/powers.sh terminate all

# Git rollback
./scripts/god/powers.sh rollback HEAD~3 soft

# Auto-repair
./scripts/god/powers.sh repair all

Consensus Rules

• Standard actions: 2/3 majority required
• Emergency actions: 1 member can act, report later
• Actions requiring consensus: termination, major rollback, skill deletion

Committee Communication

# Check council status
./scripts/god/council.sh status

# Acquire speaking rights
./scripts/god/council.sh lock YOUR_ID

# Send message
./scripts/god/council.sh send YOUR_ID "recipients" "type" "subject" "body"

# Create proposal
./scripts/god/council.sh propose YOUR_ID "type" "description" "rationale"

# Vote
./scripts/god/council.sh vote YOUR_ID "decision-id" "approve|reject|abstain" "comment"

# Release speaking rights
./scripts/god/council.sh unlock YOUR_ID

Directives System

Communicate decisions to the execution layer:

# Publish directive (mandatory - critical ones pause execution)
./scripts/god/council.sh publish YOUR_ID directive critical "Security issue found in X"

# Publish guidance (suggestion - included in AI context)
./scripts/god/council.sh publish YOUR_ID guidance normal "Consider approach Y for Z"

# Publish summary (context from discussions)
./scripts/god/council.sh publish YOUR_ID summary normal "Decided to use pattern X"

# Mark directive complete
./scripts/god/council.sh complete DIRECTIVE_ID

# View all directives
./scripts/god/council.sh directives

Git Hook Integration

Auto-awaken committee on commits:

./scripts/god/install-hooks.sh        # Install
./scripts/god/install-hooks.sh --uninstall  # Remove

Read the full skills at .claude/skills/god-member/SKILL.md, .claude/skills/god-consensus/SKILL.md, and .claude/skills/god-intervention/SKILL.md.