@atlashub/smartstack-cli 1.36.0 → 2.0.0

package/templates/skills/cc-audit/steps/step-01-scan.md

@@ -0,0 +1,142 @@
+---
+name: step-01-scan
+description: Scan all Claude Code components in target directories
+next_step: steps/step-02-analyze.md
+---
+
+# Step 1: Scan Components
+
+## MANDATORY EXECUTION RULES:
+- Scan ALL component types (skills, agents, hooks, settings)
+- Record metadata for each component found
+- Do NOT validate yet - just inventory
+
+## YOUR TASK:
+Discover and inventory all Claude Code components in the resolved scan paths.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Scan Skills
+
+For each path in {scan_paths}:
+
+```
+Search for skills:
+  Glob: "{path}/skills/*/SKILL.md"
+
+For each SKILL.md found:
+  Read the file
+  Extract frontmatter fields:
+    - name
+    - description
+    - disable-model-invocation
+    - user-invocable
+    - allowed-tools
+    - model
+    - context
+    - agent
+    - argument-hint
+    - hooks
+
+  Check for supporting directories:
+    Glob: "{skill_dir}/steps/step-*.md" → step_count
+    Glob: "{skill_dir}/templates/*" → template_count
+    Glob: "{skill_dir}/references/*" → reference_count
+    Glob: "{skill_dir}/scripts/*" → script_count
+    Glob: "{skill_dir}/examples/*" → example_count
+
+  Record in {skills_found}:
+    {name, path, frontmatter, step_count, template_count, reference_count, script_count, example_count, line_count}
+```
+
+### 2. Scan Agents
+
+```
+Search for agents:
+  Glob: "{path}/agents/*.md"
+  Glob: "{path}/agents/**/*.md"
+
+For each agent .md found:
+  Read the file
+  Extract frontmatter fields:
+    - name
+    - description
+    - color
+    - model
+    - tools
+    - disallowedTools
+    - permissionMode
+    - skills
+    - hooks
+
+  Record in {agents_found}:
+    {name, path, frontmatter, line_count, category}
+
+  category = parent directory name if nested (e.g., "efcore", "gitflow"), else "root"
+```
+
+### 3. Scan Hooks
+
+```
+Search for hook configurations:
+  Read: "{path}/hooks/hooks.json" (if exists)
+  Read: "{path}/settings.json" → extract "hooks" section
+  Read: "{path}/settings.local.json" → extract "hooks" section (if exists)
+
+For each hook configuration found:
+  Extract events (PreToolUse, PostToolUse, Stop, etc.)
+  For each event:
+    Extract matchers and hook handlers
+    Record type (command, prompt, agent)
+    Record referenced scripts/files
+
+  Record in {hooks_found}:
+    {source_file, event, matcher, type, command_or_prompt, timeout}
+```
+
+### 4. Scan Settings
+
+```
+Read settings files:
+  "{path}/settings.json"
+  "{path}/settings.local.json"
+
+Extract:
+  - permissions (allow, deny, ask rules)
+  - MCP server config
+  - plugin config
+  - environment variables
+  - model settings
+```
+
+### 5. Display Inventory Summary
+
+```
+Component Inventory:
+
+| Type | Count | Scope |
+|------|-------|-------|
+| Skills | {skills_found.length} | {scope} |
+| Agents | {agents_found.length} | {scope} |
+| Hooks | {hooks_found.length} | {scope} |
+| Settings files | N | {scope} |
+
+Skills: {list names}
+Agents: {list names}
+Hooks: {list events}
+
+→ Analyzing components...
+```
+
+---
+
+## SUCCESS METRICS:
+- All component types scanned
+- Metadata extracted for each component
+- Counts displayed in summary table
+- No components missed
+
+## NEXT STEP:
+After showing inventory summary, proceed directly to `./step-02-analyze.md`

package/templates/skills/cc-audit/steps/step-02-analyze.md

