@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/skills/gaia-patterns/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gaia-patterns
+description: Use when analyzing, designing, or modifying the gaia-ops orchestration system architecture
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# Gaia-Ops Patterns
+
+Domain knowledge for the gaia-ops meta-system. For the Component Map details, see `reference.md`.
+
+## Prompt → Result Flow
+
+```
+1. User sends prompt
+   ↓
+2. Orchestrator (identity injected by submit hook) — routes to the correct agent
+   ↓
+3. Pre-Tool Hook (pre_tool_use.py)
+   ├─ Inject project-context.json (relevant sections per agent)
+   ├─ Load skills from frontmatter
+   └─ Validate permissions
+   ↓
+4. Agent Executes — uses tools, follows skills, returns `json:contract` block
+   ↓
+5. Post-Tool Hook — audit + metrics
+   ↓
+6. Orchestrator processes `json:contract` block (plan_status)
+   ├─ REVIEW → present plan, get feedback → resume (with approval_id if hook-blocked)
+   ├─ NEEDS_INPUT → ask user → resume
+   └─ COMPLETE → respond to user
+```
+
+## Key Concepts
+
+- **Binary Delegation:** The orchestrator always delegates. Its only tools are Agent and AskUserQuestion.
+- **Agent Instantiation:** identity (.md) + skills (injected) + project-context (contracts) + orchestrator request.
+- **Security Tiers:** T0 (read) → T1 (validate) → T2 (simulate) → T3 (realize, requires approval).
+- **T3 Flow:** IN_PROGRESS → REVIEW → IN_PROGRESS → COMPLETE (plan-first or hook-blocked with approval_id).
+- **Consolidation Loop:** for multi-surface work, Gaia may dispatch more than one round of agents, but only while gaps are actionable and evidence is still improving.
+- **Principle:** Skills teach process. Agents teach identity and domain knowledge. Runtime enforces deterministic contracts. Never duplicate.
+
+## Multi-Agent Consolidation
+
+The orchestrator owns the consolidation loop. Agents return `json:contract` blocks with `consolidation` objects; the orchestrator merges, decides whether to dispatch another round, and stops when gaps are no longer actionable.
+
+## Workflow Design Philosophy
+
+1. **Flow naturally** — each step leads to the next without friction
+2. **Be positive** — describe what to do, not what to avoid
+3. **Allow discovery** — agent reaches conclusions empirically
+4. **Be concise** — leave room for growth
+5. **Be measurable** — goals with numbers, not subjective terms
+
+## Line Budget
+
+| Document | Target | Max |
+|----------|--------|-----|
+| Agent `.md` | 80 lines | 120 |
+| `CLAUDE.md` | 60 lines | 100 |
+| Skill (injected) | < 100 lines | 100 |
+
+## Agent Creation Standards
+
+1. **YAML Frontmatter** — `name`, `description` (routing label), `tools`, `model`, `skills` (canonical order)
+2. **Identity** — 1-2 paragraphs: what domain, what output format
+3. **Scope** — CAN DO / CANNOT DO → DELEGATE table with agent names
+4. **Domain Errors** — domain-specific errors only
+
+**Canonical injected skills order:** `agent-protocol` → `security-tiers` → `investigation` → `command-execution` → domain skill → `context-updater` → `fast-queries`
+
+**On-demand workflow skills:** `approval`, `execution`, `git-conventions`
+
+## Documentation Standards
+
+**Required sections (in order):** What it does, Where it fits, How it works, Components, Usage, References.
+
+**The zoom lens rule:** every README shows the complete system flow and bolds where this module participates.
+
+**Writing rules:** every line earns its place — no duplication, discoverable over documented.
+
+## Release Management
+
+- **Package:** `@jaguilar87/gaia-ops` (npm public registry)
+- **Symlinks:** `.claude/` symlinks to `node_modules/@jaguilar87/gaia-ops/`
+
+| Change | Version |
+|--------|---------|
+| Bug fix in agent or skill | PATCH |
+| New agent or skill | MINOR |
+| Breaking change to `json:contract` format | MAJOR |

package/dist/gaia-ops/skills/gaia-patterns/reference.md

