@atlashub/smartstack-cli 1.37.0 → 2.0.0

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

@@ -0,0 +1,94 @@
+# Template: Agent with Preloaded Skills
+
+Use this template for agents that need skills injected at startup for domain knowledge.
+
+## Generated agent file format:
+
+```yaml
+---
+name: {{AGENT_NAME}}
+description: {{DESCRIPTION}}
+{{#if MODEL}}
+model: {{MODEL}}
+{{/if}}
+{{#if TOOLS}}
+tools: "{{TOOLS}}"
+{{/if}}
+{{#if PERMISSION_MODE}}
+permissionMode: {{PERMISSION_MODE}}
+{{/if}}
+skills:
+{{#each SKILLS}}
+  - {{this}}
+{{/each}}
+{{#if COLOR}}
+color: {{COLOR}}
+{{/if}}
+---
+
+{{SYSTEM_PROMPT}}
+
+## Preloaded Knowledge
+
+This agent has the following skills preloaded for domain expertise:
+{{#each SKILLS}}
+- **{{this}}**: Provides knowledge about {{SKILL_PURPOSE}}
+{{/each}}
+
+## 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}}
+- Always reference preloaded skill knowledge when applicable
+- {{RULE_3}}
+
+## Output Format
+
+{{OUTPUT_FORMAT_DESCRIPTION}}
+```
+
+## How Skills Preloading Works:
+- The `skills` field injects the FULL content of each listed skill into the agent's context at startup
+- This gives the agent domain-specific knowledge without needing to search for it
+- Increases initial context size but improves response quality
+- Skills must exist in the same scope or a higher-priority scope
+
+## When to Use:
+- Agent needs deep domain knowledge (e.g., code reviewer needs review-code skill)
+- Agent operates in a specific framework context
+- Agent needs access to conventions and patterns
+- Agent should follow specific workflows defined in skills
+
+## Considerations:
+- Each preloaded skill adds to context size
+- Limit to 1-3 skills for optimal performance
+- Prefer specific skills over broad ones
+- Ensure skills are relevant to the agent's purpose
+
+## Example:
+```yaml
+---
+name: smartstack-reviewer
+description: Code reviewer specialized in SmartStack conventions
+model: sonnet
+tools: "Read, Grep, Glob"
+permissionMode: plan
+skills:
+  - review-code
+  - validate
+---
+
+You are a SmartStack-aware code reviewer. Use the preloaded review-code
+and validate skills to check code against SmartStack conventions.
+```
+
+## Notes:
+- The code-reviewer agent in SmartStack uses this pattern (loads review-code skill)
+- Keep the number of preloaded skills minimal (1-3)
+- Agent description should mention the specialized knowledge area

