hyperloop 0.4.0__tar.gz → 0.5.0__tar.gz

hyperloop-0.5.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.5.0 (2026-04-15)
+
+### Features
+
+- Make base_ref configurable via config file and HYPERLOOP_BASE_REF env var
+  ([`8efcc0f`](https://github.com/jsell-rh/hyperloop/commit/8efcc0f4292229525e4aa8831561982ad5384220))
+
+- Replace local base/ loading with kustomize-based prompt composition
+  ([`9644afb`](https://github.com/jsell-rh/hyperloop/commit/9644afb89a96eee564f997222d86201312bcb63e))
+
+
+## v0.4.0 (2026-04-15)
+
+
+## v0.3.0 (2026-04-15)
+
+
+## v0.2.0 (2026-04-15)
+
+
+## v0.1.1 (2026-04-15)
+
+
+## v0.1.0 (2026-04-15)
+
+- Initial Release

{hyperloop-0.4.0 → hyperloop-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperloop
-Version: 0.4.0
+Version: 0.5.0
 Summary: Orchestrator that walks tasks through composable process pipelines using AI agents
 Requires-Python: >=3.12
 Requires-Dist: pyyaml>=6.0.3
@@ -21,6 +21,7 @@ Walks tasks through composable process pipelines using AI agents. You write spec
 
 - Python 3.12+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) (`kustomize` on PATH) — resolves agent definitions at startup
 - `git`
 - `gh` CLI (optional, for GitHub PR operations)
 
@@ -222,6 +223,7 @@ All task state is tracked in git. Every commit includes `Spec-Ref` and `Task-Ref
 # .hyperloop.yaml
 
 overlay: .hyperloop/agents/    # local path or git URL to kustomization dir
+base_ref: github.com/jsell-rh/hyperloop//base?ref=v1.0.0  # kustomize remote base (env: HYPERLOOP_BASE_REF)
 
 target:
   repo: owner/repo                 # GitHub repo (default: inferred from git remote)

{hyperloop-0.4.0 → hyperloop-0.5.0}/README.md

@@ -6,6 +6,7 @@ Walks tasks through composable process pipelines using AI agents. You write spec
 
 - Python 3.12+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) (`kustomize` on PATH) — resolves agent definitions at startup
 - `git`
 - `gh` CLI (optional, for GitHub PR operations)
 
@@ -207,6 +208,7 @@ All task state is tracked in git. Every commit includes `Spec-Ref` and `Task-Ref
 # .hyperloop.yaml
 
 overlay: .hyperloop/agents/    # local path or git URL to kustomization dir
+base_ref: github.com/jsell-rh/hyperloop//base?ref=v1.0.0  # kustomize remote base (env: HYPERLOOP_BASE_REF)
 
 target:
   repo: owner/repo                 # GitHub repo (default: inferred from git remote)

{hyperloop-0.4.0 → hyperloop-0.5.0}/base/implementer.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: implementer
+metadata:
+  name: implementer
 prompt: |
   You are a worker agent implementing a task.
 

hyperloop-0.5.0/base/kustomization.yaml

@@ -0,0 +1,7 @@
+resources:
+  - process.yaml
+  - implementer.yaml
+  - verifier.yaml
+  - process-improver.yaml
+  - rebase-resolver.yaml
+  - pm.yaml

{hyperloop-0.4.0 → hyperloop-0.5.0}/base/pm.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: pm
+metadata:
+  name: pm
 prompt: |
   You are a product manager creating tasks from specs.
 

{hyperloop-0.4.0 → hyperloop-0.5.0}/base/process-improver.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: process-improver
+metadata:
+  name: process-improver
 prompt: |
   You improve the development process based on review findings.
 

{hyperloop-0.4.0 → hyperloop-0.5.0}/base/process.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Process
-name: default
+metadata:
+  name: default
 
 intake:
   - role: pm

{hyperloop-0.4.0 → hyperloop-0.5.0}/base/rebase-resolver.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: rebase-resolver
+metadata:
+  name: rebase-resolver
 prompt: |
   You resolve merge conflicts on a worker branch.
 

{hyperloop-0.4.0 → hyperloop-0.5.0}/base/verifier.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: verifier
+metadata:
+  name: verifier
 prompt: |
   You are a code reviewer verifying a task implementation.
 

{hyperloop-0.4.0 → hyperloop-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyperloop"
-version = "0.4.0"
+version = "0.5.0"
 description = "Orchestrator that walks tasks through composable process pipelines using AI agents"
 readme = "README.md"
 requires-python = ">=3.12"

{hyperloop-0.4.0 → hyperloop-0.5.0}/src/hyperloop/cli.py

@@ -54,6 +54,7 @@ def _config_table(cfg: Config) -> Table:
     table.add_row("base_branch", cfg.base_branch)
     table.add_row("specs_dir", cfg.specs_dir)
     table.add_row("overlay", cfg.overlay or "[dim]none[/dim]")
+    table.add_row("base_ref", cfg.base_ref)
     table.add_row("runtime", cfg.runtime)
     table.add_row("max_workers", str(cfg.max_workers))
     table.add_row("auto_merge", str(cfg.auto_merge))
@@ -66,35 +67,26 @@ def _config_table(cfg: Config) -> Table:
     return table
 
 
-def _make_composer(state: object) -> object | None:
-    """Construct a PromptComposer using the base/ directory.
+def _make_composer(cfg: object, state: object) -> object:
+    """Construct a PromptComposer via kustomize build.
 
-    Tries two locations:
-    1. Development: relative to this file (src/hyperloop/../../base)
-    2. Installed package: via importlib.resources
+    Runs ``kustomize build`` on the configured overlay (or the default
+    hyperloop base if no overlay is set).
 
-    Returns None if base/ directory cannot be found.
-    """
-    from hyperloop.compose import PromptComposer
-
-    # Development path: relative to this source file
-    dev_base = Path(__file__).resolve().parent.parent.parent / "base"
-    if dev_base.is_dir():
-        return PromptComposer(base_dir=dev_base, state=state)  # type: ignore[arg-type]
+    Args:
+        cfg: Config object with an ``overlay`` attribute.
+        state: StateStore instance for reading process overlays at spawn time.
 
-    # Installed package: try importlib.resources
-    try:
-        import importlib.resources as pkg_resources
+    Returns:
+        A PromptComposer with resolved templates.
+    """
+    from hyperloop.compose import PromptComposer, check_kustomize_available
 
-        ref = pkg_resources.files("hyperloop").joinpath("../../base")
-        base_path = Path(str(ref))
-        if base_path.is_dir():
-            return PromptComposer(base_dir=base_path, state=state)  # type: ignore[arg-type]
-    except (ImportError, TypeError, FileNotFoundError):
-        pass
+    check_kustomize_available()
 
-    console.print("[dim]Warning: base/ directory not found — prompts will be empty.[/dim]")
-    return None
+    overlay = getattr(cfg, "overlay", None)
+    base_ref = getattr(cfg, "base_ref", "github.com/jsell-rh/hyperloop//base?ref=main")
+    return PromptComposer.from_kustomize(overlay, state, base_ref=base_ref)  # type: ignore[arg-type]
 
 
 @app.command()
@@ -197,8 +189,8 @@ def run(
     runtime = LocalRuntime(repo_path=str(repo_path))
     serial_runner = SubprocessSerialRunner(repo_path=str(repo_path))
 
-    # Resolve base/ directory for agent prompt definitions
-    composer = _make_composer(state)
+    # Resolve agent definitions via kustomize build
+    composer = _make_composer(cfg, state)
 
     def _on_cycle(summary: dict[str, object]) -> None:
         """Print a rich status line after each orchestrator cycle."""

hyperloop-0.5.0/src/hyperloop/compose.py

@@ -0,0 +1,288 @@
+"""Prompt composition — kustomize-resolved templates + runtime context.
+
+Three layers composed at spawn time:
+1. Base + project overlay via kustomize (resolved at startup)
+2. Process overlay from specs/prompts/{role}-overlay.yaml (injected at spawn time)
+3. Task context: spec content, findings, traceability refs (spec_ref, task_id)
+
+The orchestrator runs ``kustomize build`` at startup to resolve layers 1+2 into
+AgentTemplate objects. Layer 3 (process overlay + task context) is injected at
+spawn time because it changes during the loop.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+import yaml
+
+if TYPE_CHECKING:
+    from hyperloop.ports.state import StateStore
+
+logger = logging.getLogger(__name__)
+
+HYPERLOOP_BASE_REF = "github.com/jsell-rh/hyperloop//base?ref=main"
+
+
+@dataclass(frozen=True)
+class AgentTemplate:
+    """A resolved agent definition from kustomize build."""
+
+    name: str
+    prompt: str
+    annotations: dict[str, str]
+
+
+class PromptComposer:
+    """Composes agent prompts from kustomize-resolved templates + runtime context."""
+
+    def __init__(self, templates: dict[str, AgentTemplate], state: StateStore) -> None:
+        """
+        Args:
+            templates: role name -> resolved agent definition (from kustomize build).
+            state: StateStore for reading process overlays and spec files at spawn time.
+        """
+        self._templates = templates
+        self._state = state
+
+    @classmethod
+    def from_kustomize(
+        cls,
+        overlay: str | None,
+        state: StateStore,
+        base_ref: str = HYPERLOOP_BASE_REF,
+    ) -> PromptComposer:
+        """Resolve templates via kustomize build, then construct.
+
+        Args:
+            overlay: Path or git URL to a kustomization directory. If None,
+                     a temporary kustomization referencing the hyperloop base
+                     is created and built.
+            state: StateStore for reading process overlays at spawn time.
+            base_ref: Kustomize remote resource for the base definitions.
+                      Configurable via .hyperloop.yaml or HYPERLOOP_BASE_REF env var.
+
+        Returns:
+            A PromptComposer with resolved templates.
+
+        Raises:
+            RuntimeError: If kustomize build fails.
+        """
+        raw_yaml = _kustomize_build(overlay, base_ref=base_ref)
+        templates = _parse_multi_doc(raw_yaml)
+        return cls(templates, state)
+
+    def compose(
+        self,
+        role: str,
+        task_id: str,
+        spec_ref: str,
+        findings: str,
+    ) -> str:
+        """Compose the full prompt for a worker.
+
+        Layers:
+        1. Resolved template prompt (from kustomize, includes base + project overlay)
+        2. Process overlay from specs/prompts/{role}-overlay.yaml (if exists)
+        3. Task context: spec content, findings, traceability refs
+
+        Args:
+            role: Agent role name (e.g. "implementer", "verifier").
+            task_id: Task identifier (e.g. "task-027").
+            spec_ref: Path to the originating spec file (e.g. "specs/persistence.md").
+            findings: Findings from prior rounds (empty string if none).
+
+        Returns:
+            The composed prompt string ready to pass to a worker.
+
+        Raises:
+            ValueError: If the role has no resolved template.
+        """
+        if role not in self._templates:
+            msg = f"Unknown role '{role}': no agent template resolved for this role"
+            raise ValueError(msg)
+
+        template = self._templates[role]
+        prompt = template.prompt.replace("{spec_ref}", spec_ref).replace("{task_id}", task_id)
+
+        # Layer 2: Process overlay (from target repo specs/prompts/)
+        overlay_path = f"specs/prompts/{role}-overlay.yaml"
+        overlay_content = self._state.read_file(overlay_path)
+        overlay_text = ""
+        if overlay_content is not None:
+            overlay_text = self._extract_overlay_prompt(overlay_content)
+
+        # Layer 3: Task context — spec content
+        spec_content = self._state.read_file(spec_ref)
+
+        # Assemble the final prompt
+        sections: list[str] = [prompt.rstrip()]
+
+        if overlay_text:
+            sections.append(f"## Process Overlay\n{overlay_text}")
+
+        if spec_content is not None:
+            sections.append(f"## Spec\n{spec_content}")
+        else:
+            sections.append(
+                f"## Spec\n[Spec file '{spec_ref}' not found. Proceed with available context.]"
+            )
+
+        if findings:
+            sections.append(f"## Findings\n{findings}")
+
+        return "\n\n".join(sections) + "\n"
+
+    @staticmethod
+    def _extract_overlay_prompt(raw_yaml: str) -> str:
+        """Extract prompt or content from overlay YAML.
+
+        Overlay files may contain a 'prompt' field (like agent definitions)
+        or raw text content. Handles both.
+        """
+        try:
+            doc = yaml.safe_load(raw_yaml)
+            if isinstance(doc, dict) and "prompt" in doc:
+                return str(cast("dict[str, object]", doc)["prompt"]).strip()
+        except yaml.YAMLError:
+            pass
+        # Fall back to raw content
+        return raw_yaml.strip()
+
+
+def _kustomize_build(overlay: str | None, base_ref: str = HYPERLOOP_BASE_REF) -> str:
+    """Run ``kustomize build`` and return the raw YAML output.
+
+    Args:
+        overlay: Path or git URL to a kustomization directory.
+                 If None, builds from a temporary kustomization that
+                 references the hyperloop base.
+        base_ref: Kustomize remote resource for the base definitions.
+
+    Returns:
+        The multi-document YAML output from kustomize build.
+
+    Raises:
+        RuntimeError: If kustomize build exits non-zero.
+    """
+    if overlay is not None:
+        return _run_kustomize(overlay)
+
+    # No overlay — build a temp kustomization referencing the base
+    with tempfile.TemporaryDirectory() as tmp:
+        kustomization = Path(tmp) / "kustomization.yaml"
+        kustomization.write_text(f"resources:\n  - {base_ref}\n")
+        return _run_kustomize(tmp)
+
+
+def _run_kustomize(target: str) -> str:
+    """Execute ``kustomize build <target>`` and return stdout.
+
+    Raises:
+        RuntimeError: If the command fails.
+    """
+    result = subprocess.run(
+        ["kustomize", "build", target],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    if result.returncode != 0:
+        msg = f"kustomize build failed (exit {result.returncode}): {result.stderr.strip()}"
+        raise RuntimeError(msg)
+    return result.stdout
+
+
+def _extract_name(doc: dict[str, object]) -> str:
+    """Extract the resource name from a YAML document.
+
+    Supports both kustomize-style ``metadata.name`` and legacy top-level
+    ``name`` for backward compatibility.
+    """
+    metadata = doc.get("metadata")
+    if isinstance(metadata, dict) and "name" in metadata:
+        return str(metadata["name"])
+    return str(doc.get("name", ""))
+
+
+def _parse_multi_doc(raw: str) -> dict[str, AgentTemplate]:
+    """Parse multi-document YAML output into AgentTemplate objects.
+
+    Only documents with ``kind: Agent`` are extracted. Process definitions
+    and other kinds are ignored for prompt composition purposes.
+
+    Args:
+        raw: Multi-document YAML string from kustomize build.
+
+    Returns:
+        A dict mapping agent name -> AgentTemplate.
+    """
+    templates: dict[str, AgentTemplate] = {}
+    for doc in yaml.safe_load_all(raw):
+        if not isinstance(doc, dict):
+            continue
+        if doc.get("kind") != "Agent":
+            continue
+        name = _extract_name(doc)
+        prompt = doc.get("prompt", "")
+        annotations = doc.get("annotations", {})
+        if not isinstance(annotations, dict):
+            annotations = {}
+        templates[name] = AgentTemplate(
+            name=name,
+            prompt=str(prompt),
+            annotations={str(k): str(v) for k, v in annotations.items()},
+        )
+    return templates
+
+
+def check_kustomize_available() -> None:
+    """Check that kustomize is on PATH.
+
+    Raises:
+        SystemExit: If kustomize is not found.
+    """
+    if shutil.which("kustomize") is None:
+        msg = (
+            "Error: kustomize CLI not found. "
+            "Install it: https://kubectl.docs.kubernetes.io/installation/kustomize/"
+        )
+        raise SystemExit(msg)
+
+
+def load_templates_from_dir(base_dir: str | Path) -> dict[str, AgentTemplate]:
+    """Load agent templates directly from a directory of YAML files.
+
+    This is used for testing and as a fallback when kustomize is not available.
+    It reads all ``*.yaml`` files in ``base_dir`` and extracts Agent definitions.
+
+    Args:
+        base_dir: Path to the directory containing base agent YAML files.
+
+    Returns:
+        A dict mapping agent name -> AgentTemplate.
+    """
+    templates: dict[str, AgentTemplate] = {}
+    base_path = Path(base_dir)
+    for yaml_file in base_path.glob("*.yaml"):
+        if yaml_file.name == "kustomization.yaml":
+            continue
+        with open(yaml_file) as f:
+            doc = yaml.safe_load(f)
+        if doc and doc.get("kind") == "Agent" and "prompt" in doc:
+            name = _extract_name(doc)
+            annotations = doc.get("annotations", {})
+            if not isinstance(annotations, dict):
+                annotations = {}
+            templates[name] = AgentTemplate(
+                name=name,
+                prompt=doc["prompt"],
+                annotations={str(k): str(v) for k, v in annotations.items()},
+            )
+    return templates

{hyperloop-0.4.0 → hyperloop-0.5.0}/src/hyperloop/config.py

@@ -6,11 +6,14 @@ returns a frozen Config dataclass. CLI arguments can override file values.
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
 
 import yaml
 
+DEFAULT_BASE_REF = "github.com/jsell-rh/hyperloop//base?ref=main"
+
 if TYPE_CHECKING:
     from pathlib import Path
 
@@ -27,6 +30,7 @@ class Config:
     base_branch: str  # default: "main"
     specs_dir: str  # default: "specs"
     overlay: str | None  # path or git URL to kustomization dir
+    base_ref: str  # kustomize remote base ref (env: HYPERLOOP_BASE_REF)
     runtime: str  # "local" (v1 only)
     max_workers: int  # default: 6
     auto_merge: bool  # default: True
@@ -44,6 +48,7 @@ def _defaults() -> dict[str, object]:
         "base_branch": "main",
         "specs_dir": "specs",
         "overlay": None,
+        "base_ref": os.environ.get("HYPERLOOP_BASE_REF", DEFAULT_BASE_REF),
         "runtime": "local",
         "max_workers": 6,
         "auto_merge": True,
@@ -63,7 +68,7 @@ def _flatten_yaml(raw: dict[str, object]) -> dict[str, object]:
     flat: dict[str, object] = {}
 
     # Top-level scalars
-    for key in ("overlay", "poll_interval", "max_rounds", "max_rebase_attempts"):
+    for key in ("overlay", "base_ref", "poll_interval", "max_rounds", "max_rebase_attempts"):
         if key in raw:
             flat[key] = raw[key]
 
@@ -150,6 +155,7 @@ def load_config(
         base_branch=str(values["base_branch"]),
         specs_dir=str(values["specs_dir"]),
         overlay=values["overlay"] if values["overlay"] is not None else None,  # type: ignore[arg-type]
+        base_ref=str(values["base_ref"]),
         runtime=str(values["runtime"]),
         max_workers=int(values["max_workers"]),  # type: ignore[arg-type]
         auto_merge=bool(values["auto_merge"]),

{hyperloop-0.4.0 → hyperloop-0.5.0}/tests/test_compose.py

@@ -1,15 +1,17 @@
-"""Tests for prompt composition — base + overlay + task context.
+"""Tests for prompt composition — resolved templates + overlay + task context.
 
-Uses InMemoryStateStore with pre-loaded files. No real filesystem.
+Uses InMemoryStateStore with pre-loaded files and pre-resolved AgentTemplate
+objects. No kustomize dependency — unit tests skip the kustomize build step.
 """
 
 from __future__ import annotations
 
+import shutil
 from pathlib import Path
 
 import pytest
 
-from hyperloop.compose import PromptComposer
+from hyperloop.compose import AgentTemplate, PromptComposer, load_templates_from_dir
 from tests.fakes.state import InMemoryStateStore
 
 # The base/ dir lives at the repo root, adjacent to src/
@@ -21,6 +23,11 @@ BASE_DIR = Path(__file__).parent.parent / "base"
 # ---------------------------------------------------------------------------
 
 
+def _templates() -> dict[str, AgentTemplate]:
+    """Load base templates from the repo's base/ directory."""
+    return load_templates_from_dir(BASE_DIR)
+
+
 def _state_with_spec(
     spec_ref: str = "specs/widget.md", spec_content: str = "Build a widget."
 ) -> InMemoryStateStore:
@@ -40,7 +47,7 @@ class TestBasePromptOnly:
 
     def test_compose_returns_base_prompt_content(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -54,7 +61,7 @@ class TestBasePromptOnly:
 
     def test_compose_includes_spec_content(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -67,7 +74,7 @@ class TestBasePromptOnly:
 
     def test_compose_includes_no_findings_when_empty(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -85,7 +92,7 @@ class TestTemplateVariables:
 
     def test_spec_ref_is_replaced(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -99,7 +106,7 @@ class TestTemplateVariables:
 
     def test_task_id_is_replaced(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -120,7 +127,7 @@ class TestProcessOverlay:
         overlay_content = "prompt: |\n  Always run linter before submitting.\n"
         state.set_file("specs/prompts/implementer-overlay.yaml", overlay_content)
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -136,7 +143,7 @@ class TestProcessOverlay:
         state = _state_with_spec()
         # No overlay file set
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -154,7 +161,7 @@ class TestFindings:
 
     def test_findings_are_appended(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -172,7 +179,7 @@ class TestUnknownRole:
 
     def test_unknown_role_raises_value_error(self) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         with pytest.raises(ValueError, match=r"(?i)unknown.*role.*nonexistent"):
             composer.compose(
@@ -189,7 +196,7 @@ class TestMissingSpecRef:
     def test_missing_spec_still_composes(self) -> None:
         state = InMemoryStateStore()
         # No spec file set — spec_ref points to nothing
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -203,7 +210,7 @@ class TestMissingSpecRef:
 
     def test_missing_spec_notes_absence(self) -> None:
         state = InMemoryStateStore()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role="implementer",
@@ -228,7 +235,7 @@ class TestAllRoles:
     )
     def test_all_base_roles_compose(self, role: str) -> None:
         state = _state_with_spec()
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=_templates(), state=state)
 
         result = composer.compose(
             role=role,
@@ -238,3 +245,148 @@ class TestAllRoles:
         )
 
         assert len(result) > 0
+
+
+class TestLoadTemplatesFromDir:
+    """load_templates_from_dir reads YAML files and builds AgentTemplate objects."""
+
+    def test_loads_all_base_agents(self) -> None:
+        templates = load_templates_from_dir(BASE_DIR)
+        assert "implementer" in templates
+        assert "verifier" in templates
+        assert "pm" in templates
+        assert "process-improver" in templates
+        assert "rebase-resolver" in templates
+
+    def test_skips_non_agent_kinds(self) -> None:
+        """Process definitions (kind: Process) are not loaded as templates."""
+        templates = load_templates_from_dir(BASE_DIR)
+        assert "default" not in templates  # process.yaml has name: default
+
+    def test_template_has_prompt(self) -> None:
+        templates = load_templates_from_dir(BASE_DIR)
+        impl = templates["implementer"]
+        assert "You are a worker agent implementing a task" in impl.prompt
+
+    def test_template_has_annotations(self) -> None:
+        templates = load_templates_from_dir(BASE_DIR)
+        impl = templates["implementer"]
+        assert "ambient.io/persona" in impl.annotations
+
+
+class TestAgentTemplate:
+    """AgentTemplate is a frozen dataclass."""
+
+    def test_frozen(self) -> None:
+        t = AgentTemplate(name="test", prompt="hello", annotations={})
+        with pytest.raises(AttributeError):
+            t.name = "other"  # type: ignore[misc]
+
+    def test_equality(self) -> None:
+        a = AgentTemplate(name="x", prompt="p", annotations={"k": "v"})
+        b = AgentTemplate(name="x", prompt="p", annotations={"k": "v"})
+        assert a == b
+
+
+class TestParseMultiDoc:
+    """_parse_multi_doc extracts Agent definitions from multi-document YAML."""
+
+    def test_parses_agent_definitions(self) -> None:
+        from hyperloop.compose import _parse_multi_doc
+
+        raw = """\
+apiVersion: hyperloop.io/v1
+kind: Agent
+metadata:
+  name: implementer
+prompt: |
+  You are a worker.
+annotations:
+  ambient.io/persona: ""
+---
+apiVersion: hyperloop.io/v1
+kind: Process
+metadata:
+  name: default
+pipeline:
+  - role: implementer
+---
+apiVersion: hyperloop.io/v1
+kind: Agent
+metadata:
+  name: verifier
+prompt: |
+  You are a reviewer.
+annotations: {}
+"""
+        templates = _parse_multi_doc(raw)
+        assert "implementer" in templates
+        assert "verifier" in templates
+        assert "default" not in templates  # Process kind skipped
+
+    def test_handles_empty_input(self) -> None:
+        from hyperloop.compose import _parse_multi_doc
+
+        templates = _parse_multi_doc("")
+        assert templates == {}
+
+
+class TestKustomizeIntegration:
+    """Integration tests that require kustomize on PATH."""
+
+    @pytest.mark.skipif(
+        not shutil.which("kustomize"),
+        reason="kustomize CLI not available",
+    )
+    def test_from_kustomize_with_local_base(self, tmp_path: Path) -> None:
+        """Build from a local kustomization that references the base dir."""
+        import os
+
+        # kustomize requires relative paths for local resources
+        rel_base = os.path.relpath(BASE_DIR, tmp_path)
+        kustomization = tmp_path / "kustomization.yaml"
+        kustomization.write_text(f"resources:\n  - {rel_base}\n")
+
+        state = _state_with_spec()
+        composer = PromptComposer.from_kustomize(str(tmp_path), state)
+
+        result = composer.compose(
+            role="implementer",
+            task_id="task-001",
+            spec_ref="specs/widget.md",
+            findings="",
+        )
+        assert "You are a worker agent implementing a task" in result
+
+    @pytest.mark.skipif(
+        not shutil.which("kustomize"),
+        reason="kustomize CLI not available",
+    )
+    def test_from_kustomize_no_overlay_fetches_base(self) -> None:
+        """When overlay is None, builds from the hyperloop base remote resource."""
+        state = _state_with_spec()
+        # This actually hits GitHub — skip in CI if network is unavailable
+        try:
+            composer = PromptComposer.from_kustomize(None, state)
+        except RuntimeError:
+            pytest.skip("Network unavailable — cannot fetch remote base")
+
+        result = composer.compose(
+            role="implementer",
+            task_id="task-001",
+            spec_ref="specs/widget.md",
+            findings="",
+        )
+        assert len(result) > 0
+
+
+class TestCheckKustomize:
+    """check_kustomize_available raises SystemExit when kustomize is missing."""
+
+    def test_raises_when_missing(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from hyperloop.compose import check_kustomize_available
+
+        monkeypatch.setattr(shutil, "which", lambda _name: None)
+
+        with pytest.raises(SystemExit, match="kustomize CLI not found"):
+            check_kustomize_available()

{hyperloop-0.4.0 → hyperloop-0.5.0}/tests/test_loop.py

@@ -11,7 +11,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-from hyperloop.compose import PromptComposer
+from hyperloop.compose import PromptComposer, load_templates_from_dir
 from hyperloop.domain.model import (
     ActionStep,
     GateStep,
@@ -999,7 +999,7 @@ class TestPromptComposition:
         state.add_task(_task())
         state.set_file("specs/task-001.md", "Build a widget.")
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(state, runtime, composer=composer)
 
         # Cycle 1: spawn implementer
@@ -1028,7 +1028,7 @@ class TestPromptComposition:
         state.set_file("specs/task-001.md", "Build a widget.")
         state.store_findings("task-001", "Missing null check.\n")
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(state, runtime, composer=composer)
 
         orch.run_cycle()

{hyperloop-0.4.0 → hyperloop-0.5.0}/tests/test_serial_agents.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from hyperloop.compose import PromptComposer
+from hyperloop.compose import PromptComposer, load_templates_from_dir
 from hyperloop.domain.model import (
     LoopStep,
     Phase,
@@ -230,7 +230,7 @@ class TestPMIntake:
         serial = FakeSerialRunner()
         state.set_file("specs/widget.md", "Widget spec content")
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(state, runtime, serial_runner=serial, composer=composer)
 
         orch.run_cycle()
@@ -246,7 +246,7 @@ class TestPMIntake:
         state.set_file("specs/widget.md", "Widget spec content")
         state.add_task(_task(spec_ref="specs/widget.md"))
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(state, runtime, serial_runner=serial, composer=composer)
 
         orch.run_cycle()
@@ -288,7 +288,7 @@ class TestPMIntake:
         state.set_file("specs/widget.md", "Widget spec")
         state.add_task(_task(spec_ref="specs/widget.md"))
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(state, runtime, serial_runner=serial, composer=composer)
 
         orch.run_cycle()
@@ -316,7 +316,7 @@ class TestProcessImprover:
         state.add_task(_task())
         state.set_file("specs/widget.md", "Widget spec")
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(
             state, runtime, serial_runner=serial, composer=composer, max_rounds=50
         )
@@ -345,7 +345,7 @@ class TestProcessImprover:
         state.add_task(_task())
         state.set_file("specs/widget.md", "Widget spec")
 
-        composer = PromptComposer(base_dir=BASE_DIR, state=state)
+        composer = PromptComposer(templates=load_templates_from_dir(BASE_DIR), state=state)
         orch = _make_orchestrator(state, runtime, serial_runner=serial, composer=composer)
 
         # Cycle 1: spawn implementer

{hyperloop-0.4.0 → hyperloop-0.5.0}/uv.lock

@@ -61,7 +61,7 @@ wheels = [
 
 [[package]]
 name = "hyperloop"
-version = "0.2.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },

hyperloop-0.4.0/CHANGELOG.md

@@ -1,19 +0,0 @@
-# CHANGELOG
-
-<!-- version list -->
-
-## v0.4.0 (2026-04-15)
-
-
-## v0.3.0 (2026-04-15)
-
-
-## v0.2.0 (2026-04-15)
-
-
-## v0.1.1 (2026-04-15)
-
-
-## v0.1.0 (2026-04-15)
-
-- Initial Release

hyperloop-0.4.0/src/hyperloop/compose.py

@@ -1,126 +0,0 @@
-"""Prompt composition — assembles worker prompts from base + overlay + task context.
-
-Three layers composed at spawn time:
-1. Base prompt from base/{role}.yaml
-2. Process overlay from specs/prompts/{role}-overlay.yaml (if exists)
-3. Task context: spec content, findings, traceability refs (spec_ref, task_id)
-
-For v1, kustomize integration (project overlay) is skipped. The orchestrator
-reads base YAML files directly and injects process overlays + task context.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-import yaml
-
-if TYPE_CHECKING:
-    from hyperloop.ports.state import StateStore
-
-
-class PromptComposer:
-    """Composes agent prompts from base definitions + overlays + task context."""
-
-    def __init__(self, base_dir: str | Path, state: StateStore) -> None:
-        """Load base agent definitions from base_dir.
-
-        Args:
-            base_dir: Path to the directory containing base agent YAML files.
-            state: StateStore used to read process overlays and spec files
-                   from the target repo.
-        """
-        self._base_dir = Path(base_dir)
-        self._state = state
-        self._base_prompts: dict[str, str] = {}
-        self._load_base_definitions()
-
-    def _load_base_definitions(self) -> None:
-        """Load all base agent YAML files and extract their prompt fields."""
-        for yaml_file in self._base_dir.glob("*.yaml"):
-            with open(yaml_file) as f:
-                doc = yaml.safe_load(f)
-            if doc and doc.get("kind") == "Agent" and "prompt" in doc:
-                name = doc["name"]
-                self._base_prompts[name] = doc["prompt"]
-
-    def compose(
-        self,
-        role: str,
-        task_id: str,
-        spec_ref: str,
-        findings: str,
-    ) -> str:
-        """Compose the full prompt for a worker.
-
-        Layers:
-        1. Base prompt from base/{role}.yaml
-        2. Process overlay from specs/prompts/{role}-overlay.yaml (if exists)
-        3. Task context: spec content, findings, traceability refs
-
-        Args:
-            role: Agent role name (e.g. "implementer", "verifier").
-            task_id: Task identifier (e.g. "task-027").
-            spec_ref: Path to the originating spec file (e.g. "specs/persistence.md").
-            findings: Findings from prior rounds (empty string if none).
-
-        Returns:
-            The composed prompt string ready to pass to a worker.
-
-        Raises:
-            ValueError: If the role has no base agent definition.
-        """
-        # Layer 1: Base prompt
-        if role not in self._base_prompts:
-            msg = f"Unknown role '{role}': no base agent definition found in {self._base_dir}"
-            raise ValueError(msg)
-
-        base_prompt = self._base_prompts[role]
-
-        # Replace template variables
-        prompt = base_prompt.replace("{spec_ref}", spec_ref).replace("{task_id}", task_id)
-
-        # Layer 2: Process overlay (from target repo specs/prompts/)
-        overlay_path = f"specs/prompts/{role}-overlay.yaml"
-        overlay_content = self._state.read_file(overlay_path)
-        overlay_text = ""
-        if overlay_content is not None:
-            overlay_text = self._extract_overlay_prompt(overlay_content)
-
-        # Layer 3: Task context — spec content
-        spec_content = self._state.read_file(spec_ref)
-
-        # Assemble the final prompt
-        sections: list[str] = [prompt.rstrip()]
-
-        if overlay_text:
-            sections.append(f"## Process Overlay\n{overlay_text}")
-
-        if spec_content is not None:
-            sections.append(f"## Spec\n{spec_content}")
-        else:
-            sections.append(
-                f"## Spec\n[Spec file '{spec_ref}' not found. Proceed with available context.]"
-            )
-
-        if findings:
-            sections.append(f"## Findings\n{findings}")
-
-        return "\n\n".join(sections) + "\n"
-
-    @staticmethod
-    def _extract_overlay_prompt(raw_yaml: str) -> str:
-        """Extract prompt or content from overlay YAML.
-
-        Overlay files may contain a 'prompt' field (like agent definitions)
-        or raw text content. Handles both.
-        """
-        try:
-            doc = yaml.safe_load(raw_yaml)
-            if isinstance(doc, dict) and "prompt" in doc:
-                return str(cast("dict[str, object]", doc)["prompt"]).strip()
-        except yaml.YAMLError:
-            pass
-        # Fall back to raw content
-        return raw_yaml.strip()