step-by-step-cli 0.1.0__py3-none-any.whl

app/__main__.py

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

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)]

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")

app/git.py

@@ -0,0 +1,152 @@
+"""Git and GitHub CLI helpers for the Commit & PR stage."""
+
+import asyncio
+import json
+
+from app.claude import call_claude
+from app.stages import Stage
+
+
+async def _git(working_dir: str, *args: str) -> tuple[int, str, str]:
+    proc = await asyncio.create_subprocess_exec(
+        "git", *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        cwd=working_dir,
+    )
+    out, err = await proc.communicate()
+    return proc.returncode, out.decode().strip(), err.decode().strip()
+
+
+async def _gh(working_dir: str, *args: str) -> tuple[int, str, str]:
+    proc = await asyncio.create_subprocess_exec(
+        "gh", *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        cwd=working_dir,
+    )
+    out, err = await proc.communicate()
+    return proc.returncode, out.decode().strip(), err.decode().strip()
+
+
+async def create_branch(
+    prompt: str,
+    working_dir: str,
+    on_log=None,
+) -> str:
+    """Ask Claude to pick a branch name based on the task and create it."""
+    branch_prompt = (
+        "Given the following task, output ONLY a git branch name — no explanation, no punctuation, nothing else.\n"
+        "Rules:\n"
+        "- Format: type/short-kebab-description\n"
+        "- type: feat, fix, docs, refactor, test, or chore\n"
+        "- Max 50 chars total, lowercase, hyphens only (no extra slashes)\n"
+        "- Example: feat/add-user-authentication\n\n"
+        f"TASK: {prompt}"
+    )
+
+    success, output, _ = await call_claude(branch_prompt, working_dir)
+    if not success:
+        return ""
+
+    branch_name = output.strip().strip("`").split("\n")[0].strip()
+
+    rc, _, err = await _git(working_dir, "checkout", "-b", branch_name)
+    if rc != 0:
+        if on_log:
+            on_log(f"git checkout -b failed: {err}")
+        return ""
+
+    if on_log:
+        on_log(f"branch: {branch_name}")
+    return branch_name
+
+
+async def run_commit_pr_stage(
+    stage: Stage,
+    prompt: str,
+    prev_output: str,
+    working_dir: str,
+    on_stream=None,
+    on_log=None,
+) -> str:
+    """Commit changes with conventional commits and open a GitHub PR."""
+    stage.start()
+    lines: list[str] = []
+
+    def _log(msg: str) -> None:
+        lines.append(msg)
+        if on_log:
+            on_log(msg)
+
+    _, diff_stat, _ = await _git(working_dir, "diff", "HEAD", "--stat")
+    if not diff_stat:
+        _, diff_stat, _ = await _git(working_dir, "diff", "--stat")
+    if not diff_stat:
+        _, diff_stat, _ = await _git(working_dir, "status", "--short")
+
+    _, current_branch, _ = await _git(working_dir, "rev-parse", "--abbrev-ref", "HEAD")
+
+    conv_prompt = stage.prompt_template.format(
+        prompt=prompt,
+        prev_output=prev_output[:3000],
+        diff_stat=diff_stat[:1500] if diff_stat else "No changes detected yet",
+    )
+
+    success, conv_output, _ = await call_claude(conv_prompt, working_dir, on_stream=on_stream)
+    if not success:
+        stage.fail(f"Failed to generate commit info: {conv_output}")
+        return ""
+
+    try:
+        text = conv_output.strip()
+        if text.startswith("```"):
+            text = text.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+        pr_data = json.loads(text)
+        commits: list[dict] = pr_data.get("commits", [])
+        pr_title: str = pr_data.get("pr_title", f"feat: {prompt[:60]}")
+        pr_body: str = pr_data.get("pr_body", f"## Summary\n- {prompt}\n\n## Test Plan\n- [ ] Manual testing")
+    except (json.JSONDecodeError, KeyError, TypeError):
+        commits = [{"type": "feat", "scope": "", "message": prompt[:60]}]
+        pr_title = f"feat: {prompt[:60]}"
+        pr_body = f"## Summary\n- {prompt}\n\n## Test Plan\n- [ ] Manual testing"
+
+    rc, _, err = await _git(working_dir, "add", "-A")
+    if rc != 0:
+        stage.fail(f"git add failed: {err}")
+        return ""
+
+    _, status_out, _ = await _git(working_dir, "status", "--porcelain")
+    if status_out:
+        for c in commits:
+            ctype = c.get("type", "feat").strip()
+            scope = c.get("scope", "").strip()
+            msg = c.get("message", "update").strip()
+            commit_msg = f"{ctype}({scope}): {msg}" if scope else f"{ctype}: {msg}"
+
+            rc, _, err = await _git(working_dir, "commit", "-m", commit_msg)
+            if rc != 0 and "nothing to commit" not in err and "nothing added" not in err:
+                stage.fail(f"git commit failed: {err}")
+                return "\n".join(lines)
+            _log(f"commit: {commit_msg}")
+    else:
+        _log("nothing to commit — working tree clean")
+
+    rc, pr_url, err = await _gh(
+        working_dir,
+        "pr", "create",
+        "--title", pr_title,
+        "--body", pr_body,
+    )
+    if rc != 0:
+        if "already exists" in err.lower() or "pull request" in err.lower():
+            _log(f"PR already exists for branch '{current_branch}'")
+        else:
+            stage.fail(f"gh pr create failed: {err}")
+            return "\n".join(lines)
+    else:
+        _log(f"PR created: {pr_url}")
+
+    result = "\n".join(lines)
+    stage.complete(result)
+    return result

