dino-spec 18.4.0 → 18.5.0

package/.claude/skills/dino.analyze-codebase/SKILL.md

@@ -0,0 +1,166 @@
+---
+description: Analyze codebase and update documentation (README, ARCHITECTURE, CLAUDE, CHANGELOG)
+metadata:
+  model: opus
+  context: fork
+  effort: high
+  allowed-tools:
+    - Read
+    - Grep
+    - Glob
+    - Task
+    - Bash
+    - Edit
+    - Write
+    - TaskCreate
+    - TaskUpdate
+    - TaskList
+---
+
+# Codebase Analyzer
+
+Analyze project structure using parallel subagents and update documentation files for users and AI assistants.
+
+## STEP 0: DETECT CONTEXT (CRITICAL - DO THIS FIRST)
+
+**The fork loses context. You MUST reconstruct work context from files.**
+
+**Read these IN ORDER:**
+
+1. **Check ARGUMENTS**: If `$ARGUMENTS` is provided and non-empty, use it as analysis scope/flags.
+   - `--docs-only` - Only update docs, skip analysis
+   - `--stats-only` - Only show statistics
+   - `--changelog` - Only update CHANGELOG
+
+2. **Check session.md for project context**: Read `.dino/session.md`
+   - Get current Focus area to prioritize analysis there
+   - Note Phase to understand workflow stage
+   - Check Recent Changes for what needs documenting
+
+3. **Check handoff notes**: Read `.dino/handoff/latest.md` if exists
+   - Get context from previous session
+
+4. **If analyzing dino-spec itself**: Read `CLAUDE.md` and `.claude/rules/dino/` for existing architecture
+
+**CRITICAL**: Do NOT start analysis without understanding project structure first.
+
+## Purpose
+
+Deploy multiple specialized agents to explore different parts of the codebase, then synthesize findings to update:
+
+- **README.md** - User instructions (setup, testing, deployment, glossary)
+- **ARCHITECTURE.md** - System architecture and technical details
+- **CLAUDE.md** - Instructions for Claude Code AI assistant
+- **CHANGELOG.md** - Version history and release tracking
+
+## Workflow
+
+### Phase 1: Deploy Analysis Agents (Parallel)
+
+Launch 5 specialized subagents concurrently:
+
+1. **Backend API Agent** (Explore)
+   - Analyze Controllers, Services, Models, DTOs
+   - Document API patterns, middleware, background jobs
+   - Count files and identify key components
+
+2. **Frontend React Agent** (Explore)
+   - Analyze Components, Pages, Hooks, Services
+   - Document state management, build tooling
+   - Identify UI patterns and dependencies
+
+3. **Testing Infrastructure Agent** (Explore)
+   - Analyze unit tests, integration tests, E2E tests
+   - Document test patterns, frameworks, coverage
+   - Identify test utilities and mocking strategies
+
+4. **Git History Agent** (Bash)
+   - Analyze commit history for CHANGELOG
+   - Identify features, fixes, breaking changes
+   - Group by version/sprint/date
+
+5. **Configuration Agent** (Explore)
+   - Analyze appsettings, environment variables
+   - Document deployment requirements
+   - Identify external service dependencies
+
+### Phase 2: Synthesize Results
+
+Wait for all agents to complete, then:
+
+1. Aggregate statistics (file counts, LOC)
+2. Identify key patterns and conventions
+3. Extract version history from commits
+
+### Phase 3: Update Documentation
+
+Update each file with analysis results:
+
+#### README.md Updates
+
+- Add beginner-friendly explanations
+- Step-by-step setup guide
+- Troubleshooting section
+- Glossary for technical terms
+- Production deployment guide
+
+#### ARCHITECTURE.md Updates
+
+- Codebase statistics table
+- API endpoints overview
+- Database schema summary
+- Component relationship diagrams
+
+#### CLAUDE.md Updates
+
+- File counts in architecture section
+- Key services and controllers tables
+- Updated command references
+
+#### CHANGELOG.md Creation/Update
+
+- Follow Keep a Changelog format
+- Group by version or sprint
+- Categories: Added, Changed, Fixed, Security
+
+## Output
+
+Documentation files updated with:
+
+- Current codebase statistics
+- Accurate file counts
+- User-friendly explanations
+- Technical reference for AI assistants
+- Complete version history
+
+## Usage
+
+```
+/analyze-codebase
+```
+
+Or with specific focus:
+
+```
+/analyze-codebase --docs-only    # Only update docs, skip analysis
+/analyze-codebase --stats-only   # Only show statistics
+/analyze-codebase --changelog    # Only update CHANGELOG
+```
+
+## Agent Configuration
+
+| Agent         | Type    | Purpose                       |
+| ------------- | ------- | ----------------------------- |
+| Backend API   | Explore | Controllers, Services, Models |
+| Frontend      | Explore | Components, Pages, Hooks      |
+| Testing       | Explore | Unit, Integration, E2E tests  |
+| Git History   | Bash    | Commits, tags, releases       |
+| Configuration | Explore | Settings, deployment          |
+
+## Notes
+
+- Uses Task tool with `run_in_background: true` for parallel execution
+- Waits for all agents before synthesizing results
+- Creates CHANGELOG.md if it doesn't exist
+- Preserves existing documentation structure where possible
+- Designed for non-technical users joining the project

