@jaguilar87/gaia 5.0.0-rc.2

package/index.js

@@ -0,0 +1,83 @@
+/**
+ * @jaguilar87/gaia
+ *
+ * Multi-agent orchestration system for Claude Code - DevOps automation toolkit
+ *
+ * Usage:
+ *   import { getAgentPath, getToolPath, getConfigPath } from '@jaguilar87/gaia';
+ *   const agentPath = getAgentPath('gitops-operator');
+ *   const toolPath = getToolPath('context_provider.py');
+ *   const configPath = getConfigPath('git_standards.json');
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const PACKAGE_ROOT = __dirname;
+
+/**
+ * Get absolute path to an agent definition
+ * @param {string} agentName - Name of the agent (e.g., 'gitops-operator')
+ * @returns {string} Absolute path to agent file
+ */
+export function getAgentPath(agentName) {
+  return join(PACKAGE_ROOT, 'agents', `${agentName}.md`);
+}
+
+/**
+ * Get absolute path to a tool
+ * @param {string} toolName - Name of the tool (e.g., 'context_provider.py')
+ * @returns {string} Absolute path to tool file
+ */
+export function getToolPath(toolName) {
+  return join(PACKAGE_ROOT, 'tools', toolName);
+}
+
+/**
+ * Get absolute path to a hook
+ * @param {string} hookName - Name of the hook (e.g., 'pre-commit')
+ * @returns {string} Absolute path to hook file
+ */
+export function getHookPath(hookName) {
+  return join(PACKAGE_ROOT, 'hooks', hookName);
+}
+
+/**
+ * Get absolute path to a command
+ * @param {string} commandName - Name of the command (e.g., 'architect.md')
+ * @returns {string} Absolute path to command file
+ */
+export function getCommandPath(commandName) {
+  return join(PACKAGE_ROOT, 'commands', commandName);
+}
+
+/**
+ * Get absolute path to a template
+ * @param {string} templateName - Name of the template (e.g., 'governance.template.md')
+ * @returns {string} Absolute path to template file
+ */
+export function getTemplatePath(templateName) {
+  return join(PACKAGE_ROOT, 'templates', templateName);
+}
+
+/**
+ * Get absolute path to config file
+ * @param {string} configName - Name of the config (e.g., 'git_standards.json')
+ * @returns {string} Absolute path to config file
+ */
+export function getConfigPath(configName) {
+  return join(PACKAGE_ROOT, 'config', configName);
+}
+
+export default {
+  PACKAGE_ROOT,
+  getAgentPath,
+  getToolPath,
+  getHookPath,
+  getCommandPath,
+  getTemplatePath,
+  getConfigPath
+};

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@jaguilar87/gaia",
+  "version": "5.0.0-rc.2",
+  "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "gaia": "bin/gaia",
+    "gaia-doctor": "bin/gaia-doctor.js",
+    "gaia-skills-diagnose": "bin/gaia-skills-diagnose.js",
+    "gaia-cleanup": "bin/gaia-cleanup.js",
+    "gaia-uninstall": "bin/gaia-uninstall.js",
+    "gaia-metrics": "bin/gaia-metrics.js",
+    "gaia-review": "bin/gaia-review.js",
+    "gaia-status": "bin/gaia-status.js",
+    "gaia-history": "bin/gaia-history.js",
+    "gaia-update": "bin/gaia-update.js",
+    "gaia-scan": "bin/gaia-scan",
+    "gaia-evidence": "bin/gaia-evidence"
+  },
+  "keywords": [
+    "claude-code",
+    "devops",
+    "gitops",
+    "terraform",
+    "kubernetes",
+    "ai-agents",
+    "gaia",
+    "orchestration",
+    "automation"
+  ],
+  "author": "Jorge Aguilar <jorge.aguilar87@gmail.com>",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metraton/gaia.git"
+  },
+  "homepage": "https://github.com/metraton/gaia#readme",
+  "bugs": {
+    "url": "https://github.com/metraton/gaia/issues",
+    "email": "jorge.aguilar87@gmail.com"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "agents/",
+    "tools/",
+    "hooks/",
+    "commands/",
+    "templates/",
+    "config/",
+    "skills/",
+    "dist/",
+    "git-hooks/",
+    "README.md",
+    "INSTALL.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "pyproject.toml",
+    "index.js"
+  ],
+  "scripts": {
+    "test": "python3 -m pytest tests/ -v --ignore=tests/layer2_llm_evaluation --ignore=tests/layer3_e2e",
+    "test:layer1": "python3 -m pytest tests/ -v --ignore=tests/layer2_llm_evaluation --ignore=tests/layer3_e2e",
+    "test:layer2": "python3 -m pytest tests/layer2_llm_evaluation/ -v -m llm",
+    "test:layer3": "python3 -m pytest tests/layer3_e2e/ -v -m e2e",
+    "test:all": "python3 -m pytest tests/ -v -m ''",
+    "test:promptfoo": "npx promptfoo eval --config tests/promptfoo.yaml",
+    "lint": "eslint .",
+    "clean:dist": "rm -rf dist/",
+    "build:plugins": "npm run clean:dist && python3 scripts/build-plugin.py gaia-security && python3 scripts/build-plugin.py gaia-ops",
+    "clean": "find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true",
+    "pre-publish": "node bin/pre-publish-validate.js",
+    "pre-publish:dry": "node bin/pre-publish-validate.js --dry-run",
+    "pre-publish:validate": "node bin/pre-publish-validate.js --validate-only",
+    "gaia:verify-install:local": "npm pack && bash bin/validate-sandbox.sh --tarball ./jaguilar87-gaia-*.tgz --target sandbox",
+    "gaia:verify-install:rc": "bash bin/validate-sandbox.sh --version @rc --target sandbox",
+    "gaia:verify-install:latest": "bash bin/validate-sandbox.sh --version @latest --target sandbox",
+    "gaia:install-local": "npm pack && bash bin/validate-sandbox.sh --tarball ./jaguilar87-gaia-*.tgz --target local",
+    "prepack": "npm run clean",
+    "prepublishOnly": "npm run build:plugins && node bin/pre-publish-validate.js",
+    "postinstall": "node bin/gaia-update.js",
+    "preuninstall": "node bin/gaia-cleanup.js"
+  },
+  "_postinstall_note": "postinstall: settings.json replaced (hooks only), permissions merged into settings.local.json (union, user config preserved)",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "ora": "^7.0.1",
+    "prompts": "^2.4.2",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "eslint": "^8.50.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "python": ">=3.9"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "gaia"
+version = "5.0.0-rc.2"
+description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Jorge Aguilar", email = "jorge.aguilar87@gmail.com"},
+]
+readme = "README.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4.0",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "tools/scan/tests"]
+markers = [
+    "parity: JS-Python CLI parity comparison tests",
+]

