@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/cc-skill/references/frontmatter-reference.md

@@ -1,182 +0,0 @@
-# Skill Frontmatter Reference
-
-Complete reference for all SKILL.md YAML frontmatter fields, based on the official Claude Code documentation.
-
-Source: https://code.claude.com/docs/en/skills
-
-## Required Fields
-
-### `name`
-- **Type:** string
-- **Required:** YES
-- **Constraints:** lowercase, max 64 characters, kebab-case
-- **Purpose:** Unique identifier. Becomes the `/name` command.
-- **Examples:**
-  ```yaml
-  name: my-skill
-  name: code-review
-  name: deploy-staging
-  ```
-
-### `description`
-- **Type:** string (multi-line supported)
-- **Required:** YES
-- **Purpose:** Claude uses this to decide when to auto-invoke the skill. Include trigger keywords.
-- **Examples:**
-  ```yaml
-  description: Generate API controllers following REST conventions.
-
-  description: |
-    Deploy application to staging environment.
-    Use this skill when:
-    - User mentions "deploy", "staging", "release"
-    - User wants to push changes to staging
-    - Deployment pipeline needs to be triggered
-  ```
-
-## Optional Fields
-
-### `disable-model-invocation`
-- **Type:** boolean
-- **Default:** false
-- **Purpose:** When `true`, only the user can invoke via `/name`. Claude will never auto-invoke.
-- **Use for:** Side-effect operations (deploy, commit, publish, delete)
-- **Example:**
-  ```yaml
-  disable-model-invocation: true
-  ```
-
-### `user-invocable`
-- **Type:** boolean
-- **Default:** true
-- **Purpose:** When `false`, skill is hidden from /menu. Used for background knowledge injection.
-- **Example:**
-  ```yaml
-  user-invocable: false
-  ```
-
-### `allowed-tools`
-- **Type:** string (comma-separated)
-- **Default:** (none)
-- **Purpose:** Tools the skill can use without triggering permission prompts.
-- **Valid tools:** Read, Write, Edit, Bash, Glob, Grep, Task, WebFetch, WebSearch, NotebookEdit, AskUserQuestion, TodoWrite, Skill, ToolSearch
-- **Example:**
-  ```yaml
-  allowed-tools: "Read, Grep, Glob, WebSearch, WebFetch"
-  ```
-
-### `model`
-- **Type:** string
-- **Default:** inherit
-- **Valid values:** inherit, sonnet, opus, haiku
-- **Purpose:** Override the model used when this skill runs.
-- **Guidance:**
-  - `haiku` - Fast, cheap. Simple tasks.
-  - `sonnet` - Balanced. Most tasks.
-  - `opus` - Most capable. Complex reasoning.
-  - `inherit` - Use user's configured model.
-- **Example:**
-  ```yaml
-  model: haiku
-  ```
-
-### `context`
-- **Type:** string
-- **Valid values:** fork
-- **Purpose:** Run skill in an isolated subagent context. Separate conversation, clean state.
-- **Example:**
-  ```yaml
-  context: fork
-  ```
-
-### `agent`
-- **Type:** string
-- **Purpose:** Which subagent type to use when `context: fork`.
-- **Valid values:** Explore, Plan, general-purpose, Bash, or any custom agent name
-- **Example:**
-  ```yaml
-  context: fork
-  agent: Explore
-  ```
-
-### `argument-hint`
-- **Type:** string
-- **Purpose:** Autocomplete hint shown in the /menu.
-- **Example:**
-  ```yaml
-  argument-hint: "<command> [options]"
-  argument-hint: "[filename]"
-  argument-hint: "<create|update> [name]"
-  ```
-
-### `hooks`
-- **Type:** object
-- **Purpose:** Lifecycle hooks scoped to this skill.
-- **Events:** PreToolUse, PostToolUse, Stop, SessionStart, etc.
-- **Example:**
-  ```yaml
-  hooks:
-    PreToolUse:
-      - matcher: "Bash"
-        hooks:
-          - type: command
-            command: "./scripts/validate.sh"
-  ```
-
-## Dynamic Placeholders
-
-Available in SKILL.md content (not frontmatter):
-
-| Placeholder | Description |
-|-------------|-------------|
-| `$ARGUMENTS` | All arguments passed to skill |
-| `$1`, `$2`, ... | Positional arguments |
-| `$ARGUMENTS[0]` | Same as $1 |
-| `${CLAUDE_SESSION_ID}` | Current session ID |
-| `` !`command` `` | Run shell command, inject output |
-
-## Examples
-
-### Minimal Skill
-```yaml
----
-name: hello
-description: Greet the user
----
-
-Say hello to the user: $ARGUMENTS
-```
-
-### Side-Effect Skill
-```yaml
----
-name: deploy
-description: Deploy to staging
-disable-model-invocation: true
-argument-hint: "[environment]"
----
-```
-
-### Research Skill
-```yaml
----
-name: search-code
-description: Search codebase for patterns
-context: fork
-agent: Explore
-allowed-tools: "Read, Grep, Glob"
-argument-hint: "<query>"
----
-```
-
-### Complex Workflow
-```yaml
----
-name: generate-api
-description: |
-  Generate API endpoints. Use when:
-  - Creating new API routes
-  - Adding CRUD operations
-argument-hint: "<entity> [--with-tests]"
----
-```

