TaskMaster Integration: Story-Based Task Management

.github/workflows/python-ci.yml

@@ -0,0 +1,43 @@
+name: Ralph Python CI
+
+on:
+  push:
+    branches:
+      - main
+      - ralph/python-rewrite
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv with Python 3.11
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: "3.11"
+
+      - name: Synchronize dependencies
+        run: uv sync --frozen --dev
+
+      - name: Run ruff
+        run: uv run ruff check ralph
+
+      - name: Run mypy --strict
+        run: uv run python -m mypy --strict ralph
+
+      - name: Run pytest with coverage
+        run: uv run python -m pytest --cov=ralph --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error

.gitignore

@@ -3,6 +3,10 @@ prd.json
 progress.txt
 .last-branch
 
+# TaskMaster-AI task storage (managed by taskmaster-ai, not Ralph)
+.taskmaster/
+tasks.json
+
 # Archive is optional to commit
 # archive/
 
@@ -12,6 +16,19 @@ progress.txt
 #Claude
 .claude/
 
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv
+.pytest_cache/
+.coverage
+htmlcov/
+*.egg-info/
+dist/
+build/
 # Python caches
 __pycache__/
 *.pyc

AGENTS.md

@@ -45,4 +45,4 @@ npm run dev
 - Memory persists via git history, `progress.txt`, and `prd.json`
 - Stories should be small enough to complete in one context window
 - Always update AGENTS.md with discovered patterns for future iterations
-- `mypy` and `ruff` are not yet available via `uv run` until Python tooling is configured (see US-007)
+- For uv-managed tooling, prefer `uv run python -m <tool>` (e.g., mypy, pytest) so commands use the project `.venv` and find dev dependencies

CLAUDE.md

@@ -2,18 +2,30 @@
 
 You are an autonomous coding agent working on a software project.
 
+## Understanding Stories vs Tasks
+
+**IMPORTANT**: Each item in `tasks.json` should be written as a **user story** with rich context, not a bare task instruction. Stories provide narrative context that produces better results:
+
+- ✅ **Good (Story)**: "As a developer using Ralph, I need the CLI to support OpenCode as a fourth executor option, so that I can leverage OpenCode's capabilities alongside amp/claude/codex. The implementation should follow the same pattern as existing executors, using the _TeeToStderr pattern for output capture and integrating with the config system."
+
+- ❌ **Bad (Task)**: "Add OpenCode executor"
+
+Stories answer: **Who** needs it, **what** they need, **why** they need it, and **how** it should work. This context helps you understand the full picture and make better implementation decisions.
+
 ## Your Task
 
-1. Read the PRD at `prd.json` (in the same directory as this file)
+1. Read the story list at `tasks.json` (in the same directory as this file)
+   - Each "task" entry should be written as a user story with context
 2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
-3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
-4. Pick the **highest priority** user story where `passes: false`
-5. Implement that single user story
-6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
-7. Update CLAUDE.md files if you discover reusable patterns (see below)
-8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
-9. Update the PRD to set `passes: true` for the completed story
-10. Append your progress to `progress.txt`
+3. Check you're on the correct branch from tasks.json `metadata.branchName`. If not, check it out or create from main.
+4. Pick the **highest priority** story where `status: "pending"` and not blocked (empty `blockedBy` array)
+5. Set story status to `"in-progress"` before starting work
+6. Implement that single story, using the contextual information provided
+7. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+8. Update CLAUDE.md files if you discover reusable patterns (see below)
+9. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
+10. Update the story status to `"done"` for the completed story
+11. Append your progress to `progress.txt`
 
 ## Progress Report Format
 
@@ -89,12 +101,23 @@ If no browser tools are available, note in your progress report that manual brow
 
 ## Stop Condition
 
-After completing a user story, check if ALL stories have `passes: true`.
+After completing a story, check if ALL stories have `status: "done"`.
 
-If ALL stories are complete and passing, reply with:
+If ALL stories are complete, reply with:
 <promise>COMPLETE</promise>
 
-If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
+If there are still stories with `status: "pending"` or `status: "in-progress"`, end your response normally (another iteration will pick up the next story).
+
+## Writing New Stories
+
+When creating new stories in tasks.json, always write them with full narrative context:
+- **As a** [role/persona]
+- **I need** [capability/feature]
+- **So that** [business value/outcome]
+- **Implementation approach**: [technical context, patterns to follow, constraints]
+- **Acceptance criteria**: [specific, testable conditions]
+
+This story format provides the cognitive context needed for high-quality autonomous implementation.
 
 ## Important
 

README.md

@@ -2,18 +2,23 @@
 
 ![Ralph](ralph.webp)
 
-Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`.
+[![Ralph Python CI](https://github.com/promptexecution/b00t-wiggums/actions/workflows/python-ci.yml/badge.svg?branch=ralph/python-rewrite)](https://github.com/promptexecution/b00t-wiggums/actions/workflows/python-ci.yml)
+
+Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Codex](https://codex.anthropic.com)) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`.
+
+**Python Rewrite**: Ralph has been rewritten in Python for improved maintainability, testability, and type safety. See [ralph/README.md](ralph/README.md) for Python-specific documentation.
 
 Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).
 
 [Read my in-depth article on how I use Ralph](https://x.com/ryancarson/status/2008548371712135632)
 
 ## Prerequisites
 
+- Python 3.11+ with [uv](https://github.com/astral-sh/uv) package manager installed
 - One of the following AI coding tools installed and authenticated:
   - [Amp CLI](https://ampcode.com)
   - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)
-- `jq` installed (`brew install jq` on macOS)
+  - [Codex](https://codex.anthropic.com)
 - A git repository for your project
 
 ## Setup
@@ -109,15 +114,35 @@ This creates `prd.json` with user stories structured for autonomous execution.
 
 ### 3. Run Ralph
 
+**Python Version (Recommended)**:
+
+```bash
+# Using Amp (default)
+uv run ralph [max_iterations]
+
+# Using Claude Code
+uv run ralph --tool claude [max_iterations]
+
+# Using Codex
+uv run ralph --tool codex [max_iterations]
+
+# Or use justfile commands
+just ralph          # Run with amp (default)
+just ralph-claude   # Run with claude
+just ralph-codex    # Run with codex
+```
+
+**Bash Version (Deprecated)**:
+
 ```bash
-# Using Amp
-./scripts/ralph/ralph.sh [max_iterations]
+# Using Amp (default)
+./ralph.sh [max_iterations]
 
 # Using Claude Code
-./scripts/ralph/ralph.sh --agent claude [max_iterations]
+./ralph.sh --tool claude [max_iterations]
 ```
 
-Default is 10 iterations. Use `--agent amp`, `--agent claude`, or `--agent codex` to select your AI coding tool.
+Default is 10 iterations. Use `--tool amp`, `--tool claude`, or `--tool codex` to select your AI coding tool.
 
 Ralph will:
 1. Create a feature branch (from PRD `branchName`)
@@ -151,12 +176,15 @@ or Codex so you can validate behavior locally before handing off to agents.
 
 | File | Purpose |
 |------|---------|
-| `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--agent amp`, `--agent claude`, or `--agent codex`) |
+| `ralph/` | Python implementation of Ralph (recommended) |
+| `ralph/README.md` | Detailed Python documentation |
+| `ralph.sh` | Bash wrapper (delegates to Python version) |
 | `prompt.md` | Prompt template for Amp |
-| `CLAUDE.md` | Prompt template for Claude Code |
+| `CLAUDE.md` | Prompt template for Claude Code and Codex |
 | `prd.json` | User stories with `passes` status (the task list) |
 | `prd.json.example` | Example PRD format for reference |
 | `progress.txt` | Append-only learnings for future iterations |
+| `justfile` | Just commands for Ralph (ralph, ralph-test, ralph-check, etc.) |
 | `skills/prd/` | Skill for generating PRDs (works with Amp and Claude Code) |
 | `skills/ralph/` | Skill for converting PRDs to JSON (works with Amp and Claude Code) |
 | `.claude-plugin/` | Plugin manifest for Claude Code marketplace discovery |
@@ -250,6 +278,52 @@ After copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your pro
 
 Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`.
 
+## Migration from Bash to Python
+
+The Python version of Ralph maintains the same behavior as the bash version while adding benefits:
+
+### What's the Same
+- Same command-line interface (just `--agent` → `--tool`)
+- Same file structure (`prd.json`, `progress.txt`)
+- Same workflow (iterations, completion signal, archival)
+- Same tool support (amp, claude, codex)
+
+### What's Better
+- **Type Safety**: Full mypy strict mode type checking
+- **Testing**: 92% code coverage with unit and integration tests
+- **Error Handling**: Proper exception handling with returns Result types
+- **Maintainability**: Modular architecture with clear separation of concerns
+- **Development Tools**: justfile commands, ruff linting, comprehensive documentation
+
+### Migration Steps
+
+1. **Install uv** (if not already installed):
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+2. **Test the Python version**:
+   ```bash
+   uv run ralph --help
+   ```
+
+3. **Update your workflow**:
+   - Replace `./ralph.sh` with `uv run ralph` or `just ralph`
+   - Update CI/CD scripts if needed
+   - Note: `ralph.sh` still works (delegates to Python version)
+
+4. **Customize configuration** (optional):
+   - Set environment variables for codex (see [ralph/README.md](ralph/README.md))
+   - Update `CLAUDE.md` or `prompt.md` for your project
+
+### Breaking Changes
+
+- CLI flag: `--agent` → `--tool`
+- Python 3.11+ required (was: bash)
+- `uv` package manager required (was: none)
+
+See [ralph/README.md](ralph/README.md) for complete Python documentation.
+
 ## References
 
 - [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/)

justfile

@@ -0,0 +1,33 @@
+# Ralph Python CLI justfile commands
+
+# Run ralph with specified tool and iterations (default: amp, 10 iterations)
+ralph TOOL='amp' ITERATIONS='10':
+    uv run ralph --tool {{TOOL}} {{ITERATIONS}}
+
+# Run ralph tests
+ralph-test:
+    uv run pytest tests/test_ralph*
+
+# Type check and lint ralph module
+ralph-check:
+    uv run mypy ralph/ && uv run ruff check ralph/
+
+# Format ralph code with ruff
+ralph-format:
+    uv run ruff format ralph/
+
+# Run all quality checks (format, lint, type check, test)
+ralph-all: ralph-format ralph-check ralph-test
+    @echo "✅ All quality checks passed!"
+
+# Run ralph with amp tool
+ralph-amp ITERATIONS='10':
+    uv run ralph --tool amp {{ITERATIONS}}
+
+# Run ralph with claude tool
+ralph-claude ITERATIONS='10':
+    uv run ralph --tool claude {{ITERATIONS}}
+
+# Run ralph with codex tool
+ralph-codex ITERATIONS='10':
+    uv run ralph --tool codex {{ITERATIONS}}