@@ -0,0 +1,158 @@
+---
+name: step-02-analyze
+description: Validate component structure, frontmatter, and cross-references
+next_step: steps/step-03-report.md
+---
+
+# Step 2: Analyze Components
+
+## MANDATORY EXECUTION RULES:
+- Validate EVERY component found in Step 1
+- Load reference checklists from `references/` directory
+- Record all issues with severity (ERROR, WARN, INFO)
+- Check cross-references between component types
+
+## YOUR TASK:
+Validate each component against official Claude Code conventions and check cross-references.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Checklists
+
+```
+Read reference checklists:
+  Read: "references/skill-checklist.md"
+  Read: "references/agent-checklist.md"
+  Read: "references/hook-checklist.md"
+```
+
+### 2. Validate Skills
+
+For each skill in {skills_found}, check:
+
+**Frontmatter (required):**
+- `name` exists and is lowercase, max 64 chars → ERROR if missing
+- `description` exists and is non-empty → ERROR if missing
+
+**Frontmatter (recommended):**
+- `argument-hint` present if skill accepts arguments → WARN if missing
+- `disable-model-invocation` explicitly set for side-effect skills → WARN
+
+**SKILL.md quality:**
+- Line count < 500 → WARN if exceeded
+- Contains `<objective>` section → WARN if missing
+- Contains `<entry_point>` section (if has steps/) → ERROR if missing
+- Contains `<workflow>` or `<step_files>` section → INFO if missing
+
+**Step files validation (if steps/ exists):**
+- Each step file has frontmatter with `name` and `description` → ERROR if missing
+- Each step file (except last) has `next_step` in frontmatter → ERROR if missing
+- `next_step` paths resolve to existing files → ERROR if broken
+- Steps follow sequential naming (step-00, step-01, ...) → WARN if not
+- Each step has "NEXT STEP" or "SUCCESS METRICS" section → INFO if missing
+
+**File references:**
+- All files referenced in SKILL.md exist → ERROR if missing
+- Templates, references, scripts directories referenced exist → WARN if missing
+
+**Record issues in {issues}:**
+```
+{component_name, component_type: "skill", severity, message, file_path, line_number}
+```
+
+### 3. Validate Agents
+
+For each agent in {agents_found}, check:
+
+**Frontmatter (required):**
+- `name` exists → ERROR if missing
+- `description` exists and is non-empty → ERROR if missing
+
+**Frontmatter (recommended):**
+- `model` is valid (haiku, sonnet, opus, inherit) or absent → ERROR if invalid
+- `tools` references valid tool names → WARN if unrecognized tool
+- `permissionMode` is valid (default, acceptEdits, dontAsk, bypassPermissions, plan) → ERROR if invalid
+- `skills` references existing skill names → WARN if not found
+
+**Content quality:**
+- Has workflow or instructions section → INFO if very short (< 10 lines)
+- System prompt is clear and actionable → INFO
+
+**Record issues in {issues}:**
+```
+{component_name, component_type: "agent", severity, message, file_path}
+```
+
+### 4. Validate Hooks
+
+For each hook in {hooks_found}, check:
+
+**Structure:**
+- Event name is valid (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, Stop, PreCompact, SessionEnd) → ERROR if invalid
+- Hook type is valid (command, prompt, agent) → ERROR if invalid
+
+**Command hooks:**
+- Referenced script/command exists → ERROR if missing
+- Script is executable (on Unix) → WARN if not
+
+**Prompt hooks:**
+- `prompt` field is non-empty → ERROR if missing
+- `model` is valid if specified → WARN if invalid
+
+**Matcher patterns:**
+- Regex is valid → ERROR if invalid syntax
+- Pattern matches at least one known tool/event → INFO if no match
+
+### 5. Validate Cross-References
+
+```
+Check skills → agents:
+  For skills with `context: fork` and `agent: {name}`:
+    Verify agent exists in {agents_found} or is built-in (Explore, Plan, general-purpose, Bash)
+    → WARN if agent not found
+
+Check agents → skills:
+  For agents with `skills: [...]`:
+    Verify each skill exists in {skills_found}
+    → WARN if skill not found
+
+Check hooks → scripts:
+  For command hooks:
+    Verify referenced script exists on filesystem
+    → ERROR if missing
+
+Check settings → permissions:
+  For permission rules referencing tools:
+    Verify tool names are valid
+    → WARN if unrecognized
+```
+
+### 6. Display Analysis Summary
+
+```
+Analysis Complete:
+
+| Severity | Count |
+|----------|-------|
+| ERROR | {count} |
+| WARN | {count} |
+| INFO | {count} |
+
+Top issues:
+{list top 5 most critical issues}
+
+→ Generating report...
+```
+
+---
+
+## SUCCESS METRICS:
+- All components validated against checklists
+- Cross-references checked
+- All issues recorded with severity
+- Summary counts displayed
+
+## NEXT STEP:
+After showing analysis summary, proceed directly to `./step-03-report.md`