package/templates/skills/cc-skill/references/skill-patterns.md

@@ -1,199 +0,0 @@
-# Skill Patterns Reference
-
-Common patterns used in Claude Code skills.
-
-## Pattern 1: Subcommands
-
-Route to different behaviors based on first argument. Used by: efcore, gitflow.
-
-```yaml
----
-name: my-tool
-description: Multi-command tool
-argument-hint: "<command> [options]"
-disable-model-invocation: true
----
-
-<quick_start>
-` ` `bash
-/my-tool status
-/my-tool create
-/my-tool deploy
-` ` `
-</quick_start>
-
-<parameters>
-<subcommands>
-| Command | Description |
-|---------|-------------|
-| `status` | Show current status |
-| `create` | Create new item |
-| `deploy` | Deploy to environment |
-</subcommands>
-</parameters>
-
-<entry_point>
-**ROUTING LOGIC:**
-1. Parse command from input
-2. Route to command-specific step:
-
-| Command | Route To |
-|---------|----------|
-| `status` | `steps/status/step-00-init.md` |
-| `create` | `steps/create/step-00-init.md` |
-| `deploy` | `steps/deploy/step-00-init.md` |
-</entry_point>
-```
-
-## Pattern 2: Flags (Enable/Disable)
-
-Toggle behavior with flags. Used by: controller.
-
-```yaml
-<parameters>
-<flags>
-**Enable flags (lowercase):**
-| Short | Long | Description |
-|-------|------|-------------|
-| `-a` | `--auto` | Skip confirmations |
-| `-v` | `--verbose` | Detailed output |
-
-**Disable flags (UPPERCASE):**
-| Short | Long | Description |
-|-------|------|-------------|
-| `-A` | `--no-auto` | Disable auto mode |
-| `-V` | `--no-verbose` | Disable verbose |
-</flags>
-</parameters>
-```
-
-Parsing in step-00-init:
-```
-Enable flags (lowercase - turn ON):
-  -a or --auto    → {auto_mode} = true
-  -v or --verbose → {verbose} = true
-
-Disable flags (UPPERCASE - turn OFF):
-  -A or --no-auto    → {auto_mode} = false
-  -V or --no-verbose → {verbose} = false
-```
-
-## Pattern 3: Dynamic Context Injection
-
-Inject runtime information into skill content. Used by: efcore.
-
-```yaml
----
-name: my-skill
-description: Skill with runtime context
----
-
-## Current state (auto-injected)
-- Branch: !`git branch --show-current`
-- Files: !`ls -la src/ | head -10`
-- Version: !`node -p "require('./package.json').version"`
-```
-
-The `` !`command` `` syntax runs the command before skill content is sent to Claude.
-
-## Pattern 4: Argument Placeholders
-
-Access user arguments in skill content.
-
-```markdown
-## Task
-Process the following: $ARGUMENTS
-
-## Specific arguments
-First arg: $1
-Second arg: $2
-All args: $ARGUMENTS
-```
-
-## Pattern 5: XML-Style Sections
-
-Structure skill content with XML tags. Standard sections:
-
-| Section | Purpose | When to use |
-|---------|---------|-------------|
-| `<objective>` | One-paragraph purpose statement | Always |
-| `<quick_start>` | Usage examples | Always |
-| `<parameters>` | Flags, subcommands, parsing | When skill has args |
-| `<workflow>` | High-level numbered steps | Always |
-| `<state_variables>` | Persistent variables table | Progressive skills |
-| `<entry_point>` | First step to load | Progressive skills |
-| `<step_files>` | Step file mapping table | Progressive skills |
-| `<execution_rules>` | Key constraints | Always |
-| `<security_rules>` | Mandatory security checks | When security-critical |
-| `<success_criteria>` | Completion conditions | Always |
-
-## Pattern 6: State Variables
-
-Persist data across progressive steps.
-
-```xml
-<state_variables>
-| Variable | Type | Description |
-|----------|------|-------------|
-| `{name}` | string | Item name |
-| `{scope}` | string | Target scope |
-| `{auto_mode}` | boolean | Skip confirmations |
-| `{items}` | object[] | Collected items |
-</state_variables>
-```
-
-Variables are referenced as `{variable_name}` throughout steps and are maintained in conversation context.
-
-## Pattern 7: AskUserQuestion Integration
-
-Use AskUserQuestion for interactive choices.
-
-```yaml
-AskUserQuestion:
-  header: "Short Label"        # Max 12 chars
-  question: "Full question?"
-  options:
-    - label: "Option A (Recommended)"
-      description: "What this option does"
-    - label: "Option B"
-      description: "What this option does"
-  multiSelect: false           # true for checkboxes
-```
-
-## Pattern 8: Skill Chaining
-
-Call other skills from within a skill.
-
-```markdown
-After completing this step:
-1. Run `/other-skill arg1`
-2. Continue with next step
-```
-
-Or use the Skill tool:
-```
-Use Skill tool: skill="other-skill", args="arg1 arg2"
-```
-
-## Pattern 9: MCP Tool Integration
-
-Call MCP tools from skill steps.
-
-```markdown
-### Validate conventions
-Call `mcp__smartstack__validate_conventions` with:
-  - target: "{entity_path}"
-  - type: "controller"
-```
-
-## Pattern 10: Compact Output Tables
-
-Display results in scannable tables, not prose.
-
-```markdown
-| Property | Value |
-|----------|-------|
-| Name | {name} |
-| Status | OK |
-| Files | 3 created |
-```

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