@@ -0,0 +1,22 @@
+# Gaia-Ops Patterns — Reference
+
+## Component Map
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **Orchestrator** | `CLAUDE.md` | Routes requests, manages workflow |
+| **Agents** | `agents/*.md` | Domain identity + scope |
+| **Hooks** | `hooks/*.py` | Context injection, validation, audit |
+| **Skills** | `skills/*/SKILL.md` | Injected procedural knowledge |
+| **Tools** | `tools/` | Python utilities |
+| **Config** | `config/` | System configuration |
+
+## Documentation Template
+
+```
+1. User sends prompt
+2. Orchestrator routes
+3. **→ [THIS MODULE] ← acts here**
+4. Agent executes
+5. Orchestrator responds
+```

package/dist/gaia-ops/skills/git-conventions/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: git-conventions
+description: Use when creating a git commit or preparing changes for a pull request
+metadata:
+  user-invocable: false
+  type: reference
+---
+
+# Git Conventions
+
+## Commit Format
+
+All commits MUST follow Conventional Commits: `type(scope): description`
+
+| Element | Rule |
+|---------|------|
+| Format | `type(scope): short description` |
+| Types | feat, fix, refactor, docs, test, chore, ci, perf, style, build |
+| Scope | Optional, reflects module/area changed |
+| Subject | Max 72 chars, lowercase start, imperative mood, no period, no emoji |
+| Body | Optional, blank line after subject, 72 char line wrap (warning) |
+| Footers | `BREAKING CHANGE:`, `Refs:`, `Closes:`, `Fixes:` allowed |
+
+## Examples
+
+```
+feat(helmrelease): add Phase 3.3 services
+fix(pg-non-prod): correct API key environment variable mappings
+refactor: simplify context provider logic
+chore(deps): update terraform to v1.6.0
+```
+
+## Rules
+
+- Use `git commit -m "type(scope): description"` format
+- Do NOT add `Co-Authored-By` or `Generated with Claude Code` footers (hooks auto-strip these)
+- Description starts lowercase, imperative mood
+- **Never use git path flags** -- do not use `git -C <path>`, `git --git-dir=<path>`, or `git --work-tree=<path>`. The permission system matches command prefixes; these flags break all `git <subcommand>:*` allow/deny rules. Per `command-execution` Rule 2, run `cd` as a separate Bash call before running git commands.
+- **Push to the feature branch by default.** Only push directly to `main` if explicitly instructed or the plan is already on main. Never force-push (`git push --force`).
+
+## Hook Enforcement (Automatic)
+
+The `commit_validator.py` hook validates against `config/git_standards.json`:
+
+- **Forbidden footers** (error): `Co-Authored-By: Claude`, `Generated with Claude Code`, emoji-prefixed footers
+- **Conventional Commits format** (error): must match `type(scope): description` with allowed types
+- **Subject rules** (error): max 72 chars, no trailing period, no emoji
+- **Body rules** (warning): blank line after subject, 72 char line wrap

