hyperloop 0.1.0__tar.gz

hyperloop-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest --tb=short -q
+
+  gate:
+    # Single status check for branch protection rules
+    needs: [test]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: All checks passed
+        run: |
+          if [ "${{ needs.test.result }}" != "success" ]; then
+            echo "Tests failed"
+            exit 1
+          fi

hyperloop-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,106 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: github.repository == 'jsell-rh/hyperloop'
+
+    permissions:
+      contents: write
+      id-token: write
+
+    outputs:
+      released: ${{ steps.semrel.outputs.released }}
+      version: ${{ steps.semrel.outputs.version }}
+      tag: ${{ steps.semrel.outputs.tag }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Python Semantic Release
+        id: semrel
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          root_options: "-vv"
+
+  build:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout released tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: [release, build]
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hyperloop/${{ needs.release.outputs.version }}/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-github-release:
+    needs: [release, build]
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload to GitHub Release
+        uses: python-semantic-release/publish-action@v10
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ needs.release.outputs.tag }}

hyperloop-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.pyright/
+*.egg-info/
+dist/
+build/
+.venv/

hyperloop-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

hyperloop-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

hyperloop-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.0 (2026-04-15)
+
+- Initial Release

hyperloop-0.1.0/CLAUDE.md

@@ -0,0 +1,102 @@
+# hyperloop
+
+An orchestrator that walks tasks through composable process pipelines using AI agents.
+
+## Quick Start
+
+```bash
+uv sync
+uv run pytest                    # run tests
+uv run ruff check .              # lint
+uv run ruff format --check .     # format check
+```
+
+## Architecture
+
+Hexagonal (ports & adapters). Domain logic has zero I/O dependencies.
+
+```
+src/hyperloop/
+├── domain/           ← pure logic, no I/O, no framework imports
+│   ├── model.py      ← Task, WorkerResult, Process, Pipeline (value objects/entities)
+│   ├── decide.py     ← decide(world) → Action[] (pure function)
+│   └── pipeline.py   ← pipeline executor (recursive, handles loops)
+├── ports/            ← interfaces only (Protocol classes)
+│   ├── state.py      ← StateStore protocol
+│   └── runtime.py    ← Runtime protocol
+├── adapters/         ← implementations of ports
+│   ├── git_state.py  ← GitStateStore
+│   ├── local.py      ← LocalRuntime (worktrees + CLI)
+│   └── ambient.py    ← AmbientRuntime (ambient platform API)
+└── loop.py           ← main loop, wires ports to domain
+```
+
+The dependency rule: domain/ imports nothing from ports/ or adapters/. Ports/ imports from domain/ (for types). Adapters/ imports from ports/ and domain/. Loop imports everything.
+
+## Development Practices
+
+### TDD — strict, no exceptions
+
+Write the failing test first, then implement. Red → green → refactor. Every behavior starts as a test. If you can't write a test for it, reconsider the design.
+
+### No mocks — use fakes
+
+Do NOT use `unittest.mock`, `MagicMock`, `patch`, or any mocking library. Instead:
+
+- **Fakes**: complete in-memory implementations of port interfaces. They implement the full contract, not just the methods one test needs. Fakes are first-class code — tested, reusable, and shipped alongside the port they implement.
+- **Real objects**: use the actual domain objects. The domain is pure — no I/O, no reason to replace it.
+- **Layered testing**: small tests exercise domain logic with fakes. Integration tests exercise adapters against real systems. Overlap between layers is a feature, not redundancy.
+
+Why: mocks couple tests to implementation details. A mock-heavy test says "this function calls that function with these args" — it tests the wiring, not the behavior. When you refactor, mock tests break even if behavior is preserved. Fakes test the contract.
+
+Reference: https://www.alechenninger.com/2020/11/the-secret-world-of-testing-without.html
+
+### Fakes live next to their ports
+
+```
+ports/
+├── state.py          ← StateStore protocol
+└── runtime.py        ← Runtime protocol
+tests/
+├── fakes/
+│   ├── state.py      ← InMemoryStateStore (full implementation, tested)
+│   └── runtime.py    ← InMemoryRuntime (full implementation, tested)
+├── test_decide.py
+├── test_pipeline.py
+└── test_loop.py
+```
+
+Every fake must pass the same contract tests as its real adapter. If `InMemoryStateStore` diverges from `GitStateStore` behavior, the contract tests catch it.
+
+### Type hints — full coverage, no Any
+
+Every function signature, every variable where the type isn't obvious. Use `Protocol` for interfaces. Use dataclasses or named tuples for value objects. `Any` is banned — if you reach for it, the model is wrong.
+
+### DDD — domain drives the design
+
+The domain model (`domain/`) is the heart. It contains:
+- **Value objects**: `TaskStatus`, `Phase`, `Verdict`, `WorkerResult`
+- **Entities**: `Task`, `Process`
+- **Pure functions**: `decide()`, `run_pipeline()`
+
+These have no dependencies on frameworks, I/O, or infrastructure. They are tested directly, without fakes, because they are pure.
+
+Ports define what the domain needs from the outside world. Adapters fulfill those needs. The domain never knows which adapter is in use.
+
+## Tooling
+
+- **Package manager**: `uv` (not pip, not poetry)
+- **Linting + formatting**: `ruff` (configured in pyproject.toml)
+- **Testing**: `pytest`
+- **Pre-commit**: installed and configured for ruff lint, ruff format, and pytest
+- **Type checking**: `pyright` (strict mode)
+
+## Commit Conventions
+
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`, `docs:`
+- One logical change per commit
+- Atomic commits — each commit should pass all tests
+
+## Spec
+
+The product spec lives at `specs/spec.md`. It is the source of truth for behavior. If code and spec disagree, align the code to the spec.

hyperloop-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: hyperloop
+Version: 0.1.0
+Summary: Orchestrator that walks tasks through composable process pipelines using AI agents
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.24.1
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hyperloop
+
+Walks tasks through composable process pipelines using AI agents. You write specs, it creates tasks, implements them, verifies the work, and merges PRs.
+
+## Prerequisites
+
+- Python 3.12+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- `gh` CLI (authenticated, for PR management)
+- `git`
+
+## Install
+
+From PyPI (once published):
+
+```bash
+pip install hyperloop
+```
+
+From source (for development or testing):
+
+```bash
+git clone git@github.com:jsell-rh/hyperloop.git
+cd hyperloop
+uv sync --all-extras
+```
+
+## Quickstart
+
+1. Create a repo with a spec:
+
+```bash
+mkdir -p my-project/specs
+cd my-project
+git init && git commit --allow-empty -m "init"
+```
+
+2. Write a spec. This is what you want built. Be specific about acceptance criteria:
+
+```markdown
+<!-- specs/auth.md -->
+# User Authentication
+
+Implement JWT-based authentication for the API.
+
+## Acceptance Criteria
+
+- POST /auth/login accepts email + password, returns JWT
+- POST /auth/register creates a new user account
+- GET /auth/me returns the current user (requires valid JWT)
+- Passwords are hashed with bcrypt, never stored in plaintext
+- JWTs expire after 24 hours
+```
+
+3. Run:
+
+```bash
+# From source:
+uv run hyperloop run --repo owner/repo --branch main
+
+# Or if installed:
+hyperloop run --repo owner/repo --branch main
+```
+
+4. See what it would do without executing:
+
+```bash
+hyperloop run --repo owner/repo --dry-run
+```
+
+The orchestrator reads your specs, has the PM create tasks in `specs/tasks/`, then walks each task through the default pipeline: implement, verify, merge.
+
+## Configuration
+
+Create `.hyperloop.yaml` in your repo root:
+
+```yaml
+target:
+  base_branch: main
+
+runtime:
+  max_workers: 4
+
+merge:
+  auto_merge: true
+  strategy: squash
+```
+
+Then just run from the repo directory:
+
+```bash
+hyperloop run
+```
+
+The repo is inferred from your git remote. All settings have sensible defaults.
+
+## Customizing Agent Behavior
+
+Hyperloop ships with base agent definitions (implementer, verifier, etc.) that work out of the box. To customize them for your project, overlay with patches.
+
+### In-repo overlay
+
+For single-repo projects. Agent patches live in the repo itself:
+
+```yaml
+# .hyperloop.yaml
+overlay: .hyperloop/agents/
+```
+
+```
+your-repo/
+├── .hyperloop.yaml
+├── .hyperloop/
+│   └── agents/
+│       ├── implementer-patch.yaml
+│       └── process-patch.yaml
+└── specs/
+```
+
+An implementer patch injects your project's persona:
+
+```yaml
+# .hyperloop/agents/implementer-patch.yaml
+kind: Agent
+name: implementer
+annotations:
+  ambient.io/persona: |
+    You work on a Go API service.
+    Build: make build. Test: make test. Lint: make lint.
+    Follow Clean Architecture. Use dependency injection.
+```
+
+### Shared overlay via gitops repo
+
+For teams with multiple repos sharing agent definitions. The overlay lives in a central gitops repo and references the hyperloop base as a kustomize remote resource:
+
+```yaml
+# .hyperloop.yaml
+overlay: git@github.com:your-org/agent-gitops//overlays/api
+```
+
+```yaml
+# your-org/agent-gitops/overlays/api/kustomization.yaml
+resources:
+  - github.com/org/hyperloop//base?ref=v1.0.0
+
+patches:
+  - path: implementer-patch.yaml
+    target:
+      kind: Agent
+      name: implementer
+  - path: process-patch.yaml
+    target:
+      kind: Process
+      name: default
+```
+
+This pins the base version and lets you upgrade across all repos by bumping the ref.
+
+## Custom Processes
+
+The default pipeline is: implement, verify, merge. Override it by patching the process:
+
+```yaml
+# process-patch.yaml
+kind: Process
+name: default
+
+pipeline:
+  - loop:
+      - loop:
+          - role: implementer
+          - role: verifier
+      - role: security-reviewer
+  - gate: human-pr-approval
+  - action: merge-pr
+```
+
+Four primitives:
+
+| Primitive | What it does |
+|---|---|
+| `role: X` | Spawn an agent. Fail restarts the enclosing loop. |
+| `gate: X` | Block until external signal (v1: `lgtm` label on PR). |
+| `loop` | Wrap steps. Retry from top on failure. |
+| `action: X` | Terminal operation (`merge-pr`, `mark-pr-ready`). |
+
+Loops nest. Inner loops retry independently of outer loops.
+
+## What it creates in your repo
+
+The orchestrator writes to `specs/` in your repo:
+
+```
+specs/
+├── tasks/       # task files with status, findings, spec references
+├── reviews/     # review artifacts from verifier (on branches)
+└── prompts/     # process improvements (learned over time)
+```
+
+All task state is tracked in git. Every commit includes `Spec-Ref` and `Task-Ref` trailers for traceability. PRs are created as drafts and labeled by spec and task.
+
+## Configuration Reference
+
+```yaml
+# .hyperloop.yaml
+
+overlay: .hyperloop/agents/    # local path or git URL to kustomization dir
+
+target:
+  repo: owner/repo                 # GitHub repo (default: inferred from git remote)
+  base_branch: main                # trunk branch
+  specs_dir: specs                 # where specs live
+
+runtime:
+  default: local                   # local (v1) | ambient (planned)
+  max_workers: 6                   # max parallel task workers
+
+merge:
+  auto_merge: true                 # squash-merge on review pass
+  strategy: squash                 # squash | merge
+  delete_branch: true              # delete worker branch after merge
+
+poll_interval: 30                  # seconds between orchestrator cycles
+max_rounds: 50                     # max retry rounds per task before failure
+max_rebase_attempts: 3             # max rebase retries before full loop retry
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest                    # run tests (280 tests)
+uv run ruff check .              # lint
+uv run ruff format --check .     # format check
+uv run pyright                   # type check
+uv run hyperloop --help          # CLI help
+```