package/.claude/skills/dino.refactor/SKILL.md

@@ -0,0 +1,367 @@
+---
+description: Enterprise-grade refactor agent - customer review then engineer planning
+metadata:
+  model: opus
+  context: fork
+  effort: high
+  allowed-tools:
+    - Read
+    - Glob
+    - Grep
+    - Task
+    - AskUserQuestion
+    - Write
+    - TaskCreate
+    - TaskList
+    - TaskUpdate
+    - TaskGet
+    - WebSearch
+  auto-approve: false
+---
+
+# Enterprise Refactor Agent
+
+A two-phase agent that first reviews your project as a **demanding enterprise customer**, then transitions to an **engineer role** to plan and clarify before implementation.
+
+---
+
+## STEP 0: DETECT CONTEXT (CRITICAL - DO THIS FIRST)
+
+**The fork loses context. You MUST reconstruct work context from files.**
+
+**Read these IN ORDER (stop at first match with relevant context):**
+
+**Error Handling**: If any file read fails (file not found), skip to next source. Do NOT error out.
+
+1. **Check ARGUMENTS**: If `$ARGUMENTS` is provided and non-empty, use it as the refactor scope.
+   - Found: Use as scope, proceed to Step 0.5
+   - Empty/missing: Continue to step 2
+
+2. **Check session.md for recent Discovery**: Read `.dino/session.md`
+   - Find `### Discovery:` sections in `## Notes`
+   - Use the MOST RECENT discovery (by date)
+   - Extract any requirements or scope constraints
+   - Found discovery: Use as scope, proceed to Step 0.5
+   - File missing or no discovery: Continue to step 3
+
+3. **Check handoff context**: Read `.dino/handoff/latest.md`
+   - Look for refactor-related scope or constraints
+   - Check for partial progress from previous session
+   - Found relevant handoff: Use as scope, proceed to Step 0.5
+   - File missing or not refactor-related: Continue to step 4
+
+4. **Check existing refactor plans**: Read `.dino/plans/refactor-customer-review.md`
+   - If shows incomplete review (missing sections), CONTINUE from where it left off
+   - If shows complete review, skip to Phase 2
+   - Found: Resume from state, proceed accordingly
+   - File missing: Continue to step 5
+
+5. **If NONE found**: Use `AskUserQuestion` with proper format:
+   ```
+   AskUserQuestion({
+     questions: [{
+       question: "What area of the codebase should I review?",
+       header: "Scope",
+       options: [
+         {label: "Full project", description: "Review entire codebase"},
+         {label: "Security only", description: "Focus on security audit"},
+         {label: "Performance only", description: "Focus on performance issues"},
+         {label: "Specific directory", description: "You'll specify the path"}
+       ],
+       multiSelect: false
+     }]
+   })
+   ```
+
+**CRITICAL**: Do NOT ask user if context exists in any of the above files.
+
+---
+
+## STEP 0.5: PRE-FLIGHT CHECKS
+
+Before proceeding, verify readiness:
+
+1. **Check test/build status**: Read `.dino/session.md` for `## Test Status` and `## Build Status`
+   - If tests failing or build broken, WARN user: "Codebase has existing failures. Review may be incomplete."
+   - Recommend fixing critical failures first
+
+2. **Check complexity**: Evaluate if `/dino.ralph-gate` is more appropriate
+
+   **Complexity Score Calculation:**
+   | Factor | Points |
+   |--------|--------|
+   | Files in scope > 10 | +30 |
+   | Multiple directories | +20 |
+   | Breaking changes expected | +20 |
+   | Database migrations needed | +15 |
+   | API contract changes | +15 |
+   | Security-critical changes | +10 |
+
+   If total > 70 points, recommend `/dino.ralph-gate` instead:
+   ```
+   AskUserQuestion({
+     questions: [{
+       question: "This refactor appears complex (score: [N]). Use Ralph Gate for better tracking?",
+       header: "Workflow",
+       options: [
+         {label: "Use Ralph Gate (Recommended)", description: "Three-agent system with checkpoints"},
+         {label: "Continue with Refactor", description: "Standard two-phase review"}
+       ],
+       multiSelect: false
+     }]
+   })
+   ```
+
+3. **Check confidence**: Read `.dino/session.md` for confidence score
+   - If confidence < 80% and scope is unclear, run `/dino.spec` first
+
+4. **Update session state**:
+   ```
+   Write to .dino/session.md under ## Phase:
+   Phase: refactor-review
+   ```
+
+**Proceed only when scope is clear and pre-flight checks pass.**
+
+---
+
+## PHASE 1: CUSTOMER REVIEW MODE
+
+**Persona**: You are a senior enterprise customer with 20+ years in technology leadership. You have seen countless failed projects and know exactly what separates production-ready systems from prototypes. You are paying significant money and expect enterprise-grade quality.
+
+### Step 1.0: Detect Project Type
+
+Before applying checklists, detect project type by scanning codebase:
+
+```
+Glob for indicators:
+- package.json scripts.start -> Web app / API
+- bin/ or CLI in name -> CLI tool
+- src/components/ or .tsx files -> Frontend
+- prisma/ or migrations/ -> Has database
+- Dockerfile or k8s/ -> Containerized
+- openapi.yaml or swagger -> Has API
+```
+
+**Project Type Classification:**
+
+| Type | Indicators | Skip Domains |
+|------|------------|--------------|
+| **CLI Tool** | bin/, no src/components/, commander/yargs deps | UX/Accessibility, Frontend, Database (if no DB) |
+| **Backend API** | express/fastify/hono, no .tsx | Frontend, UX/Accessibility (except API errors) |
+| **Frontend SPA** | react/vue/svelte, no server | Database, API Design (if no backend) |
+| **Full-Stack** | Both frontend and backend indicators | None |
+| **Library/SDK** | main/module in package.json, no app code | UX/Accessibility, Database |
+
+Record detected type in session.md:
+```markdown
+## Project Type
+[type] - [key indicators found]
+```
+
+**Session Update**: Before starting, update `.dino/session.md`:
+```markdown
+## Phase
+refactor-review (customer audit in progress)
+
+## Focus
+[scope from Step 0]
+```
+
+### Step 1.1: Full Codebase Audit
+
+Launch parallel sub-agents to comprehensively review the entire project.
+
+**Sub-Agent Launch Pattern:**
+```
+Task({
+  subagent_type: "Explore",
+  description: "[Domain] audit",
+  prompt: "Perform a VERY THOROUGH exploration of the codebase focusing on [domain].
+           Find ALL issues, not just obvious ones. Include file:line references.
+           Return findings as structured list with severity (critical/high/medium/low)."
+})
+```
+
+**Domains to Review (launch in parallel where applicable):**
+
+| # | Domain | Skip When |
+|---|--------|-----------|
+| 1 | Architecture & Structure | Never |
+| 2 | Security & Vulnerability | Never |
+| 3 | Performance & Scalability | Never |
+| 4 | Code Quality & Maintainability | Never |
+| 5 | API Design & Contract | No API endpoints |
+| 6 | Frontend UX & Accessibility | CLI/backend-only |
+| 7 | Database Design & Data Integrity | No database |
+| 8 | Error Handling & Resilience | Never |
+| 9 | Testing Coverage & Quality | Never |
+| 10 | Documentation & Onboarding | Never |
+
+**Cost Warning**: Launching 10 parallel agents is expensive. For budget-constrained reviews, batch into 2-3 sequential rounds.
+
+### Step 1.1.1: Validate Sub-Agent Results
+
+After all sub-agents complete:
+
+1. **Check completion**: Verify each agent returned results (not empty/error)
+2. **Merge findings**: Combine results, deduplicate overlapping issues
+3. **Flag gaps**: If any agent failed, note which domain was not reviewed
+4. **Severity count**: Tally critical/high/medium/low findings
+
+```markdown
+## Sub-Agent Results Summary
+- Agents launched: [N]
+- Agents completed: [N]
+- Agents failed: [list or "none"]
+- Total findings: [N] (critical: X, high: Y, medium: Z, low: W)
+```
+
+If any critical domain (Security, Architecture) failed, RE-LAUNCH that agent before proceeding.
+
+### Step 1.1.2: Handle Phase 1 Failure
+
+If Phase 1 cannot complete (multiple agent failures, timeout, or user cancellation):
+
+1. **Save partial state** to `.dino/handoff/latest.md`
+2. **Notify user** with AskUserQuestion
+3. **If "Abort and save"**: Write handoff and exit cleanly
+
+### Step 1.2: Customer Demands Checklist
+
+Review findings against ENTERPRISE-GRADE expectations.
+
+**IMPORTANT**: Skip sections marked with project type restrictions based on Step 1.0 detection.
+
+#### Security Demands (CRITICAL) [ALL PROJECT TYPES]
+- No hardcoded secrets, API keys, or credentials
+- Input validation on ALL user inputs
+- Authentication & authorization on all sensitive endpoints
+- HTTPS enforced, secure headers configured
+- Rate limiting implemented
+- Audit logging for sensitive operations
+- Dependency vulnerabilities scanned
+- CORS properly configured
+
+#### Performance Demands [ALL PROJECT TYPES]
+- Database queries optimized (no N+1, proper indexing)
+- Pagination on all list endpoints
+- Caching strategy for frequently accessed data
+- Async operations where appropriate
+- Bundle size optimized
+- Connection pooling configured
+
+#### Architecture Demands [ALL PROJECT TYPES]
+- Clear separation of concerns
+- Dependency injection used properly
+- Configuration externalized
+- Logging structured and consistent
+- Error handling centralized
+- API versioning strategy
+
+### Step 1.3: Generate Customer Feedback Report
+
+Write findings to `.dino/plans/refactor-customer-review.md`
+
+### Step 1.4: Capture Review Learnings
+
+**Auto-Memory Capture**: After writing customer-review.md, capture key findings for future sessions.
+
+---
+
+## PHASE 2: ENGINEER PLANNING MODE
+
+**Persona**: You are now a senior software engineer who has received the customer review. You must create a realistic implementation plan and ask clarifying questions before any implementation begins.
+
+### Step 2.1: Prioritize and Categorize
+
+Group issues into implementation batches:
+
+| Priority | Criteria | Action |
+|----------|----------|--------|
+| P0 - Critical | Security vulnerabilities, data loss risks | Fix before any deployment |
+| P1 - High | Performance blockers, major bugs | Fix before feature work |
+| P2 - Medium | Technical debt, code quality | Address when touching area |
+| P3 - Low | Nice-to-have improvements | Backlog |
+
+### Step 2.2: Ask Clarifying Questions
+
+**MANDATORY**: Before creating any implementation plan, use `AskUserQuestion` with proper format.
+
+### Step 2.3: Create Engineering Plan
+
+After clarification, write plan to `.dino/plans/refactor-engineering-plan.md`
+
+### Step 2.4: Create Task List
+
+Use `TaskCreate` to create atomic, verifiable tasks.
+
+### Step 2.5: Request Final Approval
+
+Present summary to user with options: Approve -> /dino.hunt, Revise plan, Save for later.
+
+### Step 2.6: Capture Planning Decisions
+
+**Auto-Memory Capture**: After user approves, capture planning decisions for future sessions.
+
+---
+
+## WORKFLOW SUMMARY
+
+```
+Step 0: Context Recovery -> Step 0.5: Pre-flight -> Phase 1: Customer Review -> Phase 2: Engineer Planning -> User Decision
+```
+
+---
+
+## OUTPUT FILES
+
+| File | Purpose |
+|------|---------|
+| `.dino/plans/refactor-customer-review.md` | Customer findings and demands |
+| `.dino/plans/refactor-engineering-plan.md` | Implementation plan |
+| `.dino/session.md` | Phase and progress tracking |
+| `.dino/handoff/latest.md` | Handoff state (if interrupted) |
+
+---
+
+## RELATED SKILLS
+
+| Skill | When to Use |
+|-------|-------------|
+| `/spec` | Run before refactor if scope unclear (confidence < 80%) |
+| `/ralph-gate` | Use instead of refactor if complexity > 70 |
+| `/hunt` | Execute tasks after refactor plan approved |
+| `/scout` | Research specific patterns before planning |
+| `/handoff` | Resume interrupted refactor from handoff |
+| `/verify` | Verify implementation after /hunt |
+| `/fossil` | Archive completed refactor work |
+
+---
+
+## CRITICAL RULES (ENFORCED)
+
+| Rule | Enforcement Point | Block Condition |
+|------|-------------------|-----------------|
+| 1. NO IMPLEMENTATION until approved | Step 2.5 | Edit/Write tool called before approval |
+| 2. ALWAYS ask clarifying questions | Step 2.2 | No AskUserQuestion called in Phase 2 |
+| 3. ALWAYS provide file:line references | Step 1.3 | Findings without :line pattern |
+| 4. ALWAYS estimate impact and risk | Step 2.3 | Batch missing Risks/Rollback sections |
+| 5. NEVER skip security review | Step 1.1.1 | Security domain not in completed list |
+| 6. PRIORITIZE by business impact | Step 2.1 | P0 issues not listed first |
+| 7. DOCUMENT everything | Step 2.3 | Plan file < 500 characters |
+
+---
+
+## STARTING THE REVIEW
+
+**Execution Order:**
+1. Execute Step 0 (Context Recovery) - DO NOT skip
+2. Execute Step 0.5 (Pre-flight Checks)
+3. Execute Step 1.0 (Project Type Detection)
+4. Execute Steps 1.1+ (Customer Review)
+5. Execute Phase 2 (Engineering)
+
+**Trigger**: This skill activates on `/dino.refactor` or "enterprise refactor review"
+
+**SKILL COMPLETE** marker: Skill ends when user approves plan (Step 2.5) or saves handoff.