aia 1.1.1 → 2.0.0.0.pre.alpha

data/examples/README.md

@@ -185,6 +185,64 @@ Docs: [Executable Prompts](https://madbomber.github.io/aia/guides/executable-pro
 
 Docs: [Chat Guide](https://madbomber.github.io/aia/guides/chat/), [Directives Reference](https://madbomber.github.io/aia/directives-reference/), [Workflows and Pipelines](https://madbomber.github.io/aia/workflows-and-pipelines/)
 
+### 23 — Verify Mode
+
+`23_verify.sh` — Demonstrates `/verify` mode via `VerificationNetwork`. Two robots independently answer the same question with slightly different system prompts, then a third reconciler robot compares both answers and produces a final verified response. Part 1 verifies a factual question (causes of the 2008 financial crisis); Part 2 verifies a technical explanation (TCP three-way handshake).
+
+**Requires:** `expect` (pre-installed on macOS).
+
+Docs: [Advanced Prompting](https://madbomber.github.io/aia/advanced-prompting/), [Chat Guide](https://madbomber.github.io/aia/guides/chat/)
+
+### 24 — Decompose Mode
+
+`24_decompose.sh` — Demonstrates `/decompose` mode via `PromptDecomposer`. A coordinator robot analyzes whether a prompt can be split into 2–5 independent sub-tasks. If decomposable, specialist robots run each in parallel and results are synthesized into a single coherent response. Falls back to normal mode if the prompt is not decomposable. Part 1 uses a complex multi-part TCP/UDP question; Part 2 demonstrates the fallback with a simple question.
+
+**Requires:** `expect` (pre-installed on macOS).
+
+Docs: [Advanced Prompting](https://madbomber.github.io/aia/advanced-prompting/), [Chat Guide](https://madbomber.github.io/aia/guides/chat/)
+
+### 25 — Spawn Mode
+
+`25_spawn.sh` — Demonstrates `/spawn` mode via `SpawnHandler`. Dynamically creates a specialist robot on demand. Part 1 explicitly names a specialist type (`/spawn security-expert`) and asks a SQL injection question. Part 2 uses auto-detection (`/spawn` with no args) where the primary robot determines the needed expertise from the question content. Specialists are cached and reused within the session.
+
+**Requires:** `expect` (pre-installed on macOS).
+
+Docs: [Advanced Prompting](https://madbomber.github.io/aia/advanced-prompting/), [Chat Guide](https://madbomber.github.io/aia/guides/chat/)
+
+### 26 — Debate Mode
+
+`26_debate.sh` — Demonstrates `/debate` mode via `DebateHandler`. Two robots debate a topic across multiple rounds. Each round, every robot sees what the other said and responds. The debate ends when a robot says CONVERGED or after 5 rounds. `SimilarityScorer` also detects convergence by comparing round-to-round similarity. Uses `qwen3` (Tobor) vs `phi4-mini` (Quark) debating REST vs GraphQL.
+
+**Requires:** `expect` (pre-installed on macOS), `phi4-mini` model (auto-pulled if missing).
+
+Docs: [Advanced Prompting](https://madbomber.github.io/aia/advanced-prompting/), [Working with Models](https://madbomber.github.io/aia/guides/models/)
+
+### 27 — @mention Routing
+
+`27_mention_routing.sh` — Demonstrates `@mention` routing in a multi-model network. Prefixing a message with `@RobotName` directs it to a specific robot; only that robot responds. Robot names are assigned by AIA: `qwen3` becomes `Tobor`, `phi4-mini` becomes `Quark`. Part 1 routes to `@Tobor`; Part 2 routes to `@Quark`; Part 3 shows how an unknown `@mention` triggers a listing of available robot names. Part 4 opens interactive chat to mix directed and undirected turns freely.
+
+**Requires:** `expect` (pre-installed on macOS), `phi4-mini` model (auto-pulled if missing).
+
+Docs: [Chat Guide](https://madbomber.github.io/aia/guides/chat/), [Working with Models](https://madbomber.github.io/aia/guides/models/)
+
+### 28 — Model Switching
+
+`28_model_switching.sh` — Demonstrates the `/model` directive for switching models mid-conversation. Conversation history is transferred to the new model so it has full context of everything discussed before the switch. Part 1 asks a question with `qwen3` (Tobor), switches to `phi4-mini` (Quark) via `/model ollama/phi4-mini`, then asks a follow-up that requires the previous exchange for context.
+
+**Requires:** `expect` (pre-installed on macOS), `phi4-mini` model (auto-pulled if missing).
+
+Docs: [Chat Guide](https://madbomber.github.io/aia/guides/chat/), [Working with Models](https://madbomber.github.io/aia/guides/models/)
+
+### 29 — Agent Harness
+
+`29_agent_harness.sh` — Demonstrates AIA as a full agent harness using a three-tier orchestration model. Tobor starts with an `orchestrator` role loaded via `--role orchestrator`, making it the primary coordinator. Part 1 shows Tobor describing its coordination strategy for a complex request. Part 2 uses `/spawn security-expert` to create a specialist lead agent on demand and route a task to it. Part 3 uses `/decompose` with a multi-dimension design review — Tobor and Quark run parallel workstreams as task runners, then Tobor synthesizes the result. Part 4 opens a free orchestration session where any combination of `/spawn`, `/decompose`, `/delegate`, `/debate`, and `@mention` routing can be tried.
+
+The orchestrator role file lives at `examples/prompts_dir/roles/orchestrator.md` and can be customized to tune Tobor's coordination behavior.
+
+**Requires:** `expect` (pre-installed on macOS), `phi4-mini` model (auto-pulled if missing).
+
+Docs: [Chat Guide](https://madbomber.github.io/aia/guides/chat/), [Roles](https://madbomber.github.io/aia/guides/roles/)
+
 ## Running All Demos
 
 `run_all.sh` runs all non-interactive demo scripts in sequence and captures the combined output. It serves as a structural integration test — since LLM responses are non-deterministic, exact diffs between runs won't match, but you can spot missing sections, crashes, or changed command output.
@@ -221,6 +279,13 @@ diff output/run_PREV.log output/run_LATEST.log
 | `15_parameters.sh` | Part 2 prompts interactively for a required parameter |
 | `20_mcp_servers.sh` | Requires Node.js/npx + MCP filesystem server |
 | `22_chat_mode.sh` | Interactive chat session (uses `expect`) |
+| `23_verify.sh` | Uses `expect` for interactive chat |
+| `24_decompose.sh` | Uses `expect` for interactive chat |
+| `25_spawn.sh` | Uses `expect` for interactive chat |
+| `26_debate.sh` | Uses `expect` for interactive chat |
+| `27_mention_routing.sh` | Uses `expect` for interactive chat |
+| `28_model_switching.sh` | Uses `expect` for interactive chat |
+| `29_agent_harness.sh` | Uses `expect` for interactive chat; Part 4 is fully interactive |
 
 The output includes a banner with version info, per-script pass/fail status, and a summary with counts.
 

data/examples/advanced_multi_robot_capabilities_without_examples.md

@@ -0,0 +1,106 @@
+# Advanced Multi-Robot Capabilities Without Examples
+
+AIA v2 includes several advanced multi-robot execution modes that have no demo
+scripts yet. These are currently accessible only through chat-time directives
+(`/verify`, `/debate`, etc.) inside a `--chat` session, but the underlying
+handlers are self-contained and could equally be exposed via CLI flags, YAML
+front matter, or `//` prompt-file directives in batch mode.
+
+## Already Covered
+
+`11_multi_model.sh` covers:
+- Multi-model comparison mode (`-m modelA,modelB`)
+- `--consensus` cooperative synthesis
+
+## Missing Demos
+
+| Feature | Handler | Min models | Current entry point |
+|---|---|---|---|
+| `/verify` self-review | `VerificationNetwork` | 1 | `/verify` in chat |
+| `/decompose` parallel tasks | `PromptDecomposer` | 1 | `/decompose` in chat |
+| `/spawn` specialist robots | `SpawnHandler` | 1 | `/spawn [type]` in chat |
+| `/debate` multi-round | `DebateHandler` | 2 | `/debate` in chat |
+| `@mention` routing | `MentionRouter` | 2 | `@robot_name question` in chat |
+| Natural language model switch | `ModelSwitchHandler` | 1 | "switch to X" in chat |
+| `/delegate` TrakFlow teams | `DelegateHandler` | 2 | `/delegate` in chat |
+
+## Feature Details
+
+### `/verify` Self-Review (`lib/aia/verification_network.rb`)
+- Two robots independently answer the same question with slightly different system
+  prompts to encourage independence, then a third "reconciler" robot compares both
+  answers, identifies agreements and disagreements, and produces a final verified
+  answer.
+- All three robots use the same model (`config.models.first`) — no second model needed.
+- Batch-capable: the handler takes a prompt string and returns a response with no
+  interactive steps. Could be exposed as `--verify` CLI flag or `mode: verify`
+  front matter.
+
+### `/decompose` Parallel Tasks (`lib/aia/prompt_decomposer.rb`)
+- A coordinator robot analyzes whether a complex prompt can be split into 2-5
+  independent sub-tasks. If decomposable, specialist robots solve each in parallel
+  and results are synthesized into a unified answer. Falls back to normal mode if
+  the prompt is not decomposable.
+- Single model is sufficient.
+- Batch-capable: no interactivity required. Could be `--decompose` or `mode: decompose`.
+
+### `/spawn` Specialist Robots (`lib/aia/spawn_handler.rb`)
+- Dynamically creates a specialist robot on demand. The user can name a type
+  (`/spawn security-expert`) or omit it and let the primary robot auto-detect the
+  needed expertise. Spawned specialists are cached for reuse within the session.
+  Optionally creates TrakFlow tasks when TrakFlow is available.
+- Single model is sufficient.
+- Batch-capable: specialist type could be specified via CLI flag or front matter.
+
+### `/debate` Multi-Round (`lib/aia/debate_handler.rb`)
+- Two or more robots debate a topic across rounds. Each round, every robot responds
+  to the previous arguments. Stops when any robot says "CONVERGED" or after 5
+  rounds. Displays formatted round-by-round output.
+- Requires a 2-model network (`-m modelA,modelB`).
+- Batch-capable: debate runs to completion without user input — could be `--debate`.
+
+### `@mention` Routing (`lib/aia/mention_router.rb`)
+- Directs a message to one specific robot in a multi-model network by name.
+  Syntax: `@robot_name your question`. If the robot name is unknown, available
+  robots are listed. Shows token metrics with `--tokens`.
+- Requires a 2-model network.
+- Genuinely interactive: the value is in the user directing conversation flow
+  turn-by-turn; less meaningful as a one-shot batch operation.
+
+### Natural Language Model Switch (`lib/aia/model_switch_handler.rb`)
+- Detects model-change intent from natural language input, e.g. "switch to llama"
+  or "use phi4-mini instead". Shows "Interpreted as: /model X" and prompts for
+  confirmation (y/n). On confirmation, rebuilds the robot with the new model and
+  transfers history. Also handles `model_compare` and `model_switch_capability` intents.
+- Genuinely interactive: depends on the user directing the conversation.
+
+### `/delegate` TrakFlow Teams (`lib/aia/delegate_handler.rb`)
+- A lead robot breaks the prompt into subtasks and assigns each to team members via
+  a TrakFlow plan. Each robot executes its subtask in order with full shared context.
+  Shows the plan before execution, then step-by-step results.
+- Requires a 2-model network and the TrakFlow gem.
+- **Blocked**: `trak_flow` gem currently has a LoadError in this environment.
+  Defer until the TrakFlow dependency is resolved.
+
+## Batch Mode Extension Opportunities
+
+`/verify`, `/decompose`, `/debate`, and `/spawn` are ready to be lifted out of
+chat-only access. `@mention` routing and natural language model switching are
+genuinely conversational and are better left as chat-only features.
+
+| Feature | Suggested CLI flag | Suggested front matter key |
+|---|---|---|
+| `/verify` | `--verify` | `mode: verify` |
+| `/decompose` | `--decompose` | `mode: decompose` |
+| `/debate` | `--debate` | `mode: debate` |
+| `/spawn` | `--spawn TYPE` | `mode: spawn` / `spawn_type: TYPE` |
+
+## Demo Implementation Notes
+
+- Chat-mode demos would use `expect` scripting like `22_chat_mode.sh`.
+- Single-model demos can reuse `ollama/qwen3` from the setup script.
+- Multi-model demos need a second model — `ollama/phi4-mini` (already used in
+  `11_multi_model.sh`) is the natural choice.
+- Suggested numbering: `23_verify.sh`, `24_decompose.sh`, `25_spawn.sh`,
+  `26_debate.sh`, `27_mention_routing.sh`, `28_model_switching.sh`
+- Skip `29_delegate.sh` until the TrakFlow LoadError is resolved.

data/examples/aia_config.yml

@@ -13,7 +13,7 @@ prompts:
   dir: ./prompts_dir
 
 models:
-  - name: ollama/qwen3
+  - name: gpt-4.1
 
 output:
   file: ~

data/examples/aia_config_orchestrator.yml

@@ -0,0 +1,45 @@
+# AIA configuration for agent harness demo (29_agent_harness.sh)
+#
+# Extends the base demo config with an orchestrator system prompt so Tobor
+# is pre-configured as the primary coordinator from the start of the session.
+# The system_prompt is injected into the robot's context at build time —
+# it is NOT sent as a user message. Use this config with --chat and optionally
+# -m MODEL_A,MODEL_B to add specialist network robots.
+#
+# Usage:
+#   aia -c aia_config_orchestrator.yml --chat
+#   aia -c aia_config_orchestrator.yml -m gpt-4.1,gpt-4.1-mini --chat
+
+prompts:
+  dir: ./prompts_dir
+  system_prompt: |
+    You are Tobor, the primary AI orchestrator in this session.
+
+    Your role is to coordinate a team of specialized robots to handle complex
+    tasks. Think like a project director: delegate what can be parallelized,
+    direct what requires deep specialization, and synthesize what needs
+    holistic judgment.
+
+    When you receive a request, apply this decision framework:
+
+    - Direct response: Simple, self-contained questions — answer yourself.
+    - /spawn specialist-type: Questions requiring narrow domain expertise.
+      This creates a specialist lead agent on the fly and routes the task to it.
+    - /decompose: Complex requests with multiple independent dimensions.
+      This splits the task into parallel workstreams across your robot team,
+      then synthesizes the results into a unified response.
+    - /delegate: Structured multi-step tasks where steps have dependencies.
+      This creates a tracked execution plan with ordered hand-offs between robots.
+
+    Always be explicit about which coordination strategy you are using and why.
+    When you spawn or decompose, briefly state the workstreams or specialist
+    roles before execution so the user understands the plan.
+
+models:
+  - name: gpt-4.1
+
+output:
+  file: ~
+
+flags:
+  chat: false

data/examples/common.sh

@@ -12,6 +12,15 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "${SCRIPT_DIR}"
 
+# When running from inside the development repo, prefer the local bin/aia
+# over any system-installed gem. bin/aia loads from ../lib/aia directly,
+# so demos always run against the version in this checkout.
+# Exported so child processes (including `expect`'s `spawn aia`) inherit it.
+REPO_BIN="$(cd "${SCRIPT_DIR}/.." && pwd)/bin"
+if [ -f "${REPO_BIN}/aia" ]; then
+  export PATH="${REPO_BIN}:${PATH}"
+fi
+
 # Clear all AIA_* env vars so personal settings don't leak in.
 while IFS= read -r var; do
   unset "$var"
@@ -19,9 +28,12 @@ done < <(env | grep '^AIA_' | cut -d= -f1)
 
 CONFIG="aia_config.yml"
 
-# When running from the develop branch, prefer the local bin/aia over any
-# installed gem so that uncommitted working-tree changes are exercised.
-LOCAL_AIA="${SCRIPT_DIR}/../bin/aia"
-if [[ -x "${LOCAL_AIA}" ]]; then
-  export PATH="${SCRIPT_DIR}/../bin:${PATH}"
-fi
+# Drain leaked escape sequences from the terminal input buffer.
+# Reline queries cursor position (\e[6n) inside the pty; the
+# terminal's responses (\e[row;colR) can leak into bash's stdin
+# after expect exits. Call this after every expect block.
+drain_terminal() {
+    sleep 0.2
+    stty sane 2>/dev/null || true
+    while IFS= read -r -t 0.2 -n 100 _ 2>/dev/null; do :; done
+}

data/examples/context/tech_stack.md

@@ -1,7 +1,7 @@
 # Tech Stack
 
-- Language: Ruby 3.3+
-- LLM interface: ruby_llm gem
+- Language: Ruby 4.0+
+- LLM interface: robot_lab gem (orchestration) + ruby_llm gem (LLM abstraction)
 - Prompt storage: prompt_manager gem (Markdown files)
 - CLI parsing: optparse (stdlib)
 - Config: myway_config gem (YAML + XDG)

data/examples/prompts_dir/roles/orchestrator.md

@@ -0,0 +1,21 @@
+You are Tobor, the primary AI orchestrator in this session.
+
+Your role is to coordinate a team of specialized robots to handle complex tasks.
+Think like a project director: delegate what can be parallelized, direct what
+requires deep specialization, and synthesize what needs holistic judgment.
+
+When you receive a request, apply this decision framework:
+
+- **Direct response**: Simple, self-contained questions — answer yourself.
+- **/spawn specialist-type**: Questions requiring narrow domain expertise.
+  This creates a specialist lead agent on the fly and routes the task to it.
+  Example: `/spawn security-expert` before asking about API hardening.
+- **/decompose**: Complex requests with multiple independent dimensions.
+  This splits the task into parallel workstreams across your robot team,
+  then synthesizes the results into a unified response.
+- **/delegate**: Structured multi-step tasks where steps have dependencies.
+  This creates a tracked execution plan with ordered hand-offs between robots.
+
+Always be explicit about which coordination strategy you are using and why.
+When you spawn or decompose, briefly state the workstreams or specialist roles
+before execution so the user understands the plan.

data/examples/requirements/sinatra_taskflow_app.md

@@ -0,0 +1,139 @@
+# TaskFlow — Project & Task Management Web Application
+
+## Overview
+
+Build a standalone Ruby application using Sinatra as the web framework.
+TaskFlow is a multi-user project and task management system similar to a
+simplified Trello or Asana. The application must be a single deployable
+Ruby process with no external service dependencies beyond SQLite.
+
+## Technology Stack
+
+- Ruby 3.x
+- Sinatra 4.x (classic style, single `app.rb` entry point)
+- SQLite via the Sequel ORM (migrations in `db/migrations/`)
+- ERB templates in `views/` (layouts, partials)
+- Bootstrap 5 via CDN for styling
+- bcrypt for password hashing
+- jwt gem for API token issuance
+- Rack::Session::Cookie for browser sessions
+- WEBrick for development; Puma for production
+
+## Authentication & Authorization
+
+- Users register with email, password (bcrypt), and display name
+- Login issues a session cookie (browser) and a JWT (API clients)
+- Passwords must be at least 8 characters; emails must be unique
+- Sessions expire after 24 hours; JWT tokens after 1 hour
+- Route protection: unauthenticated requests redirect to /login (browser)
+  or return 401 JSON (API requests with Accept: application/json)
+- Role system: each project has members with role `owner`, `editor`, or `viewer`
+- Only owners may delete a project or change member roles
+- Editors may create/update/delete tasks within the project
+- Viewers may only read
+
+## Data Model
+
+### User
+- id (integer, primary key)
+- email (string, unique, not null)
+- password_digest (string, not null)
+- display_name (string, not null)
+- created_at, updated_at (timestamps)
+
+### Project
+- id (integer, primary key)
+- name (string, not null)
+- description (text)
+- owner_id (integer, FK → users.id)
+- created_at, updated_at
+
+### ProjectMember
+- id (integer, primary key)
+- project_id (integer, FK → projects.id)
+- user_id (integer, FK → users.id)
+- role (string: 'owner' | 'editor' | 'viewer')
+- joined_at (timestamp)
+- UNIQUE constraint on (project_id, user_id)
+
+### Task
+- id (integer, primary key)
+- project_id (integer, FK → projects.id)
+- title (string, not null)
+- description (text)
+- status (string: 'todo' | 'in_progress' | 'done', default 'todo')
+- priority (string: 'low' | 'medium' | 'high', default 'medium')
+- assigned_to (integer, FK → users.id, nullable)
+- due_date (date, nullable)
+- created_by (integer, FK → users.id)
+- created_at, updated_at
+
+## Web Routes (Browser)
+
+- GET  /                   → redirect to /dashboard if logged in, else /login
+- GET  /login              → login form
+- POST /login              → authenticate, set session, redirect to /dashboard
+- GET  /register           → registration form
+- POST /register           → create user, auto-login, redirect to /dashboard
+- POST /logout             → clear session, redirect to /login
+- GET  /dashboard          → list all projects the current user is a member of
+- GET  /projects/new       → form to create a project
+- POST /projects           → create project, add user as owner
+- GET  /projects/:id       → project detail: task list, member list
+- GET  /projects/:id/edit  → edit project name/description
+- PUT  /projects/:id       → update project
+- DELETE /projects/:id     → delete project (owner only)
+- GET  /projects/:id/tasks/new → new task form
+- POST /projects/:id/tasks    → create task
+- GET  /projects/:id/tasks/:tid/edit → edit task form
+- PUT  /projects/:id/tasks/:tid     → update task
+- DELETE /projects/:id/tasks/:tid   → delete task
+
+## REST API Routes (JSON, prefix /api/v1)
+
+- POST /api/v1/auth/login   → { token: "jwt..." }
+- GET  /api/v1/projects     → array of projects for current user
+- POST /api/v1/projects     → create project
+- GET  /api/v1/projects/:id → project + tasks
+- PUT  /api/v1/projects/:id → update project
+- DELETE /api/v1/projects/:id → delete project
+- GET  /api/v1/projects/:id/tasks   → task list
+- POST /api/v1/projects/:id/tasks   → create task
+- PUT  /api/v1/projects/:id/tasks/:tid → update task
+- DELETE /api/v1/projects/:id/tasks/:tid → delete task
+- GET  /api/v1/projects/:id/members → member list
+- POST /api/v1/projects/:id/members → add member
+- DELETE /api/v1/projects/:id/members/:uid → remove member
+
+## Views (ERB)
+
+- layout.erb           → HTML shell, nav bar, flash messages, Bootstrap 5
+- dashboard.erb        → project cards grid, "New Project" button
+- projects/show.erb    → task board (Kanban columns by status), member sidebar
+- projects/form.erb    → shared create/edit form
+- tasks/form.erb       → shared create/edit form
+- auth/login.erb       → login form
+- auth/register.erb    → registration form
+- partials/_flash.erb  → flash message component
+- partials/_task_card.erb → task card with status badge and priority indicator
+
+## Infrastructure & Configuration
+
+- `app.rb`             → Sinatra application class, requires all components
+- `config.ru`          → Rack entry point, mounts the app
+- `Gemfile`            → all dependencies with locked versions
+- `db/migrations/`     → numbered Sequel migration files
+- `db/schema.rb`       → auto-generated schema dump
+- `lib/auth_helpers.rb` → session/JWT helpers, `current_user`, `require_login`
+- `lib/api_helpers.rb` → JSON response helpers, token verification
+- `config/database.rb` → Sequel connection setup (dev/test/prod environments)
+- `config/settings.rb` → app constants: session secret, JWT secret, token TTL
+- `.env.example`       → template for required environment variables
+
+## Testing
+
+- RSpec with rack-test for request specs
+- Factory pattern for test data (no FactoryBot, plain Ruby factory methods)
+- Tests in `spec/`: `spec/auth_spec.rb`, `spec/projects_spec.rb`,
+  `spec/tasks_spec.rb`, `spec/api_spec.rb`
+- Test database: separate SQLite file, schema reset before each suite

data/examples/rules/01_classify_ruby.rb

@@ -0,0 +1,16 @@
+# examples/rules/01_classify_ruby.rb
+#
+# Custom classification rule: detect Ruby-specific requests.
+#
+# Install: cp examples/rules/01_classify_ruby.rb ~/.config/aia/rules/
+
+AIA.rules_for(:classify) do
+  rule "ruby_request" do
+    on :turn_input do
+      text matches(/\b(ruby|rails|gem|bundler|rake|rspec|minitest|rubocop|sorbet)\b/i)
+    end
+    perform do |_facts|
+      AIA.decisions.add(:classification, domain: "code", subdomain: "ruby", source: "user_ruby_request")
+    end
+  end
+end

data/examples/rules/02_prefer_claude_for_code.rb

@@ -0,0 +1,19 @@
+# examples/rules/02_prefer_claude_for_code.rb
+#
+# Model selection rule: prefer Claude for code tasks.
+# When the classify KB tags a prompt as "code" domain,
+# suggest Claude as the preferred model.
+#
+# Install: cp examples/rules/02_prefer_claude_for_code.rb ~/.config/aia/rules/
+
+AIA.rules_for(:model_select) do
+  rule "prefer_claude_for_code" do
+    on :classification_decision, domain: "code"
+    on :model, name: satisfies { |n| n.to_s.include?("claude") }
+    perform do |facts|
+      AIA.decisions.add(:model_decision,
+                        model: facts[1][:name],
+                        reason: "user rule: prefer Claude for code tasks")
+    end
+  end
+end

data/examples/rules/03_gate_prompt_length.rb

@@ -0,0 +1,19 @@
+# examples/rules/03_gate_prompt_length.rb
+#
+# Quality gate rule: warn when context files are very large.
+# This supplements the built-in 100KB warning with a custom threshold.
+#
+# Install: cp examples/rules/03_gate_prompt_length.rb ~/.config/aia/rules/
+
+AIA.rules_for(:gate) do
+  rule "very_large_context_warning" do
+    on :context_stats, large: true
+    perform do |facts|
+      size = facts[0][:total_size]
+      if size && size > 500_000
+        AIA.decisions.add(:gate, action: "warn",
+          message: "Context exceeds 500KB (#{size / 1024}KB). This may be slow and expensive.")
+      end
+    end
+  end
+end

data/examples/rules/04_tool_selection.rb

@@ -0,0 +1,41 @@
+# examples/rules/04_tool_selection.rb
+#
+# Custom tool selection rules (optional).
+#
+# AIA automatically builds tool routing rules at startup by analyzing
+# each loaded tool's name and description against domain keyword patterns.
+# This file shows how to ADD custom rules on top of the automatic ones.
+#
+# Use cases for custom rules:
+#   - Override automatic classification for a specific tool
+#   - Add domain routing for a custom tool with unusual naming
+#   - Activate tools based on input text patterns instead of domain
+#
+# Install: cp examples/rules/04_tool_selection.rb ~/.config/aia/rules/
+#
+# Facts available in the :route KB:
+#   :tool — name: String, description: String, active: true
+#   :classification_decision — domain: String, ...
+#   :turn_input — text: String, length: Integer
+
+AIA.rules_for(:route) do
+  # Example: activate a custom tool for a specific keyword
+  # rule "activate_my_custom_tool" do
+  #   on :turn_input do
+  #     text matches(/\b(my_keyword)\b/i)
+  #   end
+  #   on :tool, name: "my_custom_tool"
+  #   perform do |facts|
+  #     AIA.decisions.add(:tool_activate, tool: facts[1][:name], reason: "custom keyword match")
+  #   end
+  # end
+
+  # Example: force a tool into a domain it wasn't auto-classified into
+  # rule "activate_special_tool_for_data" do
+  #   on :classification_decision, domain: "data"
+  #   on :tool, name: "my_special_tool"
+  #   perform do |facts|
+  #     AIA.decisions.add(:tool_activate, tool: facts[1][:name], reason: "custom data domain override")
+  #   end
+  # end
+end

data/examples/rules/README.md

@@ -0,0 +1,30 @@
+# AIA User Rules
+
+> **NOTE (2026-03-28)**: The KBS rule engine has been removed from AIA (see ADR-010).
+> This directory is preserved for historical reference only. The `.rb` example files
+> here no longer work. User-defined rule hooks (`~/.config/aia/rules/*.rb`) are no
+> longer supported. Tool filtering is now handled exclusively by the TF-IDF/vector
+> strategies (A=TF-IDF, B=Zvec, C=SqliteVec, D=LSI).
+
+User rules extended the built-in KBS rule engine with custom classification,
+model selection, MCP routing, quality gate, and learning rules.
+
+## Setup
+
+Place `.rb` files in `~/.config/aia/rules/`. AIA loads them alphabetically
+at startup. Each file calls `AIA.rules_for(:kb_name)` to register rules
+targeting a specific knowledge base.
+
+## Available Knowledge Bases
+
+| KB Name        | Purpose                              | Facts Available                |
+|----------------|--------------------------------------|--------------------------------|
+| `:classify`    | Categorize prompts by domain/intent  | `:turn_input`, `:context_file` |
+| `:model_select`| Choose model based on classification | `:classification_decision`, `:model` |
+| `:route`       | Activate MCP servers                 | `:classification_decision`, `:mcp_server` |
+| `:gate`        | Pre-send quality checks              | `:turn_input`, `:context_stats`, `:session_stats` |
+| `:learn`       | Post-response tracking               | `:response_outcome`, `:session_stats` |
+
+## Examples
+
+See the `.rb` files in this directory for working examples.