package/dist/gaia-ops/skills/gitops-patterns/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: gitops-patterns
+description: Use when creating, modifying, or reviewing Kubernetes manifests, HelmReleases, or Flux configuration
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# GitOps Patterns
+
+Project-specific conventions. For YAML examples, read `reference.md` in this directory.
+Use values from your injected project-context — never hardcode cluster names, registry URLs, or namespaces.
+
+## Repository Structure
+
+```
+{gitops_repo_path}/
+├── clusters/
+│   └── {cluster-name}/          # from project-context cluster_name
+│       ├── flux-system/         # Flux controllers + sync
+│       ├── apps.yaml            # Kustomization → apps overlay
+│       └── infrastructure.yaml  # Kustomization → infra overlay
+├── infrastructure/
+│   ├── base/                    # Shared: namespaces, sources, components
+│   └── overlays/{env}/          # Per-environment patches
+└── apps/
+    ├── base/{service}/          # Per-service Kustomize base
+    └── overlays/{env}/          # Per-environment patches
+```
+
+## Flux Configuration
+
+- **Reconciliation interval:** 1 minute (Kustomization), 5 minutes (HelmRelease)
+- **Source:** Git via SSH, branch `main`
+- **Image automation:** semver `>=1.0.0` — Flux updates tags automatically
+- **Pruning:** `prune: true` — resources removed from Git are deleted from cluster
+
+## Naming Conventions
+
+| Resource | Pattern | Example |
+|----------|---------|---------|
+| Namespace | `kebab-case` | `common`, `mobile-backend` |
+| Service / HelmRelease | `kebab-case` | `products-service` |
+| ConfigMap | `{service}-config` | `products-service-config` |
+| Secret | `{service}-secret` | `products-service-secret` |
+| Kustomization | `{scope}-{env}` | `apps-oci-dev` |
+
+## Image Versioning (CRITICAL)
+
+- **Pattern:** semantic versioning `v1.0.xxx`
+- **NEVER:** `latest`, `main`, `master`, `dev`, `staging`
+- Flux ImagePolicy uses `semver.range: '>=1.0.0'`
+
+For resource limit defaults and secrets management strategy, see `reference.md`.
+
+## Per-Namespace Structure
+
+Each namespace directory contains:
+- `namespace.yaml` — Namespace definition with standard labels
+- `{service}.yaml` — HelmRelease
+- `{service}-config.yaml` — ConfigMap (if needed)
+- `{service}-secret.yaml` — SealedSecret (if needed)
+
+## Key Rules
+
+1. **Git-first** — NEVER `kubectl apply` directly. All changes via git commit + push
+2. **Semver tags** — Never `latest`, always `v1.0.xxx`
+3. **Secrets via SealedSecrets** — Never plain secrets in Git
+4. **Flux reconciles** — Auto in ~1m, or force: `flux reconcile kustomization {name}`
+5. **Always set resource limits** — Both requests and limits required
+6. **Verify cluster context** — `kubectl config current-context` before any operation
+7. **Use project-context** — cluster_name, gitops_repo_path, environment from injected context
+8. **Post-push verification (T3 MANDATORY)** — After pushing manifests, verify Flux reconciled successfully. See `reference.md` "Post-Push Verification" for the exact command sequence

package/dist/gaia-ops/skills/gitops-patterns/reference.md

