@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

package/codeyam-cli/templates/codeyam:power-rules.md

@@ -0,0 +1,447 @@
+---
+name: codeyam:power-rules
+autoApprove: true
+description: |
+  Generate and maintain Claude Rules for your codebase based on thorough analysis.
+  Use when: User wants to set up power rules, document confusing areas, or ensure
+  Claude has proper context for working in the codebase.
+---
+
+# CodeYam Power Rules Assistant
+
+This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that provide context-specific guidance. The goal is robust coverage of anything confusing while avoiding documentation of things Claude can intuit.
+
+## When to Use This Skill
+
+- Initial setup: User asks to "set up power rules" 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 power rules.
+
+### 1A. Add Documentation Section to CLAUDE.md
+
+If CLAUDE.md doesn't contain a "Power Rules" or "Automated Architectural Documentation" section, add:
+
+```markdown
+## Automated Architectural Documentation (Claude Rules via CodeYam)
+
+This project uses significant documentation stored as Claude Rules (`.claude/rules`).
+It is your responsibility to add to, update, and improve this documentation.
+We focus on three categories of documentation:
+
+1. Architecture
+
+- Any time there is a specific relationship between files please capture the architecture
+- Note how the files relate, how data flows, and how changes should be approached
+
+2. Testing
+
+- For complex areas of the app where both manual and automated testing is complex track:
+  - Helpful commands used in debugging and testing
+  - Where test files are located if it is not obvious (and the command to run them if not obvious)
+
+3. FAQ
+
+- If you are ever confused about something that does not fit into the above categories document it here.
+- Anything you have to figure out or ask the user about should be captured here.
+
+During each development session modify and add appropriate rules to track anything that is at all confusing.
+Ask clarifying questions to ensure you are not documenting anything inaccurate.
+After each development session review and improve all appropriate rules to ensure they are accurate, concise, and up-to-date.
+Always focus on positive instructions explaining how it works, what to run, where to find things, etc in concise terms. Do not add warnings unless necessary.
+When adding a new rules document see `.codeyam/rules/instructions.md` for instructions on where to create the rule and the format to use.
+```
+
+### 1B. Create Instructions File
+
+Create `.codeyam/rules/instructions.md` with the content from the Instructions File section at the end of this document.
+
+### 1C. Install Pre-commit Hook
+
+Check if the project uses Husky (`.husky/` directory exists).
+
+**If using Husky**, append to `.husky/pre-commit`:
+
+```bash
+# CodeYam Power Rules Check
+if [ -f ".codeyam/bin/power-rules-hook.sh" ]; then
+  .codeyam/bin/power-rules-hook.sh
+fi
+```
+
+**If not using Husky**, create or append to `.git/hooks/pre-commit`.
+
+Ensure `.codeyam/bin/power-rules-hook.sh` exists and is executable (`chmod +x`).
+
+---
+
+## Phase 2: Deep Codebase Analysis
+
+Perform thorough analysis to identify areas that may be confusing. The goal is to find everything that might trip up someone (or Claude) working in this codebase.
+
+### 2A. Analyze Git Commit Messages for Problem Signals
+
+Look for commits indicating gotchas, workarounds, or complexity:
+
+```bash
+# Find commits with problem-indicating keywords
+git log --oneline --since="6 months ago" --grep="fix" --grep="bug" --grep="workaround" --grep="hack" --grep="revert" --grep="oops" --grep="forgot" --grep="actually" --all-match | head -30
+
+# Find commits with long messages (indicate complex changes)
+git log --since="6 months ago" --format="%h %s" | awk 'length($0) > 80' | head -20
+
+# Find reverted commits
+git log --oneline --since="6 months ago" --grep="revert" -i | head -10
+```
+
+For interesting commits, examine the full message and changes:
+
+```bash
+git show <commit-hash> --stat
+git log -1 --format="%B" <commit-hash>
+```
+
+### 2B. Identify Files with High Churn or Complexity Signals
+
+```bash
+# Files changed most frequently (last 6 months)
+git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -30
+
+# Files with many different authors (tribal knowledge risk)
+git shortlog -sn --since="6 months ago" -- . | head -20
+
+# Files frequently modified together (hidden dependencies)
+git log --since="6 months ago" --name-only --pretty=format: | awk '/^$/{if(NR>1)print "---"}; /./{print}' | head -100
+```
+
+Look for patterns where the same 2-3 files appear together repeatedly.
+
+### 2C. Scan for Developer Notes in Code
+
+```bash
+# Find TODO, FIXME, HACK, XXX, NOTE comments
+grep -rn "TODO\|FIXME\|HACK\|XXX\|NOTE:" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.rb" --include="*.go" --include="*.java" --include="*.rs" . 2>/dev/null | head -50
+
+# Find "workaround" or "hack" mentions in comments
+grep -rni "workaround\|hack\|temporary\|legacy" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -30
+```
+
+### 2D. Analyze Project Structure
+
+```bash
+# Get directory structure (2 levels deep)
+find . -type d -maxdepth 3 | grep -v node_modules | grep -v .git | grep -v dist | grep -v build | head -50
+
+# Find config files
+find . -name "*.config.*" -o -name "*.rc" -o -name ".env*" -o -name "tsconfig*" -o -name "package.json" 2>/dev/null | grep -v node_modules | head -30
+
+# Find test directories
+find . -type d -name "*test*" -o -type d -name "*spec*" -o -type d -name "__tests__" 2>/dev/null | grep -v node_modules | head -20
+```
+
+### 2E. Check for Environment and Configuration Complexity
+
+```bash
+# Find environment variable references
+grep -rn "process.env\|os.environ\|ENV\[" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | head -30
+
+# Find multiple config files that might conflict or confuse
+ls -la *.config.* .*.rc tsconfig*.json 2>/dev/null
+```
+
+### 2F. Review Existing Documentation
+
+Read these files if they exist:
+
+- `README.md`
+- `CLAUDE.md`
+- `CONTRIBUTING.md`
+- `docs/` directory
+- Any `*.md` files in the root
+
+Note what's already documented and what gaps exist.
+
+### 2G. Examine Import/Dependency Patterns
+
+```bash
+# Find files with many imports (high coupling)
+for f in $(find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" 2>/dev/null | grep -v node_modules | head -100); do
+  count=$(grep -c "^import\|^from\|require(" "$f" 2>/dev/null || echo 0)
+  if [ "$count" -gt 15 ]; then
+    echo "$count $f"
+  fi
+done | sort -rn | head -20
+
+# Find commonly imported local modules (core utilities)
+grep -rh "from '\.\|from \"\.\|require('\.\|require(\"\." --include="*.ts" --include="*.tsx" --include="*.js" . 2>/dev/null | sort | uniq -c | sort -rn | head -20
+```
+
+---
+
+## Phase 3: Cluster and Prioritize Findings
+
+After gathering signals, organize them by area/module:
+
+1. **Group findings by directory** - Which parts of the codebase have the most signals?
+2. **Identify themes**:
+   - Architecture patterns (how things connect)
+   - Testing complexity (special setup needed)
+   - Configuration/environment gotchas
+   - Historical workarounds still in place
+   - Non-obvious conventions
+
+3. **Score areas** - More signals = higher priority for documentation
+
+Create a mental map of:
+
+- Which directories/modules are most complex?
+- What relationships exist between different parts?
+- Where are the gotchas hiding?
+
+---
+
+## Phase 4: Ask Specific Questions
+
+Based on your analysis, ask the user specific questions about the actual findings. Reference the concrete evidence you found (file names, commit messages, code patterns) and ask about the substance.
+
+Always include "I'm not sure" as an easy opt-out option.
+
+### Question Format
+
+Ask about the **specific finding**, not the file generally:
+
+**For high-churn files with concerning commits:**
+
+> "ScopeDataStructure.ts has commits mentioning 'exponential blowup' and 'execution flows'. What causes this blowup? When does it happen?"
+>
+> Options: [Explain the cause] [I'm not sure]
+
+**For files frequently modified together:**
+
+> "`src/api/auth.ts` and `src/middleware/session.ts` are modified together in 12 commits. Why do these need to change together?"
+>
+> Options: [Explain the relationship] [I'm not sure]
+
+**For commits with workaround language:**
+
+> "Commit `abc123` says 'workaround for webpack issue'. What's the underlying issue and what's the workaround?"
+>
+> Options: [Explain] [I'm not sure]
+
+**For multiple config files:**
+
+> "There are 3 tsconfig files. When is each one used?"
+>
+> Options: [Explain usage] [I'm not sure]
+
+**For TODO/FIXME comments:**
+
+> "There's a FIXME in `src/parser.ts:142` about 'handle nested callbacks'. What's the issue with nested callbacks here?"
+>
+> Options: [Explain] [I'm not sure]
+
+**For test organization:**
+
+> "Tests are split between `__tests__/` folders and colocated `*.test.ts` files. When should each approach be used?"
+>
+> Options: [Explain convention] [I'm not sure]
+
+### 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", either:
+   - Read the code/commits yourself to understand, OR
+   - Skip documenting that specific detail (but still document what you do know)
+4. Move to next area after capturing answers
+
+---
+
+## Phase 5: Generate Rules
+
+For each area where you have enough information, create a rule file.
+
+### 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 be actionable**
+   - Focus on "how to" and "what to know"
+   - Avoid warnings unless truly critical
+   - 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]
+
+[Concise explanation of what this covers]
+
+### [Section as appropriate]
+
+[Specific, actionable content]
+
+**Learned:** [DATE] from [context - e.g., "analysis of git history", "discussion with user"]
+```
+
+---
+
+## 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 Power Rules for Claude Code"
+   ```
+
+---
+
+## 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
+
+---
+
+## Instructions File Content
+
+Create `.codeyam/rules/instructions.md` with this content:
+
+```markdown
+# Power Rules Guide
+
+## Creating a New Rule
+
+1. **Ask the user** what they want to document (architecture, testing pattern, or gotcha/FAQ)
+2. **Read the relevant source files** to understand the patterns
+3. **Ask clarifying questions** if anything is unclear
+4. **Determine the file location** - rules mirror the source code structure (see below)
+5. **Create the rule file** with proper YAML frontmatter and concise content
+6. **Remind the user** to commit the rule and suggest running `codeyam` to view it in the dashboard
+
+## File Locations
+
+Rules mirror the source code structure:
+
+| Source Path          | Rule Path                                 |
+| -------------------- | ----------------------------------------- |
+| `src/api/auth.ts`    | `.claude/rules/src/api/auth.md`           |
+| `src/utils/**`       | `.claude/rules/src/utils/architecture.md` |
+| Project-wide testing | `.claude/rules/testing-patterns.md`       |
+
+## YAML Frontmatter (Required)
+
+Every rule file MUST have this structure:
+
+## \`\`\`yaml
+
+paths:
+
+- 'specific/path/\*_/_.ts'
+- 'another/path/\*.tsx'
+  category: architecture | testing | faq
+  timestamp: 2026-01-27T15:30:00Z
+
+---
+
+\`\`\`
+
+### Fields
+
+| Field       | Required | Description                                          |
+| ----------- | -------- | ---------------------------------------------------- |
+| `paths`     | Yes      | Glob patterns - be specific to avoid wasting context |
+| `category`  | Yes      | `architecture`, `testing`, or `faq`                  |
+| `timestamp` | Yes      | ISO 8601 - must update when reviewing rule           |
+
+### Timestamp Enforcement
+
+The pre-commit hook blocks commits when:
+
+- You modify files matching a rule's `paths`
+- The rule's `timestamp` is older than your changes
+
+To proceed: review the rule, update timestamp, commit.
+
+## Content Guidelines
+
+### Be Specific and Actionable
+
+- Good: "Run `pnpm test:api` for API tests, `pnpm test:ui` for component tests"
+- Bad: "Make sure to run the appropriate tests"
+
+### Be Concise
+
+Every word costs context window space. Trim aggressively.
+
+### Focus on Positive Instructions
+
+- Good: "Auth tokens are stored in httpOnly cookies managed by `src/auth/cookies.ts`"
+- Bad: "WARNING: Don't store tokens in localStorage!"
+
+### Include Provenance
+
+End with: `**Learned:** YYYY-MM-DD from [context]`
+
+## Categories
+
+**architecture** - Design decisions, file relationships, data flow, "why X is done this way"
+
+**testing** - Test commands, mock patterns, fixtures, "how to test X"
+
+**faq** - Gotchas, workarounds, common questions, "if you see X, do Y"
+```

package/codeyam-cli/templates/{codeyam-setup-skill.md → codeyam:setup.md}

@@ -1,5 +1,5 @@
 ---
-name: CodeYam Setup
+name: codeyam:setup
 autoApprove: true
 description: |
   Use this skill when the user asks to "setup CodeYam" or needs to configure CodeYam for their project.
@@ -7,6 +7,7 @@ description: |
   - Configuring the dev server start command
   - Creating a sandbox to iterate on startup fixes directly
   - Writing universal mocks for dependencies that prevent startup
+  - Identifying and mocking authentication logic that could block simulations
   - Verifying with test-startup at the end
   Use when: User runs `codeyam init` and wants to complete the setup process
 ---
@@ -277,7 +278,85 @@ This verifies the mocks work correctly in the standard CodeYam flow.
 
 **ALL webapps must pass test-startup before proceeding to Step 4.**
 
-### Step 4: Success
+### Step 4: Identify and Mock Authentication Logic
+
+Even with a successful `test-startup`, authentication logic can block individual component simulations. Proactively search for and mock auth patterns.
+
+**4A. Search for common auth patterns**
+
+Look for these patterns in the codebase:
+
+```bash
+# Auth middleware
+grep -r "middleware" --include="*.ts" --include="*.tsx" | grep -i "auth\|session\|token"
+
+# Auth packages in use
+grep -r "@clerk\|next-auth\|@auth0\|lucia\|passport" package.json
+
+# Auth hooks and HOCs
+grep -rn "useAuth\|useSession\|useUser\|withAuth\|requireAuth" --include="*.ts" --include="*.tsx"
+
+# Route protection patterns
+grep -rn "getServerSideProps.*session\|loader.*auth\|redirect.*login" --include="*.ts" --include="*.tsx"
+```
+
+**4B. Common auth packages that need mocks**
+
+| Package               | Mock Location                         | Key Exports                                                  |
+| --------------------- | ------------------------------------- | ------------------------------------------------------------ |
+| `@clerk/nextjs`       | `node_modules/@clerk/nextjs.ts`       | `auth`, `currentUser`, `ClerkProvider`, `useAuth`, `useUser` |
+| `next-auth`           | `node_modules/next-auth.ts`           | `getServerSession`, `useSession`, `SessionProvider`          |
+| `@auth0/nextjs-auth0` | `node_modules/@auth0/nextjs-auth0.ts` | `getSession`, `withPageAuthRequired`                         |
+| `lucia`               | `node_modules/lucia.ts`               | `Lucia`, `validateRequest`                                   |
+
+**4C. Create auth mocks even if startup succeeded**
+
+For each auth package found, create a universal mock. Example for `@clerk/nextjs`:
+
+```typescript
+// .codeyam/universal-mocks/node_modules/@clerk/nextjs.ts
+export const auth = () => ({
+  userId: null,
+  sessionId: null,
+  getToken: async () => null,
+});
+export const currentUser = async () => null;
+export const useAuth = () => ({
+  isLoaded: true,
+  isSignedIn: false,
+  userId: null,
+});
+export const useUser = () => ({
+  isLoaded: true,
+  isSignedIn: false,
+  user: null,
+});
+export const ClerkProvider = ({ children }: any) => children;
+export const SignedIn = ({ children }: any) => null;
+export const SignedOut = ({ children }: any) => children;
+```
+
+**4D. Check for project-specific auth wrappers**
+
+Many projects wrap auth in local utilities. Search for:
+
+```bash
+grep -rn "export.*auth\|export.*session\|export.*getUser" lib/ utils/ src/lib/ src/utils/ --include="*.ts"
+```
+
+If found (e.g., `lib/auth.ts`), create a mock at `.codeyam/universal-mocks/lib/auth.ts` that returns null/unauthenticated state.
+
+**4E. Validate all auth mocks**
+
+```bash
+codeyam validate-mock .codeyam/universal-mocks/node_modules/@clerk/nextjs.ts
+codeyam validate-mock .codeyam/universal-mocks/lib/auth.ts
+# etc.
+```
+
+**Note:** The goal is to ensure all auth checks return an "unauthenticated" state so components render their logged-out or loading states during simulation.
+
+### Step 5: Success
 
 Once `test-startup` passes for ALL webapps:
 
@@ -340,14 +419,69 @@ export const supabase = {
 } as any;
 ```
 
-### Example: Node Module Mock
+### Example: Node Module Mock (@clerk/nextjs)
 
 For `@clerk/nextjs`, create `.codeyam/universal-mocks/node_modules/@clerk/nextjs.ts`:
 
 ```typescript
-export const auth = () => ({ userId: null, sessionId: null });
+export const auth = () => ({
+  userId: null,
+  sessionId: null,
+  getToken: async () => null,
+});
 export const currentUser = async () => null;
+export const useAuth = () => ({
+  isLoaded: true,
+  isSignedIn: false,
+  userId: null,
+});
+export const useUser = () => ({
+  isLoaded: true,
+  isSignedIn: false,
+  user: null,
+});
 export const ClerkProvider = ({ children }: any) => children;
+export const SignedIn = ({ children }: any) => null;
+export const SignedOut = ({ children }: any) => children;
+```
+
+### Example: Node Module Mock (next-auth)
+
+For `next-auth`, create `.codeyam/universal-mocks/node_modules/next-auth.ts`:
+
+```typescript
+export const getServerSession = async () => null;
+export const useSession = () => ({ data: null, status: 'unauthenticated' });
+export const SessionProvider = ({ children }: any) => children;
+export const signIn = async () => ({ ok: false, error: null });
+export const signOut = async () => ({ url: '/' });
+export default { getServerSession };
+```
+
+For `next-auth/react`, create `.codeyam/universal-mocks/node_modules/next-auth/react.ts`:
+
+```typescript
+export const useSession = () => ({ data: null, status: 'unauthenticated' });
+export const SessionProvider = ({ children }: any) => children;
+export const signIn = async () => ({ ok: false, error: null });
+export const signOut = async () => ({ url: '/' });
+export const getSession = async () => null;
+```
+
+### Example: Node Module Mock (lucia)
+
+For `lucia`, create `.codeyam/universal-mocks/node_modules/lucia.ts`:
+
+```typescript
+export class Lucia {
+  createSession = async () => ({ id: null });
+  validateSession = async () => ({ user: null, session: null });
+  invalidateSession = async () => {};
+  createSessionCookie = () => ({ serialize: () => '' });
+  createBlankSessionCookie = () => ({ serialize: () => '' });
+}
+
+export const validateRequest = async () => ({ user: null, session: null });
 ```
 
 ---
@@ -430,6 +564,7 @@ Setup is complete when:
 - ✅ Sandbox created and all webapps start successfully with fixes applied
 - ✅ All fixes written to `.codeyam/universal-mocks/`
 - ✅ `codeyam test-startup --webappPath <path> --debug` passes for ALL webapps
+- ✅ Authentication logic identified and mocked (even if startup succeeded)
 - ✅ User knows how to use CodeYam (analyze, test)
 
 **CRITICAL:** The startCommand must include `$PORT` in the args (e.g., `["dev", "--port", "$PORT"]`) or env (e.g., `{"PORT": "$PORT"}`). Without this, CodeYam cannot start the server on the required port for capture.

package/codeyam-cli/templates/{codeyam-sim-skill.md → codeyam:sim.md}

@@ -1,5 +1,5 @@
 ---
-name: CodeYam Simulation
+name: codeyam:sim
 autoApprove: true
 description: |
   Use this skill to create interactive simulations of components and functions using CodeYam's analysis.

package/codeyam-cli/templates/{codeyam-test-skill.md → codeyam:test.md}

@@ -1,5 +1,5 @@
 ---
-name: CodeYam Testing
+name: codeyam:test
 autoApprove: true
 description: |
   Use this skill to write comprehensive unit and integration tests using CodeYam's mock generation.

package/codeyam-cli/templates/{codeyam-verify-skill.md → codeyam:verify.md}

@@ -1,5 +1,5 @@
 ---
-name: CodeYam Verify
+name: codeyam:verify
 autoApprove: true
 description: |
   Use this skill after making code changes that impact application functionality.