package/skills/README.md

@@ -0,0 +1,158 @@
+# Skills
+
+Skills are the procedural knowledge layer of Gaia. Where agents carry identity — their scope, their tone, their domain — skills carry process: how to classify a command, how to format a response contract, how to approach an investigation. An agent without skills knows who it is but not how to operate. Skills bridge that gap by injecting step-by-step protocols that the agent follows during its session.
+
+Each skill lives in its own directory under `skills/<name>/` and contains at minimum a `SKILL.md` file. That file is what gets injected. Supporting material (`reference.md`, `examples.md`) lives in the same directory but is read on-demand — the agent pulls it from disk when needed rather than receiving it at startup. This keeps startup context lean while making full documentation accessible.
+
+Skills are not shared via inheritance or imports — they are text injected verbatim into the agent's context window. The size limit for injected skills is roughly 100 lines. If a skill grows beyond that, the detailed content moves to `reference.md` and the main `SKILL.md` becomes a compact index pointing there.
+
+The assignment matrix below shows which skills each agent receives. The first two — `agent-protocol` and `security-tiers` — appear on every agent. They are the non-negotiables: every agent must understand the response contract and the tier system.
+
+## Cuándo se activa
+
+Skills reach an agent through two distinct routes, and understanding both matters when troubleshooting why a skill is or is not present in a session.
+
+**Route 1 — Startup injection via frontmatter:**
+
+```
+Orchestrator dispatches agent
+        |
+pre_tool_use.py intercepts the Task/Agent tool call
+        |
+Reads agents/<name>.md frontmatter -> skills: list
+        |
+For each skill in the list:
+  reads skills/<skill>/SKILL.md from disk
+  appends content to agent's system context
+        |
+Agent starts with all listed skills already in context
+```
+
+**Route 2 — On-demand via Skill tool:**
+
+```
+Agent is running and encounters a situation
+requiring a workflow skill (e.g. approval, execution, git-conventions)
+        |
+Agent calls Skill tool: Skill("request-approval")
+        |
+Claude Code reads skills/request-approval/SKILL.md from disk
+        |
+Content is injected into the agent's active context window
+        |
+Agent follows the newly loaded protocol
+```
+
+Orchestrator-level skills (`agent-response`, `orchestrator-approval`) are always Route 2 — they are never in a frontmatter list, only loaded when the orchestrator needs to interpret a specific situation.
+
+## Qué hay aquí
+
+```
+skills/
+├── agent-creation/        # Coach skill: structure, tone, and component inventory for new specialist agents
+├── agent-protocol/        # Response contract format, state machine, error handling
+├── agent-response/        # Orchestrator: interpret agent json:contract responses
+├── agentic-loop/          # Iterative metric-driven improvement loop (on-demand injection)
+├── blog-writing/          # Blog article writing and publishing for metraton.github.io
+├── brief-spec/            # Brief and spec creation for features before planning
+├── command-execution/     # Defensive Bash execution, no-pipes discipline
+│   └── reference.md
+├── context-updater/       # CONTEXT_UPDATE format and writable sections contract
+│   └── examples.md
+├── developer-patterns/    # Application code patterns (Node.js, Python)
+├── execution/             # Post-approval execution discipline
+├── fast-queries/          # Quick diagnostic scripts for cloud/system state
+├── gaia-compact/          # Orchestrator: structured /compact prompt with preservation contract
+├── gaia-patterns/         # Gaia component patterns: hooks, agents, routing, CLI
+│   └── reference.md
+├── gaia-planner/          # Feature planning, briefs, task decomposition
+├── gaia-release/          # Gaia release pipeline: live, dry-run, beta, stable
+├── gaia-self-check/       # Validate internal consistency of the .claude/ installation
+├── gaia-verify/           # Verify a Gaia installation across delivery surfaces
+├── git-conventions/       # Conventional Commits (on-demand workflow skill)
+├── gitops-patterns/       # GitOps/Flux/Kubernetes patterns
+│   └── reference.md
+├── gmail-policy/          # Gmail domain policy (label-only, no delete)
+├── gmail-triage/          # Interactive Gmail inbox triage
+├── gws-setup/             # Google Workspace CLI (gws) installation and configuration
+├── investigation/         # Diagnosis methodology and pattern analysis
+├── memory-curation/       # Curate MEMORY.md index and topic files
+├── memory-search/         # Query episodic memory via `gaia memory` CLI
+├── orchestrator-approval/ # T3 approval presentation for orchestrator
+├── pending-approvals/     # Present and manage pending approval requests
+├── readme-writing/        # How to write READMEs for Gaia component folders
+├── request-approval/      # T3 approval-request workflow (attempt first, emit APPROVAL_REQUEST)
+│   ├── reference.md
+│   └── examples.md
+├── schedule-task/         # Dispatch parameter extraction and prompt templates
+├── security-tiers/        # T0-T3 classification + hook enforcement model
+│   └── reference.md
+├── session-reflection/    # End-of-session reflection on conversational arc
+├── skill-creation/        # How to design and write new skills
+├── terraform-patterns/    # Terraform/Terragrunt patterns
+│   └── reference.md
+└── reference.md           # Cross-skill reference index
+```
+
+## Convenciones
+
+**Skill assignment matrix:**
+
+| Agent | Core Skills | Domain Skills |
+|-------|-------------|---------------|
+| cloud-troubleshooter | agent-protocol, security-tiers, investigation, command-execution | context-updater, fast-queries |
+| terraform-architect | agent-protocol, security-tiers, investigation, command-execution, terraform-patterns | context-updater, fast-queries |
+| gitops-operator | agent-protocol, security-tiers, investigation, command-execution, gitops-patterns | context-updater, fast-queries |
+| developer | agent-protocol, security-tiers, investigation, command-execution, developer-patterns | context-updater, fast-queries |
+| gaia-system | agent-protocol, security-tiers, command-execution, gaia-patterns, gaia-release, skill-creation | gaia-verify |
+| gaia-planner | agent-protocol, security-tiers | gaia-planner |
+| gaia-operator | agent-protocol, security-tiers, command-execution, context-updater, memory-curation, memory-search, gmail-triage, gws-setup | blog-writing |
+
+Orchestrator skills (loaded on-demand via Skill tool, not assigned in frontmatter):
+- `agent-response` — contract status interpretation and presentation
+- `orchestrator-approval` — T3 approval presentation and grant activation
+- `gaia-compact` — structured `/compact` invocation with a six-category preservation prompt
+
+Workflow skills (on-demand injection, not in any agent frontmatter):
+- `agent-creation` — coach skill for creating specialist agents; loaded on demand by gaia-system, `user-invocable: false`
+- `agentic-loop` — iterative metric-driven improvement; injected by orchestrator text prompt, `user-invocable: false`
+- `brief-spec` — brief and spec creation; loaded on demand by orchestrator
+- `execution` — post-approval execution discipline
+- `git-conventions` — Conventional Commits format
+- `pending-approvals` — present and resolve pending approval requests
+- `request-approval` — T3 approval-request workflow
+- `schedule-task` — dispatch parameter templates
+- `session-reflection` — end-of-session reflection; loaded on demand by orchestrator at Cerrar la sesión
+
+**Skill types:**
+
+| Type | Injection | Examples |
+|------|-----------|---------|
+| Core | Always via `skills:` frontmatter | agent-protocol, security-tiers |
+| Common | Most agents via `skills:` frontmatter | command-execution, context-updater |
+| Domain | Per-agent via `skills:` frontmatter | terraform-patterns, gaia-patterns |
+| Workflow | On-demand (agent reads from disk) | request-approval, execution, git-conventions |
+| Orchestrator | On-demand via Skill tool | agent-response, orchestrator-approval |
+
+**SKILL.md format:**
+
+```yaml
+---
+name: skill-name
+description: When Claude should load and follow this skill
+metadata:
+  user-invocable: false
+  type: core
+---
+
+# Skill Content
+```
+
+**Line budget:** Keep injected `SKILL.md` under 100 lines. Move details to `reference.md` (read on-demand). Supporting examples go in `examples.md`.
+
+## Ver también
+
+- [`agents/README.md`](../agents/README.md) — agent frontmatter and skills: field
+- [`hooks/pre_tool_use.py`](../hooks/pre_tool_use.py) — where skill injection happens at runtime
+- [`skills/skill-creation/SKILL.md`](./skill-creation/SKILL.md) — how to design a new skill
+- [`skills/gaia-patterns/reference.md`](./gaia-patterns/reference.md) — full component inventory

