loopflow 0.5.0__tar.gz

loopflow-0.5.0/.claude/commands/compare.md

@@ -0,0 +1,75 @@
+Compare two implementations and recommend which to use.
+
+This task is typically invoked via `lf ops compare <branch-a> <branch-b>`, which injects the diffs below.
+
+## Implementation A: {{name_a}}
+
+<diff>
+{{diff_a}}
+</diff>
+
+## Implementation B: {{name_b}}
+
+<diff>
+{{diff_b}}
+</diff>
+
+## Workflow
+
+1. Read both diffs to understand what each implementation does
+2. Identify the key differences in approach
+3. Evaluate against loopflow's design principles (below)
+4. Write your analysis to `{{output_dir}}/comparison.md`
+
+## What to cover
+
+**Approach.** How does each solve the problem? What are the architectural differences? One-paragraph summary for each.
+
+**Trade-offs.** What does each gain and lose? Consider:
+- Code complexity (less code is usually better)
+- Match with existing patterns in the codebase
+- Error handling and edge cases
+- Testability
+
+**Recommendation.** Which implementation should be used? Be specific. If parts of each are better, note what to cherry-pick.
+
+## Evaluation criteria for loopflow
+
+When comparing, prefer implementations that:
+
+- **Use fewer lines of code.** The best code is code that doesn't exist.
+- **Match existing patterns.** If the codebase uses `@dataclass`, use `@dataclass`. If it uses functions, use functions.
+- **Avoid new abstractions.** Don't prefer the implementation that adds a base class or registry.
+- **Work in auto mode.** Implementations that require interactive confirmation are worse.
+- **Delegate to CLIs.** Implementations that shell out to claude/codex are better than ones that reimplement.
+
+## Output format
+
+Write to `{{output_dir}}/comparison.md`:
+
+```markdown
+# {{name_a}} vs {{name_b}}
+
+## Summary
+
+<Which to use and why, in 2-3 sentences>
+
+## Approach comparison
+
+<One paragraph per implementation>
+
+## Recommendation
+
+<Specific recommendation with rationale>
+
+## Cherry-pick opportunities
+
+<If applicable: what to take from the non-recommended implementation>
+```
+
+Keep it under 500 words. This is a decision document, not an exhaustive review.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/debug.md

@@ -0,0 +1,44 @@
+Debug an error using the stacktrace or error message from clipboard.
+
+Run with `-v` to include clipboard content:
+```bash
+lf debug -v
+```
+
+## Workflow
+
+1. Parse the error/stacktrace from the clipboard content
+2. Identify the file and line number where the error originated
+3. Run `git diff main...HEAD -- <file>` to see if this file was changed on this branch
+4. Read the relevant files to understand context
+5. Fix the bug
+6. Run `uv run pytest tests/` to verify the fix doesn't break anything
+
+## Debugging strategy
+
+**Follow the stack trace.** The deepest frame in your code (not library code) is usually where the problem originates. Start there.
+
+**Check recent changes.** If the error is new, run `git diff` to see what changed. The bug is likely in the delta.
+
+**Reproduce first.** Before fixing, understand how to trigger the error. A fix you can't verify isn't a fix.
+
+## Common patterns in this codebase
+
+**Import errors.** Imports are at top of file. Check if a new import was added but not the dependency.
+
+**Path errors.** Loopflow uses `Path` objects. Check if something expects a string or vice versa.
+
+**Subprocess failures.** Many operations shell out to git, claude, codex. Check if the subprocess command is correct and the tool is available.
+
+**Config errors.** `.lf/config.yaml` parsing uses Pydantic. Check if required fields are missing or types are wrong.
+
+## Output
+
+Fix the bug directly. If the cause isn't obvious from the fix, add a brief inline comment.
+
+If you can't determine the cause, describe what you learned and what additional context is needed.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/design.md