app/models.py

@@ -0,0 +1,74 @@
+"""Shared data models for the multi-agent pipeline."""
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class AgentRole(Enum):
+    MANAGER = "manager"
+    WORKER = "worker"
+
+
+@dataclass
+class Task:
+    id: int
+    description: str
+    files: list[str] = field(default_factory=list)
+    status: str = "pending"
+    output: str = ""
+    elapsed: float = 0.0
+    error: str = ""
+
+
+@dataclass
+class WorkerResult:
+    task_id: int
+    success: bool
+    output: str
+    elapsed: float
+    error: str = ""
+
+
+@dataclass
+class PipelineStats:
+    total_cost_usd: float = 0.0
+    total_calls: int = 0
+    total_stage_time: float = 0.0
+    start_time: float = 0.0
+
+    def reset(self):
+        self.total_cost_usd = 0.0
+        self.total_calls = 0
+        self.total_stage_time = 0.0
+        self.start_time = time.time()
+
+    def add_call(self, cost_usd: float):
+        self.total_cost_usd += cost_usd
+        self.total_calls += 1
+
+    def add_stage_time(self, elapsed: float):
+        self.total_stage_time += elapsed
+
+    @property
+    def elapsed(self) -> float:
+        if self.start_time == 0.0:
+            return 0.0
+        return time.time() - self.start_time
+
+    @staticmethod
+    def _fmt(secs: float) -> str:
+        s = int(secs)
+        if s < 60:
+            return f"{s}s"
+        m, s = divmod(s, 60)
+        return f"{m}m {s}s"
+
+    def format_elapsed(self) -> str:
+        return self._fmt(self.elapsed)
+
+    def format_stage_time(self) -> str:
+        return self._fmt(self.total_stage_time)
+
+
+pipeline_stats = PipelineStats()

app/pipeline.py

@@ -0,0 +1,79 @@
+"""Pipeline stage runners."""
+
+from app.claude import call_claude
+from app.models import Task
+from app.stages import Stage, StageStatus
+from app.workers import run_workers_parallel, aggregate_results
+
+
+async def run_stage(
+    stage: Stage,
+    prompt: str,
+    prev_output: str,
+    working_dir: str,
+    iteration_context: str = "",
+    on_stream=None,
+) -> str:
+    """Run a single pipeline stage (manager mode — single agent)."""
+    stage.start()
+
+    full_prompt = stage.prompt_template.format(
+        prompt=prompt,
+        prev_output=prev_output[:8000],
+        iteration_context=iteration_context,
+    )
+
+    success, output, _ = await call_claude(full_prompt, working_dir, on_stream=on_stream)
+
+    if success:
+        stage.complete(output)
+        return output
+    else:
+        stage.fail(output)
+        return ""
+
+
+async def run_stage_parallel(
+    stage: Stage,
+    tasks: list[Task],
+    prompt: str,
+    prev_output: str,
+    working_dir: str,
+    iteration_context: str = "",
+    on_worker_start=None,
+    on_worker_complete=None,
+    on_stream=None,
+) -> str:
+    """Run a pipeline stage in parallel worker mode (fan-out to multiple agents)."""
+    stage.start()
+    stage.tasks = tasks
+
+    worker_prompts = [
+        stage.worker_prompt_template.format(
+            prompt=prompt,
+            task_description=task.description,
+            task_files=", ".join(task.files) if task.files else "as needed",
+            prev_output=prev_output[:6000],
+            iteration_context=iteration_context,
+        )
+        for task in tasks
+    ]
+
+    results = await run_workers_parallel(
+        tasks,
+        worker_prompts,
+        working_dir,
+        on_start=on_worker_start,
+        on_complete=on_worker_complete,
+        on_stream=on_stream,
+    )
+
+    failures = [r for r in results if not r.success]
+    if failures:
+        error_msgs = "; ".join(f"Worker {r.task_id}: {r.error}" for r in failures)
+        stage.fail(error_msgs)
+        return ""
+
+    output = aggregate_results(results)
+    stage.complete(output)
+    return output

