agentic-workflows

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 governance footprints with one shared correctness, autonomy, maintainability, and review-quality bar
• 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. Linux tarballs carry portable root:root ownership and ordinary executable and regular-file modes, so a restricted rootless user namespace can extract them without mapping the release builder's account.

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 to add ADR, plan, current-state, context, and workflow-audit governance. Both footprints use the same correctness, autonomy, maintainability, and review-quality bar. 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 includes the operational workflow: 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. These governance footprints select artifacts, not different standards of rigor or autonomy.

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

Punctuation findings are advisory Warnings with zero exit.

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.

Current limitations remain explicit:

• Adopter pi-tools is revision-independent and usable only after a successful protocol-v2 handshake; awf pins only its test support.
• Effort-backed implementation children align with an explicit managed checkout, but parent-session mutation still relies on explicit path targeting and deliberate outside writes are not confined. See Known Issues.
• Release archives and checksums share one publication channel. Exact-revision rulesets and workflow gates do not provide independent provenance; immutable releases and attestations remain deferred.
• Linux is the behavioral CI host. Darwin and Windows release targets receive compile and archive checks but not hosted behavioral jobs; broader platform assurance remains deferred.
• The exact-identity coverage ratchet retains a reviewed exception ledger and focused mutation blocker. Coverage-system redesign and broader mutation sampling remain deferred.

Every open repository issue and its completion criteria remains listed in Known Issues.

Contributing

Read AGENTS.md and the development guide.

License

GNU Affero General Public License v3.0 only © hypnotox.

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