Introduction

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.

Most specs define what to build. Wai extends the workflow to also inform — preserving the research, reasoning, and decisions that shaped the design. When you revisit a project months later, the spec tells you what exists; wai tells you why.

It organizes artifacts using the PARA method (Projects, Areas, Resources, Archives) with project phase tracking, agent config sync, handoff generation, and plugin integration.

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).
• 🔄 Sync — Keep AI instructions (CLAUDE.md, .cursorrules) automatically in sync.
• 📦 Handoff — Generate high-context session summaries for yourself or other agents.

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.

Design Principles

• 🛣️ Desire Path Alignment — Pave the cowpaths; make common workflows shortest.
• 🩹 Self-Healing Errors — Errors suggest fixes, not just report problems.
• 🌊 Progressive Disclosure — Simple by default, powerful when needed.
• 💡 Context-Aware — Offer smart next steps based on your current project state.

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 to store your artifacts and configuration.

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

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."

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."

6. Check Your Progress

Get a context-aware overview of your workspace:

wai status

Status shows your active projects, their current phases, and smart suggestions for what to do next.

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.
• Agent Config Sync — Keep your AI tools in sync.
• Diagnostics & Health — Learn the difference between wai doctor and wai way.

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:

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.”

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

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 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

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

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

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

Projects in wai progress through six phases:

research → design → plan → implement → review → archive

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.

Plugin System

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

Agent Config Sync

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

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:
  - type: 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

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

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.

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