@atlashub/smartstack-cli 4.81.0 → 5.0.0

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

@@ -1,213 +0,0 @@
-# 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 +0,0 @@
-# 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

@@ -1,144 +0,0 @@
-# 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

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