Why Wai?

wai — pronounced like “why” — is a workflow manager for AI-driven development. It can also be read as “way”, and that’s intentional: the tool’s focus is capturing why it was built that way.

The Problem

You come back Monday morning. The code is there — merged, deployed, working. But nobody remembers why approach X was chosen over Y. The research that ruled out three alternatives? Lost in a chat thread. The design constraint that shaped the API? Buried in a meeting note nobody bookmarked. The trade-off that made the architecture click? It lived in someone’s head, and they moved on.

This happens constantly in AI-assisted development, where code is produced fast but reasoning evaporates even faster:

• Context resets every session. AI agents start fresh each time. The research you did yesterday is gone unless you manually re-explain it.
• Decisions outlive their rationale. Code survives; the thinking behind it doesn’t. Six months later, nobody can explain why the system works the way it does.
• Handoffs lose signal. Switching between agents, or between human and agent, means re-discovering context that already existed.
• Config drift. AI instructions (CLAUDE.md, .cursorrules) fall out of sync across tools, so agents get inconsistent guidance.

How Wai Helps

Wai addresses each of these pain points directly:

At a Glance

wai bridges the gap between your thoughts and your codebase:

• 🧠 Capture — Record research, designs, and decisions as you work.
• 🗺️ Context — Advance projects through phases (Research → Design → Plan → Implement → Review → Archive).
• 🔄 Sync — Keep AI instructions automatically aligned from one source of truth.
• 📦 Handoff — Generate high-context session summaries for yourself or other agents.

How It Fits Together

┌──────────────────────────────────────────────────────────┐
│                        .wai/                             │
│                                                          │
│  ┌─ Projects ──┐  ┌─ Areas ──┐  ┌─ Resources ─────────┐ │
│  │ my-feature/ │  │ ops/     │  │ agent-config/        │ │
│  │  research/  │  │ docs/    │  │   skills/ rules/     │ │
│  │  designs/   │  └──────────┘  │ reflections/         │ │
│  │  plans/     │                │ pipelines/           │ │
│  │  handoffs/  │  ┌─ Archives ┐ └──────────────────────┘ │
│  └─────────────┘  │ old-proj/ │                          │
│                   └───────────┘                          │
├──────────────────────────────────────────────────────────┤
│  Phases: research → design → plan → implement → review   │
│  Plugins: git · beads · openspec · custom                │
│  Sync: .wai/resources/ ──→ .claude/ .cursorrules etc.    │
└──────────────────────────────────────────────────────────┘

Key Capabilities

• PARA Method Storage: Logical organization into Projects, Areas, Resources, and Archives.
• Phase Tracking: Structured workflow from initial research to final archive.
• Sync Engine: Single source of truth for agent configurations across multiple tools.
• Plugin System: Seamless integration with git, beads, openspec, and more.
• Reasoning Oracle: Ask natural language “why” questions about your codebase with wai why.

Where to Go Next

Depending on your role, different parts of the docs will be most useful:

• 👤 Adopting wai in your own repo? Start with the Quick Start, then read How to Adopt Wai for a step-by-step guide.
• 🔧 Contributing to wai itself? This repo dogfoods wai — it uses wai, beads, and openspec to manage its own development. See Development and Architecture, and read AGENTS.md for the session workflow.
• 🤖 AI assistant? Follow the instructions in AGENTS.md at the repo root. Key commands: wai prime (session start), wai close (session end), bd ready (find work).

Design Principles

• 🛣️ Desire Path Alignment — Pave the cowpaths; make common workflows shortest. wai status suggests the next command based on your current phase — if you’re in research, it nudges you toward wai add research; when research is captured, it suggests advancing to design.

• 🩹 Self-Healing Errors — Errors suggest fixes, not just report problems. wai doctor --fix auto-repairs common workspace issues. Typos in commands get “Did you mean?” suggestions. Error messages include the exact command to fix the problem.

• 🌊 Progressive Disclosure — Simple by default, powerful when needed. wai init asks nothing beyond a project name. -v shows more detail, -vv reveals internals, -vvv shows everything. Beginners see clean output; power users get full diagnostics.

• 💡 Context-Aware — Offer smart next steps based on your current project state. Wai auto-detects your toolchain (git, beads, openspec) by scanning for workspace markers and adapts its suggestions accordingly — no configuration required.

A note on authorship

All the code in this repository was generated by a large language model. This is not a confession, nor an apology. It’s a fact, like the one that says water boils at a hundred degrees at sea level: neutral, technical, and with consequences one discovers later.

What the human did is what tends to happen before and after things come into existence: thinking. Reviewing requirements, arguing about edge cases, understanding what needs to be built and why, deciding how the system should behave when reality —which is capricious and does not read documentation— confronts it with situations nobody anticipated. The hours of planning, of design, of reading specifications until exhaustion dissolves the boundary between understanding and hallucination.

The LLM writes. The human knows what it should say.

There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is for, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.

Leer en español

Installation

The easiest way to install wai is using a package manager.

Homebrew (macOS & Linux)

brew tap charly-vibes/charly
brew install wai

Scoop (Windows)

scoop bucket add charly https://github.com/charly-vibes/scoop-charly.git
scoop install wai

From Binary (All Platforms)

Download the latest pre-compiled binary for your architecture from the GitHub Releases page.

1. Unpack the archive.
2. Move the wai binary to a directory in your PATH (e.g., /usr/local/bin or C:\Windows\System32).

From Source (Rust Developers)

Requires Rust (stable toolchain).

cargo install --path .

This installs the wai binary to ~/.cargo/bin/.

⚠️ WARNING: Ensure ~/.cargo/bin/ is in your PATH and has precedence. If you’ve previously installed wai via a package manager, the cargo version might be shadowed.

Verify Installation

which wai        # Check which binary is being used
wai --version    # Check version
wai --help       # Check help

Common Installation Issues

“wai: command not found”

Problem: The directory containing the wai binary is not in your shell’s PATH.

Solution (macOS/Linux): Add this to your shell profile (.bashrc, .zshrc, or .profile):

export PATH="$HOME/.cargo/bin:$PATH"

Solution (Windows): Add %USERPROFILE%\.cargo\bin to your User PATH environment variable.

Quick Start

Get up and running with wai in 5 minutes.

1. Run the Interactive Tutorial

The best way to learn is by doing. Run:

wai tutorial

This interactive guide covers the PARA method, project phases, and basic commands in a safe sandbox.

2. Initialize Your Workspace

Navigate to your project directory and initialize:

wai init

This creates a .wai/ directory — the single source of truth for all reasoning and workflow state in this repository. Everything wai tracks lives here: artifacts, configs, plugin definitions, and project metadata. It’s designed to be committed alongside your code.

3. Create a Project

In wai, a “Project” is an active work item with a specific goal. Create your first one:

wai new project my-feature

Projects use phases instead of jumping straight to code. This forces the research and design reasoning to exist before implementation, so when you or an agent revisits the project later, the why is already captured — not lost in a chat thread.

4. Capture Research

Projects start in the Research phase. Record your initial thoughts or findings:

wai add research "Evaluated options A and B. Choosing A for performance."

This creates a dated Markdown artifact in .wai/projects/my-feature/research/. The artifact persists across sessions — unlike chat history, it won’t disappear when an agent’s context resets.

5. Advance Through Phases

As your work progresses, advance the project’s phase:

# Advance: Research → Design
wai phase next

# Add a design artifact
wai add design "New API will use standard REST patterns."

Phases (research → design → plan → implement → review → archive) guide what kind of work and artifacts are expected at each stage. They’re flexible — skip forward or go back as needed.

6. Check Your Progress

Get a context-aware overview of your workspace:

wai status

Status is the context-aware next-step command. It shows active projects, their current phases, plugin context (git status, open issues), and smart suggestions for what to do next based on your current state. It’s the first thing to run at the start of any session.

Next Steps

Now that you’ve got the basics down, explore the more powerful features of wai:

• Commands Reference — Comprehensive list of all commands and flags.
• PARA Method — Learn how wai organizes your work.
• Project Phases — Master the workflow from Research to Archive.
• Sessions — The prime→close lifecycle for session continuity.
• Agent Config Sync — Keep your AI tools in sync.

Troubleshooting

If you run into issues, check the Troubleshooting guide or run:

wai doctor  # Check workspace health

Commands

Complete CLI reference for wai.

Wai provides a comprehensive set of commands for managing projects, artifacts, phases, and agent configurations.

Tip: Run wai --help for a quick overview, or wai <command> --help for detailed help on any command.

Global Flags

Available for all commands:

Safe mode

--safe prevents all write operations. Commands that modify state — add, sync, move, pipeline start/next/init/approve/lock, phase next/back/set, and import — will exit with an error. Read-only commands like status, search, doctor, pipeline verify, and pipeline current work normally.

Workspace & Initialization

Commands for managing the wai workspace and checking repo hygiene.

Choosing the Right Tool

• Use wai doctor when your .wai/ directory is missing, a project phase is stuck, or a sync command is failing.
• Use wai way when you want to improve your overall repository for AI friendliness (e.g., adding CLAUDE.md, .editorconfig, or SKILL.md files).

Projects & Artifacts

Manage PARA items (Projects, Areas, Resources, Archives) and their associated artifacts.

Items & Phases

Available phases: research, design, plan, implement, review, archive

Adding Artifacts

Choosing an Artifact Type

Wai encourages capturing the right kind of documentation at each stage:

• Research (wai add research) — Use for gathering information, exploring problem spaces, and evaluating options.
  • Example: “Evaluated two DB engines; chose PostgreSQL for its JSONB support.”
• Design (wai add design) — Use for making architectural decisions and defining system structure.
  • Example: “Proposed microservices architecture with EventBridge for communication.”
• Plan (wai add plan) — Use for breaking down implementation into specific, actionable steps.
  • Example: “Step 1: Scaffold auth service. Step 2: Implement JWT middleware.”
• Review (wai add review) — Use for recording validation results against an existing artifact.
  • Example: wai add review --reviews 2026-04-15-findings.md --verdict pass --severity "critical:0,high:1"
  • Requires --reviews <filename> to specify the target artifact.
  • Optional: --verdict (pass/fail/needs-work), --severity (level:count pairs), --produced_by (skill name).

Searching & Timeline

Agent Configuration

Manage how AI agents interact with your project through skills, rules, and context.

⚠️ WARNING: wai sync is destructive to your target files. It will overwrite manual changes in .cursorrules, .claude/config.json, etc., with the sources from your .wai/ directory.

AI-Driven Workflows

Advanced reasoning, session management, and automated pipelines.

Reasoning & Reflection

Session Management

Pipelines

Plugins

Doctor Checks

wai doctor runs the following checks. Use --fix to auto-repair where possible.

Examples

Basic Workflow

# Initialize and create project
wai init
wai new project my-feature

# Add artifacts
wai add research "Evaluated options A and B, chose A for performance"
wai phase next
wai add design "Architecture uses microservices pattern"

Search and Timeline