@@ -0,0 +1,63 @@
+Produce a short implementation spec that another LLM session can use to write a first draft.
+
+The design doc is scaffolding—a checkpoint for recovery, not documentation for posterity. If a session crashes, the spec lets a fresh session pick up where things left off. `lf ops pr land` deletes `.design/` contents.
+
+## Workflow
+
+1. Run `git branch --show-current` to confirm you're on a feature branch (not `main`)
+2. Create `.design/<feature-name>.md` early—after the first exchange or two
+3. Write as you go, refining with each conversation turn
+4. Run `git add .design/ && git commit -m "design: <branch>"` when done
+5. End session. Implementation happens via `lf implement`.
+
+Write as you go, not at the end. If the session crashes mid-design, the partial doc is still useful. Let writing inspire questions—gaps become obvious when you make things concrete.
+
+## What makes a good design doc
+
+**Heavy on code.** Sketch data structures, function signatures, example API calls. The code is for communication, not execution:
+
+```python
+@dataclass
+class Worktree:
+    path: Path
+    branch: str
+
+def create_worktree(name: str) -> Worktree:
+    """Create sibling worktree at ../{repo}.{name}"""
+    ...
+```
+
+**Quote the user verbatim.** When they say something that captures intent, constraint, or priority—copy it into the doc. Quotes anchor what matters and prevent drift.
+
+**Specify "done when."** A command to run, output to expect. The implementing session needs to know when to stop.
+
+## Required sections (~1000 words max)
+
+- **What to build** — One sentence. What exists after this that doesn't exist now.
+- **Data structures** — Core types, sketched in code.
+- **Key functions** — Signatures with one-line intent.
+- **Constraints** — What would require rewriting if guessed wrong.
+- **Done when** — Verification command and expected output.
+
+## Loopflow design principles
+
+When designing for this codebase:
+
+- **Worktrees are first-class.** Features should work across isolated worktrees. Don't assume a single working directory.
+- **Prompts are files, not config.** Task definitions live in `.claude/commands/` or `.lf/`. Don't design template systems or prompt builders.
+- **Design for auto mode.** Most tasks run headless. Don't require interactive confirmation for core flows.
+- **Wrap, don't reimplement.** Loopflow delegates to Claude Code and Codex CLIs. Design to pass through, not duplicate.
+- **Simple data structures.** Prefer `@dataclass` over inheritance hierarchies. Prefer functions over classes when state isn't needed.
+
+## Conversation guidance
+
+Bias toward brevity. Ask only what's needed to start coding.
+
+If scope is unclear, ask "what's the smallest version that's useful?" and spec that.
+
+Completeness is not required. Wrong guesses get fixed in implementation. The goal is to not block the implementing session, not to predict everything.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/draft_commit.md

@@ -0,0 +1,61 @@
+Draft a commit message for landing this branch.
+
+## Workflow
+
+```bash
+# 1. See commit history on this branch
+git log main..HEAD --oneline
+
+# 2. See all changes
+git diff main...HEAD --stat
+git diff main...HEAD
+```
+
+Read the changes and write a commit message to `.lf/COMMIT`.
+
+## Commit message format
+
+```
+<area>: <summary>
+
+<body explaining what and why>
+```
+
+**Title:** Lowercase, under 50 chars. Optional area prefix for focused changes.
+
+**Body:** One paragraph explaining what this branch accomplished and why. Skip if the title is self-explanatory.
+
+## Style examples
+
+```
+maestro: add session tracking daemon
+
+Sessions now write to SQLite and can be viewed via lf ops status.
+The maestro daemon provides a web UI for tailing logs across worktrees.
+```
+
+```
+fix worktree cleanup on branch delete
+```
+
+```
+prompts: improve expand and iterate focus
+
+Both prompts now direct agents to focus on code touched by the current
+branch rather than generic improvements across the codebase.
+```
+
+## What NOT to do
+
+- Don't list individual commits. Summarize the branch's overall change.
+- Don't add "Generated with Claude" or co-author footers.
+- Don't use imperative mood in the body ("Add X" → "X now works").
+
+## Output
+
+Write the commit message to `.lf/COMMIT`. Tell the user to review it and run `lf ops land` when ready.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/expand.md

