[P3] Phase 3.3: Create CLI options documentation

[frankbria]

Description

Create documentation for Ralph's modern CLI options so users don't have to dig through CLAUDE.md.

Document to Create

docs/CLI_OPTIONS.md

Document all modern CLI flags:

• --output-format json|text — structured output format
• --allowed-tools "Write,Read,Bash(git *)" — restrict permitted tools
• --no-continue — disable session continuity, start fresh each loop
• --monitor — launch integrated tmux monitoring
• --live — stream output in real time
• --calls N — max API calls per hour
• --prompt FILE — custom prompt file path
• --reset-circuit, --circuit-status, --auto-reset-circuit — circuit breaker management
• --reset-session — reset session state manually
• Examples for each option
• Best practices and common .ralphrc patterns

Note

SDK documentation — removed. SDK integration was closed as won't-implement (#32–35). CLI is the definitive interface.

Acceptance Criteria

• docs/CLI_OPTIONS.md created with all flags documented
• Each flag includes purpose, syntax, and example
• Common .ralphrc configuration patterns documented

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The GitHub issue specifies creating docs/CLI_OPTIONS.md to document Ralph's modern CLI flags. The ticket lists 9 specific flags: --output-format json|text, --allowed-tools, --no-continue, --monitor, --live, --calls, --prompt, --reset-circuit/--circuit-status/--auto-reset-circuit, and --reset-session. SDK documentation has been removed (won't-implement). The README contains scattered CLI documentation (lines 393-577) and .ralphrc examples. The docs/ directory does not exist. The ticket emphasizes documenting "modern CLI flags" and "common .ralphrc patterns" as acceptance criteria.

Approach

Create a focused docs/CLI_OPTIONS.md file consolidating CLI documentation from README.md and ralph_loop.sh. Organize flags into logical groups (basic, monitoring, modern options, circuit breaker, session management), provide syntax, defaults, examples, and best practices. Include .ralphrc configuration patterns and common use cases. This centralizes CLI reference while maintaining consistency with existing documentation.

Implementation Steps

1. Create docs/ Directory

Create the docs/ directory at the repository root.

2. Create docs/CLI_OPTIONS.md

Create comprehensive CLI reference with these sections:

Section 1: Overview & Quick Reference

• Brief introduction to Ralph CLI
• Quick reference table of all flags
• Link to .ralphrc configuration section

Section 2: Basic Options

Document from file:ralph_loop.sh (lines 2100-2103):

• -h, --help: Show help message
• -c, --calls NUM: Max API calls per hour (default: 100)
• -p, --prompt FILE: Custom prompt file (default: .ralph/PROMPT.md)
• -s, --status: Show current status JSON

For each: syntax, description, default, valid range, example, when to use.

Section 3: Monitoring & Output Options

Document from file:ralph_loop.sh (lines 2104-2106):

• -m, --monitor: Launch tmux monitoring
• -v, --verbose: Detailed progress updates
• -l, --live: Real-time output streaming (auto-switches to JSON)

Include: how monitoring works, verbose details, live streaming behavior, combining flags.

Section 4: Execution Control

Document from file:ralph_loop.sh (line 2107):

• -t, --timeout MIN: Claude timeout (1-120 minutes, default: 15)

Include: timeout behavior, when to adjust, examples for different project sizes.

Section 5: Modern CLI Options

Document from file:ralph_loop.sh (lines 2113-2118):

• --output-format FORMAT: Output format (json or text, default: json)
• --allowed-tools TOOLS: Restrict permitted tools
• --no-continue: Disable session continuity
• --session-expiry HOURS: Session expiration (default: 24)

For each: purpose, syntax, valid values, default, examples, .ralphrc equivalent.

Section 6: Circuit Breaker Management

Document from file:ralph_loop.sh (lines 2108-2110, 2246-2248):

• --reset-circuit: Reset to CLOSED state
• --circuit-status: Show circuit status
• --auto-reset-circuit: Auto-reset on startup

Include: what circuit breaker does, when to use each, auto-recovery behavior, cooldown configuration.

Section 7: Session Management

Document from file:ralph_loop.sh (lines 2203-2209):

• --reset-session: Reset session state and exit

Include: when needed, difference from --reset-circuit, auto-reset triggers, session files.

Section 8: .ralphrc Configuration Patterns

Reference file:README.md (lines 394-428) and document:

• Complete .ralphrc template with all options
• Common patterns:
  • Development: High call limit, verbose output
  • Production: Lower call limit, circuit breaker tuning
  • Tool-restricted: Specific ALLOWED_TOOLS patterns
  • Long-running: Extended timeout, session expiry
  • Quick iteration: Low timeout, no session continuity
• CLI flag override behavior
• Environment variable precedence

Section 9: Practical Examples

Organize by use case:

• Basic Usage: Single-flag examples
• Monitoring & Debugging: --monitor, --verbose, --live combinations
• Rate Limiting: --calls with different thresholds
• Custom Prompts: --prompt examples
• Session Management: --no-continue, --reset-session, --session-expiry
• Circuit Breaker Recovery: --reset-circuit, --auto-reset-circuit
• Complex Projects: Multiple flags combined

Section 10: Best Practices

Include:

• Monitoring vs background execution
• Timeout values by project complexity
• Tool restriction patterns
• Session continuity trade-offs
• Rate limiting strategies
• Circuit breaker tuning
• Flag combinations

Section 11: Troubleshooting

Document common issues:

• Permission denied errors (reference README lines 1984-2003)
• Session continuity issues
• Circuit breaker false positives
• Timeout configuration
• Tool restriction problems
• API limit handling

Section 12: Exit Codes & Status

Document:

• Exit code meanings (0=success, 1=error, 2=API limit, 3=circuit breaker)
• Status file JSON structure
• Interpreting status output

3. Add Mermaid Diagrams

Include visual aids showing flag categories and interaction flow.

4. Update file:README.md

Add reference section after line 392:

## 📚 CLI Documentation

For comprehensive CLI flag reference, see **[CLI Options Guide](docs/CLI_OPTIONS.md)**.

Update existing sections to link to new doc:

• Line 393: Add reference to CLI_OPTIONS.md
• Line 430: Add link for rate limiting details
• Line 483: Add link for custom prompts

