loopflow 0.7.0__tar.gz → 0.7.2__tar.gz

{loopflow-0.7.0 → loopflow-0.7.2}/.gitignore

@@ -15,3 +15,5 @@ swift/dist/
 # Loopflow (generated cache)
 .lf/summaries/
 *.profraw
+.DS_Store
+target/

loopflow-0.7.2/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: loopflow
+Version: 0.7.2
+Summary: Run LLM coding agents from reusable prompt files
+Project-URL: Homepage, https://loopflowstudio.github.io/loopflow/
+Project-URL: Repository, https://github.com/loopflowstudio/loopflow
+Project-URL: Documentation, https://loopflowstudio.github.io/loopflow/
+Project-URL: Issues, https://github.com/loopflowstudio/loopflow/issues
+Project-URL: Changelog, https://github.com/loopflowstudio/loopflow/releases
+Author: Jack
+License-Expression: MIT
+Keywords: agents,ai,automation,claude,cli,codex,coding,gemini,llm,prompts,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: croniter>=2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: grpcio-tools>=1.60.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.34.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Loopflow
+
+Loopflow helps you maintain flow and craft using coding agents (Claude Code, Codex, Gemini CLI) at high scale.
+
+Loopflow helps you create and run **Waves**. Waves are chains of coding agents working together in pre-defined ways.  
+
+Waves are first built manually through more interactive exploration. Eventually waves become autonomous through looping, scheduling, and watching for changes.
+
+## Waves
+
+Waves are objects with 4 primary fields.
+
+| Field | Usage | Form |
+|-------|------|------|
+| **Area** | Scope and context | pathset |
+| **Flow** | Process followed / steps taken | sequence of prompts |
+| **Direction** | Defines success, quality, and aesthetics | prompt |
+| **Stimulus** | Watch, loop, or cron | mode |
+
+## Steps
+
+```bash
+lf debug -c    # paste an error, watch it fix
+lf design      # interactive design session
+```
+
+Steps are prompts that run coding agents. Add your own in `.lf/steps/`.
+
+### Planning steps (`plan/`)
+
+| Step | What it does |
+|------|--------------|
+| `review` | Research an area — architecture, complexity, quality, potential |
+| `reduce` | Find simplification opportunities |
+| `polish` | Find polish priorities |
+| `expand` | Find expansion opportunities |
+| `iterate` | Read review, write design to address it |
+| `ingest` | Pick roadmap item, move to scratch/ |
+| `kickoff` | Elaborate design — alternatives, research, imagine success/failure |
+| `roadmap` | Synthesize analysis into a roadmap proposal |
+| `5whys` | Root cause analysis on a bug fix |
+
+### Code steps (`code/`)
+
+| Step | What it does |
+|------|--------------|
+| `debug` | Fix an error |
+| `implement` | Build from a design doc |
+| `compress` | Simplify touched code |
+| `gate` | Ship-ready code and reviewer-friendly docs |
+
+### Interactive steps (`interactive/`)
+
+| Step | What it does |
+|------|--------------|
+| `design` | Interactive design session |
+| `explore` | Investigate the codebase |
+| `refine` | Refine existing work |
+
+### Ops steps (`ops/`)
+
+| Step | What it does |
+|------|--------------|
+| `consolidate` | Reorganize scratch/ for roadmap |
+| `add-to-roadmap` | Promote from scratch/ to roadmap/ |
+| `synthesize` | Combine multiple perspectives into one |
+| `validate` | Validate flows, steps, and directions |
+
+## Flows
+
+```bash
+lf design && lf implement && lf gate    # chain steps manually
+lf flow ship                            # or use a named flow
+```
+
+Steps chain into flows. Flows feed into waves.
+
+### Code flows (`code/`)
+
+| Flow | Steps |
+|------|-------|
+| `ship` | implement → compress → gate → consolidate |
+| `design-and-ship` | design → implement → reduce → polish |
+| `pair` | design → ship |
+| `grind` | review → iterate → ship → gate |
+| `incident` | debug → 5whys → ship |
+| `start` | ingest → kickoff |
+| `ship-roadmap` | start → ship |
+
+### Plan flows (`plan/`)
+
+| Flow | Steps |
+|------|-------|
+| `roadmap-reduce` | review → fork(reduce×3) → publish |
+| `roadmap-polish` | review → fork(polish×3) → publish |
+| `roadmap-expand` | review → fork(expand×3) → publish |
+| `research` | explore → review → publish |
+| `publish` | consolidate → add-to-roadmap |
+
+### Forks
+
+Forks run a step in parallel with different directions, then synthesize the results.
+
+```bash
+lf flow roadmap-reduce    # runs reduce 3x with different perspectives
+```
+
+`roadmap-reduce` forks `reduce` across infra-engineer, designer, and product-engineer directions, then synthesizes and publishes to roadmap.
+
+## Playing in the Waves
+
+Once you have played with chaining steps into flows, you're ready to start running waves.
+
+```bash
+lfd create engbot                         # create a wave
+lfd area engbot src/                      # set area
+lfd direction engbot product-engineer     # set direction
+lfd flow engbot ship                      # set flow
+lfd loop engbot                           # start looping
+```
+
+Runs the `ship` flow on `src/` continuously using the `product-engineer` direction, creating PRs until stopped.
+
+```bash
+lfd watch ship designs/ -d designer       # ship when designs/ changes on main
+```
+
+You can compose multiple directions to add additional nuance or perspectives.
+
+```bash
+lf review -d designer,product-engineer
+lf review -d ceo
+```
+
+## Install
+
+```bash
+uv tool install loopflow
+```
+
+Built-in steps and flows included. `lf init` sets up your coding agent and preferences.
+
+[Documentation →](docs/index.md)
+
+## Integrations
+
+**Coding Agents**
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's coding agent (default)
+- [Codex CLI](https://github.com/openai/codex) — OpenAI's coding agent
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) — Google's coding agent
+
+**Tools**
+- [worktrunk](https://github.com/loopflowstudio/worktrunk) — git worktree management (`wt` commands)
+
+**Skill Libraries**
+- [superpowers](https://github.com/obra/superpowers) — prompt library (`lf sp:<skill>`)
+- [SkillRegistry](https://skillregistry.io/) — remote skill directory (`lf sr:<skill>`)
+- [rams](https://rams.ai) — accessibility and visual design review
+
+## Requirements
+
+- macOS
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+
+## License
+
+MIT

loopflow-0.7.2/README.md

@@ -0,0 +1,167 @@
+# Loopflow
+
+Loopflow helps you maintain flow and craft using coding agents (Claude Code, Codex, Gemini CLI) at high scale.
+
+Loopflow helps you create and run **Waves**. Waves are chains of coding agents working together in pre-defined ways.  
+
+Waves are first built manually through more interactive exploration. Eventually waves become autonomous through looping, scheduling, and watching for changes.
+
+## Waves
+
+Waves are objects with 4 primary fields.
+
+| Field | Usage | Form |
+|-------|------|------|
+| **Area** | Scope and context | pathset |
+| **Flow** | Process followed / steps taken | sequence of prompts |
+| **Direction** | Defines success, quality, and aesthetics | prompt |
+| **Stimulus** | Watch, loop, or cron | mode |
+
+## Steps
+
+```bash
+lf debug -c    # paste an error, watch it fix
+lf design      # interactive design session
+```
+
+Steps are prompts that run coding agents. Add your own in `.lf/steps/`.
+
+### Planning steps (`plan/`)
+
+| Step | What it does |
+|------|--------------|
+| `review` | Research an area — architecture, complexity, quality, potential |
+| `reduce` | Find simplification opportunities |
+| `polish` | Find polish priorities |
+| `expand` | Find expansion opportunities |
+| `iterate` | Read review, write design to address it |
+| `ingest` | Pick roadmap item, move to scratch/ |
+| `kickoff` | Elaborate design — alternatives, research, imagine success/failure |
+| `roadmap` | Synthesize analysis into a roadmap proposal |
+| `5whys` | Root cause analysis on a bug fix |
+
+### Code steps (`code/`)
+
+| Step | What it does |
+|------|--------------|
+| `debug` | Fix an error |
+| `implement` | Build from a design doc |
+| `compress` | Simplify touched code |
+| `gate` | Ship-ready code and reviewer-friendly docs |
+
+### Interactive steps (`interactive/`)
+
+| Step | What it does |
+|------|--------------|
+| `design` | Interactive design session |
+| `explore` | Investigate the codebase |
+| `refine` | Refine existing work |
+
+### Ops steps (`ops/`)
+
+| Step | What it does |
+|------|--------------|
+| `consolidate` | Reorganize scratch/ for roadmap |
+| `add-to-roadmap` | Promote from scratch/ to roadmap/ |
+| `synthesize` | Combine multiple perspectives into one |
+| `validate` | Validate flows, steps, and directions |
+
+## Flows
+
+```bash
+lf design && lf implement && lf gate    # chain steps manually
+lf flow ship                            # or use a named flow
+```
+
+Steps chain into flows. Flows feed into waves.
+
+### Code flows (`code/`)
+
+| Flow | Steps |
+|------|-------|
+| `ship` | implement → compress → gate → consolidate |
+| `design-and-ship` | design → implement → reduce → polish |
+| `pair` | design → ship |
+| `grind` | review → iterate → ship → gate |
+| `incident` | debug → 5whys → ship |
+| `start` | ingest → kickoff |
+| `ship-roadmap` | start → ship |
+
+### Plan flows (`plan/`)
+
+| Flow | Steps |
+|------|-------|
+| `roadmap-reduce` | review → fork(reduce×3) → publish |
+| `roadmap-polish` | review → fork(polish×3) → publish |
+| `roadmap-expand` | review → fork(expand×3) → publish |
+| `research` | explore → review → publish |
+| `publish` | consolidate → add-to-roadmap |
+
+### Forks
+
+Forks run a step in parallel with different directions, then synthesize the results.
+
+```bash
+lf flow roadmap-reduce    # runs reduce 3x with different perspectives
+```
+
+`roadmap-reduce` forks `reduce` across infra-engineer, designer, and product-engineer directions, then synthesizes and publishes to roadmap.
+
+## Playing in the Waves
+
+Once you have played with chaining steps into flows, you're ready to start running waves.
+
+```bash
+lfd create engbot                         # create a wave
+lfd area engbot src/                      # set area
+lfd direction engbot product-engineer     # set direction
+lfd flow engbot ship                      # set flow
+lfd loop engbot                           # start looping
+```
+
+Runs the `ship` flow on `src/` continuously using the `product-engineer` direction, creating PRs until stopped.
+
+```bash
+lfd watch ship designs/ -d designer       # ship when designs/ changes on main
+```
+
+You can compose multiple directions to add additional nuance or perspectives.
+
+```bash
+lf review -d designer,product-engineer
+lf review -d ceo
+```
+
+## Install
+
+```bash
+uv tool install loopflow
+```
+
+Built-in steps and flows included. `lf init` sets up your coding agent and preferences.
+
+[Documentation →](docs/index.md)
+
+## Integrations
+
+**Coding Agents**
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's coding agent (default)
+- [Codex CLI](https://github.com/openai/codex) — OpenAI's coding agent
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) — Google's coding agent
+
+**Tools**
+- [worktrunk](https://github.com/loopflowstudio/worktrunk) — git worktree management (`wt` commands)
+
+**Skill Libraries**
+- [superpowers](https://github.com/obra/superpowers) — prompt library (`lf sp:<skill>`)
+- [SkillRegistry](https://skillregistry.io/) — remote skill directory (`lf sr:<skill>`)
+- [rams](https://rams.ai) — accessibility and visual design review
+
+## Requirements
+
+- macOS
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+
+## License
+
+MIT

{loopflow-0.7.0 → loopflow-0.7.2}/pyproject.toml

@@ -30,10 +30,12 @@ dependencies = [
     "pyyaml>=6.0",
     "pydantic>=2.12.5",
     "tiktoken>=0.7.0",
-    "asana>=5.0.0",
     "croniter>=2.0",
     "fastapi>=0.115.0",
     "uvicorn>=0.34.0",
+    "grpcio>=1.60.0",
+    "grpcio-tools>=1.60.0",
+    "protobuf>=4.25.0",
 ]
 
 [project.urls]
@@ -51,8 +53,6 @@ dev = [
 [project.scripts]
 lf = "loopflow.lf.cli:main"
 lfd = "loopflow.lfd.cli:main"
-lfops = "loopflow.lfops:main"
-lfwork = "loopflow.lfwork:main"
 
 [build-system]
 requires = ["hatchling"]
@@ -92,10 +92,12 @@ select = [
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["F841"]  # unused variables OK in test fixtures
+"src/loopflow/proto/**/*_pb2*" = ["E501", "F401", "F811", "I001", "E402"]  # generated protobuf code
 
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",
     "boto3>=1.35.0",
     "ruff>=0.9.0",
+    "maturin>=1.4,<2.0",
 ]

loopflow-0.7.2/src/loopflow/LOOPFLOW.md

@@ -0,0 +1,73 @@
+# Loopflow
+
+Run prompts, hand off cleanly. Each step does one thing and leaves state for the next.
+
+---
+
+## Area
+
+Your working scope. Everything here is relevant.
+
+**Area docs**: Patterns and constraints for this part of the codebase.
+
+**Repo docs**: STYLE, CLAUDE.md, and other guidelines. Follow them.
+
+**Direction**: Your perspective. Follow its principles.
+
+**Step**: Your task. Do what it says.
+
+**Diff**: What's changed on this branch. Your primary working material.
+
+**Clipboard**: User-provided input. If present, it's why you're here.
+
+---
+
+## Run Modes
+
+Check the run mode at the top of the prompt.
+
+**If auto mode**: Run to completion. Don't pause for questions. Make best-effort assumptions. Write open questions to `scratch/questions.md` and keep moving.
+
+**If interactive mode**: Ask clarifying questions when needed. The user will guide you.
+
+---
+
+## Where to Write
+
+**scratch/**: PR-scoped artifacts. Design docs, notes, questions. Cleared on merge.
+- `scratch/<branch>.md` — design doc for current work
+- `scratch/questions.md` — open questions, unknowns, blockers
+
+**Code**: The actual work. Tests, implementation, fixes.
+
+Don't modify `roadmap/` unless the step explicitly says to. It persists across PRs.
+
+---
+
+## Commits
+
+In auto mode, commit when a step completes. Small, atomic commits. Don't leave the branch broken.
+
+In interactive mode, commit at natural breakpoints when the user signals readiness.
+
+---
+
+## Chaining
+
+Steps produce artifacts that later steps consume:
+
+| Step | Reads | Writes |
+|------|-------|--------|
+| design | — | scratch/<branch>.md |
+| implement | scratch/<branch>.md | code, tests |
+| review | code on branch | verdict in scratch/ |
+
+If a required artifact is missing, check scratch/ first. If still missing, note it in `scratch/questions.md` and proceed with what you have.
+
+---
+
+## Quality
+
+Ship working code. Tests pass. No regressions.
+
+When unsure between two approaches, pick the simpler one. You can always iterate.

loopflow-0.7.2/src/loopflow/__init__.py

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

{loopflow-0.7.0 → loopflow-0.7.2}/src/loopflow/lf/branch_names.py

@@ -6,6 +6,8 @@ import subprocess
 from datetime import datetime
 from typing import TYPE_CHECKING
 
+from loopflow.lf.naming import generate_word_pair
+
 if TYPE_CHECKING:
     from loopflow.lf.config import BranchNameConfig
 
@@ -36,7 +38,15 @@ def _sanitize_for_branch(s: str) -> str:
 
 
 def format_branch_name(short_name: str, config: "BranchNameConfig | None") -> str:
-    """Transform short name into full branch name using schema."""
+    """Transform short name into full branch name using schema.
+
+    Available placeholders:
+        {name}  - the short name provided
+        {user}  - git username
+        {ts}    - timestamp (YYYYMMDD_HHMM)
+        {date}  - date (YYYYMMDD)
+        {words} - magical-musical word pair (e.g., wisp-forte)
+    """
     if config is None:
         return short_name
 
@@ -51,6 +61,7 @@ def format_branch_name(short_name: str, config: "BranchNameConfig | None") -> st
         "user": _get_git_username(),
         "ts": now.strftime("%Y%m%d_%H%M"),
         "date": now.strftime("%Y%m%d"),
+        "words": generate_word_pair(),
     }
 
     result = schema

loopflow-0.7.2/src/loopflow/lf/builtins/directions/roles/infra-engineer.md

@@ -0,0 +1,24 @@
+Build systems that don't break.
+
+## Core responsibilities
+
+**Security.** Defense in depth. Validate inputs, sanitize outputs, minimize attack surface. Assume breach. Least privilege. Audit sensitive operations.
+
+**Performance.** Speed matters. Measure before optimizing. Profile hot paths. Watch memory, latency, throughput. Indexing, batching, caching, connection pooling.
+
+**Reliability.** Systems work correctly, always. Handle failures gracefully. Retry with backoff. Circuit breakers. Graceful degradation. Timeouts, health checks, monitoring.
+
+## What matters
+
+**Slow is smooth. Smooth is fast.** Rushing creates incidents. Measure twice, cut once.
+
+**Correctness over speed.** A fast system that's wrong is worthless. A correct system can be optimized.
+
+**Observability is not optional.** If you can't see it, you can't fix it. Logging, metrics, tracing are load-bearing.
+
+## Quality bar
+
+- Handles 10x current load without architectural changes
+- Fails gracefully—partial degradation, not total collapse
+- Recoverable in minutes, not hours
+- Every state change is observable and reversible

loopflow-0.7.2/src/loopflow/lf/builtins/directions/values/craft.md

@@ -0,0 +1,3 @@
+Quality and attention to detail. Code should be clear, tested, documented.
+Take time to get it right. Refactor when needed. No shortcuts.
+Consider: edge cases, error messages, naming, consistency.

loopflow-0.7.2/src/loopflow/lf/builtins/directions/values/flow.md

@@ -0,0 +1,3 @@
+Maintain momentum. Ship small, iterate fast, unblock quickly.
+Prefer simple solutions that work now over perfect solutions later.
+Consider: what's the smallest useful change? What's blocking progress?

loopflow-0.7.2/src/loopflow/lf/builtins/directions/values/scale.md

@@ -0,0 +1,3 @@
+Build for growth. Prefer horizontal scaling, stateless design, async patterns.
+Avoid premature optimization but design for 10x current load.
+Consider: caching, sharding, queues, idempotency.

loopflow-0.7.2/src/loopflow/lf/builtins/flows/README.md

@@ -0,0 +1,50 @@
+# Built-in Flows
+
+Flows shipped with loopflow. Organized by purpose.
+
+## Code flows (`code/`)
+
+Flows that produce code changes.
+
+| Flow | Steps | Use case |
+|------|-------|----------|
+| `ship` | implement → compress → gate | Build from design, ship clean |
+| `pair` | design → ship | Interactive design then build |
+| `grind` | review → iterate → ship → gate | Review-driven iteration |
+| `incident` | debug → 5whys → ship | Fix bug, analyze root cause, ship fixes |
+| `start` | ingest → kickoff | Pick roadmap item, elaborate design |
+| `ship-roadmap` | start → ship | Pick roadmap item, elaborate, build |
+
+## Plan flows (`plan/`)
+
+Flows that produce roadmap items and analysis.
+
+| Flow | Steps | Use case |
+|------|-------|----------|
+| `roadmap-reduce` | review → fork(reduce×3) → publish | Find simplification opportunities |
+| `roadmap-polish` | review → fork(polish×3) → publish | Find polish priorities |
+| `roadmap-expand` | review → fork(expand×3) → publish | Find expansion opportunities |
+| `research` | explore → review → publish | Investigate then propose |
+| `publish` | consolidate → add-to-roadmap | Promote scratch/ to roadmap/ |
+
+## Fork pattern
+
+Plan flows use forks to get multiple perspectives:
+
+```yaml
+- review
+- fork:
+    step: reduce
+    drafts:
+      - direction: infra-engineer
+      - direction: designer
+      - direction: product-engineer
+- publish
+```
+
+The fork runs `reduce` three times with different directions, synthesizes results using the wave's direction, then publishes to roadmap.
+
+## Adding a flow
+
+1. Create `{category}/{name}.yaml` with step list
+2. Update this README

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/design-and-ship.yaml

@@ -0,0 +1,4 @@
+- design
+- implement
+- reduce
+- polish

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/grind.yaml

@@ -0,0 +1,4 @@
+- review
+- iterate
+- ship
+- gate

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/incident.yaml

@@ -0,0 +1,3 @@
+- debug
+- 5whys
+- ship

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/pair.yaml

@@ -0,0 +1,2 @@
+- design
+- ship

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/ship-roadmap.yaml

@@ -0,0 +1,2 @@
+- start
+- ship

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/ship.yaml

@@ -0,0 +1,4 @@
+- implement
+- compress
+- gate
+- consolidate

loopflow-0.7.2/src/loopflow/lf/builtins/flows/code/start.yaml

@@ -0,0 +1,2 @@
+- ingest
+- kickoff

loopflow-0.7.2/src/loopflow/lf/builtins/flows/plan/publish.yaml

@@ -0,0 +1,2 @@
+- consolidate
+- add-to-roadmap

loopflow-0.7.2/src/loopflow/lf/builtins/flows/plan/research.yaml

@@ -0,0 +1,3 @@
+- explore
+- review
+- publish

loopflow-0.7.2/src/loopflow/lf/builtins/flows/plan/roadmap-expand.yaml

@@ -0,0 +1,8 @@
+- review
+- fork:
+    step: expand
+    drafts:
+      - direction: infra-engineer
+      - direction: designer
+      - direction: product-engineer
+- publish

loopflow-0.7.2/src/loopflow/lf/builtins/flows/plan/roadmap-polish.yaml

@@ -0,0 +1,8 @@
+- review
+- fork:
+    step: polish
+    drafts:
+      - direction: infra-engineer
+      - direction: designer
+      - direction: product-engineer
+- publish