Merge pull request #15 from luohaha/feat/pip-installable

feat: pip/uv installable + auto-publish to PyPI on tag

Author: luohaha

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release to PyPI
+
+# Push a version tag (e.g. `v0.1.0`) to build and publish to PyPI.
+# Auth is PyPI Trusted Publishing (OIDC) — no token/secret in the repo.
+# One-time setup: on pypi.org add a publisher for project `goaloop`
+#   owner: luohaha   repo: GoaLoop   workflow: release.yml   environment: pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/goaloop
+    permissions:
+      id-token: write   # mint the OIDC token Trusted Publishing needs
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ver=$(grep -m1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          echo "tag=$tag  pyproject=$ver"
+          if [ "$tag" != "$ver" ]; then
+            echo "::error::tag v$tag does not match pyproject version $ver — bump pyproject.toml first"
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -57,37 +57,37 @@ verification passes.
 
 ## Install
 
-Two pieces: the `goaloop` CLI (the orchestrator), and the Claude Code
-skills (the Manager front-end).
-
-**1. Install the `goaloop` CLI** (stdlib-only, Python ≥ 3.10):
+Two pieces, two commands: install the `goaloop` CLI (the orchestrator),
+then deploy the Claude Code skills (the Manager front-end). Both ship in
+the package — no source checkout needed.
 
 ```bash
-git clone <repo-url> ~/GoaLoop
-pip install -e ~/GoaLoop          # provides the `goaloop` command
-# or run without installing:  python3 -m goaloop ...  (from ~/GoaLoop)
+uv tool install goaloop      # provides the `goaloop` command (stdlib-only, Python ≥ 3.10)
+goaloop install              # deploys /goal-init, /goal-run, /goal-flash + the goal-runner agent into ~/.claude
 ```
 
-The CLI reads the Runner's system prompt from `~/GoaLoop/agents/goal-runner.md`
-(set `GOALOOP_RUNNER_PROMPT` to override). It shells out to `claude`, so the
-Claude Code CLI must be on your `PATH` and authenticated.
+`uvx goaloop ...` works too if you prefer not to install persistently;
+`pip install goaloop` is equivalent if you don't use uv. The Runner's
+system prompt ships inside the package (override with
+`GOALOOP_RUNNER_PROMPT`). The CLI shells out to `claude`, so the Claude
+Code CLI must be on your `PATH` and authenticated.
 
-**2. Install the skills** — either local to one project:
+`goaloop install` skips any skill/agent that already exists; pass
+`--force` to overwrite. Verify by opening Claude Code and typing
+`/goal-init` — it should be recognized. (You can also drive the
+orchestrator entirely from the shell with `goaloop run`, skipping the
+skills.)
 
-```bash
-cd ~/your-working-project && mkdir -p .claude
-ln -s ~/GoaLoop/skills .claude/skills
-```
-
-…or globally for all CC sessions:
+<details>
+<summary>From source (development)</summary>
 
 ```bash
-mkdir -p ~/.claude/skills && cp -r ~/GoaLoop/skills/* ~/.claude/skills/
+git clone https://github.com/luohaha/GoaLoop ~/GoaLoop
+uv pip install -e ~/GoaLoop      # or: pip install -e ~/GoaLoop
+goaloop install                  # same skill/agent deploy as above
+# run without installing:  python3 -m goaloop ...  (from ~/GoaLoop)
 ```
-
-Verify by opening Claude Code and typing `/goal-init` — it should be
-recognized. (You can also drive the orchestrator entirely from the shell
-with `goaloop run`, skipping the skills.)
+</details>
 
 ## Quickstart
 

goaloop/cli.py

@@ -10,6 +10,7 @@
 
 import argparse
 import os
+import shutil
 import signal
 import subprocess
 import sys
@@ -230,6 +231,58 @@ def cmd_continue(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_install(args: argparse.Namespace) -> int:
+    """Deploy the bundled skills and Runner agent into ~/.claude.
+
+    Makes `/goal-init`, `/goal-run`, `/goal-flash` and the `goal-runner`
+    subagent available to every Claude Code session. The assets ship inside
+    the installed package (`resources/`), so this works from a `uv tool
+    install` / `pip install` with no source checkout.
+    """
+    resources = Path(__file__).resolve().parent / "resources"
+    claude = Path.home() / ".claude"
+
+    copied: list[str] = []
+    skipped: list[str] = []
+
+    def deploy(src: Path, dst: Path) -> None:
+        if dst.exists() and not args.force:
+            skipped.append(str(dst))
+            return
+        if dst.exists():
+            if dst.is_dir():
+                shutil.rmtree(dst)
+            else:
+                dst.unlink()
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if src.is_dir():
+            shutil.copytree(src, dst)
+        else:
+            shutil.copy2(src, dst)
+        copied.append(str(dst))
+
+    skills_src = resources / "skills"
+    if skills_src.is_dir():
+        for skill in sorted(p for p in skills_src.iterdir() if p.is_dir()):
+            deploy(skill, claude / "skills" / skill.name)
+
+    agents_src = resources / "agents"
+    if agents_src.is_dir():
+        for agent in sorted(agents_src.glob("*.md")):
+            deploy(agent, claude / "agents" / agent.name)
+
+    for path in copied:
+        print(f"installed  {path}")
+    for path in skipped:
+        print(f"exists     {path}  (use --force to overwrite)")
+    if not copied and not skipped:
+        print("Nothing to install — no bundled resources found.", file=sys.stderr)
+        return 1
+    if copied:
+        print("\nDone. Open Claude Code and type /goal-init to verify.")
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="goaloop", description=__doc__)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -265,6 +318,12 @@ def main(argv: list[str] | None = None) -> int:
     p_continue.add_argument("workspace")
     p_continue.set_defaults(func=cmd_continue)
 
+    p_install = sub.add_parser(
+        "install", help="deploy bundled skills + agent into ~/.claude")
+    p_install.add_argument("--force", action="store_true",
+                           help="overwrite existing skills/agents")
+    p_install.set_defaults(func=cmd_install)
+
     args = parser.parse_args(argv)
     return args.func(args)
 

goaloop/orchestrator.py

@@ -445,15 +445,17 @@ def _parse_terminator(text: str) -> dict | None:
 def _runner_system_prompt() -> str:
     """The Runner instructions, used as --append-system-prompt.
 
-    Single source of truth is `agents/goal-runner.md` in the repo; its YAML
-    frontmatter is stripped. Override with GOALOOP_RUNNER_PROMPT if the file
-    is not co-located with the package.
+    Single source of truth is `agents/goal-runner.md` in the repo, shipped
+    inside the package at `resources/agents/goal-runner.md` (a symlink in the
+    source tree, a real copy in the installed wheel) so an installed `goaloop`
+    is self-contained. Its YAML frontmatter is stripped. Override with
+    GOALOOP_RUNNER_PROMPT to point elsewhere.
     """
     import os
 
     override = os.environ.get("GOALOOP_RUNNER_PROMPT")
     path = Path(override) if override else (
-        Path(__file__).resolve().parents[1] / "agents" / "goal-runner.md"
+        Path(__file__).resolve().parent / "resources" / "agents" / "goal-runner.md"
     )
     text = path.read_text()
     if text.startswith("---"):

goaloop/resources/README.md

@@ -0,0 +1,10 @@
+# Packaged resources
+
+`agents/` and `skills/` here are symlinks to the repo's top-level `agents/`
+and `skills/` — the single source of truth. They live under the package so
+the build (`setuptools`) copies their real content into the wheel, making an
+installed `goaloop` self-contained: the orchestrator loads the Runner system
+prompt from `resources/agents/goal-runner.md`, and `goaloop install` deploys
+`resources/skills/*` and `resources/agents/*` into `~/.claude/`.
+
+Editing the top-level files is all you need; do not edit through the symlinks.

goaloop/resources/agents

@@ -0,0 +1 @@
+../../agents

goaloop/resources/skills

@@ -0,0 +1 @@
+../../skills

pyproject.toml

@@ -2,8 +2,25 @@
 name = "goaloop"
 version = "0.1.0"
 description = "Goal-driven multi-attempt iteration loop driven by `claude -p`"
+readme = "README.md"
 requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "luohaha" }]
+keywords = ["claude", "claude-code", "agent", "automation", "iteration", "goal-driven"]
 dependencies = []  # stdlib only
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Build Tools",
+    "Operating System :: POSIX",
+]
+
+[project.urls]
+Homepage = "https://github.com/luohaha/GoaLoop"
+Repository = "https://github.com/luohaha/GoaLoop"
 
 [project.scripts]
 goaloop = "goaloop.cli:main"
@@ -14,3 +31,13 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
 packages = ["goaloop"]
+
+# `resources/agents` and `resources/skills` are symlinks to the repo's
+# top-level dirs (the single source of truth); setuptools copies their real
+# content into the wheel so an installed `goaloop` is self-contained.
+[tool.setuptools.package-data]
+goaloop = [
+    "resources/README.md",
+    "resources/agents/*.md",
+    "resources/skills/*/*.md",
+]