5. Content Sourcing

Primary sources:

• file:ralph_loop.sh lines 2089-2147 (help text)
• file:ralph_loop.sh lines 2150-2256 (argument parsing)
• file:README.md lines 393-577 (existing CLI docs)
• file:CLAUDE.md lines 199-272 (configuration)

6. Validation Checklist

1. All 9 flags from ticket documented
2. Flag syntax matches file:ralph_loop.sh implementation
3. Each flag has practical examples
4. Terminology consistent with README and CLAUDE.md
5. Cross-references work correctly
6. Markdown renders on GitHub
7. Mermaid diagrams display properly
8. Logical flag grouping

7. File Structure

docs/
└── CLI_OPTIONS.md          # Comprehensive CLI reference

Update README.md with reference to new doc.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The GitHub issue specifies creating `docs/CLI_OPTIONS.md` to document Ralph's modern CLI flags. The ticket lists 9 specific flags: `--output-format json|text`, `--allowed-tools`, `--no-continue`, `--monitor`, `--live`, `--calls`, `--prompt`, `--reset-circuit`/`--circuit-status`/`--auto-reset-circuit`, and `--reset-session`. SDK documentation has been removed (won't-implement). The README contains scattered CLI documentation (lines 393-577) and `.ralphrc` examples. The `docs/` directory does not exist. The ticket emphasizes documenting "modern CLI flags" and "common .ralphrc patterns" as acceptance criteria.

## Approach

Create a focused `docs/CLI_OPTIONS.md` file consolidating CLI documentation from `README.md` and `ralph_loop.sh`. Organize flags into logical groups (basic, monitoring, modern options, circuit breaker, session management), provide syntax, defaults, examples, and best practices. Include `.ralphrc` configuration patterns and common use cases. This centralizes CLI reference while maintaining consistency with existing documentation.

## Implementation Steps

### 1. Create `docs/` Directory

Create the `docs/` directory at the repository root.

### 2. Create `docs/CLI_OPTIONS.md`

Create comprehensive CLI reference with these sections:

**Section 1: Overview & Quick Reference**
- Brief introduction to Ralph CLI
- Quick reference table of all flags
- Link to `.ralphrc` configuration section

**Section 2: Basic Options**

Document from `file:ralph_loop.sh` (lines 2100-2103):
- `-h, --help`: Show help message
- `-c, --calls NUM`: Max API calls per hour (default: 100)
- `-p, --prompt FILE`: Custom prompt file (default: `.ralph/PROMPT.md`)
- `-s, --status`: Show current status JSON

For each: syntax, description, default, valid range, example, when to use.

**Section 3: Monitoring & Output Options**

Document from `file:ralph_loop.sh` (lines 2104-2106):
- `-m, --monitor`: Launch tmux monitoring
- `-v, --verbose`: Detailed progress updates
- `-l, --live`: Real-time output streaming (auto-switches to JSON)

Include: how monitoring works, verbose details, live streaming behavior, combining flags.

**Section 4: Execution Control**

Document from `file:ralph_loop.sh` (line 2107):
- `-t, --timeout MIN`: Claude timeout (1-120 minutes, default: 15)

Include: timeout behavior, when to adjust, examples for different project sizes.

**Section 5: Modern CLI Options**

Document from `file:ralph_loop.sh` (lines 2113-2118):
- `--output-format FORMAT`: Output format (json or text, default: json)
- `--allowed-tools TOOLS`: Restrict permitted tools
- `--no-continue`: Disable session continuity
- `--session-expiry HOURS`: Session expiration (default: 24)

For each: purpose, syntax, valid values, default, examples, `.ralphrc` equivalent.

**Section 6: Circuit Breaker Management**

Document from `file:ralph_loop.sh` (lines 2108-2110, 2246-2248):
- `--reset-circuit`: Reset to CLOSED state
- `--circuit-status`: Show circuit status
- `--auto-reset-circuit`: Auto-reset on startup

Include: what circuit breaker does, when to use each, auto-recovery behavior, cooldown configuration.

**Section 7: Session Management**

Document from `file:ralph_loop.sh` (lines 2203-2209):
- `--reset-session`: Reset session state and exit

Include: when needed, difference from `--reset-circuit`, auto-reset triggers, session files.

**Section 8: .ralphrc Configuration Patterns**

Reference `file:README.md` (lines 394-428) and document:
- Complete `.ralphrc` template with all options
- Common patterns:
  - **Development**: High call limit, verbose output
  - **Production**: Lower call limit, circuit breaker tuning
  - **Tool-restricted**: Specific ALLOWED_TOOLS patterns
  - **Long-running**: Extended timeout, session expiry
  - **Quick iteration**: Low timeout, no session continuity
- CLI flag override behavior
- Environment variable precedence

**Section 9: Practical Examples**

Organize by use case:
- **Basic Usage**: Single-flag examples
- **Monitoring & Debugging**: `--monitor`, `--verbose`, `--live` combinations
- **Rate Limiting**: `--calls` with different thresholds
- **Custom Prompts**: `--prompt` examples
- **Session Management**: `--no-continue`, `--reset-session`, `--session-expiry`
- **Circuit Breaker Recovery**: `--reset-circuit`, `--auto-reset-circuit`
- **Complex Projects**: Multiple flags combined

**Section 10: Best Practices**

Include:
- Monitoring vs background execution
- Timeout values by project complexity
- Tool restriction patterns
- Session continuity trade-offs
- Rate limiting strategies
- Circuit breaker tuning
- Flag combinations

**Section 11: Troubleshooting**

Document common issues:
- Permission denied errors (reference README lines 1984-2003)
- Session continuity issues
- Circuit breaker false positives
- Timeout configuration
- Tool restriction problems
- API limit handling

**Section 12: Exit Codes & Status**

Document:
- Exit code meanings (0=success, 1=error, 2=API limit, 3=circuit breaker)
- Status file JSON structure
- Interpreting status output

### 3. Add Mermaid Diagrams

Include visual aids showing flag categories and interaction flow.

### 4. Update `file:README.md`

