start-vibing 1.1.3 → 1.1.4

package/template/.claude/skills/codebase-knowledge/domains/claude-system.md

@@ -2,16 +2,17 @@
 
 ## Last Update
 
-- **Date:** 2025-12-24
-- **Session:** Clean template - removed project-specific content
+- **Date:** 2024-12-19
+- **Commit:** pending
+- **Session:** Fixed all skills to use YAML frontmatter format
 
 ## Files
 
 ### Agents
 
 - `.claude/agents/analyzer.md` - Analyzes change impact, approves files
-- `.claude/agents/research.md` - Researches best practices before implementation
-- `.claude/agents/commit-manager.md` - Manages git commits
+- `.claude/agents/research.md` - **NEW** Researches best practices (2024-2025) before implementation
+- `.claude/agents/commit-manager.md` - Manages git commits, runs complete-task
 - `.claude/agents/documenter.md` - Creates/updates documentation
 - `.claude/agents/domain-updater.md` - Updates domain knowledge after sessions
 - `.claude/agents/final-validator.md` - Final validation with VETO power
@@ -21,34 +22,239 @@
 - `.claude/agents/tester.md` - Creates unit and E2E tests
 - `.claude/agents/ui-ux-reviewer.md` - Reviews UI/UX patterns
 
+### Hooks
+
+- `.claude/hooks/user-prompt-submit.py` - Agent selection guidance before prompt processing
+
 ### Skills
 
 - `.claude/skills/codebase-knowledge/` - Domain mapping system
-- `.claude/skills/research-cache/` - Best practices research cache
+- `.claude/skills/research-cache/` - **NEW** Best practices research cache
 - `.claude/skills/docs-tracker/` - Documentation tracking
 - `.claude/skills/final-check/` - Final validation rules
 - `.claude/skills/quality-gate/` - Quality gate definitions
 - `.claude/skills/security-scan/` - Security audit rules
 - `.claude/skills/test-coverage/` - Test coverage tracking
 - `.claude/skills/ui-ux-audit/` - UI/UX audit rules
-- `.claude/skills/workflow-state/` - Task state tracking
 
 ### Configuration
 
+- `.claude/settings.json` - Agent registration, flows, rules
+- `.claude/workflow-state.json` - Current task state
+- `.claude/CLAUDE.md` - System documentation
+
+### Config Files (NEW - 2024-12-19)
+
 - `.claude/config/project-config.json` - Stack, structure, commands
 - `.claude/config/domain-mapping.json` - File patterns to domains
 - `.claude/config/quality-gates.json` - Quality check commands
 - `.claude/config/testing-config.json` - Test framework config
 - `.claude/config/security-rules.json` - Security audit rules
+- `.claude/config/README.md` - Config documentation
+
+### Root Files
+
+- `CLAUDE.md` - Development rules (115 lines, generalist)
+- `PROJECT.md` - Project-specific details (Solana Listeners)
 
 ## Connections
 
 - **All domains:** domain-updater reads/updates domain files after sessions
 - **Infrastructure:** Hooks enforce workflow rules project-wide
 
