step-by-step-cli 0.1.0__tar.gz

step_by_step_cli-0.1.0/.env.example

@@ -0,0 +1 @@
+GITHUB_TOKEN=ghp_your-github-token-here

step_by_step_cli-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.agents/
+.env
+.claude/
+skills-lock.json
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.python-version
+
+# Pipeline exports
+pipeline_log_*.txt

step_by_step_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Valentin Dutra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

step_by_step_cli-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: step-by-step-cli
+Version: 0.1.0
+Summary: LLM Development Pipeline UI - GitHub Actions-style visual dashboard for LLM-driven workflows
+Project-URL: Homepage, https://github.com/ValentinDutra/step-by-step
+Project-URL: Repository, https://github.com/ValentinDutra/step-by-step
+Project-URL: Issues, https://github.com/ValentinDutra/step-by-step/issues
+Author: Valentin Dutra
+License: MIT License
+        
+        Copyright (c) 2025 Valentin Dutra
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,automation,claude,cli,developer-tools,llm,pipeline,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Terminals
+Requires-Python: >=3.13
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: textual>=8.1.1
+Description-Content-Type: text/markdown
+
+# Step-by-Step
+
+A terminal UI that runs your development tasks through a structured multi-agent pipeline. You describe what you want to build; a team of specialized Claude agents plans, implements, tests, reviews, and opens a pull request — autonomously.
+
+![Step-by-Step in action](assets/screenshot.png)
+
+---
+
+## How it works
+
+Step-by-Step models software delivery as a linear pipeline of specialized agents, each owning a single responsibility. Stages that can be parallelized fan out into independent worker agents that run concurrently, then merge their results before the next stage begins.
+
+```
+Plan ──● Decomp ──● Impl ⇶ ──● Tests ⇶ ──● Quality ──● Docs ──● PR
+```
+
+`⇶` = parallel workers · `●` = single agent
+
+### Pipeline stages
+
+| Stage | Mode | What it does |
+|---|---|---|
+| **Planning** | Single agent | Senior architect reads your codebase and produces a concrete, numbered implementation plan |
+| **Decomposition** | Manager agent | Splits the plan into independent subtasks that can be worked on simultaneously |
+| **Implementation** | Parallel workers | Each subtask is handed to a dedicated worker agent; all workers run concurrently |
+| **Tests & Validation** | Parallel workers | QA agents write and run tests per subtask; surface failures via `## Issues Found` |
+| **Code Quality** | Single agent | Reviewer checks for code smells, security issues, and readability |
+| **Documentation** | Single agent | Generates or updates README sections, docstrings, and API reference |
+| **Commit & PR** | Single agent | Writes conventional commits and opens a GitHub Pull Request |
+
+### Refinement loops
+
+Claude drives two autonomous feedback loops — it decides when to stop by reporting `## Issues Found: None`.
+
+- **Test loop** — cycles through Implementation → Tests & Validation until no issues remain
+- **Quality loop** — re-decomposes and re-implements until Code Quality is satisfied
+
+### RAM-based flow control
+
+Worker concurrency is not capped by a fixed number. Instead, the pipeline uses TCP-style flow control: a new worker starts only when system RAM is below 75%. Starts are serialized and include a post-start delay so the OS can register each new process's footprint before the next candidate is evaluated. When RAM is high, new workers queue up and resume as running workers release memory.
+
+---
+
+## Requirements
+
+- **Python 3.13+**
+- **[uv](https://docs.astral.sh/uv/)** (recommended) or pip
+- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** — `npm install -g @anthropic-ai/claude-code`
+- **[GitHub CLI](https://cli.github.com/)** — required for the Commit & PR stage (`gh auth login`)
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/ValentinDutra/step-by-step.git
+cd step-by-step
+uv sync
+```
+
+---
+
+## Usage
+
+```bash
+# Run against the current directory
+uv run pipeline
+
+# Run against a specific repository
+uv run pipeline /path/to/your/repo
+
+# Load a prompt from a file and start immediately
+uv run pipeline /path/to/your/repo -f prompt.txt
+```
+
+Type your task in the input area at the bottom and press `Ctrl+Enter` to start.
+
+### Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `Ctrl+Enter` | Submit prompt and run the pipeline |
+| `Ctrl+L` | Clear the activity log |
+| `Ctrl+E` | Export log to `pipeline_log_<timestamp>.txt` |
+| `Ctrl+C` | Quit |
+
+### Re-running from a specific stage
+
+Once a run completes, every stage pill in the header becomes clickable. Click any stage to **re-run from that point forward**, reusing all prior context — useful for retrying a failed stage or iterating on implementation without re-planning.
+
+---
+
+## UI layout
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Plan  │  Decomp  │  Impl ⇶  │  Tests ⇶  │  Quality  │  PR    │  ← stage bar
+├─────────────────────────────────────────────────────────────────┤
+│  > Describe your task…                                          │  ← prompt input
+├──────────────────────────────┬──────────────────────────────────┤
+│  ● Planning                  │                                  │
+│                              │         Activity log             │
+│      Streaming pane          │   (full chronological history)   │
+│  (live output from active    │                                  │
+│   stage or worker)           │                                  │
+├──────────────────────────────┴──────────────────────────────────┤
+│  ^p palette  ^l Clear Log  ctrl+↵ Run  ^e Export Log  ^m Monitor        Calls: 4  |  Cost: $0.0234  |  Time: 1m 20s  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Project structure
+
+```
+app/
+├── __main__.py      Entry point
+├── models.py        Shared data classes (Task, WorkerResult, PipelineStats)
+├── agents.py        Claude CLI invocation, flow control, and worker coordination
+├── stages.py        Stage definitions, prompt templates, and pipeline configuration
+├── pipeline.py      Stage runners: run_stage() and run_stage_parallel()
+├── runner.py        PipelineRunnerMixin: run_pipeline() and rerun_from_stage()
+├── widgets.py       StagePill TUI widget and display constants
+├── git.py           Git/gh subprocess helpers and Commit & PR stage runner
+└── tui.py           PipelineApp (Textual App) and main() entry point
+```
+
+---
+
+## Safety
+
+The pipeline invokes `claude --dangerously-skip-permissions` so agents can read and write files autonomously. **Only point it at repositories where you trust the output.** Always review the diff before the PR stage commits.
+
+Each subprocess is run with a 10-minute timeout and cleaned up unconditionally on exit — even on errors or cancellation — so stalled Claude processes do not accumulate.
+
+---
+
+## License
+
+MIT © Valentin Dutra — see [LICENSE](LICENSE)

step_by_step_cli-0.1.0/README.md

@@ -0,0 +1,140 @@
+# Step-by-Step
+
+A terminal UI that runs your development tasks through a structured multi-agent pipeline. You describe what you want to build; a team of specialized Claude agents plans, implements, tests, reviews, and opens a pull request — autonomously.
+
+![Step-by-Step in action](assets/screenshot.png)
+
+---
+
+## How it works
+
+Step-by-Step models software delivery as a linear pipeline of specialized agents, each owning a single responsibility. Stages that can be parallelized fan out into independent worker agents that run concurrently, then merge their results before the next stage begins.
+
+```
+Plan ──● Decomp ──● Impl ⇶ ──● Tests ⇶ ──● Quality ──● Docs ──● PR
+```
+
+`⇶` = parallel workers · `●` = single agent
+
+### Pipeline stages
+
+| Stage | Mode | What it does |
+|---|---|---|
+| **Planning** | Single agent | Senior architect reads your codebase and produces a concrete, numbered implementation plan |
+| **Decomposition** | Manager agent | Splits the plan into independent subtasks that can be worked on simultaneously |
+| **Implementation** | Parallel workers | Each subtask is handed to a dedicated worker agent; all workers run concurrently |
+| **Tests & Validation** | Parallel workers | QA agents write and run tests per subtask; surface failures via `## Issues Found` |
+| **Code Quality** | Single agent | Reviewer checks for code smells, security issues, and readability |
+| **Documentation** | Single agent | Generates or updates README sections, docstrings, and API reference |
+| **Commit & PR** | Single agent | Writes conventional commits and opens a GitHub Pull Request |
+
+### Refinement loops
+
+Claude drives two autonomous feedback loops — it decides when to stop by reporting `## Issues Found: None`.
+
+- **Test loop** — cycles through Implementation → Tests & Validation until no issues remain
+- **Quality loop** — re-decomposes and re-implements until Code Quality is satisfied
+
+### RAM-based flow control
+
+Worker concurrency is not capped by a fixed number. Instead, the pipeline uses TCP-style flow control: a new worker starts only when system RAM is below 75%. Starts are serialized and include a post-start delay so the OS can register each new process's footprint before the next candidate is evaluated. When RAM is high, new workers queue up and resume as running workers release memory.
+
+---
+
+## Requirements
+
+- **Python 3.13+**
+- **[uv](https://docs.astral.sh/uv/)** (recommended) or pip
+- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** — `npm install -g @anthropic-ai/claude-code`
+- **[GitHub CLI](https://cli.github.com/)** — required for the Commit & PR stage (`gh auth login`)
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/ValentinDutra/step-by-step.git
+cd step-by-step
+uv sync
+```
+
+---
+
+## Usage
+
+```bash
+# Run against the current directory
+uv run pipeline
+
+# Run against a specific repository
+uv run pipeline /path/to/your/repo
+
+# Load a prompt from a file and start immediately
+uv run pipeline /path/to/your/repo -f prompt.txt
+```
+
+Type your task in the input area at the bottom and press `Ctrl+Enter` to start.
+
+### Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `Ctrl+Enter` | Submit prompt and run the pipeline |
+| `Ctrl+L` | Clear the activity log |
+| `Ctrl+E` | Export log to `pipeline_log_<timestamp>.txt` |
+| `Ctrl+C` | Quit |
+
+### Re-running from a specific stage
+
+Once a run completes, every stage pill in the header becomes clickable. Click any stage to **re-run from that point forward**, reusing all prior context — useful for retrying a failed stage or iterating on implementation without re-planning.
+
+---
+
+## UI layout
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Plan  │  Decomp  │  Impl ⇶  │  Tests ⇶  │  Quality  │  PR    │  ← stage bar
+├─────────────────────────────────────────────────────────────────┤
+│  > Describe your task…                                          │  ← prompt input
+├──────────────────────────────┬──────────────────────────────────┤
+│  ● Planning                  │                                  │
+│                              │         Activity log             │
+│      Streaming pane          │   (full chronological history)   │
+│  (live output from active    │                                  │
+│   stage or worker)           │                                  │
+├──────────────────────────────┴──────────────────────────────────┤
+│  ^p palette  ^l Clear Log  ctrl+↵ Run  ^e Export Log  ^m Monitor        Calls: 4  |  Cost: $0.0234  |  Time: 1m 20s  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Project structure
+
+```
+app/
+├── __main__.py      Entry point
+├── models.py        Shared data classes (Task, WorkerResult, PipelineStats)
+├── agents.py        Claude CLI invocation, flow control, and worker coordination
+├── stages.py        Stage definitions, prompt templates, and pipeline configuration
+├── pipeline.py      Stage runners: run_stage() and run_stage_parallel()
+├── runner.py        PipelineRunnerMixin: run_pipeline() and rerun_from_stage()
+├── widgets.py       StagePill TUI widget and display constants
+├── git.py           Git/gh subprocess helpers and Commit & PR stage runner
+└── tui.py           PipelineApp (Textual App) and main() entry point
+```
+
+---
+
+## Safety
+
+The pipeline invokes `claude --dangerously-skip-permissions` so agents can read and write files autonomously. **Only point it at repositories where you trust the output.** Always review the diff before the PR stage commits.
+
+Each subprocess is run with a 10-minute timeout and cleaned up unconditionally on exit — even on errors or cancellation — so stalled Claude processes do not accumulate.
+
+---
+
+## License
+
+MIT © Valentin Dutra — see [LICENSE](LICENSE)

step_by_step_cli-0.1.0/app/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for the pipeline TUI."""
+
+from app.tui import main
+
+main()

step_by_step_cli-0.1.0/app/agents.py

@@ -0,0 +1,42 @@
+"""Manager agent: task decomposition."""
+
+import json
+
+from app.claude import call_claude
+from app.models import Task
+
+
+async def decompose_task(prompt: str, plan: str, working_dir: str) -> list[Task]:
+    """Manager agent: decompose a plan into independent parallel subtasks."""
+    decompose_prompt = (
+        "You are a task decomposition agent. Given a plan, break it into independent subtasks "
+        "that can be worked on IN PARALLEL by different engineers.\n\n"
+        f"ORIGINAL TASK: {prompt}\n\n"
+        f"PLAN:\n{plan}\n\n"
+        "Output a JSON array of subtasks. Each subtask should have:\n"
+        '- "id": sequential integer starting at 1\n'
+        '- "description": what to implement (be specific and self-contained, include enough context)\n'
+        '- "files": list of files this subtask will create or modify\n\n'
+        "Rules:\n"
+        "- Each subtask must be independent enough to work on in parallel\n"
+        "- Include enough context in each description so a worker can act without seeing other subtasks\n"
+        "- Create as many subtasks as the complexity genuinely requires — no artificial limit\n"
+        "- If the task is simple and cannot be split, return a single subtask\n"
+        "- Output ONLY the JSON array, no markdown fences or other text\n"
+    )
+
+    success, output, _ = await call_claude(decompose_prompt, working_dir)
+    if not success:
+        return [Task(id=1, description=prompt)]
+
+    try:
+        text = output.strip()
+        if text.startswith("```"):
+            text = text.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+        tasks_data = json.loads(text)
+        return [
+            Task(id=t["id"], description=t["description"], files=t.get("files", []))
+            for t in tasks_data
+        ]
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return [Task(id=1, description=prompt)]

step_by_step_cli-0.1.0/app/claude.py

@@ -0,0 +1,149 @@
+"""Claude CLI invocation and iteration evaluation."""
+
+import asyncio
+import json
+
+_CLAUDE_TIMEOUT = 600  # seconds per subprocess call
+
+
+async def call_claude(
+    prompt: str,
+    working_dir: str,
+    on_stream=None,
+) -> tuple[bool, str, float]:
+    """Call Claude CLI and return (success, output, cost_usd).
+
+    Streams output chunks to on_stream(chunk: str) if provided.
+    Drains stderr concurrently to prevent pipe deadlock.
+    Always cleans up the subprocess on exit.
+    """
+    proc = None
+    stderr_task: asyncio.Task | None = None
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "claude",
+            "--print",
+            "--dangerously-skip-permissions",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=working_dir,
+        )
+
+        proc.stdin.write(prompt.encode())
+        await proc.stdin.drain()
+        proc.stdin.close()
+
+        final_output = ""
+        cost_usd = 0.0
+        early_result: tuple[bool, str, float] | None = None
+
+        stderr_chunks: list[bytes] = []
+
+        async def _drain_stderr() -> None:
+            while True:
+                chunk = await proc.stderr.read(4096)
+                if not chunk:
+                    break
+                stderr_chunks.append(chunk)
+
+        stderr_task = asyncio.create_task(_drain_stderr())
+
+        buf = b""
+        try:
+            async with asyncio.timeout(_CLAUDE_TIMEOUT):
+                while True:
+                    raw_chunk = await proc.stdout.read(65536)
+                    if not raw_chunk:
+                        break
+                    buf += raw_chunk
+                    while b"\n" in buf:
+                        raw_line, buf = buf.split(b"\n", 1)
+                        line = raw_line.decode(errors="replace").strip()
+                        if not line:
+                            continue
+                        try:
+                            event = json.loads(line)
+                            etype = event.get("type")
+                            if etype == "assistant" and on_stream:
+                                for block in event.get("message", {}).get("content", []):
+                                    if block.get("type") == "text":
+                                        chunk = block["text"]
+                                        if asyncio.iscoroutinefunction(on_stream):
+                                            await on_stream(chunk)
+                                        else:
+                                            on_stream(chunk)
+                            elif etype == "result":
+                                final_output = event.get("result", "")
+                                cost_usd = float(event.get("total_cost_usd") or 0.0)
+                                if event.get("subtype") == "error" or event.get("is_error"):
+                                    early_result = (
+                                        False,
+                                        final_output or "Claude returned an error",
+                                        cost_usd,
+                                    )
+                        except (json.JSONDecodeError, KeyError, TypeError):
+                            pass
+                    if early_result:
+                        break
+        except asyncio.TimeoutError:
+            return False, f"Timeout after {_CLAUDE_TIMEOUT}s", 0.0
+
+        await stderr_task
+        stderr_task = None
+        await proc.wait()
+
+        if early_result:
+            from app.models import pipeline_stats
+            pipeline_stats.add_call(early_result[2])
+            return early_result
+
+        if proc.returncode != 0 and not final_output:
+            stderr_data = b"".join(stderr_chunks)
+            err = stderr_data.decode().strip() or f"Exit code {proc.returncode}"
+            return False, err, 0.0
+
+        from app.models import pipeline_stats
+        pipeline_stats.add_call(cost_usd)
+        return True, final_output, cost_usd
+
+    except FileNotFoundError:
+        return (
+            False,
+            "'claude' CLI not found. Install: npm install -g @anthropic-ai/claude-code",
+            0.0,
+        )
+    except Exception as e:
+        return False, str(e), 0.0
+    finally:
+        if stderr_task is not None and not stderr_task.done():
+            stderr_task.cancel()
+            try:
+                await stderr_task
+            except asyncio.CancelledError:
+                pass
+        if proc is not None and proc.returncode is None:
+            proc.kill()
+            try:
+                await proc.wait()
+            except Exception:
+                pass
+
+
+async def evaluate_should_iterate(stage_output: str, working_dir: str) -> bool:
+    """Ask Claude whether the stage output has issues that require another iteration."""
+    prompt = (
+        "You are a quality gate agent. Review the following stage output and decide "
+        "whether it contains genuine issues that require another implementation iteration.\n\n"
+        "Answer ONLY with 'yes' if there are real issues that need fixing, "
+        "or 'no' if the output is satisfactory and the pipeline can proceed.\n\n"
+        f"STAGE OUTPUT:\n{stage_output[:4000]}"
+    )
+    success, response, _ = await call_claude(prompt, working_dir)
+    if not success:
+        return False
+    return response.strip().lower().startswith("yes")