v1.3.0 — Contract Task Descriptions

What's New in v1.3.0

Contract Task Descriptions

Planning agent now generates "contract" task descriptions — specific enough that workers execute without exploring the codebase.

Before (vague):
```

• E2-T1 Implement AppCacheScanner
  ```

After (contract):
```

• E2-T1 Create `Sources/App/Scanners/AppCacheScanner.swift` implementing
  `ScannerProtocol` (`Sources/App/Protocols/ScannerProtocol.swift`).
  Scan `~/Library/Caches/`. Register in `ScannerRegistry.allScanners`
  (`Sources/App/ScannerRegistry.swift`). Return `[ScanResult]` sorted by size.
  ```

Phase 0 — Explore First

build_planning_prompt() now begins with an explicit exploration phase:

1. Find protocol/interface files
2. Read 1–2 existing implementations
3. Find registries and factory files
4. Note naming conventions

Planning agent does this once, so each worker runs without repeating the discovery.

Verified DOC-INDEX Sections

Step B now requires the planning agent to read each section before mapping — confirming it contains the actual interface definition, not just a reference to it.

Token Impact

Stage	Before	After
Planning (runs 1x)	Same	~30% more (exploration)
Worker (runs per task)	High (exploration)	~80% less (contract)
Net for 10 tasks	baseline	~70% fewer total tokens

Files Changed

• ralph.py — build_planning_prompt(): Phase 0 + contract format + Step B verification
• SKILL.md — Step 2: pre-work exploration + contract examples; Step 3: verification rule

v1.2.0 — Parallel Orchestrator

What's new

Parallel execution via git worktrees

Add [parallel] to any epic header in TASKS.md to run its tasks concurrently:

## Epic 2 — Scanners [parallel]

- [ ] **E2-T1** Implement AppCacheScanner
- [ ] **E2-T2** Implement SystemCacheScanner
- [ ] **E2-T3** Implement LogsScanner

The orchestrator:

1. Creates an isolated git worktree per task (.ralph/worktrees/E2-T1/, etc.)
2. Runs all workers simultaneously via ThreadPoolExecutor, streaming prefixed output ([E2-T1] ...)
3. Merges successful branches sequentially into the main tree
4. Runs VERIFY_STEPS once on the merged state
5. Marks all passing tasks done; reverts and re-queues failed ones as sequential

New CLI flags

python ralph.py --no-parallel       # force sequential (disable parallel)
python ralph.py --max-parallel 8    # allow up to 8 concurrent workers

Other changes

• run_claude() now accepts cwd and output_prefix for worker isolation
• All state writes (log_activity, log_progress, add_guardrail) are thread-safe
• show_status() displays [parallel] tag on parallel epic headers
• templates/.gitignore updated: adds .ralph/worktrees/ and planning files
• templates/TASKS.md updated: includes [parallel] example with comment
• README.md: new Parallel Execution section + updated CLI reference
• SKILL.md Step 2: [parallel] syntax documented in format + rules

Upgrade

curl -O https://raw.githubusercontent.com/vansearch/ralphloop-implementation/main/ralph.py

Or re-run the skill in your project:

/ralphloop-implementation

v1.1.0 — Full Restore

What's new in v1.1.0

Files restored

File	Description
ralph.py	Production loop — 841 lines, 6 security hardening measures
setup.py	Project scaffolding script — creates TASKS.md, docs/, .ralph/, .gitignore
README.md	Full documentation with CLI reference and quick-start guide
templates/TASKS.md	Task list template with example epics
templates/docs/DOC-INDEX.md	Routing table template
templates/.ralph/guardrails.md	Guardrails header template
templates/.ralph/progress.md	Progress log header template
templates/.gitignore	.gitignore entries for .ralph/ state files

SKILL.md updated

Step 4 no longer embeds a 690-line ralph.py code block. It now references the standalone file with curl download instructions — keeping SKILL.md focused and readable.

Quick start

# Download to your project
curl -O https://raw.githubusercontent.com/vansearch/ralphloop-implementation/main/ralph.py
curl -O https://raw.githubusercontent.com/vansearch/ralphloop-implementation/main/setup.py

# Scaffold the project
python setup.py --name "My Project" --lang swift

# Start the loop
python ralph.py --dry-run

Or use the Claude Code skill

/ralphloop-implementation

v1.0.0 — Stable Release

Ralph Loop Implementation — Versão Estável

Esta é a versão completa e estável da skill ralphloop-implementation.

O que está incluído

• Doc routing via DOC-INDEX.md — reduz contexto em ~95% por iteração
• Security audit gate — roda OWASP Top 10 após cada plano completo
• Planning mode contínuo — gera novos Epics automaticamente quando tasks acabam
• ralph.py completo (~400 linhas) com CLI: --dry-run, --status, --task, --reset
• Retry automático — 3x por task com backoff
• Guardrails de segurança — sanitização de paths, output em streaming

Como usar

/ralphloop-implementation

Arquivos gerados pelo bootstrapper

• TASKS.md — checklist de tasks
• docs/DOC-INDEX.md — tabela de roteamento task → doc
• ralph.py — loop autônomo externo
• .ralph/ — estado do loop (guardrails, progress, activity log)