@@ -0,0 +1,183 @@
+# GitOps Patterns — YAML Reference
+
+Structural patterns for Kubernetes and Flux. Use placeholders — replace with values from project-context.
+
+For cloud-specific resource examples, discover patterns from the existing codebase using the `investigation` skill.
+
+---
+
+## HelmRelease
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: {service-name}
+  namespace: {namespace}
+spec:
+  interval: 5m
+  chart:
+    spec:
+      chart: {chart-name}
+      version: '>=1.0.0'
+      sourceRef:
+        kind: GitRepository
+        name: helm-charts
+        namespace: flux-system
+      interval: 1m
+  values:
+    image:
+      repository: {registry}/{service-name}
+      tag: v1.0.0
+    resources:
+      requests:
+        memory: "256Mi"
+        cpu: "100m"
+      limits:
+        memory: "512Mi"
+        cpu: "500m"
+```
+
+## Namespace
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {namespace}
+  labels:
+    name: {namespace}
+    environment: {env}
+```
+
+## ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {service-name}-config
+  namespace: {namespace}
+data:
+  KEY: "value"
+```
+
+## SealedSecret
+
+```yaml
+apiVersion: bitnami.com/v1alpha1
+kind: SealedSecret
+metadata:
+  name: {service-name}-secret
+  namespace: {namespace}
+spec:
+  encryptedData:
+    SECRET_KEY: AgB...  # Encrypted with kubeseal
+```
+
+## Kustomization
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: {scope}-{env}
+  namespace: flux-system
+spec:
+  interval: 1m
+  path: ./clusters/{cluster-name}
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+```
+
+## ImagePolicy
+
+```yaml
+apiVersion: image.toolkit.fluxcd.io/v1beta1
+kind: ImagePolicy
+metadata:
+  name: {service-name}
+spec:
+  imageRepositoryRef:
+    name: {service-name}
+  policy:
+    semver:
+      range: '>=1.0.0'
+```
+
+## Health Probes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: {port}
+  initialDelaySeconds: 30
+  periodSeconds: 10
+  timeoutSeconds: 5
+  failureThreshold: 3
+readinessProbe:
+  httpGet:
+    path: /ready
+    port: {port}
+  initialDelaySeconds: 5
+  periodSeconds: 5
+  timeoutSeconds: 3
+  failureThreshold: 3
+```
+
+## Troubleshooting
+
+| Issue | Check | Solution |
+|-------|-------|----------|
+| Pod not starting | `kubectl describe pod {name} -n {ns}` | Check events, resource limits, image pull |
+| HelmRelease failed | `flux get helmrelease {name} -n {ns}` | Check chart version, values syntax |
+| Image not found | `kubectl describe pod {name} -n {ns}` | Verify image exists in registry, check tag |
+| Service pending | `kubectl get svc -n {ns}` | Check cloud quotas, subnet/network config |
+| Flux not reconciling | `flux get kustomizations` | Check source sync, path exists |
+
+## Post-Push Verification
+
+After pushing manifests to Git (T3), verify Flux reconciled successfully. Run each command separately:
+
+```bash
+flux reconcile helmrelease {name} -n {namespace} --timeout=30s
+```
+
+```bash
+kubectl wait --for=condition=Ready helmrelease/{name} -n {namespace} --timeout=120s
+```
+
+```bash
+kubectl get helmrelease {name} -n {namespace} -o jsonpath='{.status.conditions[?(@.type=="Ready")]}'
+```
+
+## Debug Commands
+
+```bash
+flux get helmrelease {service-name} -n {namespace} --verbose
+kubectl logs -n {namespace} deployment/{service-name} --tail=100
+kubectl get events -n {namespace} --sort-by='.lastTimestamp'
+kubectl top pods -n {namespace}
+```
+
+## Resource Limits
+
+Always set both requests AND limits:
+
+| Size | CPU Req | CPU Lim | Mem Req | Mem Lim |
+|------|---------|---------|---------|---------|
+| Small | 100m | 500m | 256Mi | 512Mi |
+| Medium | 250m | 1000m | 512Mi | 1Gi |
+| Large | 500m | 2000m | 1Gi | 2Gi |
+
+## Secrets Management
+
+```
+Preference order:
+1. SealedSecrets (Bitnami) — encrypted in Git, decrypted in cluster
+2. External Secrets — from cloud secret store (Secret Manager, Vault)
+3. NEVER plain Kubernetes Secrets in Git
+```

package/dist/gaia-ops/skills/investigation/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: investigation
+description: Use when starting an investigation, analyzing existing code or infrastructure, or building findings before proposing changes
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Investigation
+
+Investigation is about understanding a problem well enough to propose
+a correct solution. For the `json:contract` response format, see `agent-protocol`.
+
+## Phase 1: Start From Injected Context
+
+Before your first tool call, extract anchors from your injected
+Project Context: paths, service names, resource IDs. These are
+your starting point — go directly to them.
+
+Define what you need to know that the context does NOT answer.
+Those are your unknowns.
+
+## Phase 2: Explore Known Paths
+
+For each path or name from context:
+- Read the file or directory directly — no Glob needed
+- Read 2-3 similar existing resources to understand conventions
+- Extract: naming patterns, directory structure, dependencies
+
+If context includes an `investigation_brief`, use it to prioritize
+your surface, adjacent surfaces, and required checks.
+
+## Phase 3: Discover Unknowns
+
+Search only for things NOT covered by context. Use Glob and Grep.
+
+After initial evidence, check adjacency:
+- **Neighbors:** Files next to your target often explain constraints
+- **References:** What references this resource? What does it reference?
+- **Breadth:** Find 2-3 instances of the same pattern. One example is
+  anecdote; three are convention.
+
+Stop when new files confirm what you already know.
+
+## Phase 4: Live State
+
+Only if drift is suspected or the task requires runtime data.
+If you have the `fast-queries` skill, run triage first.
+
+## Phase 5: Pattern Hierarchy
+
+Apply in order — do not skip levels:
+
+1. **Codebase first** — Find 2-3 existing resources of the same type.
+   If found, follow them. Consistency beats preference.
+2. **Domain skill** — If no codebase pattern, use your domain skill
+   (terraform-patterns, gitops-patterns, etc.)
+3. **Training knowledge** — Last resort. Mark explicitly:
+   *"No existing pattern found — applying best practices."*
+
+When following patterns: **COPY** names/paths exactly.
+When a pattern is problematic: **ALERT** as DEVIATION, propose alternative.
+
+## Phase 6: Validate Before Proposing
+
+- Does code agree with project-context? If not → investigate drift
+- Uncertain about correctness? → one more read-only validation
+- Multiple valid approaches? → list options, set status `NEEDS_INPUT`
+
+Separate what is **confirmed** (seen in code, validated) from what
+is **assumed** (inferred). Never propose on assumptions.
+
+## Anti-Patterns
+
+- Searching before checking if context already has the path
+- Planning before resolving critical unknowns
+- Treating your training preference as codebase convention

package/dist/gaia-ops/skills/orchestrator-approval/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: orchestrator-approval
+description: Use when processing REVIEW with approval_id from a subagent -- enforces showing values before asking for user consent
+metadata:
+  user-invocable: false
+  type: discipline
+---
+
+# Orchestrator Approval
+
+```
+THIS SKILL HANDLES REVIEW WITH approval_id (hook-blocked T3).
+Plain REVIEW (plan-first, no approval_id) is handled directly by the orchestrator.
+NEVER PRESENT AN APPROVAL WITHOUT SHOWING THE USER
+(1) WHAT WILL HAPPEN, (2) EXACT CONTENT/COMMAND, (3) WHAT IT MODIFIES.
+```
+
+## Mental Model
+
+The orchestrator sits between the subagent and the user. The subagent presents a plan; the user decides. But the user cannot decide on information they have not seen. Every approval prompt must contain enough detail for informed consent -- not a summary, not a reference to "the plan above", not an offer to show details on request. The values go in the prompt, every time, before the question is asked.
+
+When a hook blocks a T3 command, it writes a pending approval and returns an `approval_id` in the deny response. The subagent includes this `approval_id` in its `approval_request`. The orchestrator presents the plan via AskUserQuestion with structured options (Approve / Modify / Reject). When the user selects "Approve", the PostToolUse hook for AskUserQuestion fires and activates the pending grant. No nonce or approval_id is relayed through SendMessage -- grant activation is handled entirely by the hook.
+
+**Scope:** This skill applies ONLY when a subagent emits `REVIEW` with an `approval_id` in its `approval_request`. Without `approval_id`, the orchestrator handles REVIEW directly.
+
+## Mandatory Presentation Block
+
+Every hook-blocked `REVIEW` presented to the user MUST include these 5 fields.
+Read them from the `approval_request` object in the agent's `json:contract` block:
+
+| Field | Source in `approval_request` | Content |
+|-------|------------------------------|---------|
+| **OPERATION** | `approval_request.operation` | What will happen (verb + target) |
+| **EXACT_CONTENT** | `approval_request.exact_content` | The literal command, file content, or config values |
+| **SCOPE** | `approval_request.scope` | What gets modified (files, resources, environments) |
+| **RISK_LEVEL** | `approval_request.risk_level` | LOW / MEDIUM / HIGH / CRITICAL |
+| **ROLLBACK** | `approval_request.rollback` | How to undo if wrong |
+
+## Rules
+
+**1. Grant activates through the PostToolUse hook for AskUserQuestion -- not SendMessage.**
+Resume the subagent via SendMessage with natural language only (e.g., "Proceed with the approved operation"). Never include any nonce, approval_id, or APPROVE: token.
+
+**2. Scope guard.**
+Compare the blocked command's scope to what the user originally approved. If the command expands scope, changes operation, or targets something materially different -- present the new scope and ask again.
+
+**3. Fresh presentation every time.**
+Each hook-blocked REVIEW requires its own presentation with all mandatory fields. Prior approvals do not carry forward.
+
+## Approval Procedure
+
+1. Extract the 5 mandatory fields from `approval_request` in the subagent's `json:contract` block.
+2. Present to the user via AskUserQuestion with all mandatory fields populated. Use exactly these options: **Approve / Modify / Reject**. Never include the approval_id in user-facing text.
+3. On "Approve": resume the subagent via SendMessage with natural language describing the approved direction.
+4. On scope change: present the new scope with all mandatory fields and ask again.
+
+## Anti-Patterns
+
+- **Summary-only approval** -- presenting "Deploy to dev?" without the exact command, files, or rollback.
+- **Token relay in SendMessage** -- including approval_id or nonce in the resume message.
+- **Implicit carry-forward** -- treating a prior approval as valid for a new hook-blocked REVIEW.
+- **Details on demand** -- offering to show the plan instead of showing it upfront.
+- **"It's just a small change"** -- size does not change the contract. Show exact content regardless.
+- **"The subagent already showed it"** -- show it again in the approval prompt.

package/dist/gaia-ops/skills/reference.md

@@ -0,0 +1,134 @@
+# Agent Reference
+
+Reference material for the gaia meta-agent. Load from disk when needed.
+
+## Agent Template
+
+```markdown
+---
+name: agent-name
+description: One-line description of what this agent does
+tools: Tool1, Tool2, Tool3
+model: inherit
+skills:
+  - security-tiers
+  - agent-protocol
+  - context-updater
+  - investigation
+  - command-execution
+---
+
+## TL;DR
+
+**Purpose:** [What this agent does]
+**Input:** [What context it needs]
+**Output:** [What it produces]
+**Tier:** [T0-T2 or T0-T3]
+
+For T3 approval/execution workflows, read `.claude/skills/approval/SKILL.md` and `.claude/skills/execution/SKILL.md`.
+
+---
+
+## Core Identity
+
+[What makes this agent unique - 2-3 paragraphs max]
+
+### Code-First Protocol
+
+1. **Trust the Contract** - [Key contract field]
+2. **Analyze Before Generating** - Follow `investigation` skill
+3. **Pattern-Aware Generation** - [Domain-specific generation rules]
+4. **Validate** - [Domain-specific validation]
+5. **Output is a Realization Package** - [What the package contains]
+
+---
+
+## 4-Phase Workflow
+
+### Phase 1: Investigation
+Follow `investigation` skill protocol. Then: [domain-specific steps]
+
+### Phase 2: Present
+[What to show user]
+
+### Phase 3: Confirm
+[Approval requirements]
+
+### Phase 4: Execute
+[Execution steps]
+
+---
+
+## Scope
+
+### CAN DO
+- [List capabilities]
+
+### CANNOT DO
+- [List restrictions with delegation targets]
+
+### DELEGATE
+[When to recommend other agents]
+
+---
+
+## Error Handling
+
+| Error | Detection | Recovery |
+|-------|-----------|----------|
+| [error] | [how detected] | [how to recover] |
+```
+
+## Release Checklist
+
+When publishing a new version:
+
+1. Read `package.json` for current version
+2. Review changes (`git log`, CHANGELOG.md)
+3. Determine version bump (patch/minor/major)
+4. Update CHANGELOG.md with changes
+5. Test symlinks work in consuming project:
+   ```bash
+   # In consuming project
+   ls -la .claude/  # Should point to node_modules/@jaguilar87/gaia-ops/
+   ```
+6. Bump version:
+   ```bash
+   npm version [patch|minor|major]
+   ```
+7. Publish:
+   ```bash
+   npm publish --access public
+   ```
+8. Verify:
+   ```bash
+   npm info @jaguilar87/gaia-ops version
+   ```
+
+## Documentation Template
+
+```markdown
+# Component Name
+
+Brief description of what this does and why it exists.
+Written like you're explaining to a colleague.
+
+## Where This Fits
+
+```
+User request → Orchestrator → **This Tool** → Agent receives context
+```
+
+## Quick Start
+
+\`\`\`bash
+python3 tool.py --help
+\`\`\`
+
+## Examples
+
+\`\`\`bash
+python3 tool.py "example input"
+# Output: example output
+\`\`\`
+```