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.