# Search with filters
wai search "authentication" --type research
wai search "api.*error" --regex -n 10

# View project history
wai timeline my-feature
wai timeline my-feature --from 2026-02-01 --to 2026-02-15

JSON Output for Automation

# Get structured data
wai status --json | jq '.projects[] | .name'
wai search "config" --json | jq '.results[].path'
wai plugin list --json
wai way --json | jq '.summary.pass'

Troubleshooting

Common issues and solutions for wai.

Commands Not Working

“wai: command not found”

Problem: Wai is not in your PATH after installation.

Solution:

# Check if cargo bin is in PATH
echo $PATH | grep cargo

# If not, add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/.cargo/bin:$PATH"

# Reload shell
source ~/.bashrc  # or ~/.zshrc

“Project not found” or “Not initialized”

Problem: Running wai commands outside of an initialized directory.

Solution:

# Check if you're in a wai workspace
ls -la .wai/

# If not, initialize or navigate to the correct directory
wai init
# or
cd /path/to/your/wai/workspace

Error example:

Error: wai::error::not_initialized
  ╭─[command]
  │ wai status
  ╰────
  help: Run 'wai init' to initialize wai in this directory

Sync Issues

⚠️ WARNING: wai sync is destructive to your target files (e.g., .cursorrules, .claude/config.json). It will overwrite any manual changes in these files with the versions from your .wai/resources/agent-config/ source directory.

Sync conflicts - target file manually edited

Problem: You edited a synced file directly and wai sync overwrote your changes, or you want to keep manual changes before syncing.

Solution:

1. Always edit source files, not targets. Use wai config list to find sources.
2. If you’ve already edited the target, back up your changes before running wai sync.
3. Use wai sync --status to see what will be changed before applying.

# Recommended workflow:
# 1. Check status
wai sync --status

# 2. Edit the source file correctly
wai config edit rules/my-rule.md

# 3. Apply sync
wai sync

Symlinks not working on Windows

Problem: Symlink strategy fails on Windows.

Solution: Wai automatically falls back to file copies on Windows. If you see errors:

# Check sync status
wai sync --status

# Run doctor to diagnose
wai doctor

# Try auto-fix
wai doctor --fix

Alternatively, switch to inline or reference strategy in .projections.yml.

“Permission denied” during sync

Problem: Wai can’t write to target directory.

Solution:

# Check target directory permissions
ls -ld .claude/

# Fix permissions
chmod u+w .claude/

# Or run sync with appropriate permissions
sudo wai sync  # Last resort, not recommended

Plugin Issues

Plugin not detected

Problem: Plugin shows as “not detected” in wai plugin list.

Solution:

# Check if detector file/directory exists
ls -la .beads/    # for beads
ls -la .git/      # for git
ls -la openspec/  # for openspec

# Install the plugin tool
cargo install beads  # or appropriate installation

# Verify detection
wai plugin list

Custom plugin not loading

Problem: TOML plugin in .wai/plugins/ not appearing.

Solution:

# Check TOML syntax
cat .wai/plugins/my-plugin.toml

# Verify file extension (.toml)
ls .wai/plugins/

# Check for TOML errors
wai doctor

# Example valid plugin:
cat > .wai/plugins/example.toml << 'EOF'
name = "example"
description = "Example plugin"

[detector]
type = "directory"
path = ".example"

[[commands]]
name = "status"
description = "Show status"
passthrough = "example status"
read_only = true
EOF

Plugin command fails

Problem: wai <plugin> <command> returns an error.

Solution:

# Verify plugin tool is installed and in PATH
which beads
which mytool

# Test command directly
beads list
mytool status

# Check plugin definition
wai plugin list --json | jq '.plugins[] | select(.name=="myplugin")'

Search & Timeline Issues

Search returns no results

Problem: Can’t find artifacts you know exist.

Solution:

# Check if you're searching the right project
wai search "query" --in project-name

# Try without filters
wai search "query"

# Use case-insensitive search (regex mode)
wai search "(?i)query" --regex

# Verify artifacts exist
wai timeline my-project
wai show my-project

Timeline shows wrong dates

Problem: Artifacts appear in unexpected order.

Solution: Timeline is sorted by filename date (YYYY-MM-DD prefix). Artifacts are created with the current date by default.

# Check actual filenames
ls .wai/projects/my-project/research/

# Files are named: YYYY-MM-DD-slug.md
# Timeline sorts by this date, not file modification time

Doctor Command Issues

Doctor runs 16 checks covering directory structure, configuration, plugins, agent configs, pipelines, artifact locks, and more. See the full list in Commands — Doctor Checks.

Doctor reports issues but –fix doesn’t work

Problem: wai doctor --fix doesn’t repair all issues.

Solution: Some issues require manual intervention:

# Run doctor to see all issues
wai doctor

# Check which issues can't be auto-fixed
# Doctor will show suggestions for manual fixes

# Common manual fixes:
# 1. Corrupted config - restore from backup or re-init
# 2. Missing directories - create manually or re-init
# 3. Permission issues - fix with chmod/chown

Doctor false positives

Problem: Doctor reports issues that aren’t actually problems.

Solution:

# Check specific validation
wai doctor --json | jq .

# Some "warnings" are informational
# Only "error" severity items need fixing

# If you believe it's a false positive, file an issue:
# https://github.com/charly-vibes/wai/issues

Artifact Integrity Issues

Locked artifact verification fails

Problem: wai pipeline verify or wai doctor reports hash mismatches.

Solution: A mismatch means a locked artifact was modified after locking. This can happen if you edited it directly instead of creating an addendum.

# See which artifacts failed
wai pipeline verify

# If the edit was intentional, create an addendum instead:
# 1. Restore the original (git checkout the file)
git checkout -- .wai/projects/my-project/research/2026-04-15-findings.md

# 2. Record corrections as an addendum
wai add research --corrects=.wai/projects/my-project/research/2026-04-15-findings.md "corrected details"

# 3. Verify again
wai pipeline verify

If you need to re-lock after a legitimate change, delete the .lock sidecar and run wai pipeline lock again.

“artifact missing” in verify output

Problem: A .lock file references an artifact that no longer exists.

Solution: The artifact was deleted after locking. Either restore it from git history or remove the orphaned .lock file:

# Find orphaned lock files
wai pipeline verify

# Restore from git
git checkout -- <path-to-artifact>

# Or remove the orphaned lock
rm <path-to-artifact>.lock

Phase Management Issues

Can’t advance to next phase

Problem: wai phase next doesn’t work or gives unexpected results.

Solution:

# Check current phase
wai phase show

# Phases are: research → design → plan → implement → review → archive
# Can't advance past archive

# If stuck, set phase directly
wai phase set implement

# Check phase history
wai phase show  # Shows all transitions

Phase history looks wrong

Problem: Phase history shows unexpected transitions.

Solution: Phase history is stored in .wai/projects/<name>/.state. This file tracks all transitions with timestamps.

# View state file
cat .wai/projects/my-project/.state

# If corrupted, you can manually edit (advanced)
# Or reset to a phase:
wai phase set research  # Starts fresh from research

Artifact Issues

Tags not working

Problem: Tags don’t appear or can’t search by tags.

Solution: Tags are stored in YAML frontmatter for research artifacts:

# Add tags correctly (comma-separated, no spaces around commas)
wai add research "Finding" --tags "api,security,auth"

# NOT: --tags "api, security, auth"  # Extra spaces cause issues

