gawt 0.1.0__tar.gz

gawt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install the project
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src tests
+
+      - name: Test with pytest
+        run: pytest -q

gawt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI (trusted publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

gawt-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.gitagent/

gawt-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-07
+
+### Added
+- Initial public release.
+- `git worktree`-based agent isolation under `.gitagent/`.
+- Session lifecycle: `init`, `start`, `status`, `log`, `abort`.
+- Agent management: `spawn`, `list-agents`, `kill`.
+- Proposals as patch + manifest: `propose`, `proposals`, `show`, `diff`.
+- Superagent decisions: `accept`, `reject`, `revise`, `integrate` (with `git apply --3way` conflict detection).
+- `finalize` producing a single squashed commit on the current branch and resetting `.gitagent` (never pushes).
+- `--json` output on `status`, `log`, `list-agents`, `proposals`, `integrate` for LLM/orchestrator consumption.
+- Append-only audit trail at `.gitagent/log.jsonl`.
+- CI (ruff + pytest on Python 3.11–3.13) and trusted-publishing release workflow.
+- Bundled `gitagent` agent skill (installable via `gitagent install-skill` or `make install-skill`).
+
+### Notes
+- The PyPI distribution is published as **`gawt`** (not `gitagent`) because the
+  name `gitagent` on PyPI is already taken by an unrelated project (a Tornado
+  HTTP webhook server, last released 2016). The installed command is still
+  `gitagent`. Install with `pipx install gawt` / `uv tool install gawt`.

gawt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Florez Mazuera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gawt-0.1.0/Makefile

@@ -0,0 +1,16 @@
+.PHONY: install-skill uninstall-skill test lint build
+
+install-skill:
+	bash scripts/install-skill.sh
+
+uninstall-skill:
+	rm -rf ~/.agents/skills/gitagent
+
+test:
+	. .venv/bin/activate && pytest
+
+lint:
+	. .venv/bin/activate && ruff check src tests
+
+build:
+	. .venv/bin/activate && uv build

gawt-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: gawt
+Version: 0.1.0
+Summary: Agent workspace manager over Git: isolate, review and consolidate multi-agent changes into a single commit.
+Project-URL: Homepage, https://github.com/david-fm/gawt
+Project-URL: Repository, https://github.com/david-fm/gawt
+Project-URL: Issues, https://github.com/david-fm/gawt/issues
+Author: David Florez Mazuera
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,cli,git,llm,multi-agent,worktree
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Pre-processors
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gitagent
+
+> Agent workspace manager over Git: isolate, review and consolidate multi-agent changes into a **single commit**.
+
+`gitagent` is a lightweight CLI that wraps `git worktree` so a **superagent** can spawn isolated **subagents**, collect their work as **proposals** (patch + manifest), accept/reject/revise them, and finally produce **one clean commit** on the real repository — then clean everything up. It never pushes.
+
+Two planes are kept strictly separate:
+
+- **`.git`** — the source of truth. Untouched until `finalize`, which writes exactly one commit.
+- **`.gitagent/`** — an ephemeral coordination layer: worktrees, patches, manifests, decisions, audit log. Discardable and reset after `finalize`/`abort`.
+
+`gitagent` does **not** reimplement Git. Proposals are stored as `git diff` patches plus JSON metadata, never as a second history.
+
+## Decision / application split (Option B)
+
+`gitagent` cleanly separates **deciding** from **applying**:
+
+| Command | Role |
+|---|---|
+| `accept <pid>` | Record the decision "approved". Does **not** apply. |
+| `reject <pid>` | Record "rejected". |
+| `revise <pid>` | Send back to the agent (new `pid` on re-propose). |
+| `integrate` | **Apply** all accepted proposals onto the integration branch. Detects conflicts. |
+| `finalize` | Calls `integrate` (if needed) + creates **one** commit on the current branch. |
+
+So a minimal flow is: `accept` each → `finalize`. Run `integrate` standalone when you want to see conflicts *before* the final commit.
+
+## Install
+
+The PyPI distribution is **`gawt`** (the name `gitagent` on PyPI is a different,
+unrelated project). The command it installs is still called `gitagent`.
+
+```bash
+# end user (isolated environment)
+pipx install gawt
+# or
+uv tool install gawt
+
+# from GitHub
+pipx install "git+https://github.com/david-fm/gawt"
+
+# local development
+git clone https://github.com/david-fm/gawt && cd gawt
+uv tool install . -e   # or: pipx install -e .
+```
+
+Requires Python 3.11+ and a working `git` on `PATH`.
+
+## Quick start (Option B)
+
+```bash
+gitagent init
+gitagent start --feature "auth-rate-limiting"
+
+# each subagent gets an isolated worktree + ephemeral branch
+gitagent spawn --id a_backend --role "implement limiter"
+gitagent spawn --id a_tests   --role "write tests"
+
+# subagents work in their own folders, then propose (no commit to .git)
+gitagent propose --agent a_backend --title "Token bucket limiter" --confidence 0.85
+gitagent propose --agent a_tests   --title "Limiter tests"        --confidence 0.9
+
+# superagent reviews and marks decisions
+gitagent proposals
+gitagent show p_7f3a
+gitagent accept p_7f3a
+gitagent revise p_9b2c --feedback "add edge cases"
+# ... a_tests re-proposes (a new pid is generated) ...
+gitagent accept p_9b2c
+
+# OPTIONAL: pre-flight apply to surface conflicts before committing
+gitagent integrate
+
+# consolidate into ONE commit on the current branch, then reset
+gitagent finalize --message "feat(auth): add rate limiting with tests"
+# → 1 local commit on HEAD, .gitagent reset, no push
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `init` | Create `.gitagent/` and add it to `.gitignore`. |
+| `start --feature <name>` | Open a session anchored at current `HEAD`. |
+| `status [--json]` | Show session, agents, proposals, integration state. |
+| `log [--json]` | Append-only audit trail (`log.jsonl`). |
+| `abort` | Discard everything: remove worktrees/branches, reset `.gitagent`. |
+| `spawn --id <id> [--base <ref>] [--role ...]` | Create an isolated worktree for a subagent. |
+| `list-agents [--json]` | List agents. |
+| `kill <id>` | Remove an agent's worktree and ephemeral branch. |
+| `propose --agent <id> --title ... [--summary ...] [--confidence 0..1]` | Capture worktree changes as a patch proposal. |
+| `proposals [--json]` | List proposals + review state. |
+| `show <id>` | Show a proposal's diff (color). |
+| `diff <id>` | Print a proposal's raw diff (pipe-friendly, for LLMs). |
+| `accept <id>` | Mark a proposal as accepted (decision only; does **not** apply). |
+| `reject <id> [--reason ...]` | Reject a proposal (patch not applied). |
+| `revise <id> --feedback ...` | Send a proposal back for another iteration. |
+| `integrate [--json]` | Apply all accepted proposals onto the integration branch; detect conflicts. |
+| `finalize --message ... [--sign] [--no-reset]` | Call `integrate` + produce one commit on the current branch + reset `.gitagent`. **Never pushes.** |
+| `install-skill` | Install the bundled `gitagent` agent skill into `~/.agents/skills/gitagent`. |
+
+## How it works
+
+- **Isolation**: `git worktree add` gives every agent its own `HEAD`, index and working tree while sharing the object store — ideal for parallelism.
+- **Proposals as patches**: `git -C <worktree> diff --cached <base_sha> --binary` is stored as `change.patch` and re-applied with `git apply --3way` on the integration worktree. Agent "commits" never pollute the final history.
+- **Integration order = proposal creation order**: the first agent to `propose` integrates first. Plan who proposes first if their change is the "base" others depend on.
+- **Single commit**: `finalize` does `git merge --squash <integration-branch>` on the current branch and creates exactly one commit, then removes all worktrees/branches and resets `.gitagent` (the audit log is kept).
+- **Conflicts**: a conflicting patch is marked `conflict` at `integrate` time — the session stays alive so the superagent can `revise`, fix the integration worktree manually (then re-`accept` + re-`integrate`), or `abort`.
+- **Concurrency**: file locks (`fcntl`) guard review-state writes; `accept` is safe to race (it only marks).
+- **Audit**: every event is appended to `.gitagent/log.jsonl` (parseable by another agent/LLM).
+- **Dual output**: humans get Rich tables; `--json` and `diff` give raw, pipe-friendly output for orchestration.
+
+## Layout
+
+```
+.gitagent/
+├── session.json                 # active session: id, feature, base_sha, state
+├── agents/<agent-id>/
+│   ├── meta.json                # role, worktree path, ephemeral branch, state
+│   └── worktree/                # git worktree for this agent
+├── proposals/<proposal-id>/
+│   ├── manifest.json            # agent, base_sha, files, summary, confidence
+│   ├── change.patch             # git diff of the proposal
+│   └── review.json              # pending|accepted|integrated|rejected|revise|conflict + feedback
+├── integration/worktree/        # integration branch under construction
+├── locks/                       # fcntl lockfiles for concurrent writes
+└── log.jsonl                    # append-only audit trail
+```
+
+Proposal states: `pending → accepted → integrated | conflict | revise | rejected`.
+Session states: `open → integrating → finalized | aborted`.
+
+## Installing the agent skill
+
+`gitagent` ships with a **skill** so any AI agent can use it freely — it teaches another agent the full CLI surface, the Option B decision/application split, conflict resolution recipes, and the supervisor/coder/reviewer patterns.
+
+The skill lives in the repo at `skills/gitagent/` (SKILL.md + AGENTS.md) and gets installed into the local opencode skills directory so future agent sessions can load it.
+
+### From a gitagent install (pipx / pip / uv tool)
+
+```bash
+gitagent install-skill
+# → installs bundled skill to ~/.agents/skills/gitagent
+# → re-run to refresh after upgrading gitagent
+```
+
+### From a git clone (developers / source installs)
+
+```bash
+git clone https://github.com/david-fm/gawt
+cd gitagent
+make install-skill
+# (equivalent to: bash scripts/install-skill.sh)
+```
+
+### Manual
+
+```bash
+cp -R skills/gitagent ~/.agents/skills/
+```
+
+The skill will be available to agents in **future** sessions. Re-run any of the above commands to refresh the installed copy.
+
+## Design principle
+
+> `finalize` **never** runs `git push`. It produces the local commit and stops. Pushing is entirely the user's responsibility.
+
+## License
+
+MIT © David Florez Mazuera

gawt-0.1.0/README.md

@@ -0,0 +1,170 @@
+# gitagent
+
+> Agent workspace manager over Git: isolate, review and consolidate multi-agent changes into a **single commit**.
+
+`gitagent` is a lightweight CLI that wraps `git worktree` so a **superagent** can spawn isolated **subagents**, collect their work as **proposals** (patch + manifest), accept/reject/revise them, and finally produce **one clean commit** on the real repository — then clean everything up. It never pushes.
+
+Two planes are kept strictly separate:
+
+- **`.git`** — the source of truth. Untouched until `finalize`, which writes exactly one commit.
+- **`.gitagent/`** — an ephemeral coordination layer: worktrees, patches, manifests, decisions, audit log. Discardable and reset after `finalize`/`abort`.
+
+`gitagent` does **not** reimplement Git. Proposals are stored as `git diff` patches plus JSON metadata, never as a second history.
+
+## Decision / application split (Option B)
+
+`gitagent` cleanly separates **deciding** from **applying**:
+
+| Command | Role |
+|---|---|
+| `accept <pid>` | Record the decision "approved". Does **not** apply. |
+| `reject <pid>` | Record "rejected". |
+| `revise <pid>` | Send back to the agent (new `pid` on re-propose). |
+| `integrate` | **Apply** all accepted proposals onto the integration branch. Detects conflicts. |
+| `finalize` | Calls `integrate` (if needed) + creates **one** commit on the current branch. |
+
+So a minimal flow is: `accept` each → `finalize`. Run `integrate` standalone when you want to see conflicts *before* the final commit.
+
+## Install
+
+The PyPI distribution is **`gawt`** (the name `gitagent` on PyPI is a different,
+unrelated project). The command it installs is still called `gitagent`.
+
+```bash
+# end user (isolated environment)
+pipx install gawt
+# or
+uv tool install gawt
+
+# from GitHub
+pipx install "git+https://github.com/david-fm/gawt"
+
+# local development
+git clone https://github.com/david-fm/gawt && cd gawt
+uv tool install . -e   # or: pipx install -e .
+```
+
+Requires Python 3.11+ and a working `git` on `PATH`.
+
+## Quick start (Option B)
+
+```bash
+gitagent init
+gitagent start --feature "auth-rate-limiting"
+
+# each subagent gets an isolated worktree + ephemeral branch
+gitagent spawn --id a_backend --role "implement limiter"
+gitagent spawn --id a_tests   --role "write tests"
+
+# subagents work in their own folders, then propose (no commit to .git)
+gitagent propose --agent a_backend --title "Token bucket limiter" --confidence 0.85
+gitagent propose --agent a_tests   --title "Limiter tests"        --confidence 0.9
+
+# superagent reviews and marks decisions
+gitagent proposals
+gitagent show p_7f3a
+gitagent accept p_7f3a
+gitagent revise p_9b2c --feedback "add edge cases"
+# ... a_tests re-proposes (a new pid is generated) ...
+gitagent accept p_9b2c
+
+# OPTIONAL: pre-flight apply to surface conflicts before committing
+gitagent integrate
+
+# consolidate into ONE commit on the current branch, then reset
+gitagent finalize --message "feat(auth): add rate limiting with tests"
+# → 1 local commit on HEAD, .gitagent reset, no push
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `init` | Create `.gitagent/` and add it to `.gitignore`. |
+| `start --feature <name>` | Open a session anchored at current `HEAD`. |
+| `status [--json]` | Show session, agents, proposals, integration state. |
+| `log [--json]` | Append-only audit trail (`log.jsonl`). |
+| `abort` | Discard everything: remove worktrees/branches, reset `.gitagent`. |
+| `spawn --id <id> [--base <ref>] [--role ...]` | Create an isolated worktree for a subagent. |
+| `list-agents [--json]` | List agents. |
+| `kill <id>` | Remove an agent's worktree and ephemeral branch. |
+| `propose --agent <id> --title ... [--summary ...] [--confidence 0..1]` | Capture worktree changes as a patch proposal. |
+| `proposals [--json]` | List proposals + review state. |
+| `show <id>` | Show a proposal's diff (color). |
+| `diff <id>` | Print a proposal's raw diff (pipe-friendly, for LLMs). |
+| `accept <id>` | Mark a proposal as accepted (decision only; does **not** apply). |
+| `reject <id> [--reason ...]` | Reject a proposal (patch not applied). |
+| `revise <id> --feedback ...` | Send a proposal back for another iteration. |
+| `integrate [--json]` | Apply all accepted proposals onto the integration branch; detect conflicts. |
+| `finalize --message ... [--sign] [--no-reset]` | Call `integrate` + produce one commit on the current branch + reset `.gitagent`. **Never pushes.** |
+| `install-skill` | Install the bundled `gitagent` agent skill into `~/.agents/skills/gitagent`. |
+
+## How it works
+
+- **Isolation**: `git worktree add` gives every agent its own `HEAD`, index and working tree while sharing the object store — ideal for parallelism.
+- **Proposals as patches**: `git -C <worktree> diff --cached <base_sha> --binary` is stored as `change.patch` and re-applied with `git apply --3way` on the integration worktree. Agent "commits" never pollute the final history.
+- **Integration order = proposal creation order**: the first agent to `propose` integrates first. Plan who proposes first if their change is the "base" others depend on.
+- **Single commit**: `finalize` does `git merge --squash <integration-branch>` on the current branch and creates exactly one commit, then removes all worktrees/branches and resets `.gitagent` (the audit log is kept).
+- **Conflicts**: a conflicting patch is marked `conflict` at `integrate` time — the session stays alive so the superagent can `revise`, fix the integration worktree manually (then re-`accept` + re-`integrate`), or `abort`.
+- **Concurrency**: file locks (`fcntl`) guard review-state writes; `accept` is safe to race (it only marks).
+- **Audit**: every event is appended to `.gitagent/log.jsonl` (parseable by another agent/LLM).
+- **Dual output**: humans get Rich tables; `--json` and `diff` give raw, pipe-friendly output for orchestration.
+
+## Layout
+
+```
+.gitagent/
+├── session.json                 # active session: id, feature, base_sha, state
+├── agents/<agent-id>/
+│   ├── meta.json                # role, worktree path, ephemeral branch, state
+│   └── worktree/                # git worktree for this agent
+├── proposals/<proposal-id>/
+│   ├── manifest.json            # agent, base_sha, files, summary, confidence
+│   ├── change.patch             # git diff of the proposal
+│   └── review.json              # pending|accepted|integrated|rejected|revise|conflict + feedback
+├── integration/worktree/        # integration branch under construction
+├── locks/                       # fcntl lockfiles for concurrent writes
+└── log.jsonl                    # append-only audit trail
+```
+
+Proposal states: `pending → accepted → integrated | conflict | revise | rejected`.
+Session states: `open → integrating → finalized | aborted`.
+
+## Installing the agent skill
+
+`gitagent` ships with a **skill** so any AI agent can use it freely — it teaches another agent the full CLI surface, the Option B decision/application split, conflict resolution recipes, and the supervisor/coder/reviewer patterns.
+
+The skill lives in the repo at `skills/gitagent/` (SKILL.md + AGENTS.md) and gets installed into the local opencode skills directory so future agent sessions can load it.
+
+### From a gitagent install (pipx / pip / uv tool)
+
+```bash
+gitagent install-skill
+# → installs bundled skill to ~/.agents/skills/gitagent
+# → re-run to refresh after upgrading gitagent
+```
+
+### From a git clone (developers / source installs)
+
+```bash
+git clone https://github.com/david-fm/gawt
+cd gitagent
+make install-skill
+# (equivalent to: bash scripts/install-skill.sh)
+```
+
+### Manual
+
+```bash
+cp -R skills/gitagent ~/.agents/skills/
+```
+
+The skill will be available to agents in **future** sessions. Re-run any of the above commands to refresh the installed copy.
+
+## Design principle
+
+> `finalize` **never** runs `git push`. It produces the local commit and stops. Pushing is entirely the user's responsibility.
+
+## License
+
+MIT © David Florez Mazuera

gawt-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "gawt"
+version = "0.1.0"
+description = "Agent workspace manager over Git: isolate, review and consolidate multi-agent changes into a single commit."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "David Florez Mazuera" }]
+keywords = ["git", "worktree", "ai-agents", "llm", "cli", "multi-agent"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Software Development :: Pre-processors",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://github.com/david-fm/gawt"
+Repository = "https://github.com/david-fm/gawt"
+Issues = "https://github.com/david-fm/gawt/issues"
+
+[project.scripts]
+gitagent = "gitagent.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitagent"]
+artifacts = ["_skills"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/gitagent" = "gitagent/_skills/gitagent"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

gawt-0.1.0/scripts/install-skill.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Install the gitagent agent skill into the local opencode skills directory.
+#
+# Usage:
+#   bash scripts/install-skill.sh
+#
+# The skill is copied to ~/.agents/skills/gitagent/. After this, any agent
+# you run in a future session that triggers the `gitagent` skill will see it.
+#
+# Re-run this script to refresh the installed copy (e.g. after pulling new
+# changes to the skill in this repo).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILL_SRC="$REPO_DIR/skills/gitagent"
+SKILL_DST="${HOME}/.agents/skills/gitagent"
+
+if [ ! -d "$SKILL_SRC" ]; then
+  echo "error: skill source not found at $SKILL_SRC" >&2
+  echo "Run this from inside the gitagent repository." >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$SKILL_DST")"
+rm -rf "$SKILL_DST"
+cp -R "$SKILL_SRC" "$SKILL_DST"
+echo "Installed gitagent skill to $SKILL_DST"
+echo "It will be available to agents in future sessions."