dynamic-ralph 0.1.0__tar.gz

dynamic_ralph-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: dynamic-ralph
+Version: 0.1.0
+Summary: Dynamic Ralph: step-based multi-agent workflow orchestrator for Claude Code
+Author: github.com/cybergrind
+License: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.0

dynamic_ralph-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Dynamic Ralph
+
+A step-based multi-agent workflow orchestrator for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Dynamic Ralph decomposes user stories into focused, sequential steps and executes them via Claude Code agents. It supports three execution modes:
+
+- **One-shot**: Single task, ephemeral state, full 10-step workflow
+- **PRD serial**: Stories from a PRD file, executed one at a time
+- **PRD parallel**: Multiple agents via git worktrees for concurrent story execution
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://github.com/astral-sh/uv) package manager
+- Docker (for containerized agent execution)
+- Claude Code CLI (`npx @anthropic-ai/claude-code`)
+
+## Setup
+
+```bash
+# Install dependencies
+uv sync
+
+# Install as a tool
+uv tool install -e .
+
+# Build the Docker agent image
+uv tool run --from=dynamic-ralph dynamic-ralph --build "dummy"
+```
+
+## Usage
+
+### Interactive agent
+
+Launch an interactive Claude Code session inside the ralph-agent container:
+
+```bash
+uv tool run --from=dynamic-ralph ralph-agent
+```
+
+### One-shot mode
+
+Execute a single task through the full workflow:
+
+```bash
+uv tool run --from=dynamic-ralph dynamic-ralph "Add a logout button to the settings page"
+```
+
+### PRD serial mode
+
+Execute stories from a PRD file one at a time:
+
+```bash
+uv tool run --from=dynamic-ralph dynamic-ralph --prd prd.json
+```
+
+### PRD parallel mode
+
+Execute stories concurrently with multiple agents:
+
+```bash
+uv tool run --from=dynamic-ralph dynamic-ralph --prd prd.json --agents 3
+```
+
+### Resume a previous run
+
+```bash
+uv tool run --from=dynamic-ralph dynamic-ralph --prd prd.json --resume
+```
+
+## Configuration
+
+Dynamic Ralph uses environment variables for project-specific configuration:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RALPH_IMAGE` | `ralph-agent:latest` | Docker image for agent containers |
+| `RALPH_COMPOSE_FILE` | `compose.test.yml` | Docker Compose file for infrastructure |
+| `RALPH_ENV_FILE` | `.env` | Environment file for Docker Compose |
+| `RALPH_SERVICE` | `app` | Main service name in Docker Compose |
+| `RALPH_INFRA_SERVICES` | `mysql,redis` | Comma-separated infrastructure services |
+| `RALPH_GIT_EMAIL` | `claude-agent@dynamic-ralph.dev` | Git email for agent commits |
+
+## Workflow Steps
+
+The default 10-step workflow:
+
+1. **Context Gathering** - Explore codebase, understand relevant files
+2. **Planning** - Design implementation approach
+3. **Architecture** - Plan file changes and interfaces
+4. **Test Architecture** - Design test strategy
+5. **Coding** - Implement the changes
+6. **Linting** - Format and lint (mandatory)
+7. **Initial Testing** - Run tests, fix failures
+8. **Review** - Self-review the implementation
+9. **Prune Tests** - Remove redundant tests
+10. **Final Review** - Final verification (mandatory)
+
+Agents can dynamically edit the workflow (add, split, skip, reorder steps) during execution.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Format and lint
+uv run pre-commit run -a
+```
+
+## License
+
+Apache-2.0

dynamic_ralph-0.1.0/bin/run_agent.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Run an interactive Claude Code session inside the ralph-agent container.
+
+Mounts host credentials (~/.claude, ~/.config/claude), the current directory
+as /workspace, and the Docker socket.  Uses ``os.execvp`` so the container
+gets direct TTY access for a regular interactive Claude experience.
+
+Extra arguments after ``--`` are forwarded to the ``claude`` CLI.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from multi_agent.constants import GIT_EMAIL, RALPH_IMAGE, RALPH_MODE, get_git_author_identity
+from multi_agent.docker import build_image, docker_sock_gid, image_exists
+
+
+def build_interactive_docker_command(
+    *,
+    image: str = RALPH_IMAGE,
+    workspace: str | None = None,
+    extra_args: list[str] | None = None,
+) -> list[str]:
+    """Build a ``docker run -it`` command for interactive Claude Code use."""
+    if workspace is None:
+        workspace = os.getcwd()
+
+    author_name, author_email = get_git_author_identity()
+    home = Path.home()
+    claude_dir = home / '.claude'
+    config_claude = home / '.config' / 'claude'
+
+    cmd: list[str] = [
+        'docker',
+        'run',
+        '-it',
+        '--rm',
+        '--group-add',
+        docker_sock_gid(),
+        '-e',
+        'IS_SANDBOX=1',
+        '-e',
+        'UV_PROJECT_ENVIRONMENT=/tmp/venv',
+        '-e',
+        f'GIT_AUTHOR_NAME={author_name}',
+        '-e',
+        f'GIT_AUTHOR_EMAIL={author_email}',
+        '-e',
+        'GIT_COMMITTER_NAME=Claude Agent',
+        '-e',
+        f'GIT_COMMITTER_EMAIL={GIT_EMAIL}',
+        '-e',
+        f'RALPH_MODE={RALPH_MODE}',
+        '-v',
+        '/var/run/docker.sock:/var/run/docker.sock',
+        '-v',
+        f'{workspace}:/workspace',
+        '-v',
+        '/workspace/.venv',
+        '-v',
+        f'{claude_dir}:/home/agent/.claude',
+        '-v',
+        f'{config_claude}:/home/agent/.config/claude',
+        '-w',
+        '/workspace',
+        image,
+        'claude',
+        '--dangerously-skip-permissions',
+    ]
+
+    if extra_args:
+        cmd.extend(extra_args)
+
+    return cmd
+
+
+def main() -> None:
+    # Ensure the Docker image is available
+    if not image_exists():
+        build_image()
+
+    # Everything after '--' is forwarded to claude
+    extra: list[str] = []
+    if '--' in sys.argv:
+        sep = sys.argv.index('--')
+        extra = sys.argv[sep + 1 :]
+
+    cmd = build_interactive_docker_command(extra_args=extra or None)
+    os.execvp(cmd[0], cmd)
+
+
+if __name__ == '__main__':
+    main()