@codeyam/codeyam-cli 0.1.0-staging.483fdc2 → 0.1.0-staging.50df560

package/codeyam-cli/templates/codeyam:memory.md

@@ -1,403 +0,0 @@
----
-name: codeyam:memory
-autoApprove: true
-description: |
-  Generate and maintain Claude Rules for your codebase based on thorough analysis.
-  Use when: User wants to set up memory, claude rules, document confusing areas,
-  or ensure Claude has proper context for working in the codebase.
----
-
-# CodeYam Memory Assistant
-
-This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that provide context-specific guidance. The goal is to **document genuinely confusing aspects** of the codebase—not things Claude can figure out by reading code.
-
-## Core Principle: Document Confusion, Not Information
-
-**Good rules** explain things that are NOT obvious from reading the code:
-
-- Historical context (why code evolved this way)
-- Hidden relationships (files that must change together)
-- Gotchas that caused bugs
-- Non-obvious conventions
-
-**Bad rules** document things Claude can easily ascertain:
-
-- What functions do (Claude can read the code)
-- Type definitions (Claude can see them)
-- Directory structure (Claude can explore it)
-- Basic patterns (Claude knows common patterns)
-
-## When to Use This Skill
-
-- Initial setup: User asks to "set up memory" or "generate claude rules"
-- Maintenance: After completing complex work where lessons should be preserved
-- Review: Periodically to ensure rules are accurate and up-to-date
-
----
-
-## Phase 1: Setup (First Run Only)
-
-Check if this is the first time running memory.
-
-### 1A. Add Documentation Section to CLAUDE.md
-
-If CLAUDE.md doesn't contain a "When Confused / With Mistakes" section, add close to the top:
-
-```markdown
-## When Confused / With Mistakes: Stop. Ask. Document.
-
-- If you are not sure about something stop and ask about it.
-- If you attempt something and it goes wrong then you are confused. Stop and ask about it.
-- If the user is unable to help. Do your best to research.
-- Then document the findings!
-
-### Documenting Confusion / Mistakes
-
-It is very important to document any confusion or mistakes you encounter in Claude Rules (`.claude/rules`).
-Please see `.codeyam/rules/instructions.md` for guidance.
-
-After making any code changes please run `codeyam memory status` and follow the instructions.
-```
-
-### 1B. Verify Instructions File
-
-Check that `.codeyam/rules/instructions.md` exists (it should be created during `codeyam init`). If missing, copy it from `codeyam-cli/templates/rules-instructions.md`.
-
-### 1C. Install Pre-commit Hook
-
-Check if the project uses Husky (`.husky/` directory exists).
-
-**If using Husky**, append to `.husky/pre-commit`:
-
-```bash
-# CodeYam Memory Up-To-Date Check
-if [ -f ".codeyam/bin/memory-hook.sh" ]; then
-  .codeyam/bin/memory-hook.sh
-fi
-```
-
-**If not using Husky**, create or append to `.git/hooks/pre-commit`.
-
-Ensure `.codeyam/bin/memory-hook.sh` exists and is executable (`chmod +x`).
-
----
-
-## Phase 2: Confusion Archaeology
-
-The goal is to find areas where developers have **struggled**—not just areas that are complex. High churn alone doesn't mean confusion; we're looking for patterns that indicate something is genuinely non-obvious.
-
-### 2A. Find Confusion Signals in Commit History
-
-**Files with rapid successive changes** (same file, multiple commits in short windows = iteration/confusion):
-
-```bash
-# Files changed 3+ times in last month (rapid iteration signal)
-git log --since="1 month ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | awk '$1 >= 3 {print}' | head -20
-```
-
-**Reverts** (definite confusion signals—someone made a change that didn't work):
-
-```bash
-git log --since="6 months ago" --oneline --grep="[Rr]evert" | head -10
-```
-
-**Correction language** (commits that fix misunderstandings):
-
-```bash
-git log --since="6 months ago" --oneline | grep -iE "(oops|forgot|actually|wrong|typo|missing|should have|meant to)" | head -15
-```
-
-**Files with multiple fix commits** (confusion hotspots):
-
-```bash
-git log --since="3 months ago" --oneline --grep="fix" -i --name-only --pretty=format: | sort | uniq -c | sort -rn | awk '$1 >= 2 {print}' | head -15
-```
-
-**Long commit messages** (someone felt the need to explain—complexity that needs documentation):
-
-```bash
-git log --since="6 months ago" --format="%h %s" | awk 'length($0) > 100' | head -15
-```
-
-### 2B. Dig Into High-Confusion Files
-
-For each file that shows confusion signals, examine its evolution:
-
-```bash
-# View the story of changes to understand what kept going wrong
-git log --since="6 months ago" --oneline -- path/to/confusing-file.ts
-
-# Read the full commit messages for context
-git log --since="6 months ago" --format="%h %s%n%b" -- path/to/confusing-file.ts | head -100
-```
-
-**As you analyze, ask:**
-
-- What was the initial implementation?
-- What kept breaking or needed fixing?
-- What was non-obvious about the fix?
-- What knowledge would have prevented the issue?
-
-### 2C. Find Hidden Dependencies
-
-**Files that always change together** (may have non-obvious relationships):
-
-```bash
-# Look for file pairs that frequently appear in the same commits
-git log --since="3 months ago" --name-only --pretty=format: | awk 'NF' | sort | uniq -c | sort -rn | head -30
-```
-
-When you see the same files appearing together repeatedly, investigate why they're coupled.
-
-### 2D. Scan for Developer Notes
-
-**TODO/FIXME/HACK comments** often mark confusion points:
-
-```bash
-grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -30
-```
-
-Focus on comments that explain **why** something is the way it is, not just **what** needs to be done.
-
-### 2E. Review Existing Documentation
-
-Read these files if they exist to understand what's already documented:
-
-- `README.md`
-- `CLAUDE.md`
-- `CONTRIBUTING.md`
-- `docs/` directory
-
-Note gaps between what's documented and the confusion signals you found.
-
----
-
-## Phase 3: Distinguish Important from Confusing
-
-Not all high-churn areas need documentation. Filter your findings:
-
-### Skip These (High Churn but NOT Confusing)
-
-- Lock files (`pnpm-lock.yaml`, `package-lock.json`)
-- Build outputs (`dist/`, `build/`)
-- Generated files (`.build-info.json`, etc.)
-- Files with mechanical changes (version bumps, auto-formatting)
-
-### Document These (High Churn AND Confusing)
-
-- Files with multiple fix commits in short windows
-- Files with reverts (someone's approach didn't work)
-- Files where commit messages explain complex reasoning
-- Files where the same area keeps breaking
-- Files that must change together but aren't obviously related
-
-### Confusion Scoring
-
-Prioritize areas with stronger confusion signals:
-
-| Signal                    | Weight | Example                           |
-| ------------------------- | ------ | --------------------------------- |
-| Reverts                   | 5      | "Revert 'Track useState sources'" |
-| Correction language       | 5      | "Oops, forgot to import..."       |
-| Follow-up fix within days | 5      | Fix commit 2 days after change    |
-| "Workaround" or "hack"    | 3      | "Workaround for webpack issue"    |
-| Long commit message       | 3      | >100 chars explaining complexity  |
-| Multiple fix commits      | 2      | 3+ fixes to same file             |
-| Numbered fix series       | 1      | "Analysis Fixes 4", "Fixes 5"     |
-
-Focus your documentation efforts on areas with the highest confusion scores.
-
----
-
-## Phase 4: Ask Evidence-Based Questions
-
-Questions must reference **specific confusion evidence** you found. Don't ask generic questions about files; ask about the specific commits, patterns, or problems you discovered.
-
-Always include "I'm not sure - please investigate" as an option so users can delegate investigation to you.
-
-### Question Examples
-
-**For rapid successive changes:**
-
-> "I found 5 commits to `ScopeDataStructure.ts` in 3 weeks, including 'Fix exponential blowup' and 'scope data structure optimization'. What kept causing issues here? What would someone need to know to avoid similar problems?"
->
-> Options: [Explain the pattern] [I'm not sure - please investigate]
-
-**For reverts:**
-
-> "Commit `a9fbd6385` reverted 'Track useState initialization sources'. Why didn't that approach work? What should be done instead?"
->
-> Options: [Explain what went wrong] [I'm not sure - please investigate]
-
-**For correction commits:**
-
-> "Commit `31e4a3842` says 'Oops, lost an import'. What import was lost and why is it easy to miss?"
->
-> Options: [Explain the gotcha] [I'm not sure - please investigate]
-
-**For files that change together:**
-
-> "I noticed `auth.ts` and `session.ts` are modified together in 8 commits. Is there an invariant that must be maintained between them? What would break if someone changed one without the other?"
->
-> Options: [Explain the relationship] [I'm not sure - please investigate]
-
-**For long explanatory commits:**
-
-> "Commit `abc123` has a detailed message about 'why we need to track execution flows separately'. What's the key insight here that should be documented?"
->
-> Options: [Summarize the insight] [I'm not sure - please investigate]
-
-### Process
-
-1. Group related questions by area/module
-2. Ask 2-3 questions at a time, wait for answers
-3. If user says "I'm not sure - please investigate":
-   - Read the relevant code, commits, and context yourself
-   - Analyze the patterns and behavior
-   - Document your findings based on what you discover
-4. Move to next area after capturing answers
-
----
-
-## Phase 5: Generate and Validate Rules
-
-For each area where you have enough information, create a rule file—but **validate it first**.
-
-### 5A. Rule Validation (Before Writing)
-
-Before generating each rule, verify it passes these tests:
-
-**1. Evidence check**: Does the rule reference actual confusion evidence from commit history?
-
-- If no evidence of confusion, reconsider whether the rule is needed
-
-**2. Code-derivable check**: Read the files the rule will cover. Could the rule's content be determined by reading those files alone?
-
-- If YES → rule probably not needed (Claude can read the code)
-- If NO (historical context, edge cases, non-obvious behavior) → rule is valuable
-
-**3. Prevention check**: Would this rule have prevented one of the confusion commits you found?
-
-- If YES → definitely document it
-- If NO → reconsider its value
-
-### Rule Quality Examples
-
-**✅ Good rule** (passes all tests):
-
-```markdown
-## Path Prefix Matching Must Check Boundaries
-
-When checking if one schema path is a prefix of another using `startsWith()`,
-you must verify the match is at a path boundary. Otherwise sibling properties
-with similar names incorrectly match.
-
-This caused a bug where `entity` matched `entityCode` (siblings, not parent-child).
-```
-
-- Evidence: Learned from actual bug (commit history evidence)
-- Not code-derivable: Code doesn't explain why boundary checking matters
-- Prevention: Would prevent future prefix-matching bugs
-
-**❌ Bad rule** (fails tests):
-
-```markdown
-## Running Tests
-
-Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
-```
-
-- No confusion evidence (no commits showing people struggled with this)
-- Code-derivable: Anyone can see `jest.config.ts` exists
-- Doesn't prevent any confusion
-
-### 5B. Rule File Guidelines
-
-1. **Location mirrors code structure**
-   - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
-   - Rule for testing patterns → `.claude/rules/testing-patterns.md`
-
-2. **Paths must be specific**
-   - Good: `paths: ['src/api/**/*.ts']`
-   - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
-
-3. **Content should explain "why" not just "what"**
-   - Focus on the reasoning, history, or gotcha
-   - Be concise - every word costs context
-
-4. **Timestamp must be current**
-   - Use ISO 8601 format: `2026-01-27T15:30:00Z`
-   - This enables the pre-commit hook enforcement
-
-### Rule Template
-
-```markdown
----
-paths:
-  - 'specific/path/**/*.ts'
-category: architecture | testing | faq
-timestamp: [CURRENT_ISO_TIMESTAMP]
----
-
-## [Clear, Descriptive Title]
-
-[What's the gotcha/insight/non-obvious thing?]
-
-### Why This Matters
-
-[What would go wrong if someone didn't know this?]
-
-### The Solution/Pattern
-
-[What should someone do differently?]
-```
-
----
-
-## Phase 6: Final Review
-
-After generating rules based on your analysis and user answers:
-
-1. **Present a summary** of all rules created
-
-2. **Ask the user:**
-
-   > "I've created rules covering [list areas]. Are there any other areas of the codebase that you know are confusing or have tribal knowledge that I might have missed?"
-
-3. **Generate any additional rules** based on their response
-
-4. **Suggest viewing rules in the dashboard:**
-
-   > "Run `codeyam` to open the dashboard and view all rules in the Rules tab."
-
-5. **Remind the user** to commit the new rules:
-   ```
-   git add .claude/rules/ .codeyam/rules/
-   git commit -m "Add rules for Claude Code (generated via /codeyam:memory)"
-   ```
-
----
-
-## Ongoing Maintenance
-
-### When Claude Should Update Rules
-
-- After fixing a bug that revealed a gotcha
-- After making an architectural decision
-- When code patterns change
-- When asking "why does this work this way?" and learning the answer
-- When receiving clarification from the user about any confusion
-
-### Pre-commit Hook Behavior
-
-The pre-commit hook **blocks commits** when:
-
-- Code files matching a rule's `paths` are modified
-- The rule's `timestamp` is older than the code changes
-
-To proceed:
-
-1. Review the flagged rule(s)
-2. Update content if needed
-3. Update the `timestamp` to current time
-4. Stage and commit

package/codeyam-cli/templates/codeyam:new-rule.md

@@ -1,52 +0,0 @@
----
-name: codeyam:new-rule
-autoApprove: true
-description: |
-  Create a new Claude Rule for documenting codebase patterns.
-  Use when: User wants to add documentation for a specific area of the codebase.
----
-
-# Create New Claude Rule
-
-## Before Creating: The Confusion Test
-
-Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code.
-
-**Ask yourself:**
-
-1. **Could Claude figure this out by reading the code?**
-   - If YES → don't create the rule
-   - If NO → proceed
-
-2. **Does this explain "why" not just "what"?**
-   - Good: Historical context, gotchas, non-obvious behavior
-   - Bad: What functions do, how files are structured
-
-3. **Would this have prevented a past mistake?**
-   - If you can point to a bug or confusion this would have prevented → create it
-   - If it's just "nice to know" → skip it
-
-## Creating the Rule
-
-Read `.codeyam/rules/instructions.md` for detailed guidance on structure and formatting.
-
-If the instructions file doesn't exist, copy it from `codeyam-cli/templates/rules-instructions.md`.
-
-### Quick Template
-
-```markdown
----
-paths:
-  - 'specific/path/**/*.ts'
-category: architecture | testing | faq
-timestamp: [CURRENT_ISO_TIMESTAMP]
----
-
-## [Clear, Descriptive Title]
-
-[What's the gotcha/insight/non-obvious thing?]
-
-### Why This Matters
-
-[What would go wrong if someone didn't know this?]
-```

package/scripts/finalize-analyzer.cjs

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Post-install script to finalize the analyzer template
- * This runs after npm install and sets up the complete analysis environment
- */
-
-const path = require('path');
-const { spawn } = require('child_process');
-
-// Get the analyzer template path relative to where this script is installed
-const packageRoot = path.join(__dirname, '..');
-const analyzerTemplatePath = path.join(packageRoot, 'analyzer-template');
-
-console.log('🚀 CodeYam CLI: Finalizing analyzer template...');
-console.log('📁 Template path:', analyzerTemplatePath);
-
-async function execAsync(command, args, workingDir) {
-  return new Promise((resolve, reject) => {
-    console.log(`Running: ${command} ${args.join(' ')}`);
-    const process = spawn(command, args, {
-      cwd: workingDir,
-      stdio: 'inherit',
-      shell: true,
-    });
-
-    process.on('close', (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
-        reject(
-          new Error(
-            `Command failed with exit code ${code}: ${command} ${args.join(' ')}`,
-          ),
-        );
-      }
-    });
-
-    process.on('error', (error) => {
-      reject(new Error(`Failed to start command: ${error.message}`));
-    });
-  });
-}
-
-async function finalizeAnalyzerTemplate() {
-  try {
-    console.log('📦 Installing analyzer dependencies...');
-    // Use --include=dev to ensure devDependencies (like @types/node) are installed
-    // even when running from a global install context
-    await execAsync('npm', ['install', '--include=dev'], analyzerTemplatePath);
-
-    console.log('🎭 Installing Playwright chromium browser...');
-    await execAsync('npx', ['playwright', 'install', 'chromium'], analyzerTemplatePath);
-
-    console.log('🔨 Building analyzer template...');
-    await execAsync('npm', ['run', 'build'], analyzerTemplatePath);
-
-    // Create finalization marker
-    const fs = require('fs');
-    const markerPath = path.join(analyzerTemplatePath, '.finalized');
-    fs.writeFileSync(markerPath, new Date().toISOString());
-
-    console.log('✅ CodeYam CLI analyzer ready!');
-    console.log('');
-    console.log('You can now use: codeyam init');
-  } catch (error) {
-    console.error('❌ Failed to finalize CodeYam CLI analyzer:');
-    console.error(error.message);
-    console.error('');
-    console.error('This means the CodeYam CLI installation is incomplete.');
-    console.error('You can try manually running:');
-    console.error(`  cd ${analyzerTemplatePath}`);
-    console.error('  npm install');
-    console.error('  npx playwright install chromium');
-    console.error('  npm run build');
-    console.error('');
-    process.exit(1);
-  }
-}
-
-finalizeAnalyzerTemplate();