YAAW
yet another agentic workflow
Pronounced "yaw" — rhymes with "saw"
A tool that prepares any repo for human+AI collaboration with reusable skills, structured conventions, and compound memory.
17+ skills •
Compounding knowledge •
Enforced quality gates
The Problem
- AI agents lose project context between sessions
- No memory between sessions — same mistakes repeated
- No guardrails — agents commit to main, skip tests, break builds
- Each dev configures their own agent differently
- Knowledge stays siloed per dev — solved problems get re-discovered by everyone else
- Discovery and findings disappear into chat history instead of becoming reusable context
- No cross-repo awareness — local fixes can break silent dependents
Solution: yaaw-skills
- 17 shared skills propagated to all devs via yaaw update
- Compounding knowledge base — context/ persists across sessions
- 6 enforced gates — TDD, branch, build, plan approval, review, commit
- Session continuity — agent resumes where it left off
- Cross-repo coordination — shared changes, pipeline templates, dependency mapping
- Per-repo auto-detection — pre-filled configs for known repos
- Skill overrides — customize behavior without forking
- External knowledge boundaries — guardrails for project-specific libraries and APIs
- Stack constraint enforcement — keeps agents aligned to repo conventions
- Caveman mode — 50-70% fewer tokens, code stays readable
- Branch naming enforcement — issue or work item IDs supported
- Works with any AI agent (Amazon Q, Copilot, Claude Code, Cursor)
First-Time Setup
git config --global credential.useHttpPath true; $y="$env:USERPROFILE\.yaaw"; if (Get-Command yaaw -ErrorAction SilentlyContinue) { yaaw help } elseif (Test-Path "$y\install.ps1") { & "$y\install.ps1" } elseif (Test-Path $y) { throw "$y already exists but is not a yaaw-skills checkout. Rename or remove it, then run setup again." } else { git clone https://github.com/koshikg/yaaw.git $y; if ($LASTEXITCODE -ne 0) { throw "git clone failed" }; & "$y\install.ps1" }
Then in any repo:
yaaw init
- Auto-detects repo name
- Scaffolds context/ folder
- Generates router file (.amazonq/rules/yaaw-agent.md)
CLI Commands
| Command | What it does |
|---|---|
| yaaw init | Setup current repo for agentic dev |
| yaaw update | Pull latest skills + refresh router |
| yaaw skills | List skills + open directory |
| yaaw status | Show installed version |
| yaaw doctor | Diagnose setup issues |
| yaaw reset | Repair install + regenerate router |
Architecture
%USERPROFILE%\.yaaw\ ← shared (this repo)
├── dist/skills/ ← 17 skill definitions
├── dist/templates/ ← router + config templates
├── dist/AGENTS.md ← agent identity
├── dist/PROCESS.yaml ← gates & rules
└── dist/SYSTEM.md ← cross-repo knowledge
<any-project-repo>/ ← each project
├── .amazonq/rules/yaaw-agent.md ← generated router (gitignored)
└── context/ ← knowledge base (committed)
├── config.yaml
├── _session.md
├── discovery/
├── learnings/
├── plans/
└── work/
The 17+ Skills
Core Workflow 5
| Skill | Purpose |
|---|---|
| yaaw-discover | Investigate codebase, map dependencies |
| yaaw-plan | Produce PRDs with implementation units |
| yaaw-work | Execute plans — TDD, build verification, small commits |
| yaaw-review | Self-review before pushing |
| yaaw-commit | Conventional commits with gate enforcement |
yaaw-build runs inside yaaw-work — work is never complete without passing build + tests.
Utility 12
| Skill | Purpose |
|---|---|
| yaaw-build | Repo-aware build & test gate (called by yaaw-work) |
| yaaw-capture | Record learnings |
| yaaw-grillme | Stress-test designs |
| yaaw-caveman | 50-70% fewer tokens |
| yaaw-security | Vulnerability audit |
| yaaw-techdebt | Debt analysis & scoring |
| yaaw-pipeline | GitHub Actions and CI/CD YAML |
| yaaw-crossrepo | Multi-repo coordination |
| yaaw-release | Release notes from commits |
| yaaw-doctor | Setup diagnostics |
| yaaw-devops | DevOps CLI workflows |
| yaaw-stack-constraints | Repo conventions (always active) |
Engineering Lifecycle
Discover → Plan → Work → Review → Commit
↓ ↓ ↓ ↓ ↓
findings PRD code self-check push
↓ ↓ ↓ ↓ ↓
[gate] [approval] [TDD+build] [approval] [all gates]
- Discover — investigate codebase, map dependencies, identify unknowns
- Plan — structured PRD with implementation units, grilled until shared understanding
- Work — TDD execution unit by unit, valid branch required, build after each unit
- Review — agent self-review (auth, data changes, risk) + human approval
- Commit — conventional commit only after ALL prior gates proven satisfied
- Human approval at EVERY phase boundary — silence = do not proceed
- Fresh session at each boundary — Discover → Plan → Work → Review → Commit
- If client cannot auto-open a new session: stop, write handoff, emit next-phase starter prompt
- Model pool: Discover/Plan/Review → GPT-5.5 primary (Opus/Gemini/Sonnet alternatives); Work/Commit → GPT-5.3-Codex primary (5.2-Codex/Sonnet alternatives)
Enforced Gates (cannot be bypassed)
- Plan Approval Gate — PRD must be approved before work starts
- Branch Gate — Must be on valid feature branch (with work item ID)
- TDD Gate — Tests before code, always
- Build Verification Gate — yaaw-build must pass per unit
- Review Gate — Self-review before push
- Commit Gate — All prior gates satisfied + user approval
Compounding Knowledge Base
- Every skill READS from context/ before work
- Every skill WRITES back after work
- Knowledge accumulates across sessions
- Mandatory reading order:
_session.md → config.yaml → learnings/_index.yaml → discovery/ → SYSTEM.md
- "refresh knowledge" / "sync" command forces full re-read
Session Continuity
- _session.md = handoff contract between sessions
- Tracks:
- current focus
- recent decisions
- in-progress items
- blocked items
- next steps
- Agent reads it FIRST every session — resumes where it left off
- Say "resume" or "status" to pick up
In-Chat Commands
| Say this | What happens |
|---|---|
| resume / continue | Picks up where last session left off |
| status / where are we | 5-line summary |
| refresh knowledge / sync | Full context re-read |
| /yaaw-<skill> | Invoke any skill directly |
Repo Context Scaffold
- yaaw init prepares the current repository
- Creates committed context/ memory for repo facts, discoveries, plans, and work logs
- Generates agent router files for the selected assistant
- Stores optional yaaw_workspace_root for related repositories
Skill Overrides
# context/skill-overrides.yaml
overrides:
yaaw-build:
build_tool: "dotnet build"
yaaw-work:
worktrees: false
yaaw-caveman:
default: true
- Customize behavior without forking
- Safety gates CANNOT be overridden
Cross-Repo Coordination
- yaaw_workspace_root in config.yaml points to parent folder
- Agent discovers sibling repos dynamically
- Supports:
- Dependency version bumps
- Pipeline template impact analysis
- Dependency mapping
- Never fails if a sibling repo is missing
External Knowledge Boundaries
Built-in guardrails for project-specific dependencies, APIs, and conventions where hallucination risk is highest:
- Internal APIs, custom packages, and deployment rules
- Repo-specific build tools, test conventions, and release gates
- Agent states uncertainty rather than guessing
- Never applies generic advice when repo-specific context says otherwise
Caveman Mode
- 50-70% fewer tokens in responses
- 3-6 word sentences
- Code output stays readable — only chat is terse
- Activated via:
- /yaaw-caveman
- config flag
- skill override
Daily Workflow Demo
- Open terminal in project repo
- Agent reads context automatically (silent setup)
- Say "resume" → picks up where you left off
- Say "/yaaw-discover how does this integration work?" → investigates
- New session: "/yaaw-plan" → creates PRD with implementation units
- Approve plan → new session "/yaaw-work" executes with TDD + yaaw-build per unit
- New session: "/yaaw-review" for risk check + approval
- New session: "/yaaw-commit" only after all gates pass → done
- Model policy: pick best-fit model per stage and utility skill; GPT-5.5 for heavy reasoning, codex-first for build/code execution
Updating
yaaw update
- Pulls latest skills from git
- Refreshes router in current repo
- All devs get same skills on next update
- No manual config needed
Why YAAW?
- Yet another agentic workflow because every team already has one — this one is explicit, reusable, and versioned.
- Reusable skills give agents a shared operating model.
- Structured conventions make human review predictable.
- Compound memory ensures no discovery or finding goes to waste.
- Pronounced yaw, rhyming with saw.