agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/core/dev-companion/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: dev-companion
+description: 'WHAT — Dev Companion (general): layered companion for client delivery; modes, gates, delegation
+  to assistant and workflow-generic-project; no CLI matrices.'
+origin:
+  type: first-party
+---
+# Dev Companion (WHAT) — general layer (L2)
+
+This skill is the **general** dev companion for work. It does **not** replace **`assistant`** (orchestrator); it **sits above** workflows and names **what to invoke next**.
+
+**Language:** English for ticket comments, PR text, and user-facing outputs when this companion drives delivery work.
+
+## Layering
+
+| Layer | Skill | Role |
+| --- | --- | --- |
+| L1 | **assistant** | Repo inspection order, conflict resolution, fallback |
+| **L2 (this skill)** | **dev-companion** | Companion framing: modes, gates, delegation for client work |
+| L3 | **Workspace pack overlay** | Client/account-specific context loaded from `~/.ai-workspace/packs/` |
+
+If engagement triggers match, load the appropriate **workspace pack overlay** first, then proceed with **workflow-generic-project**. Do not mix multiple workflow drivers on the same task.
+
+## Mode selection
+
+- **Default** for /client delivery: use **workflow-generic-project** for phased delivery.
+- If the user mentions an engagement, ticket prefix, or repo context → load the matching pack from the workspace (overlay) and apply its boundaries/gates.
+- If unclear → **ask** before applying L3.
+
+## Delegation (HOW is in other skills)
+
+| Need | Delegate to |
+| --- | --- |
+| Discovery, AGENTS conflict handling | **assistant** |
+| Generic client delivery phases | **workflow-generic-project** |
+| Planning / default workflow / validation | **planning** / **development-workflow** |
+| Work items, incidents, meetings, decisions, agreements, spikes | **work-item**, **incident**, **meeting-minutes**, **decision-log**, **agreement**, **spike** |
+| Project assessments, evidence maps, technical/management unit scorecards | **project-assessment**, **project-assessment-evidence**, **technical-unit-assessment**, **management-unit-assessment** |
+| ClickUp | **clickup-cli** |
+| Jira | External **jira-*** pack (**jira-assistant** router; CLI: `jira-as`) |
+| Confluence | External **confluence-*** pack (**confluence-assistant** router; CLI: `confluence-as` or `confluence`) |
+| Draft PR GitHub / GitLab | **github-cli-workflow** / **gitlab-cli-workflow** (for default body when the repo has no template: **pr-fallback** first) |
+| Where to save deliverables + human review | **output-handshake** |
+| UI depth | **figma** / **figma-implement-design** |
+| Workstation health | **triage** |
+
+Do **not** paste forge or ticket CLI sequences here.
+
+## Operating modes
+
+- **Interactive (default):** IDE session; user steers each step.
+- **Queued job (optional):** only when a local runner is configured; see `~/.local/share//dev-companion/README.md` (installed from chezmoi) and **references/LOOP_GUARDRAILS.md**.
+
+The queue worker is **mandatory infrastructure** (installed by workstation). The **workspace** (`~/ai-workspace`) is optional — it provides project-aware wrappers, job templates, and knowledge base integration. When both are present, the runner automatically enriches LLM prompts with workspace context (`projects.yaml`, `projects/`, `knowledge/todos/`).
+
+### LLM policy gate (client engagements)
+
+Before queueing background jobs for a client repo, confirm the active LLM policy with **`devcompanion llm-status`**. If the engagement requires a single AI account (e.g. only the customer's Anthropic key), the workstation/pack must set **`DOTS_WORKSTATION_DEVCOMPANION_LLM_ALLOWLIST`** and **`DOTS_WORKSTATION_DEVCOMPANION_LLM_STRICT=1`** so the runner fails closed instead of falling back to OpenCode. For Cursor/Copilot-only engagements, prefer **`run-once --no-llm`** (skeleton plan) plus IDE-driven execution. Full reference: **`docs/DEV_COMPANION_LLM.md`**.
+
+## Checklist
+
+- [ ] L3 not needed; if needed, user confirmed engagement context
+- [ ] **assistant** discovery pass before large edits
+- [ ] **workflow-generic-project** phases and gates when doing generic client delivery
+- [ ] Tool skills used for all CLI operations

agent_toolkit/data/skills/core/onboarding/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: onboarding
+description: Getting started guide for new users. Walks through setup validation, the skill/agent hierarchy,
+  and the three most useful commands per role (developer, PM, tech lead). Use when someone is new to the
+  workstation or asks "where do I start?"
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - onboarding
+  - setup
+  - getting-started
+---
+# Onboarding
+
+Welcome to . This skill guides new users through initial setup and daily usage.
+
+## When to use
+
+- User asks "where do I start?" or "how does this work?"
+- First-time setup after `chezmoi apply`
+- Troubleshooting a broken installation
+- Onboarding a teammate
+
+## Step 1 — Validate setup
+
+```bash
+doctor
+```
+
+Expected: `result: COMPLIANT`. If any check fails, `doctor` shows the fix command.
+
+For persistent issues:
+
+```bash
+update-check            # check for available updates
+skills list             # verify skills are installed
+skills sync             # re-sync symlinks to AI tools
+```
+
+## Step 2 — Understand the hierarchy
+
+```text
+User message
+    ↓
+Orchestrator (assistant)
+    ↓ routes to
+Workflow skill (WHAT — decides scope and gates)
+    e.g. workflow-generic-project
+    ↓ delegates to
+Tool skill (HOW — executes CLI commands)
+    e.g. clickup-cli, github-cli-workflow
+```
+
+**Skills** are invoked via the skill tool (e.g. `/planning`).
+**Agents** are invoked via `@mention` (e.g. `@planner`). Never use the skill tool for agents.
+
+## Step 3 — First commands by role
+
+### Developer
+
+```bash
+# Start any task
+/workflow-generic-project
+
+# After code changes — review before PR
+@code-reviewer
+
+# CI failing
+/gh-fix-ci
+```
+
+### Product Manager / Tech Lead
+
+```bash
+# Plan a feature
+@planner
+
+# Create a ClickUp task
+/clickup-cli  # then: clickup task create --current --name "..."
+
+# Project health check
+/project-assessment
+```
+
+### Anyone
+
+```bash
+# Check workstation health
+doctor
+
+# Find which skill to use
+# → ask the orchestrator: "what skill should I use for X?"
+
+# Load client/project context
+./bin/workspace-context load packs/<client>.yaml   # if in ai-workspace
+```
+
+## Key concepts in 60 seconds
+
+| Concept | What it means |
+|---------|--------------|
+| **Pack** | Context bundle for a client/project (repos, constraints, commands) |
+| **Skill** | Reusable AI prompt for a specific task (WHAT or HOW) |
+| **Agent** | Specialized AI persona with restricted tool access (invoked via @mention) |
+| **Loop** | Recurring autonomous process with state, tiers, and cost budgets |
+| **L1 / L2 / L3** | Loop autonomy tiers: L1=observe-only, L2=PR-gated, L3=unattended |
+| **knowledge/** | Persistent memory across sessions |
+
+## Anti-patterns
+
+- Do not skip `doctor` — it catches 90% of setup issues
+- Do not invoke agents via the skill tool — use `@mention`
+- Do not run L3 loops without 3+ clean L1 runs first
+
+## Next steps
+
+- Load a project pack: `./bin/workspace-context load packs/<project>.yaml`
+- Run your first task: `/workflow-generic-project`
+- Set up daily loop: `./bin/loop init daily-triage`

agent_toolkit/data/skills/core/output-handshake/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: output-handshake
+description: 'WHAT — Default gate for any deliverable: confirm where the final artifact will be stored
+  and that a human will review, before writing PRDs, TRDs, ADRs, or PR bodies. Repository paths, wikis,
+  and ticket tools differ by engagement; never assume a single location.'
+origin:
+  type: first-party
+---
+# Output handshake (WHAT)
+
+**Use first** when producing a **final** version of any deliverable that will leave the chat session: PRD, TRD, ADR, work item, planning notes, workflow/validation summary, project assessment, assessment scorecard, evidence map, meeting minutes, decision log, agreement, incident report, spike, or PR/MR body.
+
+## Default behavior (always)
+
+1. **Destination** — Ask explicitly: *where should the final content live?* (Examples: a path in `docs/`, a file in a repo, a page in a documentation tool, a task/Doc description, paste-only, or a combination.) Do **not** default to a location without the user (or the engagement pack) saying so.
+2. **Review** — State that a **human** must review before the artifact is considered approved; the assistant does not substitute for that review.
+3. Then proceed with the relevant skill (**`prd`**, **`trd`**, **`adr`**, **`work-item`**, **`planning`**, **`development-workflow`**, **`project-assessment`**, **`project-assessment-evidence`**, **`technical-unit-assessment`**, **`management-unit-assessment`**, **`meeting-minutes`**, **`decision-log`**, **`agreement`**, **`incident`**, **`spike`**, **`pr-fallback`** + forge workflow, etc.).
+
+## Boundaries
+
+- This skill does not contain org templates; those stay in the specific artifact skills and their `references/default-template.md` files.
+
+## See also
+
+- `workflow-generic-project` — delivery gates
+- `assistant` — discover existing `docs/`, PR templates, `AGENTS.md`

agent_toolkit/data/skills/core/pr-fallback/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: pr-fallback
+description: WHAT — When the repo has no GitHub PR template, structure the pull-request body using the
+  default in references/pr-body-default.md. Pair with output-handshake and github-cli-workflow. Does not
+  open the PR; HOW stays in the forge skill.
+origin:
+  type: first-party
+---
+# PR body — default when no repo template (WHAT)
+
+## When to use
+
+- Remote is **GitHub** and **`assistant`** (or a file search) shows **no** `PULL_REQUEST_TEMPLATE` / `pull_request_template` under `.github/`.
+- You need a **reasonable default** for `gh pr create --body-file` until the repo adds its own template.
+
+## Instructions
+
+1. Run **`output-handshake`**: user confirms where the final description will live (e.g. `body.md` for `gh`, paste-only) and that a **human** will review.
+2. If the repository adds a template later, **prefer the repo** over this file.
+3. Copy sections from **`references/pr-body-default.md`**, fill placeholders (issue id, test notes), and pass the path to **`github-cli-workflow`**.
+
+## GitLab
+
+If there is no `.gitlab/merge_request_templates/`, you may use the same Markdown structure in the **merge request description** for consistency, subject to the user’s **destination** choice (MR description field, file, etc.) and **`output-handshake`**.
+
+## What not to do
+
+- Do not **assume** a PR is always in a specific ticket system; the **file** the user points to is wherever they said in the handshake.
+
+## References
+
+- `references/pr-body-default.md` — local copy of the default body
+- `development-workflow` — default PR validation and DoD expectations
+- `github-cli-workflow` — draft PR creation
+- `gitlab-cli-workflow` — GitLab MRs

agent_toolkit/data/skills/core/project/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: project
+description: Clone, index, and orchestrate multi-repo work via agent-toolkit project — symlinks, quick
+  access, and swarm workspaces.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - project
+  - git
+  - multi-repo
+  - workspace
+---
+# Project
+
+Manage the local multi-repo registry (`~/.ai-workspace/repos/` and `projects/` symlinks) so swarms and agents can target any repo by name, not path.
+
+## When to use
+
+- User says "clone X", "add repo Y", "list projects", or references `owner/repo` without a local path.
+- Swarm needs `--workspace /path/to/repo` that isn't yet cloned.
+- Workspace context shows missing `projects/` symlink for a repo referenced in a prompt.
+
+## Prerequisites
+
+- `agent-toolkit` with `project` subcommand (`agent-toolkit project --help`).
+- `gh` authenticated for private repos (`gh auth status`).
+- Workspace has `repos/github.com/<owner>/<repo>` layout.
+
+## Workflow
+
+### 1. Clone and index
+
+```bash
+agent-toolkit project clone owner/my-repo          # clone + symlink projects/my-repo -> repos/github.com/owner/my-repo
+agent-toolkit project clone owner/my-repo --branch feat/x
+# Alias resolution: swarm's config.py also resolves_owner_repo from prompt URLs like https://github.com/owner/repo
+
+# Verify
+agent-toolkit project list                         # indexed projects
+ls -l ~/.ai-workspace/projects
+ls ~/.ai-workspace/repos/github.com/owner/my-repo
+```
+
+### 2. Use with swarm and other skills
+
+```bash
+# Swarm can target any indexed repo via --workspace
+agent-toolkit swarm start --recipe pair --ui herdr --runner opencode --model-profile balanced --workspace ~/.ai-workspace/repos/github.com/owner/my-repo --attach "task"
+# Inside a cloned repo, just run from its directory — swarm's find_repo_root uses git rev-parse --git-common-dir
+
+# Assistant discovery before swarm
+# (assistant skill: README -> docs/ -> AGENTS.md -> CONTRIBUTING -> PR templates -> Makefile/package.json -> devcontainer -> CI -> configs)
+```
+
+### 3. Scan and sync
+
+```bash
+agent-toolkit project scan                         # re-index repos/ -> projects/
+agent-toolkit project list --json | jq
+agent-toolkit workspace context --json | jq '.repos'
+```
+
+### 4. Multi-repo swarms
+
+For cross-repo tasks, clone all targets first, then launch swarms per repo with handoffs referencing the correct `--workspace` or `AGENT_TOOLKIT_SWARM_REPO` env:
+
+```bash
+agent-toolkit project clone org/repo-a
+agent-toolkit project clone org/repo-b
+export AGENT_TOOLKIT_SWARM_REPO=org/repo-a  # swarm's store respects this for run location
+```
+
+## Boundaries
+
+- Never `git clone` by hand when `project clone` can do it — it handles symlinks and registry.
+- Never assume CWD is the target repo; use `--workspace` or `workdir` per `AGENTS.md`.
+- Do not delete `repos/` entries directly; use `agent-toolkit project remove` if available, or ask before manual `rm`.
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Workspace packs and memory for the new repo | `workspace` |
+| Repo conventions before coding | `assistant` |
+| Swarm orchestration on the repo | `swarm` |
+| Branch/PR after swarm promotion | `github-cli-workflow` |

agent_toolkit/data/skills/core/workspace/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: workspace
+description: Scaffold and manage the stateless AI workspace — context, packs, repos, and knowledge for
+  multi-repo orchestration.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - workspace
+  - packs
+  - context
+  - multi-repo
+  - orchestration
+---
+# Workspace
+
+Initialize and operate the **stateless AI workspace** (`~/.ai-workspace`) that orchestrates work across any repo, team, or client via `agent-toolkit workspace` and `agent-toolkit memory`. This is the entry point for multi-repo delivery; all swarm and project work runs inside it.
+
+## When to use
+
+- Starting a new session (`agent-toolkit workspace context` + `agent-toolkit memory inject` + `agent-toolkit memory todo` — the session start protocol per `AGENTS.md`).
+- User needs to switch client/project context via packs (`packs/*.yaml`).
+- Workspace health check, pack load, or knowledge sync is needed.
+
+## Prerequisites
+
+- `agent-toolkit` installed (`agent-toolkit workspace --help` works).
+- Workspace at `~/.ai-workspace` (or `$WORKSPACE_ROOT`) with `repos/`, `projects/` symlinks, `knowledge/`, `personas/`, `packs/`.
+
+## Workflow
+
+### 1. Session start protocol (always)
+
+```bash
+agent-toolkit workspace context          # inject session state (repos, packs, personas)
+agent-toolkit memory inject              # load persistent knowledge
+agent-toolkit memory todo                # show pending follow-ups
+# Optional: load a pack
+agent-toolkit workspace load packs/<client>.yaml
+```
+
+Per `AGENTS.md`: check `knowledge/` before asking a question already answered; run discovery before large edits; follow plan → implement → review → PR.
+
+### 2. Inspect and switch context
+
+```bash
+agent-toolkit workspace context --json | jq
+ls ~/.ai-workspace/projects  # symlinks to active repos
+ls ~/.ai-workspace/packs
+cat ~/.ai-workspace/AGENTS.md  # portable contract (primary), plus CLAUDE.md/GEMINI.md symlinks
+```
+
+Packs bundle client/project context:
+
+```bash
+agent-toolkit workspace load packs/my-client.yaml  # sets env, LLM policy, registry
+# Verify LLM policy before queuing devcompanion jobs (esp. for client engagements)
+dots-devcompanion llm-status  # or agent-toolkit devcompanion status
+```
+
+### 3. Knowledge lifecycle
+
+```bash
+agent-toolkit memory search "topic"           # find existing knowledge
+agent-toolkit memory add --type learning "pattern"  # save after discovering
+agent-toolkit memory add --type todo "follow-up"    # track
+agent-toolkit memory todo                    # review before closing session
+```
+
+Knowledge is project-aware; `memory inject` surfaces prior learnings for the current repo.
+
+### 4. Personas and routing
+
+Per `AGENTS.md` routing table:
+
+| Task | Delegate |
+|------|----------|
+| Discovery / first repo look | `assistant` skill |
+| Generic delivery | `workflow-generic-project` |
+| UI/UX | `figma` / `figma-implement-design` |
+| JIRA / Confluence / ClickUp | `jira-assistant` / `confluence-assistant` / `clickup-cli` |
+| Swarm orchestration | `swarm`, `swarm-observer`, `swarm-handoff` |
+| Herdr/tmux backend | `herdr`, `worktree` |
+
+Personas (`personas/*.md`: implementer, reviewer, researcher, architect) constrain toolset when `use-persona` is active — respect `allow/deny` and handoff.
+
+## Boundaries
+
+- Never `cd && command` to change repo context — use `workdir` or `--workspace`/`-C`.
+- Never commit without code review; never skip plan phase for non-trivial work.
+- Do not assume we are inside a repo — verify with `workspace context` first.
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Repo discovery and conventions | `assistant` |
+| Multi-repo clone and sync | `project` |
+| Swarm delivery | `swarm` |
+| Knowledge persistence | `workspace-knowledge-sync` |
+| Generic delivery workflow | `workflow-generic-project` |

agent_toolkit/data/skills/core/workspace-knowledge-sync/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: workspace-knowledge-sync
+description: Syncs knowledge to the ai-workspace knowledge base. Use when the assistant discovers new
+  patterns, learns user preferences, or identifies information worth preserving for future sessions. Integrates
+  with tech-assistant for automatic trigger points.
+origin:
+  type: first-party
+---
+# Workspace Knowledge Sync
+
+Automatically syncs valuable discoveries, patterns, and decisions to the ai-workspace knowledge base.
+
+---
+
+## Purpose
+
+The orchestrator session accumulates knowledge through work. This skill ensures that valuable discoveries don't get lost and are available for future sessions.
+
+---
+
+## Trigger Points (Automatic)
+
+The tech-assistant will invoke this skill automatically when:
+
+| Situation | What to Sync | Target File |
+|-----------|--------------|-------------|
+| Discovery of new skill/tool | Skill name, purpose, usage pattern | `knowledge/skills/discovered.md` |
+| New process pattern | Process steps, roles, tools | `knowledge/processes/general.md` |
+| Key decision made | Decision, rationale, outcome | `knowledge/learnings/general.md` |
+| Pending follow-up | Task description, context | `knowledge/todos/pending.md` |
+| User teaches something | Information, preference | Relevant knowledge file |
+
+---
+
+## How It Works
+
+The skill uses the stable `assistant-memory` API with `--from-skill` for origin tracking:
+
+```bash
+# Search before adding
+assistant-memory search "<query>"
+
+# Add a learning (with origin tracking)
+assistant-memory add --type learning --from-skill knowledge-sync "Pattern: <description>"
+
+# Add a skill (with tags)
+assistant-memory add --type skill --from-skill knowledge-sync --tags jira,workflow "New skill: <name>"
+
+# Add a pending todo
+assistant-memory add --type todo --from-skill knowledge-sync "<description>"
+```
+
+---
+
+## Knowledge Structure
+
+```
+knowledge/
+├── skills/
+│   └── discovered.md      # New skills found during work
+├── processes/
+│   ├── jira.md
+│   ├── confluence.md
+│   └── general.md        # Generic process patterns
+├── learnings/
+│   └── general.md        # Key decisions and insights
+└── todos/
+    └── pending.md        # Follow-up items
+```
+
+---
+
+## Manual Usage
+
+You can also trigger this skill manually:
+
+```
+User: "Save that pattern for later"
+
+Assistant: → Use knowledge-sync to preserve the pattern
+```
+
+---
+
+## Integration with tech-assistant
+
+The tech-assistant skill checks for these automatic sync opportunities:
+
+1. **After task creation/update** → Sync initiative info
+2. **After discovering space/list IDs** → Sync to knowledge base (per `knowledge-sync`).
+3. **After learning user preferences** → Sync to learnings
+4. **When user mentions follow-up** → Add to pending
+
+---
+
+## Best Practices
+
+1. **Be selective** - Only sync valuable, reusable information
+2. **Be specific** - Include context and usage examples
+3. **Be concise** - One idea per entry, link to details
+4. **Be current** - Update outdated information when found
+
+---
+
+## Examples
+
+### Auto-sync discovery
+
+```
+Assistant discovers Initiative list IDs for all Technology spaces
+→ Syncs to knowledge/processes/clickup/spaces/
+```
+
+### Auto-sync key decision
+
+```
+Assistant and user decide on naming convention
+→ Syncs to knowledge/learnings/general.md
+```
+
+### Manual sync request
+
+```
+User: "Remember that we always use feature branches"
+→ Assistant syncs to knowledge/processes/general.md
+```
+
+---
+
+## Configuration
+
+The skill uses these environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `KNOWLEDGE_BASE_PATH` | `~/ai-workspace/knowledge` | Knowledge base root |
+
+---
+
+Base directory: `~/.local/share//skills/knowledge-sync`

agent_toolkit/data/skills/data/dbt-validation/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: dbt-validation
+description: HOW — Run dbt checks as documented in the target repo (parse, compile, test, selective run).
+  Does not configure Snowflake accounts or change cloud security.
+origin:
+  type: first-party
+---
+# dbt validation (HOW)
+
+Use when the repository is a **dbt** project or the task requires **dbt** verification. Client workflows may delegate here.
+
+## Boundaries
+
+- Follow **repo** `AGENTS.md`, `Makefile`, `README`, and CI—not generic guesses.
+- **Do not** change Snowflake security settings, network rules, or warehouse admin from this skill.
+- If `dbt` or credentials are missing, **say so** and do not claim validation passed.
+
+## Discovery
+
+Look for `dbt_project.yml`, `packages.yml`, `models/`, `Makefile`, `pyproject.toml`, or CI jobs that invoke dbt.
+
+## Typical commands (examples only—prefer repo docs)
+
+| Intent | Often used (verify in repo) |
+| --- | --- |
+| Syntax / graph | `dbt parse`, `dbt compile` |
+| Dependencies | `dbt deps` when packages change |
+| Tests | `dbt test` or subset flags the repo documents |
+| Build | `dbt run` / `dbt build` when the user approves mutating runs |
+
+**Makefile** wrappers (e.g. `make parse`) take precedence when documented.
+
+## Evidence
+
+- Summarize **which** commands ran and **high-level** outcome (pass/fail/skipped) for tickets and PRs.
+- On failure, capture **actionable** error lines; do not dump full logs unless the user asks.
+
+## Safety
+
+- Prefer **read-only** checks (`parse`, `compile`, `test`) when the task is review-only.
+- Production runs require explicit user approval per repo policy.

agent_toolkit/data/skills/data/snowflake-validation/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: snowflake-validation
+description: 'HOW — Read-only Snowflake validation patterns: use repo-documented CLI (snowflake/sql) or
+  SQL checks. Never claim success without working credentials and evidence.'
+origin:
+  type: first-party
+---
+# Snowflake validation (HOW)
+
+Use when the task or repo requires **Snowflake** verification. Client workflows may delegate here alongside **dbt-validation**.
+
+## Boundaries
+
+- **Read-only** validation unless the user and repo explicitly authorize DDL/DML.
+- **Never** claim “Snowflake validation passed” or “query succeeded” without **credentials** and **observed outputs** (or explicit statement that checks were skipped).
+- **Do not** rotate keys, change roles, or alter security objects from this skill unless the repo’s `AGENTS.md` clearly authorizes it and the user approves.
+
+## Discovery
+
+Read repo docs for: connection method (env vars, `profiles.yml`, SSO), Snowflake **SQL** or **Snowflake CLI** (`snow`) usage, and warehouse/database/schema defaults.
+
+## Patterns
+
+| Situation | Action |
+| --- | --- |
+| Credentials available | Run minimal **SELECT** statements or documented smoke queries; record that they were executed |
+| Snowflake CLI documented | Use repo’s exact commands; check `snow --help` for current subcommands |
+| No credentials | State **skipped** in Jira/PR; list what would be validated when access exists |
+| dbt + Snowflake | Coordinate with **dbt-validation**; Snowflake may be exercised indirectly via dbt |
+
+## Evidence
+
+- For each run: **what** ran (object or test name), **environment** (non-secret), **result** (row count, success/failure).
+- Redact account identifiers if the user requests privacy in chat.
+
+## Safety
+
+- No secrets in tickets, PRs, or command lines in logs pasted to chat—use env vars and documented patterns only.