# Check frontmatter
head -10 .wai/projects/my-project/research/*.md

# Should see:
# ---
# tags: [api, security, auth]
# ---

Can’t import file

Problem: wai add research --file path.md fails.

Solution:

# Check file exists and is readable
ls -la path.md
cat path.md

# Use absolute or relative path
wai add research --file ./notes/research.md
wai add research --file /full/path/to/research.md

# Check file isn't binary
file notes/research.md  # Should say "text"

JSON Output Issues

JSON output malformed

Problem: --json flag produces invalid JSON.

Solution:

# Ensure no extra output
wai status --json --quiet

# Check for errors on stderr
wai status --json 2>&1 | jq .

# Validate JSON
wai status --json | jq empty

Can’t parse JSON in scripts

Problem: Automation scripts fail to parse wai JSON output.

Solution:

# Capture only stdout
wai status --json 2>/dev/null | jq .

# Handle errors separately
if ! output=$(wai status --json 2>&1); then
  echo "Error: $output" >&2
  exit 1
fi
echo "$output" | jq .

Performance Issues

Commands are slow

Problem: Wai commands take a long time to execute.

Solution:

# Check project size
du -sh .wai/

# Large artifact counts can slow search/timeline
find .wai/projects -name "*.md" | wc -l

# Use filters to limit scope
wai search "query" --in specific-project -n 10
wai timeline project --from 2026-02-01

# For very large projects, consider archiving old work
wai move old-project archives

Getting Help

Where to find more help

Resources:

• Built-in help: wai <command> --help
• Verbose help: wai --help -v (shows advanced options)
• Status check: wai doctor (diagnoses workspace issues)
• GitHub Issues: https://github.com/charly-vibes/wai/issues
• Documentation: Check docs/ directory

Filing a bug report

Include:

1. Wai version: wai --version
2. Operating system: uname -a
3. Command that failed: Full command with flags
4. Error message: Complete error output
5. Doctor output: wai doctor

# Create comprehensive debug report
{
  echo "=== Version ==="
  wai --version

  echo -e "\n=== System ==="
  uname -a

  echo -e "\n=== Doctor ==="
  wai doctor

  echo -e "\n=== Config ==="
  cat .wai/config.toml
} > wai-debug-report.txt

Then attach wai-debug-report.txt to your issue.

PARA Method

Why PARA? Without structure, project artifacts end up scattered across flat directories, wikis, Slack threads, and local notes. Finding that design decision from three weeks ago becomes an archaeological dig. PARA gives every artifact a clear home based on its lifecycle stage — active work goes in Projects, ongoing responsibilities in Areas, reference material in Resources, and completed work in Archives. You always know where to look.

Wai organizes artifacts using the PARA method — a system for organizing digital information into four categories:

.wai/
├── projects/          ← Active work with a goal and phases
│   ├── auth-feature/     research/ designs/ plans/ handoffs/
│   └── api-redesign/     research/ designs/ plans/ handoffs/
├── areas/             ← Ongoing responsibilities (no end date)
│   └── security/
├── resources/         ← Reference material and reusable assets
│   ├── agent-config/     skills/ rules/ context/
│   ├── reflections/
│   └── pipelines/
└── archives/          ← Completed items (searchable, hidden from status)
    └── old-feature/

Projects

Active work with a defined goal and deadline. Each project has its own directory under .wai/projects/ containing research notes, plans, designs, and handoff documents.

.wai/projects/my-app/
├── .state           # Phase state machine (YAML)
├── research/        # Date-prefixed research notes
├── plans/           # Date-prefixed plan documents
├── designs/         # Date-prefixed design documents
└── handoffs/        # Date-prefixed handoff documents

Areas

Ongoing areas of responsibility with no end date. These live under .wai/areas/.

Resources

Reference material and reusable assets. Stored under .wai/resources/:

.wai/resources/
├── agent-config/    # Single source of truth for agent configs
│   ├── skills/
│   ├── rules/
│   ├── context/
│   └── .projections.yml
├── templates/
└── patterns/

Archives

Completed or inactive items moved here for reference. Located at .wai/archives/.

Moving between categories

Use wai move to reclassify items as their status changes:

wai move my-app archives    # Archive a completed project

Project Phases

Why phases? When teams skip straight to code, they build the wrong thing — or the right thing the wrong way. Decisions get made implicitly, trade-offs go unrecorded, and the first sign of trouble triggers a rewrite. Formalizing research → design → plan → implement → review → archive doesn’t slow you down; it forces the reasoning to exist before the code, so when you revisit the project later, the why is already captured.

Projects in wai progress through six phases:

          ┌──────────────────────────────────────────┐
          │                                          │
          ▼                                          │
  ┌──────────┐   ┌────────┐   ┌──────┐   ┌─────────────┐   ┌────────┐   ┌─────────┐
  │ research │──▶│ design │──▶│ plan │──▶│ implement   │──▶│ review │──▶│ archive │
  └──────────┘   └────────┘   └──────┘   └─────────────┘   └────────┘   └─────────┘
       ▲              ▲                        │
       └──────────────┴────────────────────────┘
                  (back-transitions allowed)

Phases

1. Research — Gather information, explore the problem space, understand constraints
2. Design — Define architecture, make key decisions, document trade-offs
3. Plan — Break work into tasks, define milestones, set priorities
4. Implement — Build the solution, write code, integrate components
5. Review — Validate the work, run tests, gather feedback
6. Archive — Complete the project, generate final handoff, move to archives

Managing phases

wai phase              # Show current phase
wai phase next         # Advance to next phase
wai phase back         # Return to previous phase
wai phase set design   # Jump to a specific phase

Flexibility

Transitions are flexible — skip forward or go back as needed. Phase history is tracked with timestamps so you can see how a project evolved over time.

Adding artifacts by phase

Each phase has associated artifact types. Wai encourages capturing the right kind of documentation at each stage:

• Research phase → wai add research "..."
• Design phase → wai add design "..."
• Plan phase → wai add plan "..."

Archive Phase vs. Category

The word “archive” is used in two ways in wai, and they serve different purposes:

1. The Archive Phase (wai phase set archive)

This is a status for a project. It indicates that the project is complete, all final handoffs are generated, and no further work is planned. It stays in its current PARA category (usually Projects).

Use when: A project is finished but you still want it to appear in wai status and your active workspace overview.

2. The Archives Category (wai move my-project archives)

This is a storage location. Moving an item to archives reclassifies it in the PARA system, moving its directory from .wai/projects/ to .wai/archives/.

Use when: You want to declutter your workspace. Archived items are hidden from default wai status views and most context suggestions, but remain fully searchable.

Recommended Workflow:

1. Set phase to archive when the work is done.
2. Generate a final handoff (wai close).
3. Move to the archives category when you no longer need it in your active projects list.

Sessions

Context is expensive. Every time an AI agent starts a new session, it begins with a blank slate — no memory of what was tried, what failed, or what decision was made and why. Humans face the same problem at smaller scale: you close your laptop Friday, and by Monday the thread of reasoning has frayed.

Wai’s session lifecycle exists to solve this: capture context at the end of a session, and restore it at the beginning of the next one.

The Prime → Work → Close Loop

A wai session follows a three-step loop:

┌─────────┐      ┌──────┐      ┌───────┐
│  prime   │ ───▶ │ work │ ───▶ │ close │
└─────────┘      └──────┘      └───────┘
     ▲                              │
     └──────────────────────────────┘

1. wai prime — Orient yourself. Prime reads the latest handoff, shows active projects and their phases, surfaces plugin context (git status, open issues), and suggests next steps. If a previous session was interrupted, it detects this automatically.

2. Work — Do your actual work: add artifacts, advance phases, write code. Wai stays out of the way.

3. wai close — Capture state. Close generates a handoff document summarizing the session, writes a .pending-resume signal, and shows what to do before ending (close issues, commit, push).

Resume Detection

When you run wai prime after a wai close, wai checks for a .pending-resume file. If one exists and is less than 12 hours old, prime enters ⚡ RESUMING mode:

• It reads the linked handoff document
• Extracts the ## Next Steps section
• Displays them prominently so you (or an agent) can pick up exactly where you left off

This is what makes session continuity work across agent boundaries — the next agent doesn’t need to rediscover context; it’s handed a precise resumption point.

What Goes Into a Handoff

A handoff document is a Markdown file stored in .wai/projects/<name>/handoffs/. It contains:

• Session summary — What was accomplished
• Current state — Active phase, open issues, uncommitted changes
• Plugin context — Git status, beads issue counts, and other plugin-contributed data (gathered via the on_handoff_generate hook)
• Next steps — Concrete actions for the next session
• Decisions made — Key choices and their rationale

wai close vs wai handoff create

Both generate handoff documents, but they serve different purposes:

Use wai close when you’re done working. Use wai handoff create when you need to hand context to someone else but aren’t stopping yet.

The Autonomous Loop

For AI agents running in autonomous mode, the session loop becomes a tight cycle:

1. wai prime — orient (detects ⚡ RESUMING if mid-task)
2. Work on one task
3. wai close — capture state
4. git commit and push
5. Clear context (e.g., /clear)

The next session starts with wai prime again, which shows RESUMING with exact next steps. This pattern keeps agents productive across context window boundaries without losing the thread.

Reasoning

Capturing artifacts — research notes, design decisions, plans — is the foundation. But artifacts alone don’t answer the questions that come up later: Why did we choose this approach? What patterns have emerged across sessions? What does this file’s history tell us?

Wai’s reasoning features bridge this gap with two LLM-powered commands that query and synthesize your captured knowledge.

wai why — The Reasoning Oracle

wai why answers natural-language questions about your project by combining your artifacts with git history and feeding them to an LLM.

How It Works

1. Context gathering — Wai collects relevant PARA artifacts (research, designs, plans) and recent git history, scoped to your query.
2. LLM query — The gathered context and your question are sent to the configured LLM backend.
3. Structured response — The answer comes back with a decision chain and references to the artifacts that informed it.

Query Types

You can ask wai why two kinds of questions:

# Ask a question about your project
wai why "Why did we choose TOML over YAML for config?"

# Ask about a specific file's history and purpose
wai why src/config.rs

Questions work best when they’re specific and tied to decisions your project has already made. The oracle is only as good as the artifacts you’ve captured — it queries what you recorded.

When It Shines

• Onboarding: A new contributor asks “why does the plugin system use auto-detection?” and gets an answer grounded in actual design artifacts, not guesses.
• Revisiting decisions: Six months later, you wonder why a particular architecture was chosen. The oracle traces it back through research and design notes.
• File archaeology: Pointing wai why at a file explains its role in the project based on commit history and related artifacts.

wai reflect — Project Synthesis

Where wai why answers specific questions, wai reflect steps back and synthesizes patterns across your entire project history.

How It Works

1. Context aggregation — Wai gathers conversation transcripts, handoff documents, and session history up to a character budget.
2. Pattern synthesis — An LLM distills the accumulated context into recurring patterns, conventions, and architectural notes.
3. Persistent output — The synthesis is written as a versioned Markdown file in .wai/resources/reflections/.
4. Instruction updates — Wai detects instruction files (CLAUDE.md, AGENTS.md) and updates them with the new reflection, so agents pick up the patterns automatically.

When to Run It

Run wai reflect approximately every 5 sessions, or whenever you feel the project has accumulated enough new context to be worth synthesizing. It’s not meant to run after every change — it’s a periodic distillation.

wai reflect

What It Produces

The output is a reflection file containing:

• Project conventions — Naming patterns, code style preferences, framework choices that emerged organically
• Architectural notes — How components relate, where boundaries are, what invariants matter
• Gotchas — Things that tripped you up and shouldn’t trip someone else

These reflections feed back into agent instructions via managed blocks, so the next agent session starts with accumulated project wisdom — not just the raw artifacts.

LLM Configuration

Both commands support multiple backends:

• Claude API — Uses the Anthropic REST API directly (requires ANTHROPIC_API_KEY)
• Claude CLI — Delegates to the claude binary
• Ollama — Local LLM for offline use

Wai auto-detects the available backend. No configuration is needed if you have one of these set up.

How They Build on Artifacts

Both wai why and wai reflect are only as useful as the artifacts you’ve captured. They don’t hallucinate project context — they query and synthesize what exists in your .wai/ directory and git history.

This creates a virtuous cycle:

1. You capture research, designs, and decisions with wai add
2. wai why makes that knowledge queryable on demand
3. wai reflect distills it into persistent patterns
4. Those patterns inform the next session via managed blocks
5. The next session captures more artifacts, and the cycle continues

Plugin System

Why plugins? Every team uses different tools — issue trackers, spec managers, version control. Building all of these into wai would make it opinionated and brittle. Instead, wai auto-detects what’s already in your workspace and integrates through a plugin architecture. You get seamless context (git status in handoffs, open issues in wai status) without wai prescribing your toolchain.

Wai auto-detects and integrates with external tools through a flexible plugin architecture.

Built-in Plugins

Beads

• Detection: .beads/ directory
• Description: Issue tracking with tasks, bugs, and dependencies
• Commands: list, show, ready (read-only)
• Hooks:
  • on_handoff_generate — Includes open issues in handoffs
  • on_status — Shows issue statistics

Example:

wai beads list        # Pass-through to beads plugin
wai beads ready       # Show issues ready to work on

Git

• Detection: .git/ directory
• Description: Version control integration
• Hooks:
  • on_handoff_generate — Includes git status
  • on_status — Shows recent commits

OpenSpec

• Detection: openspec/ directory
• Description: Specification and change management
• Integration: Status display shows active specs and change proposals with progress

Plugin Commands

Pass-through commands allow direct access to plugin functionality:

wai <plugin> <command> [args...]

Example:

wai beads list --status=open
wai beads show beads-123

Plugin Hooks

Plugins can inject context into wai workflows through hooks:

Available Hooks

Custom Plugins

Wai scans the .wai/plugins/ directory at your workspace root for any files with a .toml extension.

Example Plugin Definition

name = "my-tool"
description = "Custom tool integration"

[detector]
type = "directory"
path = ".mytool"   # Relative to workspace root

[[commands]]
name = "list"
description = "List items"
passthrough = "mytool list"
read_only = true

[[commands]]
name = "sync"
description = "Sync data"
passthrough = "mytool sync"
read_only = false

[hooks.on_status]
command = "mytool stats"
inject_as = "mytool_stats"

[hooks.on_handoff_generate]
command = "mytool status --format=summary"
inject_as = "mytool_context"

Detector Types

• directory — Detect by directory presence. The path attribute is relative to the workspace root.
• file — Detect by file presence. The path attribute is relative to the workspace root.
• command — Detect by command availability. The path (or command) attribute is the shell command to execute (must return exit code 0).

Note: For the command detector in TOML, use the path field to specify the command to run (e.g. path = "mytool --version").

Command Attributes

• name — Command name (e.g., list)
• description — Human-readable description
• command — Shell command to execute
• read_only — Whether command modifies state (respects --safe mode)

Managing Plugins

List All Plugins

wai plugin list

Shows:

• Plugin name and description
• Detection status (detected/not found)
• Available commands
• Configured hooks

Enable/Disable Plugins

wai plugin enable my-tool
wai plugin disable my-tool

Note: Built-in plugins cannot be disabled.

JSON Output

Get structured plugin information:

wai plugin list --json

Returns:

{
  "plugins": [
    {
      "name": "beads",
      "description": "Issue tracking",
      "detected": true,
      "commands": ["list", "show", "ready"],
      "hooks": ["on_status", "on_handoff_generate"]
    }
  ]
}

Safe Mode

Plugin commands that modify state are blocked in safe mode:

wai beads list --safe         # OK - read-only
wai my-tool sync --safe       # Blocked if not read_only

Plugin Troubleshooting

Plugin Not Detected

Symptom: wai plugin list shows plugin as “not detected”

Common Causes:

1. Detector file/directory missing

   # Check if detector path exists
   ls -la .beads/     # for beads plugin
   ls -la .git/       # for git plugin
   ls -la openspec/   # for openspec plugin
   

2. Plugin tool not installed

   # Verify tool is available
   which beads
   which mytool
   
   # Install if missing
   cargo install beads
   

3. Custom plugin TOML syntax error

   # Validate TOML
   cat .wai/plugins/my-plugin.toml
   
   # Check for common issues:
   # - Missing required fields (name, description, detector)
   # - Wrong detector type (must be: directory, file, or command)
   

Plugin Command Fails

Symptom: wai <plugin> <command> returns error

Debugging Steps:

# 1. Verify plugin is detected
wai plugin list | grep myplugin

# 2. Test command directly
mytool command args

# 3. Check command definition
wai plugin list --json | jq '.plugins[] | select(.name=="myplugin") | .commands'

# 4. Verify passthrough is in PATH
which mytool

# 5. Check for command output issues
mytool command 2>&1 | head

Custom Plugin Not Loading

Symptom: Custom plugin in .wai/plugins/ doesn’t appear

Checklist:

• ✅ File has .toml extension
• ✅ File is in .wai/plugins/ directory
• ✅ TOML syntax is valid
• ✅ Required fields present: name, description, detector
• ✅ Detector path exists (for directory/file detectors)

Example Valid Plugin:

name = "example-tool"
description = "Example tool integration"

[detector]
type = "directory"
path = ".example"

[[commands]]
name = "status"
description = "Show status"
passthrough = "example status"
read_only = true

[[commands]]
name = "sync"
description = "Sync data"
passthrough = "example sync"
read_only = false

[hooks.on_status]
command = "example stats"
inject_as = "example_stats"

Hook Output Not Showing

Symptom: Plugin hooks defined but output doesn’t appear in status/handoffs

Debugging:

# 1. Check if plugin is detected
wai plugin list | grep myplugin

# 2. Verify hook command runs successfully
example stats  # Run hook command directly

# 3. Check hook definition
wai plugin list --json | jq '.plugins[] | select(.name=="example") | .hooks'

# 4. Look for hook output in status
wai status -v  # Verbose mode shows more detail

# 5. Check JSON output for hook_outputs
wai status --json | jq '.hook_outputs'

Permission Errors

Symptom: “Permission denied” when running plugin commands

Solutions:

# 1. Check plugin tool permissions
ls -l $(which mytool)

# 2. Verify tool is executable
chmod +x $(which mytool)

# 3. For safe mode issues, check read_only flag
wai plugin list --json | jq '.plugins[] | select(.name=="myplugin") | .commands[] | {name, read_only}'

Detector Not Working

Symptom: Plugin should be detected but shows as “not detected”

Detector Types and Requirements:

Directory Detector:

[detector]
type = "directory"
path = ".mytool"  # Directory must exist at workspace root

Check: ls -la .mytool/

File Detector:

[detector]
type = "file"
path = "mytool.config"  # File must exist at workspace root

Check: ls -la mytool.config

Command Detector:

[detector]
type = "command"
path = "mytool --version"  # Command must exit 0 and be in PATH

Check: which mytool && mytool --version

Getting Help

If you can’t resolve plugin issues:

# Create debug report
{
  echo "=== Plugin List ==="
  wai plugin list

  echo -e "\n=== Plugin JSON ==="
  wai plugin list --json

  echo -e "\n=== Custom Plugins ==="
  ls -la .wai/plugins/

  echo -e "\n=== Doctor Check ==="
  wai doctor
} > plugin-debug.txt

File an issue at https://github.com/charly-vibes/wai/issues with plugin-debug.txt attached.

See Also

• Commands Reference - Plugin management commands
• Troubleshooting - Plugin-specific troubleshooting
• JSON Output - Plugin JSON schema

Pipelines

Why pipelines? Some tasks are too complex or error-prone for a single pass. When an AI agent tries to do research, validation, and synthesis all at once, errors compound — context drifts, assumptions go unchecked, and the final output is built on shaky foundations. Pipelines break these tasks into discrete steps with validation gates between them, so each step is verified before the next one begins.

Pipelines are ordered, multi-step workflows that guide you through a structured process. Each step provides a prompt with deliverables and instructions, and you advance through steps sequentially.

Pipelines are useful when a task is too large or too error-prone for a single pass — for example, research that spans many subtasks, or a process where intermediate validation prevents compounding errors. If your work fits naturally into wai’s project phases without extra structure, you probably don’t need a pipeline.

Prerequisite: an initialized wai workspace (wai init). See Quick Start.

Overview

wai pipeline list                                # List available pipelines
wai pipeline show <name>                         # View steps and gates
wai pipeline start <name> --topic="<objective>"  # Start a run
wai pipeline next                                # Mark current step done, move to next

Pipelines are defined as TOML files in .wai/resources/pipelines/. When you run wai init, built-in templates are installed into this directory. You can modify your local copy without affecting the built-in defaults.

Creating Custom Pipelines

Pipelines are TOML files with a simple structure:

[pipeline]
name = "my-workflow"
description = "What this pipeline does"

[pipeline.metadata]
when = "When to use this pipeline"
skills = ["skill-a", "skill-b"]    # Optional: skills used by steps

[[steps]]
id = "step-one"
prompt = """
{topic}: Instructions for this step.

Deliverables:
- What to produce

Record findings: `wai add research "..."`
Advance: `wai pipeline next`
"""

[[steps]]
id = "step-two"
prompt = """
{topic}: Instructions for this step.
"""

The {topic} placeholder is replaced with the --topic value when the run starts.

Place custom pipelines in .wai/resources/pipelines/ and run wai init --update to refresh the managed block in CLAUDE.md.

Pipeline Gates

Steps can optionally define gates — conditions that must be satisfied before advancing. Gates enforce validation at step boundaries and are checked when you run wai pipeline next.

Gate tiers

Gates evaluate in order. The first failure blocks advancement — wai pipeline next prints the failing gate and what’s missing, and blocks until the condition is satisfied.

Configuring gates in TOML

Gate sections go inside the [[steps]] entry they belong to. Here is a complete step with all four gate tiers:

[[steps]]
id = "generate-validate-accrue"
prompt = """
{topic}: Execute subtasks with intermediate validation.
...
"""

[steps.gate.structural]
min_artifacts = 1
types = ["research"]

[steps.gate.procedural]
require_review = true
review_verdict = "pass"
max_critical = 0
max_high = 0

[[steps.gate.oracles]]
name = "dimensional-analysis"
description = "Verify dimensional consistency"
timeout = 300

[steps.gate.approval]
required = true
message = "Review all accrued artifacts before advancing"

Oracle scripts

Oracles are user-written scripts that perform domain-specific checks:

• Location: .wai/resources/oracles/<name>.sh or .wai/resources/oracles/<name>.py
• Contract: receives the artifact path as an argument, exits 0 on pass, writes failure reason to stderr
• Timeout: default 30 seconds, configurable per oracle

Gate commands

wai pipeline gates <name>              # Show gate requirements per step
wai pipeline check                     # Dry-run gates without advancing
wai pipeline approve                   # Human approval for current step
wai pipeline validate <name>           # Validate pipeline TOML and gate config

Built-in: Scientific Research Pipeline

The scientific-research pipeline is designed for frontier-level theoretical or computational research where an LLM generates mathematical derivations, proofs, or data analysis across many subtasks and a human supervisor needs systematic validation.

It addresses three common failure modes in AI-assisted research:

• Context drift — the research gradually shifts away from the original problem
• Sycophancy — the model confirms what it thinks you want rather than what’s true
• Hallucinated data smoothing — gaps are filled with plausible but unverified claims

Starting a run

wai pipeline start scientific-research --topic="Your research objective here"

This creates a pipeline run and places you at step 1. Each step provides a detailed prompt explaining what to do, what deliverables to produce, and how to record them.

Steps

The pipeline has five framing steps (Describe, Diagnose, Delimit, Direction, Decompose), a core execution loop (Generate-Validate-Accrue), and two closing steps (Synthesize, Final Review).

Every step ends with recording artifacts and advancing:

wai add research "findings..."   # or design/plan as appropriate
wai pipeline next

1. Describe

Capture the research problem neutrally. Focus on observed symptoms, signals, metrics, boundary conditions, and known constraints. Do not propose solutions or hypotheses yet.

Deliverables: neutral problem statement, known constraints, data sources, success criteria.

2. Diagnose

Generate and test competing hypotheses — at least three. For each, state its predictions and identify confirming/refuting evidence. Use negative progress (ruling out false leads) rather than converging too early.

Deliverables: hypothesis map, evidence for/against each, eliminated paths.

3. Delimit

Define explicit boundaries and scope. This is the primary defense against context drift. Document what is in scope, what is explicitly out, constraints, and assumptions taken as given.

Deliverables: scope document (referenced throughout remaining steps).

4. Direction

Select the research approach using a decision matrix. Compare surviving hypotheses against feasibility, rigor, falsifiability, and compute cost. Include a null hypothesis baseline. Document what would cause you to revisit the decision.

Deliverables: decision matrix, selected approach with justification.

5. Decompose

Break the selected approach into a master task tree of discrete, independently verifiable subtasks. Each subtask gets a unique ID, input dependencies, expected output format, and validation criteria.

Deliverables: task tree (created as beads issues with dependencies).

bd create --title="<subtask>" --description="<details>" --type=task
bd dep add <blocked> <blocker>
wai add plan "task decomposition..."

6. Generate-Validate-Accrue (core loop)

Execute each subtask from the task tree. For every subtask:

1. Generate — produce the derivation, code, analysis, or argument
2. Validate — run /ro5 (Rule of 5, a wai review skill) on the artifact:
   • Accuracy — verify facts, citations, mathematical correctness
   • Completeness — check for skipped steps, missing edge cases
   • Clarity — ensure unambiguous terminology and notation
   • Actionability — confirm output is usable by the next subtask
   • Integration — check consistency with all previously accrued artifacts
3. Accrue — if validation passes, commit the artifact:

   wai add research "<subtask findings>"
   bd close <subtask-id>
   

Critical rules:

• Do not skip validation. Do not accrue unvalidated artifacts.
• If a subtask contradicts a previously accrued artifact, halt and surface the contradiction for human review.
• Fix and re-validate before accruing if validation fails.

7. Synthesize

Assemble the final output from all accrued artifacts. Check for logical flow, notation consistency, gap detection, and whether boundary conditions from the delimit step are satisfied.

Deliverables: coherent final output (paper, report, derivation).

8. Final Review

Run /ro5 on the complete synthesized output. Verify:

• The result satisfies success criteria from step 1
• The scope document from step 3 was respected
• The decision matrix from step 4 is still valid
• All beads subtasks are closed

If critical issues are found, route back to step 6 for the specific subtask that introduced the error.

Visual overview

┌─────────┐   ┌───────────┐   ┌─────────┐   ┌───────────┐   ┌───────────┐
│ Describe │──▶│ Diagnose  │──▶│ Delimit │──▶│ Direction │──▶│ Decompose │
│          │   │           │   │         │   │           │   │           │
│ Problem  │   │ Hypotheses│   │ Scope   │   │ Decision  │   │ Task tree │
└─────────┘   └───────────┘   └─────────┘   └───────────┘   └─────┬─────┘
                                                                   │
                                                                   ▼
┌──────────────┐   ┌─────────────┐   ┌─────────────────────────────────┐
│ Final Review │◀──│ Synthesize  │◀──│ Generate → Validate → Accrue    │
│              │   │             │   │         (repeat per subtask)     │
│ Quality gate │   │ Assembly    │   └─────────────────────────────────┘
└──────────────┘   └─────────────┘

Artifact Locking

Steps can declare lock = true to freeze their artifacts with SHA-256 hashes when you advance past them. This prevents accidental modification of validated work — once a step’s artifacts are locked, any change will be caught by wai pipeline verify or wai doctor.

How it works

When a step with lock = true completes (via wai pipeline next), wai computes a SHA-256 hash of each artifact tagged with that step and writes a .lock sidecar file alongside it. The sidecar records the hash, run ID, step ID, and timestamp.

You can also lock manually at any time:

wai pipeline lock      # Lock current step's artifacts now

Verifying integrity

wai pipeline verify    # Check all locked artifacts across the workspace

Verify reports:

• Missing artifacts — a .lock file exists but the artifact was deleted
• Hash mismatches — an artifact was modified after locking

wai doctor also checks artifact lock integrity as part of its health checks.

Correcting locked artifacts

Locked artifacts should not be edited directly. Instead, create an addendum — a new artifact that references the original:

wai add research --corrects=<path-to-locked-artifact> "correction details"

This preserves the audit trail: the original artifact stays intact and the addendum records what changed and why.

Configuring lock in pipeline TOML

Add lock = true to any step definition:

[[steps]]
id = "synthesize"
lock = true
prompt = """
{topic}: Assemble findings into a coherent output.
"""

Command reference

See Also

• Project Phases — the phase system pipelines build on
• Plugin System — beads issue tracking used in task decomposition
• Commands Reference — full command documentation

Agent Config Sync

Why a single source of truth? When agent instructions live in multiple files (CLAUDE.md, .cursorrules, .gemini/), they inevitably drift apart. One tool gets the updated security rules, another doesn’t. Copy-pasting between configs is tedious and error-prone. Wai solves this by storing configs once and projecting them to each tool’s expected location — edit in one place, sync everywhere.

Wai maintains a single source of truth for agent configurations and syncs them to tool-specific locations using configurable projection strategies.

Directory Structure

Agent configs are stored in .wai/resources/agent-config/:

.wai/resources/agent-config/
├── .projections.yml          # Sync configuration
├── skills/                   # Agent skills
│   ├── code-review.md
│   └── commit.md
├── rules/                    # System rules
│   ├── security.md
│   └── style.md
└── context/                  # Context files
    └── project-context.md

Projection Strategies

Configure syncs in .wai/resources/agent-config/.projections.yml:

1. Symlink Strategy

Creates target directory with symlinks (or copies on Windows) to source files.

Note on Windows: Windows doesn’t support symlinks in all configurations (requires Developer Mode or admin privileges). Wai automatically falls back to file copies when symlinks aren’t available.

Use when: Tools expect a directory structure with individual files.

projections:
  - strategy: symlink
    sources:
      - skills/
    target: .claude/skills/

Result:

• .claude/skills/code-review.md → symlink to .wai/resources/agent-config/skills/code-review.md
• .claude/skills/commit.md → symlink to .wai/resources/agent-config/skills/commit.md

2. Inline Strategy

Concatenates multiple source files into a single target file.

Use when: Tools expect a single configuration file (e.g., .cursorrules).

projections:
  - strategy: inline
    sources:
      - rules/base.md
      - rules/security.md
      - rules/style.md
    target: .cursorrules

Result:

<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: .wai/resources/agent-config/rules/base.md -->

[content of base.md]

<!-- Source: .wai/resources/agent-config/rules/security.md -->

[content of security.md]

<!-- Source: .wai/resources/agent-config/rules/style.md -->

[content of style.md]

3. Reference Strategy

Creates a markdown file listing paths to source files.

Use when: Tools can follow references to external files.

projections:
  - strategy: reference
    sources:
      - context/
    target: .agents/context-refs.md

Result:

# Agent Context References

This file references agent context files managed by wai.

## Files

- .wai/resources/agent-config/context/project-context.md

Specialized Targets

Wai provides built-in specialized targets that handle complex tool-specific transformations automatically.

Claude Code (claude-code)

The claude-code target is a high-level projection that translates hierarchical skills into Claude Code custom slash commands.

Instead of manual file mapping, use the special target: claude-code:

projections:
  - target: claude-code

How it works:

1. Source Discovery: It automatically scans .wai/resources/agent-config/skills/ for hierarchical directories (e.g., skills/git/commit/SKILL.md).
2. Translation:
   • It translates the directory hierarchy into a human-readable skill name (e.g., git/commit → Git: Commit).
   • It updates the frontmatter of the destination file to match Claude Code’s expected format (including name, description, and category).
3. Destination: Files are synced to .claude/commands/<category>/<action>.md.
4. Smart Syncing: wai sync --status uses file modification times (mtime) to detect if Claude Code commands are out of date with your source skills.

Note: “Flat” skills (e.g., skills/my-skill/SKILL.md) are skipped by this target. Only hierarchical skills (e.g., skills/category/action/SKILL.md) are processed to ensure clean command grouping in Claude Code.

Configuration Format

Full .projections.yml example:

projections:
  # Symlink skills to Claude Code
  - strategy: symlink
    sources:
      - skills/
    target: .claude/skills/

  # Inline rules to Cursor
  - strategy: inline
    sources:
      - rules/base.md
      - rules/security.md
    target: .cursorrules

  # Reference context files
  - strategy: reference
    sources:
      - context/
    target: .gemini/context-refs.md

Commands

Check Sync Status

wai sync --status

Shows:

• Current projections
• Source files
• Target status (in sync / out of sync)
• Files that would be created/updated

Apply Sync

wai sync

Applies all configured projections:

• Creates/updates symlinks
• Regenerates inline files
• Updates reference files

Managing Configs

Add New Config

wai config add skill my-skill.md

Copies my-skill.md to .wai/resources/agent-config/skills/my-skill.md.

List Configs

wai config list

Shows all configs organized by type (skills, rules, context).

Edit Config

wai config edit skills/my-skill.md

Opens config in $EDITOR (or $VISUAL, falls back to vi).

Import Existing Configs

wai import .claude/
wai import .cursorrules

Imports existing tool configs into wai’s single source of truth.

Workflow

1. Add/Edit configs in .wai/resources/agent-config/
2. Check status: wai sync --status
3. Apply sync: wai sync
4. Verify: wai doctor

Doctor Checks

The wai doctor command validates:

• Projection configuration syntax
• Source files exist
• Target directories are writable
• Symlinks are valid
• Inline files match sources
• Reference files are current

Auto-fix mode can repair common issues:

wai doctor --fix

Conflict Resolution

Important: Wai always overwrites target files during sync. The source files in .wai/resources/agent-config/ are the single source of truth.

What Happens When You Edit Synced Files

If you manually edit a synced target file (e.g., .cursorrules, .claude/skills/my-skill.md):

1. Your changes will be overwritten the next time you run wai sync
2. No warning is given - wai assumes sources are authoritative

Best Practices

✅ DO:

• Edit files in .wai/resources/agent-config/
• Use wai config edit skills/my-skill.md
• Run wai sync --status before syncing to preview changes
• Keep sources under version control

❌ DON’T:

• Edit target files directly (.cursorrules, .claude/skills/, etc.)
• Manually create files in target directories
• Expect wai to merge changes from targets back to sources

Missing Source Files

If a source file listed in .projections.yml is missing:

1. Sync behavior: wai sync will skip the missing file and continue with the remaining sources. For inline strategies, the output file will be generated without the missing content.
2. Reporting: wai sync --status will not show a specific error, but the target may appear as “out of sync”.
3. Diagnosis: Run wai doctor to identify exactly which source files are missing from your configuration.

Recovering Manual Edits

If you accidentally edited a target file:

# Copy your changes to a backup
cp .cursorrules my-changes-backup.md

# Check what the source contains
cat .wai/resources/agent-config/rules/*.md

# Manually merge your changes into the source files
wai config edit rules/base.md

# Re-sync to apply
wai sync

Migration Workflow

When importing from existing tool configs:

# Import existing configs (one-time)
wai import .cursorrules
wai import .claude/

# From now on, edit only in .wai/resources/agent-config/
wai config edit rules/imported-rules.md

# Sync to propagate changes
wai sync

Benefits

• Single Source of Truth — Edit once, sync everywhere
• Version Control — All configs tracked in .wai/
• Consistency — Same configs across all tools
• Flexibility — Different strategies for different tools
• Auditability — Clear projection configuration
• No Conflicts — Unidirectional sync prevents merge conflicts

See Also

• Commands Reference - Config management commands
• Troubleshooting - Sync troubleshooting guide
• Quick Start - Getting started with config sync

Ubiquitous Language

Domain-driven design talks about a ubiquitous language — a shared vocabulary that developers and domain experts use consistently in code, conversations, and documentation. Without it, agents guess at terminology and hallucinate synonyms: is “order” the same as “purchase”? Does “customer” overlap with “user”? Is “shipment” the same as “delivery”?

Wai gives teams a first-class home for this vocabulary under .wai/resources/ubiquitous-language/.

The Directory Layout

.wai/resources/ubiquitous-language/
├── README.md              # navigation index (required)
├── shared.md              # cross-context terms (optional)
└── contexts/
    ├── orders.md
    ├── inventory.md
    └── billing.md

Three layers:

• README.md — a lightweight index that describes the tree, lists available bounded contexts (self-contained parts of the domain with their own consistent terminology, e.g. Orders, Billing), and tells agents how to navigate it. This is the only file agents read by default.
• shared.md — optional. Holds terms that are genuinely shared across multiple bounded contexts. Keep it short; most terms belong in a context file.
• contexts/*.md — one file per bounded context. Each file records the preferred term, a concise definition, discouraged synonyms or anti-terms, and related terms. Each bounded context should be a single .md file directly under contexts/. Subdirectories and non-Markdown files are not currently recognized by wai way.

Getting Started

Create the directory and a minimal index:

mkdir -p .wai/resources/ubiquitous-language/contexts

Then write README.md as a short navigation guide:

# Ubiquitous Language

This directory contains domain terminology for this project.

## Bounded Contexts

- [Orders](contexts/orders.md) — fulfillment, line items, cancellation
- [Inventory](contexts/inventory.md) — SKUs, stock levels, reservations

## Usage

Read this file first. Open only the context file(s) relevant to your task.

Add a bounded-context file when you encounter ambiguous or domain-specific terms:

# Orders Context

## Order

**Definition:** A customer's confirmed intent to purchase one or more items.

**Anti-terms:** Do not use "cart" or "basket" — those refer to the pre-checkout state, not a confirmed order.

**Related:** Line Item, Fulfillment, Cancellation

Run wai way after setup to confirm the tree is fully configured.

Progressive Disclosure

Agents work better when they load terminology on demand rather than dumping an entire glossary into context. The layout is designed for this:

1. Agent reads README.md to learn what contexts exist.
2. Agent opens only the bounded-context file(s) relevant to the current task.
3. Agent ignores unrelated context files entirely.

The managed block injection (see below) is what makes agents aware of this pattern — the directory layout alone is not enough. Running wai sync is the step that teaches agents to navigate it correctly.

This matters in large codebases with many domains — loading every term file wastes context and increases noise.

wai way Detection

wai way checks the state of your ubiquitous-language tree and surfaces it alongside other project health signals:

Run wai way to see the result alongside other project health checks.

Managed Block Injection

When wai sync regenerates your CLAUDE.md, AGENTS.md, or .wai/AGENTS.md managed blocks, it checks whether README.md exists. If it does, it injects a usage note:

## Ubiquitous Language

If `.wai/resources/ubiquitous-language/README.md` exists, read it first as the
navigation index, then open only the bounded-context files relevant to the task.
Avoid loading every terminology file unless the work truly spans multiple contexts.

Every agent reading your CLAUDE.md will automatically know where the vocabulary lives and how to use it without you having to explain it in each session prompt.

Maintenance Workflow

Use the ubiquitous-language skill template to scaffold a skill that keeps the tree up to date:

wai add skill update-terminology --template ubiquitous-language

The generated skill guides an agent to:

1. Search existing artifacts and code for domain terminology.
2. Identify the appropriate bounded context for each term.
3. Update README.md, shared.md, or the relevant contexts/*.md file.
4. Prefer incremental edits over rewriting the whole tree.

Run the skill whenever new domain concepts emerge or existing terms need clarification. Invoke it directly with wai skill run update-terminology or by referencing the generated SKILL.md in your agent prompt.

See Also

• wai way — project health check command that detects the ubiquitous-language tree state
• Managed Blocks — how wai sync injects guidance into CLAUDE.md and AGENTS.md
• wai add skill — scaffold skill templates including ubiquitous-language

Toolchain Synergy

Wai is designed to work alongside two companion tools — beads (issue tracking) and openspec (specification management). Each tool owns a distinct concern:

When to Use What

How They Integrate

The three tools are connected through wai’s plugin system:

• beads is detected automatically when .beads/ exists. Open issue counts appear in wai status, and wai handoff create includes issue context in handoff documents.
• openspec is detected when openspec/ exists. Active change proposals and their progress appear in wai status.
• Cross-references tie them together: beads tickets reference openspec tasks (e.g., add-why-command:7.1 in the description), and completing a beads ticket means checking the box in the openspec tasks.md.

Worked Example: Adding a Feature

Here’s how a ticket flows through all three tools:

# 1. Propose the change in openspec
openspec create add-search-filters
# Edit the spec: requirements, acceptance criteria, task breakdown

# 2. Create beads tickets for the implementation tasks
bd create --title="Add --tag flag to search" --description="add-search-filters:3.1"
bd create --title="Add --type flag to search" --description="add-search-filters:3.2"

# 3. Research the approach in wai
wai add research "Evaluated regex vs glob for tag matching — chose glob for simplicity"

# 4. Work the ticket
bd update wai-abc1 --status in_progress
wai add design "Tags stored in YAML frontmatter, filtered at search time"

# 5. Close the loop
bd close wai-abc1
# Check [x] for task 3.1 in openspec's tasks.md

What You Lose by Skipping One

• Without wai: Tasks get done, but nobody remembers why decisions were made. Six months later, the code is a black box.
• Without beads: Reasoning is captured, but there’s no task decomposition, no dependency tracking, and no way to find available work.
• Without openspec: Changes happen ad hoc — no requirements, no acceptance criteria, no validation that the system matches the spec.

Each tool is optional. Wai works fine alone. But together, they cover the full lifecycle from proposal to implementation to archival.

How to Adopt Wai in an Existing Repository

This guide walks through adding wai to a repository that already has code, history, and an established workflow.

Prerequisite: Install wai first — see the Installation page.

1. Initialize the Workspace

From your repository root:

wai init

This creates a .wai/ directory. Commit it — wai artifacts are designed to live alongside your code.

2. Create a Project for Your Current Work

If you’re actively working on something, create a project for it:

wai new project my-current-feature

If you have multiple workstreams, create one project per feature or initiative.

3. Capture What You Already Know

Don’t start from scratch — import the reasoning that already exists:

# Record decisions you've already made
wai add research "Chose PostgreSQL over SQLite for concurrent write support"
wai add design "REST API with versioned endpoints (/v1/, /v2/)"

# Import existing notes or docs
wai add research --file docs/architecture-notes.md

Set the phase to match where you actually are:

wai phase set implement    # if you're already writing code

4. Set Up Agent Config Sync (Optional)

If you use AI assistants (Claude Code, Cursor, etc.), consolidate your configs:

# Import existing configs into wai's single source of truth
wai import .cursorrules
wai import .claude/

# Check what was imported
wai config list

# Sync back to tool locations
wai sync

5. Start Using the Session Loop

From now on, use wai prime at the start of each session and wai close at the end:

# Beginning of session
wai prime                  # Shows status, phase, suggestions

# ... do your work, capture decisions as you go ...
wai add research "Discovered edge case with auth tokens"

# End of session
wai close                  # Creates handoff for next session

6. Check Your Setup

Verify everything is healthy:

wai doctor                 # Workspace health check
wai way                    # Repository best practices

What Not to Do

• Don’t try to backfill all history. Capture decisions going forward. The value compounds over time.
• Don’t skip phases. Even if you set the phase to implement, record the reasoning that got you there.
• Don’t forget to commit .wai/. It’s part of your repository.

JSON Output

All major wai commands support --json flag for machine-readable output, enabling integration with scripts, automation tools, and other software.

Usage

wai <command> --json

JSON output is written to stdout, errors to stderr. This allows you to separate data from errors:

# Capture JSON output only
wai status --json > status.json

# Capture errors only
wai status --json 2> errors.log

# Capture both separately
wai status --json > status.json 2> errors.log

# Pipe JSON directly to processing tools
wai status --json | jq '.projects[].name'

Supported Commands

Status

wai status --json

Output:

{
  "project_root": "/path/to/project",
  "projects": [
    {
      "name": "my-app",
      "phase": "implement",
      "path": ".wai/projects/my-app"
    }
  ],
  "plugins": [
    {
      "name": "beads",
      "detected": true,
      "description": "Issue tracking"
    },
    {
      "name": "git",
      "detected": true,
      "description": "Version control"
    }
  ],
  "hook_outputs": {
    "git_status": "M src/main.rs\n",
    "beads_stats": "Open: 5, Closed: 12"
  },
  "openspec": {
    "specs": ["cli-core", "plugin-system"],
    "changes": [
      {
        "name": "add-feature-x",
        "progress": 75
      }
    ]
  },
  "suggestions": [
    {
      "pattern": "ImplementPhaseActive",
      "suggestion": "Consider running tests",
      "command": "cargo test"
    }
  ]
}

Search

wai search "authentication" --json

Output:

{
  "query": "authentication",
  "results": [
    {
      "path": ".wai/projects/my-app/research/2026-02-15-auth-research.md",
      "type": "research",
      "project": "my-app",
      "line": 12,
      "context": [
        "Evaluated JWT vs session-based authentication.",
        "Chose JWT for stateless API design.",
        "Will store tokens in httpOnly cookies."
      ]
    }
  ]
}

Timeline

wai timeline my-app --json

Output:

{
  "project": "my-app",
  "entries": [
    {
      "date": "2026-02-15",
      "type": "research",
      "title": "auth-research",
      "path": ".wai/projects/my-app/research/2026-02-15-auth-research.md"
    },
    {
      "date": "2026-02-16",
      "type": "design",
      "title": "api-design",
      "path": ".wai/projects/my-app/designs/2026-02-16-api-design.md"
    }
  ]
}

Plugin List

wai plugin list --json

Output:

{
  "plugins": [
    {
      "name": "beads",
      "description": "Issue tracking",
      "detected": true,
      "commands": [
        {
          "name": "list",
          "description": "List issues",
          "read_only": true
        },
        {
          "name": "show",
          "description": "Show issue details",
          "read_only": true
        }
      ],
      "hooks": [
        {
          "type": "on_status",
          "command": "bd stats"
        },
        {
          "type": "on_handoff_generate",
          "command": "bd list --status=open"
        }
      ]
    }
  ]
}

Resource List

wai resource list skills --json

Output:

{
  "skills": [
    {
      "name": "code-review",
      "path": ".wai/resources/agent-config/skills/code-review.md"
    },
    {
      "name": "commit",
      "path": ".wai/resources/agent-config/skills/commit.md"
    }
  ]
}

Error Handling

Errors are returned as JSON when --json is used:

{
  "code": "wai::error::project_not_found",
  "message": "Project 'missing-app' not found",
  "help": "Use 'wai show' to list available projects",
  "details": null
}

JSON Schema Stability

Current Policy: JSON output schemas are considered stable within a major version.

• ✅ Safe: Adding new optional fields
• ✅ Safe: Adding new values to enums
• ❌ Breaking: Removing fields
• ❌ Breaking: Changing field types
• ❌ Breaking: Renaming fields

Recommendation: When writing automation scripts, handle unknown fields gracefully and validate expected fields exist.

Example resilient parsing:

# Good - checks for field existence
if jq -e '.projects[]? | select(.name == "my-app")' status.json; then
  echo "Project exists"
fi

# Good - provides defaults for missing fields
jq '.projects[]? | {name, phase: (.phase // "unknown")}' status.json

Processing with jq

Use jq for powerful JSON processing:

# Extract project names
wai status --json | jq '.projects[].name'

# Get all research artifacts
wai search ".*" --regex --type research --json | jq '.results[].path'

# Count plugins detected
wai plugin list --json | jq '[.plugins[] | select(.detected)] | length'

# Get recent timeline entries
wai timeline my-app --json | jq '.entries | .[-5:]'

# Check if sync is needed
wai sync --status --json | jq '.projections[] | select(.status != "in_sync")'

Automation Examples

CI/CD Integration

#!/bin/bash
# Check if handoff exists for current branch
BRANCH=$(git branch --show-current)
HANDOFFS=$(wai search "$BRANCH" --type handoff --json | jq -r '.results[].path')

if [ -z "$HANDOFFS" ]; then
  echo "No handoff found for branch $BRANCH"
  exit 1
fi

Slack Notifications

#!/bin/bash
# Send status to Slack
STATUS=$(wai status --json)
PROJECTS=$(echo "$STATUS" | jq -r '.projects[] | "\(.name): \(.phase)"' | tr '\n' ', ')

curl -X POST "$SLACK_WEBHOOK" \
  -H 'Content-Type: application/json' \
  -d "{\"text\":\"Project Status: $PROJECTS\"}"

Dashboard Generation

import json
import subprocess

# Get status
result = subprocess.run(['wai', 'status', '--json'], capture_output=True, text=True)
status = json.loads(result.stdout)

# Generate HTML dashboard
html = "<h1>Project Status</h1>"
for project in status['projects']:
    html += f"<div><strong>{project['name']}</strong>: {project['phase']}</div>"

print(html)

Non-Interactive Mode

Combine --json with --no-input for fully automated scripts:

wai status --json --no-input
wai search "query" --json --no-input

This prevents any interactive prompts that might block automation.

Safe Mode

Use --safe with --json for read-only automation:

wai status --json --safe

Ensures no modifications occur during automated queries.

See Also

• Commands Reference - Global flags documentation
• Troubleshooting - JSON troubleshooting
• Quick Start - Getting started with JSON

Workflow Detection

Wai automatically detects project patterns and provides context-aware suggestions based on your current state.

How It Works

When you run wai status, wai analyzes:

• Current project phase
• Number and type of artifacts
• Plugin state (git status, open issues, etc.)
• Recent activity

Based on this analysis, it detects workflow patterns and suggests relevant next steps.

Detected Patterns

NewProject

Condition: Project exists but has no artifacts yet, in research phase.

Suggestions:

• Add initial research with wai add research "..."
• Import existing research with wai add research --file notes.md
• Run tutorial for guidance: wai tutorial

Example:

$ wai status
Project: my-app
Phase: research
Artifacts: 0

Pattern: NewProject
Suggestions:
  - Start gathering research: wai add research "Initial findings"
  - Import existing notes: wai add research --file notes.md

ResearchPhaseMinimal

Condition: In research phase with few (≤1) research artifacts.

Suggestions:

• Continue gathering information
• Add more research artifacts
• Consider when you have enough to move to design

Example:

$ wai status
Project: my-app
Phase: research
Research artifacts: 1

Pattern: ResearchPhaseMinimal
Suggestions:
  - Add more research: wai add research "Additional findings"
  - When ready, advance: wai phase next

ReadyToImplement

Condition: In plan or design phase with design documents created.

Suggestions:

• Move to implement phase
• Review designs before starting
• Set up development environment

Example:

$ wai status
Project: my-app
Phase: design
Design artifacts: 2
Plan artifacts: 1

Pattern: ReadyToImplement
Suggestions:
  - Ready to implement: wai phase next
  - Review designs: wai search "design" --in my-app
  - Create handoff: wai handoff create my-app

ImplementPhaseActive

Condition: Currently in implement phase.

Suggestions:

• Run tests regularly
• Document implementation decisions
• Consider moving to review when done

Example:

$ wai status
Project: my-app
Phase: implement

Pattern: ImplementPhaseActive
Suggestions:
  - Run tests: cargo test
  - Document decisions: wai add design "Implementation notes"
  - When done, advance: wai phase next

Context-Aware Commands

Suggestions include specific commands tailored to your project:

$ wai status
Project: api-server
Phase: implement
Plugin: beads (5 open issues)
Plugin: git (uncommitted changes)

Suggestions:
  - Review open issues: wai beads ready
  - Check git status: git status
  - Run tests: cargo test
  - Commit changes: git add -A && git commit

Plugin Integration

Workflow detection incorporates plugin context:

With beads plugin:

• Suggests reviewing open issues
• Recommends closing completed work
• Highlights blockers

With git plugin:

• Detects uncommitted changes
• Suggests creating commits
• Recommends pushing to remote

With openspec plugin:

• Shows active change proposals
• Displays implementation progress
• Suggests next specification steps

JSON Output

Get structured workflow information:

wai status --json | jq '.suggestions'

Output:

[
  {
    "pattern": "ReadyToImplement",
    "suggestion": "Move to implement phase",
    "command": "wai phase next"
  },
  {
    "pattern": "ReadyToImplement",
    "suggestion": "Review designs before implementing",
    "command": "wai search \"design\" --in my-app"
  }
]

Custom Patterns

While wai detects common patterns automatically, you can create custom workflow patterns through plugins.

Example Custom Pattern Plugin

name = "my-workflow"
description = "Custom workflow detector"

[hooks.on_status]
command = """
if [ -f .needs-review ]; then
  echo "Ready for review - run: make review"
fi
"""
inject_as = "custom_workflow"

Best Practices

Follow Suggestions

Wai’s suggestions are designed to guide you through proven workflows:

1. Research → gather information
2. Design → make decisions
3. Plan → break down work
4. Implement → build
5. Review → validate
6. Archive → document and close

Ignore When Needed

Suggestions are guidance, not rules. Feel free to:

• Skip phases that don’t apply
• Go back when you need more research
• Add artifacts in any phase
• Move forward at your own pace

Use with Plugins

Workflow detection works best with plugins:

• beads — Track concrete tasks alongside high-level workflow
• git — Keep version control in sync with project phases
• openspec — Align specifications with implementation phases

Disable Suggestions

To hide workflow suggestions:

wai status --quiet

Or suppress output:

wai status -q

See Also

• Project Phases - Understanding workflow stages
• Commands Reference - Status command details
• JSON Output - Programmatic access to suggestions

Implementation Status

At-a-glance view of wai’s implemented commands and their relation to formal change proposals tracked in openspec/.

Commands

For the authoritative list run wai --help.

Change Proposals

Formal changes are tracked in openspec/changes/. Each entry links a capability to the reasoning that motivated it. Status values come from openspec list; task counts from tasks.md in each change directory.

Run openspec list for the full list including archived changes.

Capability Specs

Stable capabilities have formal specs in openspec/specs/. These define the expected behavior independently of any single change.

Run openspec list --specs to see current specs.

Release History

Releases follow calendar versioning (vYYYY.M.N). See the GitHub Releases page for the full changelog.

Frequently Asked Questions

General

What is wai?

Wai (pronounced “why”) is a command-line workflow manager for AI-driven development. It helps you capture and organize the research, reasoning, and decisions behind your code - the “why” that’s often lost between sessions.

How is wai different from other documentation tools?

Most tools focus on what you built. Wai captures why you built it that way:

• Research findings and trade-offs
• Design decisions and alternatives considered
• Implementation plans and reasoning
• Session handoffs with context

Do I need to use git with wai?

No, wai works independently. However, wai integrates nicely with git through the plugin system, including git status in handoffs and status output.

Can I use wai with existing projects?

Yes! Run wai init in any directory to start using wai. You can import existing documentation with wai import or wai add research --file.

Usage

Which phase should I be in?

Phases are guidelines, not gates. Use what makes sense:

• Research - Exploring, learning, gathering information
• Design - Making architectural decisions
• Plan - Breaking down implementation steps
• Implement - Writing code
• Review - Testing, validating, refining
• Archive - Wrapping up, documenting outcomes

You can skip phases or go backward anytime.

How do I choose between projects, areas, and resources?

PARA method:

• Projects - Active work with a goal and end date (e.g., “user-auth-feature”)
• Areas - Ongoing responsibilities without end date (e.g., “performance-monitoring”)
• Resources - Reference material (e.g., agent configs, templates)
• Archives - Completed or inactive items

Should I use wai for every project?

Wai is most valuable for:

• Complex features requiring research and design
• Work spanning multiple sessions
• Collaboration requiring knowledge transfer
• Projects where “why” matters (architecture decisions, trade-offs)

For quick fixes or trivial changes, standard git commits may be enough.

How often should I create handoffs?

Create handoffs when:

• Ending a work session (especially multi-hour sessions)
• Switching context to another project
• Handing work to another developer
• Taking a break and might forget context

Think of handoffs as “save points” for your reasoning.

Agent Configuration

What’s the difference between skills, rules, and context?

• Skills - Task-specific instructions (e.g., “how to review code”, “how to commit”)
• Rules - System-wide constraints (e.g., “always add tests”, “follow security practices”)
• Context - Project-specific background (e.g., “architecture overview”, “team conventions”)

Which sync strategy should I use?

See Agent Config Sync for details.

Can I use multiple sync strategies?

Yes! You can have different projections for different tools:

projections:
  - strategy: symlink
    sources: [skills/]
    target: .claude/skills/
  - strategy: inline
    sources: [rules/]
    target: .cursorrules

What happens if I edit synced files directly?

Wai will overwrite them on the next sync. Always edit source files in .wai/resources/agent-config/, never the synced targets.

Plugins

How do I create a custom plugin?

Create a TOML file in .wai/plugins/:

name = "my-tool"
description = "My tool integration"

[detector]
type = "directory"
path = ".mytool"

[[commands]]
name = "status"
description = "Show status"
passthrough = "mytool status"
read_only = true

[hooks.on_status]
command = "mytool stats"
inject_as = "mytool_stats"

See Plugin System for complete guide.

Can I disable built-in plugins?

No, built-in plugins (git, beads, openspec) cannot be disabled. They’re only active when their detector finds the relevant files (e.g., .git/ for git).

Why isn’t my plugin detected?

Common reasons:

1. Detector path doesn’t exist (e.g., .mytool/ directory missing)
2. TOML syntax error in plugin definition
3. Plugin tool not installed or not in PATH

Run wai doctor to diagnose plugin issues.

Workflow & Patterns

What are workflow patterns?

Wai automatically detects your project state and suggests next steps:

• NewProject - No artifacts yet → suggests adding research
• ResearchPhaseMinimal - Few artifacts → suggests gathering more info
• ReadyToImplement - Designs complete → suggests moving to implementation
• ImplementPhaseActive - Currently implementing → suggests testing

Can I customize workflow suggestions?

Not yet, but it’s planned. For now, you can ignore suggestions that don’t fit your workflow.

How does wai know what to suggest?

Wai analyzes:

• Current project phase
• Number and type of artifacts
• Plugin state (git status, open issues, etc.)
• Recent activity

Based on this, it matches patterns and suggests relevant commands.

Technical

Where is data stored?

Everything is in .wai/ directory:

.wai/
├── config.toml           # Project configuration
├── projects/             # Active projects with artifacts
├── resources/            # Agent configs, templates
└── plugins/              # Custom plugin definitions

Safe to version control with git!

Is wai data portable?

Yes! The entire .wai/ directory can be:

• Committed to git
• Copied to another machine
• Backed up
• Shared with team members

Can I use wai in CI/CD?

Yes! Use non-interactive mode with JSON output:

wai status --json --no-input
wai search "query" --json --no-input
wai doctor --json --no-input

Does wai work offline?

Yes, wai is completely local. No network required.

What’s the performance impact?

Minimal. Wai is a lightweight CLI tool. Most commands complete in milliseconds. Large projects (hundreds of artifacts) may see slower search/timeline commands, but typically still under 1 second.

Troubleshooting

Command not found after installation

Add cargo bin to PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Add to ~/.bashrc or ~/.zshrc to make permanent.

Doctor reports issues I don’t understand

Run with verbose mode:

wai doctor -v

Check Troubleshooting for common issues.

My synced files keep getting overwritten

This is expected behavior. Wai syncs from source files in .wai/resources/agent-config/ to target locations. Always edit source files, never the synced targets.

See Agent Config Sync - Conflict Resolution.

Search returns no results but files exist

Check:

1. Are you searching the right project? Use --in project-name
2. Is the search term exact? Try regex mode: --regex
3. Do artifacts exist? Check: wai timeline project-name

Getting More Help

• Documentation: Read full docs in docs/ directory
• Tutorial: Run wai tutorial for interactive guide
• Command help: wai <command> --help
• Workspace health: wai doctor
• GitHub Issues: https://github.com/charly-vibes/wai/issues

See Also

• Quick Start - Get started in 5 minutes
• Commands Reference - Complete command list
• Troubleshooting - Common problems and solutions
• Concepts - Deep dive into wai’s design

Glossary

Domain-specific terms used throughout the wai documentation.

Addendum A correction artifact that references a locked artifact via --corrects=<path>. Preserves the original’s integrity while recording what changed and why. See Pipelines — Artifact Locking.

Artifact A dated Markdown file capturing reasoning at a specific point in time. Types include research, design, plan, handoff, and review. Stored in project subdirectories under .wai/projects/. See Project Phases.

Artifact lock A SHA-256 hash sidecar (.lock file) written alongside a pipeline artifact to freeze its content. Created automatically when a step with lock = true advances, or manually via wai pipeline lock. Verified by wai pipeline verify and wai doctor. See Pipelines — Artifact Locking.

Frontmatter YAML metadata at the top of an artifact file (between --- markers). Contains fields like title, date, tags, and project name. Used by wai search for filtering and by wai why for context gathering.

Handoff A session context transfer document generated by wai close or wai handoff create. Contains a session summary, current state, plugin context, and next steps. Enables continuity across sessions and agents. See Sessions.

Managed block An auto-generated section in instruction files (AGENTS.md, CLAUDE.md) delimited by <!-- WAI:START --> / <!-- WAI:END --> markers. Updated automatically by wai init and wai reflect. Do not edit manually — changes will be overwritten.

Oracle The LLM-powered reasoning engine behind wai why. Queries your project artifacts and git history to answer natural-language questions about design decisions. See Reasoning. Not to be confused with oracle scripts — see Pipeline gate.

Oracle script A user-defined validation script executed during pipeline gate checks. Placed in .wai/resources/oracles/ and referenced from pipeline TOML definitions. Exit 0 = pass, non-zero = fail. See Pipelines — Gates.

PARA An organizational system with four categories: Projects (active work with a goal), Areas (ongoing responsibilities), Resources (reference material), Archives (completed items). See PARA Method.

Phase One of six lifecycle stages a project moves through: research → design → plan → implement → review → archive. Phases guide what kind of work and artifacts are expected. See Project Phases.

Pipeline An ordered, multi-step workflow defined in TOML. Pipelines structure complex tasks (like research) into sequential steps with validation between them. See Pipelines.

Pipeline gate A condition that must be satisfied before advancing to the next pipeline step. Gate tiers include structural (artifact counts), procedural (review verdicts), oracle (custom scripts), and approval (human checkpoints). See Pipelines — Gates.

Pipeline run An active execution of a pipeline, scoped to a topic. Created with wai pipeline start and advanced with wai pipeline next. State is tracked so you can resume across sessions.

Review artifact An artifact that records validation results against another artifact. Created with wai add review --reviews <target>. Includes optional verdict (pass/fail/needs-work), severity counts, and the producing skill name. Used by pipeline procedural gates to enforce review requirements. See Commands — Adding Artifacts.

Plugin An integration module that connects wai with external tools (git, beads, openspec). Plugins are auto-detected based on workspace markers (e.g., .git/, .beads/). See Plugin System.

Projection A sync strategy that maps source files in .wai/resources/agent-config/ to tool-specific target locations. Strategies include symlink, inline, and reference. See Agent Config Sync.

Hook A plugin extension point triggered during wai operations. Hooks like on_status and on_handoff_generate let plugins inject context into wai’s output. See Plugin System — Hooks.

Passthrough A plugin command that delegates directly to the underlying tool. For example, wai beads list passes through to the beads CLI. See Plugin System — Commands.

Safe mode A read-only execution mode activated by the --safe global flag. Blocks all write operations (add, sync, move, pipeline start/next/init/approve/lock, phase changes, import). Read-only commands work normally. See Commands — Safe mode.

Reflection A synthesized summary of project patterns, conventions, and architectural notes produced by wai reflect. Stored as versioned Markdown in .wai/resources/reflections/ and injected into instruction files. See Reasoning.

Session A unit of work bounded by wai prime (start) and wai close (end). Sessions preserve context across agent restarts and context window boundaries. See Sessions.

Development

Prerequisites

• Rust (stable toolchain)
• just (command runner)

Architecture Overview

wai is built as a modular CLI tool in Rust, focusing on local-first storage and tool-agnostic integration.

For a deeper dive into the codebase structure and ADRs, see Architecture.

Core Systems

1. Registry & Workspace (src/workspace.rs, src/config.rs)

Manages the .wai/ directory structure and the PARA method (Projects, Areas, Resources, Archives).

• Project state: Tracked via .state files in each project.
• Artifacts: Stored as date-prefixed markdown files with optional frontmatter.

2. Plugin System (src/plugin.rs)

A flexible architecture for detecting and interacting with external tools.

• Built-in plugins: git, beads, openspec.
• Custom plugins: Loaded from .wai/plugins/*.toml.
• Hooks: Allows tools to inject context into wai status (on_status) and wai handoff create (on_handoff_generate).
• Passthrough: Direct execution of tool commands (e.g., wai beads list).

3. Agent-Config Sync Engine (src/sync_core.rs, src/commands/sync.rs)

Syncs a single source of truth for agent configurations to tool-specific locations.

• Projections: Defined in .projections.yml.
• Strategies: symlink, inline (concatenation), reference (path listing), and copy.
• Specialized Targets: Built-in logic for tools like claude-code.

4. Reasoning Oracle (src/llm.rs, src/commands/why.rs)

Interfaces with LLMs (Claude, Ollama) to answer natural language questions about the codebase using project artifacts as context.

5. Pipelines (src/commands/pipeline.rs)

Multi-step, prompt-driven workflows that track run IDs and automatically tag artifacts.

Building

just build           # Debug build
just build-release   # Release build

Testing

just test            # Run all tests
just test-verbose    # Run tests with output
just test-one <name> # Run a specific test

Linting & formatting

just lint            # Run clippy
just fmt             # Format code
just fmt-check       # Check formatting without changes

Full CI pipeline

Run the same checks that CI runs:

just ci

Documentation

Build and preview the docs locally:

just docs            # Build docs
just docs-serve      # Live preview at localhost:3000

Requires mdBook:

cargo install mdbook

Architecture

This page describes wai’s internal architecture for contributors who want to understand or modify the codebase.

High-Level Structure

Wai is a modular Rust CLI organized into five core subsystems:

src/
├── main.rs                 # Entry point
├── cli.rs                  # Clap argument definitions
├── commands/               # One file per subcommand
│   ├── status.rs           # wai status
│   ├── add.rs              # wai add
│   ├── search.rs           # wai search
│   ├── prime.rs            # wai prime
│   ├── close.rs            # wai close
│   ├── why.rs              # wai why (reasoning oracle)
│   ├── reflect.rs          # wai reflect (synthesis)
│   ├── doctor.rs           # wai doctor
│   ├── way.rs              # wai way (best practices)
│   ├── pipeline.rs         # wai pipeline
│   └── ...
├── workspace.rs            # Registry & PARA directory management
├── config.rs               # Config loading (.wai/config.toml)
├── plugin.rs               # Plugin detection, hooks, passthrough
├── sync_core.rs            # Agent config sync engine
├── llm.rs                  # LLM backend abstraction
├── suggestions.rs          # Context-aware next-step suggestions
└── help.rs                 # Tiered help system

Subsystems

1. Registry & Workspace

Files: src/workspace.rs, src/config.rs

Manages the .wai/ directory structure and the PARA method. Project state is tracked via .state files. Artifacts are stored as date-prefixed Markdown files with optional YAML frontmatter.

2. Plugin System

Files: src/plugin.rs

Auto-detects external tools by scanning for workspace markers (.git/, .beads/, openspec/). Plugins contribute context through hooks (on_status, on_handoff_generate, on_phase_transition) and expose commands via passthrough. Custom plugins are loaded from .wai/plugins/*.toml.

3. Agent Config Sync Engine

Files: src/sync_core.rs, src/commands/sync.rs

Projects agent configurations from .wai/resources/agent-config/ to tool-specific locations using configurable strategies (symlink, inline, reference, copy). Specialized targets like claude-code handle complex tool-specific transformations.

4. Reasoning Oracle & Synthesis

Files: src/llm.rs, src/commands/why.rs, src/commands/reflect.rs

Interfaces with LLMs (Claude API, Claude CLI, Ollama) to answer questions about the codebase (wai why) and synthesize project patterns (wai reflect). The LlmClient trait abstracts backend differences.

5. Pipelines

Files: src/commands/pipeline.rs

Multi-step, prompt-driven workflows defined in TOML. Tracks run state, supports pipeline gates (structural, procedural, oracle, approval), and auto-tags artifacts with run IDs.

Design Decisions

Significant trade-offs and architectural choices are captured as wai artifacts. Run wai search "design" to browse design decisions, or check .wai/resources/reflections/ for synthesized project patterns.