@@ -1,119 +0,0 @@
----
-name: step-00-init
-description: Parse subcommand, skill name, scope, 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 skill name format
-- ALWAYS resolve target directory before proceeding
-- For UPDATE: verify skill exists before continuing
-
-## YOUR TASK:
-Parse input arguments, validate the skill name, and resolve the target directory.
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Parse Input
-
-```
-Arguments from $ARGUMENTS:
-  First word  → {subcommand} ("create" or "update")
-  Second word → {skill_name} (lowercase, kebab-case)
-  --scope X   → {scope} (default: "project")
-  --type X    → {skill_type} (optional, skip type selection in step-01)
-
-Valid subcommands: create, update
-Valid scopes: project, global, templates
-Valid types: simple, progressive, forked
-```
-
-If {subcommand} is missing or invalid:
-
-```yaml
-AskUserQuestion:
-  header: "Action"
-  question: "What do you want to do?"
-  options:
-    - label: "Create"
-      description: "Create a new skill from scratch"
-    - label: "Update"
-      description: "Update an existing skill"
-```
-
-### 2. Validate Skill Name
-
-If {skill_name} missing:
-
-```yaml
-AskUserQuestion:
-  header: "Name"
-  question: "What is the skill name? (lowercase, kebab-case, max 64 chars)"
-```
-
-Validation rules:
-- Lowercase only
-- Kebab-case (hyphens, no spaces or underscores)
-- Max 64 characters
-- No special characters except hyphens
-- Must not conflict with existing built-in commands (/help, /clear, /compact, etc.)
-
-### 3. Resolve Target Directory
-
-```
-Based on {scope}:
-
-  "project" →
-    {target_dir} = "{cwd}/.claude/skills/{skill_name}/"
-
-  "global" →
-    {target_dir} = "~/.claude/skills/{skill_name}/"
-    Resolve ~ to actual home directory
-
-  "templates" →
-    {target_dir} = "{cwd}/templates/skills/{skill_name}/"
-    Verify this is a SmartStack CLI project (templates/ exists)
-```
-
-### 4. Check Existing
-
-**For CREATE:**
-- Verify {target_dir} does NOT already exist
-- If exists: warn and ask to overwrite or switch to update
-
-**For UPDATE:**
-- Verify {target_dir} exists and contains SKILL.md
-- If missing: warn and ask to switch to create
-- If exists: read SKILL.md and extract current frontmatter
-
-### 5. Show Summary
-
-```
-Skill Configuration:
-
-| Setting | Value |
-|---------|-------|
-| Action | {subcommand} |
-| Name | {skill_name} |
-| Scope | {scope} |
-| Target | {target_dir} |
-| Type | {skill_type} (if pre-set) |
-
-→ Designing skill...
-```
-
----
-
-## SUCCESS METRICS:
-- Subcommand correctly identified
-- Skill name validated
-- Target directory resolved and checked
-- Summary displayed
-
-## NEXT STEP:
-After showing summary, proceed directly to `./step-01-design.md`

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

