@jaguilar87/gaia 5.0.0-rc.2

package/skills/gaia-patterns/reference.md

@@ -0,0 +1,395 @@
+# Gaia Patterns -- Reference
+
+Package: `@jaguilar87/gaia` v5.0.0-rc1 | Node >=18 | Python >=3.9
+
+---
+
+## 1. Component Map
+
+### Hook Entry Points (10 files)
+
+| File | Event | Matchers |
+|------|-------|----------|
+| `hooks/pre_tool_use.py` | PreToolUse | `Bash`, `Task`, `Agent`, `SendMessage`, `Read\|Edit\|Write\|Glob\|Grep\|WebSearch\|WebFetch\|NotebookEdit` |
+| `hooks/post_tool_use.py` | PostToolUse | `Bash`, `AskUserQuestion` |
+| `hooks/stop_hook.py` | Stop | (all) |
+| `hooks/user_prompt_submit.py` | UserPromptSubmit | (all) |
+| `hooks/subagent_start.py` | SubagentStart | `*` |
+| `hooks/subagent_stop.py` | SubagentStop | `*` |
+| `hooks/session_start.py` | SessionStart | `startup` |
+| `hooks/task_completed.py` | TaskCompleted | (all) |
+| `hooks/post_compact.py` | PostCompact | (all) |
+| `hooks/elicitation_result.py` | ElicitationResult | (none registered) |
+
+### Hook Modules (13 packages)
+
+| Package | Files | Purpose |
+|---------|-------|---------|
+| `core/` | `hook_entry`, `paths`, `plugin_mode`, `plugin_setup`, `state`, `stdin` | Entry dispatch, path resolution, mode detection, shared state |
+| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `gitops_validator`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
+| `audit/` | `logger`, `metrics`, `event_detector`, `workflow_auditor`, `workflow_recorder` | Structured logging, metrics collection, workflow audit trail |
+| `tools/` | `bash_validator`, `cloud_pipe_validator`, `shell_parser`, `task_validator`, `hook_response` | Command validation, pipe detection, shell parsing |
+| `context/` | `context_injector`, `context_writer`, `context_freshness`, `contracts_loader`, `compact_context_builder`, `anchor_tracker` | Project-context injection, freshness checks, contract loading |
+| `agents/` | `contract_validator`, `response_contract`, `skill_injection_verifier`, `task_info_builder`, `transcript_analyzer`, `transcript_reader` | json:contract validation, skill verification, transcript analysis |
+| `session/` | `session_manager`, `session_context_writer`, `session_event_injector` | Session lifecycle, context persistence |
+| `orchestrator/` | `delegate_mode` | Delegation mode detection |
+| `validation/` | `commit_validator` | Git commit validation |
+| `scanning/` | `scan_trigger` | Auto-scan trigger |
+| `events/` | `event_writer` | Structured event output |
+| `memory/` | `episode_writer` | Episodic memory persistence |
+| `adapters/` | `base`, `channel`, `claude_code`, `types`, `utils` | Hook I/O abstraction layer |
+
+### Agents (8)
+
+| Agent | File | Domain | permissionMode |
+|-------|------|--------|----------------|
+| gaia-orchestrator | `agents/gaia-orchestrator.md` | Routes requests, manages workflow, consolidation | (not set) |
+| gaia-operator | `agents/gaia-operator.md` | Workspace operator -- personal workspace tasks, memory management, integrations | `acceptEdits` |
+| gaia-system | `agents/gaia-system.md` | Gaia-ops meta-system itself | `acceptEdits` |
+| developer | `agents/developer.md` | Application code (Node/TS, Python) | `acceptEdits` |
+| cloud-troubleshooter | `agents/cloud-troubleshooter.md` | Live cloud diagnostics | (not set) |
+| gitops-operator | `agents/gitops-operator.md` | Kubernetes, HelmRelease, Flux | `acceptEdits` |
+| terraform-architect | `agents/terraform-architect.md` | Terraform/Terragrunt IaC | `acceptEdits` |
+| gaia-planner | `agents/gaia-planner.md` | Feature planning, briefs, and task decomposition | `acceptEdits` |
+
+### Skills (24 directories + 1 top-level reference)
+
+| Skill | Type | Injection |
+|-------|------|-----------|
+| `agent-protocol/` | Protocol | Injected (all agents) |
+| `agent-response/` | Protocol | Injected (orchestrator) |
+| `approval/` | Technique | On-demand |
+| `blog-writing/` | Technique | Injected (gaia-operator) |
+| `command-execution/` | Discipline | Injected |
+| `context-updater/` | Protocol | Injected |
+| `developer-patterns/` | Domain | Injected (developer) |
+| `execution/` | Discipline | On-demand |
+| `fast-queries/` | Reference | Injected |
+| `gaia-patterns/` | Domain | Injected (gaia-system) |
+| `gaia-release/` | Technique | Injected (gaia-system) |
+| `git-conventions/` | Reference | On-demand |
+| `gitops-patterns/` | Domain | Injected (gitops-operator) |
+| `gmail-policy/` | Reference | Injected (orchestrator) |
+| `gmail-triage/` | Technique | Injected (gaia-operator) |
+| `gws-setup/` | Technique | On-demand |
+| `investigation/` | Technique | Injected |
+| `memory-curation/` | Reference | Injected (orchestrator) |
+| `orchestrator-approval/` | Discipline | Injected (orchestrator) |
+| `security-tiers/` | Reference | Injected (all agents) |
+| `skill-creation/` | Technique | Injected (gaia-system) |
+| `terraform-patterns/` | Domain | Injected (terraform-architect) |
+| `skills/reference.md` | Reference | On-demand (shared security-tiers ref) |
+
+### Commands (slash commands)
+
+| Command | File | Purpose |
+|---------|------|---------|
+| `/gaia` | `commands/gaia.md` | Invoke gaia meta-agent |
+| `/scan-project` | `commands/scan-project.md` | Scan project, generate project-context.json |
+| `/gaia-plan` | `commands/gaia-plan.md` | Plan a feature, create brief, decompose into tasks |
+
+### Tools (7 subsystems)
+
+| Subsystem | Location | Purpose |
+|-----------|----------|---------|
+| context | `tools/context/` | `context_provider`, `context_section_reader`, `deep_merge`, `pending_updates`, `surface_router` |
+| fast-queries | `tools/fast-queries/` | Triage scripts for cloud/gitops/terraform/appservices |
+| gaia_simulator | `tools/gaia_simulator/` | Routing simulator: `cli`, `extractor`, `reporter`, `routing_simulator`, `runner`, `skills_mapper` |
+| memory | `tools/memory/` | `episodic` -- episodic memory store |
+| review | `tools/review/` | `review_engine` -- code review engine |
+| scan | `tools/scan/` | Project scanner: `orchestrator`, `registry`, `scanners/`, `config`, `merge`, `verify`, `walk`, `workspace`, `ui` |
+| validation | `tools/validation/` | `approval_gate`, `validate_skills` |
+| (top-level) | `tools/persist_transcript_analysis.py` | Transcript persistence utility |
+
+### CLI Tools (10 bin commands + 1 wrapper)
+
+| Command | File | Purpose |
+|---------|------|---------|
+| `gaia-doctor` | `bin/gaia-doctor.js` | Health check: hooks, symlinks, Python, config |
+| `gaia-skills-diagnose` | `bin/gaia-skills-diagnose.js` | Skills injection diagnostics |
+| `gaia-cleanup` | `bin/gaia-cleanup.js` | Remove symlinks and settings (preuninstall) |
+| `gaia-uninstall` | `bin/gaia-uninstall.js` | Full uninstall |
+| `gaia-metrics` | `bin/gaia-metrics.js` | Usage metrics and analytics |
+| `gaia-review` | `bin/gaia-review.js` | Code review utility |
+| `gaia-status` | `bin/gaia-status.js` | Installation status report |
+| `gaia-history` | `bin/gaia-history.js` | Session history viewer |
+| `gaia-update` | `bin/gaia-update.js` | Postinstall: symlinks, settings merge, verification |
+| `gaia-scan` | `bin/gaia-scan` | Shell wrapper for `gaia-scan.py` |
+| `gaia-scan.py` | `bin/gaia-scan.py` | Project scanner (Python implementation) |
+| `pre-publish-validate` | `bin/pre-publish-validate.js` | Pre-publish validation (not a bin export) |
+
+### Config Files
+
+| File | Purpose |
+|------|---------|
+| `config/universal-rules.json` | Rules shared by both plugin modes |
+| `config/context-contracts.json` | Context injection contracts per agent |
+| `config/surface-routing.json` | Surface routing table (intent to agent mapping) |
+| `config/git_standards.json` | Git commit and branch standards |
+| `config/cloud/aws.json` | AWS service patterns and commands |
+| `config/cloud/gcp.json` | GCP service patterns and commands |
+
+---
+
+## 2. Plugin Modes
+
+| Mode | Package | What ships |
+|------|---------|-----------|
+| `gaia-ops` | `@jaguilar87/gaia` (full) | All hooks, all modules, all agents, all skills, all commands, all tools, all config |
+| `gaia-security` | `@jaguilar87/gaia` (security dist) | 5 hooks (`pre_tool_use`, `post_tool_use`, `stop_hook`, `user_prompt_submit`, `session_start`), all modules, no agents, no skills, `config/universal-rules.json` only |
+
+### Detection Cascade (`hooks/modules/core/plugin_mode.py`)
+
+```
+1. plugin-registry.json    -- checks installed[].name for "gaia-ops" or "gaia-security"
+2. CLAUDE_PLUGIN_ROOT + plugin.json  -- reads .claude-plugin/plugin.json name field
+3. NPM package path        -- inspects node_modules path for package name
+4. GAIA_PLUGIN_MODE env    -- explicit override ("security" or "ops")
+5. Default: "security"     -- most restrictive fallback
+```
+
+### Mode Behavioral Differences
+
+| Behavior | `security` mode | `ops` mode |
+|----------|----------------|------------|
+| T3 approval | Claude Code native dialog (`permissionDecision: ask`) | Hook blocks with nonce, orchestrator approval flow |
+| Agents | None | 8 agents routed by orchestrator |
+| Skills | None | 24 skills injected per frontmatter |
+| Commands | None | 7 slash commands |
+| PreToolUse matchers | `Bash` only | `Bash`, `Task`, `Agent`, `SendMessage`, multi-tool |
+| File write protection | `_is_protected()` blocks hooks/ and settings*.json for Edit/Write tools | Same -- fires regardless of permissionMode |
+
+### Security Tiers (quick reference)
+
+| Tier | Name | Side Effects | Approval |
+|------|------|-------------|----------|
+| T0 | Read-Only | None | No |
+| T1 | Validation | None (local) | No |
+| T2 | Simulation | None (dry-run) | No |
+| T3 | Realization | Modifies state | Yes |
+
+Enforcement: `blocked_commands.py` (permanent deny) + `mutative_verbs.py` (nonce-based approval). Everything not blocked and not mutative is safe by elimination.
+
+---
+
+## 3. Build / Publish Pipeline
+
+### Build
+
+```
+scripts/build-plugin.py <plugin-name> [--output-dir <path>]
+```
+
+1. Reads `build/<plugin-name>.manifest.json`
+2. Resolves `"all"` to concrete file lists
+3. Copies to `dist/<plugin-name>/`
+4. Generates `hooks.json` and `settings.json` from manifest
+
+### Publish
+
+```
+npm run build:plugins          # builds both gaia-security + gaia-ops to dist/
+npm run pre-publish:validate   # validates dist/ contents
+npm run prepublishOnly         # build + validate (automatic before npm publish)
+npm publish                    # publishes @jaguilar87/gaia
+```
+
+### Postinstall (`bin/gaia-update.js`, runs on `npm install`)
+
+**First install** (no `.claude/`):
+1. Check Python 3 available
+2. Run `gaia-scan --npm-postinstall` to create `.claude/`, symlinks, settings, project-context
+3. Create `plugin-registry.json`
+4. Merge permissions into `settings.local.json`
+5. Merge hooks into `settings.local.json` -- also writes `defaultMode: acceptEdits` to `settings.local.json` for the parent session
+6. Verification
+
+**Update** (`.claude/` exists):
+1. Show version transition
+2. `settings.json`: create only if missing (non-invasive)
+3. Merge permissions, env vars, agent key into `settings.local.json` (union, preserves user config)
+4. Merge hooks from `hooks.json` into `settings.local.json`
+5. Recreate/fix broken symlinks
+6. Verify hooks, Python, project-context, config
+
+### Symlinks Created
+
+```
+.claude/agents   -> node_modules/@jaguilar87/gaia/agents/
+.claude/hooks    -> node_modules/@jaguilar87/gaia/hooks/
+.claude/skills   -> node_modules/@jaguilar87/gaia/skills/
+.claude/tools    -> node_modules/@jaguilar87/gaia/tools/
+.claude/commands -> node_modules/@jaguilar87/gaia/commands/
+.claude/config   -> node_modules/@jaguilar87/gaia/config/
+```
+
+---
+
+## 4. Test Pyramid
+
+### Layers
+
+| Layer | Command | Cost | Speed | Count |
+|-------|---------|------|-------|-------|
+| L1 | `npm test` | Free | ~0.25s | ~1462 |
+| L2 | `npm run test:layer2` | ~$0.10 | Minutes | ~11 |
+| L3 | `npm run test:layer3` | Free | Minutes | ~13 |
+
+### L1 Categories (46 test files)
+
+| Category | Directory | What it tests |
+|----------|-----------|---------------|
+| Prompt regression | `tests/layer1_prompt_regression/` | Routing table, skill content rules, agent frontmatter, agent prompts, security tier consistency, skills cross-reference, context contracts |
+| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, gitops_validator, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
+| System | `tests/system/` | Directory structure, permissions, agent definitions, configuration, schema compatibility |
+| Tools | `tests/tools/` | context_provider, episodic, pending_updates, deep_merge, review_engine, surface_router |
+| Integration | `tests/integration/` | Context enrichment, subagent lifecycle, subagent stop, nonce approval relay |
+| Performance | `tests/performance/` | Context injection benchmarks |
+| Cross-layer | `tests/test_cross_layer_consistency.py` | Consistency between hooks, config, and agents |
+
+### L2 (LLM Evaluation)
+
+| File | What it tests |
+|------|---------------|
+| `tests/layer2_llm_evaluation/test_agent_behavior.py` | Agent response quality via LLM judge |
+
+### L3 (End-to-End)
+
+| File | What it tests |
+|------|---------------|
+| `tests/layer3_e2e/test_installation_smoke.py` | npm install in /tmp/, symlinks, settings, hooks |
+| `tests/layer3_e2e/test_hook_lifecycle.py` | Full hook lifecycle: pre/post tool use, session |
+
+### Which Tests for Which Changes
+
+| Change | Run |
+|--------|-----|
+| Hook module (security, tools, core) | `pytest tests/hooks/ -v` |
+| Agent definition (.md) | `pytest tests/layer1_prompt_regression/ tests/system/ -v` |
+| Skill content | `pytest tests/layer1_prompt_regression/ -v` |
+| Config file | `pytest tests/system/ tests/test_cross_layer_consistency.py -v` |
+| Context/routing | `pytest tests/tools/ tests/integration/ -v` |
+| CLI tool (bin/) | `pytest tests/layer3_e2e/ -v -m e2e` |
+| Any change (pre-commit) | `npm test` (full L1) |
+| Pre-publish | `npm run build:plugins && npm run pre-publish:validate` |
+
+---
+
+## 5. CLI Tools
+
+| Command | Purpose | When to use |
+|---------|---------|-------------|
+| `npx gaia-doctor` | Health check: hooks reachable, symlinks valid, Python available, config present | After install, after update, debugging |
+| `npx gaia-skills-diagnose` | Skills injection: verifies frontmatter, SKILL.md presence, injection pipeline | Skills not loading, wrong skills in agent |
+| `npx gaia-status` | Installation status: version, mode, symlinks, settings | Quick status check |
+| `npx gaia-metrics` | Usage analytics: hook invocations, tier distribution, approval rates | Performance analysis |
+| `npx gaia-review` | Code review utility | PR review |
+| `npx gaia-history` | Session history viewer | Debugging past sessions |
+| `npx gaia-update` | Re-run postinstall: fix symlinks, merge settings | Manual repair |
+| `npx gaia-cleanup` | Remove symlinks and settings (runs on preuninstall) | Before uninstall |
+| `npx gaia-uninstall` | Full uninstall: cleanup + remove package artifacts | Complete removal |
+| `npx gaia-scan` | Project scanner: detect stack, generate project-context.json | New project setup |
+| `node bin/pre-publish-validate.js` | Validate dist/ before npm publish | Release workflow |
+
+---
+
+## 6. Metrics and Anomaly Detection
+
+| Module | What It Tracks |
+|--------|----------------|
+| `audit/metrics.py` | Hook invocations, tier distribution, approval rates |
+| `audit/event_detector.py` | Anomalous patterns in agent behavior |
+| `audit/workflow_auditor.py` | Workflow compliance and audit trail |
+| `npx gaia-metrics` | CLI access to collected metrics |
+
+---
+
+## 7. Dev Workflow
+
+### Dev Mode (symlinks to source)
+
+```bash
+# In any project directory:
+ln -sf /home/jorge/ws/me/gaia-dev/agents   .claude/agents
+ln -sf /home/jorge/ws/me/gaia-dev/hooks    .claude/hooks
+ln -sf /home/jorge/ws/me/gaia-dev/skills   .claude/skills
+ln -sf /home/jorge/ws/me/gaia-dev/tools    .claude/tools
+ln -sf /home/jorge/ws/me/gaia-dev/commands .claude/commands
+ln -sf /home/jorge/ws/me/gaia-dev/config   .claude/config
+```
+
+Changes to source files take effect immediately (no build step).
+
+### Release Mode (npm install)
+
+```bash
+npm install @jaguilar87/gaia
+# postinstall creates symlinks: .claude/* -> node_modules/@jaguilar87/gaia/*
+```
+
+### Test Isolation
+
+```bash
+cd /tmp
+mkdir test-project && cd test-project
+npm init -y
+npm install ~/ws/me/gaia-dev        # installs from local source
+npx gaia-doctor                      # verify installation
+npm test                             # run L1 suite from gaia-dev
+```
+
+### Version Bump + Publish
+
+```bash
+npm version patch|minor|major        # bump in package.json
+npm run build:plugins                 # rebuild dist/
+npm run pre-publish:validate          # validate
+npm publish                           # publish to npm
+```
+
+---
+
+## 8. Validation Tools
+
+### Routing Simulator
+
+```bash
+python3 tools/gaia_simulator/cli.py "deploy the terraform changes"
+```
+
+Tests the surface-routing pipeline: prompt -> intent extraction -> agent selection. Validates that `config/surface-routing.json` routes correctly without invoking any agent.
+
+Components: `cli.py` (entry), `routing_simulator.py` (engine), `extractor.py` (intent), `skills_mapper.py` (skill resolution), `runner.py` (batch), `reporter.py` (output).
+
+### Transcript Analyzer
+
+```bash
+# Within hooks, automatically invoked by subagent_stop
+hooks/modules/agents/transcript_analyzer.py
+```
+
+Analyzes agent transcripts for contract compliance, skill adherence, and behavioral patterns. Used by `subagent_stop.py` to validate agent output. Paired with `transcript_reader.py` for parsing.
+
+### Skills Diagnostics
+
+```bash
+npx gaia-skills-diagnose
+```
+
+Validates the full skills pipeline: frontmatter declarations, SKILL.md file presence, injection chain integrity, on-demand vs injected classification.
+
+### Approval Gate
+
+```bash
+python3 tools/validation/approval_gate.py
+```
+
+Validates T3 approval nonce lifecycle: generation, scope matching, expiry, grant/deny.
+
+### Doctor
+
+```bash
+npx gaia-doctor
+```
+
+Full system health: hook reachability (all 10 entry points), symlink integrity, Python environment, config file presence, settings.json/settings.local.json correctness.

