@codeyam/codeyam-cli 0.1.0-staging.8aea589 → 0.1.0-staging.8df382d

package/codeyam-cli/templates/codeyam-sim.md

@@ -0,0 +1,222 @@
+---
+name: codeyam-sim
+autoApprove: true
+description: |
+  Use this skill to create interactive simulations of components and functions using CodeYam's analysis.
+  Use when: User asks to simulate/analyze a component, generate scenarios, see visual output with screenshots,
+  or demonstrate code behavior. This skill runs full CodeYam analysis with scenario capture and visual results.
+---
+
+# CodeYam Simulation Assistant
+
+Use this skill to help users create interactive simulations of their code using CodeYam's full analysis pipeline, including scenario generation, data capture, and screenshot visualization.
+
+## When to Use This Skill
+
+- User asks to "simulate" or "analyze" a component/function
+- User wants to see visual output with screenshots
+- User requests scenario generation
+- User wants to demonstrate code behavior interactively
+- User mentions viewing results in a browser
+- You want to show how code behaves with different data states
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam analyze`, `codeyam entities`, etc.)
+- ✅ All CodeYam skills
+- ✅ Read/Write operations for `.codeyam/ai-requests/` and `.codeyam/ai-responses/` directories
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use Read, Write, and Bash tools for CodeYam operations without asking for permission.
+
+## AI Mode: Automatic Detection
+
+CodeYam automatically detects the best AI mode based on your configuration:
+
+### Mode Detection (Automatic)
+
+CodeYam checks in this priority order:
+
+1. **Direct API Mode**: If an API key is found → uses Anthropic API directly
+   - Project: `.codeyam/secrets.json` (highest priority)
+   - Home: `~/.codeyam/secrets.json` (shared across projects)
+   - Environment variables
+2. **Claude CLI Mode**: If no API key AND `.claude` folder exists → uses Claude Code CLI
+3. **Error**: If neither is found → provides helpful error message
+
+### Claude CLI Mode (Default for Claude Code Users)
+
+- **What it is**: CodeYam calls `claude -p` (headless Claude Code) for all AI requests
+- **Authentication**: Uses your existing Claude authentication automatically
+- **When used**: Automatically when using CodeYam from Claude Code (`.claude` folder detected)
+- **How it works**:
+  1. Run `codeyam analyze --entity ComponentName 'path/to/file.tsx'`
+  2. When analyzer needs AI (key attributes, scenarios, data), it executes: `claude -p "prompt" --output-format json`
+  3. Claude CLI returns response
+  4. Analyzer continues automatically until complete
+- **User experience**: Fast, fully autonomous, zero setup, zero API keys
+
+### Direct API Mode
+
+- **What it is**: CodeYam calls Anthropic API directly for AI requests
+- **When used**: Automatically when an API key is found in:
+  - `~/.codeyam/secrets.json` (recommended - shared across projects)
+  - `.codeyam/secrets.json` (project-specific override)
+  - Environment variables
+- **Setup**: Add your API key to `~/.codeyam/secrets.json`:
+  ```json
+  {
+    "ANTHROPIC_API_KEY": "sk-ant-..."
+  }
+  ```
+- **Benefits**: Faster, can run in background without Claude Code
+
+### No Manual Mode Selection Required!
+
+**Mode is detected automatically** - you never need to specify which mode to use:
+
+- ✅ No `--claude-cli` flag needed
+- ✅ Works seamlessly in Claude Code (`.claude` folder detected)
+- ✅ API keys take precedence if configured
+- ✅ Clear error if neither mode is available
+
+## ⚠️ CRITICAL: User Interruption Protocol
+
+**If the user interrupts with "[Request interrupted by user]":**
+
+- ❌ **STOP ALL PROCESSING IMMEDIATELY** - Do not continue processing AI requests
+- ❌ Do not read any more AI request files
+- ❌ Do not write any more AI response files
+- ❌ Do not poll BashOutput anymore
+- ✅ Wait for user instructions
+- ✅ **ONLY resume processing if the user explicitly asks you to continue**
+- ✅ If resuming, check for any unprocessed requests and continue from where you stopped
+
+**Why this matters**: The user may be debugging, updating code, or needs to stop the process. Continuing to process requests after interruption can cause confusion and wastes tokens.
+
+## Workflow: Simulating a Component
+
+When a user asks to simulate a component (e.g., "simulate BranchIndicator"), **ALWAYS follow this complete workflow**:
+
+### Step 1: Search for the Entity
+
+**IMPORTANT**: Never skip this step! Even if you think you know where the entity is, always search first to get the exact entity name and file path.
+
+Use the `codeyam entities` command to find matching entities:
+
+```bash
+codeyam entities ComponentName
+```
+
+This will return all entities matching that name with their file paths.
+
+### Step 2: Handle Results
+
+**If SINGLE match found:**
+
+- Automatically proceed to Step 3 with that entity
+- No need to ask the user which one
+
+**If MULTIPLE matches found:**
+
+- Present the list to the user
+- Ask which file path they want to simulate
+- Example: "I found 3 entities named 'Button'. Which one would you like to simulate?"
+  - Button in components/ui/Button.tsx
+  - Button in legacy/Button.tsx
+  - Button in admin/Button.tsx
+
+**If NO matches found:**
+
+- Inform the user the entity wasn't found
+- Suggest they check the entity name or file path
+
+### Step 3: Run Analysis
+
+Once you have the specific entity and file path, run the analysis. CodeYam automatically detects whether to use Claude CLI or direct API mode:
+
+**ACTION 1:** Ensure the CodeYam server is running:
+
+```bash
+codeyam start
+```
+
+This will start the server if it's not already running. If it's already running, it will just confirm that.
+
+**ACTION 2:** Run the analysis in the background:
+
+```bash
+codeyam analyze --entity ComponentName 'path/to/file.tsx'
+```
+
+**Optional: Provide Business Logic Context**
+
+If you just made changes to business logic that require specific data to demonstrate, use the `--context` and `--scenario-count` flags:
+
+```bash
+codeyam analyze --entity ComponentName 'path/to/file.tsx' \
+  --context "Added warning icon that displays when status is 'deleted'. Create a scenario with status='deleted' to show the warning icon prominently" \
+  --scenario-count 3
+```
+
+**When to provide context:**
+
+- ✅ New feature that depends on specific data values (e.g., "show badge when count > 0")
+- ✅ Conditional rendering added based on data (e.g., "warning icon when status is 'deleted'")
+- ✅ Business logic changed in a way that specific data reveals the change (e.g., "empty state when array is empty")
+- ❌ Pure refactoring (extracting components, renaming, reorganizing) - no context needed
+- ❌ Style-only changes (colors, fonts, spacing) - no context needed
+- ❌ Type safety improvements - no context needed
+
+**Context format:**
+
+1. Describe what changed (the new behavior)
+2. Describe what data needs to be present/missing/specific to demonstrate it
+3. Be specific about data values that trigger the behavior
+
+**Good examples:**
+
+- "Added notification badge that appears when unreadCount > 0. Create a scenario with unreadCount=5 to show the badge"
+- "Updated empty state to show when items array is empty. Create a scenario with an empty array to demonstrate the empty state"
+- "Added warning icon for deleted files. Create a scenario with status='deleted' to show the warning icon"
+
+**Bad examples:**
+
+- ❌ "New filtering feature: when 'showErrors' prop is true, only display files with errors" (describes the logic, not what data to provide)
+- ❌ "Refactored to use union types" (no business logic change)
+- ❌ "Updated colors to match design system" (style-only)
+
+**Instructions:**
+
+1. Run the command with `run_in_background: true` and `timeout: 600000` (10 minutes)
+2. Extract the entity SHA from the `codeyam entities` output (Step 1) - it's the first column in the results
+3. Tell user: "I've started the CodeYam analysis. Depending on the complexity of the analysis it might take between 1 and 5 minutes. Then your browser will open automatically with the results."
+4. Provide the progress link: "You can watch the real-time analysis progress at: http://localhost:3111/entity/{entitySha}"
+5. **That's it! Do nothing else.** Don't poll output, don't monitor progress, don't check status.
+
+The analysis runs autonomously using `claude -p` (headless Claude Code) and opens the browser when complete.
+
+**What happens**:
+
+1. Background process analyzes the entity and generates data scenarios
+2. Background process launches the project server and captures the results
+3. Browser automatically opens with results
+
+The browser will show:
+
+- All generated scenarios
+- Screenshots for each scenario (for visual components)
+- Data structures and mock data
+- Any errors encountered
+
+## When NOT to Use This Skill
+
+- User wants to write unit/integration tests → Use **CodeYam Testing** skill instead
+- User asks for Jest mocks or test templates → Use **CodeYam Testing** skill instead
+- User wants to run `codeyam generate-data-structure` → Use **CodeYam Testing** skill instead
+
+---
+
+**Remember**: CodeYam analyzes your code to discover real data scenarios and usage patterns. The analysis runs autonomously and provides comprehensive visual documentation of component behavior.

package/codeyam-cli/templates/codeyam-test.md

@@ -0,0 +1,178 @@
+---
+name: codeyam-test
+autoApprove: true
+description: |
+  Use this skill to write comprehensive unit and integration tests using CodeYam's mock generation.
+  Use when: User asks to write tests, generate mocks, understand function dependencies, or improve test coverage.
+  This skill uses the `codeyam generate-data-structure` command to create realistic test mocks based on actual code analysis.
+---
+
+# CodeYam Testing Assistant
+
+Use this skill to help users write comprehensive unit and integration tests for their code using CodeYam's dependency analysis and mock generation.
+
+## When to Use This Skill
+
+- User asks to write unit or integration tests
+- User wants to generate Jest mocks for a function
+- User needs help understanding function dependencies for testing
+- User requests mock data for testing
+- You see an opportunity to improve test coverage
+- Testing complex functions with many dependencies
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam generate-data-structure`)
+- ✅ All CodeYam skills
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use Read, Write, and Bash tools for CodeYam operations without asking for permission.
+
+## Workflow: Writing Tests with CodeYam
+
+### Step 1: Generate Mock Template
+
+Use `codeyam generate-data-structure` to analyze the function and generate a mock template:
+
+```bash
+codeyam generate-data-structure --entity FunctionName path/to/file.ts
+```
+
+**What this does:**
+
+1. Runs partial analysis (data structure only, no scenarios)
+2. Discovers all function dependencies
+3. Generates Jest mock template with proper types
+4. Caches results for instant subsequent runs
+
+**Optional flags:**
+
+- `--json` - Output raw data structure for advanced use cases
+- `--output path/to/output.ts` - Write to file instead of stdout
+
+**Example:**
+
+```bash
+codeyam generate-data-structure --entity computeBranchEntityDiff codeyam-cli/src/webserver/app/lib/branchEntityComparison.ts
+```
+
+### Step 2: Understand the Analysis Output
+
+The mock template shows:
+
+- **Dependencies by module** - All external functions/imports
+- **Mock declarations** - `jest.mock()` calls for each module
+- **Return value templates** - Sample data for `mockReturnValue()`
+
+**With `--json` flag, you get:**
+
+```json
+{
+  "dataForMocks": {
+    "getProjectRoot()": "/project/root",
+    "getBranchDiffForProject(baseBranch, compareBranch)": [...]
+  },
+  "dependencySchemas": {
+    "module/path": {
+      "functionName": { "type": "object", "properties": {...} }
+    }
+  }
+}
+```
+
+### Step 3: Write the Test
+
+Use the generated template as a starting point:
+
+**Key principles learned from experience:**
+
+1. **Mock external dependencies only** - Let internal functions run
+2. **Use realistic mock data** - Based on CodeYam's analysis
+3. **Test behavior, not implementation** - Focus on what the function does
+4. **Consider edge cases** - Added files, deleted files, empty results, etc.
+
+**Example pattern:**
+
+```typescript
+// Mock external dependencies
+jest.mock('path/to/module', () => ({
+  externalFunction: jest.fn(),
+}));
+
+describe('FunctionName', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Setup default mocks
+  });
+
+  it('should handle normal case', () => {
+    // Arrange: Setup mocks
+    // Act: Call function
+    // Assert: Verify behavior
+  });
+
+  it('should handle edge case', () => {
+    // Test edge cases
+  });
+});
+```
+
+### Step 4: Run the Test
+
+```bash
+npx jest path/to/test.test.ts --verbose
+```
+
+### Step 5: Iterate
+
+If tests fail:
+
+1. Check mock data matches actual usage
+2. Verify mock call counts (added files call extract once, modified call twice)
+3. Ensure edge cases are handled
+4. Use `jest.clearAllMocks()` between tests for isolation
+
+## Common Testing Patterns
+
+### Integration Tests
+
+- Mock external dependencies (fs, child_process, imports)
+- Let internal logic run naturally
+- Test complete workflows
+
+### Unit Tests
+
+- Mock all dependencies
+- Test single function in isolation
+- Focus on edge cases and error handling
+
+### Cache Testing
+
+- Test both cache hit and miss scenarios
+- Verify cache writes happen correctly
+- Ensure cache reads prevent unnecessary work
+
+## Tips from Experience
+
+1. **Call counts matter** - Different file statuses call dependencies differently:
+   - Modified files: extract entities from old AND new content (2 calls)
+   - Added files: extract only from new content (1 call)
+   - Deleted files: extract only from old content (1 call)
+
+2. **Mock isolation** - Use `jest.clearAllMocks()` between tests to prevent interference
+
+3. **Realistic data** - Use CodeYam's analysis to ensure mock data matches real usage patterns
+
+4. **Test structure** - Organize by scenarios (cache hit, cache miss, edge cases)
+
+## When NOT to Use This Skill
+
+- User wants to simulate a component in the browser → Use **CodeYam Simulation** skill instead
+- User wants to see visual screenshots of scenarios → Use **CodeYam Simulation** skill instead
+- User asks to "analyze" or "simulate" an entity → Use **CodeYam Simulation** skill instead
+
+---
+
+**Remember**: This skill is for writing traditional unit/integration tests with Jest. For running CodeYam simulations with screenshots and scenarios, use the CodeYam Simulation skill.