Add reference section after line 392:
```markdown
## 📚 CLI Documentation

For comprehensive CLI flag reference, see **[CLI Options Guide](docs/CLI_OPTIONS.md)**.
```

Update existing sections to link to new doc:
- Line 393: Add reference to CLI_OPTIONS.md
- Line 430: Add link for rate limiting details
- Line 483: Add link for custom prompts

### 5. Content Sourcing

**Primary sources:**
- `file:ralph_loop.sh` lines 2089-2147 (help text)
- `file:ralph_loop.sh` lines 2150-2256 (argument parsing)
- `file:README.md` lines 393-577 (existing CLI docs)
- `file:CLAUDE.md` lines 199-272 (configuration)

### 6. Validation Checklist

1. All 9 flags from ticket documented
2. Flag syntax matches `file:ralph_loop.sh` implementation
3. Each flag has practical examples
4. Terminology consistent with README and CLAUDE.md
5. Cross-references work correctly
6. Markdown renders on GitHub
7. Mermaid diagrams display properly
8. Logical flag grouping

### 7. File Structure

```
docs/
└── CLI_OPTIONS.md          # Comprehensive CLI reference
```

Update `README.md` with reference to new doc.

---

Execution Information

Branch: main
Commit: 8c7a7d9

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#47 - [P1] feat(cli): add modern CLI commands with JSON output support (Phase 1.1) [merged]
#52 - test(cli): add comprehensive CLI argument parsing tests [merged]
#166 - fix(live-mode): crash with text output format (#164) [merged]
#191 - feat(loop): validate Claude Code CLI command at startup (#97) [merged]
#231 - fix(loop): respect .ralphrc CLAUDE_CODE_CMD; add CLAUDE_MODEL/EFFORT (#228) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[wtthornton]

Completed via epic/story system. All 148/148 stories across 40 epics are done. See IMPLEMENTATION_STATUS.md for details.

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The GitHub issue references CLI options (--output-format json, --allowedTools, --continue, --append-system-prompt) and an "Agent SDK" that do not exist in the current codebase. The actual implementation is a bash script-based autonomous development loop with different CLI options. The existing CLI flags are: --help, --calls, --prompt, --status, --monitor, --verbose, --timeout, --reset-circuit, and --circuit-status. There is no SDK; instead, Ralph uses template files (PROMPT.md, @AGENT.md) to guide Claude Code's autonomous behavior. The docs/ directory does not exist yet.

Approach

Create documentation for the actual implemented features rather than non-existent ones. Establish a docs/ directory structure and create three documentation files: CLI_OPTIONS.md documenting real CLI flags with examples, AGENT_INTEGRATION.md (not SDK) explaining how Ralph works as an autonomous agent using templates, and update README.md to reference these new docs. This approach documents what exists while maintaining clarity about Ralph's architecture as a bash-based autonomous loop rather than an SDK.

Implementation Steps

1. Create Documentation Directory Structure

Create the docs/ directory at the repository root to house all documentation files:

docs/
├── CLI_OPTIONS.md
├── AGENT_INTEGRATION.md
└── MIGRATION_GUIDE.md (optional)

2. Create docs/CLI_OPTIONS.md

Document all actual CLI options from file:ralph_loop.sh (lines 631-691):

Content Structure:

• Overview: Brief introduction to Ralph CLI
• Global Commands: Document ralph, ralph-monitor, ralph-setup, ralph-import
• Ralph Loop Options: Document each flag with:
  • Flag syntax (short and long form)
  • Description
  • Default value
  • Valid range/values
  • Usage example
  • Common use cases

Flags to Document:

• -h, --help: Show help message
• -c, --calls NUM: Set max API calls per hour (default: 100)
• -p, --prompt FILE: Set prompt file (default: PROMPT.md)
• -s, --status: Show current status JSON
• -m, --monitor: Start with tmux monitoring
• -v, --verbose: Enable detailed progress updates
• -t, --timeout MIN: Set Claude Code timeout (1-120 minutes, default: 15)
• --reset-circuit: Reset circuit breaker state
• --circuit-status: Show circuit breaker status

Include Sections:

• Basic Examples: Simple single-flag usage
• Advanced Examples: Multiple flags combined
• Best Practices: When to use each option
• Troubleshooting: Common issues with CLI flags
• Exit Codes: Document return codes (0=success, 1=error, 2=API limit, 3=circuit breaker)

Reference Files:

• file:ralph_loop.sh (lines 591-628 for help text, lines 631-691 for argument parsing)
• file:README.md (lines 538-567 for existing CLI documentation)

3. Create docs/AGENT_INTEGRATION.md

Since there is no SDK, document Ralph's agent-based architecture instead:

Content Structure:

Section 1: Understanding Ralph as an Agent

• Explain Ralph is not an SDK but an autonomous agent loop
• Architecture: bash scripts + Claude Code CLI + template system
• How Ralph differs from traditional SDKs

Section 2: Agent Templates

• Document file:templates/PROMPT.md - Instructions for Claude Code
• Document file:templates/AGENT.md - Build and quality standards
• Document file:templates/fix_plan.md - Task management
• Explain how these templates guide autonomous behavior

Section 3: Integration Patterns

• Pattern 1: Using Ralph for new projects (ralph-setup)
• Pattern 2: Importing existing requirements (ralph-import)
• Pattern 3: Customizing agent behavior (editing PROMPT.md)
• Pattern 4: Monitoring and control (ralph-monitor, status.json)

Section 4: Library Components

• Document file:lib/circuit_breaker.sh - Prevents runaway loops
• Document file:lib/response_analyzer.sh - Detects completion signals
• Document file:lib/date_utils.sh - Cross-platform utilities
• Explain how these modules work together

Section 5: Exit Detection System

• Explain intelligent exit conditions from file:ralph_loop.sh (lines 236-304)
• Document exit signals file format (.exit_signals)
• Explain circuit breaker thresholds
• Show how to configure exit behavior

Section 6: Custom Tools via Templates

• How to add custom build commands in @AGENT.md
• How to define custom workflows in PROMPT.md
• How to integrate with project-specific tools
• Examples of customization

Section 7: Performance Considerations

• Rate limiting configuration
• Timeout settings for different project sizes
• Circuit breaker tuning
• Log management