app/prompts.py

@@ -0,0 +1,156 @@
+"""Stage prompt templates."""
+
+PLANNING = (
+    "You are a senior software architect. Given the following task, create a detailed implementation plan.\n\n"
+    "TASK: {prompt}\n\n"
+    "Create:\n"
+    "1. A numbered list of implementation tasks (ordered by dependency)\n"
+    "2. For each task: what files to create/modify, key decisions, and acceptance criteria\n"
+    "3. Identify risks, ambiguities, and potential edge cases\n\n"
+    "Be specific and actionable. Output the plan in markdown."
+)
+
+IMPLEMENTATION = (
+    "You are a senior software engineer. Implement the following plan.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "PLAN:\n{prev_output}\n\n"
+    "{iteration_context}"
+    "Write clean, production-ready code. Follow the plan step by step.\n"
+    "Use best practices, proper error handling, and clear naming.\n"
+    "Output the complete implementation."
+)
+
+IMPLEMENTATION_WORKER = (
+    "You are a senior software engineer working as part of a team.\n"
+    "You are responsible for ONE specific subtask.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "YOUR SUBTASK: {task_description}\n"
+    "FILES TO WORK ON: {task_files}\n\n"
+    "FULL PLAN FOR CONTEXT:\n{prev_output}\n\n"
+    "{iteration_context}"
+    "Implement ONLY your subtask. Write clean, production-ready code.\n"
+    "Use best practices, proper error handling, and clear naming.\n"
+    "Output the complete implementation for your subtask."
+)
+
+TESTS = (
+    "You are a senior QA engineer. Write comprehensive tests for the implementation below.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "IMPLEMENTATION:\n{prev_output}\n\n"
+    "{iteration_context}"
+    "Create:\n"
+    "1. Unit tests covering all functions/methods\n"
+    "2. Edge cases and error scenarios\n"
+    "3. Integration tests where applicable\n\n"
+    "Use the appropriate test framework for the language.\n"
+    "Report any real, unfixed problems clearly. If everything is correct, state that all tests pass."
+)
+
+TESTS_WORKER = (
+    "You are a senior QA engineer working as part of a team.\n"
+    "You are responsible for testing ONE specific subtask.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "YOUR SUBTASK TO TEST: {task_description}\n"
+    "FILES INVOLVED: {task_files}\n\n"
+    "IMPLEMENTATION:\n{prev_output}\n\n"
+    "{iteration_context}"
+    "Create comprehensive tests for your subtask:\n"
+    "1. Unit tests covering all functions/methods\n"
+    "2. Edge cases and error scenarios\n"
+    "3. Integration tests where applicable\n\n"
+    "Report any real, unfixed problems clearly. If everything is correct, state that all tests pass."
+)
+
+CODE_QUALITY = (
+    "You are a senior code reviewer and software architect. Perform a thorough quality and technical debt audit.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "IMPLEMENTATION:\n{prev_output}\n\n"
+    "{iteration_context}"
+    "Review and fix the following categories — apply every fix you can inline:\n\n"
+    "**Code Quality**\n"
+    "1. Naming conventions and clarity (variables, functions, classes, modules)\n"
+    "2. Code structure, separation of concerns, and readability\n"
+    "3. DRY violations and unnecessary duplication\n"
+    "4. Dead code, unused imports, unreachable branches\n\n"
+    "**Technical Debt**\n"
+    "5. Shortcuts, hacks, or TODO/FIXME comments that need resolution\n"
+    "6. Fragile patterns, implicit assumptions, and magic values\n"
+    "7. Missing abstractions or premature abstractions\n"
+    "8. Coupling issues: tight coupling between modules that should be independent\n\n"
+    "**Robustness**\n"
+    "9. Security vulnerabilities (injection, auth, data exposure, unsafe deserialization)\n"
+    "10. Missing or inadequate error handling and edge case coverage\n"
+    "11. Performance bottlenecks and unnecessary allocations\n"
+    "12. Test coverage gaps: critical paths that lack tests\n\n"
+    "Output the improved code with a clear summary of every change made and why.\n"
+    "If there are issues that cannot be fixed inline and require a full re-implementation pass, "
+    "describe them explicitly and clearly."
+)
+
+DOCUMENTATION = (
+    "You are a senior technical writer and developer advocate. "
+    "Generate complete, professional-grade documentation for everything that was implemented.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "IMPLEMENTATION:\n{prev_output}\n\n"
+    "Produce ALL of the following sections:\n\n"
+    "## 1. Overview\n"
+    "- What was built and why (the problem it solves)\n"
+    "- High-level architecture description with an ASCII diagram if applicable\n"
+    "- Key design decisions and the rationale behind them\n\n"
+    "## 2. Getting Started\n"
+    "- Prerequisites and dependencies\n"
+    "- Installation and setup instructions (step by step)\n"
+    "- Configuration options and environment variables (with defaults and descriptions)\n"
+    "- A minimal working example that a new developer can run immediately\n\n"
+    "## 3. Usage Guide\n"
+    "- Common use cases with full code examples\n"
+    "- Edge cases and how to handle them\n"
+    "- Known limitations and workarounds\n\n"
+    "## 4. API Reference\n"
+    "- Every public function, class, and method\n"
+    "- For each: signature, parameter descriptions (name, type, purpose, default), "
+    "return value, exceptions raised, and a usage example\n\n"
+    "## 5. Inline Documentation\n"
+    "- Show the final code with complete docstrings / JSDoc on every public symbol\n"
+    "- Inline comments for any non-obvious logic\n\n"
+    "## 6. Architecture & Design Notes\n"
+    "- Trade-offs considered and rejected alternatives\n"
+    "- Extension points and how to add new functionality\n"
+    "- Performance characteristics and scaling considerations\n\n"
+    "## 7. Testing Guide\n"
+    "- How to run the test suite\n"
+    "- What each test category covers\n"
+    "- How to add new tests\n\n"
+    "## 8. Changelog Entry\n"
+    "- A professional CHANGELOG entry for this implementation\n\n"
+    "Format everything in clean, professional markdown. "
+    "Be thorough — this documentation should be sufficient for a developer who has never seen "
+    "this code to understand, use, and extend it confidently."
+)
+
+COMMIT_PR = (
+    "You are a senior engineer preparing a pull request.\n\n"
+    "ORIGINAL TASK: {prompt}\n\n"
+    "IMPLEMENTATION SUMMARY:\n{prev_output}\n\n"
+    "GIT DIFF STAT:\n{diff_stat}\n\n"
+    "Generate conventional commit messages and a PR description.\n"
+    "Output ONLY a JSON object — no markdown fences, no extra text:\n"
+    "{{\n"
+    '  "commits": [\n'
+    '    {{"type": "feat|fix|docs|refactor|test|chore", "scope": "module-or-empty", "message": "imperative lowercase description"}}\n'
+    "  ],\n"
+    '  "pr_title": "type(scope): short description",\n'
+    '  "pr_body": "## Summary\\n- bullet\\n\\n## Test Plan\\n- [ ] item"\n'
+    "}}\n\n"
+    "Conventional commit rules:\n"
+    "- feat: new user-visible feature\n"
+    "- fix: bug fix\n"
+    "- docs: documentation only\n"
+    "- refactor: no behaviour change\n"
+    "- test: adding or fixing tests\n"
+    "- chore: tooling, deps, config\n"
+    "- scope: affected module / package (omit if unclear)\n"
+    "- message: imperative mood, lowercase, ≤72 chars, no trailing period\n"
+    "- Group tightly related file changes into one commit\n"
+    "- Separate docs changes into their own docs commit if docs files were modified"
+)