package/skills/gaia-planner/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gaia-planner
+description: Use when planning features or decomposing work into tasks from a brief
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Gaia Planner
+
+Plan creation from briefs. The planner produces plan.md and returns it
+to the orchestrator. The orchestrator owns task dispatch and execution.
+
+## When to Activate
+
+- A brief.md exists and needs to become an execution plan
+- A plan.md needs revision or restructuring
+
+## Create Plan
+
+Read the brief.md. Decompose into tasks. Write plan.md using the
+plan structure defined in `reference.md`. For the full decomposition
+process and task rules, see `reference.md`.
+
+**Quick path:** Read brief -> decompose into tasks -> write plan.md
+-> return plan.md to orchestrator.
+
+Each task in plan.md carries: goal, AC with verify command, agent
+assignment, context slice, and dependencies. This gives the orchestrator
+everything it needs to dispatch using its own goal+AC model.
+
+## Anti-Patterns
+
+- **Dispatching agents** -- the planner writes the plan; the orchestrator dispatches. If you have Agent() in your tools, something is wrong.
+- **Fat tasks** -- a task needing more than one context window forces the agent to lose track. Split it.
+- **Thin tasks** -- a task without its own context slice forces the agent to read the full brief. Inline the slice.
+- **Vague ACs** -- every task needs a verify command the orchestrator can run post-dispatch. No verify command = no way to confirm completion.

