@atlashub/smartstack-cli 1.37.0 → 2.1.0

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`

package/templates/skills/cc-agent/steps/step-01-design.md

@@ -0,0 +1,186 @@
+---
+name: step-01-design
+description: Design agent - choose model, tools, permissions, skills to preload
+next_step: steps/step-02-generate.md
+---
+
+# Step 1: Design Agent
+
+## MANDATORY EXECUTION RULES:
+- ALWAYS ask the user for design decisions (don't assume)
+- For UPDATE: show current values and ask what to change
+- Load reference docs for guidance
+- Tools should follow principle of least privilege
+
+## YOUR TASK:
+Guide the user through agent design decisions. Gather model, tools, permissions, skills, and system prompt content.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load References
+
+```
+Read: "references/agent-frontmatter.md"
+Read: "references/tools-reference.md"
+Read: "references/permission-modes.md"
+```
+
+### 2. Gather Description
+
+```yaml
+AskUserQuestion:
+  header: "Purpose"
+  question: "Describe what this agent does and WHEN Claude should delegate to it. Be specific - Claude uses this to decide delegation. Example: 'Expert code reviewer for PR analysis. Use when reviewing code changes for security, logic, or performance.'"
+```
+
+Store in {description}.
+
+### 3. Choose Model
+
+```yaml
+AskUserQuestion:
+  header: "Model"
+  question: "Which model should this agent use?"
+  options:
+    - label: "Haiku (Recommended for fast tasks)"
+      description: "Fast and cheap. Best for: search, scan, simple checks, read-only tasks."
+    - label: "Sonnet"
+      description: "Balanced. Best for: code generation, analysis, most tasks."
+    - label: "Opus"
+      description: "Most capable. Best for: complex reasoning, architecture, planning."
+    - label: "Inherit"
+      description: "Use parent's model. Best when you don't want to override."
+```
+
+### 4. Choose Tools
+
+```yaml
+AskUserQuestion:
+  header: "Tools"
+  question: "What tools does this agent need?"
+  options:
+    - label: "Read-only"
+      description: "Read, Grep, Glob - safe exploration only"
+    - label: "Read + Write"
+      description: "Read, Write, Edit, Grep, Glob - file modifications"
+    - label: "Full dev"
+      description: "Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch"
+    - label: "Custom"
+      description: "I'll specify the exact tool list"
+  multiSelect: false
+```
+
+If "Custom" selected, ask for comma-separated list.
+
+Map selections:
+- Read-only → "Read, Grep, Glob"
+- Read + Write → "Read, Write, Edit, Grep, Glob"
+- Full dev → "Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch"
+
+Also ask about disallowed tools:
+
+```yaml
+AskUserQuestion:
+  header: "Blocked"
+  question: "Should any tools be explicitly blocked? (Usually not needed)"
+  options:
+    - label: "None (Recommended)"
+      description: "Don't block any tools beyond the allowed list"
+    - label: "Block Bash"
+      description: "Prevent command execution"
+    - label: "Block Write/Edit"
+      description: "Read-only, no file modifications"
+    - label: "Custom"
+      description: "I'll specify tools to block"
+```
+
+### 5. Choose Permission Mode
+
+```yaml
+AskUserQuestion:
+  header: "Permissions"
+  question: "How should this agent handle permission prompts?"
+  options:
+    - label: "Default (Recommended)"
+      description: "Standard permission prompts for sensitive operations"
+    - label: "Accept Edits"
+      description: "Auto-accept file edits. Good for code generation agents."
+    - label: "Plan (read-only)"
+      description: "Read-only exploration mode. No modifications allowed."
+    - label: "Don't Ask"
+      description: "Auto-deny all permission prompts. For background tasks."
+```
+
+### 6. Choose Skills to Preload (optional)
+
+```yaml
+AskUserQuestion:
+  header: "Skills"
+  question: "Should any skills be preloaded into this agent? Preloaded skills inject their full content at startup."
+  options:
+    - label: "None (Recommended)"
+      description: "Agent operates without preloaded skills"
+    - label: "Select skills"
+      description: "I'll choose which skills to preload"
+```
+
+If "Select skills", list available skills and let user choose.
+
+### 7. Design System Prompt
+
+Ask the user to describe the agent's behavior:
+
+```yaml
+AskUserQuestion:
+  header: "Behavior"
+  question: "Describe the agent's behavior pattern. Choose a template or describe custom behavior."
+  options:
+    - label: "Explorer"
+      description: "Search codebase, read files, report findings. Workflow: Search → Read → Analyze → Report."
+    - label: "Modifier"
+      description: "Read code, make changes, validate. Workflow: Read → Edit → Validate → Report."
+    - label: "Validator"
+      description: "Check conventions, rules, quality. Workflow: Scan → Check → Report issues."
+    - label: "Custom"
+      description: "I'll describe the workflow and behavior"
+```
+
+If "Custom", ask for detailed description of:
+1. What the agent does when invoked
+2. The workflow steps (numbered)
+3. Key execution rules
+4. Output format
+
+### 8. Show Design Summary
+
+```
+Agent Design:
+
+| Field | Value |
+|-------|-------|
+| Name | {agent_name} |
+| Description | {description} (truncated) |
+| Model | {model} |
+| Tools | {tools} |
+| Blocked tools | {disallowed_tools} |
+| Permission mode | {permission_mode} |
+| Preloaded skills | {preloaded_skills} |
+| Behavior pattern | {pattern} |
+| Category | {category} |
+
+→ Generating agent file...
+```
+
+---
+
+## SUCCESS METRICS:
+- All required fields gathered from user
+- Model choice appropriate for agent's purpose
+- Tools follow least privilege principle
+- Permission mode matches risk level
+- System prompt pattern identified
+
+## NEXT STEP:
+After design is confirmed, proceed directly to `./step-02-generate.md`

package/templates/skills/cc-agent/steps/step-02-generate.md

@@ -0,0 +1,204 @@
+---
+name: step-02-generate
+description: Generate agent .md file from template based on design choices
+next_step: steps/step-03-validate.md
+---
+
+# Step 2: Generate Agent File
+
+## MANDATORY EXECUTION RULES:
+- ALWAYS load the appropriate template from `templates/` directory
+- ALWAYS use the design choices from Step 1
+- For UPDATE: read existing agent first, then apply changes
+- Generate COMPLETE agent file (not a stub)
+
+## YOUR TASK:
+Generate the agent .md file based on the design choices gathered in Step 1.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Template
+
+Based on agent configuration:
+
+```
+Standalone (no category)     → Read: "templates/agent-standalone.md"
+Categorized (with category)  → Read: "templates/agent-categorized.md"
+With preloaded skills        → Read: "templates/agent-with-skills.md"
+```
+
+### 2. Create Directory (if needed)
+
+```bash
+# For categorized agents
+mkdir -p {target_dir}/{category}/
+```
+
+### 3. Generate Frontmatter
+
+Build the YAML frontmatter from design choices:
+
+```yaml
+---
+name: {agent_name}
+description: {description}
+```
+
+Add optional fields only if they differ from defaults:
+
+```yaml
+# Only if not inherit
+model: {model}
+
+# Only if explicitly specified
+tools: "{tools}"
+
+# Only if blocking specific tools
+disallowedTools: "{disallowed_tools}"
+
+# Only if not default
+permissionMode: {permission_mode}
+
+# Only if preloading skills
+skills:
+  - {skill_1}
+  - {skill_2}
+
+# Optional visual indicator
+color: {color}
+```
+
+Close frontmatter:
+```yaml
+---
+```
+
+### 4. Generate System Prompt Content
+
+Based on the behavior pattern chosen in Step 1:
+
+**Explorer pattern:**
+```markdown
+You are a specialized exploration agent for {purpose}.
+
+## Workflow
+
+1. **Search**: Use Grep and Glob to find relevant files
+2. **Read**: Load and analyze discovered files
+3. **Analyze**: Identify patterns, dependencies, and relationships
+4. **Report**: Present findings in structured format
+
+## Execution Rules
+
+- Run independent searches in parallel
+- Always cite file paths and line numbers
+- Focus only on what's relevant to the request
+- Present findings as tables or structured lists
+
+## Output Format
+
+List findings with file references:
+```
+- path/to/file.ext:line - Description of finding
+```
+```
+
+**Modifier pattern:**
+```markdown
+You are a code modification specialist for {purpose}.
+
+## Workflow
+
+1. **Read**: Load all specified files with Read tool
+2. **Analyze**: Understand current structure and patterns
+3. **Edit**: Apply requested changes using Edit tool
+4. **Validate**: Verify changes are correct
+5. **Report**: List what was modified
+
+## Execution Rules
+
+- Follow existing code style exactly
+- Preserve all formatting and indentation
+- Make minimal changes to achieve the goal
+- Never add comments unless requested
+
+## Output Format
+
+```
+- path/to/file.ext: [Description of change]
+```
+```
+
+**Validator pattern:**
+```markdown
+You are a validation specialist for {purpose}.
+
+## Workflow
+
+1. **Scan**: Find all files to validate
+2. **Check**: Apply validation rules to each file
+3. **Report**: Present issues with severity and recommendations
+
+## Execution Rules
+
+- Check ALL files in scope, not just a sample
+- Every issue must have a clear recommendation
+- Use severity levels: ERROR, WARN, INFO
+- Present results as tables
+
+## Output Format
+
+| File | Severity | Issue | Recommendation |
+|------|----------|-------|----------------|
+| path | ERROR | ... | ... |
+```
+
+**Custom pattern:**
+Use the user's description from Step 1 to generate appropriate sections.
+
+### 5. Write Agent File
+
+Use Write tool to create the file at {target_path}.
+
+### 6. For UPDATE Subcommand
+
+If {subcommand} = "update":
+1. Read existing file at {target_path}
+2. Parse current frontmatter
+3. Apply only the requested changes (merge frontmatter, update content sections)
+4. Use Edit tool for targeted modifications
+5. Preserve custom content not being updated
+
+### 7. Confirm Generation
+
+```
+Generated: {target_path}
+
+Frontmatter:
+  name: {agent_name}
+  description: {description} (truncated)
+  model: {model}
+  tools: {tools}
+  permissionMode: {permission_mode}
+
+Content sections:
+  - Workflow ({step_count} steps)
+  - Execution Rules
+  - Output Format
+
+→ Validating agent...
+```
+
+---
+
+## SUCCESS METRICS:
+- Agent .md file created at correct path
+- Frontmatter includes all required and chosen optional fields
+- System prompt is clear and actionable
+- Content follows the chosen behavior pattern
+- No placeholder text left unreplaced
+
+## NEXT STEP:
+Proceed directly to `./step-03-validate.md`

package/templates/skills/cc-agent/steps/step-03-validate.md

@@ -0,0 +1,130 @@
+---
+name: step-03-validate
+description: Validate generated agent file and display final summary
+---
+
+# Step 3: Validate Agent
+
+## MANDATORY EXECUTION RULES:
+- Validate the generated file against official conventions
+- Check frontmatter completeness
+- Verify tool names are valid
+- Display actionable report if issues found
+
+## YOUR TASK:
+Validate the generated agent against official Claude Code conventions and display a final summary.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Read Generated File
+
+```
+Read: "{target_path}"
+```
+
+### 2. Validate Frontmatter
+
+**Required fields:**
+- [ ] `name` exists and is a valid identifier
+- [ ] `description` exists, non-empty, actionable for Claude delegation
+
+**Optional field validation:**
+- [ ] `model` is valid: haiku, sonnet, opus, inherit (or absent)
+- [ ] `tools` references valid tool names (see tools-reference.md)
+- [ ] `disallowedTools` references valid tool names
+- [ ] `permissionMode` is valid: default, acceptEdits, dontAsk, bypassPermissions, plan
+- [ ] `skills` references existing skill names
+- [ ] `color` is a valid color name (if present)
+
+**Valid tool names:**
+```
+Read, Write, Edit, Bash, Glob, Grep, Task, WebFetch, WebSearch,
+NotebookEdit, AskUserQuestion, TodoWrite, Skill, ToolSearch,
+mcp__* (any MCP tool)
+```
+
+### 3. Validate Content
+
+- [ ] Has workflow or instructions section
+- [ ] Workflow has numbered steps
+- [ ] Has execution rules
+- [ ] Has output format specification
+- [ ] Content is not empty (> 5 lines of non-frontmatter content)
+- [ ] No unreplaced placeholder text
+
+### 4. Check Consistency
+
+- [ ] If `permissionMode: plan` → tools should be read-only (warn if Write/Edit/Bash included)
+- [ ] If `model: haiku` → agent should be designed for simple/fast tasks (info)
+- [ ] If `skills` field present → referenced skills exist in scope
+- [ ] Description matches the agent's actual capabilities (tools + content)
+
+### 5. Check Against Built-in Agents
+
+Verify the agent doesn't duplicate a built-in agent:
+
+| Built-in | Purpose |
+|----------|---------|
+| Explore | Fast codebase search, read-only (haiku) |
+| Plan | Research and design, read-only (inherit) |
+| general-purpose | Complex multi-step tasks (all tools) |
+| Bash | Command execution in separate context |
+
+If the new agent overlaps significantly with a built-in, display a warning:
+```
+WARN: This agent's purpose overlaps with the built-in '{name}' agent.
+Consider using the built-in agent instead, or ensure this agent adds
+unique value (specialized prompts, restricted tools, preloaded skills).
+```
+
+### 6. Display Validation Report
+
+```
+Agent Validation Report:
+
+| Check | Status |
+|-------|--------|
+| Frontmatter complete | PASS/FAIL |
+| Tool names valid | PASS/FAIL |
+| Permission mode valid | PASS/FAIL |
+| Content quality | PASS/WARN |
+| No built-in overlap | PASS/WARN |
+| Skills references | PASS/WARN/N/A |
+
+{If any FAIL: show specific issues and recommendations}
+```
+
+### 7. Display Final Summary
+
+```
+Agent Created Successfully!
+
+| Property | Value |
+|----------|-------|
+| Name | {agent_name} |
+| Location | {target_path} |
+| Model | {model} |
+| Tools | {tools} |
+| Permission mode | {permission_mode} |
+| Skills | {preloaded_skills} |
+
+Usage:
+  In Task tool: subagent_type="{agent_name}"
+  In skill frontmatter: agent: "{agent_name}"
+  In agent frontmatter: (reference by name)
+
+Next steps:
+- Test the agent via Task tool
+- Reference it in a skill with `context: fork` and `agent: {agent_name}`
+- Run audit: /cc-audit
+```
+
+---
+
+## SUCCESS METRICS:
+- All validations pass (or issues clearly reported)
+- Final summary displayed with usage instructions
+- Agent is ready to use
+- No built-in overlap warnings (or acknowledged)

package/templates/skills/cc-agent/templates/agent-categorized.md

@@ -0,0 +1,67 @@
+# Template: Categorized Agent
+
+Use this template for agents that belong to a category subdirectory (e.g., efcore/, gitflow/).
+
+## Generated agent file format:
+
+```yaml
+---
+name: {{AGENT_NAME}}
+description: {{DESCRIPTION}}
+{{#if MODEL}}
+model: {{MODEL}}
+{{/if}}
+{{#if TOOLS}}
+tools: "{{TOOLS}}"
+{{/if}}
+{{#if DISALLOWED_TOOLS}}
+disallowedTools: "{{DISALLOWED_TOOLS}}"
+{{/if}}
+{{#if PERMISSION_MODE}}
+permissionMode: {{PERMISSION_MODE}}
+{{/if}}
+{{#if COLOR}}
+color: {{COLOR}}
+{{/if}}
+---
+
+{{SYSTEM_PROMPT}}
+
+## Context: {{CATEGORY}}
+
+This agent is part of the **{{CATEGORY}}** agent group, specialized for {{CATEGORY_PURPOSE}}.
+
+## Workflow
+
+1. **{{STEP_1_NAME}}**: {{STEP_1_DESC}}
+2. **{{STEP_2_NAME}}**: {{STEP_2_DESC}}
+3. **{{STEP_3_NAME}}**: {{STEP_3_DESC}}
+
+## Execution Rules
+
+- {{RULE_1}}
+- {{RULE_2}}
+- {{RULE_3}}
+
+## Output Format
+
+{{OUTPUT_FORMAT_DESCRIPTION}}
+```
+
+## File Location:
+- Project: `.claude/agents/{category}/{name}.md`
+- Global: `~/.claude/agents/{category}/{name}.md`
+- Templates: `templates/agents/{category}/{name}.md`
+
+## Category Examples:
+| Category | Purpose | Agents |
+|----------|---------|--------|
+| `efcore` | EF Core database operations | migration, db-status, db-deploy, conflicts |
+| `gitflow` | Git workflow management | commit, merge, plan, finish, status |
+| `testing` | Test execution and validation | unit-tests, integration-tests, coverage |
+
+## Notes:
+- Category directories group related agents together
+- Agents within a category often share similar tool requirements
+- Category name should be lowercase, descriptive
+- Each agent in the category should have a distinct, non-overlapping purpose