@atlashub/smartstack-cli 3.39.0 → 3.41.0

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

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