agentic-workflows

agentic-workflows

An opinionated agentic-development workflow, wrapped in deterministic checks so it actually holds.

awf renders a standardised, opinionated agentic-development workflow into any project — a suite of Claude Code skills, independent review agents, and documentation — from a small committed config tree, and wraps the probabilistic agent in deterministic checks (drift, frontmatter, invariant backing, dead links).

You keep a .awf/ config tree in your repo; awf renders it into the files your agent reads (.claude/, AGENTS.md, docs/), and tells you the moment the rendered output drifts from the config that produced it.

Status: pre-1.0 and evolving; the rendered standard is language-agnostic, the awf tool is a Go binary. Interfaces may change before a tagged release.

Why

The instructions your AI agent follows — how to brainstorm, when to write an ADR, what a review must check, which gate blocks a commit — are usually scattered across prompts, retyped per session, and impossible to review. They drift from how the project actually works, and nothing tells you when.

awf makes that workflow a version-controlled artifact:

• Reviewable — the workflow lives in a committed .awf/ config tree, so changes to how your agents work go through the same diff-and-review as changes to your code.
• Consistent — every contributor (and every agent session) reads the same rendered skills, agents, and docs; there is no per-developer prompt folklore.
• Enforced — a deterministic gate wraps the probabilistic agent: drift detection, frontmatter validation, invariant backing, and dead-link checks fail loudly instead of rotting silently.
• Portable — one small config tree renders a whole standard into any repo, in any language, and awf check keeps the rendered output honest forever after.

How it works

.awf/  (you commit this)          rendered output (awf writes & tracks this)
├── config.yaml   enable arrays   ├── AGENTS.md            agent guide
│                 + vars          ├── CLAUDE.md            imports AGENTS.md
├── <kind>/<name>.yaml  sidecars  ├── .claude/skills/…     workflow skills
└── <kind>/parts/…/…    overrides ├── .claude/agents/…     review agents
                                  └── docs/…               project docs

You change the config and re-render; you never hand-edit a rendered file. awf check fails if a rendered file is stale (config changed) or hand-edited, so the two never silently diverge. To customise a section, drop a convention part under .awf/ that overrides just that section and inherits the rest of the template.

Install

Download a prebuilt binary for your platform from the latest release, extract it, and put awf on your PATH. awf is a single static binary with no runtime dependencies — no Go toolchain required.

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

Pinning with .awf/bootstrap.sh

Projects that enable the bootstrap artifact get a small rendered shell script at .awf/bootstrap.sh (enabled by default on awf init). It downloads the exact awf version the repo was rendered with from GitHub releases, verifies the archive's SHA-256 against the release checksums before installing, caches the binary under ~/.cache/awf/<version>/, and prints its path — so hooks and CI run the pinned version without anyone installing awf by hand:

"$(bash .awf/bootstrap.sh)" check

It touches nothing outside its cache directory, and awf remove bootstrap deletes it if you'd rather manage the binary yourself. The bootstrap and the rendered hook payloads are bash scripts and the bootstrap targets the linux/darwin archives — on Windows, install awf on PATH and run it directly instead of through the pin.

Quickstart

cd your-project
awf init             # scaffold .awf/, render the workflow-core set
awf check            # verify rendered output is in sync
awf list             # see which targets are enabled vs available
awf add skill tdd    # opt a skill in
awf add doc pitfalls # opt a doc in

awf init enables a curated workflow core by default — the brainstorm → ADR → plan → implement → review chain skills, the review agents, and the workflow docs. Everything else in the catalog is opt-in with awf add <kind> <name> (and awf remove <kind> <name> to opt back out).

Commands

Run awf help for the full synopsis.

Adopting into an existing repo

awf init never silently clobbers your files. If a path it would write (e.g. an existing AGENTS.md) is already present and not awf-managed, init refuses and lists the collisions. Then:

• awf init --force overwrites them, backing each original up to <path>.awf-bak first.
• Trim to taste — the curated default is small; grow or shrink it with awf add/remove <kind> <name> (or edit .awf/config.yaml directly).
• Prefix — rendered skills are named <prefix>-<skill>; awf init derives prefix from the repo directory's basename. Change it via the prefix key in .awf/config.yaml, then awf sync.
• Back out anytime — awf uninstall removes everything awf generated, leaving your .awf/ config in place.

awf never installs or activates git hooks — the wiring is yours. It does render hook content: with the hooks artifact enabled (on by default from awf init, or awf add hooks), three inert payload scripts land under .awf/hooks/ — pre-commit.sh (drift check, then your gate), commit-msg.sh (awf commit-gate), and pre-push.sh (the fullest gate tier you configure) — drift-checked and kept current like every rendered file. Invoke them from wiring you own: an executable .git/hooks/pre-commit stub containing exec bash .awf/hooks/pre-commit.sh "$@", a tracked core.hooksPath directory, or your hook manager's config. If you adopted an earlier awf that ran awf setup, your repo's core.hooksPath still points at the no-longer-rendered .githooks/; run git config --unset core.hooksPath (or keep the now hand-owned hook files) after upgrading.

Local hooks are per-clone, so back them with CI. A minimal GitHub Actions job — the bootstrap script keeps CI on the exact awf version the repo was rendered with:

jobs:
  awf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Drift check (pinned awf)
        run: '"$(bash .awf/bootstrap.sh)" check'
      - name: Gate
        run: make gate # your project's gate command

Documentation

• AGENTS.md — the agent guide (rendered) that orients an AI agent in this repo
• docs/architecture.md — system shape, packages, key components
• docs/workflow.md — the brainstorm/ADR/plan chain and commit discipline
• docs/decisions/README.md — architecture decision records
• docs/development.md — local setup and the ./x command runner

Contributing

This project develops itself with the workflow it ships. Before non-trivial work, read AGENTS.md and docs/workflow.md. The core rule: never hand-edit a rendered file — change .awf/ (or a template) and run awf sync, then awf check. The gate (./x gate) must pass before every commit.

License

MIT © hypnotox.

awf renders configuration for, and interoperates with, Anthropic's Claude Code, but is an independent project — not affiliated with or endorsed by Anthropic.