Ralph Init

Step 3: Initialize Directory Structure

mkdir -p "$TRACK_DIR/logs"

# Create .gitignore if missing
if [[ ! -f "$RALPH_DIR/.gitignore" ]]; then
  printf '*\n!.gitignore\n' > "$RALPH_DIR/.gitignore"
fi

echo "planning" > "$TRACK_DIR/status"
echo "0" > "$TRACK_DIR/current_phase"

Write $TRACK_DIR/state.md:

# Track State: <slug>

Phase history will be appended below by agents.

Step 4: Select Base Branch

Ask the user which branch to base this track on. Show the available local branches:

git branch --format='%(refname:short)'

Default to main if the user doesn't have a preference. Store the chosen branch:

echo "<chosen-branch>" > "$TRACK_DIR/base_branch"

Step 5: Analyze & Discuss

Now analyze the codebase and discuss the plan with the user:

• Read key project files (package.json, Cargo.toml, Makefile, etc.) to understand the stack
• Explore relevant source code
• Ask the user for the ticket number (e.g. CON-31, DEX-120) if not already provided in $ARGUMENTS
• Ask the user for the scope (app or sub-area, e.g. home, dex-web, web3) if not obvious from the feature
• Propose an approach and iterate with the user
• Break the feature into 3–8 small sequential phases

Step 6: Write plan.md

Once the user is happy, write $TRACK_DIR/plan.md using this exact format:

# Track: <name>

**Ticket:** <TICKET-123>
**Scope:** <app or sub-area, e.g. home, dex-web, web3>

## Description

<1-2 sentences describing the feature/task>

## Phases

### Phase 1: <title>

**Description:** <what to do in this phase>
**Files:** <expected files to touch>
**Checks:** <phase-specific validation commands>

### Phase 2: <title>

**Description:** <what to do>
**Files:** <expected files>
**Checks:** <validation commands>

...

## Quality Gates

- <command 1, e.g. "pnpm build">
- <command 2, e.g. "pnpm test">
- <command 3, e.g. "pnpm lint">

Phase Design Guidelines

• Phase 1 sets up the foundation (config, types, scaffolding)
• Middle phases implement the feature incrementally
• Final phase runs all quality gates and polishes. This should include things like linting, formatting, building and running type checks as well as other things like testing where applicable
• Each phase must produce a working (if incomplete) codebase
• Keep phases small enough that an agent can finish in one session
• Include specific file paths where possible
• Phase checks should be fast, deterministic commands

Step 7: Finalize

After writing plan.md:

echo "planned" > "$TRACK_DIR/status"
echo "$SLUG" > "$RALPH_DIR/active_track"

Count the phases and print a summary:

Track '<slug>' planned with N phases.
Active track set to: <slug>

Next steps:
  ralph-run             # run all phases
  ralph-single          # run one phase at a time
  /ralph-status         # view the plan