Section 8: Troubleshooting

• Common integration issues
• Debugging agent behavior
• Circuit breaker recovery
• Log analysis

Reference Files:

• file:CLAUDE.md (lines 1-337 for architecture overview)
• file:templates/PROMPT.md (lines 1-282 for agent instructions)
• file:templates/AGENT.md (lines 1-159 for quality standards)
• file:lib/circuit_breaker.sh and file:lib/response_analyzer.sh

4. Update file:README.md

Add new sections referencing the documentation:

Location: After line 567 (end of Command Reference section)

New Section: "📚 Documentation"

## 📚 Documentation

### Core Documentation
- **[CLI Options Guide](docs/CLI_OPTIONS.md)** - Complete reference for all command-line flags
- **[Agent Integration Guide](docs/AGENT_INTEGRATION.md)** - Understanding Ralph's autonomous agent architecture
- **[CLAUDE.md](CLAUDE.md)** - Technical architecture and library components

### Getting Started
- **[Quick Start](#-quick-start)** - Installation and first project
- **[How It Works](#-how-it-works)** - Understanding the autonomous loop
- **[Best Practices](#-best-practices)** - Writing effective prompts

### Advanced Topics
- **[Configuration](#-configuration)** - Rate limiting, timeouts, circuit breaker
- **[Monitoring](#-monitoring-and-debugging)** - Live dashboard and debugging
- **[Contributing](#-contributing)** - Development guidelines

Update Section: "🚀 Quick Start" (around line 67)
Add reference to CLI options:

For detailed CLI options, see [CLI Options Guide](docs/CLI_OPTIONS.md).

Update Section: "🛠️ Configuration" (around line 200)
Add reference to agent integration:

For advanced integration patterns, see [Agent Integration Guide](docs/AGENT_INTEGRATION.md).

5. Create Cross-Reference Links

Ensure bidirectional linking between documents:

In docs/CLI_OPTIONS.md:

• Link to file:README.md for quick start
• Link to docs/AGENT_INTEGRATION.md for advanced usage
• Link to file:CLAUDE.md for architecture details

In docs/AGENT_INTEGRATION.md:

• Link to docs/CLI_OPTIONS.md for command reference
• Link to file:README.md for installation
• Link to file:templates/PROMPT.md and file:templates/AGENT.md examples

In file:README.md:

• Link to both new docs files
• Update table of contents if present

6. Add Examples and Diagrams

For docs/CLI_OPTIONS.md:

Include practical examples:

# Example 1: Basic usage with monitoring
ralph --monitor

# Example 2: Limited API calls for testing
ralph --calls 10 --verbose

# Example 3: Long-running complex project
ralph --monitor --timeout 60 --calls 50

# Example 4: Custom prompt file
ralph --prompt custom_instructions.md --monitor

For docs/AGENT_INTEGRATION.md:

Add Mermaid sequence diagram showing Ralph's autonomous loop:

sequenceDiagram
    participant User
    participant Ralph
    participant CircuitBreaker
    participant Claude
    participant ResponseAnalyzer
    
    User->>Ralph: ralph --monitor
    Ralph->>Ralph: Load PROMPT.md
    loop Autonomous Loop
        Ralph->>CircuitBreaker: Check if should halt
        CircuitBreaker-->>Ralph: Continue
        Ralph->>Claude: Execute with PROMPT.md
        Claude-->>Ralph: Output + Status
        Ralph->>ResponseAnalyzer: Analyze response
        ResponseAnalyzer-->>Ralph: Exit signals
        alt Exit condition met
            Ralph->>User: Graceful exit
        else Continue
            Ralph->>Ralph: Update status.json
        end
    end

Loading

Add architecture diagram showing component relationships:

graph TD
    A[ralph CLI] --> B[ralph_loop.sh]
    B --> C[lib/circuit_breaker.sh]
    B --> D[lib/response_analyzer.sh]
    B --> E[lib/date_utils.sh]
    B --> F[Claude Code CLI]
    B --> G[PROMPT.md]
    B --> H[status.json]
    I[ralph-monitor] --> H
    J[templates/] --> K[New Projects]
    K --> G

Loading

7. Address Issue Discrepancies

Create a note in docs/CLI_OPTIONS.md addressing the missing features:

Section: "Planned Features (Not Yet Implemented)"

## Planned Features

The following features are referenced in issue #38 but not yet implemented:

- `--output-format json`: Structured JSON output format
- `--allowedTools`: Tool restriction configuration
- `--continue`: Resume from previous state
- `--append-system-prompt`: Custom system prompt injection

These features are planned for future releases. Track progress in:
- Issue #7 (Phase 3.3)
- Issues #24-27 (related documentation)

8. Validation Steps

Before considering documentation complete:

1. Verify all CLI flags documented match file:ralph_loop.sh implementation
2. Test all examples in CLI_OPTIONS.md work correctly
3. Validate links between all documentation files
4. Check Mermaid diagrams render correctly on GitHub
5. Review consistency with existing file:README.md and file:CLAUDE.md
6. Ensure templates referenced in AGENT_INTEGRATION.md exist and are accurate

File Reference Summary

File	Purpose	Lines of Interest
file:ralph_loop.sh	Main CLI implementation	591-628 (help), 631-691 (arg parsing)
file:README.md	Main documentation	538-567 (CLI reference), entire file for context
file:CLAUDE.md	Architecture guide	1-337 (complete architecture)
file:templates/PROMPT.md	Agent instructions template	1-282 (complete template)
file:templates/AGENT.md	Quality standards template	1-159 (complete template)
file:lib/circuit_breaker.sh	Circuit breaker module	Entire file
file:lib/response_analyzer.sh	Response analysis module	Entire file
file:IMPLEMENTATION_STATUS.md	Current project status	Entire file for context

Architecture Visualization

graph TD
    subgraph "New Documentation"
        A[docs/CLI_OPTIONS.md]
        B[docs/AGENT_INTEGRATION.md]
    end
    
    subgraph "Existing Documentation"
        C[README.md]
        D[CLAUDE.md]
        E[templates/PROMPT.md]
        F[templates/AGENT.md]
    end
    
    subgraph "Implementation"
        G[ralph_loop.sh]
        H[lib/circuit_breaker.sh]
        I[lib/response_analyzer.sh]
    end
    
    A -->|references| G
    A -->|links to| C
    A -->|links to| B
    B -->|references| E
    B -->|references| F
    B -->|references| H
    B -->|references| I
    B -->|links to| D
    C -->|links to| A
    C -->|links to| B

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The GitHub issue references CLI options (`--output-format json`, `--allowedTools`, `--continue`, `--append-system-prompt`) and an "Agent SDK" that do not exist in the current codebase. The actual implementation is a bash script-based autonomous development loop with different CLI options. The existing CLI flags are: `--help`, `--calls`, `--prompt`, `--status`, `--monitor`, `--verbose`, `--timeout`, `--reset-circuit`, and `--circuit-status`. There is no SDK; instead, Ralph uses template files (`PROMPT.md`, `@AGENT.md`) to guide Claude Code's autonomous behavior. The `docs/` directory does not exist yet.

## Approach

Create documentation for the **actual implemented features** rather than non-existent ones. Establish a `docs/` directory structure and create three documentation files: `CLI_OPTIONS.md` documenting real CLI flags with examples, `AGENT_INTEGRATION.md` (not SDK) explaining how Ralph works as an autonomous agent using templates, and update `README.md` to reference these new docs. This approach documents what exists while maintaining clarity about Ralph's architecture as a bash-based autonomous loop rather than an SDK.

## Implementation Steps

### 1. Create Documentation Directory Structure

Create the `docs/` directory at the repository root to house all documentation files:

```
docs/
├── CLI_OPTIONS.md
├── AGENT_INTEGRATION.md
└── MIGRATION_GUIDE.md (optional)
```

### 2. Create `docs/CLI_OPTIONS.md`

Document all **actual** CLI options from `file:ralph_loop.sh` (lines 631-691):

**Content Structure:**
- **Overview**: Brief introduction to Ralph CLI
- **Global Commands**: Document `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`
- **Ralph Loop Options**: Document each flag with:
  - Flag syntax (short and long form)
  - Description
  - Default value
  - Valid range/values
  - Usage example
  - Common use cases

**Flags to Document:**
- `-h, --help`: Show help message
- `-c, --calls NUM`: Set max API calls per hour (default: 100)
- `-p, --prompt FILE`: Set prompt file (default: PROMPT.md)
- `-s, --status`: Show current status JSON
- `-m, --monitor`: Start with tmux monitoring
- `-v, --verbose`: Enable detailed progress updates
- `-t, --timeout MIN`: Set Claude Code timeout (1-120 minutes, default: 15)
- `--reset-circuit`: Reset circuit breaker state
- `--circuit-status`: Show circuit breaker status

**Include Sections:**
- **Basic Examples**: Simple single-flag usage
- **Advanced Examples**: Multiple flags combined
- **Best Practices**: When to use each option
- **Troubleshooting**: Common issues with CLI flags
- **Exit Codes**: Document return codes (0=success, 1=error, 2=API limit, 3=circuit breaker)

**Reference Files:**
- `file:ralph_loop.sh` (lines 591-628 for help text, lines 631-691 for argument parsing)
- `file:README.md` (lines 538-567 for existing CLI documentation)

### 3. Create `docs/AGENT_INTEGRATION.md`

Since there is no SDK, document Ralph's **agent-based architecture** instead:

**Content Structure:**

**Section 1: Understanding Ralph as an Agent**
- Explain Ralph is not an SDK but an autonomous agent loop
- Architecture: bash scripts + Claude Code CLI + template system
- How Ralph differs from traditional SDKs

**Section 2: Agent Templates**
- Document `file:templates/PROMPT.md` - Instructions for Claude Code
- Document `file:templates/AGENT.md` - Build and quality standards
- Document `file:templates/fix_plan.md` - Task management
- Explain how these templates guide autonomous behavior

**Section 3: Integration Patterns**
- **Pattern 1**: Using Ralph for new projects (`ralph-setup`)
- **Pattern 2**: Importing existing requirements (`ralph-import`)
- **Pattern 3**: Customizing agent behavior (editing PROMPT.md)
- **Pattern 4**: Monitoring and control (`ralph-monitor`, status.json)

**Section 4: Library Components**
- Document `file:lib/circuit_breaker.sh` - Prevents runaway loops
- Document `file:lib/response_analyzer.sh` - Detects completion signals
- Document `file:lib/date_utils.sh` - Cross-platform utilities
- Explain how these modules work together

**Section 5: Exit Detection System**
- Explain intelligent exit conditions from `file:ralph_loop.sh` (lines 236-304)
- Document exit signals file format (`.exit_signals`)
- Explain circuit breaker thresholds
- Show how to configure exit behavior

**Section 6: Custom Tools via Templates**
- How to add custom build commands in `@AGENT.md`
- How to define custom workflows in `PROMPT.md`
- How to integrate with project-specific tools
- Examples of customization

**Section 7: Performance Considerations**
- Rate limiting configuration
- Timeout settings for different project sizes
- Circuit breaker tuning
- Log management

**Section 8: Troubleshooting**
- Common integration issues
- Debugging agent behavior
- Circuit breaker recovery
- Log analysis

**Reference Files:**
- `file:CLAUDE.md` (lines 1-337 for architecture overview)
- `file:templates/PROMPT.md` (lines 1-282 for agent instructions)
- `file:templates/AGENT.md` (lines 1-159 for quality standards)
- `file:lib/circuit_breaker.sh` and `file:lib/response_analyzer.sh`

### 4. Update `file:README.md`

Add new sections referencing the documentation:

**Location**: After line 567 (end of Command Reference section)

**New Section: "📚 Documentation"**
```markdown
## 📚 Documentation

### Core Documentation
- **[CLI Options Guide](docs/CLI_OPTIONS.md)** - Complete reference for all command-line flags
- **[Agent Integration Guide](docs/AGENT_INTEGRATION.md)** - Understanding Ralph's autonomous agent architecture
- **[CLAUDE.md](CLAUDE.md)** - Technical architecture and library components

### Getting Started
- **[Quick Start](#-quick-start)** - Installation and first project
- **[How It Works](#-how-it-works)** - Understanding the autonomous loop
- **[Best Practices](#-best-practices)** - Writing effective prompts

### Advanced Topics
- **[Configuration](#-configuration)** - Rate limiting, timeouts, circuit breaker
- **[Monitoring](#-monitoring-and-debugging)** - Live dashboard and debugging
- **[Contributing](#-contributing)** - Development guidelines
```

**Update Section: "🚀 Quick Start"** (around line 67)
Add reference to CLI options:
```markdown
For detailed CLI options, see [CLI Options Guide](docs/CLI_OPTIONS.md).
```

**Update Section: "🛠️ Configuration"** (around line 200)
Add reference to agent integration:
```markdown
For advanced integration patterns, see [Agent Integration Guide](docs/AGENT_INTEGRATION.md).
```

### 5. Create Cross-Reference Links

Ensure bidirectional linking between documents:

**In `docs/CLI_OPTIONS.md`:**
- Link to `file:README.md` for quick start
- Link to `docs/AGENT_INTEGRATION.md` for advanced usage
- Link to `file:CLAUDE.md` for architecture details

**In `docs/AGENT_INTEGRATION.md`:**
- Link to `docs/CLI_OPTIONS.md` for command reference
- Link to `file:README.md` for installation
- Link to `file:templates/PROMPT.md` and `file:templates/AGENT.md` examples

**In `file:README.md`:**
- Link to both new docs files
- Update table of contents if present

### 6. Add Examples and Diagrams

**For `docs/CLI_OPTIONS.md`:**

Include practical examples:
```bash
# Example 1: Basic usage with monitoring
ralph --monitor

# Example 2: Limited API calls for testing
ralph --calls 10 --verbose

# Example 3: Long-running complex project
ralph --monitor --timeout 60 --calls 50

# Example 4: Custom prompt file
ralph --prompt custom_instructions.md --monitor
```

**For `docs/AGENT_INTEGRATION.md`:**

Add Mermaid sequence diagram showing Ralph's autonomous loop:

```mermaid
sequenceDiagram
    participant User
    participant Ralph
    participant CircuitBreaker
    participant Claude
    participant ResponseAnalyzer
    
    User->>Ralph: ralph --monitor
    Ralph->>Ralph: Load PROMPT.md
    loop Autonomous Loop
        Ralph->>CircuitBreaker: Check if should halt
        CircuitBreaker-->>Ralph: Continue
        Ralph->>Claude: Execute with PROMPT.md
        Claude-->>Ralph: Output + Status
        Ralph->>ResponseAnalyzer: Analyze response
        ResponseAnalyzer-->>Ralph: Exit signals
        alt Exit condition met
            Ralph->>User: Graceful exit
        else Continue
            Ralph->>Ralph: Update status.json
        end
    end
```

Add architecture diagram showing component relationships:

```mermaid
graph TD
    A[ralph CLI] --> B[ralph_loop.sh]
    B --> C[lib/circuit_breaker.sh]
    B --> D[lib/response_analyzer.sh]
    B --> E[lib/date_utils.sh]
    B --> F[Claude Code CLI]
    B --> G[PROMPT.md]
    B --> H[status.json]
    I[ralph-monitor] --> H
    J[templates/] --> K[New Projects]
    K --> G
```

### 7. Address Issue Discrepancies

Create a note in `docs/CLI_OPTIONS.md` addressing the missing features:

**Section: "Planned Features (Not Yet Implemented)"**
```markdown
## Planned Features

The following features are referenced in issue #38 but not yet implemented:

- `--output-format json`: Structured JSON output format
- `--allowedTools`: Tool restriction configuration
- `--continue`: Resume from previous state
- `--append-system-prompt`: Custom system prompt injection

These features are planned for future releases. Track progress in:
- Issue #7 (Phase 3.3)
- Issues #24-27 (related documentation)
```

### 8. Validation Steps

Before considering documentation complete:

1. **Verify all CLI flags** documented match `file:ralph_loop.sh` implementation
2. **Test all examples** in CLI_OPTIONS.md work correctly
3. **Validate links** between all documentation files
4. **Check Mermaid diagrams** render correctly on GitHub
5. **Review consistency** with existing `file:README.md` and `file:CLAUDE.md`
6. **Ensure templates** referenced in AGENT_INTEGRATION.md exist and are accurate

## File Reference Summary

| File | Purpose | Lines of Interest |
|------|---------|-------------------|
| `file:ralph_loop.sh` | Main CLI implementation | 591-628 (help), 631-691 (arg parsing) |
| `file:README.md` | Main documentation | 538-567 (CLI reference), entire file for context |
| `file:CLAUDE.md` | Architecture guide | 1-337 (complete architecture) |
| `file:templates/PROMPT.md` | Agent instructions template | 1-282 (complete template) |
| `file:templates/AGENT.md` | Quality standards template | 1-159 (complete template) |
| `file:lib/circuit_breaker.sh` | Circuit breaker module | Entire file |
| `file:lib/response_analyzer.sh` | Response analysis module | Entire file |
| `file:IMPLEMENTATION_STATUS.md` | Current project status | Entire file for context |

## Architecture Visualization

```mermaid
graph TD
    subgraph "New Documentation"
        A[docs/CLI_OPTIONS.md]
        B[docs/AGENT_INTEGRATION.md]
    end
    
    subgraph "Existing Documentation"
        C[README.md]
        D[CLAUDE.md]
        E[templates/PROMPT.md]
        F[templates/AGENT.md]
    end
    
    subgraph "Implementation"
        G[ralph_loop.sh]
        H[lib/circuit_breaker.sh]
        I[lib/response_analyzer.sh]
    end
    
    A -->|references| G
    A -->|links to| C
    A -->|links to| B
    B -->|references| E
    B -->|references| F
    B -->|references| H
    B -->|references| I
    B -->|links to| D
    C -->|links to| A
    C -->|links to| B
```

---

Execution Information

Branch: main
Commit: 3b4f5f0

New Plan

Observations

The GitHub issue specifies creating docs/CLI_OPTIONS.md to document Ralph's modern CLI flags. The ticket lists 9 specific flags: --output-format json|text, --allowed-tools, --no-continue, --monitor, --live, --calls, --prompt, --reset-circuit/--circuit-status/--auto-reset-circuit, and --reset-session. SDK documentation has been removed (won't-implement). The README contains scattered CLI documentation (lines 393-577) and .ralphrc examples. The docs/ directory does not exist. The ticket emphasizes documenting "modern CLI flags" and "common .ralphrc patterns" as acceptance criteria.

Approach

Create a focused docs/CLI_OPTIONS.md file consolidating CLI documentation from README.md and ralph_loop.sh. Organize flags into logical groups (basic, monitoring, modern options, circuit breaker, session management), provide syntax, defaults, examples, and best practices. Include .ralphrc configuration patterns and common use cases. This centralizes CLI reference while maintaining consistency with existing documentation.

Implementation Steps

1. Create docs/ Directory

Create the docs/ directory at the repository root.

2. Create docs/CLI_OPTIONS.md

Create comprehensive CLI reference with these sections:

Section 1: Overview & Quick Reference

• Brief introduction to Ralph CLI
• Quick reference table of all flags
• Link to .ralphrc configuration section

Section 2: Basic Options

Document from file:ralph_loop.sh (lines 2100-2103):

• -h, --help: Show help message
• -c, --calls NUM: Max API calls per hour (default: 100)
• -p, --prompt FILE: Custom prompt file (default: .ralph/PROMPT.md)
• -s, --status: Show current status JSON

For each: syntax, description, default, valid range, example, when to use.

Section 3: Monitoring & Output Options

Document from file:ralph_loop.sh (lines 2104-2106):

• -m, --monitor: Launch tmux monitoring
• -v, --verbose: Detailed progress updates
• -l, --live: Real-time output streaming (auto-switches to JSON)

Include: how monitoring works, verbose details, live streaming behavior, combining flags.

Section 4: Execution Control

Document from file:ralph_loop.sh (line 2107):

• -t, --timeout MIN: Claude timeout (1-120 minutes, default: 15)

Include: timeout behavior, when to adjust, examples for different project sizes.

Section 5: Modern CLI Options

Document from file:ralph_loop.sh (lines 2113-2118):

• --output-format FORMAT: Output format (json or text, default: json)
• --allowed-tools TOOLS: Restrict permitted tools
• --no-continue: Disable session continuity
• --session-expiry HOURS: Session expiration (default: 24)

For each: purpose, syntax, valid values, default, examples, .ralphrc equivalent.

Section 6: Circuit Breaker Management

Document from file:ralph_loop.sh (lines 2108-2110, 2246-2248):

• --reset-circuit: Reset to CLOSED state
• --circuit-status: Show circuit status
• --auto-reset-circuit: Auto-reset on startup

Include: what circuit breaker does, when to use each, auto-recovery behavior, cooldown configuration.

Section 7: Session Management

Document from file:ralph_loop.sh (lines 2203-2209):

• --reset-session: Reset session state and exit

Include: when needed, difference from --reset-circuit, auto-reset triggers, session files.

Section 8: .ralphrc Configuration Patterns

Reference file:README.md (lines 394-428) and document:

• Complete .ralphrc template with all options
• Common patterns:
  • Development: High call limit, verbose output
  • Production: Lower call limit, circuit breaker tuning
  • Tool-restricted: Specific ALLOWED_TOOLS patterns
  • Long-running: Extended timeout, session expiry
  • Quick iteration: Low timeout, no session continuity
• CLI flag override behavior
• Environment variable precedence

Section 9: Practical Examples

Organize by use case:

• Basic Usage: Single-flag examples
• Monitoring & Debugging: --monitor, --verbose, --live combinations
• Rate Limiting: --calls with different thresholds
• Custom Prompts: --prompt examples
• Session Management: --no-continue, --reset-session, --session-expiry
• Circuit Breaker Recovery: --reset-circuit, --auto-reset-circuit
• Complex Projects: Multiple flags combined

Section 10: Best Practices

Include:

• Monitoring vs background execution
• Timeout values by project complexity
• Tool restriction patterns
• Session continuity trade-offs
• Rate limiting strategies
• Circuit breaker tuning
• Flag combinations

Section 11: Troubleshooting

Document common issues:

• Permission denied errors (reference README lines 1984-2003)
• Session continuity issues
• Circuit breaker false positives
• Timeout configuration
• Tool restriction problems
• API limit handling

Section 12: Exit Codes & Status

Document:

• Exit code meanings (0=success, 1=error, 2=API limit, 3=circuit breaker)
• Status file JSON structure
• Interpreting status output

3. Add Mermaid Diagrams

Include visual aids showing flag categories and interaction flow.

4. Update file:README.md

Add reference section after line 392:

## 📚 CLI Documentation

For comprehensive CLI flag reference, see **[CLI Options Guide](docs/CLI_OPTIONS.md)**.

Update existing sections to link to new doc:

• Line 393: Add reference to CLI_OPTIONS.md
• Line 430: Add link for rate limiting details
• Line 483: Add link for custom prompts

5. Content Sourcing

Primary sources:

• file:ralph_loop.sh lines 2089-2147 (help text)
• file:ralph_loop.sh lines 2150-2256 (argument parsing)
• file:README.md lines 393-577 (existing CLI docs)
• file:CLAUDE.md lines 199-272 (configuration)

6. Validation Checklist

1. All 9 flags from ticket documented
2. Flag syntax matches file:ralph_loop.sh implementation
3. Each flag has practical examples
4. Terminology consistent with README and CLAUDE.md
5. Cross-references work correctly
6. Markdown renders on GitHub
7. Mermaid diagrams display properly
8. Logical flag grouping

7. File Structure

docs/
└── CLI_OPTIONS.md          # Comprehensive CLI reference

Update README.md with reference to new doc.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The GitHub issue specifies creating `docs/CLI_OPTIONS.md` to document Ralph's modern CLI flags. The ticket lists 9 specific flags: `--output-format json|text`, `--allowed-tools`, `--no-continue`, `--monitor`, `--live`, `--calls`, `--prompt`, `--reset-circuit`/`--circuit-status`/`--auto-reset-circuit`, and `--reset-session`. SDK documentation has been removed (won't-implement). The README contains scattered CLI documentation (lines 393-577) and `.ralphrc` examples. The `docs/` directory does not exist. The ticket emphasizes documenting "modern CLI flags" and "common .ralphrc patterns" as acceptance criteria.

## Approach

Create a focused `docs/CLI_OPTIONS.md` file consolidating CLI documentation from `README.md` and `ralph_loop.sh`. Organize flags into logical groups (basic, monitoring, modern options, circuit breaker, session management), provide syntax, defaults, examples, and best practices. Include `.ralphrc` configuration patterns and common use cases. This centralizes CLI reference while maintaining consistency with existing documentation.

## Implementation Steps

### 1. Create `docs/` Directory

Create the `docs/` directory at the repository root.

### 2. Create `docs/CLI_OPTIONS.md`

Create comprehensive CLI reference with these sections:

**Section 1: Overview & Quick Reference**
- Brief introduction to Ralph CLI
- Quick reference table of all flags
- Link to `.ralphrc` configuration section

**Section 2: Basic Options**

Document from `file:ralph_loop.sh` (lines 2100-2103):
- `-h, --help`: Show help message
- `-c, --calls NUM`: Max API calls per hour (default: 100)
- `-p, --prompt FILE`: Custom prompt file (default: `.ralph/PROMPT.md`)
- `-s, --status`: Show current status JSON

For each: syntax, description, default, valid range, example, when to use.

**Section 3: Monitoring & Output Options**

Document from `file:ralph_loop.sh` (lines 2104-2106):
- `-m, --monitor`: Launch tmux monitoring
- `-v, --verbose`: Detailed progress updates
- `-l, --live`: Real-time output streaming (auto-switches to JSON)

Include: how monitoring works, verbose details, live streaming behavior, combining flags.

**Section 4: Execution Control**

Document from `file:ralph_loop.sh` (line 2107):
- `-t, --timeout MIN`: Claude timeout (1-120 minutes, default: 15)

Include: timeout behavior, when to adjust, examples for different project sizes.

**Section 5: Modern CLI Options**

Document from `file:ralph_loop.sh` (lines 2113-2118):
- `--output-format FORMAT`: Output format (json or text, default: json)
- `--allowed-tools TOOLS`: Restrict permitted tools
- `--no-continue`: Disable session continuity
- `--session-expiry HOURS`: Session expiration (default: 24)

For each: purpose, syntax, valid values, default, examples, `.ralphrc` equivalent.

**Section 6: Circuit Breaker Management**

Document from `file:ralph_loop.sh` (lines 2108-2110, 2246-2248):
- `--reset-circuit`: Reset to CLOSED state
- `--circuit-status`: Show circuit status
- `--auto-reset-circuit`: Auto-reset on startup

Include: what circuit breaker does, when to use each, auto-recovery behavior, cooldown configuration.

**Section 7: Session Management**

Document from `file:ralph_loop.sh` (lines 2203-2209):
- `--reset-session`: Reset session state and exit

Include: when needed, difference from `--reset-circuit`, auto-reset triggers, session files.

**Section 8: .ralphrc Configuration Patterns**

Reference `file:README.md` (lines 394-428) and document:
- Complete `.ralphrc` template with all options
- Common patterns:
  - **Development**: High call limit, verbose output
  - **Production**: Lower call limit, circuit breaker tuning
  - **Tool-restricted**: Specific ALLOWED_TOOLS patterns
  - **Long-running**: Extended timeout, session expiry
  - **Quick iteration**: Low timeout, no session continuity
- CLI flag override behavior
- Environment variable precedence

**Section 9: Practical Examples**

Organize by use case:
- **Basic Usage**: Single-flag examples
- **Monitoring & Debugging**: `--monitor`, `--verbose`, `--live` combinations
- **Rate Limiting**: `--calls` with different thresholds
- **Custom Prompts**: `--prompt` examples
- **Session Management**: `--no-continue`, `--reset-session`, `--session-expiry`
- **Circuit Breaker Recovery**: `--reset-circuit`, `--auto-reset-circuit`
- **Complex Projects**: Multiple flags combined

**Section 10: Best Practices**

Include:
- Monitoring vs background execution
- Timeout values by project complexity
- Tool restriction patterns
- Session continuity trade-offs
- Rate limiting strategies
- Circuit breaker tuning
- Flag combinations

**Section 11: Troubleshooting**

Document common issues:
- Permission denied errors (reference README lines 1984-2003)
- Session continuity issues
- Circuit breaker false positives
- Timeout configuration
- Tool restriction problems
- API limit handling

**Section 12: Exit Codes & Status**

Document:
- Exit code meanings (0=success, 1=error, 2=API limit, 3=circuit breaker)
- Status file JSON structure
- Interpreting status output

### 3. Add Mermaid Diagrams

Include visual aids showing flag categories and interaction flow.

### 4. Update `file:README.md`

Add reference section after line 392:
```markdown
## 📚 CLI Documentation

For comprehensive CLI flag reference, see **[CLI Options Guide](docs/CLI_OPTIONS.md)**.
```

Update existing sections to link to new doc:
- Line 393: Add reference to CLI_OPTIONS.md
- Line 430: Add link for rate limiting details
- Line 483: Add link for custom prompts

### 5. Content Sourcing

**Primary sources:**
- `file:ralph_loop.sh` lines 2089-2147 (help text)
- `file:ralph_loop.sh` lines 2150-2256 (argument parsing)
- `file:README.md` lines 393-577 (existing CLI docs)
- `file:CLAUDE.md` lines 199-272 (configuration)

### 6. Validation Checklist

1. All 9 flags from ticket documented
2. Flag syntax matches `file:ralph_loop.sh` implementation
3. Each flag has practical examples
4. Terminology consistent with README and CLAUDE.md
5. Cross-references work correctly
6. Markdown renders on GitHub
7. Mermaid diagrams display properly
8. Logical flag grouping

### 7. File Structure

```
docs/
└── CLI_OPTIONS.md          # Comprehensive CLI reference
```

Update `README.md` with reference to new doc.

---

Execution Information

Branch: main
Commit: 8c7a7d9