pasture

module

v0.0.4 Latest Latest Go to latest Published: Jun 7, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/dayvidpham/pasture

Links

Open Source Insights

README ¶

Pasture

Go implementation of the Aura Protocol codegen and workflow engine.

What This Does

Pasture provides the runtime infrastructure for the Aura Protocol: a Temporal workflow engine (pastured daemon), CLI for sending protocol messages (pasture-msg), a local task + audit CLI (pasture), and release tooling (pasture-release). The daemon orchestrates agent workflows with constraint validation, phase transitions, and audit trail logging. All task and audit operations route through a single protocol.TaskTracker façade against one shared SQLite file at ~/.local/share/pasture/pasture.db. See AGENTS.md for the full architectural overview and docs/adr/0001-pasture-toolkit-integration-architecture.md (in the parent repo) for the integration ADR.

Quick Start

Build and test:

make build          # produces bin/pastured, bin/pasture-msg, bin/pasture-release
make test           # go test -race ./...
make lint           # go vet ./...
make fmt            # gofmt -w .

Or use Nix:

nix develop         # dev shell with Go, gopls, sqlite, temporal-cli
nix build .#pastured
nix build .#pasture-msg

Project Structure

cmd/
  ├── pasture/         # Local task + audit CLI (pasture task + pasture migrate)
  ├── pastured/        # Temporal worker daemon entry point
  ├── pasture-msg/     # CLI for sending protocol messages
  └── pasture-release/ # Release and versioning tool
internal/
  ├── acp/             # Agent Control Protocol client + adapter
  ├── audit/           # Audit trail + schema migrator (SQLite-backed)
  ├── config/          # Viper-based configuration
  ├── errors/          # Actionable error types
  ├── formatters/      # Output formatters (JSON, text, table)
  ├── handlers/        # Cobra RunE → standalone handler functions
  ├── hooks/           # Claude Code hook event handlers
  ├── tasks/           # protocol.TaskTracker implementation + well-known agent registry
  ├── temporal/        # Temporal workflow/activity implementations
  └── types/           # Internal aggregate types
pkg/
  └── protocol/        # Public aura-protocol types — including protocol.TaskTracker

CLI Surface (`pasture`)

The local pasture CLI hosts task verbs (task create / show / update / close / list, task ready, task blocked, task dep add|tree, task label add|remove, task comment add, task comments) and event/audit verbs added by PROPOSAL-2:

Subcommand	Purpose
`pasture task events [--epoch-id <id>] [--phase <p>] [--role <r>]`	Query audit events
`pasture task timeline TASK-ID`	Show all events attached to a task
`pasture task contexts EVENT-ID`	List context_edges attached to an event
`pasture task agents [list\|show]`	List or inspect registered agents
`pasture migrate [--dry-run]`	Run pending audit-database schema migrations (top-level — NOT under `pasture task`)

Key Conventions

No CGo: All dependencies pure Go (CGO_ENABLED=0). Use modernc.org/sqlite, not mattn/go-sqlite3.
Strongly-typed enums: Prefer typed constants over bare strings.
Actionable errors: Every error describes what, why, where, when, and how to fix.
Test pattern: *_test.go files import actual production code with dependency injection for mocks.

Contributing

See CONTRIBUTING.md for how to evolve protocol concepts (adding constraints, roles, phases, etc.).

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
pasture command Command pasture is the local task management CLI for the Pasture toolkit.	Command pasture is the local task management CLI for the Pasture toolkit.
pasture-migrate-crash command Command pasture-migrate-crash is a TEST-ONLY binary that drives the v2→v3 migration on a supplied SQLite file but aborts via os.Exit(137) (SIGKILL-equivalent) AFTER the v3 transaction has executed `INSERT INTO audit_schema_meta (version=3, ...)` but BEFORE `tx.Commit()`.	Command pasture-migrate-crash is a TEST-ONLY binary that drives the v2→v3 migration on a supplied SQLite file but aborts via os.Exit(137) (SIGKILL-equivalent) AFTER the v3 transaction has executed `INSERT INTO audit_schema_meta (version=3, ...)` but BEFORE `tx.Commit()`.
pasture-msg command Command pasture-msg is the Pasture CLI — sends control messages to the pastured daemon via Temporal signals and queries.	Command pasture-msg is the Pasture CLI — sends control messages to the pastured daemon via Temporal signals and queries.
pasture-release command Command pasture-release manages versioning and release coordination across the Pasture polyrepo (Nix, GitHub Releases, go install, skill channels).	Command pasture-release manages versioning and release coordination across the Pasture polyrepo (Nix, GitHub Releases, go install, skill channels).
pasture-test-agent command Package main implements pasture-test-agent — a fake ACP-compatible agent binary used only in tests.	Package main implements pasture-test-agent — a fake ACP-compatible agent binary used only in tests.
pastured command Command pastured is the Pasture daemon — a Temporal worker that runs pasture-protocol workflows and activities for multi-agent orchestration.	Command pastured is the Pasture daemon — a Temporal worker that runs pasture-protocol workflows and activities for multi-agent orchestration.
internal
acp Package acp provides an ACP (Agent Client Protocol) client for connecting to ACP-compatible agents and receiving live session update streams.	Package acp provides an ACP (Agent Client Protocol) client for connecting to ACP-compatible agents and receiving live session update streams.
audit Package audit provides the pluggable audit persistence interface and concrete implementations for the Pasture epoch workflow audit trail.	Package audit provides the pluggable audit persistence interface and concrete implementations for the Pasture epoch workflow audit trail.
codegen Package codegen — agent definition generation.	Package codegen — agent definition generation.
config Package config provides configuration structs and resolution logic for pasture daemons and CLI tools.	Package config provides configuration structs and resolution logic for pasture daemons and CLI tools.
errors Package errors provides structured, actionable error reporting for the pasture system.	Package errors provides structured, actionable error reporting for the pasture system.
formatters Package formatters — events.go	Package formatters — events.go
handlers Package handlers — hook.go	Package handlers — hook.go
hooks Package hooks provides a hook event dispatch system for the pasture protocol.	Package hooks provides a hook event dispatch system for the pasture protocol.
release Package release provides version management, changelog generation, git helpers, and plugin registry operations for pasture-release.	Package release provides version management, changelog generation, git helpers, and plugin registry operations for pasture-release.
tasks Package tasks provides the small wiring layer between pasture's CLI and the Provenance task tracker library.	Package tasks provides the small wiring layer between pasture's CLI and the Provenance task tracker library.
temporal Package temporal defines shared Temporal signal and query name constants for the Pasture epoch workflow.	Package temporal defines shared Temporal signal and query name constants for the Pasture epoch workflow.
testutil Package testutil provides shared testing utilities for the pasture test suite.	Package testutil provides shared testing utilities for the pasture test suite.
types Package types defines internal enums and value types for the Pasture daemon and CLI.	Package types defines internal enums and value types for the Pasture daemon and CLI.
pkg
protocol Package protocol defines the public convergence types for the Pasture multi-agent orchestration protocol.	Package protocol defines the public convergence types for the Pasture multi-agent orchestration protocol.
tools
codegen command Command codegen is the go:generate entry point for the pasture codegen system.	Command codegen is the go:generate entry point for the pasture codegen system.