@atlashub/smartstack-cli 3.39.0 → 3.40.0

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

@@ -1,199 +1,199 @@
-# 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 |
-```
+# 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 +1,119 @@
----
-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`
+---
+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`