@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/cc-agent/references/agent-frontmatter.md

@@ -1,213 +1,213 @@
-# Agent Frontmatter Reference
-
-Complete reference for all agent .md YAML frontmatter fields, based on official Claude Code documentation.
-
-Source: https://code.claude.com/docs/en/sub-agents
-
-## Required Fields
-
-### `name`
-- **Type:** string
-- **Required:** YES
-- **Purpose:** Unique identifier for the agent. Used in `subagent_type` parameter of Task tool.
-- **Examples:**
-  ```yaml
-  name: code-reviewer
-  name: test-runner
-  name: db-migration
-  ```
-
-### `description`
-- **Type:** string (multi-line supported)
-- **Required:** YES
-- **Purpose:** Claude uses this to decide when to delegate tasks to this agent. Must be clear and specific.
-- **Examples:**
-  ```yaml
-  description: Expert code reviewer for PR analysis. Use when reviewing code changes for security, logic, clean code, or feature-specific behavior.
-
-  description: |
-    Fast agent specialized for exploring codebases.
-    Use this when you need to quickly find files by patterns,
-    search code for keywords, or answer questions about the codebase.
-  ```
-
-## Optional Fields
-
-### `model`
-- **Type:** string
-- **Default:** inherit (uses parent's model)
-- **Valid values:** haiku, sonnet, opus, inherit
-- **Guidance:**
-
-| Model | Best for | Cost | Speed |
-|-------|----------|------|-------|
-| `haiku` | Simple tasks, search, scan | Lowest | Fastest |
-| `sonnet` | Most tasks, code generation | Medium | Medium |
-| `opus` | Complex reasoning, planning | Highest | Slowest |
-| `inherit` | When you don't want to override | Parent's | Parent's |
-
-- **Example:**
-  ```yaml
-  model: haiku
-  ```
-
-### `tools`
-- **Type:** string (comma-separated)
-- **Default:** all tools inherited
-- **Purpose:** Whitelist of tools this agent can use. If specified, ONLY these tools are available.
-- **Example:**
-  ```yaml
-  tools: "Read, Grep, Glob, Bash"
-  ```
-
-### `disallowedTools`
-- **Type:** string (comma-separated)
-- **Default:** none
-- **Purpose:** Blacklist of tools to remove from the agent's available tools.
-- **Example:**
-  ```yaml
-  disallowedTools: "Write, Edit, Bash"
-  ```
-
-### `permissionMode`
-- **Type:** string
-- **Default:** default
-- **Valid values:** default, acceptEdits, dontAsk, bypassPermissions, plan
-- **Details:**
-
-| Mode | Behavior | Risk Level |
-|------|----------|------------|
-| `default` | Standard permission prompts | Low |
-| `acceptEdits` | Auto-accept file edit permissions | Medium |
-| `dontAsk` | Auto-deny all permission prompts | Medium |
-| `bypassPermissions` | Skip ALL permission checks | **HIGH** |
-| `plan` | Read-only, no modifications | None |
-
-- **Example:**
-  ```yaml
-  permissionMode: acceptEdits
-  ```
-
-### `skills`
-- **Type:** list of strings
-- **Default:** none
-- **Purpose:** Skills to preload into the agent's context at startup. Full skill content is injected.
-- **Example:**
-  ```yaml
-  skills:
-    - review-code
-    - validate
-  ```
-
-### `hooks`
-- **Type:** object
-- **Default:** none
-- **Purpose:** Lifecycle hooks scoped to this agent only.
-- **Example:**
-  ```yaml
-  hooks:
-    PreToolUse:
-      - matcher: "Bash"
-        hooks:
-          - type: command
-            command: "./scripts/validate-command.sh"
-  ```
-
-### `color`
-- **Type:** string
-- **Default:** none
-- **Purpose:** Visual indicator color (displayed in some UI contexts).
-- **Examples:** blue, yellow, purple, green, red, orange
-
-## Available Tools
-
-Tools that can be referenced in `tools` or `disallowedTools`:
-
-### Core Tools
-| Tool | Purpose |
-|------|---------|
-| `Read` | Read file contents |
-| `Write` | Create/overwrite files |
-| `Edit` | Edit existing files (find-and-replace) |
-| `Bash` | Execute shell commands |
-| `Glob` | Find files by pattern |
-| `Grep` | Search file contents |
-
-### Communication Tools
-| Tool | Purpose |
-|------|---------|
-| `AskUserQuestion` | Ask user interactive questions |
-| `TodoWrite` | Manage task lists |
-
-### Agent Tools
-| Tool | Purpose |
-|------|---------|
-| `Task` | Launch sub-agents |
-| `Skill` | Invoke skills |
-| `ToolSearch` | Discover deferred tools |
-
-### Web Tools
-| Tool | Purpose |
-|------|---------|
-| `WebFetch` | Fetch URL content |
-| `WebSearch` | Search the web |
-
-### Specialized Tools
-| Tool | Purpose |
-|------|---------|
-| `NotebookEdit` | Edit Jupyter notebooks |
-
-### MCP Tools
-| Tool | Purpose |
-|------|---------|
-| `mcp__*` | Any MCP server tool (e.g., `mcp__smartstack__validate_conventions`) |
-
-## Priority & Scope
-
-Agents are loaded in priority order (higher overrides lower):
-
-| Location | Priority | Scope |
-|----------|----------|-------|
-| `--agents` CLI flag | 1 (highest) | Session only |
-| `.claude/agents/` | 2 | Project |
-| `~/.claude/agents/` | 3 | User |
-| Plugin agents | 4 (lowest) | Plugin |
-
-## Examples
-
-### Minimal Agent
-```yaml
----
-name: my-helper
-description: Helps with basic tasks
----
-
-You are a helpful assistant.
-```
-
-### Read-Only Explorer
-```yaml
----
-name: codebase-explorer
-description: Fast codebase search and analysis
-model: haiku
-tools: "Read, Grep, Glob"
-permissionMode: plan
----
-```
-
-### Full-Featured Agent
-```yaml
----
-name: feature-builder
-description: |
-  Builds complete features with tests.
-  Use when implementing new features from requirements.
-model: sonnet
-tools: "Read, Write, Edit, Bash, Grep, Glob"
-permissionMode: acceptEdits
-skills:
-  - validate
-color: green
----
-```
+# Agent Frontmatter Reference
+
+Complete reference for all agent .md YAML frontmatter fields, based on official Claude Code documentation.
+
+Source: https://code.claude.com/docs/en/sub-agents
+
+## Required Fields
+
+### `name`
+- **Type:** string
+- **Required:** YES
+- **Purpose:** Unique identifier for the agent. Used in `subagent_type` parameter of Task tool.
+- **Examples:**
+  ```yaml
+  name: code-reviewer
+  name: test-runner
+  name: db-migration
+  ```
+
+### `description`
+- **Type:** string (multi-line supported)
+- **Required:** YES
+- **Purpose:** Claude uses this to decide when to delegate tasks to this agent. Must be clear and specific.
+- **Examples:**
+  ```yaml
+  description: Expert code reviewer for PR analysis. Use when reviewing code changes for security, logic, clean code, or feature-specific behavior.
+
+  description: |
+    Fast agent specialized for exploring codebases.
+    Use this when you need to quickly find files by patterns,
+    search code for keywords, or answer questions about the codebase.
+  ```
+
+## Optional Fields
+
+### `model`
+- **Type:** string
+- **Default:** inherit (uses parent's model)
+- **Valid values:** haiku, sonnet, opus, inherit
+- **Guidance:**
+
+| Model | Best for | Cost | Speed |
+|-------|----------|------|-------|
+| `haiku` | Simple tasks, search, scan | Lowest | Fastest |
+| `sonnet` | Most tasks, code generation | Medium | Medium |
+| `opus` | Complex reasoning, planning | Highest | Slowest |
+| `inherit` | When you don't want to override | Parent's | Parent's |
+
+- **Example:**
+  ```yaml
+  model: haiku
+  ```
+
+### `tools`
+- **Type:** string (comma-separated)
+- **Default:** all tools inherited
+- **Purpose:** Whitelist of tools this agent can use. If specified, ONLY these tools are available.
+- **Example:**
+  ```yaml
+  tools: "Read, Grep, Glob, Bash"
+  ```
+
+### `disallowedTools`
+- **Type:** string (comma-separated)
+- **Default:** none
+- **Purpose:** Blacklist of tools to remove from the agent's available tools.
+- **Example:**
+  ```yaml
+  disallowedTools: "Write, Edit, Bash"
+  ```
+
+### `permissionMode`
+- **Type:** string
+- **Default:** default
+- **Valid values:** default, acceptEdits, dontAsk, bypassPermissions, plan
+- **Details:**
+
+| Mode | Behavior | Risk Level |
+|------|----------|------------|
+| `default` | Standard permission prompts | Low |
+| `acceptEdits` | Auto-accept file edit permissions | Medium |
+| `dontAsk` | Auto-deny all permission prompts | Medium |
+| `bypassPermissions` | Skip ALL permission checks | **HIGH** |
+| `plan` | Read-only, no modifications | None |
+
+- **Example:**
+  ```yaml
+  permissionMode: acceptEdits
+  ```
+
+### `skills`
+- **Type:** list of strings
+- **Default:** none
+- **Purpose:** Skills to preload into the agent's context at startup. Full skill content is injected.
+- **Example:**
+  ```yaml
+  skills:
+    - review-code
+    - validate
+  ```
+
+### `hooks`
+- **Type:** object
+- **Default:** none
+- **Purpose:** Lifecycle hooks scoped to this agent only.
+- **Example:**
+  ```yaml
+  hooks:
+    PreToolUse:
+      - matcher: "Bash"
+        hooks:
+          - type: command
+            command: "./scripts/validate-command.sh"
+  ```
+
+### `color`
+- **Type:** string
+- **Default:** none
+- **Purpose:** Visual indicator color (displayed in some UI contexts).
+- **Examples:** blue, yellow, purple, green, red, orange
+
+## Available Tools
+
+Tools that can be referenced in `tools` or `disallowedTools`:
+
+### Core Tools
+| Tool | Purpose |
+|------|---------|
+| `Read` | Read file contents |
+| `Write` | Create/overwrite files |
+| `Edit` | Edit existing files (find-and-replace) |
+| `Bash` | Execute shell commands |
+| `Glob` | Find files by pattern |
+| `Grep` | Search file contents |
+
+### Communication Tools
+| Tool | Purpose |
+|------|---------|
+| `AskUserQuestion` | Ask user interactive questions |
+| `TodoWrite` | Manage task lists |
+
+### Agent Tools
+| Tool | Purpose |
+|------|---------|
+| `Task` | Launch sub-agents |
+| `Skill` | Invoke skills |
+| `ToolSearch` | Discover deferred tools |
+
+### Web Tools
+| Tool | Purpose |
+|------|---------|
+| `WebFetch` | Fetch URL content |
+| `WebSearch` | Search the web |
+
+### Specialized Tools
+| Tool | Purpose |
+|------|---------|
+| `NotebookEdit` | Edit Jupyter notebooks |
+
+### MCP Tools
+| Tool | Purpose |
+|------|---------|
+| `mcp__*` | Any MCP server tool (e.g., `mcp__smartstack__validate_conventions`) |
+
+## Priority & Scope
+
+Agents are loaded in priority order (higher overrides lower):
+
+| Location | Priority | Scope |
+|----------|----------|-------|
+| `--agents` CLI flag | 1 (highest) | Session only |
+| `.claude/agents/` | 2 | Project |
+| `~/.claude/agents/` | 3 | User |
+| Plugin agents | 4 (lowest) | Plugin |
+
+## Examples
+
+### Minimal Agent
+```yaml
+---
+name: my-helper
+description: Helps with basic tasks
+---
+
+You are a helpful assistant.
+```
+
+### Read-Only Explorer
+```yaml
+---
+name: codebase-explorer
+description: Fast codebase search and analysis
+model: haiku
+tools: "Read, Grep, Glob"
+permissionMode: plan
+---
+```
+
+### Full-Featured Agent
+```yaml
+---
+name: feature-builder
+description: |
+  Builds complete features with tests.
+  Use when implementing new features from requirements.
+model: sonnet
+tools: "Read, Write, Edit, Bash, Grep, Glob"
+permissionMode: acceptEdits
+skills:
+  - validate
+color: green
+---
+```

package/templates/skills/cc-agent/references/permission-modes.md

@@ -1,102 +1,102 @@
-# Permission Modes Reference
-
-Complete reference for Claude Code agent permission modes.
-
-Source: https://code.claude.com/docs/en/sub-agents
-
-## Overview
-
-Permission modes control how an agent handles permission prompts (e.g., "Allow Edit to file?"). Choosing the right mode balances automation with safety.
-
-## Modes
-
-### `default`
-- **Behavior:** Standard permission prompts for sensitive operations
-- **User sees:** Permission dialogs for Write, Edit, Bash, etc.
-- **Best for:** Interactive agents where user oversight is desired
-- **Risk level:** Low
-- **Example use cases:**
-  - General-purpose development agents
-  - Agents that might make unexpected changes
-  - First-time or untrusted agents
-
-### `acceptEdits`
-- **Behavior:** Auto-accept file edit permissions (Write, Edit)
-- **User sees:** No prompts for file modifications; prompts still appear for Bash
-- **Best for:** Code generation and modification agents
-- **Risk level:** Medium
-- **Example use cases:**
-  - Code scaffolding agents
-  - Refactoring agents
-  - File generation agents
-
-### `dontAsk`
-- **Behavior:** Auto-deny all permission prompts
-- **User sees:** No prompts; sensitive operations silently fail
-- **Best for:** Background tasks that should not interrupt the user
-- **Risk level:** Medium (operations may fail silently)
-- **Example use cases:**
-  - Background monitoring agents
-  - Read-only agents that might accidentally try to write
-  - Agents where failure is acceptable
-
-### `bypassPermissions`
-- **Behavior:** Skip ALL permission checks entirely
-- **User sees:** Nothing; all operations proceed without any checks
-- **Best for:** Fully trusted automation pipelines
-- **Risk level:** **HIGH** - Use with extreme caution
-- **Example use cases:**
-  - CI/CD pipeline agents
-  - Fully automated batch processing
-  - Testing harnesses
-- **Warning:** This mode can execute ANY command without confirmation. Only use for agents you fully trust in controlled environments.
-
-### `plan`
-- **Behavior:** Read-only exploration mode; no modifications allowed
-- **User sees:** No prompts; modification attempts are blocked
-- **Best for:** Research and analysis agents
-- **Risk level:** None
-- **Example use cases:**
-  - Codebase exploration agents
-  - Documentation analysis agents
-  - Code review agents (read-only)
-  - Architecture analysis agents
-
-## Decision Matrix
-
-| Need | Mode |
-|------|------|
-| User should approve all changes | `default` |
-| Agent modifies files autonomously | `acceptEdits` |
-| Agent only reads, never writes | `plan` |
-| Agent runs in background, no prompts | `dontAsk` |
-| Full automation, no checks | `bypassPermissions` |
-
-## Combining with Tools
-
-Permission modes interact with the `tools` field:
-
-| Scenario | Configuration |
-|----------|---------------|
-| Read-only agent | `permissionMode: plan` + `tools: "Read, Grep, Glob"` |
-| File editor | `permissionMode: acceptEdits` + `tools: "Read, Write, Edit, Glob, Grep"` |
-| Shell executor | `permissionMode: default` + `tools: "Bash, Read, Glob"` |
-| Full automation | `permissionMode: bypassPermissions` + all tools |
-
-## Best Practices
-
-1. **Start with `default`** and escalate only if needed
-2. **Use `plan` for research** - prevents accidental modifications
-3. **Prefer `acceptEdits` over `bypassPermissions`** - still blocks dangerous Bash commands
-4. **Never use `bypassPermissions` in production** without careful review
-5. **Document why** a specific mode was chosen in the agent description
-6. **Combine with tool restrictions** for defense in depth:
-   ```yaml
-   # Safe: read-only mode + read-only tools
-   permissionMode: plan
-   tools: "Read, Grep, Glob"
-
-   # Dangerous: bypass + all tools (avoid)
-   permissionMode: bypassPermissions
-   # (no tools restriction = everything allowed)
-   ```
+# Permission Modes Reference
+
+Complete reference for Claude Code agent permission modes.
+
+Source: https://code.claude.com/docs/en/sub-agents
+
+## Overview
+
+Permission modes control how an agent handles permission prompts (e.g., "Allow Edit to file?"). Choosing the right mode balances automation with safety.
+
+## Modes
+
+### `default`
+- **Behavior:** Standard permission prompts for sensitive operations
+- **User sees:** Permission dialogs for Write, Edit, Bash, etc.
+- **Best for:** Interactive agents where user oversight is desired
+- **Risk level:** Low
+- **Example use cases:**
+  - General-purpose development agents
+  - Agents that might make unexpected changes
+  - First-time or untrusted agents
+
+### `acceptEdits`
+- **Behavior:** Auto-accept file edit permissions (Write, Edit)
+- **User sees:** No prompts for file modifications; prompts still appear for Bash
+- **Best for:** Code generation and modification agents
+- **Risk level:** Medium
+- **Example use cases:**
+  - Code scaffolding agents
+  - Refactoring agents
+  - File generation agents
+
+### `dontAsk`
+- **Behavior:** Auto-deny all permission prompts
+- **User sees:** No prompts; sensitive operations silently fail
+- **Best for:** Background tasks that should not interrupt the user
+- **Risk level:** Medium (operations may fail silently)
+- **Example use cases:**
+  - Background monitoring agents
+  - Read-only agents that might accidentally try to write
+  - Agents where failure is acceptable
+
+### `bypassPermissions`
+- **Behavior:** Skip ALL permission checks entirely
+- **User sees:** Nothing; all operations proceed without any checks
+- **Best for:** Fully trusted automation pipelines
+- **Risk level:** **HIGH** - Use with extreme caution
+- **Example use cases:**
+  - CI/CD pipeline agents
+  - Fully automated batch processing
+  - Testing harnesses
+- **Warning:** This mode can execute ANY command without confirmation. Only use for agents you fully trust in controlled environments.
+
+### `plan`
+- **Behavior:** Read-only exploration mode; no modifications allowed
+- **User sees:** No prompts; modification attempts are blocked
+- **Best for:** Research and analysis agents
+- **Risk level:** None
+- **Example use cases:**
+  - Codebase exploration agents
+  - Documentation analysis agents
+  - Code review agents (read-only)
+  - Architecture analysis agents
+
+## Decision Matrix
+
+| Need | Mode |
+|------|------|
+| User should approve all changes | `default` |
+| Agent modifies files autonomously | `acceptEdits` |
+| Agent only reads, never writes | `plan` |
+| Agent runs in background, no prompts | `dontAsk` |
+| Full automation, no checks | `bypassPermissions` |
+
+## Combining with Tools
+
+Permission modes interact with the `tools` field:
+
+| Scenario | Configuration |
+|----------|---------------|
+| Read-only agent | `permissionMode: plan` + `tools: "Read, Grep, Glob"` |
+| File editor | `permissionMode: acceptEdits` + `tools: "Read, Write, Edit, Glob, Grep"` |
+| Shell executor | `permissionMode: default` + `tools: "Bash, Read, Glob"` |
+| Full automation | `permissionMode: bypassPermissions` + all tools |
+
+## Best Practices
+
+1. **Start with `default`** and escalate only if needed
+2. **Use `plan` for research** - prevents accidental modifications
+3. **Prefer `acceptEdits` over `bypassPermissions`** - still blocks dangerous Bash commands
+4. **Never use `bypassPermissions` in production** without careful review
+5. **Document why** a specific mode was chosen in the agent description
+6. **Combine with tool restrictions** for defense in depth:
+   ```yaml
+   # Safe: read-only mode + read-only tools
+   permissionMode: plan
+   tools: "Read, Grep, Glob"
+
+   # Dangerous: bypass + all tools (avoid)
+   permissionMode: bypassPermissions
+   # (no tools restriction = everything allowed)
+   ```