package/templates/skills/cc-audit/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: cc-audit
+description: |
+  Audit Claude Code components (skills, agents, hooks, settings).
+  Use this skill when:
+  - Checking component health and conventions
+  - Inventorying all components in a project
+  - Validating structure before deployment
+  - Verifying cross-references between components
+argument-hint: "[project|global|templates]"
+disable-model-invocation: true
+---
+
+<objective>
+Audit all Claude Code components (skills, agents, hooks, settings) in a given scope, validate their structure against official conventions, and generate a comprehensive report with actionable recommendations.
+</objective>
+
+<quick_start>
+
+```bash
+/cc-audit                  # Audit current project (.claude/)
+/cc-audit project          # Audit project-level components
+/cc-audit global           # Audit user-level (~/.claude/)
+/cc-audit templates        # Audit SmartStack CLI templates/
+/cc-audit all              # Audit all scopes
+```
+
+</quick_start>
+
+<parameters>
+
+<flags>
+| Flag | Description |
+|------|-------------|
+| `project` | Scan `.claude/` in current working directory |
+| `global` | Scan `~/.claude/` (user-level) |
+| `templates` | Scan `templates/` (SmartStack CLI source) |
+| `all` | Scan all scopes |
+| `--fix` | Attempt auto-fix of common issues |
+| `--verbose` | Show detailed validation per component |
+</flags>
+
+<examples>
+```bash
+# Quick health check
+/cc-audit
+
+# Full audit with details
+/cc-audit all --verbose
+
+# Audit and fix issues
+/cc-audit project --fix
+```
+</examples>
+
+</parameters>
+
+<workflow>
+1. Parse scope and flags
+2. Scan directories for all components
+3. Validate each component against official conventions
+4. Check cross-references (skills ↔ agents, hooks ↔ scripts)
+5. Generate audit report with status and recommendations
+</workflow>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{scope}` | string | project, global, templates, or all |
+| `{fix_mode}` | boolean | Auto-fix common issues |
+| `{verbose}` | boolean | Show detailed output |
+| `{scan_paths}` | string[] | Directories to scan |
+| `{skills_found}` | object[] | Skills inventory |
+| `{agents_found}` | object[] | Agents inventory |
+| `{hooks_found}` | object[] | Hooks inventory |
+| `{issues}` | object[] | All issues found |
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+</entry_point>
+
+<step_files>
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `steps/step-00-init.md` | Parse scope, detect environment, resolve paths |
+| 01 | `steps/step-01-scan.md` | Scan all components in target directories |
+| 02 | `steps/step-02-analyze.md` | Validate structure, frontmatter, cross-references |
+| 03 | `steps/step-03-report.md` | Generate audit report with recommendations |
+</step_files>
+
+<execution_rules>
+- **Load one step at a time** - Progressive loading
+- **Non-destructive** - Read-only unless --fix is set
+- **Comprehensive** - Check ALL components, not just a sample
+- **Actionable** - Every issue must have a clear recommendation
+- **Reference official docs** - Base all checks on Claude Code documentation
+</execution_rules>
+
+<success_criteria>
+- All components in scope are inventoried
+- Each component validated against official conventions
+- Cross-references verified (no broken links)
+- Clear report with status per component
+- Actionable recommendations for each issue
+</success_criteria>

package/templates/skills/cc-audit/references/agent-checklist.md

@@ -0,0 +1,91 @@
+# Agent Validation Checklist
+
+Based on official Claude Code documentation: https://code.claude.com/docs/en/sub-agents
+
+## Required
+
+- [ ] Agent file is a `.md` file with YAML frontmatter
+- [ ] Frontmatter contains `name` (unique identifier)
+- [ ] Frontmatter contains `description` (when Claude should delegate to this agent)
+
+## Recommended
+
+- [ ] `description` is clear enough for Claude to decide when to delegate
+- [ ] `model` specified appropriately:
+  - `haiku` for fast, read-only tasks
+  - `sonnet` for balanced tasks
+  - `opus` for complex reasoning
+  - `inherit` to use parent's model
+- [ ] `tools` explicitly lists needed tools (principle of least privilege)
+- [ ] `permissionMode` set appropriately for the agent's task
+
+## Structure
+
+- [ ] File located in correct directory:
+  - `.claude/agents/` for project-level
+  - `~/.claude/agents/` for user-level
+  - `.claude/agents/{category}/` for categorized agents
+- [ ] Content includes clear system prompt
+- [ ] Content describes workflow/steps
+- [ ] Content defines execution rules
+- [ ] Content specifies output format
+
+## Tool Access
+
+- [ ] `tools` field only includes necessary tools
+- [ ] `disallowedTools` used to explicitly block dangerous tools if needed
+- [ ] MCP tools referenced correctly (mcp__{server}__{tool})
+
+## Permission Modes
+
+| Mode | Use Case | Risk |
+|------|----------|------|
+| `default` | Standard interactive work | Low |
+| `acceptEdits` | Automated file modifications | Medium |
+| `dontAsk` | Background tasks that should not prompt | Medium |
+| `bypassPermissions` | Full automation (trusted agents only) | HIGH |
+| `plan` | Read-only exploration and research | None |
+
+## Skills Preloading
+
+- [ ] `skills` field references existing skill names
+- [ ] Referenced skills are relevant to agent's purpose
+- [ ] Not overloading agent with too many preloaded skills
+
+## Hooks (if applicable)
+
+- [ ] Hook events are valid lifecycle events
+- [ ] Hook matchers use valid regex
+- [ ] Hook commands reference existing scripts
+- [ ] Hooks are scoped to agent's responsibilities
+
+## Content Quality
+
+- [ ] System prompt is actionable (not vague)
+- [ ] Workflow has numbered steps
+- [ ] Execution rules define clear constraints
+- [ ] Output format is specified
+- [ ] Agent doesn't duplicate functionality of built-in agents
+
+## Built-in Agents (do not recreate)
+
+| Agent | Purpose | Model |
+|-------|---------|-------|
+| Explore | Fast codebase search, read-only | haiku |
+| Plan | Research and design, read-only | inherit |
+| general-purpose | Complex multi-step tasks | inherit |
+| Bash | Command execution in separate context | inherit |
+
+## Frontmatter Fields Reference
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | YES | - | Unique agent identifier |
+| `description` | string | YES | - | When to delegate to this agent |
+| `tools` | string | no | all | CSV of available tools |
+| `disallowedTools` | string | no | - | CSV of blocked tools |
+| `model` | string | no | inherit | haiku/sonnet/opus/inherit |
+| `permissionMode` | string | no | default | Permission handling mode |
+| `skills` | list | no | - | Skills to preload |
+| `hooks` | object | no | - | Agent-scoped lifecycle hooks |
+| `color` | string | no | - | Visual indicator color |

package/templates/skills/cc-audit/references/hook-checklist.md

@@ -0,0 +1,110 @@
+# Hook Validation Checklist
+
+Based on official Claude Code documentation: https://code.claude.com/docs/en/hooks
+
+## Required
+
+- [ ] Hook configuration is valid JSON
+- [ ] Event name is a valid lifecycle event
+- [ ] At least one hook handler defined per event entry
+
+## Valid Lifecycle Events
+
+| Event | When it fires | Matcher target |
+|-------|---------------|----------------|
+| `SessionStart` | Session begins/resumes | source: startup, resume, clear, compact |
+| `UserPromptSubmit` | Before Claude processes prompt | - |
+| `PreToolUse` | Before tool call | tool name |
+| `PermissionRequest` | Permission dialog appears | tool name |
+| `PostToolUse` | After successful tool call | tool name |
+| `PostToolUseFailure` | After tool failure | tool name |
+| `Notification` | Claude sends notification | type: permission_prompt, idle_prompt |
+| `SubagentStart` | Subagent spawned | agent type name |
+| `SubagentStop` | Subagent finishes | agent type name |
+| `Stop` | Main agent finishes | - |
+| `PreCompact` | Before context compaction | - |
+| `SessionEnd` | Session ends | - |
+
+## Hook Handler Validation
+
+### Command type (`type: "command"`)
+- [ ] `command` field is non-empty
+- [ ] Referenced script/binary exists on filesystem
+- [ ] Script is executable (Unix: chmod +x)
+- [ ] Script handles JSON stdin correctly
+- [ ] Exit codes are meaningful (0=continue, 2=block)
+- [ ] `timeout` set if script might hang (default: varies)
+
+### Prompt type (`type: "prompt"`)
+- [ ] `prompt` field is non-empty and descriptive
+- [ ] `model` is valid if specified (haiku recommended for speed)
+- [ ] `timeout` set appropriately
+
+### Agent type (`type: "agent"`)
+- [ ] Agent configuration is valid
+- [ ] Tools specified for the agent hook
+- [ ] Timeout set to prevent runaway agents
+
+## Matcher Validation
+
+- [ ] Matcher is a valid regex pattern
+- [ ] Matcher is specific enough (avoid `.*` unless intentional)
+- [ ] For tool events: matches known tool names
+- [ ] For SessionStart: matches valid sources
+- [ ] For Notification: matches valid types
+- [ ] For Subagent events: matches valid agent types
+
+## Configuration Locations
+
+| Location | Scope | Priority |
+|----------|-------|----------|
+| `~/.claude/settings.json` | User (all projects) | Low |
+| `.claude/settings.json` | Project (shared) | Medium |
+| `.claude/settings.local.json` | Personal (gitignored) | High |
+| Skill frontmatter `hooks:` | Skill-scoped | Skill only |
+| Agent frontmatter `hooks:` | Agent-scoped | Agent only |
+
+## JSON Input Format (stdin to command hooks)
+
+```json
+{
+  "session_id": "string",
+  "transcript_path": "string",
+  "cwd": "string",
+  "permission_mode": "string",
+  "hook_event_name": "string",
+  "tool_name": "string (for tool events)",
+  "tool_input": { "object (for tool events)" }
+}
+```
+
+## JSON Output Format (stdout from command hooks)
+
+```json
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow|deny|block",
+    "permissionDecisionReason": "string"
+  }
+}
+```
+
+## Exit Code Meanings
+
+| Code | Meaning | Behavior |
+|------|---------|----------|
+| 0 | Success | Continue execution |
+| 2 | Blocking error | Prevent action, show error |
+| Other | Non-blocking error | Log warning, continue |
+
+## Best Practices
+
+- [ ] Hooks are fast (< 5 seconds for sync hooks)
+- [ ] Use `async: true` for long-running operations
+- [ ] Use `once: true` for one-time setup hooks
+- [ ] Use `statusMessage` for user visibility
+- [ ] Quote all shell variables in scripts
+- [ ] Use absolute paths or `$CLAUDE_PROJECT_DIR`
+- [ ] Test hooks manually before deploying

package/templates/skills/cc-audit/references/skill-checklist.md

@@ -0,0 +1,70 @@
+# Skill Validation Checklist
+
+Based on official Claude Code documentation: https://code.claude.com/docs/en/skills
+
+## Required
+
+- [ ] `SKILL.md` exists in skill directory
+- [ ] Frontmatter contains `name` (lowercase, max 64 chars)
+- [ ] Frontmatter contains `description` (non-empty, describes when to use)
+
+## Recommended
+
+- [ ] `description` uses natural language keywords for auto-detection
+- [ ] `argument-hint` present if skill accepts arguments
+- [ ] `disable-model-invocation: true` set for side-effect operations (deploy, commit, publish)
+- [ ] `user-invocable` explicitly set (true for /commands, false for background knowledge)
+- [ ] `allowed-tools` specified if skill needs tool access without permission prompts
+- [ ] `model` specified if skill needs a specific model (haiku for speed, opus for quality)
+
+## Structure
+
+- [ ] SKILL.md is under 500 lines
+- [ ] Supporting files in appropriate directories:
+  - `templates/` for code templates
+  - `references/` for documentation
+  - `scripts/` for executable scripts
+  - `examples/` for example outputs
+  - `steps/` for progressive step loading
+
+## Progressive Step Loading (if applicable)
+
+- [ ] `<entry_point>` section in SKILL.md points to first step
+- [ ] `<step_files>` section lists all steps with purpose
+- [ ] Each step file has YAML frontmatter with `name` and `description`
+- [ ] Each step (except last) has `next_step` in frontmatter
+- [ ] All `next_step` paths resolve to existing files
+- [ ] Steps follow sequential naming: step-00-*, step-01-*, ...
+- [ ] Each step has sections: YOUR TASK, EXECUTION SEQUENCE, SUCCESS METRICS, NEXT STEP
+- [ ] State variables documented in `<state_variables>` section
+
+## Forked Context (if applicable)
+
+- [ ] `context: fork` set in frontmatter
+- [ ] `agent` field specifies valid agent (Explore, Plan, general-purpose, or custom)
+- [ ] `allowed-tools` lists tools the forked context can use
+- [ ] Custom agent exists if referenced
+
+## Content Quality
+
+- [ ] Has `<objective>` section explaining what the skill does
+- [ ] Has `<quick_start>` with usage examples
+- [ ] Has `<workflow>` describing high-level flow
+- [ ] Has `<execution_rules>` with key constraints
+- [ ] Has `<success_criteria>` defining completion
+- [ ] All file references in content point to existing files
+
+## Frontmatter Fields Reference
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | YES | - | Lowercase identifier, max 64 chars |
+| `description` | string | YES | - | When/why Claude should use this skill |
+| `disable-model-invocation` | bool | no | false | true = manual /command only |
+| `user-invocable` | bool | no | true | false = hidden from /menu |
+| `allowed-tools` | string | no | - | CSV of tools without permission prompts |
+| `model` | string | no | inherit | inherit/sonnet/opus/haiku |
+| `context` | string | no | - | "fork" for isolated subagent |
+| `agent` | string | no | - | Subagent type if context: fork |
+| `argument-hint` | string | no | - | Autocomplete hint text |
+| `hooks` | object | no | - | Lifecycle hooks (PreToolUse, etc.) |

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

@@ -0,0 +1,98 @@
+---
+name: step-00-init
+description: Parse scope argument, detect environment, resolve scan paths
+next_step: steps/step-01-scan.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES:
+- NEVER skip scope detection
+- ALWAYS resolve actual filesystem paths before proceeding
+- YOU ARE AN INITIALIZER, not a scanner
+
+## YOUR TASK:
+Parse the scope argument, detect the environment, and resolve which directories to scan.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Input
+
+```
+Arguments from $ARGUMENTS:
+  First word → {scope} (default: "project")
+  --fix      → {fix_mode} = true (default: false)
+  --verbose  → {verbose} = true (default: false)
+
+Valid scopes:
+  "project"   → .claude/ in current working directory
+  "global"    → ~/.claude/ (user-level)
+  "templates" → templates/ (SmartStack CLI source only)
+  "all"       → all of the above
+```
+
+### 2. Detect Environment
+
+```
+Use Bash to determine:
+  - Current working directory
+  - Home directory (for global scope)
+  - Is this a SmartStack CLI project? (check for templates/ directory)
+  - Is this a Claude Code project? (check for .claude/ directory)
+```
+
+### 3. Resolve Scan Paths
+
+```
+Based on {scope}:
+
+  "project" →
+    {scan_paths} = ["{cwd}/.claude/"]
+    Verify .claude/ exists, warn if missing
+
+  "global" →
+    {scan_paths} = ["~/.claude/"]
+    Resolve ~ to actual home directory
+
+  "templates" →
+    {scan_paths} = ["{cwd}/templates/"]
+    Only valid in SmartStack CLI project
+
+  "all" →
+    {scan_paths} = combination of applicable paths
+```
+
+### 4. Validate Paths
+
+For each path in {scan_paths}:
+- Use Bash `ls` to verify directory exists
+- If missing: record as warning, skip that path
+- If empty: record as info, skip that path
+
+### 5. Show Summary and Proceed
+
+```
+Audit Configuration:
+
+| Setting | Value |
+|---------|-------|
+| Scope | {scope} |
+| Fix mode | {fix_mode} |
+| Verbose | {verbose} |
+| Paths to scan | {scan_paths} |
+
+→ Scanning components...
+```
+
+---
+
+## SUCCESS METRICS:
+- Scope correctly parsed
+- All paths resolved and validated
+- Environment detected (SmartStack CLI vs generic Claude Code project)
+- Summary displayed
+
+## NEXT STEP:
+After showing initialization summary, proceed directly to `./step-01-scan.md`