@atlashub/smartstack-cli 1.36.0 → 2.0.0

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

@@ -0,0 +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
+---
+```

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

@@ -0,0 +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)
+   ```

package/templates/skills/cc-agent/references/tools-reference.md

@@ -0,0 +1,144 @@
+# Tools Reference
+
+Complete reference of all tools available in Claude Code agents and skills.
+
+Source: https://code.claude.com/docs/en/
+
+## Core File Tools
+
+### Read
+- **Purpose:** Read file contents from the filesystem
+- **Input:** file_path (absolute), optional offset and limit for large files
+- **Capabilities:** Text files, images (PNG, JPG), PDFs, Jupyter notebooks
+- **Risk:** None (read-only)
+
+### Write
+- **Purpose:** Create or overwrite files
+- **Input:** file_path (absolute), content
+- **Risk:** Medium (overwrites existing files)
+- **Requirement:** Must Read file first if it exists
+
+### Edit
+- **Purpose:** Find-and-replace edits in existing files
+- **Input:** file_path, old_string, new_string, optional replace_all
+- **Risk:** Medium (modifies files)
+- **Requirement:** Must Read file first; old_string must be unique
+
+### Glob
+- **Purpose:** Find files by glob pattern
+- **Input:** pattern (e.g., `**/*.ts`), optional path
+- **Risk:** None (read-only)
+- **Use for:** File discovery by name pattern
+
+### Grep
+- **Purpose:** Search file contents using regex
+- **Input:** pattern (regex), optional path, glob filter, output_mode
+- **Risk:** None (read-only)
+- **Use for:** Content search, finding implementations
+
+## Execution Tools
+
+### Bash
+- **Purpose:** Execute shell commands
+- **Input:** command, optional timeout, description
+- **Risk:** High (can execute any command)
+- **Notes:** Working directory persists, shell state does not
+
+## Communication Tools
+
+### AskUserQuestion
+- **Purpose:** Ask the user interactive questions with options
+- **Input:** questions array with options, headers, descriptions
+- **Risk:** None (user interaction)
+- **Notes:** Users can always select "Other" for custom input
+
+### TodoWrite
+- **Purpose:** Manage structured task lists
+- **Input:** todos array with content, status, activeForm
+- **Risk:** None (UI only)
+
+## Agent Tools
+
+### Task
+- **Purpose:** Launch specialized sub-agents
+- **Input:** prompt, subagent_type, optional model/max_turns
+- **Risk:** Depends on agent configuration
+- **Notes:** Agents run in isolated contexts
+
+### Skill
+- **Purpose:** Invoke skills (slash commands)
+- **Input:** skill name, optional args
+- **Risk:** Depends on skill
+
+### ToolSearch
+- **Purpose:** Discover and load deferred tools
+- **Input:** query (keyword search or `select:tool_name`)
+- **Risk:** None
+
+## Web Tools
+
+### WebFetch
+- **Purpose:** Fetch and analyze web content
+- **Input:** url, prompt
+- **Risk:** None (read-only)
+- **Notes:** Fails for authenticated URLs; use MCP tools instead
+
+### WebSearch
+- **Purpose:** Search the web
+- **Input:** query, optional domain filters
+- **Risk:** None (read-only)
+
+## Specialized Tools
+
+### NotebookEdit
+- **Purpose:** Edit Jupyter notebook cells
+- **Input:** notebook_path, cell_number, new_source
+- **Risk:** Medium (modifies notebooks)
+
+## MCP Tools
+
+### Pattern: `mcp__{server}__{tool}`
+- **Purpose:** Tools provided by MCP (Model Context Protocol) servers
+- **Examples:**
+  - `mcp__smartstack__validate_conventions`
+  - `mcp__smartstack__scaffold_extension`
+  - `mcp__context7__query-docs`
+- **Risk:** Varies by tool
+- **Notes:** Must be loaded via ToolSearch first if deferred
+
+## Tool Selection Guide
+
+### By Risk Level
+
+| Risk | Tools |
+|------|-------|
+| None | Read, Glob, Grep, WebFetch, WebSearch, AskUserQuestion, TodoWrite, ToolSearch |
+| Medium | Write, Edit, NotebookEdit |
+| High | Bash |
+| Variable | Task, Skill, mcp__* |
+
+### By Use Case
+
+| Use Case | Recommended Tools |
+|----------|-------------------|
+| Exploration / Research | Read, Glob, Grep, WebSearch |
+| Code Generation | Read, Write, Edit, Glob, Grep |
+| Full Development | Read, Write, Edit, Bash, Glob, Grep |
+| Testing | Bash, Read, Glob, Grep |
+| Documentation | Read, Write, Glob, Grep, WebFetch |
+| Validation | Read, Glob, Grep, mcp__* |
+
+### Principle of Least Privilege
+
+Always give agents the minimum tools needed:
+
+```yaml
+# Too broad
+tools: "Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, Skill"
+
+# Just right for an explorer
+tools: "Read, Grep, Glob"
+
+# Just right for a code modifier
+tools: "Read, Write, Edit, Glob, Grep"
+```

