MiAW

Minimal Agentic Workflow — project-local state and evidence for work done with coding Agents.

MiAW gives an Agent a recorded task to resume, rather than asking it to reconstruct the project from chat history. It works alongside your coding Agent and Git; it is not a model, an IDE or a hosted execution service.

中文

The design

Human decisions
      ↓
Coding Agent + skills ── aw CLI ── project records (.aw/)
                            ├── Agent Server → delegated workers
                            └── Project Index → source retrieval

The host Agent reasons and uses tools. Skills explain the working procedure. The CLI validates records and state transitions. Agent Server runs bounded delegated work; Project Index helps locate source evidence. Neither a worker report nor a search result counts as acceptance by itself.

| Record | Question it answers | | --- | --- | | Project and Blueprint | What are we building, and which design rules apply? | | Roadmap | Which candidate work should come next? | | Task | What was requested, planned, changed and checked? | | Agent evidence | What did each delegated worker actually do? | | Knowledge | Which accepted lessons should later tasks retain? |

A task follows a recorded work loop:

Intention → Analyze → Plan → Execute → Verify → Commit → Archive

Brainstorm, Review and Consolidate are used when needed; skipping an optional step requires a recorded reason. Blocked work stays resumable by task ID. Verification, risk acceptance and commit approval are separate decisions: an Agent saying “done” does not close the task.

Durable design and execution records live in .aw/; Git records source changes. Disposable service state and index caches live in .aw/.runtime/ and stay out of Git and synchronization. Worktrees share a worker pool only for the same workflow owner on the same host platform; WSL and native Windows have separate runtime pools.

Start

Requires Node.js 18+ and a supported host: Linux x64 with glibc 2.28+, Windows x64 or macOS Apple Silicon. npm installs the platform binary; Rust is not required. Use Git for commits and isolated worktrees, or configure vcs = "none" for a project without Git.

npm install -g @direal/miaw
aw --version
cd your-project
aw init "Short project summary"
aw install --target agents
aw status

agents installs skills into .agents/skills/. Use --target claude-code for Claude Code or --target codex for hosts that use .codex/skills/. Pi users can also install the optional status integration with pi install npm:@direal/miaw.

Open your authenticated coding Agent in that project and use the skills through its supported interface. For example:

$aw-init Establish the project goals and constraints
$aw-task Add rate limiting to the API
$aw-resume <task-id>

Initialization and record inspection need no model account. Delegated execution additionally needs a configured provider and passing readiness checks. Linux/WSL workers require Bubblewrap; native Windows execution requires explicit unsandboxed opt-in. Roles and permitted write paths are not a substitute for OS isolation.

Inspect and maintain

• aw status shows task state; aw tui provides an interactive view.
• aw docs getting-started --lang en explains provider setup and host integration. Use --lang zh for Chinese; the manual ships with the package and works outside a source checkout.
• aw update status inspects the installed release; aw update asks for authorization before the first update. Update each host separately.
• If aw --version still shows an older build, inspect command precedence with type -a aw on Linux/WSL or Get-Command aw -All in PowerShell. A Cargo installation can precede the npm command.

Manage workflow state through the CLI or skills, not by editing task JSON. Review prompts, responses and logs before sharing .aw/: durable evidence can contain private project information.

MIT licensed. Model accounts and provider credentials remain under your control.