@@ -0,0 +1,43 @@
+Explore ambitious changes that extend what this branch is already doing.
+
+This is for bigger swings—but grounded in the current work. Look at what this branch changes, then ask: what's the natural next step that would multiply the value?
+
+## Workflow
+
+1. Run `git diff main...HEAD` to see what this branch has changed
+2. Read the modified files to understand the current direction
+3. Identify one expansion that extends this work meaningfully
+4. Write a design doc to `.design/<expansion-name>.md`
+5. If the expansion is tractable, start building it
+
+## What makes a good expansion
+
+**Extends the branch's intent.** If this branch adds worktree support, expand might add parallel worktree execution. If it improves commit messages, expand might add PR description generation. The expansion should feel like "part 2" of what's already here.
+
+**Multiplicative value.** Changes that make everything else better, not just add one more thing. A new abstraction that simplifies three existing features beats a fourth feature.
+
+**Tractable scope.** Ambitious but achievable in one session. If it needs a design doc longer than 500 words, it's too big for expand.
+
+## Loopflow's architectural beliefs
+
+When expanding, stay aligned with these principles:
+
+- **Worktrees over branches.** Agents run in isolated worktrees so you can work in parallel. Expansions should assume multi-worktree workflows.
+- **Prompts are files.** Tasks live in `.claude/commands/` or `.lf/`. Don't add config-driven prompt generation or template engines.
+- **Auto mode is default.** Most tasks run headless with `--print`. Interactive is the exception. Design for unattended execution.
+- **CLI passthrough.** Loopflow wraps Claude Code and Codex CLIs. Don't reimplement their features—pass args through.
+- **Design docs are scaffolding.** `.design/` is for session recovery, not permanent documentation. `lf ops pr land` deletes it.
+- **Simple data, simple APIs.** Prefer dataclasses over complex hierarchies. Prefer functions over classes when state isn't needed.
+
+## What to avoid
+
+**Unrelated improvements.** The expansion must connect to what this branch is doing. Generic "wouldn't it be nice" ideas belong in a separate branch.
+
+**Abstraction layers.** If you're tempted to add a plugin system, registry pattern, or config-driven dispatch, that's a sign to stop and reconsider.
+
+**Trend-chasing.** The project should be better at being itself, not more like whatever's popular this month.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/implement.md

@@ -0,0 +1,47 @@
+Turn the design doc into working code.
+
+The design doc is under `.design/` and auto-included in this prompt. It contains data structures, function signatures, constraints, and a "done when" verification step.
+
+## Workflow
+
+1. Read the design doc in `.design/` to understand what to build
+2. Read STYLE.md to understand code conventions
+3. Implement data structures first—get the core types right
+4. Implement functions one at a time, following the signatures in the design
+5. Run `uv run pytest tests/` to verify nothing broke
+6. Run the "done when" check from the design doc
+7. Do not commit—leave that to the caller or pipeline
+
+## Implementation rules
+
+**Match existing patterns.** Before writing new code, find similar code nearby and match its style. If the codebase uses `@dataclass`, use `@dataclass`. If it uses type hints, use type hints.
+
+**Stay in scope.** Implement exactly what the design doc describes. If something should be added, note it in `.design/questions.md` but don't build it.
+
+**Tests prove it works.** Add tests for user-visible behavior. Don't test implementation details. Don't write tests that just verify mock calls—assert on actual results.
+
+**Skip obvious docstrings.** If the function name and types tell the whole story, don't repeat it in prose. No `Args:`/`Returns:` blocks.
+
+**Leave the design doc.** Don't delete `.design/*.md`. The review step and landing process handle cleanup.
+
+## Loopflow code conventions
+
+These are specific to this codebase:
+
+- **Use `uv run`** for all Python commands, or activate `.venv` first
+- **Imports at top of file**, never inline
+- **Prefix private functions with `_`**
+- **Return `None` for "not found"**, raise exceptions for "shouldn't happen"
+- **Prefer functions over classes** when you don't need state
+- **No backwards-compatibility shims** unless explicitly required
+
+## If something's wrong
+
+If the design doc is unclear, make the simplest choice and move on. Note your assumption in `.design/questions.md`. The code can be rewritten if needed.
+
+If implementation reveals a design flaw, note it but keep going. The design was scaffolding—reality should diverge when it makes sense.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/iterate.md

@@ -0,0 +1,43 @@
+Make meaningful improvements to code touched by this branch.
+
+Focus on the areas this branch has already modified. The goal is incremental quality improvements that compound—not generic refactoring across the whole codebase.
+
+## Workflow
+
+1. Run `git diff main...HEAD --stat` to see which files this branch modified
+2. Read those files and identify the highest-impact improvement
+3. Make one focused change—don't scatter effort across multiple areas
+4. Run `uv run pytest tests/` to verify nothing broke
+5. If tests pass, you're done. If not, fix what you broke.
+
+## Priority order (within the branch's scope)
+
+**1. User experience problems.** Error messages that don't help. Workflows that require too many steps. Missing feedback. Fix the worst friction first.
+
+**2. Bugs and edge cases.** Logic errors, off-by-ones, unhandled errors in the modified code.
+
+**3. Simplification.** Code that could be deleted. Abstractions that don't earn their keep. Duplication within the changed files.
+
+**4. Test coverage.** Missing tests for the new behavior. Tests that verify mock calls instead of results.
+
+## Loopflow's quality bar
+
+These aren't generic best practices—they're specific to how this codebase works:
+
+- **No Args:/Returns: docstrings.** If types are clear, skip the docstring entirely.
+- **Assert on results, not mock calls.** Mocks prevent side effects; tests verify behavior.
+- **One implementation.** No `_v2`, `_old`, `_new` suffixes. Delete the old version.
+- **Errors for users, exceptions for programmers.** Return None for "not found"; raise for "shouldn't happen."
+
+## What to avoid
+
+**Scope creep.** Only improve code this branch touched. "While I'm here" improvements belong in a separate branch.
+
+**Refactoring for style.** Don't rewrite working code because you'd write it differently. Only fix actual problems.
+
+**Adding features.** This is about quality, not scope. New capabilities need their own design.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/polish.md

