agent-toolkit-cli 1.0.3__py3-none-any.whl

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/code-reviewer.mdc

@@ -0,0 +1,21 @@
+---
+description: Code quality review. Apply when reviewing code changes for quality, correctness, security, and maintainability.
+alwaysApply: false
+---
+
+# Code Review Guidelines
+
+Run `git diff HEAD` or `git diff --staged` first. Review full file context, not just the diff.
+
+## Review checklist
+
+**Quality**: clear and self-documenting, SRP, no duplication, meaningful names
+**Correctness**: error handling for all paths, edge cases (null, empty, boundary), no off-by-one
+**Security**: no exposed secrets, input validation, injection prevention, proper auth checks
+**Performance**: no N+1 queries, no unnecessary recomputation, appropriate caching
+**Testing**: new behavior has coverage, tests are meaningful (not just padding)
+
+## Output priority
+🚨 Critical (block merge) → ⚠️ Warning (should fix) → 💡 Suggestion (consider)
+
+Include code snippets showing the fix for critical and warning items.

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/database-reviewer.mdc

@@ -0,0 +1,29 @@
+---
+description: PostgreSQL and database review. Apply for schema design, query optimization, migration review, index analysis, and ORM usage.
+alwaysApply: false
+---
+
+# Database Review Guidelines
+
+## Schema
+- 3NF normalization unless intentionally denormalized for performance
+- Appropriate data types (avoid overusing TEXT/VARCHAR)
+- Constraints: NOT NULL, UNIQUE, FK, CHECK where appropriate
+- snake_case naming, plural table names
+
+## Queries
+- Use EXPLAIN ANALYZE for performance analysis
+- Detect and eliminate N+1 queries in ORM calls
+- Use keyset pagination over LIMIT/OFFSET for large datasets
+- Index query predicates and join columns
+
+## Migrations (production safety)
+- Avoid operations that take long locks (e.g., `ADD COLUMN DEFAULT` on large tables)
+- Make migrations reversible
+- Plan backfill strategies for schema changes on large tables
+- Use zero-downtime patterns (expand/contract)
+
+## ORM
+- Correct eager vs lazy loading
+- Proper transaction scope and isolation level
+- Manage connection pool settings

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/docs-lookup.mdc

@@ -0,0 +1,15 @@
+---
+description: Documentation and API reference lookup. Apply when searching for framework docs, library APIs, configuration options, or usage examples.
+alwaysApply: false
+---
+
+# Documentation Lookup
+
+When looking up documentation:
+
+1. Check local docs first: README.md, docs/ directory, inline comments
+2. Identify the exact API, configuration option, or behavior being sought
+3. Return: direct answer → code example → source reference → version notes
+
+Keep responses focused and practical. Note version-specific differences.
+If the question has multiple interpretations, clarify before searching.

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/e2e-runner.mdc

@@ -0,0 +1,30 @@
+---
+description: End-to-end testing with Playwright. Apply when writing, debugging, or reviewing E2E tests.
+alwaysApply: false
+---
+
+# Playwright E2E Testing
+
+## Selector priority
+1. `getByRole()` — most resilient and accessible
+2. `getByLabel()` — for form fields
+3. `getByText()` — for content
+4. `data-testid` — when semantic selectors unavailable
+5. CSS selectors — last resort
+
+## Reliability
+- Use `await expect(locator).toBeVisible()` — not `await locator.isVisible()`
+- Never use `page.waitForTimeout()` — use `waitForResponse`, `waitForURL`, or assertions
+- Mock external services and APIs
+- Test network failures and loading states
+
+## Structure
+- One test file per feature/page
+- `test.describe` for grouping
+- `beforeEach`/`afterEach` for setup
+- Page Object Model for reusable interactions
+
+## Test coverage
+- User journey happy paths
+- Error states and validation feedback
+- Keyboard navigation and accessibility

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/performance-optimizer.mdc

