nemonix-cli 1.0.0

package/src/config/claude-code-config/skills/meta-skill-workflow-creator/references/prompt-engineering.md

@@ -0,0 +1,377 @@
+# Prompt Engineering for Workflow Skills
+
+Best practices for writing effective prompts in workflow steps.
+
+---
+
+## Core Principles
+
+### 1. Be Explicit, Not Vague
+
+❌ **Bad:**
+```
+Try to find relevant files.
+Consider the patterns.
+```
+
+✅ **Good:**
+```
+Find ALL files matching: **/*auth*.ts
+Document EACH pattern with file path and line number.
+```
+
+### 2. Use Positive Framing
+
+❌ **Bad:**
+```
+Don't forget to check for errors.
+Don't skip the validation.
+```
+
+✅ **Good:**
+```
+Always check for errors before proceeding.
+Run validation after each change.
+```
+
+### 3. Define Success Criteria
+
+❌ **Bad:**
+```
+Make sure it works properly.
+```
+
+✅ **Good:**
+```
+<success_criteria>
+- Typecheck passes: `pnpm run typecheck` exits 0
+- Lint passes: `pnpm run lint` exits 0
+- Tests pass: All tests green
+- No console errors
+</success_criteria>
+```
+
+### 4. Handle Edge Cases
+
+❌ **Bad:**
+```
+Process the files.
+```
+
+✅ **Good:**
+```
+Process the files:
+- If no files found: Report "No matching files" and ask user
+- If file is empty: Skip with note
+- If file is too large (>1000 lines): Read in chunks
+- If file has errors: Log error and continue to next
+```
+
+---
+
+## XML Structure
+
+Use semantic XML tags for clear organization:
+
+```xml
+<objective>
+What this step accomplishes.
+</objective>
+
+<context>
+Background information and prerequisites.
+</context>
+
+<execution_sequence>
+Step-by-step instructions.
+</execution_sequence>
+
+<success_criteria>
+How to know if this step succeeded.
+</success_criteria>
+
+<failure_modes>
+What can go wrong and how to handle it.
+</failure_modes>
+```
+
+### Benefits of XML Tags
+- Clear section boundaries
+- Semantic meaning built-in
+- Lower token usage than markdown
+- Programmatically parseable
+- Easy to reference: "Using the rules in `<execution_sequence>`..."
+
+---
+
+## Instruction Patterns
+
+### Pattern 1: Conditional Behavior
+
+```markdown
+**If `{auto_mode}` = true:**
+→ Use recommended option automatically
+→ Skip confirmation dialogs
+→ Proceed without waiting
+
+**If `{auto_mode}` = false:**
+→ Present options to user
+→ Wait for confirmation
+→ Handle user response
+```
+
+### Pattern 2: Numbered Steps
+
+```markdown
+**1. First Action**
+- Sub-step A
+- Sub-step B
+
+**2. Second Action**
+- Sub-step A
+- Sub-step B
+
+**3. Third Action**
+- Depends on step 2 completing successfully
+```
+
+### Pattern 3: Decision Trees
+
+```markdown
+<decision_tree>
+IF condition_a:
+    → Action A
+    → Load step-X
+
+ELSE IF condition_b:
+    → Action B
+    → Load step-Y
+
+ELSE:
+    → Default action
+    → Load step-Z
+</decision_tree>
+```
+
+### Pattern 4: CRITICAL Markers
+
+Use for absolutely essential instructions:
+
+```markdown
+**CRITICAL: Never skip this step.**
+
+**CRITICAL: Use AskUserQuestion tool, NOT plain text prompts.**
+
+**CRITICAL: Launch ALL agents in a SINGLE message for parallel execution.**
+```
+
+---
+
+## Tool Usage Patterns
+
+### AskUserQuestion Pattern
+
+```markdown
+**CRITICAL: Use AskUserQuestion tool, NOT plain text 1/2/3 prompts.**
+
+Use AskUserQuestion:
+```yaml
+questions:
+  - header: "Header"
+    question: "Full question?"
+    options:
+      - label: "Option A (Recommended)"
+        description: "What this does"
+      - label: "Option B"
+        description: "What this does"
+    multiSelect: false
+```
+```
+
+### Parallel Agent Pattern
+
+```markdown
+**CRITICAL: Launch ALL agents in a SINGLE message for parallel execution.**
+
+**Agent 1:** (`explore-codebase`)
+```
+Find files related to: {task}
+Return: file paths with line numbers
+```
+
+**Agent 2:** (`explore-docs`)
+```
+Research documentation for: {task}
+Return: key findings with references
+```
+
+**Agent 3:** (`websearch`)
+```
+Search for: {task}
+Return: best practices and patterns
+```
+```
+
+### Tool Selection Pattern
+
+```markdown
+**Use the RIGHT tool:**
+
+- File search → Glob (not find)
+- Content search → Grep (not grep command)
+- Read files → Read (not cat)
+- Edit files → Edit (not sed)
+- Complex exploration → Task with explore agent
+- User input → AskUserQuestion (not plain text)
+```
+
+---
+
+## State Documentation
+
+### Available State Section
+
+```markdown
+<available_state>
+From previous step:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What to implement |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Skip confirmations |
+| `{files_found}` | List from step 1 |
+</available_state>
+```
+
+### Produces Section
+
+```markdown
+<produces>
+This step produces:
+
+| Variable | Description |
+|----------|-------------|
+| `{plan_items}` | List of implementation steps |
+| `{file_changes}` | Map of files to changes |
+</produces>
+```
+
+---
+
+## Error Handling Patterns
+
+### Graceful Failure
+
+```markdown
+<error_handling>
+**If validation fails:**
+
+1. Log the specific error
+2. Attempt auto-fix if possible
+3. If auto-fix fails:
+   - **If `{auto_mode}` = true:** Try alternative approach
+   - **If `{auto_mode}` = false:** Ask user for guidance
+4. Never proceed with failing checks
+</error_handling>
+```
+
+### Retry Pattern
+
+```markdown
+<retry_pattern>
+max_attempts = 3
+attempt = 0
+
+WHILE attempt < max_attempts:
+    attempt += 1
+
+    Try the operation
+
+    IF success:
+        → Continue
+
+    IF failure AND attempt < max_attempts:
+        → Log error
+        → Apply fix
+        → Retry
+
+    IF failure AND attempt >= max_attempts:
+        → Stop and ask user
+</retry_pattern>
+```
+
+---
+
+## Formatting Guidelines
+
+### Code Blocks
+
+Use triple backticks with language hints:
+
+```markdown
+```bash
+pnpm run typecheck
+```
+
+```typescript
+const result = await validate(input);
+```
+
+```yaml
+questions:
+  - header: "Test"
+```
+```
+
+### Tables for Structured Data
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Value 1  | Value 2  | Value 3  |
+```
+
+### Lists for Steps
+
+```markdown
+1. First step
+2. Second step
+   - Sub-step A
+   - Sub-step B
+3. Third step
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Vague instructions**
+```
+Handle the errors appropriately.
+```
+
+❌ **Missing conditions**
+```
+Ask the user what to do.  # What if auto_mode?
+```
+
+❌ **Plain text prompts**
+```
+Choose 1, 2, or 3:  # Use AskUserQuestion!
+```
+
+❌ **Sequential when parallel possible**
+```
+Launch Agent 1, wait, then launch Agent 2  # Launch together!
+```
+
+❌ **Assuming state exists**
+```
+Use {files_found} to...  # What if empty?
+```
+
+❌ **Missing next step directive**
+```
+# Step ends without saying what's next
+```