@@ -0,0 +1,68 @@
+Fix issues and run tests before landing.
+
+The deliverable is working, clean code that passes tests.
+
+## Workflow
+
+1. **Review and fix**
+   - Run `git diff main...HEAD` to see what changed
+   - Review against STYLE.md and general code quality
+   - Fix bugs, style violations, and unnecessary complexity directly
+   - Don't just note issues—fix them
+   - Rewrite the primary design doc in `.design/` to match the implementation (keep any decisions log)
+
+2. **Test**
+   - Run the full test suite: `./dev test` (runs both Python and Swift tests)
+   - If tests fail, determine: broken test or broken code?
+   - Fix failures one by one, running single tests while debugging
+   - Add missing tests for key behavior changes
+   - Reduce or simplify existing tests according to new behavioral requirements.
+
+   For component-specific testing:
+   - Python only: `./dev py`
+   - Swift only: `./dev swift`
+
+## What to fix
+
+Focus only on code changed by this branch.
+
+**Test failures.** Get the suite green first. Run single tests while debugging:
+```bash
+uv run pytest tests/test_specific.py::test_name -v
+```
+
+**Style violations specific to this codebase:**
+- Remove `Args:`/`Returns:` docstrings when types are clear
+- Move inline imports to top of file
+- Add `_` prefix to private functions
+- Replace tests that assert on mock calls with tests that assert on results
+
+**Bugs.** Logic errors, edge cases, off-by-ones in the new code.
+
+**Missing tests.** Add tests for user-visible behavior that isn't covered. Keep them short and focused.
+
+## What to ignore
+
+**Unrelated code.** Don't fix things outside this branch's scope. "While I'm here" improvements belong in a separate branch.
+
+**Working code you'd write differently.** Only fix actual problems, not style preferences.
+
+**Design doc deviations.** The implementation is the source of truth. Deviations are intentional.
+
+## Test standards
+
+These are specific to this codebase:
+
+- **Test behavior, not implementation.** Assert on what the function returns, not how it works internally.
+- **Mocks prevent side effects.** Use them for network, subprocess, file I/O. But don't assert on mock calls—assert on the result.
+- **Delete flaky tests.** Don't add retries or sleeps. If a test is flaky, it's testing the wrong thing.
+- **One behavior per test.** Short, focused tests that prove one thing works.
+
+## Output
+
+Fix issues directly. Run tests until they pass. If nothing needs fixing and tests pass, say so.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/publish.md

@@ -0,0 +1,91 @@
+Publish the loopflow package to PyPI.
+
+```bash
+lf publish           # auto-detect version bump from changes
+lf publish minor     # force minor version bump
+lf publish major     # force major version bump
+```
+
+## Workflow
+
+Execute these steps in order. Stop if any step fails.
+
+### 1. Run tests
+```bash
+uv run pytest tests/
+```
+If tests fail, stop and report which tests failed. Do not publish broken code.
+
+### 2. Determine version bump
+
+Read current version from `src/loopflow/__init__.py`. Then:
+
+- If `minor` or `major` was passed as argument, use that
+- Otherwise, analyze `git diff main...HEAD`:
+  - **Major**: Breaking changes to CLI flags, removed commands, incompatible config changes
+  - **Minor**: New commands, new flags, non-breaking additions (default)
+
+Calculate new version (X.Y.Z):
+- Minor: increment Y, reset Z to 0
+- Major: increment X, reset Y and Z to 0
+
+### 3. Update version
+Edit `src/loopflow/__init__.py`:
+```python
+__version__ = "X.Y.Z"
+```
+
+### 4. Generate release notes
+Write `RELEASE_NOTES.md` (overwrite if exists):
+```markdown
+# vX.Y.Z
+
+<2-3 sentence summary>
+
+## Changes
+
+- <notable change 1>
+- <notable change 2>
+
+## Breaking changes
+
+<if major bump, list what breaks>
+```
+
+### 5. Build and publish
+```bash
+uv build
+uv publish
+```
+Requires `UV_PUBLISH_TOKEN` env var or `~/.pypirc` credentials.
+
+### 6. Install locally
+```bash
+uv tool install --force loopflow
+```
+
+### 7. Commit and tag
+```bash
+git add src/loopflow/__init__.py RELEASE_NOTES.md
+git commit -m "release: vX.Y.Z"
+git tag vX.Y.Z
+git push && git push --tags
+```
+
+## If something fails
+
+- **Test failures:** Stop immediately. Report which tests failed.
+- **Build failures:** Check `pyproject.toml`. Common issue: missing file in `[tool.hatch.build]`.
+- **Publish failures:** Check `UV_PUBLISH_TOKEN`. May need to generate new token at pypi.org.
+- **Don't leave partial state.** If publish fails, revert the version bump before stopping.
+
+## Output
+
+Report each step as it completes. End with:
+- New version number
+- PyPI URL: https://pypi.org/project/loopflow/
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/rebase.md