package/templates/skills/cc-audit/steps/step-03-report.md

@@ -0,0 +1,142 @@
+---
+name: step-03-report
+description: Generate comprehensive audit report with recommendations
+---
+
+# Step 3: Audit Report
+
+## MANDATORY EXECUTION RULES:
+- Display COMPLETE report (every component, every issue)
+- Group by component type, then by severity
+- Include actionable recommendations for each issue
+- If --fix mode, apply auto-fixes where safe
+
+## YOUR TASK:
+Generate and display the final audit report. Apply auto-fixes if requested.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Component Inventory Table
+
+Display full inventory:
+
+```markdown
+## Component Inventory
+
+### Skills ({count})
+| Name | Steps | Templates | Refs | Lines | Status |
+|------|-------|-----------|------|-------|--------|
+| {name} | {step_count} | {template_count} | {ref_count} | {line_count} | OK/WARN/ERROR |
+
+### Agents ({count})
+| Name | Category | Model | Tools | Status |
+|------|----------|-------|-------|--------|
+| {name} | {category} | {model} | {tool_count} | OK/WARN/ERROR |
+
+### Hooks ({count})
+| Event | Matcher | Type | Status |
+|-------|---------|------|--------|
+| {event} | {matcher} | {type} | OK/WARN/ERROR |
+```
+
+### 2. Issues Report
+
+Group by severity, then by component:
+
+```markdown
+## Issues Found
+
+### ERRORS ({count}) - Must Fix
+| Component | Type | Issue | File | Recommendation |
+|-----------|------|-------|------|----------------|
+| {name} | {type} | {message} | {file} | {recommendation} |
+
+### WARNINGS ({count}) - Should Fix
+| Component | Type | Issue | File | Recommendation |
+|-----------|------|-------|------|----------------|
+| {name} | {type} | {message} | {file} | {recommendation} |
+
+### INFO ({count}) - Nice to Have
+| Component | Type | Issue | File | Recommendation |
+|-----------|------|-------|------|----------------|
+| {name} | {type} | {message} | {file} | {recommendation} |
+```
+
+### 3. Recommendations by Issue Type
+
+Provide common fix patterns:
+
+```markdown
+## Common Fix Patterns
+
+### Missing frontmatter fields
+Add required fields to YAML frontmatter:
+- `name`: lowercase identifier, max 64 chars
+- `description`: multi-line, describe when to use
+
+### Broken step chain
+Verify `next_step` in each step file points to existing file.
+Steps should follow: step-00-init → step-01-xxx → step-02-xxx → ...
+
+### Missing agent reference
+Skills with `context: fork` need a valid `agent` field.
+Built-in agents: Explore, Plan, general-purpose, Bash
+
+### Oversized SKILL.md
+Keep SKILL.md under 500 lines. Move detailed content to:
+- references/ for documentation
+- templates/ for code templates
+- steps/ for progressive step loading
+```
+
+### 4. Auto-Fix (if --fix mode)
+
+If {fix_mode} is true, apply safe fixes:
+
+```
+Safe auto-fixes:
+  ✅ Add missing `name` field (derive from directory name)
+  ✅ Fix broken next_step paths (if obvious rename)
+  ✅ Add missing description placeholder
+  ✅ Fix invalid model values (suggest closest match)
+
+Unsafe (skip, only recommend):
+  ❌ Restructure SKILL.md sections
+  ❌ Change skill type or architecture
+  ❌ Modify hook configurations
+  ❌ Delete files
+```
+
+For each auto-fix applied:
+- Use Edit tool to modify the file
+- Record the change
+- Display what was changed
+
+### 5. Final Summary
+
+```markdown
+## Audit Summary
+
+| Metric | Value |
+|--------|-------|
+| Scope | {scope} |
+| Components scanned | {total_count} |
+| Healthy | {ok_count} |
+| With warnings | {warn_count} |
+| With errors | {error_count} |
+| Auto-fixes applied | {fix_count} (if --fix) |
+
+### Health Score: {score}%
+(100% = no errors or warnings)
+```
+
+---
+
+## SUCCESS METRICS:
+- Complete report displayed with all components
+- Every issue has an actionable recommendation
+- Auto-fixes applied if --fix mode (safe fixes only)
+- Health score calculated and displayed
+- Report is scannable (tables, not prose)

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