+## Recent Commits
+
+| Hash | Date | Description |
+| ---- | ---- | ----------- |
+| de8cda9 | 2024-12-18 | feat(hooks): add domain-updater agent and enhance Task tool guidance |
+| e9b4ad3 | 2024-12-18 | fix(claude-system): move complete-task from commit-manager to domain-updater |
+| 251dfad | 2024-12-18 | feat(claude-system): add domain-updater agent as final workflow step |
+
+## Problems & Solutions
+
+### 2024-12-19 - Workflow Manager Removed
+
+**Problem:**
+The workflow-manager.py script and enforcement hooks (pre-tool-use.py, post-tool-use.py, stop-validation.py) were blocking operations and adding unnecessary complexity.
+
+**Root Cause:**
+The system was designed with strict workflow enforcement that prevented Claude from working flexibly.
+
+**Solution:**
+- Deleted workflow-manager.py, pre-tool-use.py, post-tool-use.py, stop-validation.py
+- Removed references from all documentation
+- Simplified settings.local.json to only keep UserPromptSubmit hook
+- Agents now work independently without state tracking requirements
+
+**Prevention:**
+Trust agents to coordinate naturally through Task tool invocation rather than enforcing artificial state machine.
+
+---
+- Git tree is clean after session ends
+
+**Prevention:**
+- domain-updater priority: 9 (runs after final-validator)
+- commit-manager priority: 10 (FINAL step)
+- Stop hook enforces both must run before session ends
+
+---
+
+### 2024-12-18 - domain-updater Not Available as Subagent
+
+**Problem:**
+Tried to invoke domain-updater via Task tool but got "Agent type 'domain-updater' not found"
+
+**Root Cause:**
+Agents defined in `.claude/agents/*.md` are instructions for Claude to follow, not subagent_types in Claude Code system
+
+**Solution:**
+Execute domain-updater logic manually or use documenter agent which has similar capabilities
+
+**Prevention:**
+To make an agent invokable via Task tool, it needs to be registered in Claude Code's internal system (separate from .claude/agents/)
+
 ## Attention Points
 
