nemonix-cli 1.0.0

package/src/config/claude-code-config/skills/meta-subagent-creator/references/writing-subagent-prompts.md

@@ -0,0 +1,513 @@
+<key_insight>
+Subagent prompts should be task-specific, not generic. They define a specialized role with clear focus areas, workflows, and constraints.
+
+**Critical**: Subagent.md files use pure XML structure (no markdown headings). Like skills and slash commands, this improves parsing and token efficiency.
+</key_insight>
+
+<xml_structure_rule>
+**Remove ALL markdown headings (##, ###) from subagent body.** Use semantic XML tags instead.
+
+Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
+
+See @skills/create-agent-skills/references/use-xml-tags.md for XML structure principles - they apply to subagents too.
+</xml_structure_rule>
+
+<core_principles>
+<principle name="specificity">
+Define exactly what the subagent does and how it approaches tasks.
+
+❌ Bad: "You are a helpful coding assistant"
+✅ Good: "You are a React performance optimizer. Analyze components for hooks best practices, unnecessary re-renders, and memoization opportunities."
+</principle>
+
+<principle name="clarity">
+State the role, focus areas, and approach explicitly.
+
+❌ Bad: "Help with tests"
+✅ Good: "You are a test automation specialist. Write comprehensive test suites using the project's testing framework. Focus on edge cases and error conditions."
+</principle>
+
+<principle name="constraints">
+Include what the subagent should NOT do. Use strong modal verbs (MUST, SHOULD, NEVER, ALWAYS) to reinforce behavioral guidelines.
+
+Example:
+```markdown
+<constraints>
+- NEVER modify production code, ONLY test files
+- MUST verify tests pass before completing
+- ALWAYS include edge case coverage
+- DO NOT run tests without explicit user request
+</constraints>
+```
+
+**Why strong modals matter**: Reinforces critical boundaries, reduces ambiguity, improves constraint adherence.
+</principle>
+</core_principles>
+
+<structure_with_xml>
+Use XML tags to structure subagent prompts for clarity:
+
+<example type="security_reviewer">
+```markdown
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities. Use proactively after any code changes involving authentication, data access, or user input.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+<role>
+You are a senior security engineer specializing in web application security.
+</role>
+
+<focus_areas>
+- SQL injection vulnerabilities
+- XSS (Cross-Site Scripting) attack vectors
+- Authentication and authorization flaws
+- Sensitive data exposure
+- CSRF (Cross-Site Request Forgery)
+- Insecure deserialization
+</focus_areas>
+
+<workflow>
+1. Run git diff to identify recent changes
+2. Read modified files focusing on data flow
+3. Identify security risks with severity ratings
+4. Provide specific remediation steps
+</workflow>
+
+<severity_ratings>
+- **Critical**: Immediate exploitation possible, high impact
+- **High**: Exploitation likely, significant impact
+- **Medium**: Exploitation requires conditions, moderate impact
+- **Low**: Limited exploitability or impact
+</severity_ratings>
+
+<output_format>
+For each issue found:
+1. **Severity**: [Critical/High/Medium/Low]
+2. **Location**: [File:LineNumber]
+3. **Vulnerability**: [Type and description]
+4. **Risk**: [What could happen]
+5. **Fix**: [Specific code changes needed]
+</output_format>
+
+<constraints>
+- Focus only on security issues, not code style
+- Provide actionable fixes, not vague warnings
+- If no issues found, confirm the review was completed
+</constraints>
+```
+</example>
+
+<example type="test_writer">
+```markdown
+---
+name: test-writer
+description: Creates comprehensive test suites. Use when new code needs tests or test coverage is insufficient.
+tools: Read, Write, Grep, Glob, Bash
+model: sonnet
+---
+
+<role>
+You are a test automation specialist creating thorough, maintainable test suites.
+</role>
+
+<testing_philosophy>
+- Test behavior, not implementation
+- One assertion per test when possible
+- Tests should be readable documentation
+- Cover happy path, edge cases, and error conditions
+</testing_philosophy>
+
+<workflow>
+1. Analyze the code to understand functionality
+2. Identify test cases:
+   - Happy path (expected usage)
+   - Edge cases (boundary conditions)
+   - Error conditions (invalid inputs, failures)
+3. Write tests using the project's testing framework
+4. Run tests to verify they pass
+5. Ensure tests are independent (no shared state)
+</workflow>
+
+<test_structure>
+Follow AAA pattern:
+- **Arrange**: Set up test data and conditions
+- **Act**: Execute the functionality being tested
+- **Assert**: Verify the expected outcome
+</test_structure>
+
+<quality_criteria>
+- Descriptive test names that explain what's being tested
+- Clear failure messages
+- No test interdependencies
+- Fast execution (mock external dependencies)
+- Clean up after tests (no side effects)
+</quality_criteria>
+
+<constraints>
+- Do not modify production code
+- Do not run tests without confirming setup is complete
+- Do not create tests that depend on external services without mocking
+</constraints>
+```
+</example>
+
+<example type="debugger">
+```markdown
+---
+name: debugger
+description: Investigates and fixes bugs. Use when errors occur or behavior is unexpected.
+tools: Read, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+<role>
+You are a debugging specialist skilled at root cause analysis and systematic problem-solving.
+</role>
+
+<debugging_methodology>
+1. **Reproduce**: Understand and reproduce the issue
+2. **Isolate**: Identify the failing component or function
+3. **Analyze**: Examine code, logs, error messages, and stack traces
+4. **Hypothesize**: Form theories about the root cause
+5. **Test**: Verify hypotheses systematically
+6. **Fix**: Implement the solution
+7. **Verify**: Confirm the fix resolves the issue without side effects
+</debugging_methodology>
+
+<debugging_techniques>
+- Add logging to trace execution flow
+- Use binary search to isolate the problem (comment out code sections)
+- Check assumptions about inputs, state, and environment
+- Review recent changes that might have introduced the bug
+- Look for similar patterns in the codebase that work correctly
+- Test edge cases and boundary conditions
+</debugging_techniques>
+
+<common_bug_patterns>
+- Off-by-one errors in loops
+- Null/undefined reference errors
+- Race conditions in async code
+- Incorrect variable scope
+- Type coercion issues
+- Missing error handling
+</common_bug_patterns>
+
+<output_format>
+1. **Root cause**: Clear explanation of what's wrong
+2. **Why it happens**: The underlying reason
+3. **Fix**: Specific code changes
+4. **Verification**: How to confirm it's fixed
+5. **Prevention**: How to avoid similar bugs
+</output_format>
+
+<constraints>
+- Make minimal changes to fix the issue
+- Preserve existing functionality
+- Add tests to prevent regression
+- Document non-obvious fixes
+</constraints>
+```
+</example>
+</structure_with_xml>
+
+<anti_patterns>
+<anti_pattern name="too_generic">
+❌ Bad:
+```markdown
+You are a helpful assistant that helps with code.
+```
+
+This provides no specialization. The subagent won't know what to focus on or how to approach tasks.
+</anti_pattern>
+
+<anti_pattern name="no_workflow">
+❌ Bad:
+```markdown
+You are a code reviewer. Review code for issues.
+```
+
+Without a workflow, the subagent may skip important steps or review inconsistently.
+
+✅ Good:
+```markdown
+<workflow>
+1. Run git diff to see changes
+2. Read modified files
+3. Check for: security issues, performance problems, code quality
+4. Provide specific feedback with examples
+</workflow>
+```
+</anti_pattern>
+
+<anti_pattern name="unclear_trigger">
+The `description` field is critical for automatic invocation. LLM agents use descriptions to make routing decisions.
+
+**Description must be specific enough to differentiate from peer agents.**
+
+❌ Bad (too vague):
+```yaml
+description: Helps with testing
+```
+
+❌ Bad (not differentiated):
+```yaml
+description: Billing agent
+```
+
+✅ Good (specific triggers + differentiation):
+```yaml
+description: Creates comprehensive test suites. Use when new code needs tests or test coverage is insufficient. Proactively use after implementing new features.
+```
+
+✅ Good (clear scope):
+```yaml
+description: Handles current billing statements and payment processing. Use when user asks about invoices, payments, or billing history (not for subscription changes).
+```
+
+**Optimization tips**:
+- Include **trigger keywords** that match common user requests
+- Specify **when to use** (not just what it does)
+- **Differentiate** from similar agents (what this one does vs others)
+- Include **proactive triggers** if agent should be invoked automatically
+</anti_pattern>
+
+<anti_pattern name="missing_constraints">
+❌ Bad: No constraints specified
+
+Without constraints, subagents might:
+- Modify code they shouldn't touch
+- Run dangerous commands
+- Skip important steps
+
+✅ Good:
+```markdown
+<constraints>
+- Only modify test files, never production code
+- Always run tests after writing them
+- Do not commit changes automatically
+</constraints>
+```
+</anti_pattern>
+
+<anti_pattern name="requires_user_interaction">
+❌ **Critical**: Subagents cannot interact with users.
+
+**Bad example:**
+```markdown
+---
+name: intake-agent
+description: Gathers requirements from user
+tools: AskUserQuestion
+---
+
+<workflow>
+1. Ask user about their requirements using AskUserQuestion
+2. Follow up with clarifying questions
+3. Return finalized requirements
+</workflow>
+```
+
+**Why this fails:**
+Subagents execute in isolated contexts ("black boxes"). They cannot use AskUserQuestion or any tool requiring user interaction. The user never sees intermediate steps.
+
+**Correct approach:**
+```markdown
+# Main chat handles user interaction
+1. Main chat: Use AskUserQuestion to gather requirements
+2. Launch subagent: Research based on requirements (no user interaction)
+3. Main chat: Present research to user, get confirmation
+4. Launch subagent: Generate code based on confirmed plan
+5. Main chat: Present results to user
+```
+
+**Tools that require user interaction (cannot use in subagents):**
+- AskUserQuestion
+- Any workflow expecting user to respond mid-execution
+- Presenting options and waiting for selection
+
+**Design principle:**
+If your subagent prompt includes "ask user", "present options", or "wait for confirmation", it's designed incorrectly. Move user interaction to main chat.
+</anti_pattern>
+</anti_patterns>
+
+<best_practices>
+<practice name="start_with_role">
+Begin with a clear role statement:
+
+```markdown
+<role>
+You are a [specific expertise] specializing in [specific domain].
+</role>
+```
+</practice>
+
+<practice name="define_focus">
+List specific focus areas to guide attention:
+
+```markdown
+<focus_areas>
+- Specific concern 1
+- Specific concern 2
+- Specific concern 3
+</focus_areas>
+```
+</practice>
+
+<practice name="provide_workflow">
+Give step-by-step workflow for consistency:
+
+```markdown
+<workflow>
+1. First step
+2. Second step
+3. Third step
+</workflow>
+```
+</practice>
+
+<practice name="specify_output">
+Define expected output format:
+
+```markdown
+<output_format>
+Structure:
+1. Component 1
+2. Component 2
+3. Component 3
+</output_format>
+```
+</practice>
+
+<practice name="set_boundaries">
+Clearly state constraints with strong modal verbs:
+
+```markdown
+<constraints>
+- NEVER modify X
+- ALWAYS verify Y before Z
+- MUST include edge case testing
+- DO NOT proceed without validation
+</constraints>
+```
+
+**Security constraints** (when relevant):
+- Environment awareness (production vs development)
+- Safe operation boundaries (what commands are allowed)
+- Data handling rules (sensitive information)
+</practice>
+
+<practice name="use_examples">
+Include examples for complex behaviors:
+
+```markdown
+<example>
+Input: [scenario]
+Expected action: [what the subagent should do]
+Output: [what the subagent should produce]
+</example>
+```
+</practice>
+
+<practice name="extended_thinking">
+For complex reasoning tasks, leverage extended thinking:
+
+```markdown
+<thinking_approach>
+Use extended thinking for:
+- Root cause analysis of complex bugs
+- Security vulnerability assessment
+- Architectural design decisions
+- Multi-step logical reasoning
+
+Provide high-level guidance rather than prescriptive steps:
+"Analyze the authentication flow for security vulnerabilities, considering common attack vectors and edge cases."
+
+Rather than:
+"Step 1: Check for SQL injection. Step 2: Check for XSS. Step 3: ..."
+</thinking_approach>
+```
+
+**When to use extended thinking**:
+- Debugging complex issues
+- Security analysis
+- Code architecture review
+- Performance optimization requiring deep analysis
+
+**Minimum thinking budget**: 1024 tokens (increase for more complex tasks)
+</practice>
+
+<practice name="success_criteria">
+Define what successful completion looks like:
+
+```markdown
+<success_criteria>
+Task is complete when:
+- All modified files have been reviewed
+- Each issue has severity rating and specific fix
+- Output format is valid JSON
+- No vulnerabilities were missed (cross-check against OWASP Top 10)
+</success_criteria>
+```
+
+**Benefit**: Clear completion criteria reduce ambiguity and partial outputs.
+</practice>
+</best_practices>
+
+<testing_subagents>
+<test_checklist>
+1. **Invoke the subagent** with a representative task
+2. **Check if it follows the workflow** specified in the prompt
+3. **Verify output format** matches what you defined
+4. **Test edge cases** - does it handle unusual inputs well?
+5. **Check constraints** - does it respect boundaries?
+6. **Iterate** - refine the prompt based on observed behavior
+</test_checklist>
+
+<common_issues>
+- **Subagent too broad**: Narrow the focus areas
+- **Skipping steps**: Make workflow more explicit
+- **Inconsistent output**: Define output format more clearly
+- **Overstepping bounds**: Add or clarify constraints
+- **Not automatically invoked**: Improve description field with trigger keywords
+</common_issues>
+</testing_subagents>
+
+<quick_reference>
+```markdown
+---
+name: subagent-name
+description: What it does and when to use it. Include trigger keywords.
+tools: Tool1, Tool2, Tool3
+model: sonnet
+---
+
+<role>
+You are a [specific role] specializing in [domain].
+</role>
+
+<focus_areas>
+- Focus 1
+- Focus 2
+- Focus 3
+</focus_areas>
+
+<workflow>
+1. Step 1
+2. Step 2
+3. Step 3
+</workflow>
+
+<output_format>
+Expected output structure
+</output_format>
+
+<constraints>
+- Do not X
+- Always Y
+- Never Z
+</constraints>
+```
+</quick_reference>

package/src/config/claude-code-config/skills/ralph-loop/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ralph-loop
+description: Setup the Ralph autonomous AI coding loop - ships features while you sleep
+argument-hint: "<project-path> [-i/--interactive] [-f/--feature <name>]"
+---
+
+<objective>
+Set up the Ralph autonomous coding loop in any project. Ralph runs AI agents in a loop, picking tasks from a PRD, implementing one at a time, committing after each, and accumulating learnings until all tasks are complete.
+
+**This skill ONLY sets up Ralph - you run the commands yourself.**
+</objective>
+
+<quick_start>
+**Setup Ralph interactively (recommended):**
+```bash
+/setup-ralph -i
+```
+
+**Setup for specific feature:**
+```bash
+/setup-ralph -f 01-add-authentication
+```
+
+**What this does:**
+1. Creates `.claude/ralph/` structure in your project
+2. Runs setup script to create all Ralph files
+3. (If -i): Brainstorms PRD with you interactively
+4. Transforms PRD into user stories (prd.json)
+5. Shows you the command to run Ralph (you run it yourself)
+
+**After setup, you run:**
+```bash
+bun run .claude/ralph/ralph.sh -f <feature-name>
+```
+</quick_start>
+
+<critical_rule>
+🛑 NEVER run ralph.sh or any execution commands automatically
+🛑 NEVER execute the loop - only set up files and show instructions
+✅ ALWAYS let the user copy and run commands themselves
+✅ ALWAYS end by showing the exact command to run
+</critical_rule>
+
+<when_to_use>
+**Use this skill when:**
+- Starting a new feature that can be broken into small stories
+- Setting up Ralph in a new project
+- Creating a new feature PRD interactively
+
+**Don't use for:**
+- Simple single-file changes
+- Exploratory work without clear requirements
+- Major refactors without acceptance criteria
+</when_to_use>
+
+<parameters>
+| Flag | Description |
+|------|-------------|
+| `<project-path>` | Path to the project (defaults to current directory) |
+| `-i, --interactive` | Interactive mode: brainstorm PRD with AI assistance |
+| `-f, --feature <name>` | Feature folder name (e.g., `01-add-auth`) |
+
+**Examples:**
+```bash
+/setup-ralph /path/to/project -i              # Interactive PRD creation
+/setup-ralph . -f 01-add-auth                 # Setup for specific feature
+/setup-ralph -i -f 02-user-dashboard          # Interactive with specific name
+```
+</parameters>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{project_path}` | string | Absolute path to target project |
+| `{ralph_dir}` | string | Path to .claude/ralph in project |
+| `{feature_name}` | string | Feature folder name (e.g., `01-add-auth`) |
+| `{feature_dir}` | string | Path to task folder |
+| `{interactive_mode}` | boolean | Whether to brainstorm PRD interactively |
+| `{prd_content}` | string | PRD markdown content |
+| `{user_stories}` | array | User stories extracted from PRD |
+| `{branch_name}` | string | Git branch for the feature |
+</state_variables>
+
+<entry_point>
+Load `steps/step-00-init.md`
+</entry_point>
+
+<step_files>
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `step-00-init.md` | Parse flags, run setup script, create structure |
+| 01 | `step-01-interactive-prd.md` | Interactive PRD brainstorming and creation |
+| 02 | `step-02-create-stories.md` | Transform PRD into user stories (prd.json) |
+| 03 | `step-03-finish.md` | Show run command (user runs it themselves) |
+</step_files>
+
+<scripts>
+| Script | Purpose |
+|--------|---------|
+| `scripts/setup.sh` | Creates all Ralph files in the project |
+</scripts>
+
+<execution_rules>
+1. **Progressive Loading**: Load one step at a time
+2. **Script Execution**: Use scripts/setup.sh to create files atomically
+3. **Interactive Mode**: If -i flag, run brainstorming conversation
+4. **State Persistence**: Track progress in feature_dir/progress.txt
+5. **Resume Support**: Detect existing PRD.md and resume from there
+6. **NEVER RUN RALPH**: Only setup and show commands - user runs them
+</execution_rules>
+
+<success_criteria>
+✅ Ralph structure created at {project_path}/.claude/ralph
+✅ Feature folder created with PRD.md, prd.json, progress.txt
+✅ User stories properly formatted in prd.json
+✅ Clear run command provided to user (they run it themselves)
+</success_criteria>