package/skills/gaia-planner/reference.md

@@ -0,0 +1,107 @@
+# Gaia Planner -- Reference
+
+## Phase 1: Create Plan
+
+### Step 1: Read the Brief
+
+Read the brief.md provided by the orchestrator. Extract:
+- Objectives and approach
+- Acceptance criteria: id, description, evidence{type, shape}, artifact
+- Constraints from project-context
+- Out of scope boundaries
+
+Every task you write must cite which brief AC-id(s) it satisfies. A task
+with no AC-id satisfies nothing observable; split or delete it.
+
+No brief -> BLOCKED. Tell the orchestrator to create one first (brief-spec skill).
+
+### Step 2: Decompose into Tasks
+
+Each task MUST:
+- **Fit in one context window.** If you need to say "see also", split it.
+- **Name its agent target.** Route by domain: terraform keywords -> terraform-architect, k8s/helm -> gitops-operator, code/test/build -> developer, gaia internals -> gaia-system.
+- **Carry its own context slice.** The agent receives the task description, not the brief. Inline relevant constraints, file paths, and tech stack.
+- **Cite the brief AC-ids it satisfies.** Every task lists `satisfies: [AC-1, AC-3]`. Unreferenced tasks get removed; uncovered ACs get new tasks.
+- **Have a task-level AC with a command.** Binary pass/fail, internal to the task (build green, test passes, file exists).
+- **Inherit the evidence slot from the brief AC.** The task AC is the technical proof (e.g. `pytest tests/auth/ -q` exits 0); the brief AC (e.g. login URL flow) is verified separately by the orchestrator post-dispatch.
+
+Two AC levels, one per layer:
+- **Brief AC (product):** what the user observes. Verified once, post-execution.
+- **Task AC (technical):** what the agent must produce. Verified per task.
+
+A feature is COMPLETE only when every task AC passes AND every brief AC's
+evidence has been executed and persisted.
+
+Task sizing: aim for 2-5 minutes of agent work. A task that takes 15 minutes
+is three tasks that should have been split.
+
+### Step 3: Write plan.md
+
+Use the structure below. Write plan.md to the same directory as the brief.
+Do not reconstruct the path from the feature name -- read the brief's actual
+directory path (which may have any prefix: `open_`, `in-progress_`, `closed_`)
+and write plan.md there. This keeps the skill prefix-tolerant.
+
+If the directory does not exist yet, default to:
+`.claude/project-context/briefs/open_{feature-name}/plan.md`
+
+## Plan Structure
+
+```markdown
+---
+status: draft
+brief: ./brief.md
+created: {date}
+---
+
+# Plan: {Feature Name}
+
+## Approach
+{Technical strategy -- 3-5 sentences}
+
+## Tasks
+
+### T1: {Task title}
+- agent: {agent-type}
+- status: pending
+- satisfies: [AC-1, AC-2]   # brief AC-ids this task contributes to
+- AC: `{verify command}`    # task-level technical proof, binary pass/fail
+- blocked-by: none
+
+**Context:** {Inline context slice}
+**Change:** {Exact files + what changes}
+
+## Execution Order
+{Dependency graph}
+```
+
+Fill in:
+- Approach (technical strategy, 3-5 sentences)
+- Tasks with agent, status, AC, blocked-by, context, and change description
+- Execution order (dependency graph)
+
+### Step 4: Task List Checkpoint
+
+Before executing any tasks, present the complete task list and wait for
+confirmation. The checkpoint must show:
+
+- Task number, title, and target agent
+- Dependencies (blocked-by relationships)
+- Execution order
+
+Ask: "Here are the tasks I plan to execute. Confirm to proceed, or
+suggest changes." Do not dispatch until the user confirms.
+
+## Agent Routing Reference
+
+Use this table to assign agent types to tasks in plan.md. The orchestrator
+uses these assignments when dispatching.
+
+| Domain Signal | Agent |
+|---------------|-------|
+| Terraform, IaC, cloud resources | `terraform-architect` |
+| Kubernetes, Helm, Flux, manifests | `gitops-operator` |
+| Live cluster, pods, logs, diagnostics | `cloud-troubleshooter` |
+| App code, tests, CI/CD, Docker | `developer` |
+| Gaia hooks, skills, agents, routing | `gaia-system` |
+| Workspace, memory, email, automation | `gaia-operator` |