package/skills/agent-creation/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: agent-creation
+description: Use when creating a new specialist agent for Gaia, or reviewing whether an existing agent follows the correct structure, tone, and component inventory
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Agent Creation
+
+## What is an agent?
+
+A specialist agent is a persistent identity with its own tool set, scope, and output contract. The identity is what separates it from a skill or inline behavior: an agent acts from a role, not just follows a process. If the component you are building has no distinct output type, no delegation surface, and could work as injected text, it is a skill, not an agent. That decision belongs upstream -- this skill assumes it has already been made.
+
+## Step 1:  Answer the 3 bifurcating dimensions
+
+Answer these before writing a single line. They determine which components are required, what the tool set looks like, and what the failure model must handle.
+
+**D1: Does the agent mutate system state?**
+A "yes" means: Write/Edit in tools, `permissionMode: acceptEdits` in frontmatter, T3 approval flow in failure handling, and an output type that says "Realization Package" rather than "Diagnostic Report."
+A "no" means: `disallowedTools` should explicitly exclude Write/Edit/NotebookEdit, no T3 surface in failure handling, and output is always read-only.
+
+**D2: Does the agent delegate to other agents?**
+Almost always "no" for specialists -- they are terminal nodes. A "yes" adds a delegation table to the body. A "no" still needs a CANNOT DO -> DELEGATE table for the orchestrator's benefit, but the agent itself never dispatches.
+
+**D3: Does the agent enter the orchestrator's automatic routing?**
+Almost always "yes." A "yes" means the description field must be written as triggering conditions (not a role summary), and surface signals should be proposed for `surface-routing.json`. Those signals are proposals -- gaia-system applies them; this skill only guides what to propose.
+
+## Step 2: Apply the component inventory
+
+**Obligatory in every specialist:**
+
+1. **Frontmatter**: `name`, `description` (triggering conditions only), `model`, `tools`, `color`. Add `permissionMode: acceptEdits` if D1=yes. Add `disallowedTools` if D1=no and enforcement matters. Add `maxTurns` for long-running agents.
+2. **Identity** (1-2 paragraphs): what this agent *is*, not what it does. Carries enough weight that removing it would change behavior -- see Step 4.
+3. **Workflow** (numbered steps): the operational sequence for this agent's domain. Put this before Identity when the workflow is complex enough to be the agent's primary reference.
+4. **Scope -- CAN DO / CANNOT DO -> DELEGATE**: boundaries with reasons. Every entry in CANNOT DO must name a concrete delegate agent.
+5. **Failure handling / Domain Errors**: a table of concrete errors with concrete actions. "Report the error" is not an action.
+6. **Response protocol**: the agent must load `agent-protocol`. Reference it in the skills list; do not replicate its content.
+
+**Optional by dimension:**
+- **Delegation table** (D2=yes): which agents this specialist can dispatch, under what conditions.
+- **Surface signals** (D3=yes): proposed keyword patterns for the orchestrator's `surface-routing.json`. Write them as a proposal block -- gaia-system applies them.
+- **Domain reference inline**: domain-specific lookup tables or decision logic that applies only to this agent and does not warrant a skill.
+
+## Step 3: Write for judgment, not compliance
+
+Each obligatory component must carry enough weight to actually change behavior. The test: if the section were removed, would the agent behave differently? If not, the section is decorative.
+
+**Identity:** "You are a specialist in X" is baseline -- the LLM already knows what X specialists do. The identity must justify *why this agent exists as a distinct entity* -- what it sees that a generic assistant would miss, what constraint it operates under that shapes every decision. If the identity section were removed and the agent still behaved identically, it needs more weight.
+
+**Scope boundaries:** Each CANNOT DO entry needs enough specificity that the agent declines at the right moment, not one step too late. A boundary described only as a category ("cloud infrastructure") is weaker than one that names the decision point ("if the resource type is managed by IaC, creating it belongs to terraform-architect even if you need it as a prerequisite").
+
+**Failure handling:** A Domain Errors table that says "check logs" or "report the error" does nothing the agent would not do by default. Each row should describe what a naive agent would do wrong, and redirect to the correct action.
+
+**Output type declaration:** Specialists declare their output type explicitly ("Your output is always a Realization Package" / "Your output is always a Diagnostic Report"). This is not cosmetic -- it prevents the agent from producing hybrid outputs that neither commit nor diagnose.
+
+## Step 4: Write the description field as triggering conditions
+
+The description is what the orchestrator reads to decide when to dispatch. It must describe *when to use this agent*, not *what this agent is*. Summarizing the role in the description causes the orchestrator to satisfy itself with the summary and never dispatch.
+
+```yaml
+# Wrong -- describes the role
+description: Senior Terraform architect that manages cloud infrastructure lifecycle
+
+# Right -- triggering conditions
+description: Use when creating, modifying, or validating Terraform/Terragrunt configurations, or managing the infrastructure lifecycle via IaC
+```
+
+## Step 5: Evaluate the skills catalog and propose applicable skills
+
+Do not hardcode a mapping of tool to skill. Instead, evaluate the current catalog at `.claude/skills/` and propose which skills apply to this agent's tool set and domain. The catalog changes; a hardcoded mapping goes stale silently.
+
+The evaluation should ask: which skills address a recurring risk or discipline gap for this agent's tool set? `agent-protocol` and `security-tiers` are non-negotiable for every agent. Beyond those, let the tool set and domain guide the selection.
+
+## Step 6: Propose surface signals (if D3=yes)
+
+For agents entering automatic routing, propose signal patterns for `surface-routing.json` -- high-confidence and medium-confidence keyword clusters that would reliably indicate this agent should handle the request. These are proposals: write them as a block the invoking agent (gaia-system) can apply directly. Do not apply them yourself.
+
+## Anti-patterns
+
+- **Treating this as a form**: filling in sections without testing whether each one carries enough weight to change behavior produces a well-structured agent that the LLM ignores and acts from baseline.
+- **Skipping the weight test**: an identity section that says "You are a specialist in X" is decorative. Test every section: if it were removed, would behavior change?
+- **Creating a new archetype**: the 3 bifurcating dimensions cover the full specialist space. Adding a new archetype ("Readonly Specialist", "Executor") when the dimensions already capture the distinction adds taxonomy without adding precision.
+- **Hardcoding the tool-to-skill mapping**: the skills catalog changes; a fixed mapping produces agents that reference non-existent skills or miss new ones that would help.
+- **Writing the description as a role summary**: the orchestrator reads the description to decide when to dispatch. A role summary satisfies the read without triggering the dispatch.
+- **Skipping disallowedTools for read-only agents**: not listing Write/Edit in `tools` is weaker than explicitly disallowing them. A future edit that adds a tool could silently give a read-only agent write access.
+- **Domain Errors that only say "report"**: every error row should redirect to a concrete action that a naive agent would not take by default.