-- **Config files for project specifics** - Agents read from `.claude/config/*.json` instead of hardcoding
-- **CLAUDE.md < 300 lines** - Best practice from Anthropic
-- **SKILL.md YAML frontmatter** - ALL skills MUST have `---` frontmatter with name, description
-- **Skill name format** - max 64 chars, lowercase, letters/numbers/hyphens only
+- [2024-12-18] **Workflow is enforced by hooks** - Cannot skip steps, hooks will block
+- [2024-12-18] **domain-updater is MANDATORY** - Stop hook blocks if not executed
+- [2024-12-18] **10 agents total** - domain-updater added as final step (priority 10)
+- [2024-12-18] **Config files (.claude/*) don't require tests** - Excluded from source file checks
+- [2024-12-18] ~~**domain-updater runs complete-task**~~ - OUTDATED: commit-manager now runs complete-task
+- [2024-12-18] **.claude/agents/ vs subagent_type** - Agents in .claude/agents/ are instructions, not Claude Code subagents
+- [2024-12-18] **Never bypass workflow manually** - Follow the agents properly, don't mark as executed without running
+- [2024-12-18] **Use Task tool for agents** - UserPromptSubmit now reminds to use Task(subagent_type="agent-name") instead of manual execution
+- [2024-12-18] **Workflow order fixed** - domain-updater runs BEFORE commit-manager (not after) for clean git
+- [2024-12-18] **commit-manager is FINAL** - It runs complete-task, not domain-updater
+- [2024-12-18] **Stop hook enforces commit** - Blocks if domain-updater ran but commit-manager didn't
+- [2024-12-18] **Research agent added** - Mandatory for features/fixes, runs after analyzer
+- [2024-12-18] **11 agents total** - research added (priority 3)
+- [2024-12-18] **workflow-state.json in .gitignore** - Transient state, not tracked in git
+- [2024-12-19] **Config files for project specifics** - Agents read from `.claude/config/*.json` instead of hardcoding
+- [2024-12-19] **CLAUDE.md < 300 lines** - Best practice from Anthropic, ideally < 60 lines
+- [2024-12-19] **PROJECT.md for project details** - Separate from generic CLAUDE.md
+- [2024-12-19] **Pre-tool-use wildcard issue** - Pattern `.claude/config/*` doesn't match absolute paths, use specific files
+- [2024-12-19] **Tester agent v3.0** - Complete Playwright E2E architecture with fixture-based cleanup
+- [2024-12-19] **E2E cleanup is MANDATORY** - Track all created IDs, delete ONLY tracked data after tests
+- [2024-12-19] **Multi-viewport testing** - Desktop (1280x800), Tablet (768x1024), iPhone SE (375x667) required
+- [2024-12-19] **DB validation in E2E** - Always verify database state after UI actions
+- [2024-12-19] **Real auth only** - Never mock authentication in E2E tests
+- [2024-12-19] **data-testid required** - All interactive elements must have data-testid attributes
+- [2024-12-19] **SKILL.md YAML frontmatter** - ALL skills MUST have `---` frontmatter with name, description
+- [2024-12-19] **Skill name format** - max 64 chars, lowercase, letters/numbers/hyphens only
+- [2024-12-19] **Skill description** - max 1024 chars, describes WHAT skill does and WHEN to use it
+- [2024-12-19] **allowed-tools optional** - Comma-separated tool names to restrict skill capabilities
+- [2024-12-19] **Hooks config correct** - settings.json hooks format is valid, uses command type with python scripts
+
+## Problems & Solutions (2024-12-19)
+
+### 2024-12-19 - CLAUDE.md Too Long and Specific
+
+**Problem:**
+CLAUDE.md had 594 lines, 95% specific to Solana Listeners project. Too long for Claude to follow consistently.
+
+**Root Cause:**
+Project-specific details (workers, docker config, path aliases examples) mixed with universal rules.
+
+**Solution:**
+1. Reduced CLAUDE.md to 115 lines (universal rules only)
+2. Created `PROJECT.md` with project-specific details
+3. Created `.claude/config/` with JSON configs for project specifics
+4. Updated agents to read from config files
+
+**Prevention:**
+- Keep CLAUDE.md under 300 lines (ideally < 60)
+- Put project specifics in PROJECT.md
+- Use `.claude/config/` for things agents need to adapt to
+
+---
+
+### 2024-12-19 - Pre-Tool-Use Wildcard Pattern Not Working
+
+**Problem:**
+Approved files with pattern `.claude/config/*` but hook still blocked edits to `.claude/config/project-config.json`
+
+**Root Cause:**
+Hook checks `file_path.startswith(approved[:-1])` but file_path is absolute path `C:/Users/.../` while approved is relative `.claude/config/*`
+
+**Solution:**
+Approve each file individually instead of using wildcard patterns
+
+**Prevention:**
+When using approve-files, list specific files rather than wildcards if path matching issues occur
+
+---
+
+### 2024-12-19 - E2E Test Data Pollution
+
+**Problem:**
+E2E tests created data in the database but didn't clean up, causing test pollution and confusion with real data.
+
+**Root Cause:**
+Tests were creating users, items, etc. but not tracking or deleting them after completion.
+
+**Solution:**
+Implemented fixture-based cleanup pattern:
+1. `createdIds` fixture tracks all created document IDs by collection
+2. `trackCreated(collection, id)` function to register created data
+3. Auto-cleanup runs after each test, even on failure
+4. Only deletes tracked IDs, never affects real data
+
+**Prevention:**
+- Always use `trackCreated()` immediately after creating data
+- Use the custom `test` from fixtures, not base Playwright `test`
+- Verify cleanup is working with DB inspection
+
+---
+
+### 2024-12-19 - Tester Agent Missing E2E Architecture
+
+**Problem:**
+Tester agent didn't have comprehensive E2E testing patterns for Playwright.
+
+**Root Cause:**
+Previous version focused on unit tests, lacked E2E architecture.
+
+**Solution:**
+Rewrote tester.md with complete Playwright architecture:
+- Fixture-based cleanup pattern
+- Multi-viewport testing (desktop, tablet, mobile)
+- Database validation after UI actions
+- API testing (REST and tRPC)
+- Real authentication flows
+- Storage state for session reuse
+- Security testing (forbidden requests, rate limiting)
+
+**Prevention:**
+- Always test all viewports
+- Always verify DB state, don't trust UI alone
+- Use real auth, never mock it
+
+---
+
+### 2024-12-19 - Skills Missing YAML Frontmatter
+
+**Problem:**
+All SKILL.md files started with `# Title` instead of YAML frontmatter, making them undiscoverable by Claude Code.
+
+**Root Cause:**
+Skills were created as plain markdown without the required YAML frontmatter that Claude Code uses to discover and load skills.
+
+**Solution:**
+Added YAML frontmatter to all 8 SKILL.md files:
+```yaml
+---
+name: skill-name-lowercase
+description: What skill does and when to use it
+allowed-tools: Tool1, Tool2  # optional
+---
+```
+
+**Fixed Files:**
+- quality-gate, security-scan, codebase-knowledge, docs-tracker
+- final-check, ui-ux-audit, research-cache, test-coverage
+
+**Prevention:**
+- Quality-checker now validates SKILL.md format
+- All new skills MUST start with YAML frontmatter
+- name: lowercase-with-hyphens, max 64 chars
+- description: non-empty, max 1024 chars

package/template/.claude/skills/docs-tracker/SKILL.md

@@ -1,63 +1,239 @@
 ---
 name: docs-tracker
-description: Tracks documentation that needs updating after code changes. Activates after code is written, after git commits, when files were modified, or when user says 'update docs', 'changelog', or 'document changes'.
+description: Automates documentation maintenance. Detects modified files via git diff, creates docs for new files, updates docs for modified files, generates changelog. Use after implementation to keep docs current.
 allowed-tools: Read, Glob, Grep, Bash
 ---
 
-# Docs Tracker
+# Docs Tracker - Automatic Documentation System
 
-## When to Use
+## Purpose
 
-- After implementation completes
-- Before committing changes
-- When user asks about documentation
+This skill automates documentation maintenance:
+
+- **Detects** modified files via git diff
+- **Compares** with existing documentation
+- **Creates** docs for new files
+- **Updates** docs for modified files
+- **Removes** docs for deleted files
+- **Generates** automatic changelog
+
+---
+
+## Execution Flow
+
+```
+1. DETECT CHANGES → git diff --name-status
+        ↓
+2. CLASSIFY CHANGES → A=Added, M=Modified, D=Deleted
+        ↓
+3. CHECK EXISTING DOCS → docs/, codebase-knowledge/domains/
+        ↓
+4. EXECUTE ACTIONS → Create, update, or remove docs
+```
+
+---
 
 ## Detection Commands
 
+### Changes Since Last Commit
+
 ```bash
-# Changes since last commit
 git diff --name-status HEAD~1
+```
+
+### Changes vs Main
 
-# Changes vs main branch
+```bash
 git diff --name-status main..HEAD
+```
 
-# Staged changes
-git diff --name-status --cached
+### Added Files
+
+```bash
+git diff --name-status main..HEAD | grep "^A"
+```
+
+### Modified Files
+
+```bash
+git diff --name-status main..HEAD | grep "^M"
+```
+
+### Deleted Files
+
+```bash
+git diff --name-status main..HEAD | grep "^D"
+```
+
+### Detailed File Diff
+
+```bash
+git diff main..HEAD -- path/to/file.ts
 ```
 
+---
+
 ## File → Doc Mapping
 
-| File Type | Update This |
-|-----------|-------------|
-| `server/routers/*.ts` | `domains/[domain].md` |
-| `server/models/*.ts` | `domains/[domain].md` |
-| `app/**/page.tsx` | `docs/flows/[feature].md` |
-| `components/**/*.tsx` | Domain file or component doc |
+| File Type             | Related Documentation                         |
+| --------------------- | --------------------------------------------- |
+| `server/routers/*.ts` | `codebase-knowledge/domains/[domain].md`      |
+| `server/models/*.ts`  | `codebase-knowledge/domains/[domain].md`      |
+| `app/**/page.tsx`     | `docs/flows/[feature].md`                     |
+| `components/**/*.tsx` | `docs/components/[component].md` (if complex) |
+| `lib/**/*.ts`         | `docs/utils/[lib].md` (if exported)           |
+
+---
+
+## Update Rules
+
+### CREATE Doc When:
 
-## Workflow
+- [ ] New file in `server/routers/` → Update domain
+- [ ] New file in `server/models/` → Update domain
+- [ ] New page in `app/` → Create flow doc if complex
+- [ ] New complex component → Consider doc
 
-1. **Detect** - `git diff --name-status`
-2. **Classify** - Added/Modified/Deleted
-3. **Update** - Relevant domain files
-4. **Changelog** - Add entry if significant
+### UPDATE Doc When:
 
-## Changelog Format
+- [ ] tRPC procedure changed signature
+- [ ] Model changed schema
+- [ ] Page changed main flow
+- [ ] Connections between domains changed
+
+### REMOVE Doc When:
+
+- [ ] File was deleted
+- [ ] Feature was completely removed
+- [ ] Component was discontinued
+
+---
+
+## Changelog Template
 
 ```markdown
-## [Unreleased]
+## [Unreleased] - YYYY-MM-DD
 
 ### Added
-- New feature X
+
+- New feature X in `path/to/file.ts`
+- New component Y
 
 ### Changed
-- Modified behavior of Y
+
+- Changed behavior of Z
+- Refactored module W
 
 ### Fixed
-- Bug in Z
+
+- Fixed bug in A
+- Resolved issue #123
+
+### Removed
+
+- Removed obsolete feature B
+
+### Docs Updated
+
+- Updated `codebase-knowledge/domains/[domain].md`
+- Created `docs/flows/[feature].md`
+```
+
+---
+
+## Pre-Commit Checklist
+
+### 1. Detect Changes
+
+```bash
+git diff --name-status --cached
+```
+
+### 2. For Each Modified File
+
+- [ ] Which domain does it belong to?
+- [ ] Is domain updated in `codebase-knowledge/domains/`?
+- [ ] Has flow doc in `docs/flows/`? Needs update?
+- [ ] Commit hash will be added to domain?
+
+### 3. For Added Files
+
+- [ ] Which domain? Add to file list
+- [ ] Needs own doc or just update domain?
+- [ ] Connections with other domains?
+
+### 4. For Deleted Files
+
+- [ ] Remove from `codebase-knowledge/domains/`
+- [ ] Remove flow doc if exists
+- [ ] Update connections in related domains
+
+---
+
+## Integration with Codebase-Knowledge
+
+### Update Domain After Change
+
+```markdown
+## Domain Update: [name]
+
+### Changes Detected
+
+| File         | Status   | Description    |
+| ------------ | -------- | -------------- |
+| path/file.ts | Modified | [what changed] |
+
+### Required Updates in domains/[domain].md
+
+- [ ] Update "Last Update" with date and commit
+- [ ] Add/remove files from list
+- [ ] Update "Recent Commits"
+- [ ] Check "Connections" if integration changed
+- [ ] Update "Attention Points" if applicable
 ```
 
-## Rules
+---
+
+## Output Format
+
+```markdown
+## DOCS TRACKER - Report
+
+### Changes Detected
+
+- **Added:** X files
+- **Modified:** Y files
+- **Deleted:** Z files
+
+### Docs That Need Update
+
+| Doc              | Type   | Action | Priority |
+| ---------------- | ------ | ------ | -------- |
+| domains/auth.md  | domain | update | HIGH     |
+| flows/feature.md | flow   | create | MEDIUM   |
+
+### Actions Executed
+
+- [x] Updated `domains/auth.md` with commit abc123
+- [x] Created `flows/new-feature.md`
+- [x] Removed `flows/obsolete.md`
+
+### Changelog Generated
+
+[changelog preview]
+```
+
+---
+
+## Critical Rules
+
+1. **ALWAYS run before commit** - Outdated docs are technical debt
+2. **NEVER ignore new files** - Every file deserves documentation
+3. **KEEP changelog updated** - Facilitates releases
+4. **SYNC with codebase-knowledge** - It's the source of truth
+
+---
+
+## Version
 
-1. **Run before commit** - outdated docs = tech debt
-2. **Update domains** - sync with codebase-knowledge
-3. **Keep changelog current** - facilitates releases
+- **v2.0.0** - Generic template