loopflow 0.2.2__tar.gz → 0.3.0__tar.gz

{loopflow-0.2.2 → loopflow-0.3.0}/.gitignore

@@ -4,5 +4,5 @@ __pycache__/
 # Claude Code (personal state)
 .claude/settings.local.json
 
-# Worktrees (created by lf start)
-.lf/worktrees/
+# Research/reference files
+files/

{loopflow-0.2.2 → loopflow-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopflow
-Version: 0.2.2
+Version: 0.3.0
 Summary: Arrange LLMs to code in harmony
 Author: Jack
 License-Expression: MIT
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 
 Run LLM coding tasks from reusable prompt files.
 
-macOS only. Currently uses Claude Code; other backends planned.
+macOS only. Supports Claude Code and OpenAI Codex via configuration.
 
 ## Install
 
@@ -48,7 +48,7 @@ The workflow: create a worktree, run tasks there, merge when ready. You can have
 
 ```bash
 lf wt create my-feature       # branch + worktree, opens IDEs
-cd .lf/worktrees/my-feature
+cd ../loopflow.my-feature     # worktrees are sibling directories
 
 lf design                     # interactive: figure out what to build
 lf ship                       # batch: implement, review, test, commit, open PR
@@ -103,15 +103,33 @@ lf ship    # runs each task, auto-commits between steps
 ## Worktrees
 
 ```bash
-lf wt create auth             # .lf/worktrees/auth/, opens Warp + Cursor
+lf wt create auth             # ../loopflow.auth/, opens Warp + Cursor
 lf wt list                    # show all worktrees
 lf wt clean                   # remove merged branches
 ```
 
+## Session Tracking
+
+Track running tasks across multiple terminals with the maestro daemon:
+
+```bash
+lf maestro start              # start tracking daemon
+lf status                     # show running sessions
+
+# In another terminal
+lf implement -p               # batch task registers automatically
+
+# Check from anywhere
+lf status                     # see all running sessions
+```
+
+When maestro is running, tasks automatically register, and you'll get macOS notifications when batch tasks complete.
+
 ## Configuration
 
 ```yaml
 # .lf/config.yaml
+model: claude     # Model to use (claude or codex)
 push: true        # auto-push after commits
 pr: false         # open PR after pipelines
 
@@ -128,6 +146,8 @@ ide:
 | `-x, --context` | Add context files |
 | `-w, --worktree` | Create worktree and run task there |
 | `-c, --copy` | Copy prompt to clipboard, show token breakdown |
+| `-m, --model` | Choose model (claude, codex) |
+| `--parallel` | Run with multiple models in parallel |
 
 ## Commands
 
@@ -137,7 +157,12 @@ ide:
 | `lf <pipeline>` | Run a pipeline |
 | `lf : "prompt"` | Inline prompt |
 | `lf wt create/list/clean` | Worktree management |
+| `lf wt compare <a> <b>` | Compare two worktree implementations |
 | `lf pr create` | Open GitHub PR |
 | `lf pr land [-a]` | Squash-merge to main |
+| `lf meta init` | Initialize repo with prompts and config |
 | `lf meta install` | Install Claude Code |
 | `lf meta doctor` | Check dependencies |
+| `lf maestro start` | Start session tracking daemon |
+| `lf maestro stop` | Stop session tracking daemon |
+| `lf status` | Show running sessions |

{loopflow-0.2.2 → loopflow-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 Run LLM coding tasks from reusable prompt files.
 
-macOS only. Currently uses Claude Code; other backends planned.
+macOS only. Supports Claude Code and OpenAI Codex via configuration.
 
 ## Install
 
@@ -21,7 +21,7 @@ The workflow: create a worktree, run tasks there, merge when ready. You can have
 
 ```bash
 lf wt create my-feature       # branch + worktree, opens IDEs
-cd .lf/worktrees/my-feature
+cd ../loopflow.my-feature     # worktrees are sibling directories
 
 lf design                     # interactive: figure out what to build
 lf ship                       # batch: implement, review, test, commit, open PR
@@ -76,15 +76,33 @@ lf ship    # runs each task, auto-commits between steps
 ## Worktrees
 
 ```bash
-lf wt create auth             # .lf/worktrees/auth/, opens Warp + Cursor
+lf wt create auth             # ../loopflow.auth/, opens Warp + Cursor
 lf wt list                    # show all worktrees
 lf wt clean                   # remove merged branches
 ```
 
+## Session Tracking
+
+Track running tasks across multiple terminals with the maestro daemon:
+
+```bash
+lf maestro start              # start tracking daemon
+lf status                     # show running sessions
+
+# In another terminal
+lf implement -p               # batch task registers automatically
+
+# Check from anywhere
+lf status                     # see all running sessions
+```
+
+When maestro is running, tasks automatically register, and you'll get macOS notifications when batch tasks complete.
+
 ## Configuration
 
 ```yaml
 # .lf/config.yaml
+model: claude     # Model to use (claude or codex)
 push: true        # auto-push after commits
 pr: false         # open PR after pipelines
 
@@ -101,6 +119,8 @@ ide:
 | `-x, --context` | Add context files |
 | `-w, --worktree` | Create worktree and run task there |
 | `-c, --copy` | Copy prompt to clipboard, show token breakdown |
+| `-m, --model` | Choose model (claude, codex) |
+| `--parallel` | Run with multiple models in parallel |
 
 ## Commands
 
@@ -110,7 +130,12 @@ ide:
 | `lf <pipeline>` | Run a pipeline |
 | `lf : "prompt"` | Inline prompt |
 | `lf wt create/list/clean` | Worktree management |
+| `lf wt compare <a> <b>` | Compare two worktree implementations |
 | `lf pr create` | Open GitHub PR |
 | `lf pr land [-a]` | Squash-merge to main |
+| `lf meta init` | Initialize repo with prompts and config |
 | `lf meta install` | Install Claude Code |
 | `lf meta doctor` | Check dependencies |
+| `lf maestro start` | Start session tracking daemon |
+| `lf maestro stop` | Stop session tracking daemon |
+| `lf status` | Show running sessions |

{loopflow-0.2.2 → loopflow-0.3.0}/pyproject.toml

@@ -41,9 +41,19 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/loopflow"]
+include = [
+    "src/loopflow/prompts/*.md",
+    "src/loopflow/LOOPFLOW_STYLE.md",
+    "src/loopflow/config_template.yaml",
+]
 
 [tool.hatch.build.targets.sdist]
-include = ["src/loopflow"]
+include = [
+    "src/loopflow",
+    "src/loopflow/prompts/*.md",
+    "src/loopflow/LOOPFLOW_STYLE.md",
+    "src/loopflow/config_template.yaml",
+]
 
 [tool.hatch.version]
 path = "src/loopflow/__init__.py"

loopflow-0.3.0/src/loopflow/LOOPFLOW_STYLE.md

@@ -0,0 +1,130 @@
+# Style Guide
+
+This is the governing document for this codebase. Humans and LLMs alike are expected to follow it.
+
+## Quick Reference
+
+- Prefix private functions with `_`
+- Return `None` for "not found"; raise exceptions for "shouldn't happen"
+- No `Args:`/`Returns:` docstrings—if types are clear, skip the docstring
+- Mock side effects, but don't test mock wiring
+
+# Goals
+
+## Clarity
+
+Design around data structures and public APIs. Aim for a 1:1 mapping between real-world concepts and their representation in code.
+
+Write code that demonstrates its own correctness. If a feature exists, write a test that proves it works. Assume you won't finish everything you start—make it easy to see what's done and what's broken.
+
+## Simplicity
+
+Every line of code must earn its place. Readable code is not terse code; don't sacrifice clarity for brevity. But recognize that lines can be net-negative:
+
+* Unused code
+* Comments that restate the obvious
+* Checks for impossible conditions
+
+Start with minimal data structures and APIs. If the core is right, trimming excess at the edges is straightforward.
+
+# Code Organization
+
+Consistency with existing code matters more than any specific rule.
+
+Keep information in one place. Version numbers, configuration, documentation—each piece of information should have a single source of truth. Don't duplicate versions in multiple files. If something needs to appear in multiple places, generate it or reference the source.
+
+Put imports at the top of the file, not inline.
+
+Keep one implementation. Avoid `v2_`, `_old`, `_new`, `_backup` prefixes and suffixes—look up old versions in git. If you're tempted to keep both old and new code around, delete the old version and commit. You can always get it back from git if needed.
+
+Don't maintain backwards compatibility unless explicitly required. If a config format or API changes, migrate everything to the new format—don't write code that handles both old and new. Backwards compatibility is for production databases and published APIs with external users, not internal config files.
+
+## Naming
+
+Use verb-first names for action functions: `find_user()`, `load_config()`, `create_session()`.
+
+Prefix private functions with underscore: `_validate()`, `_parse_line()`.
+
+Name things after what they are, not what they're for: `Document`, `Session`, `Target`—not `DocumentHelper`, `SessionManager`, `OutputHandler`.
+
+## Error Handling
+
+Errors are for users; exceptions are for programmers.
+
+Return errors when the caller should handle them—invalid input, missing files, failed requests. Raise exceptions for bugs: violated invariants, impossible states, programming mistakes.
+
+```python
+# Error: caller decides what to do
+def find_config(path: Path) -> Optional[Config]:
+    if not path.exists():
+        return None
+    return load(path)
+
+# Exception: this shouldn't happen
+def get_target(name: str) -> Target:
+    if name not in TARGETS:
+        raise ValueError(f"Unknown target: {name}")
+    return TARGETS[name]
+```
+
+When in doubt: if you'd write an `assert`, raise an exception instead—it's easier for callers to catch.
+
+# Documentation
+
+The best documentation is simple code. Descriptive names, type hints, and clear APIs often suffice.
+
+The worst documentation is wrong documentation. If it can drift from the code, it will. Update docs when you change code—or delete them.
+
+Put documentation next to code. A few paragraphs at the top of a key file beats a separate doc that nobody maintains.
+
+Skip obvious docstrings. If the function name and types tell the whole story, don't repeat it in prose.
+
+# Testing
+
+Test user behavior, not implementation details. A good test proves that something users care about actually works. Most tests don't meet that bar. Delete them.
+
+Aim for a mix:
+- **Smoke tests**: Does the system run without crashing?
+- **Edge case tests**: What happens at boundaries?
+- **Value tests**: Does this feature do what users expect?
+
+## When to Mock
+
+Mock to isolate your code from things that shouldn't be part of unit tests:
+- **External systems**: Network calls, databases, file systems (when testing logic, not I/O)
+- **Side effects**: Sending emails, writing logs, spawning processes
+- **Slow operations**: Anything that would make tests take seconds instead of milliseconds
+
+Don't mock to verify internal wiring. If a test's assertions are just "did we call the mock with the right args?"—that's testing implementation, not behavior. The test will break when you refactor, even if the feature still works.
+
+```python
+# Bad: testing that we called the mock correctly
+def test_send_notification():
+    with patch("app.email.send") as mock_send:
+        notify_user(user)
+        mock_send.assert_called_once_with(user.email, ANY)
+
+# Good: mock the side effect, test the behavior
+def test_notify_user_returns_success():
+    with patch("app.email.send"):  # prevent actual email
+        result = notify_user(user)
+        assert result.success
+
+# Better: if possible, test without mocking
+def test_notification_message_format():
+    msg = build_notification(user)
+    assert user.name in msg.body
+```
+
+If a test requires elaborate mock setup, it's usually a sign that either:
+1. The code under test does too much (refactor it)
+2. You're testing implementation rather than behavior (test something else)
+3. This should be an integration test, not a unit test (move it)
+
+# Git
+
+Commit messages are documentation. Explain what changed and why, not line-by-line what you did.
+
+Keep messages short—one sentence to one paragraph.
+
+Do not add AI attribution footers like "Generated with Claude Code" or "Co-Authored-By: Claude" to commits. The git history should read the same whether written by a human or AI.

loopflow-0.3.0/src/loopflow/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{loopflow-0.2.2 → loopflow-0.3.0}/src/loopflow/cli/__init__.py

@@ -15,21 +15,23 @@ app = typer.Typer(
 
 # Import and register subcommands
 from loopflow.cli import run as run_module
-from loopflow.cli import wt, pr, meta
+from loopflow.cli import wt, pr, meta, maestro, status
 
 app.add_typer(wt.app, name="wt")
 app.add_typer(pr.app, name="pr")
 app.add_typer(meta.app, name="meta")
+app.add_typer(maestro.app, name="maestro")
 
 # Register top-level commands
-app.command()(run_module.run)
+app.command(context_settings={"allow_extra_args": True, "allow_interspersed_args": True})(run_module.run)
 app.command()(run_module.inline)
 app.command(name="pipeline")(run_module.pipeline)
+app.command()(status.status)
 
 
 def main():
     """Entry point that supports 'lf <task>' and 'lf <pipeline>' shorthand."""
-    known_commands = {"run", "pipeline", "inline", "wt", "pr", "meta", "--help", "-h"}
+    known_commands = {"run", "pipeline", "inline", "wt", "pr", "meta", "maestro", "status", "--help", "-h"}
 
     try:
         if len(sys.argv) > 1:
@@ -40,6 +42,9 @@ def main():
                 sys.argv.pop(1)
                 sys.argv.insert(1, "inline")
             elif first_arg not in known_commands:
+                # Handle colon suffix: "lf implement: add logout" -> "lf implement add logout"
+                if first_arg.endswith(":"):
+                    sys.argv[1] = first_arg[:-1]
                 name = sys.argv[1]
                 repo_root = find_worktree_root()
                 config = load_config(repo_root) if repo_root else None

loopflow-0.3.0/src/loopflow/cli/maestro.py

@@ -0,0 +1,81 @@
+"""Maestro daemon management commands."""
+
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(help="Maestro daemon management.")
+
+
+def _get_paths() -> tuple[Path, Path, Path]:
+    """Get maestro file paths."""
+    lf_dir = Path.home() / ".lf"
+    return (
+        lf_dir / "maestro.sock",
+        lf_dir / "maestro.json",
+        lf_dir / "maestro.pid",
+    )
+
+
+def _is_running(pid_path: Path) -> bool:
+    """Check if maestro is running."""
+    if not pid_path.exists():
+        return False
+
+    try:
+        pid = int(pid_path.read_text().strip())
+        os.kill(pid, 0)  # Signal 0 checks if process exists
+        return True
+    except (OSError, ValueError):
+        # Process doesn't exist or invalid PID
+        return False
+
+
+@app.command()
+def start():
+    """Start the maestro daemon."""
+    socket_path, state_path, pid_path = _get_paths()
+
+    if _is_running(pid_path):
+        typer.echo("Maestro already running")
+        raise typer.Exit(0)
+
+    # Start daemon as background process
+    process = subprocess.Popen(
+        [sys.executable, "-m", "loopflow.maestro.daemon"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+    # Save PID
+    pid_path.parent.mkdir(parents=True, exist_ok=True)
+    pid_path.write_text(str(process.pid))
+
+    typer.echo(f"Maestro listening on {socket_path}")
+
+
+@app.command()
+def stop():
+    """Stop the maestro daemon."""
+    socket_path, state_path, pid_path = _get_paths()
+
+    if not _is_running(pid_path):
+        typer.echo("Maestro not running")
+        raise typer.Exit(0)
+
+    pid = int(pid_path.read_text().strip())
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+        pid_path.unlink()
+        if socket_path.exists():
+            socket_path.unlink()
+        typer.echo("Maestro stopped")
+    except OSError:
+        typer.echo("Failed to stop maestro", err=True)
+        raise typer.Exit(1)

{loopflow-0.2.2 → loopflow-0.3.0}/src/loopflow/cli/meta.py

@@ -3,6 +3,7 @@
 import platform
 import shutil
 import subprocess
+from pathlib import Path
 
 import typer
 
@@ -36,6 +37,73 @@ def _install_cask(name: str) -> bool:
     return result.returncode == 0
 
 
+@app.command()
+def init(
+    prompts_only: bool = typer.Option(False, "--prompts", help="Only install prompts"),
+    style_only: bool = typer.Option(False, "--style", help="Only install style guide"),
+):
+    """Initialize a repository with loopflow prompts, style guide, and config."""
+    repo_root = find_worktree_root()
+    if not repo_root:
+        typer.echo("Error: Not in a git repository", err=True)
+        raise typer.Exit(1)
+
+    # Determine what to install
+    install_prompts = prompts_only or not style_only
+    install_style = style_only or not prompts_only
+    install_config = not prompts_only and not style_only
+
+    # Get bundled assets path
+    bundled_dir = Path(__file__).parent.parent
+    prompts_dir = bundled_dir / "prompts"
+    style_template = bundled_dir / "LOOPFLOW_STYLE.md"
+    config_template = bundled_dir / "config_template.yaml"
+
+    # Install prompts to .claude/commands/ (accessible via raw claude too)
+    if install_prompts:
+        commands_dir = repo_root / ".claude" / "commands"
+        commands_dir.mkdir(parents=True, exist_ok=True)
+
+        for prompt_name in ["review.md", "implement.md", "design.md"]:
+            src = prompts_dir / prompt_name
+            dst = commands_dir / prompt_name
+
+            if dst.exists():
+                typer.echo(f"- .claude/commands/{prompt_name} (already exists)")
+            else:
+                shutil.copy(src, dst)
+                typer.echo(f"✓ Created .claude/commands/{prompt_name}")
+
+    # Install style guide to .lf/ (only included in lf sessions, not raw claude/codex)
+    if install_style:
+        lf_dir = repo_root / ".lf"
+        lf_dir.mkdir(exist_ok=True)
+        style_dst = lf_dir / "LOOPFLOW_STYLE.md"
+        if style_dst.exists():
+            typer.echo("- .lf/LOOPFLOW_STYLE.md (already exists)")
+        else:
+            shutil.copy(style_template, style_dst)
+            typer.echo("✓ Created .lf/LOOPFLOW_STYLE.md")
+
+    # Install config
+    if install_config:
+        config_dir = repo_root / ".lf"
+        config_dir.mkdir(exist_ok=True)
+        config_dst = config_dir / "config.yaml"
+
+        if config_dst.exists():
+            typer.echo("- .lf/config.yaml (already exists)")
+        else:
+            shutil.copy(config_template, config_dst)
+            typer.echo("✓ Created .lf/config.yaml")
+
+    if install_prompts and not prompts_only:
+        typer.echo("\nYou can now use:")
+        typer.echo("  lf review        # or: claude /review")
+        typer.echo("  lf implement")
+        typer.echo("  lf design")
+
+
 @app.command()
 def version():
     """Show loopflow version."""