AWK - AI Workflow Kit

An AI-assisted development workflow kit that drives Spec → Implement → PR → Merge, designed to work with Claude Code (Principal) + Codex (Worker), and compatible with Kiro-style specs.

English | 繁體中文

---

📋 Table of Contents

• Features
• Architecture Overview
• Technology Stack
• Project Structure
• Quick Start
• Configuration
• Directory Monorepo Example
• CI
• Evaluation
• Docs
• Contributing
• License

---

✨ Features

Core Workflow

• Spec-driven: reads .ai/specs/<name>/tasks.md (Kiro-compatible) to decide what to do next
• GitHub as state machine: uses issues/PRs + labels to track progress
• Dispatch + review loop: dispatches implementation to Worker, then reviews/merges or creates fix issues

Kit Quality

• Offline Gate: deterministic verification (no network required)
• Strict mode: --strict enforces “no P0 findings” in audit (CI/release checks)
• Extensibility checks: validates CI triggers on feat/example (branch alignment)

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                                                              │
│  You ──► awkit kickoff ──► Claude Code (Principal)            │
│                              │                               │
│                              ├─► read specs/tasks.md          │
│                              ├─► create GitHub Issue          │
│                              ├─► dispatch to Codex (Worker)   │
│                              ├─► review PR                    │
│                              ├─► merge or reject              │
│                              └─► loop                         │
│                                                              │
│  Morning ──► gh pr list ──► harvest                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

More details: docs/ai-workflow-architecture.md.

---

🛠️ Technology Stack

Offline (required)

• bash (Windows: Git Bash / WSL)
• git
• go 1.25+

Offline (optional)

• python3 + pyyaml + jsonschema + jinja2 (only needed for legacy scripts; generation is built into awkit)

Online / E2E (optional)

• gh (GitHub CLI) + gh auth login
• claude (Claude Code)
• codex (Worker)

---

📁 Project Structure

.
├── .ai/                         # kit (config/templates/rules/specs)
│   ├── config/workflow.yaml     # main config
│   ├── templates/               # generators (CLAUDE/AGENTS/CI)
│   ├── rules/                   # architecture + git workflow rules
│   ├── docs/evaluate.md         # evaluation standard
│   └── specs/                   # Kiro-style specs
├── .github/workflows/ci.yml     # root CI example
├── backend/                     # directory example (Go)
└── frontend/                    # directory example (Unity skeleton)

---

🚀 Quick Start

0) Install awkit (recommended)

awkit is the cross-platform AWK installer CLI (named awkit to avoid clashing with the system awk command).

curl -fsSL https://github.com/silver2dream/ai-workflow-kit/releases/latest/download/install.sh | bash

Windows (PowerShell):

irm https://github.com/silver2dream/ai-workflow-kit/releases/latest/download/install.ps1 | iex

Install AWK into a project:

# Initialize AWK in current directory
awkit init

# With a preset and scaffold
awkit init --preset go --scaffold

# Monorepo with React + Go
awkit init --preset react-go --scaffold

# Preview what would be created
awkit init --preset python --scaffold --dry-run

Available Presets

Category	Presets
Single-Repo	generic, go, python, rust, dotnet, node
Monorepo	react-go, react-python, unity-go, godot-go, unreal-go

Run awkit list-presets for details. See Getting Started for scaffold file structures.

Note: awkit install is an alias for awkit init (backward compatible).

For a complete workflow walkthrough, see the Quick Start Guide.

0.1) Update awkit

Check version and updates:

awkit version
awkit check-update

Update the CLI:

curl -fsSL https://github.com/silver2dream/ai-workflow-kit/releases/latest/download/install.sh | bash

Update kit files inside a project (preserves your workflow.yaml):

awkit upgrade
awkit generate

Other update options:

# Apply a different preset to workflow.yaml only
awkit init --preset react-go --force-config