@@ -0,0 +1,27 @@
+---
+description: Performance analysis and optimization. Apply when code is slow, has memory leaks, or fails performance benchmarks.
+alwaysApply: false
+---
+
+# Performance Optimization
+
+**Profile first, optimize second — never guess at bottlenecks.**
+
+## Measure before changing
+- Frontend: React DevTools Profiler, Lighthouse, bundle analyzer
+- Backend: query logging, heap snapshots, APM traces
+- Database: EXPLAIN ANALYZE
+
+## Common bottleneck areas
+- Frontend: unnecessary re-renders, large bundle, unoptimized assets
+- Backend: N+1 queries, sync I/O in hot paths, connection pool exhaustion
+- DB: missing indexes, full table scans, lock contention
+- Algorithm: O(n²) loops, redundant computation
+
+## Safe first optimizations
+- Caching (memoization, Redis, HTTP headers)
+- Lazy loading and code splitting
+- Database indexes on query predicates
+- Batch operations over one-by-one loops
+
+## Output: current metric → bottleneck with evidence → fix → verification method → trade-offs

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/planner.mdc

@@ -0,0 +1,28 @@
+---
+description: Technical planning for complex features and refactoring. Apply before starting significant implementations to break down work and identify risks.
+alwaysApply: false
+---
+
+# Technical Planning
+
+Before writing any code for a complex change:
+
+1. Understand the full scope — what changes, what must NOT change, ordering constraints
+2. Explore the codebase to understand current state and dependencies
+3. Identify risks and blast radius for each step
+4. Create an ordered task list — tackle unknowns and risky items first
+
+## Task sizing
+- S: < 2 hours | M: half day | L: full day | XL: needs further breakdown
+
+## Each task should have
+- Clear acceptance criteria
+- Independent committability (where possible)
+- Includes: migrations, tests, and documentation updates
+
+## Output
+1. Summary (one paragraph)
+2. Risks with mitigations
+3. Ordered tasks with size estimates
+4. Definition of Done
+5. Open questions needing decisions before starting

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/refactor-cleaner.mdc

@@ -0,0 +1,26 @@
+---
+description: Dead code cleanup and refactoring. Apply when removing dead code, simplifying complex functions, reducing duplication, or improving code structure without changing behavior.
+alwaysApply: false
+---
+
+# Refactoring Guidelines
+
+**One rule above all: never change behavior while refactoring.**
+
+## Before refactoring
+- Read existing tests to understand current behavior
+- If no tests exist, write characterization tests first
+- Work in small, independently verifiable steps
+
+## Techniques
+- **Dead code**: search all usages before deleting; remove from public exports last
+- **Complexity**: extract functions, guard clauses, named constants over magic numbers
+- **Duplication**: apply Rule of Three — wait for 3 occurrences before abstracting
+- **Naming**: verb phrases for functions, noun phrases for variables, no unexplained abbreviations
+
+## Commit discipline
+- One type of refactoring per commit
+- Message format: `refactor: <what changed and why>`
+- Run tests before and after each step
+
+## Output: before/after diff with explanation; note preserved behavior

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/security-reviewer.mdc

@@ -0,0 +1,20 @@
+---
+description: Security vulnerability review. Apply after implementing authentication, data handling, API endpoints, file uploads, or any user-facing functionality.
+alwaysApply: false
+---
+
+# Security Review
+
+Run `git diff HEAD` first. Check full context, not just the diff.
+
+## Key checks
+- **Injection**: parameterized queries only; no unsanitized shell input; XSS encoding in templates
+- **Auth/Authz**: no hardcoded credentials; JWT signature+expiry validation; session security; IDOR prevention
+- **Data exposure**: no sensitive data in logs; API responses don't leak internal schema or stack traces
+- **Dependencies**: `npm audit` / `pip audit` for known CVEs
+- **Input validation**: validate all inputs; file uploads need type+size+content checks
+
+## Output priority
+🚨 Critical (fix immediately) → ⚠️ High (fix before deploy) → 📋 Medium (next sprint) → ℹ️ Low
+
+Include CVE references where applicable.

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/tdd-guide.mdc