package/codeyam-cli/templates/codeyam-verify.md

@@ -0,0 +1,179 @@
+---
+name: codeyam-verify
+autoApprove: true
+description: |
+  Use this skill after making code changes that impact application functionality.
+  Automatically run simulations to verify your changes and present results to the user.
+  Use when: You've completed making changes to visual components or library functions and are ready to present your work.
+
+  NOTE: A Stop hook is installed that will remind you to use this skill if you made changes to .ts/.tsx/.jsx/.vue files during the session.
+---
+
+# CodeYam Verify Assistant
+
+Use this skill to automatically verify code changes by running simulations and presenting results to the user.
+
+## When to Use This Skill
+
+**IMPORTANT: Use this skill automatically after making code changes that affect:**
+
+- Visual components (React components, Vue components, UI elements)
+- Library functions (exported functions, utility methods, business logic)
+- Any other code that impacts application functionality
+
+**You should invoke this skill:**
+
+- After completing a set of code changes
+- Before presenting your work to the user
+- When you want to demonstrate the impact of your changes
+
+**DO NOT use this skill for:**
+
+- Documentation-only changes
+- Type definition changes that don't affect runtime behavior
+- Configuration file updates (unless they affect component behavior)
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam verify`)
+- ✅ All CodeYam skills
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use the verify command without asking for permission.
+
+## Workflow: Verifying Your Changes
+
+When you're ready to present your changes to the user, follow this workflow:
+
+### Step 1: Run the Verify Command
+
+Execute the verify command to detect changed entities and launch the dashboard:
+
+```bash
+codeyam verify
+```
+
+**Optional: Provide Business Logic Context**
+
+If you made business logic changes that require specific data to demonstrate, use the `--context` and `--scenario-count` flags:
+
+```bash
+codeyam verify \
+  --context "Added warning icon that displays when status is 'deleted'. Create scenarios with status='deleted' to show the warning icon prominently" \
+  --scenario-count 3
+```
+
+**When to provide context:**
+
+- ✅ New feature that depends on specific data values (e.g., "show badge when count > 0")
+- ✅ Conditional rendering added based on data (e.g., "warning icon when status is 'deleted'")
+- ✅ Business logic changed in a way that specific data reveals the change (e.g., "empty state when array is empty")
+- ❌ Pure refactoring (extracting components, renaming, reorganizing) - no context needed
+- ❌ Style-only changes (colors, fonts, spacing) - no context needed
+- ❌ Type safety improvements - no context needed
+
+**Context format:**
+
+1. Describe what changed (the new behavior)
+2. Describe what data needs to be present/missing/specific to demonstrate it
+3. Be specific about data values that trigger the behavior
+
+**What this does:**
+
+1. Scans your git working directory for changed files
+2. Detects which entities (functions, components) were modified or added
+3. Filters to only visual and library entities
+4. Starts the CodeYam dashboard server (if not already running)
+5. Opens your browser to the Git verification page
+6. **If context provided**: Passes it to the analyzer to generate scenarios demonstrating the changes
+
+### Step 2: Interpret the Results
+
+The verify command will either:
+
+**If NO visual or library entities changed:**
+
+- The command exits with a message
+- No further action needed
+- Present your changes to the user normally
+
+**If entities WERE changed:**
+
+- The command lists all changed entities
+- Opens the browser to http://localhost:3111/git
+- The dashboard shows your changes with options to analyze them
+
+### Step 3: Present Results to the User
+
+After running `codeyam verify`, tell the user:
+
+**Example message:**
+
+```
+I've completed the changes and kicked off simulations for the modified components.
+
+Changed entities:
+  • Button (visual) - components/Button.tsx
+  • formatDate (library) - utils/formatters.ts
+
+You can view the results and run simulations at: http://localhost:3111/git
+
+On the Git page, you can:
+  • View all changed entities
+  • Click "Analyze All" to run simulations for all entities
+  • Click "Analyze" on individual entities to run specific simulations
+  • View real-time progress as analyses complete
+```
+
+## Complete Example
+
+**User asks:** "Can you update the Button component to support a loading state?"
+
+**Your workflow:**
+
+1. Make the code changes to the Button component
+2. BEFORE presenting to the user, invoke this skill
+3. Run `codeyam verify` with context to demonstrate the new loading state
+4. Present the changes to the user with the verification link
+
+**Your response:**
+
+```
+I've updated the Button component to support a loading state. The changes include:
+- Added a `loading` prop to the Button interface
+- Display a spinner when loading is true
+- Disable the button during loading
+
+I've kicked off simulations to verify these changes with scenarios that show the loading state:
+
+codeyam verify \
+  --context "Added loading state to Button. Create scenarios with loading=true to show the spinner and disabled state" \
+  --scenario-count 2
+
+You can view the results at: http://localhost:3111/git
+
+The simulations will show:
+- Normal button state
+- Loading button state with spinner
+```
+
+## Important Notes
+
+- **Always run verify AFTER making changes** - not before, not during
+- **The verify command only detects uncommitted changes** - changes that aren't yet committed to git
+- **If no relevant entities changed** - the command will exit quickly and you can present your work normally
+- **Simulations run in the background** - they may take 1-5 minutes to complete
+- **Multiple entities can be analyzed at once** - use the "Analyze All" button on the Git page
+
+## Integration with Your Workflow
+
+Make this automatic part of your workflow:
+
+1. User asks for code changes
+2. You make the changes
+3. **[NEW STEP]** You run `codeyam verify` to verify the changes
+4. You present the changes to the user with the verification link
+
+This ensures the user can always see simulation results for your changes, building trust and providing visual confirmation that the changes work as expected.

package/codeyam-cli/templates/hooks/staleness-check.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Staleness check hook - runs after file edits to check if related rules need review
+# Receives JSON input via stdin with tool info
+
+set -e
+
+# Read the input JSON
+INPUT=$(cat)
+
+# Extract the file path that was edited
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0  # No file path, nothing to check
+fi
+
+# Find rules that match this file path
+RULES_DIR="${CLAUDE_PROJECT_DIR}/.claude/rules"
+
+if [ ! -d "$RULES_DIR" ]; then
+  exit 0  # No rules directory
+fi
+
+# Search for rules whose paths might match the edited file
+MATCHING_RULES=""
+while IFS= read -r -d '' rule_file; do
+  # Extract paths from frontmatter
+  PATHS=$(sed -n '/^---$/,/^---$/p' "$rule_file" | grep -E "^\s*-\s*'" | sed "s/.*'\(.*\)'.*/\1/")
+
+  for pattern in $PATHS; do
+    # Simple check if the file might match the pattern
+    if [[ "$FILE_PATH" == *"${pattern%%\**}"* ]]; then
+      MATCHING_RULES="$MATCHING_RULES\n- $(basename "$rule_file")"
+      break
+    fi
+  done
+done < <(find "$RULES_DIR" -name "*.md" -print0 2>/dev/null)
+
+if [ -n "$MATCHING_RULES" ]; then
+  echo "📋 Modified file may have related rules that need review:$MATCHING_RULES"
+fi
+
+exit 0

package/codeyam-cli/templates/prompts/conversation-guidance.txt

@@ -0,0 +1,32 @@
+### What to look for
+
+Read the full transcript for these signals:
+
+**User corrections or redirections**
+- "no", "actually", "that's not right", "you need to also...", "you missed..."
+- User provides information Claude didn't know or couldn't infer from code
+- User reminds Claude of a step, pattern, or relationship
+- A correction about something other than current task requirements is ALWAYS rule-worthy
+
+**Investigation and debugging**
+- Claude tried multiple approaches, read logs, or tested hypotheses
+- Investigation revealed non-obvious behavior or root causes
+- Debugging strategies that worked (or didn't) for specific areas
+
+**Architecture not evident in code**
+- Files that must change together (templates + installation, routes + registration)
+- Complex files, data flows, pipelines, or system interactions that would benefit from an overview
+
+**Commands and workflows**
+- Specific commands or flags needed for this area
+- Order of operations that matters ("must run X before Y")
+
+**Ignore:**
+- Corrections to requirements for the current feature or bug
+- Confusion isolated to the current work session (won't recur)
+
+### Before creating a rule
+
+**Critical check:** Read the actual source files that were modified. If the code already contains comments, guard patterns, or tests that explain the insight, the code is the documentation — skip the rule unless the file is complex and you've made a mistake or the user had to interrupt and correct you.
+
+Show your thinking before proceeding with creating or updating rules.

package/codeyam-cli/templates/prompts/conversation-prompt.txt

@@ -0,0 +1,28 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+Analyze the conversation transcript for rule-worthy learnings:
+- User corrections, redirections, or information Claude didn't know
+- Investigation results and debugging knowledge
+- Architecture and relationships not obvious from code
+- Commands, workflows, and processes
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST call the rule-path API to determine the correct subdirectory:
+  curl -s 'http://localhost:3111/api/rule-path?paths=path/one&paths=path/two'
+Pass all paths from your frontmatter. The API returns the correct .claude/rules/ subdirectory. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.