package/skills/gaia-release/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: gaia-release
+description: Use when testing, validating, or publishing Gaia releases (live testing, dry-run, beta, stable)
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Gaia Release
+
+Each mode tests a different surface. Live tests your code changes in your real workspace. Dry-run tests the install pipeline in an ephemeral sandbox. Beta and release test the distribution channel. Skipping a layer means discovering its bugs in production -- a live install over an existing workspace does not predict a missing file in `package.json`'s `files` array on a clean project, and a clean dry-run does not prove npm registry delivery works.
+
+## Decision Tree
+
+```
+"I want to test Gaia"
+├─ Quick iteration on code? -> live (LOCAL)
+├─ Validate before publishing? -> dry-run (LOCAL)
+├─ Share pre-release with testers? -> beta (PIPELINE)
+└─ Ship to all users? -> release (PIPELINE)
+```
+
+## Mode: live
+
+Fresh tarball install over the current workspace -- packs the working tree and installs it like a real consumer would, but into the user's `.claude/` so restarts pick it up.
+
+**When:** "test here", "try this out", "put it in live mode"
+
+1. From the gaia-ops-dev repo root, run: `npm run gaia:install-local`
+   - Runs `npm pack` to build the tarball from the working tree
+   - Invokes `bin/validate-sandbox.sh --target local` which detects the workspace (walk-up from cwd for a `.claude/` with a Gaia instance marker, falling back to `$HOME/ws/me/` if present), installs the tarball there, and runs the 8-check harness (settings-preservation check is skipped -- no pre-snapshot possible for a real workspace).
+   - Pass `--workspace <path>` to `bin/validate-sandbox.sh` directly to override auto-detection when you want to install into a specific project.
+2. Tell user: "Gaia fresh-installed locally from dev working tree. Restart Claude Code to activate."
+
+**Default path:** Detected by the harness. Nearest `.claude/` ancestor of cwd with a Gaia marker, otherwise `$HOME/ws/me/` if present. Override with `--workspace <path>`.
+
+**Revert:** `npm install @jaguilar87/gaia@rc` (or `@latest`) over the same workspace -- the next install wins.
+
+Re-run `npm run gaia:install-local` whenever you want the workspace to pick up new edits from the working tree.
+
+Live mode does not test build output's consumer path end-to-end in a clean project -- dry-run (`gaia:verify-install:local` -> sandbox in `/tmp/`) does.
+
+## Mode: dry-run
+
+Validates the full install flow without publishing. Tests exactly what `npm publish` would ship.
+
+**When:** "test the install", "dry-run", "validate before release"
+
+Core sequence: build plugins -> validate build -> `npm pack` -> install .tgz in clean `/tmp/` project -> run `gaia-doctor` + `gaia-status` -> test both plugin modes (ops and security).
+
+For step-by-step commands, see `reference.md`.
+
+Test both modes: default (ops) validates orchestration and delegation. Security mode (`GAIA_PLUGIN_MODE=security`) validates the stripped-down path with no agents and native T3 dialog. A change that works in one mode can break the other because they load different skill sets and hook configurations.
+
+## Mode: beta
+
+Pre-release published to npm via GitHub Actions. Install with `@beta` tag.
+
+**When:** "publish beta", "beta release", "pre-release"
+
+Dry-run must pass first. Then: bump version with beta pre-release tag -> merge PR to `main` -> create GitHub Release with beta version tag -> `publish.yml` triggers automatically.
+
+For version bump details and verification steps, see `reference.md`.
+
+## Mode: release
+
+Stable release published to npm via GitHub Actions. Install with `@latest` tag.
+
+**When:** "publish release", "stable release", "ship it"
+
+Same flow as beta with a stable version bump. The pipeline owns publishing -- `NPM_TOKEN` is in GitHub Secrets.
+
+For step-by-step commands, see `reference.md`.
+
+## Pipeline: publish.yml
+
+Triggered by GitHub Release events. Builds plugins, validates artifacts, auto-detects npm tag from version string (`-beta.` -> beta, `-rc.` -> rc, else -> latest), and publishes. Details in `reference.md`.
+
+## Anti-Patterns
+
+- **Live-only testing** -- live tests the tarball on your actual workspace but with your accumulated state; an ephemeral sandbox (`gaia:verify-install:local`) is still needed to prove a clean-install works.
+- **Local npm publish** -- the pipeline owns publishing; local publish bypasses build verification.
+- **Single-mode testing** -- ops and security load different configurations; one can break independently.
+- **Stale dist/** -- forgetting `npm run build:plugins` before pack means validating old code.
+- **Missing restart** -- the process caches skills at startup; mode switches require restart.