Toolchain Synergy

Wai is the suite orchestrator for the full charly-vibes toolchain — eight tools that together cover the complete lifecycle from proposal to implementation to archival. Each tool owns a distinct concern and is detected automatically by its on-disk marker:

All tools live under the charly-vibes GitHub organisation except:

• beads — gastownhall/beads (issue tracking with Dolt-backed sync).
• openspec — openspecio/openspec (specification management lifecycle).

When to Use What

How They Integrate

All tools connect through wai’s plugin system, which auto-detects each tool by its on-disk marker:

• beads — detected when .beads/ exists. Open issue counts appear in wai status, and wai handoff create includes issue context in handoff documents.
• openspec — detected when openspec/ exists. Active change proposals and their progress appear in wai status.
• pretender — detected when pretender.toml exists. Wai can help bootstrap its config via wai way.
• dont — detected when .dont/ exists. Dont managed blocks in AGENTS.md are refreshed by wai sync.
• espectacular — detected when .espectacular/ exists. Espectacular signals (spec-test gaps) are surfaced in wai status.
• testaruda — detected when testaruda.toml exists. Test harness state is reported in wai status.
• vampiro / crua / livin — detection signals to be defined as the tools ship (expected: vampiro.toml, crua.toml, livin.toml or equivalent config files). Currently spec-stage only — presence is tracked via their spec documents (e.g. crua-ears-spec.md, vampiro-ears-spec.md). The trio’s state will appear in wai status once detected.

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. Wai’s wai doctor --suite will eventually validate suite-wide consistency (see wai-bdqw.8).

Detection is additive and optional — each tool works independently, but when multiple are present wai becomes the unified dashboard.

Worked Example: Adding a Feature

Here’s how a ticket flows through the core trio (wai + beads + openspec):

# 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

With the suite tools integrated, the workflow extends further:

# Enforce code quality conventions
dont define "No unwrap() in library code"

# Verify spec-to-test coverage before merging
ah check       # espectacular — does the test match the spec?
testaruda check  # property-based test coverage

# Lint for structural quality
pretender check .

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.
• Without pretender: Code quality standards are enforced by human review alone — slower, more inconsistent, and harder to enforce in CI.
• Without dont: Conventions live in READMEs or Slack — unenforceable and easy to forget.
• Without espectacular: Specs and tests drift independently; no automated signal that they disagree.
• Without testaruda: Property-based and harness testing must be set up manually, with no unified test dashboard.
• Without vampiro/crua/livin (planned): Spec-stage analysis must be done manually or deferred until implementation.

Each tool is optional. Wai works fine alone. But together, the full suite covers the entire lifecycle — from proposal through implementation, quality assurance, and archival.

See also: Suite Conventions for canonical policies on edition, license, version scheme, and justfile setup.