@@ -0,0 +1,58 @@
+Rebase this branch onto main.
+
+## Workflow
+
+### 1. Understand the branch's intent
+```bash
+git log main..HEAD --oneline
+git diff main...HEAD --stat
+```
+Note which files this branch modified and what it's trying to accomplish.
+
+### 2. Fetch and rebase
+```bash
+git fetch origin main
+git rebase origin/main
+```
+
+### 3. Handle conflicts
+
+If conflicts occur:
+
+```bash
+# See which files have conflicts
+git status
+
+# After resolving each file
+git add <file>
+git rebase --continue
+```
+
+**Conflict resolution strategy:**
+
+- **Files central to the branch's intent:** Preserve the branch's changes. These are the files listed in `git diff main...HEAD --stat`.
+- **Files outside the branch's scope:** Accept main's version. The branch probably touched these incidentally.
+- **Both versions are valid:** Combine manually if both changes make sense. Otherwise, prefer the branch's version for modified files, main's version for everything else.
+
+### 4. Verify and push
+```bash
+# Verify nothing broke
+uv run pytest tests/
+
+# Push the rebased branch
+git push --force-with-lease
+```
+
+## If rebase goes wrong
+
+```bash
+# Abort and return to pre-rebase state
+git rebase --abort
+```
+
+Then note what went wrong in `.design/questions.md` and stop.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.
+

loopflow-0.5.0/.claude/commands/reduce.md

@@ -0,0 +1,43 @@
+Simplify code touched by this branch while preserving user behavior.
+
+Focus on trimming complexity within files this branch has already modified. Don't refactor unrelated code.
+
+## Workflow
+
+1. Run `git diff main...HEAD --stat` to see which files this branch modified
+2. Read those files and identify what can be deleted or simplified
+3. Make one focused simplification
+4. Run `uv run pytest tests/` to verify behavior is preserved
+5. If tests pass, you're done
+
+## Priority order
+
+1. **Delete dead code.** Unused functions, unreachable branches, obsolete options. If it's not called, delete it.
+2. **Collapse duplication.** Repeated patterns within the changed files. Don't create new abstractions—inline the common code or pick one location.
+3. **Simplify logic.** Replace nested conditionals with early returns. Replace clever code with obvious code.
+4. **Tighten APIs.** Remove optional parameters that are never used. Remove public functions that should be private.
+
+## Guardrails
+
+**Preserve user behavior.** CLI flags, outputs, and workflows must stay the same. If behavior must change to simplify, document the tradeoff in `.design/questions.md`.
+
+**Prefer deletion over rewriting.** The best refactor is code that doesn't exist anymore.
+
+**Stay in scope.** Only simplify code this branch touched. "While I'm here" refactoring belongs in a separate branch.
+
+**No new abstractions.** If you're tempted to extract a helper, base class, or utility—don't. Reduce means less code, not different code.
+
+## Loopflow's simplicity principles
+
+- **One implementation.** No `_v2`, `_old`, `_new`. Delete the old version.
+- **No backwards compatibility.** If something's unused, delete it completely. No `_deprecated` stubs.
+- **Functions over classes.** If you can delete a class and use a function, do it.
+- **Inline over abstract.** Three similar lines of code is better than a premature abstraction.
+
+## Output
+
+Make the simplification directly. Run tests to verify. Note any assumptions in `.design/questions.md`.
+
+## Auto mode
+
+In auto/headless runs, do not pause to ask questions. Make the best assumption you can and append any open questions to `.design/questions.md`.