@@ -0,0 +1,26 @@
+---
+description: Test-Driven Development guidance. Apply when implementing new features to enforce write-tests-first methodology.
+alwaysApply: false
+---
+
+# TDD — Red, Green, Refactor
+
+**Write the failing test first. Always.**
+
+## The cycle
+1. **Red**: Write a failing test describing the desired behavior
+2. **Green**: Write the minimum code to pass the test
+3. **Refactor**: Clean up while keeping tests green
+4. Repeat
+
+## Test design
+- Descriptive names: `it('returns empty array when no users match the filter')`
+- AAA pattern: Arrange → Act → Assert
+- Mock external dependencies (HTTP, DB, email) in unit tests
+- Use real dependencies in integration tests
+
+## What to test
+- Happy path, error paths, boundary conditions (null, empty, max/min), state transitions
+
+## What NOT to test
+- Implementation details, third-party library internals, simple getters with no logic

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/profiles/windsurf/rules/typescript-reviewer.mdc

@@ -0,0 +1,28 @@
+---
+description: TypeScript and JavaScript type safety review. Apply for type safety improvements, modern TS patterns, and resolving type complexity.
+alwaysApply: false
+---
+
+# TypeScript Review
+
+## Type safety rules
+- Avoid `any` — use `unknown` and narrow it
+- Avoid type assertions (`as`) except at system boundaries
+- `strict: true` in tsconfig — no exceptions
+- Use discriminated unions for state modeling
+- Use `unknown` + type guards over `any` + casting
+
+## Leverage utility types
+`Partial`, `Required`, `Readonly`, `Pick`, `Omit`, `Record`, `ReturnType`, `Parameters`, `NonNullable`
+
+## Generic constraints
+```typescript
+// Good: constrained and expressive
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K]
+```
+
+## Common issues to catch
+- Missing null checks in strict mode
+- Implicit `any` from untyped libraries
+- Overuse of `!` non-null assertions
+- `Object` vs `object` vs `Record<string, unknown>`

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/core/assistant/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: assistant
+description: Assistant — on any repo, scan README→docs→AGENTS→CONTRIBUTING→PR templates→task runners→devcontainer→CI→configs before code; cite sources; prefer AGENTS.md for agent behavior; portable across Cursor/Copilot/Claude; use agent-toolkit CLI when needed.
+metadata:
+  author: ulises-jeremias
+  version: "2.1"
+---
+
+# Assistant
+
+Organizational companion for anyone building **for ** in **any** repository (client, internal, or ``). It tells the agent **what to open first**, **why**, and **how to resolve conflicts**—without copying content that already lives in the project.
+
+**Orchestration**
+
+This skill is the **default orchestrator and fallback** for agent work. **Read** `references/ORCHESTRATION.md` for routing (workflows, tool skills, delegation phrasing). Use **`~/.local/share//skills/skill-catalog.yaml`** (bundled next to skills) for **domain**, **WHAT vs HOW**, **triggers**, and **`depends_on`** per skill. **Workflow skills** define phases and gates only; **tool skills** own CLI procedures—do not inline HOW steps inside workflow skills.
+
+**Hard rules**
+
+- Derive answers from **files in the repo** and **machine-local agent-toolkit baseline (`~/.local/share/agent-toolkit/`). **Cite paths** when you recommend workflows.
+- **Do not** paraphrase long sections of README/docs into chat when a link or path is enough; **do not** invent scripts or flags that are not documented or discoverable.
+- **AGENTS.md** (when present) is the **primary contract for agent behavior** in that repo; see [Agent instruction map](#agent-instruction-map) for tie-breakers with tool-specific files.
+
+Extended path hints: `references/REPO_INSPECTION.md`. Orchestration: `references/ORCHESTRATION.md`. Starter `AGENTS.md` for new projects: `references/AGENTS_TEMPLATE.md` (and chezmoi `AGENTS.project.md.tmpl` in the baseline templates).
+
+---
+
+## Expected behavior
+
+1. **On entering a task in a repo**, spend a short **discovery pass**: follow [Repository inspection order](#repository-inspection-order) before editing large areas of code.
+2. **Classify** documentation you find (see [Documentation taxonomy](#documentation-taxonomy)) so you do not apply contributor-only rules to end-user docs or vice versa.
+3. **Prefer official automation** from `Makefile` / `justfile` / `package.json` / CI over ad-hoc commands.
+4. **When advising**, name the **source file** (“per `CONTRIBUTING.md`…”, “`.github/workflows/ci.yml` runs…”).
+5. **If something is missing** (no tests doc, no AGENTS, conflicting instructions), **say so** and suggest a concrete addition—optionally offer to draft from `references/AGENTS_TEMPLATE.md`.
+6. **Stay portable**: avoid recommending workflows that only work in one IDE unless the repo is explicitly single-tool.
+
+---
+
+## Repository inspection order
+
+Use this **sequence** for the **opened repository root** (or the **subpackage root** you are changing in a monorepo). Skips are fine if a path does not exist—document what you skipped.
+
+| Step | Where | What to extract |
+| --- | --- | --- |
+| **1** | `README.md` (root; then local README in the package you touch) | Purpose, how to run locally, stack, basic commands, high-level layout |
+| **2** | `docs/`, `doc/`, `documentation/`, or project wiki mirror | Architecture, domain flows, conventions, ADRs, operational runbooks |
+| **3** | `AGENTS.md` (root; if missing, `docs/AGENTS.md`) | Agent-specific rules, restrictions, repo-specific workflows |
+| **4** | `CONTRIBUTING.md` (or `docs/CONTRIBUTING.md`) | Branch/commit/PR norms, quality bar, review process |
+| **5** | PR templates: `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/PULL_REQUEST_TEMPLATE/*` | Expected PR content, checklists, Definition of Done |
+| **6** | `Makefile`, `justfile`, `package.json` `scripts`, `Taskfile.yml`, `mise.toml`, `pyproject.toml` scripts | **Official** build / test / lint / dev commands |
+| **7** | `.devcontainer/devcontainer.json`, `compose.yaml` / `docker-compose.yml`, `Dockerfile` | How the team expects the dev environment to run |
+| **8** | `.github/workflows/*`, `.gitlab-ci.yml`, `Jenkinsfile`, etc. | Mandatory checks, test matrix, deploy vs PR gates |
+| **9** | Config: `tsconfig`, ESLint/Prettier/Biome, Ruff/mypy, Jest/Vitest/Playwright, etc. | Implicit style and testing conventions |
+| **10** | Source tree | Implementation **after** steps 1–9 give context |
+
+**Monorepos:** run the table for the **root** first, then repeat for the **specific package/service** directory if it has its own README, `package.json`, or CI job names that differ.
+
+---
+
+## Agent instruction map
+
+These files shape **how the assistant should behave**. Discover them with **Glob**, then **Read**.
+
+| Kind | Typical paths | Role |
+| --- | --- | --- |
+| **Portable agent contract** | `AGENTS.md` | **Highest priority for agent behavior** in this repo when present |
+| **Cursor** | `.cursor/rules/**`, `.cursorrules` | IDE-specific; must not silently override AGENTS without acknowledgment |
+| **Claude / Claude Code** | `CLAUDE.md`, `.claude/**` | Tool-specific project memory |
+| **Copilot** | `.github/copilot-instructions.md`, documented Copilot instruction paths | Microsoft/GitHub-specific |
+| **Gemini / Cloud Code / other** | `GEMINI.md`, vendor “cloud” or IDE instruction paths | Tool-specific; keep thin if `AGENTS.md` exists |
+
+**If `AGENTS.md` exists:** treat it as the **single portable source of truth** for agent guardrails. Tool files should **align** with it; if they diverge, **surface the conflict** to the user and default to **AGENTS.md** unless the user says otherwise.
+
+**If `AGENTS.md` is missing** but `.cursor/rules` or `CLAUDE.md` exist: follow those **and** suggest adding a root `AGENTS.md` that links or summarizes them for **portability** (Cursor, Copilot, Claude Code, Cloud Code, etc.).
+
+**If only cloud / vendor markdown exists** (e.g. single-vendor “cloud” instructions): recommend evaluating **`AGENTS.md`** plus short tool stubs so the same rules travel across tools.
+
+---
+
+## Conflict resolution heuristics
+
+| Situation | Resolution |
+| --- | --- | --- |
+| README says “run `npm start`”, `package.json` has no `start` | Trust **`package.json`**; note README drift |
+| `AGENTS.md` vs `CONTRIBUTING.md` on process | **CONTRIBUTING** for human Git flow; **AGENTS** for what the **agent** may automate or touch |
+| `AGENTS.md` vs `.cursor/rules` | **AGENTS.md** wins for stated agent behavior; flag contradiction |
+| Local package README vs root README | **Local** for that package’s commands; **root** for global architecture |
+| Docs vs code | **Docs** describe intent; if code disagrees, **report mismatch** instead of guessing which is “right” |
+| CI does not run a script the README claims is mandatory | **CI config** is authoritative for merge gates; suggest doc fix |
+
+---
+
+## Anti-duplication and citation
+
+- **Summarize** README/docs in your own words only when needed for the task; otherwise **point** to the file and section.
+- **Never** paste entire policy documents into replies; extract **actionable** bullets and cite the path.
+- When suggesting a new rule, **check** it does not duplicate `CONTRIBUTING.md` or `AGENTS.md`.
+- Prefer **one** canonical place per concern (e.g. “all PR rules in template + CONTRIBUTING”).
+
+---
+
+## Documentation taxonomy
+
+Use this to choose tone and strictness:
+
+| Type | Examples | Use for |
+| --- | --- | --- |
+| **General / product** | Root README, user guides | What the product is, how to run it |
+| **Contributors** | CONTRIBUTING, PR template, code review guide | Branches, commits, review, quality |
+| **Agents** | AGENTS.md, tool instruction files | What assistants may or must not do |
+| **Operational / technical** | Runbooks, ADRs, architecture under `docs/` | Deploy, incidents, technical decisions |
+
+---
+
+## Documentation gap signals
+
+Flag gaps **explicitly** when you notice:
+
+- No way to run tests or lint from documented commands.
+- README references scripts that do not exist.
+- CI enforces checks not mentioned for contributors.
+- Multiple conflicting instruction files with no hierarchy.
+- Sensitive operations (migrations, prod) undocumented.
+
+Offer **small, copy-ready** fixes (e.g. a minimal `AGENTS.md` from `references/AGENTS_TEMPLATE.md`).
+
+---
+
+## workstation baseline (optional layer)
+
+When the open repo **is** (or includes) `` / chezmoi `home/`:
+
+- Read repo root **`AGENTS.md`**, **`docs/*.md`**, **`home/.chezmoidata/*`**, **`home/.chezmoiscripts/*.tmpl`**, **`home/dot_local/share//.chezmoiexternal.toml.tmpl`** as needed.
+- For **`agent-toolkit` commands**, run `agent-toolkit --help`.
+
+On **any** machine with the baseline applied:
+
+- **`~/.local/share//`** — bundled skills, templates, MCP examples, `skills-registry.yaml`.
+- **`skills list`**, **`doctor`**, **`loadenv`** — operational discovery.
+
+### New Developer Onboarding
+
+When a developer asks about **setup**, **getting started**, or **validation**:
+
+1. **First-time setup** (cite `docs/wiki/TECHNICAL_QUICKSTART.md`):
+   ```bash
+   git clone git@github.com:ulises-jeremias/.git
+   cd 
+   chezmoi init --source=. -c ~/.config/chezmoi/.toml
+   chezmoi apply --source=. -c ~/.config/chezmoi/.toml --dry-run
+   chezmoi apply --source=. -c ~/.config/chezmoi/.toml
+   ```
+
+2. **Post-setup validation**:
+   ```bash
+   doctor
+   ```
+   Expected: `result: COMPLIANT`
+
+3. **AI tools verification**:
+   ```bash
+   opencode --version  # or claude --version, etc.
+   ls ~/.config/opencode/skills/
+   ```
+
+4. **If issues found**: Run `doctor` and address failures. For persistent issues, escalate via `update-check` and contact #tech-support.
+
+### Helpful Commands for Developers
+
+| Task | Command |
+| --- | --- |
+| Validate setup | `doctor` |
+| Check updates | `update-check` |
+| Update workstation | `chezmoi update && chezmoi apply --source=. -c ~/.config/chezmoi/.toml` |
+| List AI skills | `skills list` |
+| Sync skills | `skills sync` |
+| Health check | **`triage`** (runs **`doctor`**, layout checks) |
+
+### Where to route next (bundled HOW skills)
+
+Use **`skill-catalog.yaml`** next to bundled skills for domains, triggers and **`depends_on`**. Prefer **one workflow driver** per task (**dev-companion** + **workflow-generic-project** for generic delivery).
+
+| Area | Skill(s) | Notes |
+| --- | --- | --- |
+| GitHub PR review threads | **`gh-address-comments`** | Current-branch PR; pairs with **`github-cli-workflow`** for push/PR updates |
+| GitHub Actions failures | **`gh-fix-ci`** | Fetch logs + snippet; plan before coding; pairs with **`planning`** |
+| Draft PR / MR | **`github-cli-workflow`**, **`gitlab-cli-workflow`** | After **`output-handshake`** / **`pr-fallback`** when needed |
+| Linear | **`linear`** | Linear MCP (OAuth); issues, cycles, docs |
+| Figma | **`figma`** (entry), **`figma-implement-design`**, **`figma-code-connect-components`**, **`figma-create-design-system-rules`**, **`figma-create-new-file`** | MCP templates under `~/.local/share//mcp/figma/` |
+| UI patterns / stacks | **`ui-ux-pro-max`** | Design intelligence; complements Figma skills |
+| Playwright | **`playwright-cli`** | CLI browser automation from the shell |
+| Playwright **test** specs | **`e2e-runner`** | Not the same as **`playwright-cli`** |
+| Jupyter notebooks | **`jupyter-notebook`** | Scaffold via **`newnotebook`** |
+| Workstation health | **`triage`** | **`doctor`**, **`doctor --issue`** |
+| Slack | **`slack-cli`**, **`slack-assistant`** | App CLI vs workspace chat |
+| Tickets (external packs) | **`clickup-cli`**, **jira-***, **confluence-*** | As installed via registry / chezmoiexternal |
+| Data | **`dbt-validation`**, **`snowflake-validation`** | Read-only validation patterns |
+
+Client/account overlays live in the workspace (`~/.ai-workspace/packs/` + `knowledge/`) and should be loaded when triggered.
+
+For AI agent assistance, invoke agents using **@mention** in your message (NOT the Task tool): **@planner** (feature planning), **@code-reviewer** (code review), **@security-reviewer** (security), **@tdd-guide** (TDD workflow), **@reference-lookup** (examples from public examples). Agents are defined in `~/.config/opencode/agents/` — they are NOT skills and must NOT be loaded via the skill tool.
+
+---
+
+## Organization playbooks
+
+Client delivery workflows and the skill catalog live under **`~/.local/share//skills/`**. **Read** what is installed; do not invent URLs.
+
+---
+
+## Safety
+
+- No secrets in repos; use env patterns documented for the project and `env.d` where applicable.
+- Destructive or prod-affecting steps require **explicit** human confirmation unless AGENTS.md clearly authorizes them.

agent_toolkit_cli-1.0.3.data/data/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.
+---
+
+# 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 | **ui-ux-pro-max** |
+| 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