agentic-workflows

module

v0.39.0 Latest Latest Go to latest Published: Aug 16, 2026 License: AGPL-3.0

Details

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

Repository

github.com/hypnotox/agentic-workflows

Links

Open Source Insights

README ¶

agentic-workflows

awf is a language-agnostic Go CLI for installing a governed agentic-development workflow. A committed .awf/ tree renders consistent, reviewable guidance, and awf check detects drift.

Highlights

Core and Full workflow profiles: Core for operational coding discipline, Full for governed ADR, plan, and current-state authority
A workflow from clarification through implementation, review, and retrospective
ADRs for load-bearing decisions and plans when sequencing or coordination helps
Fresh-context agents for exploration, grounding, implementation, and review
Generated agent guides, skills, documentation, and optional Git hook payloads
Current-state topics that separate live project authority from historical decisions
Backed invariants that connect documented claims to tests or explicit verification
Repository-local efforts and managed worktrees for work that needs continuity
Deterministic rendering and drift checks in local development and CI

Supported coding agents

awf renders native catalogs for both Pi and Claude Code. Both targets are generated by default.

Pi adopters install hypnotox/pi-tools independently without pinning a tag or commit, then reload Pi:

pi install git:git@github.com:hypnotox/pi-tools

awf does not pin its revision, so it can be patched or updated without an awf release. Compatibility is established by a successful protocol-v2 capability handshake and final awf profile registration. A missing, incompatible, late, or rejected handshake reports an actionable error and activates no awf fallback. pi-tools owns general context usage, handoff, and subagent execution mechanics; awf renders the workflow-specific profile adapter and, when enabled, its effort integration.

The awf-owned effort extension requires the APIs provided by the fork-v0.84.2.2 Pi release or a later compatible build. See all Pi fork releases for downloadable versions.

Install

Download a binary from the latest awf release, extract it, and place awf on your PATH.

To install from source with Go 1.26 or later:

go install github.com/hypnotox/agentic-workflows/cmd/awf@latest

Quickstart

From the repository you want awf to manage:

awf init
awf check
awf list

awf init creates a Core .awf/ tree and renders the workflow. Use awf init --profile full for ADR, plan, current-state, context, and workflow-audit governance. Existing repositories upgrade explicitly to Full. Commit both the source tree and its rendered outputs. After changing .awf/, render and check again:

awf render
awf check

If initialization finds an existing file it would replace, it stops and reports the collision. awf init --force first saves each replaced file as <path>.awf-bak.

How it works

.awf/                              rendered output
├── config.yaml                    ├── AGENTS.md
├── <kind>/<name>.yaml             ├── .pi/skills/ and .pi/agents/
├── <kind>/parts/...               ├── .claude/skills/ and .claude/agents/
└── parts/...                      └── docs/

Core supplies brainstorming, implementation, testing, review, efforts, and managed worktrees. Full adds ADRs for durable decisions, plans for sequenced work, current-state authority, context, and workflow audit.

flowchart LR
    I([intake]) --> B{clarify?}
    B -->|yes| BR[brainstorm]
    B -->|no| D{durable decision?}
    BR --> D
    D -->|yes| A[ADR and review]
    D -->|no| P{plan useful?}
    A --> P
    P -->|yes| PL[plan and review]
    P -->|no| X[implement]
    PL --> X
    X --> R[review when warranted]
    R --> T([retrospective])

See the workflow guide for the full decision criteria.

Commands

Command	Purpose
`awf init [flags]`	Scaffold .awf/ and render the selected profile
`awf render`	Re-render after a template or config change
`awf check`	Verify the repository and staged universes
`awf read <subcommand>`	Read an executable projection from a parsed artifact
`awf audit <base>\|<a>..<b>`	Report workflow-conformance findings over a commit range (advisory)
`awf effort <subcommand>`	Manage slugged repository-local efforts
`awf adr <subcommand>`	ADR lifecycle operations
`awf list [<kind>]`	Show the catalog and configured domain inventory
`awf config [<key-or-var>]`	Describe config keys and vars (live state inside a project)
`awf context [<path>...] [--show <facet>]... [--full] [--staged] [--range <a>..<b>] [--uncovered]`	Orient by request with compact current-state impact reports
`awf topic <domain>/<topic>[:<claim>] [flags]`	Query current claims, history, references, and applicability
`awf new <kind> <args>`	Scaffold a new artifact: kind in {adr, plan, topic, domain, pitfall, doc}
`awf remove domain <name>`	Remove a configured domain
`awf upgrade [--recover]`	Migrate the .awf/ config tree or consume a current-state attestation
`awf uninstall`	Remove awf's generated files (keeps .awf/)
`awf changelog [--version <v> \| --since <v> \| --range <from>..<to>]`	Print the embedded changelog, or one version/range of it
`awf version`	Print the awf version