# Upgrade kit files and overwrite workflow.yaml (requires --preset)
awkit upgrade --force-config --preset react-go

# Full reset: update kit files AND apply preset to workflow.yaml
awkit init --preset react-go --force

1) Generate outputs

awkit generate

2) (Optional) Run the full workflow

gh auth login

# Using awkit CLI (recommended)
awkit kickoff --dry-run    # Preview what would happen
awkit kickoff              # Start the workflow
awkit kickoff --resume     # Resume from saved state
awkit validate             # Validate config only

# Legacy bash scripts have been removed; use awkit commands above

Stop:

touch .ai/state/STOP

---

⚙️ Configuration

Main config: .ai/config/workflow.yaml

Repo type

AWK supports three repository types configured in .ai/config/workflow.yaml:

Type	Description	Use Case
root	Single repository	Standalone projects
directory	Subdirectory in monorepo	Monorepo with shared .git
submodule	Git submodule	Monorepo with independent repos

Type-Specific Behavior:

• root: All operations run from repo root. Path must be ./.
• directory: Operations run from worktree root, changes scoped to subdirectory.
• submodule: Commits/pushes happen in submodule first, then parent updates reference.

Example:

repos:
  - name: backend
    path: backend/
    type: directory  # or: root, submodule
    language: go
    verify:
      build: "go build ./..."
      test: "go test ./..."

Specs

Spec folder structure (Kiro compatible):

.ai/specs/<feature-name>/
├── requirements.md   # optional
├── design.md         # optional
└── tasks.md          # required

To enable a spec, add its folder name to specs.active in .ai/config/workflow.yaml.

---

📦 Directory Monorepo Example

This repo ships with a minimal directory-type example:

• backend/: a tiny Go module + unit test (go test ./...)
• frontend/: Unity skeleton (CI runs structure + JSON sanity only)
• Spec example: .ai/specs/example/
• Guide: docs/getting-started.md

---

🔁 CI

Root CI workflow: .github/workflows/ci.yml

For user projects:

• awkit init automatically creates a CI workflow for your project
• awkit upgrade automatically migrates deprecated CI configurations (removes old awk job)

For this repo (awkit itself): This repo ships a hand-maintained CI example. awkit generate does not modify workflows unless you pass --generate-ci.

It runs:

• AWK evaluation: awkit evaluate --offline and --offline --strict
• Kit tests: go test ./...
• Backend tests: go test ./... (in backend/)
• Frontend sanity: frontend/Packages/manifest.json JSON validation + folder checks

---

🧪 Evaluation

• For kit maintainers/CI only; regular users can skip.
• Standard: .ai/docs/evaluate.md
• Executor: awkit evaluate

---

📚 Documentation

For Users

Document	Description
Quick Start	5-minute setup guide
Getting Started	Detailed setup guide (zh-TW)
Configuration	workflow.yaml reference
Troubleshooting	Error solutions
FAQ	Common questions

For Developers

Document	Description
Architecture	System internals
API Reference	Scripts & modules
Contributing	Development guide
Testing	Test framework

Other

• Architecture Overview - High-level system design

---

🤝 Contributing

See Contributing Guide for:

• Development setup
• Code standards
• PR workflow

Quick reference:

• Branch model and commit format: .ai/rules/_kit/git-workflow.md
• PR base should target feat/example by default.

---

📄 License

This project is licensed under the Apache License 2.0.

🔒 Security & Trust

AWK follows open source security best practices and is monitored by OpenSSF Scorecard.

Security Features

Feature	Status	Description
SECURITY.md	✅	Vulnerability reporting policy and SLA
Branch Protection	✅	Required reviews and CI checks
CI/CD	✅	Automated testing on all PRs
Dependency Updates	✅	Dependabot enabled
Static Analysis	✅	CodeQL scanning
Token Permissions	✅	Minimal GitHub token permissions

See SECURITY.md for full security policy and vulnerability reporting.