Metadata-Version: 2.4
Name: agentguides
Version: 0.5.10
Summary: Runtime, validators, and tooling for Guides — a Skill-compatible extension for multi-step processes with human/agent judgment.
Project-URL: Homepage, https://github.com/agentguides/runtime
Project-URL: Documentation, https://github.com/agentguides/runtime/tree/main/docs
Project-URL: Issues, https://github.com/agentguides/runtime/issues
Author: Brian Cripe
License: MIT
License-File: LICENSE
Keywords: agent,guide,mcp,skills,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: agent-client-protocol>=0.10.1
Requires-Dist: anthropic>=0.40
Requires-Dist: fastmcp>=2.0
Requires-Dist: filelock>=3.13
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.20
Requires-Dist: packaging>=23
Requires-Dist: pydantic>=2.6
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: analysis
Requires-Dist: networkx>=3.0; extra == 'analysis'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'web'
Description-Content-Type: text/markdown

# Agent Guides

**Guides** — a Skill-compatible extension to the [Agent Skills specification](https://agentskills.io/specification) for multi-step processes that need human or agent judgment.

A Guide is a directory that conforms to the Skill spec and adds:

- A `GUIDE.md` describing the workflow (summary, goal state, prerequisites, rollback).
- A `steps/` directory with one markdown file per step (action + optional verify + optional recovery + optional rollback).
- An atomic, append-only state and audit history (markdown in v0.1; pluggable for future backends).

Every Guide is a valid Skill. Skill-only harnesses see a useful artifact; Guide-aware harnesses execute the workflow.

## Install

```bash
uv tool install agentguides           # puts `guide` on PATH
```

The `guide` binary is the hard prereq. Per-harness wiring (walk Skill,
walk-observer plugin, MCP server registration) is installed by
`guide setup <harness>` — one-time per machine; see the [Run a Guide](#run-a-guide)
section below and [`docs/cli/setup.md`](docs/cli/setup.md) for the four
install dimensions (scope, mode, capability, install method).

Dev install from a checkout:

```bash
uv sync                                  # creates .venv from pyproject.toml + uv.lock
```

## Author a Guide

The `guide new` scaffolder produces a SKILL-folder skeleton that passes `guide validate` immediately:

```bash
guide new my-guide --into ./guides
# Scaffolded at ./guides/my-guide/{SKILL.md, GUIDE.md, steps/010-first-step.md, plugin.json, README.md}
guide validate --root ./guides/my-guide --book ./guides
# OK
```

For an interactive author flow that asks about the goal, step list, and recovery story, invoke the `/create-guide` Skill (`skills/create-guide/`). It calls `guide new` under the hood and edits the placeholders inline.

See [`docs/SPEC.md`](docs/SPEC.md) for the full data model and [`examples/books/postgres-upgrade/postgres-major-upgrade/`](examples/books/postgres-upgrade/postgres-major-upgrade/) for a worked example.

## Share a Guide

Guides distribute as folders (drop into `~/.claude/skills/`), as plugin-per-guide (the folder + a `plugin.json`), or as a single-file `.guide` bundle for transport:

```bash
guide pack ./guides/my-guide --out ./dist
# → ./dist/my-guide-0.1.0.guide  (ZIP + MANIFEST.json; sha256-stamped)

guide unpack ./dist/my-guide-0.1.0.guide /tmp/extracted
# → /tmp/extracted/my-guide/   (sha256 + spec_version verified before write)
```

For multiple related Guides under a single plugin, see the [`examples/books/db-ops/`](examples/books/db-ops/) book example (and [`examples/books/postgres-upgrade/`](examples/books/postgres-upgrade/)).

## Run a Guide

Three execution paths:

**1. In Claude Code (LLM-driven, full feature set):**

```bash
guide setup claude-code   # one-time per machine: installs walk Skill + walk-observer plugin
guide harness walk --adapter claude-code --guide examples/books/postgres-upgrade/postgres-major-upgrade --exec
```

`guide setup` writes the walk Skill (rendered from a packaged template for
the chosen mode + capability) and the walk-observer plugin into
`~/.claude/skills/`. Claude Code auto-discovers both on its next
session. The harness `run` command prepares per-walk scratch
(mcp-config, prompt, audit state path) and invokes `claude -p` with
the right flags. See [`docs/cli/setup.md`](docs/cli/setup.md) and
[`docs/adapters/claude-code.md`](docs/adapters/claude-code.md).

**2. Headless (no LLM, scripts only):**

```bash
python -m adapters.cli.run \
    --root examples/books/postgres-upgrade/postgres-major-upgrade \
    --state-path /tmp/headless-test
# Script actions run; manual/agent_judgment steps log "skipped: no LLM".
```

Useful for CI smoke tests and non-LLM ops pipelines. See [`docs/adapters/cli.md`](docs/adapters/cli.md).

**3. Resuming an interrupted run** — the harness uses `walk_current({guide_id})` to find the active run id and asks the user whether to resume, abandon, or inspect.

## Documentation

All public documentation lives under [`docs/`](docs/):

- [**`docs/SPEC.md`**](docs/SPEC.md) — normative Guide v0.1 specification.
- [**`docs/DESIGN.md`**](docs/DESIGN.md) — design record. Appendices §22–§26 cover the v0.1 runtime, toolchain, `.guide` bundle, parity rule, and repo layout.
- [**`docs/ARCHITECTURE.md`**](docs/ARCHITECTURE.md) — runtime topology, component layering, state lifecycle, packaging shapes (Mermaid diagrams).
- [**`docs/adapters/`**](docs/adapters/) — per-harness implementation guides (`claude-code.md`, `cli.md`).
- [**`src/agentguides/schemas/`**](src/agentguides/schemas/) — JSON Schemas validating each Guide artifact (canonical inside the package; public `$id` points at `https://agentguides.io/schema/...`).
- `docs/QUICKSTART.md` and `docs/CHANGELOG.md` — added in M6.

Working Guides live in [`examples/`](examples/):

- [`postgres-upgrade/`](examples/books/postgres-upgrade/) — primary + rescue Guide pair as a book; cross-Guide bare-name references.
- [`db-ops/`](examples/books/db-ops/) — three Guides under one book; cross-Guide bare-name references.
- [`api-latency-spike-triage/`](examples/guides/api-latency-spike-triage/), [`wildland-fire-incident-command/`](examples/guides/wildland-fire-incident-command/), [`hello-walk/`](examples/guides/hello-walk/) — standalone single-Guide examples.

## Reading order

1. **`docs/SPEC.md`** — what a Guide is, what a conforming harness must do.
2. **`examples/books/postgres-upgrade/postgres-major-upgrade/`** — a worked example exercising every spec section.
3. **`docs/DESIGN.md`** — *why* each decision was made.
4. **`docs/ARCHITECTURE.md`** — *how* the v0.1 reference runtime is built.
5. **`docs/adapters/claude-code.md`** — implementing or installing the runtime for Claude Code.

## `just` recipes

```bash
just setup           # uv sync
just validate        # schema + DAG + refs for every example Guide
just test            # run the Python test suite
just new <name>      # scaffold a Guide (passes guide validate immediately)
just pack <dir>      # produce a .guide bundle
just unpack <bundle> <dest>
just launch [GUIDE]  # Claude Code session with example + MCP server attached
just watch           # tail the active run state file
just inspect         # open the active run state file in $EDITOR
just clean           # wipe /tmp/guide-test-* dirs
```

## Project planning

Internal planning artifacts (active plans, ADRs, milestone trackers) live under [`.planning/`](.planning/). Contributors who want context should look there; end users do not need to.

## Status

**v0.1.** See [`docs/SPEC.md` §19](docs/SPEC.md) for the explicit list of features deferred to v0.2+, and [`.planning/milestones/v0.1.md`](.planning/milestones/v0.1.md) for milestone progress.