package/src/config/claude-code-config/skills/meta-skill-workflow-creator/references/state-management.md

@@ -0,0 +1,275 @@
+# State Management
+
+How to manage and persist state across workflow steps.
+
+---
+
+## Principles
+
+1. **Explicit State**: Always document what state is available
+2. **Immutable Core**: Core variables (task_id, flags) don't change
+3. **Accumulated Results**: Each step adds to results, doesn't replace
+4. **Handoff Pattern**: Each step declares what it receives and produces
+
+---
+
+## State Variable Types
+
+### 1. Core Variables (Set in init, never change)
+
+```yaml
+# Set in step-00-init, persist unchanged
+task_description: string   # What to do
+task_id: string            # Unique identifier (e.g., "01-add-auth")
+auto_mode: boolean         # Skip confirmations
+save_mode: boolean         # Save outputs to files
+output_dir: string         # Path to output folder (if save_mode)
+```
+
+### 2. Flag Variables (Set in init, can be overridden)
+
+```yaml
+# Parsed from user flags
+examine_mode: boolean      # Run optional review
+test_mode: boolean         # Run optional tests
+economy_mode: boolean      # Use simplified approach
+```
+
+### 3. Accumulated Results (Grow across steps)
+
+```yaml
+# Each step adds to these
+files_found: list          # Step 1 finds files
+patterns_identified: list  # Step 1 finds patterns
+plan_items: list           # Step 2 creates plan
+completed_tasks: list      # Step 3 tracks progress
+test_results: object       # Step 4 records results
+```
+
+### 4. Step-Local Variables (Only exist in current step)
+
+```yaml
+# Temporary, not passed to next step
+current_file: string       # File being processed
+loop_counter: integer      # Iteration tracking
+temp_results: list         # Intermediate results
+```
+
+---
+
+## Documenting State
+
+### In SKILL.md
+
+```markdown
+<state_variables>
+**Persist throughout all steps:**
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{task_description}` | string | What to implement |
+| `{task_id}` | string | Kebab-case identifier |
+| `{auto_mode}` | boolean | Skip confirmations |
+| `{save_mode}` | boolean | Save outputs |
+| `{output_dir}` | string | Output path (if save_mode) |
+</state_variables>
+```
+
+### In Each Step
+
+```markdown
+<available_state>
+From previous step:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What to implement |
+| `{task_id}` | Unique identifier |
+| `{auto_mode}` | Skip confirmations |
+| `{files_found}` | List of relevant files from step 1 |
+| `{patterns}` | Patterns identified in step 1 |
+</available_state>
+```
+
+---
+
+## State Handoff Patterns
+
+### Pattern 1: Simple Handoff
+
+Step 1 produces → Step 2 consumes:
+
+```markdown
+<!-- Step 1 output -->
+<produces>
+| Variable | Description |
+|----------|-------------|
+| `{files_found}` | Files related to task |
+| `{patterns}` | Patterns in codebase |
+</produces>
+
+<!-- Step 2 input -->
+<available_state>
+From step-01-analyze:
+
+| Variable | Description |
+|----------|-------------|
+| `{files_found}` | Files related to task |
+| `{patterns}` | Patterns in codebase |
+</available_state>
+```
+
+### Pattern 2: Accumulated State
+
+Each step adds to growing state:
+
+```markdown
+<!-- Step 1 -->
+Adds: {files_found}, {patterns}
+
+<!-- Step 2 -->
+Receives: {files_found}, {patterns}
+Adds: {plan_items}
+
+<!-- Step 3 -->
+Receives: {files_found}, {patterns}, {plan_items}
+Adds: {completed_tasks}
+
+<!-- Step 4 -->
+Receives: ALL of the above
+Adds: {validation_results}
+```
+
+### Pattern 3: Conditional State
+
+State that only exists if certain flags are set:
+
+```markdown
+<available_state>
+From previous step:
+
+**Always present:**
+| `{task_description}` | What to implement |
+| `{task_id}` | Unique identifier |
+
+**If `{save_mode}` = true:**
+| `{output_dir}` | Path to output folder |
+
+**If `{test_mode}` = true:**
+| `{test_results}` | Results from test runs |
+</available_state>
+```
+
+---
+
+## Persisting State to Files
+
+When `save_mode` is true, persist state to files:
+
+### 00-context.md Structure
+
+```markdown
+# Task: {task_id}
+
+**Created:** {timestamp}
+**Task:** {task_description}
+
+## Configuration
+| Flag | Value |
+|------|-------|
+| auto_mode | {value} |
+| save_mode | {value} |
+| test_mode | {value} |
+
+## Progress
+| Step | Status | Timestamp |
+|------|--------|-----------|
+| 00-init | ✓ | {timestamp} |
+| 01-analyze | ✓ | {timestamp} |
+| 02-plan | ⏳ | {timestamp} |
+
+## Accumulated State
+```yaml
+files_found:
+  - src/auth/login.ts
+  - src/api/auth/route.ts
+
+patterns:
+  - name: "Route pattern"
+    example: "src/api/users/route.ts"
+```
+```
+
+### Reading State for Resume
+
+```markdown
+<check_resume>
+**If resuming:**
+
+1. Read `00-context.md`
+2. Parse configuration section → restore flags
+3. Parse progress table → find last completed step
+4. Parse accumulated state → restore variables
+5. Load next incomplete step
+</check_resume>
+```
+
+---
+
+## State Validation
+
+Before using state, validate it exists:
+
+```markdown
+**Validate required state:**
+
+IF {files_found} is empty:
+    → Error: "Step 1 did not find any files. Cannot proceed."
+    → Offer to re-run step 1
+
+IF {plan_items} is empty:
+    → Error: "No plan created. Cannot execute."
+    → Return to step 2
+```
+
+---
+
+## Anti-Patterns
+
+❌ **Assuming state exists without checking**
+```
+# Bad: Will fail if files_found is undefined
+For each file in {files_found}...
+```
+
+✅ **Always validate**
+```
+IF {files_found} exists AND length > 0:
+    For each file in {files_found}...
+ELSE:
+    Handle missing state
+```
+
+❌ **Overwriting accumulated state**
+```
+# Bad: Loses previous step's results
+{results} = step_3_results
+```
+
+✅ **Append to accumulated state**
+```
+# Good: Preserves previous results
+{results}.step_3 = step_3_results
+```
+
+❌ **Hardcoding paths**
+```
+# Bad: Won't work in different projects
+output_dir = "/Users/me/.claude/output/"
+```
+
+✅ **Use variables**
+```
+# Good: Works anywhere
+output_dir = {project_root}/.claude/output/{workflow}/{task_id}/
+```