@@ -0,0 +1,134 @@
+---
+name: cc-skill
+description: |
+  Create or update Claude Code skills based on official documentation.
+  Use this skill when:
+  - Creating a new skill from scratch
+  - Updating an existing skill's structure or content
+  - Converting a simple skill to progressive step loading
+argument-hint: "<create|update> [name] [--scope project|global|templates]"
+disable-model-invocation: true
+---
+
+<objective>
+Create or update Claude Code skills following official conventions. Guides the user through skill design, generates properly structured files, and validates the result.
+</objective>
+
+<quick_start>
+
+```bash
+# Create a new skill
+/cc-skill create my-skill
+/cc-skill create my-skill --scope project
+/cc-skill create my-skill --scope global
+/cc-skill create my-skill --scope templates
+
+# Update an existing skill
+/cc-skill update my-skill
+/cc-skill update my-skill --scope global
+```
+
+</quick_start>
+
+<parameters>
+
+<subcommands>
+| Command | Description | Workflow |
+|---------|-------------|----------|
+| `create` | Create a new skill from scratch | init → design → generate → steps → validate |
+| `update` | Update an existing skill | init → analyze → apply → validate |
+</subcommands>
+
+<flags>
+| Flag | Description |
+|------|-------------|
+| `--scope project` | Target `.claude/skills/` (default) |
+| `--scope global` | Target `~/.claude/skills/` |
+| `--scope templates` | Target `templates/skills/` (SmartStack CLI) |
+| `--type simple` | Skip interactive type selection |
+| `--type progressive` | Skip interactive type selection |
+| `--type forked` | Skip interactive type selection |
+</flags>
+
+<examples>
+```bash
+# Create a simple skill in current project
+/cc-skill create lint-check --type simple
+
+# Create a progressive skill for SmartStack templates
+/cc-skill create my-workflow --scope templates --type progressive
+
+# Update an existing skill
+/cc-skill update gitflow
+
+# Create a forked research skill
+/cc-skill create code-search --type forked
+```
+</examples>
+
+</parameters>
+
+<workflow>
+**Create flow:**
+1. Parse subcommand, name, scope, flags
+2. Design skill (type, frontmatter, structure)
+3. Generate SKILL.md with proper sections
+4. Generate step files (if progressive)
+5. Validate structure and conventions
+
+**Update flow:**
+1. Parse subcommand, name, scope
+2. Read and analyze existing skill
+3. Apply requested changes
+4. Validate structure and conventions
+</workflow>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{subcommand}` | string | create or update |
+| `{skill_name}` | string | Skill name (lowercase, max 64 chars) |
+| `{scope}` | string | project, global, or templates |
+| `{target_dir}` | string | Resolved target directory |
+| `{skill_type}` | string | simple, progressive, or forked |
+| `{description}` | string | Skill description |
+| `{user_invocable}` | boolean | Visible in /menu |
+| `{disable_model_invocation}` | boolean | Manual only |
+| `{allowed_tools}` | string | Tools without permission |
+| `{model}` | string | Model override |
+| `{argument_hint}` | string | Autocomplete hint |
+| `{step_count}` | number | Number of steps (if progressive) |
+| `{steps}` | object[] | Step definitions (name, description) |
+</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 subcommand, name, scope, resolve target directory |
+| 01 | `steps/step-01-design.md` | Choose skill type, gather frontmatter info via questions |
+| 02 | `steps/step-02-generate.md` | Generate SKILL.md from template |
+| 03 | `steps/step-03-steps.md` | Generate step files (progressive only) |
+| 04 | `steps/step-04-validate.md` | Validate structure, display summary |
+</step_files>
+
+<execution_rules>
+- **Load one step at a time** - Progressive loading
+- **Ask before generating** - Confirm design choices with user
+- **Use templates** - Load from `templates/` directory for generation
+- **Follow official conventions** - Based on Claude Code documentation
+- **Validate at the end** - Check all generated files
+</execution_rules>
+
+<success_criteria>
+- Skill directory created with correct structure
+- SKILL.md has valid frontmatter and sections
+- Step files properly chained (if progressive)
+- All file references valid
+- Skill follows official Claude Code conventions
+</success_criteria>