Run awf help for complete usage. See Working with awf for configuration, overrides, upgrades, hooks, efforts, and day-to-day commands.

Git hooks and CI

Wire the generated .awf/hooks/ payloads through your own hook mechanism and run awf check in CI. Enable .awf/bootstrap.sh to use the repository-pinned awf release.

Documentation

Working with awf: commands, configuration, and daily use
Workflow: the development workflow and commit discipline
Configuration reference: all configuration keys and variables
Architecture: system structure and dependencies
ADR guide: decision format and lifecycle
Development: contributing setup and project commands

Status

awf is pre-1.0. Interfaces and generated formats may change before a stable release. Use awf upgrade when moving an existing project to a newer schema.

Contributing

Read AGENTS.md and the development guide.

License

awf interoperates with third-party coding agents and is not affiliated with or endorsed by their vendors.

Directories ¶

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

Path	Synopsis
changelog Package changelog embeds the hand-maintained CHANGELOG.md (ADR-0041).	Package changelog embeds the hand-maintained CHANGELOG.md (ADR-0041).
cmd
awf command Command awf renders standardised .claude skills, agents, and docs into a project from embedded templates plus a per-project .awf/ config tree.	Command awf renders standardised .claude skills, agents, and docs into a project from embedded templates plus a per-project .awf/ config tree.
contextspilllog command Command contextspilllog is the repository runner's private context-spill observability helper.	Command contextspilllog is the repository runner's private context-spill observability helper.
covercheck command Command covercheck fails when a Go coverprofile shows less than 100% statement coverage over blocks not marked with a coverage-ignore directive.	Command covercheck fails when a Go coverprofile shows less than 100% statement coverage over blocks not marked with a coverage-ignore directive.
deadcodecheck command Command deadcodecheck fails when `deadcode -json` (read from stdin) reports any unreachable function outside the internal/testsupport/ tree.	Command deadcodecheck fails when `deadcode -json` (read from stdin) reports any unreachable function outside the internal/testsupport/ tree.
mutants command Command mutants reads a gremlins -o JSON report and prints the surviving (LIVED) mutants as an advisory triage list, backing the awf `./x mutants` command (ADR-0066).	Command mutants reads a gremlins -o JSON report and prints the surviving (LIVED) mutants as an advisory triage list, backing the awf `./x mutants` command (ADR-0066).
pincheck command Command pincheck is the workflow supply-chain pin gate (ADR-0079).	Command pincheck is the workflow supply-chain pin gate (ADR-0079).
releasecheck command Command releasecheck is the release-time project-license and changelog pin.	Command releasecheck is the release-time project-license and changelog pin.
repoaudit command Command repoaudit runs repo-specific conformance checks over a git commit range, sharing awf audit's finding contract: it reports the same warn/error rank from internal/severity, and exits non-zero only on an error finding.	Command repoaudit runs repo-specific conformance checks over a git commit range, sharing awf audit's finding contract: it reports the same warn/error rank from internal/severity, and exits non-zero only on an error finding.
internal
adr Package adr parses ADR files under docs/decisions, renders the INDEX.md decision index, and scaffolds new ADR files from the rendered template (awf new adr).	Package adr parses ADR files under docs/decisions, renders the INDEX.md decision index, and scaffolds new ADR files from the rendered template (awf new adr).
audit Package audit reports workflow-conformance findings over a branch's git history.	Package audit reports workflow-conformance findings over a branch's git history.
catalog Package catalog is the compile-time Go value declaring the standard's skills, agents, and docs.	Package catalog is the compile-time Go value declaring the standard's skills, agents, and docs.
changelog Package changelog parses the embedded CHANGELOG.md (see the top-level changelog package) into structured, filterable entries (ADR-0041).	Package changelog parses the embedded CHANGELOG.md (see the top-level changelog package) into structured, filterable entries (ADR-0041).
clispec Package clispec is the single declarative source of awf's CLI command set: every command's flags, positional bounds, gating, help text, and (for a group command) its subcommands.	Package clispec is the single declarative source of awf's CLI command set: every command's flags, positional bounds, gating, help text, and (for a group command) its subcommands.
commitmsg Package commitmsg cleans Git commit messages and parses stale-ADR authorization trailers.	Package commitmsg cleans Git commit messages and parses stale-ADR authorization trailers.
commitpolicy Package commitpolicy owns exact commit-policy facts, evaluation outcomes, and human rendering.	Package commitpolicy owns exact commit-policy facts, evaluation outcomes, and human rendering.
config Package config loads and validates the per-project .awf/ configuration: a skeleton config.yaml plus per-target sidecar YAMLs and convention parts.	Package config loads and validates the per-project .awf/ configuration: a skeleton config.yaml plus per-target sidecar YAMLs and convention parts.
configspec Package configspec is the compile-time, adopter-facing description authority for the .awf configuration surface: every config.yaml key, sidecar field, var, and per-artifact data key an adopter can set.	Package configspec is the compile-time, adopter-facing description authority for the .awf configuration surface: every config.yaml key, sidecar field, var, and per-artifact data key an adopter can set.
contextdelivery Package contextdelivery enforces the terminal-size boundary for context output.	Package contextdelivery enforces the terminal-size boundary for context output.
contextq Package contextq answers context and coverage questions over one assembled context state: path classification, request assembly, universe assembly, topic and claim and pending projection, artifact records, the context and uncovered result vocabulary, and the human rendering of those results (ADR-0195).	Package contextq answers context and coverage questions over one assembled context state: path classification, request assembly, universe assembly, topic and claim and pending projection, artifact records, the context and uncovered result vocabulary, and the human rendering of those results (ADR-0195).
contextspill Package contextspill recognizes context spill notices and records local, path-free observability events for the repository runner.	Package contextspill recognizes context spill notices and records local, path-free observability events for the repository runner.
coverage Package coverage parses a Go coverprofile and reports statement coverage over blocks not marked with a coverage-ignore directive.	Package coverage parses a Go coverprofile and reports statement coverage over blocks not marked with a coverage-ignore directive.
currentstate Package currentstate validates parsed ADR application authority and topics.	Package currentstate validates parsed ADR application authority and topics.
effort Package effort owns repository-local immutable effort residents and their memory.	Package effort owns repository-local immutable effort residents and their memory.
execution Package execution selects closed operation steps, prepares their requirement closure once, and executes prepared actions in deterministic order.	Package execution selects closed operation steps, prepares their requirement closure once, and executes prepared actions in deterministic order.
filepublication Package filepublication owns complete same-directory file preparation and released-platform atomic no-replace namespace publication.	Package filepublication owns complete same-directory file preparation and released-platform atomic no-replace namespace publication.
filesystem Package filesystem owns root-confined production filesystem access.	Package filesystem owns root-confined production filesystem access.
frontmatter Package frontmatter splits and parses YAML frontmatter delimited by leading "---" lines in markdown content.	Package frontmatter splits and parses YAML frontmatter delimited by leading "---" lines in markdown content.
git Package git is awf's one semantic git seam: every git capability the application needs is an entrypoint here, and which backend answers an entrypoint (in-process object reads, or native Git through the package runner) is an implementation detail no consumer can observe.	Package git is awf's one semantic git seam: every git capability the application needs is an entrypoint here, and which backend answers an entrypoint (in-process object reads, or native Git through the package runner) is an implementation detail no consumer can observe.
initspec Package initspec resolves awf init answers against the catalog's value descriptors and emits the descriptor schema (ADR-0029).	Package initspec resolves awf init answers against the catalog's value descriptors and emits the descriptor schema (ADR-0029).
manifest Package manifest reads and writes the .awf/awf.lock and detects drift between rendered output and its sources.	Package manifest reads and writes the .awf/awf.lock and detects drift between rendered output and its sources.
memorycite Package memorycite answers one question about a piece of text: does it cite a specific working-memory file (ADR-0158)? The working-memory convention allows a decision record to name the directory or a placeholder, and bans naming an actual file, so the discrimination is entirely about what follows the prefix.	Package memorycite answers one question about a piece of text: does it cite a specific working-memory file (ADR-0158)? The working-memory convention allows a decision record to name the directory or a placeholder, and bans naming an actual file, so the discrimination is entirely about what follows the prefix.
migrate Package migrate ports a project's awf config across schema generations.	Package migrate ports a project's awf config across schema generations.
pathglob Package pathglob is awf's single glob dialect (ADR-0077): anchored full-path doublestar matching against slash-separated repo-relative paths.	Package pathglob is awf's single glob dialect (ADR-0077): anchored full-path doublestar matching against slash-separated repo-relative paths.
pitfall Package pitfall owns authored pitfall identity and source semantics.	Package pitfall owns authored pitfall identity and source semantics.
plan Package plan parses plan files under docs/plans and scaffolds new plans from the rendered plans template (awf new plan).	Package plan parses plan files under docs/plans and scaffolds new plans from the rendered plans template (awf new plan).
presentation Package presentation owns the closed CLI presentation grammar.	Package presentation owns the closed CLI presentation grammar.
project Package project ties config, catalog, render, and manifest together to sync rendered files into a project and check them for drift.	Package project ties config, catalog, render, and manifest together to sync rendered files into a project and check them for drift.
projectlicense Package projectlicense owns verification of this project's AGPL-3.0-only license artifacts.	Package projectlicense owns verification of this project's AGPL-3.0-only license artifacts.
prosegate Package prosegate scans a project's tracked text files for the seven banned typographic punctuation substitutes (ADR-0119).	Package prosegate scans a project's tracked text files for the seven banned typographic punctuation substitutes (ADR-0119).
refs Package refs extracts internal markdown link targets from rendered content.	Package refs extracts internal markdown link targets from rendered content.
render Package render parses awf section markers and renders templates with per-project overlays via text/template.	Package render parses awf section markers and renders templates with per-project overlays via text/template.
resident Package resident owns resident-root policy and path anchoring: the closed table of repository-wide roots awf owns at the primary control root, the predicate that recognises a path or a render kind as resident, the Roots value that resolves an output path against the right anchor, and the resident lifecycle operations.	Package resident owns resident-root policy and path anchoring: the closed table of repository-wide roots awf owns at the primary control root, the predicate that recognises a path or a render kind as resident, the Roots value that resolves an output path against the right anchor, and the resident lifecycle operations.
severity Package severity holds the one finding rank awf reports.	Package severity holds the one finding rank awf reports.
snapshot Package snapshot captures immutable file trees from Git or an ordinary filesystem directory.	Package snapshot captures immutable file trees from Git or an ordinary filesystem directory.
testsupport Package testsupport provides shared test-fixture helpers used across awf's test suites: managed TestMain HOME lifecycle, project-config scaffolding, ADR frontmatter fixtures, file-writing primitives, and the seam-swap idiom.	Package testsupport provides shared test-fixture helpers used across awf's test suites: managed TestMain HOME lifecycle, project-config scaffolding, ADR frontmatter fixtures, file-writing primitives, and the seam-swap idiom.
testsupport/cmd/testtmpclean command Command testtmpclean owns repo-private test-temp cleanup invoked by ./x clean-test-tmp and is not part of the shipped awf CLI.	Command testtmpclean owns repo-private test-temp cleanup invoked by ./x clean-test-tmp and is not part of the shipped awf CLI.
testsupport/fsfixture Package fsfixture provides the repository's kernel-backed controlled filesystem fault source as the distinct test source authorized by ADR-consumer-local-contracts-over-single-home-filesystem-access.	Package fsfixture provides the repository's kernel-backed controlled filesystem fault source as the distinct test source authorized by ADR-consumer-local-contracts-over-single-home-filesystem-access.
testsupport/gitfixture Package gitfixture is the single home for building git repository state in awf's test suites.	Package gitfixture is the single home for building git repository state in awf's test suites.
topic Package topic parses and validates current-state topic inputs.	Package topic parses and validates current-state topic inputs.
upgrade Package upgrade runs the permanent final current-state upgrade: it verifies only the sealed facts of a bridge attestation and applies the cutover output plan through a recoverable journal.	Package upgrade runs the permanent final current-state upgrade: it verifies only the sealed facts of a bridge attestation and applies the cutover output plan through a recoverable journal.
worktree Package worktree manages native-Git effort worktrees.	Package worktree manages native-Git effort worktrees.
templates Package templates embeds the standard's template tree (skills, agents, docs, bootstrap).	Package templates embeds the standard's template tree (skills, agents, docs, bootstrap).
tools
pi-extension-test/lockrun command lockrun runs one command while holding a checkout-local advisory lock.	lockrun runs one command while holding a checkout-local advisory lock.