@@ -1,199 +0,0 @@
----
-name: step-01-design
-description: Choose skill type, gather frontmatter information via interactive questions
-next_step: steps/step-02-generate.md
----
-
-# Step 1: Design Skill
-
-## 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
-- Gather ALL needed information before proceeding to generation
-
-## YOUR TASK:
-Guide the user through skill design decisions. Gather all frontmatter fields and structural choices.
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Load References
-
-```
-Read: "references/frontmatter-reference.md"
-Read: "references/skill-patterns.md"
-Read: "references/best-practices.md"
-```
-
-### 2. Choose Skill Type (if not pre-set)
-
-If {skill_type} is not already set:
-
-```yaml
-AskUserQuestion:
-  header: "Type"
-  question: "What type of skill do you want to create?"
-  options:
-    - label: "Simple"
-      description: "Single SKILL.md file, no steps. Best for simple tasks or knowledge injection."
-    - label: "Progressive"
-      description: "SKILL.md + step files. Best for complex multi-phase workflows."
-    - label: "Forked"
-      description: "Runs in isolated subagent context. Best for research/exploration tasks."
-```
-
-### 3. Gather Description
-
-```yaml
-AskUserQuestion:
-  header: "Description"
-  question: "Describe what this skill does and WHEN Claude should use it. Include trigger keywords. Example: 'Generate API controllers. Use when: creating controllers, API endpoints, REST routes'"
-```
-
-Store in {description}.
-
-### 4. Gather Invocation Settings
-
-```yaml
-AskUserQuestion:
-  header: "Invocation"
-  question: "How should this skill be invoked?"
-  options:
-    - label: "Auto + Manual (Recommended)"
-      description: "Claude auto-invokes when relevant AND user can invoke with /name"
-    - label: "Manual only"
-      description: "Only user can invoke with /name. Best for side-effect operations (deploy, commit)."
-    - label: "Hidden"
-      description: "Not visible in /menu. Background knowledge only."
-```
-
-Map to:
-- Auto + Manual → {disable_model_invocation} = false, {user_invocable} = true
-- Manual only → {disable_model_invocation} = true, {user_invocable} = true
-- Hidden → {disable_model_invocation} = false, {user_invocable} = false
-
-### 5. Gather Arguments (if applicable)
-
-```yaml
-AskUserQuestion:
-  header: "Arguments"
-  question: "Does this skill accept arguments? If yes, describe the format (e.g., '<name> [--flag]'). If no, type 'none'."
-```
-
-Store in {argument_hint} (or null if "none").
-
-### 6. Gather Model Preference
-
-```yaml
-AskUserQuestion:
-  header: "Model"
-  question: "Which model should this skill use?"
-  options:
-    - label: "Inherit (Recommended)"
-      description: "Use whatever model the user has configured"
-    - label: "Haiku"
-      description: "Fast and cheap. Best for simple, repetitive tasks."
-    - label: "Sonnet"
-      description: "Balanced. Good for most tasks."
-    - label: "Opus"
-      description: "Most capable. Best for complex reasoning."
-```
-
-### 7. Gather Tools (if applicable)
-
-If {skill_type} is "forked":
-
-```yaml
-AskUserQuestion:
-  header: "Tools"
-  question: "Which tools should this skill have access to? (comma-separated)"
-  options:
-    - label: "Read-only (Recommended)"
-      description: "Read, Grep, Glob, WebSearch, WebFetch"
-    - label: "Read + Write"
-      description: "Read, Write, Edit, Grep, Glob, Bash"
-    - label: "Full access"
-      description: "All tools available"
-```
-
-Also ask for agent type:
-
-```yaml
-AskUserQuestion:
-  header: "Agent"
-  question: "Which agent type for the forked context?"
-  options:
-    - label: "Explore (Recommended)"
-      description: "Fast, read-only, optimized for searching"
-    - label: "Plan"
-      description: "Research and design, read-only"
-    - label: "general-purpose"
-      description: "Complex tasks, all tools"
-```
-
-### 8. Progressive Steps Design (if applicable)
-
-If {skill_type} is "progressive":
-
-Ask: "How many steps does this skill need? Describe each step briefly."
-
-For each step, gather:
-- Step number (00, 01, 02, ...)
-- Step name (kebab-case)
-- Step description (one line)
-
-Store in {steps}:
-```json
-[
-  {"number": "00", "name": "init", "description": "Parse arguments and initialize state"},
-  {"number": "01", "name": "analyze", "description": "Analyze the codebase"},
-  {"number": "02", "name": "generate", "description": "Generate output files"},
-  {"number": "03", "name": "validate", "description": "Validate results"}
-]
-```
-
-Also ask about state variables:
-
-Ask: "What state variables should persist across steps? (name, type, description for each)"
-
-Store in {state_vars}.
-
-### 9. Show Design Summary
-
-```
-Skill Design:
-
-| Field | Value |
-|-------|-------|
-| Name | {skill_name} |
-| Type | {skill_type} |
-| Description | {description} (truncated) |
-| Invocation | auto+manual / manual-only / hidden |
-| Arguments | {argument_hint} |
-| Model | {model} |
-| Tools | {allowed_tools} (if forked) |
-| Agent | {agent} (if forked) |
-| Steps | {step_count} (if progressive) |
-
-Step plan (if progressive):
-| # | Name | Description |
-|---|------|-------------|
-| 00 | {name} | {desc} |
-| 01 | {name} | {desc} |
-| ... | ... | ... |
-
-→ Generating skill files...
-```
-
----
-
-## SUCCESS METRICS:
-- All required fields gathered from user
-- Skill type chosen and appropriate options collected
-- Steps defined (if progressive)
-- Design summary displayed and confirmed
-
-## NEXT STEP:
-After design is confirmed, proceed directly to `./step-02-generate.md`