package/skills/agent-creation/examples.md

@@ -0,0 +1,170 @@
+# Agent Creation -- Examples
+
+Two real Gaia agents analyzed by component. The goal is not to show "correct" vs "incorrect" -- both agents work well -- but to explain *why* each section was written the way it was, so you can apply the same reasoning to a new agent.
+
+---
+
+## Example 1: `developer` (D1=yes, D2=no, D3=yes)
+
+**Dimensions:**
+- D1=yes: writes files, runs tests, commits to VCS
+- D2=no: terminal node; CANNOT DO table is for orchestrator routing, not for the agent to dispatch
+- D3=yes: enters automatic routing for application code requests
+
+### Frontmatter
+
+```yaml
+---
+name: developer
+description: Full-stack software engineer for application code, CI/CD, and developer tooling across Node.js/TypeScript and Python stacks.
+tools: Read, Edit, Write, Agent, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
+model: inherit
+maxTurns: 50
+permissionMode: acceptEdits
+skills:
+  - agent-protocol
+  - security-tiers
+  - investigation
+  - command-execution
+  - developer-patterns
+  - context-updater
+  - fast-queries
+---
+```
+
+**Why `permissionMode: acceptEdits`:** D1=yes. Without this, every Edit/Write call inside `.claude/` would trigger a CC native permission prompt -- disruptive in headless sessions.
+
+**Why `maxTurns: 50` (not 40):** Investigation + code change + test run + potential fix loop can easily consume 40 turns. 50 gives the agent room to complete a debugging cycle without getting cut off mid-execution.
+
+**Why `Agent` in tools:** `developer` can spawn sub-investigations when the codebase is large enough to warrant parallel reads. Most specialists do not have this -- it adds surface area.
+
+**Why `investigation` and `fast-queries`:** Application bugs often require root cause analysis before a fix is possible. `investigation` provides the methodology; `fast-queries` provides the triage scripts. A specialist that writes code without these would often produce code that fixes the symptom rather than the cause.
+
+### Workflow
+
+```markdown
+## Workflow
+
+1. **Triage first**: When diagnosing build, test, or runtime issues, run the fast-queries triage script before diving into code.
+2. **Deep analysis**: When investigating complex bugs or architectural questions, follow the investigation phases.
+3. **Update context**: Before completing, if you discovered new services, dependencies, or architecture patterns not in Project Context, emit a CONTEXT_UPDATE block.
+```
+
+**Why workflow appears before identity:** The developer's primary risk is diving into code without understanding the problem first. Workflow at the top of the body is the first thing the agent reads -- it front-loads the "investigate before fixing" discipline where it needs to be, before the agent's momentum carries it toward implementation.
+
+### Identity
+
+```markdown
+## Identity
+
+You are a full-stack software engineer. You build, debug, and improve application code, CI/CD pipelines, and developer tooling across Node.js/TypeScript and Python stacks.
+
+**Your output is code or a report -- never both:**
+- **Realization Package:** new or modified code files, validated (lint + tests + build)
+- **Findings Report:** analysis and recommendations to stdout only -- never
+  create standalone report files (.md, .txt, .json)
+```
+
+**Why the output type declaration matters:** Without it, the agent commonly produces a hybrid: modifies files *and* writes a summary report. That ambiguity makes it unclear to the orchestrator whether the task is complete or still in analysis. The "never both" rule forces a clean state at completion. The "never create standalone report files" clause is specific enough to prevent the most common manifestation of hybrid output.
+
+**Weight test:** Remove the output type declaration. Does behavior change? Yes -- the agent would write summary files and return code changes in the same turn. The declaration passes the weight test.
+
+### Scope boundaries
+
+```markdown
+During investigation, if you discover that a resource type is managed by Terraform,
+Terragrunt, Helm, Flux, or any other IaC/GitOps tool, creating new instances of
+that resource belongs to the agent that owns that tool -- even if you need the
+resource as a prerequisite for your task.
+```
+
+**Why this paragraph exists:** The boundary "CANNOT DO: Terraform / cloud infrastructure → terraform-architect" is correct but weak. An agent working on a Node.js service that needs a database will rationalize "I just need one RDS instance, it's a prerequisite, I'll handle it." The paragraph names that exact decision point and explicitly forbids it. Without the paragraph, the boundary would be crossed at least some of the time.
+
+---
+
+## Example 2: `cloud-troubleshooter` (D1=no, D2=no, D3=yes)
+
+**Dimensions:**
+- D1=no: read-only enforced at frontmatter level via `disallowedTools`
+- D2=no: never dispatches other agents; surfaces recommendations back to orchestrator
+- D3=yes: enters automatic routing for cloud diagnostic requests
+
+### Frontmatter
+
+```yaml
+---
+name: cloud-troubleshooter
+description: Diagnostic agent for cloud infrastructure (GCP and AWS). Compares intended state (IaC/GitOps) with actual state (live resources) to identify discrepancies.
+tools: Read, Glob, Grep, Bash, Task, Skill
+model: inherit
+maxTurns: 40
+disallowedTools: [Write, Edit, NotebookEdit]
+skills:
+  - agent-protocol
+  - security-tiers
+  - investigation
+  - command-execution
+  - context-updater
+  - fast-queries
+---
+```
+
+**Why `disallowedTools` instead of just not listing Write/Edit:** Two layers of enforcement. Not listing Write/Edit in `tools` is the first layer -- the agent nominally does not have those tools. But `disallowedTools` adds a second layer: even if a future edit accidentally re-adds Write to the tools list, the disallow overrides it. For a read-only diagnostic agent operating on live cloud state, this matters. An accidental write to a live cloud resource is a non-trivial incident.
+
+**Why no `permissionMode`:** D1=no. `permissionMode: acceptEdits` would be misleading for an agent that must never write files.
+
+**Why no `investigation` skill... wait, it does have it:** Read-only diagnostic agents need investigation methodology even without mutation capabilities. The `investigation` skill teaches how to diagnose -- tool-independent.
+
+### Identity
+
+```markdown
+## Identity
+
+You are a **discrepancy detector**. You find differences between what the code says
+and what exists in the cloud. You operate in **strict read-only mode** -- T3 forbidden.
+
+**Your output is always a Diagnostic Report:**
+- Intended vs actual state, categorized by severity
+- Root cause candidates
+- Recommendations (you suggest, you never act):
+  - **Option A:** Sync code to live → invoke `terraform-architect` or `gitops-operator`
+  - **Option B:** Sync live to code → invoke `terraform-architect` or `gitops-operator`
+  - **Option C:** Further investigation needed
+```
+
+**Why "discrepancy detector" and not "cloud infrastructure specialist":** The more generic framing lets the agent drift toward fixing things. "Discrepancy detector" constrains the action space: the agent finds differences, it does not resolve them. The constraint is load-bearing -- remove it and the agent would occasionally attempt fixes when it detects an obvious misconfiguration.
+
+**Why the output options are named A/B/C:** The orchestrator reads this output and decides what to dispatch next. Consistent option labels (A/B/C) give the orchestrator a deterministic signal to act on. Without them, the recommendations would be prose that the orchestrator has to interpret differently each time.
+
+**Weight test:** Remove the "you never act" constraint from the output section. Would behavior change? Yes -- the agent would attempt to apply fixes directly (invoking `terraform-architect` from within itself, or in extreme cases, running mutative commands). The constraint passes.
+
+### Domain-specific section
+
+```markdown
+## Cloud Provider Detection
+
+Detect which CLI to use from project-context:
+
+| Indicator | Provider | CLI |
+|-----------|----------|-----|
+| `gcloud`, `gsutil`, `GKE`, `Cloud SQL` | GCP | `gcloud` |
+| `aws`, `eksctl`, `EKS`, `RDS`, `EC2` | AWS | `aws` |
+
+If unclear, ask before proceeding.
+```
+
+**Why this is inline rather than in a skill:** This logic only applies to `cloud-troubleshooter`. A terraform-architect does not need CLI detection -- it works from HCL files and always uses terragrunt. If the same detection logic applied to two or more agents, it would warrant a skill. Single-agent-only logic stays inline.
+
+---
+
+## Pattern Summary
+
+| Decision | `developer` | `cloud-troubleshooter` | Rule |
+|---|---|---|---|
+| D1 | yes | no | Determines permissionMode and disallowedTools |
+| D2 | no | no | Both are terminal nodes |
+| D3 | yes | yes | Both need description as triggering conditions |
+| Output type | Realization Package or Findings Report | Diagnostic Report | Named explicitly in identity |
+| Workflow position | Before identity | Before identity | Both have complex sequences -- workflow first |
+| Boundary precision | Named decision point ("even if you need it as prerequisite") | Named action prohibition ("you never act") | Generic categories are weaker than named moments |
+| Domain logic inline | No (developer-patterns handles it) | Yes (cloud provider detection) | Inline only when single-agent-specific |