package/templates/skills/cc-agent/steps/step-00-init.md

@@ -0,0 +1,134 @@
+---
+name: step-00-init
+description: Parse subcommand, agent name, scope, category, and resolve target directory
+next_step: steps/step-01-design.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES:
+- ALWAYS parse subcommand first (create or update)
+- ALWAYS validate agent name uniqueness
+- ALWAYS resolve target file path before proceeding
+- For UPDATE: verify agent exists before continuing
+
+## YOUR TASK:
+Parse input arguments, validate the agent name, and resolve the target file path.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Input
+
+```
+Arguments from $ARGUMENTS:
+  First word   → {subcommand} ("create" or "update")
+  Second word  → {agent_name} (unique identifier)
+  --scope X    → {scope} (default: "project")
+  --category X → {category} (optional, for subdirectory)
+
+Valid subcommands: create, update
+Valid scopes: project, global, templates
+```
+
+If {subcommand} is missing or invalid:
+
+```yaml
+AskUserQuestion:
+  header: "Action"
+  question: "What do you want to do?"
+  options:
+    - label: "Create"
+      description: "Create a new agent from scratch"
+    - label: "Update"
+      description: "Update an existing agent"
+```
+
+### 2. Validate Agent Name
+
+If {agent_name} missing:
+
+```yaml
+AskUserQuestion:
+  header: "Name"
+  question: "What is the agent name? (unique identifier, kebab-case)"
+```
+
+Validation rules:
+- Kebab-case recommended (hyphens, no spaces)
+- Must be unique within scope
+- Must not conflict with built-in agents (Explore, Plan, general-purpose, Bash)
+
+### 3. Resolve Target Path
+
+```
+Based on {scope} and {category}:
+
+  "project" →
+    No category:  {target_path} = "{cwd}/.claude/agents/{agent_name}.md"
+    With category: {target_path} = "{cwd}/.claude/agents/{category}/{agent_name}.md"
+
+  "global" →
+    No category:  {target_path} = "~/.claude/agents/{agent_name}.md"
+    With category: {target_path} = "~/.claude/agents/{category}/{agent_name}.md"
+
+  "templates" →
+    No category:  {target_path} = "{cwd}/templates/agents/{agent_name}.md"
+    With category: {target_path} = "{cwd}/templates/agents/{category}/{agent_name}.md"
+```
+
+### 4. Check Existing
+
+**For CREATE:**
+- Verify {target_path} does NOT already exist
+- If exists: warn and ask to overwrite or switch to update
+
+**For UPDATE:**
+- Verify {target_path} exists
+- If missing: search for agent in other locations, suggest correct path
+- If found: read file and extract current frontmatter
+
+### 5. List Existing Agents (for context)
+
+Scan the target scope for existing agents:
+```
+Glob: "{target_dir}/*.md"
+Glob: "{target_dir}/**/*.md"
+```
+
+Display:
+```
+Existing agents in {scope}:
+| Name | Category | Model |
+|------|----------|-------|
+| {name} | {cat} | {model} |
+```
+
+### 6. Show Summary
+
+```
+Agent Configuration:
+
+| Setting | Value |
+|---------|-------|
+| Action | {subcommand} |
+| Name | {agent_name} |
+| Scope | {scope} |
+| Category | {category} |
+| Target | {target_path} |
+
+→ Designing agent...
+```
+
+---
+
+## SUCCESS METRICS:
+- Subcommand correctly identified
+- Agent name validated (unique, not built-in)
+- Target path resolved and checked
+- Existing agents listed for context
+- Summary displayed
+
+## NEXT STEP:
+After showing summary, proceed directly to `./step-01-design.md`