diff --git a/.claude/agents/check.md b/.claude/agents/check.md deleted file mode 100644 index 071aec4e..00000000 --- a/.claude/agents/check.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -name: check -description: | - Code quality check expert. Reviews code changes against specs and self-fixes issues. -tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa -model: opus ---- -# Check Agent - -You are the Check Agent in the Trellis workflow. - -## Context - -Before checking, read: -- `.trellis/spec/` - Development guidelines -- Pre-commit checklist for quality standards - -## Core Responsibilities - -1. **Get code changes** - Use git diff to get uncommitted code -2. **Check against specs** - Verify code follows guidelines -3. **Self-fix** - Fix issues yourself, not just report them -4. **Run verification** - typecheck and lint - -## Important - -**Fix issues yourself**, don't just report them. - -You have write and edit tools, you can modify code directly. - ---- - -## Workflow - -### Step 1: Get Changes - -```bash -git diff --name-only # List changed files -git diff # View specific changes -``` - -### Step 2: Check Against Specs - -Read relevant specs in `.trellis/spec/` to check code: - -- Does it follow directory structure conventions -- Does it follow naming conventions -- Does it follow code patterns -- Are there missing types -- Are there potential bugs - -### Step 3: Self-Fix - -After finding issues: - -1. Fix the issue directly (use edit tool) -2. Record what was fixed -3. Continue checking other issues - -### Step 4: Run Verification - -Run project's lint and typecheck commands to verify changes. - -If failed, fix issues and re-run. - ---- - -## Completion Markers (Ralph Loop) - -**CRITICAL**: You are in a loop controlled by the Ralph Loop system. -The loop will NOT stop until you output ALL required completion markers. - -Completion markers are generated from `check.jsonl` in the task directory. -Each entry's `reason` field becomes a marker: `{REASON}_FINISH` - -For example, if check.jsonl contains: -```json -{"file": "...", "reason": "TypeCheck"} -{"file": "...", "reason": "Lint"} -{"file": "...", "reason": "CodeReview"} -``` - -You MUST output these markers when each check passes: -- `TYPECHECK_FINISH` - After typecheck passes -- `LINT_FINISH` - After lint passes -- `CODEREVIEW_FINISH` - After code review passes - -If check.jsonl doesn't exist or has no reasons, output: `ALL_CHECKS_FINISH` - -**The loop will block you from stopping until all markers are present in your output.** - ---- - -## Report Format - -```markdown -## Self-Check Complete - -### Files Checked - -- src/components/Feature.tsx -- src/hooks/useFeature.ts - -### Issues Found and Fixed - -1. `:` - -2. `:` - - -### Issues Not Fixed - -(If there are issues that cannot be self-fixed, list them here with reasons) - -### Verification Results - -- TypeCheck: Passed TYPECHECK_FINISH -- Lint: Passed LINT_FINISH - -### Summary - -Checked X files, found Y issues, all fixed. -ALL_CHECKS_FINISH -``` diff --git a/.claude/agents/debug.md b/.claude/agents/debug.md deleted file mode 100644 index 0108d99f..00000000 --- a/.claude/agents/debug.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: debug -description: | - Issue fixing expert. Understands issues, fixes against specs, and verifies fixes. Precise fixes only. -tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa -model: opus ---- -# Debug Agent - -You are the Debug Agent in the Trellis workflow. - -## Context - -Before debugging, read: -- `.trellis/spec/` - Development guidelines -- Error messages or issue descriptions provided - -## Core Responsibilities - -1. **Understand issues** - Analyze error messages or reported issues -2. **Fix against specs** - Fix issues following dev specs -3. **Verify fixes** - Run typecheck to ensure no new issues -4. **Report results** - Report fix status - ---- - -## Workflow - -### Step 1: Understand Issues - -Parse the issue, categorize by priority: - -- `[P1]` - Must fix (blocking) -- `[P2]` - Should fix (important) -- `[P3]` - Optional fix (nice to have) - -### Step 2: Research if Needed - -If you need additional info: - -```bash -# Check knowledge base -ls .trellis/big-question/ -``` - -### Step 3: Fix One by One - -For each issue: - -1. Locate the exact position -2. Fix following specs -3. Run typecheck to verify - -### Step 4: Verify - -Run project's lint and typecheck commands to verify fixes. - -If fix introduces new issues: - -1. Revert the fix -2. Use a more complete solution -3. Re-verify - ---- - -## Report Format - -```markdown -## Fix Report - -### Issues Fixed - -1. `[P1]` `:` - -2. `[P2]` `:` - - -### Issues Not Fixed - -- `:` - - -### Verification - -- TypeCheck: Pass -- Lint: Pass - -### Summary - -Fixed X/Y issues. Z issues require discussion. -``` - ---- - -## Guidelines - -### DO - -- Precise fixes for reported issues -- Follow specs -- Verify each fix - -### DON'T - -- Don't refactor surrounding code -- Don't add new features -- Don't modify unrelated files -- Don't use non-null assertion (`x!` operator) -- Don't execute git commit diff --git a/.claude/agents/dispatch.md b/.claude/agents/dispatch.md deleted file mode 100644 index 2bec15c7..00000000 --- a/.claude/agents/dispatch.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -name: dispatch -description: | - Multi-Agent Pipeline main dispatcher. Pure dispatcher. Only responsible for calling subagents and scripts in phase order. -tools: Read, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa -model: opus ---- -# Dispatch Agent - -You are the Dispatch Agent in the Multi-Agent Pipeline (pure dispatcher). - -## Working Directory Convention - -Current Task is specified by `.trellis/.current-task` file, content is the relative path to task directory. - -Task directory path format: `.trellis/tasks/{MM}-{DD}-{name}/` - -This directory contains all context files for the current task: - -- `task.json` - Task configuration -- `prd.md` - Requirements document -- `info.md` - Technical design (optional) -- `implement.jsonl` - Implement context -- `check.jsonl` - Check context -- `debug.jsonl` - Debug context - -## Core Principles - -1. **You are a pure dispatcher** - Only responsible for calling subagents and scripts in order -2. **You don't read specs/requirements** - Hook will auto-inject all context to subagents -3. **You don't need resume** - Hook injects complete context on each subagent call -4. **You only need simple commands** - Tell subagent "start working" is enough - ---- - -## Startup Flow - -### Step 1: Determine Current Task Directory - -Read `.trellis/.current-task` to get current task directory path: - -```bash -TASK_DIR=$(cat .trellis/.current-task) -# e.g.: .trellis/tasks/02-03-my-feature -``` - -### Step 2: Read Task Configuration - -```bash -cat ${TASK_DIR}/task.json -``` - -Get the `next_action` array, which defines the list of phases to execute. - -### Step 3: Execute in Phase Order - -Execute each step in `phase` order. - -> **Note**: You do NOT need to manually update `current_phase`. The Hook automatically updates it when you call Task with a subagent. - ---- - -## Phase Handling - -> Hook will auto-inject all specs, requirements, and technical design to subagent context. -> Dispatch only needs to issue simple call commands. - -### action: "implement" - -``` -Task( - subagent_type: "implement", - prompt: "Implement the feature described in prd.md in the task directory", - model: "opus", - run_in_background: true -) -``` - -Hook will auto-inject: - -- All spec files from implement.jsonl -- Requirements document (prd.md) -- Technical design (info.md) - -Implement receives complete context and autonomously: read → understand → implement. - -### action: "check" - -``` -Task( - subagent_type: "check", - prompt: "Check code changes, fix issues yourself", - model: "opus", - run_in_background: true -) -``` - -Hook will auto-inject: - -- finish-work.md -- check-cross-layer.md -- check.md -- All spec files from check.jsonl - -### action: "debug" - -``` -Task( - subagent_type: "debug", - prompt: "Fix the issues described in the task context", - model: "opus", - run_in_background: true -) -``` - -Hook will auto-inject: - -- All spec files from debug.jsonl -- Error context if available - -### action: "finish" - -``` -Task( - subagent_type: "check", - prompt: "[finish] Execute final completion check before PR", - model: "opus", - run_in_background: true -) -``` - -**Important**: The `[finish]` marker in prompt triggers different context injection: -- finish-work.md checklist -- update-spec.md (spec update process and templates) -- prd.md for verifying requirements are met - -The finish agent actively updates spec docs when it detects new patterns or contracts in the changes. This is different from regular "check" which has full specs for self-fix loop. - -### action: "create-pr" - -This action creates a Pull Request from the feature branch. Run it via Bash: - -```bash -python3 ./.trellis/scripts/multi_agent/create_pr.py -``` - -This will: -1. Stage and commit all changes (excluding workspace) -2. Push to origin -3. Create a Draft PR using `gh pr create` -4. Update task.json with status="review", pr_url, and current_phase - -**Note**: This is the only action that performs git commit, as it's the final step after all implementation and checks are complete. - ---- - -## Calling Subagents - -### Basic Pattern - -``` -task_id = Task( - subagent_type: "implement", // or "check", "debug" - prompt: "Simple task description", - model: "opus", - run_in_background: true -) - -// Poll for completion -for i in 1..N: - result = TaskOutput(task_id, block=true, timeout=300000) - if result.status == "completed": - break -``` - -### Timeout Settings - -| Phase | Max Time | Poll Count | -|-------|----------|------------| -| implement | 30 min | 6 times | -| check | 15 min | 3 times | -| debug | 20 min | 4 times | - ---- - -## Error Handling - -### Timeout - -If a subagent times out, notify the user and ask for guidance: - -``` -"Subagent {phase} timed out after {time}. Options: -1. Retry the same phase -2. Skip to next phase -3. Abort the pipeline" -``` - -### Subagent Failure - -If a subagent reports failure, read the output and decide: - -- If recoverable: call debug agent to fix -- If not recoverable: notify user and ask for guidance - ---- - -## Key Constraints - -1. **Do not read spec/requirement files directly** - Let Hook inject to subagents -2. **Only commit via create-pr action** - Use `multi_agent/create_pr.py` at the end of pipeline -3. **All subagents should use opus model for complex tasks** -4. **Keep dispatch logic simple** - Complex logic belongs in subagents diff --git a/.claude/agents/implement.md b/.claude/agents/implement.md deleted file mode 100644 index 62442b0a..00000000 --- a/.claude/agents/implement.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: implement -description: | - Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed. -tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa -model: opus ---- -# Implement Agent - -You are the Implement Agent in the Trellis workflow. - -## Context - -Before implementing, read: -- `.trellis/workflow.md` - Project workflow -- `.trellis/spec/` - Development guidelines -- Task `prd.md` - Requirements document -- Task `info.md` - Technical design (if exists) - -## Core Responsibilities - -1. **Understand specs** - Read relevant spec files in `.trellis/spec/` -2. **Understand requirements** - Read prd.md and info.md -3. **Implement features** - Write code following specs and design -4. **Self-check** - Ensure code quality -5. **Report results** - Report completion status - -## Forbidden Operations - -**Do NOT execute these git commands:** - -- `git commit` -- `git push` -- `git merge` - ---- - -## Workflow - -### 1. Understand Specs - -Read relevant specs based on task type: - -- Spec layers: `.trellis/spec///` -- Shared guides: `.trellis/spec/guides/` - -### 2. Understand Requirements - -Read the task's prd.md and info.md: - -- What are the core requirements -- Key points of technical design -- Which files to modify/create - -### 3. Implement Features - -- Write code following specs and technical design -- Follow existing code patterns -- Only do what's required, no over-engineering - -### 4. Verify - -Run project's lint and typecheck commands to verify changes. - ---- - -## Report Format - -```markdown -## Implementation Complete - -### Files Modified - -- `src/components/Feature.tsx` - New component -- `src/hooks/useFeature.ts` - New hook - -### Implementation Summary - -1. Created Feature component... -2. Added useFeature hook... - -### Verification Results - -- Lint: Passed -- TypeCheck: Passed -``` - ---- - -## Code Standards - -- Follow existing code patterns -- Don't add unnecessary abstractions -- Only do what's required, no over-engineering -- Keep code readable diff --git a/.claude/agents/plan.md b/.claude/agents/plan.md deleted file mode 100644 index 5c0d0be9..00000000 --- a/.claude/agents/plan.md +++ /dev/null @@ -1,396 +0,0 @@ ---- -name: plan -description: | - Multi-Agent Pipeline planner. Analyzes requirements and produces a fully configured task directory ready for dispatch. -tools: Read, Bash, Glob, Grep, Task -model: opus ---- -# Plan Agent - -You are the Plan Agent in the Multi-Agent Pipeline. - -**Your job**: Evaluate requirements and, if valid, transform them into a fully configured task directory. - -**You have the power to reject** - If a requirement is unclear, incomplete, unreasonable, or potentially harmful, you MUST refuse to proceed and clean up. - ---- - -## Step 0: Evaluate Requirement (CRITICAL) - -Before doing ANY work, evaluate the requirement: - -``` -PLAN_REQUIREMENT = -``` - -### Reject If: - -1. **Unclear or Vague** - - "Make it better" / "Fix the bugs" / "Improve performance" - - No specific outcome defined - - Cannot determine what "done" looks like - -2. **Incomplete Information** - - Missing critical details to implement - - References unknown systems or files - - Depends on decisions not yet made - -3. **Out of Scope for This Project** - - Requirement doesn't match the project's purpose - - Requires changes to external systems - - Not technically feasible with current architecture - -4. **Potentially Harmful** - - Security vulnerabilities (intentional backdoors, data exfiltration) - - Destructive operations without clear justification - - Circumventing access controls - -5. **Too Large / Should Be Split** - - Multiple unrelated features bundled together - - Would require touching too many systems - - Cannot be completed in a reasonable scope - -### If Rejecting: - -1. **Update task.json status to "rejected"**: - ```bash - jq '.status = "rejected"' "$PLAN_TASK_DIR/task.json" > "$PLAN_TASK_DIR/task.json.tmp" \ - && mv "$PLAN_TASK_DIR/task.json.tmp" "$PLAN_TASK_DIR/task.json" - ``` - -2. **Write rejection reason to a file** (so user can see it): - ```bash - cat > "$PLAN_TASK_DIR/REJECTED.md" << 'EOF' - # Plan Rejected - - ## Reason - - - ## Details - - - ## Suggestions - - - - - - ## To Retry - - 1. Delete this directory: - rm -rf $PLAN_TASK_DIR - - 2. Run with revised requirement: - python3 ./.trellis/scripts/multi_agent/plan.py --name "" --type "" --requirement "" - EOF - ``` - -3. **Print summary to stdout** (will be captured in .plan-log): - ``` - === PLAN REJECTED === - - Reason: - Details: - - See: $PLAN_TASK_DIR/REJECTED.md - ``` - -4. **Exit immediately** - Do not proceed to Step 1. - -**The task directory is kept** with: -- `task.json` (status: "rejected") -- `REJECTED.md` (full explanation) -- `.plan-log` (execution log) - -This allows the user to review why it was rejected. - -### If Accepting: - -Continue to Step 1. The requirement is: -- Clear and specific -- Has a defined outcome -- Is technically feasible -- Is appropriately scoped - ---- - -## Input - -You receive input via environment variables (set by plan.py): - -```bash -PLAN_TASK_NAME # Task name (e.g., "user-auth") -PLAN_DEV_TYPE # Development type: backend | frontend | fullstack -PLAN_REQUIREMENT # Requirement description from user -PLAN_TASK_DIR # Pre-created task directory path -``` - -Read them at startup: - -```bash -echo "Task: $PLAN_TASK_NAME" -echo "Type: $PLAN_DEV_TYPE" -echo "Requirement: $PLAN_REQUIREMENT" -echo "Directory: $PLAN_TASK_DIR" -``` - -## Output (if accepted) - -A complete task directory containing: - -``` -${PLAN_TASK_DIR}/ -├── task.json # Updated with branch, scope, dev_type -├── prd.md # Requirements document -├── implement.jsonl # Implement phase context -├── check.jsonl # Check phase context -└── debug.jsonl # Debug phase context -``` - ---- - -## Workflow (After Acceptance) - -### Step 1: Initialize Context Files - -```bash -python3 ./.trellis/scripts/task.py init-context "$PLAN_TASK_DIR" "$PLAN_DEV_TYPE" -``` - -This creates base jsonl files with standard specs for the dev type. - -### Step 2: Analyze Codebase with Research Agent - -Call research agent to find relevant specs and code patterns: - -``` -Task( - subagent_type: "research", - prompt: "Analyze what specs and code patterns are needed for this task. - -Task: ${PLAN_REQUIREMENT} -Dev Type: ${PLAN_DEV_TYPE} - -Instructions: -1. Search .trellis/spec/ for relevant spec files -2. Search the codebase for related modules and patterns -3. Identify files that should be added to jsonl context - -Output format (use exactly this format): - -## implement.jsonl -- path: , reason: -- path: , reason: - -## check.jsonl -- path: , reason: - -## debug.jsonl -- path: , reason: - -## Suggested Scope - - -## Technical Notes -", - model: "opus" -) -``` - -### Step 3: Add Context Entries - -Parse research agent output and add entries to jsonl files: - -```bash -# For each entry in implement.jsonl section: -python3 ./.trellis/scripts/task.py add-context "$PLAN_TASK_DIR" implement "" "" - -# For each entry in check.jsonl section: -python3 ./.trellis/scripts/task.py add-context "$PLAN_TASK_DIR" check "" "" - -# For each entry in debug.jsonl section: -python3 ./.trellis/scripts/task.py add-context "$PLAN_TASK_DIR" debug "" "" -``` - -### Step 4: Write prd.md - -Create the requirements document: - -```bash -cat > "$PLAN_TASK_DIR/prd.md" << 'EOF' -# Task: ${PLAN_TASK_NAME} - -## Overview -[Brief description of what this feature does] - -## Requirements -- [Requirement 1] -- [Requirement 2] -- ... - -## Acceptance Criteria -- [ ] [Criterion 1] -- [ ] [Criterion 2] -- ... - -## Technical Notes -[Any technical considerations from research agent] - -## Out of Scope -- [What this feature does NOT include] -EOF -``` - -**Guidelines for prd.md**: -- Be specific and actionable -- Include acceptance criteria that can be verified -- Add technical notes from research agent -- Define what's out of scope to prevent scope creep - -### Step 5: Configure Task Metadata - -```bash -# Set branch name -python3 ./.trellis/scripts/task.py set-branch "$PLAN_TASK_DIR" "feature/${PLAN_TASK_NAME}" - -# Set scope (from research agent suggestion) -python3 ./.trellis/scripts/task.py set-scope "$PLAN_TASK_DIR" "" - -# Update dev_type in task.json -jq --arg type "$PLAN_DEV_TYPE" '.dev_type = $type' \ - "$PLAN_TASK_DIR/task.json" > "$PLAN_TASK_DIR/task.json.tmp" \ - && mv "$PLAN_TASK_DIR/task.json.tmp" "$PLAN_TASK_DIR/task.json" -``` - -### Step 6: Validate Configuration - -```bash -python3 ./.trellis/scripts/task.py validate "$PLAN_TASK_DIR" -``` - -If validation fails, fix the invalid paths and re-validate. - -### Step 7: Output Summary - -Print a summary for the caller: - -```bash -echo "=== Plan Complete ===" -echo "Task Directory: $PLAN_TASK_DIR" -echo "" -echo "Files created:" -ls -la "$PLAN_TASK_DIR" -echo "" -echo "Context summary:" -python3 ./.trellis/scripts/task.py list-context "$PLAN_TASK_DIR" -echo "" -echo "Ready for: python3 ./.trellis/scripts/multi_agent/start.py $PLAN_TASK_DIR" -``` - ---- - -## Key Principles - -1. **Reject early, reject clearly** - Don't waste time on bad requirements -2. **Research before configure** - Always call research agent to understand the codebase -3. **Validate all paths** - Every file in jsonl must exist -4. **Be specific in prd.md** - Vague requirements lead to wrong implementations -5. **Include acceptance criteria** - Check agent needs to verify something concrete -6. **Set appropriate scope** - This affects commit message format - ---- - -## Error Handling - -### Research Agent Returns No Results - -If research agent finds no relevant specs: -- Use only the base specs from init-context -- Add a note in prd.md that this is a new area without existing patterns - -### Path Not Found - -If add-context fails because path doesn't exist: -- Skip that entry -- Log a warning -- Continue with other entries - -### Validation Fails - -If final validation fails: -- Read the error output -- Remove invalid entries from jsonl files -- Re-validate - ---- - -## Examples - -### Example: Accepted Requirement - -``` -Input: - PLAN_TASK_NAME = "add-rate-limiting" - PLAN_DEV_TYPE = "backend" - PLAN_REQUIREMENT = "Add rate limiting to API endpoints using a sliding window algorithm. Limit to 100 requests per minute per IP. Return 429 status when exceeded." - -Result: ACCEPTED - Clear, specific, has defined behavior - -Output: - .trellis/tasks/02-03-add-rate-limiting/ - ├── task.json # branch: feature/add-rate-limiting, scope: api - ├── prd.md # Detailed requirements with acceptance criteria - ├── implement.jsonl # Backend specs + existing middleware patterns - ├── check.jsonl # Quality guidelines + API testing specs - └── debug.jsonl # Error handling specs -``` - -### Example: Rejected - Vague Requirement - -``` -Input: - PLAN_REQUIREMENT = "Make the API faster" - -Result: REJECTED - -=== PLAN REJECTED === - -Reason: Unclear or Vague - -Details: -"Make the API faster" does not specify: -- Which endpoints need optimization -- Current performance baseline -- Target performance metrics -- Acceptable trade-offs (memory, complexity) - -Suggestions: -- Identify specific slow endpoints with response times -- Define target latency (e.g., "GET /users should respond in <100ms") -- Specify if caching, query optimization, or architecture changes are acceptable -``` - -### Example: Rejected - Too Large - -``` -Input: - PLAN_REQUIREMENT = "Add user authentication, authorization, password reset, 2FA, OAuth integration, and audit logging" - -Result: REJECTED - -=== PLAN REJECTED === - -Reason: Too Large / Should Be Split - -Details: -This requirement bundles 6 distinct features that should be implemented separately: -1. User authentication (login/logout) -2. Authorization (roles/permissions) -3. Password reset flow -4. Two-factor authentication -5. OAuth integration -6. Audit logging - -Suggestions: -- Start with basic authentication first -- Create separate features for each capability -- Consider dependencies (auth before authz, etc.) -``` diff --git a/.claude/agents/research.md b/.claude/agents/research.md deleted file mode 100644 index 659d59c6..00000000 --- a/.claude/agents/research.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -name: research -description: | - Code and tech search expert. Pure research, no code modifications. Finds files, patterns, and tech solutions. -tools: Read, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__* -model: opus ---- -# Research Agent - -You are the Research Agent in the Trellis workflow. - -## Core Principle - -**You do one thing: find and explain information.** - -You are a documenter, not a reviewer. Your job is to help get the information needed. - ---- - -## Core Responsibilities - -### 1. Internal Search (Project Code) - -| Search Type | Goal | Tools | -|-------------|------|-------| -| **WHERE** | Locate files/components | Glob, Grep | -| **HOW** | Understand code logic | Read, Grep | -| **PATTERN** | Discover existing patterns | Grep, Read | - -### 2. External Search (Tech Solutions) - -Use web search for best practices and code examples. - ---- - -## Strict Boundaries - -### Only Allowed - -- Describe **what exists** -- Describe **where it is** -- Describe **how it works** -- Describe **how components interact** - -### Forbidden (unless explicitly asked) - -- Suggest improvements -- Criticize implementation -- Recommend refactoring -- Modify any files -- Execute git commands - ---- - -## Workflow - -### Step 1: Understand Search Request - -Analyze the query, determine: - -- Search type (internal/external/mixed) -- Search scope (global/specific directory) -- Expected output (file list/code patterns/tech solutions) - -### Step 2: Execute Search - -Execute multiple independent searches in parallel for efficiency. - -### Step 3: Organize Results - -Output structured results in report format. - ---- - -## Report Format - -```markdown -## Search Results - -### Query - -{original query} - -### Files Found - -| File Path | Description | -|-----------|-------------| -| `src/services/xxx.ts` | Main implementation | -| `src/types/xxx.ts` | Type definitions | - -### Code Pattern Analysis - -{Describe discovered patterns, cite specific files and line numbers} - -### Related Spec Documents - -- `.trellis/spec/xxx.md` - {description} - -### Not Found - -{If some content was not found, explain} -``` - ---- - -## Guidelines - -### DO - -- Provide specific file paths and line numbers -- Quote actual code snippets -- Distinguish "definitely found" and "possibly related" -- Explain search scope and limitations - -### DON'T - -- Don't guess uncertain info -- Don't omit important search results -- Don't add improvement suggestions in report (unless explicitly asked) -- Don't modify any files diff --git a/.claude/commands/trellis/before-dev.md b/.claude/commands/trellis/before-dev.md deleted file mode 100644 index d0807655..00000000 --- a/.claude/commands/trellis/before-dev.md +++ /dev/null @@ -1,29 +0,0 @@ -Read the relevant development guidelines before starting your task. - -Execute these steps: - -1. **Discover packages and their spec layers**: - ```bash - python3 ./.trellis/scripts/get_context.py --mode packages - ``` - -2. **Identify which specs apply** to your task based on: - - Which package you're modifying (e.g., `cli/`, `docs-site/`) - - What type of work (backend, frontend, unit-test, docs, etc.) - -3. **Read the spec index** for each relevant module: - ```bash - cat .trellis/spec///index.md - ``` - Follow the **"Pre-Development Checklist"** section in the index. - -4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns. - -5. **Always read shared guides**: - ```bash - cat .trellis/spec/guides/index.md - ``` - -6. Understand the coding standards and patterns you need to follow, then proceed with your development plan. - -This step is **mandatory** before writing any code. diff --git a/.claude/commands/trellis/brainstorm.md b/.claude/commands/trellis/brainstorm.md deleted file mode 100644 index bc2b8afe..00000000 --- a/.claude/commands/trellis/brainstorm.md +++ /dev/null @@ -1,487 +0,0 @@ -# Brainstorm - Requirements Discovery (AI Coding Enhanced) - -Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows: - -* **Task-first** (capture ideas immediately) -* **Action-before-asking** (reduce low-value questions) -* **Research-first** for technical choices (avoid asking users to invent options) -* **Diverge → Converge** (expand thinking, then lock MVP) - ---- - -## When to Use - -Triggered from `/trellis:start` when the user describes a development task, especially when: - -* requirements are unclear or evolving -* there are multiple valid implementation paths -* trade-offs matter (UX, reliability, maintainability, cost, performance) -* the user might not know the best options up front - ---- - -## Core Principles (Non-negotiable) - -1. **Task-first (capture early)** - Always ensure a task exists at the start so the user's ideas are recorded immediately. - -2. **Action before asking** - If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first. - -3. **One question per message** - Never overwhelm the user with a list of questions. Ask one, update PRD, repeat. - -4. **Prefer concrete options** - For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs. - -5. **Research-first for technical choices** - If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options. - -6. **Diverge → Converge** - After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope. - -7. **No meta questions** - Do not ask "should I search?" or "can you paste the code so I can continue?" - If you need information: search/inspect. If blocked: ask the minimal blocking question. - ---- - -## Step 0: Ensure Task Exists (ALWAYS) - -Before any Q&A, ensure a task exists. If none exists, create one immediately. - -* Use a **temporary working title** derived from the user's message. -* It's OK if the title is imperfect — refine later in PRD. - -```bash -TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: " --slug ) -``` - -Create/seed `prd.md` immediately with what you know: - -```markdown -# brainstorm: - -## Goal - - - -## What I already know - -* -* - -## Assumptions (temporary) - -* - -## Open Questions - -* - -## Requirements (evolving) - -* - -## Acceptance Criteria (evolving) - -* [ ] - -## Definition of Done (team quality bar) - -* Tests added/updated (unit/integration where appropriate) -* Lint / typecheck / CI green -* Docs/notes updated if behavior changes -* Rollout/rollback considered if risky - -## Out of Scope (explicit) - -* - -## Technical Notes - -* -* -``` - ---- - -## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS) - -Before asking questions like "what does the code look like?", gather context yourself: - -### Repo inspection checklist - -* Identify likely modules/files impacted -* Locate existing patterns (similar features, conventions, error handling style) -* Check configs, scripts, existing command definitions -* Note any constraints (runtime, dependency policy, build tooling) - -### Documentation checklist - -* Look for existing PRDs/specs/templates -* Look for command usage examples, README, ADRs if any - -Write findings into PRD: - -* Add to `What I already know` -* Add constraints/links to `Technical Notes` - ---- - -## Step 2: Classify Complexity (still useful, not gating task creation) - -| Complexity | Criteria | Action | -| ------------ | ------------------------------------------------------ | ------------------------------------------- | -| **Trivial** | Single-line fix, typo, obvious change | Skip brainstorm, implement directly | -| **Simple** | Clear goal, 1–2 files, scope well-defined | Ask 1 confirm question, then implement | -| **Moderate** | Multiple files, some ambiguity | Light brainstorm (2–3 high-value questions) | -| **Complex** | Vague goal, architectural choices, multiple approaches | Full brainstorm | - -> Note: Task already exists from Step 0. Classification only affects depth of brainstorming. - ---- - -## Step 3: Question Gate (Ask ONLY high-value questions) - -Before asking ANY question, run the following gate: - -### Gate A — Can I derive this without the user? - -If answer is available via: - -* repo inspection (code/config) -* docs/specs/conventions -* quick market/OSS research - -→ **Do not ask.** Fetch it, summarize, update PRD. - -### Gate B — Is this a meta/lazy question? - -Examples: - -* "Should I search?" -* "Can you paste the code so I can proceed?" -* "What does the code look like?" (when repo is available) - -→ **Do not ask.** Take action. - -### Gate C — What type of question is it? - -* **Blocking**: cannot proceed without user input -* **Preference**: multiple valid choices, depends on product/UX/risk preference -* **Derivable**: should be answered by inspection/research - -→ Only ask **Blocking** or **Preference**. - ---- - -## Step 4: Research-first Mode (Mandatory for technical choices) - -### Trigger conditions (any → research-first) - -* The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention -* The user asks for "best practice", "how others do it", "recommendation" -* The user can't reasonably enumerate options - -### Research steps - -1. Identify 2–4 comparable tools/patterns -2. Summarize common conventions and why they exist -3. Map conventions onto our repo constraints -4. Produce **2–3 feasible approaches** for our project - -### Research output format (PRD) - -Add a section in PRD (either within Technical Notes or as its own): - -```markdown -## Research Notes - -### What similar tools do - -* ... -* ... - -### Constraints from our repo/project - -* ... - -### Feasible approaches here - -**Approach A: ** (Recommended) - -* How it works: -* Pros: -* Cons: - -**Approach B: ** - -* How it works: -* Pros: -* Cons: - -**Approach C: ** (optional) - -* ... -``` - -Then ask **one** preference question: - -* "Which approach do you prefer: A / B / C (or other)?" - ---- - -## Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding - -After you can summarize the goal, proactively broaden thinking before converging. - -### Expansion categories (keep to 1–2 bullets each) - -1. **Future evolution** - - * What might this feature become in 1–3 months? - * What extension points are worth preserving now? - -2. **Related scenarios** - - * What adjacent commands/flows should remain consistent with this? - * Are there parity expectations (create vs update, import vs export, etc.)? - -3. **Failure & edge cases** - - * Conflicts, offline/network failure, retries, idempotency, compatibility, rollback - * Input validation, security boundaries, permission checks - -### Expansion message template (to user) - -```markdown -I understand you want to implement: . - -Before diving into design, let me quickly diverge to consider three categories (to avoid rework later): - -1. Future evolution: <1–2 bullets> -2. Related scenarios: <1–2 bullets> -3. Failure/edge cases: <1–2 bullets> - -For this MVP, which would you like to include (or none)? - -1. Current requirement only (minimal viable) -2. Add (reserve for future extension) -3. Add (improve robustness/consistency) -4. Other: describe your preference -``` - -Then update PRD: - -* What's in MVP → `Requirements` -* What's excluded → `Out of Scope` - ---- - -## Step 6: Q&A Loop (CONVERGE) - -### Rules - -* One question per message -* Prefer multiple-choice when possible -* After each user answer: - - * Update PRD immediately - * Move answered items from `Open Questions` → `Requirements` - * Update `Acceptance Criteria` with testable checkboxes - * Clarify `Out of Scope` - -### Question priority (recommended) - -1. **MVP scope boundary** (what is included/excluded) -2. **Preference decisions** (after presenting concrete options) -3. **Failure/edge behavior** (only for MVP-critical paths) -4. **Success metrics & Acceptance Criteria** (what proves it works) - -### Preferred question format (multiple choice) - -```markdown -For , which approach do you prefer? - -1. **Option A** — -2. **Option B** — -3. **Option C** — -4. **Other** — describe your preference -``` - ---- - -## Step 7: Propose Approaches + Record Decisions (Complex tasks) - -After requirements are clear enough, propose 2–3 approaches (if not already done via research-first): - -```markdown -Based on current information, here are 2–3 feasible approaches: - -**Approach A: ** (Recommended) - -* How: -* Pros: -* Cons: - -**Approach B: ** - -* How: -* Pros: -* Cons: - -Which direction do you prefer? -``` - -Record the outcome in PRD as an ADR-lite section: - -```markdown -## Decision (ADR-lite) - -**Context**: Why this decision was needed -**Decision**: Which approach was chosen -**Consequences**: Trade-offs, risks, potential future improvements -``` - ---- - -## Step 8: Final Confirmation + Implementation Plan - -When open questions are resolved, confirm complete requirements with a structured summary: - -### Final confirmation format - -```markdown -Here's my understanding of the complete requirements: - -**Goal**: - -**Requirements**: - -* ... -* ... - -**Acceptance Criteria**: - -* [ ] ... -* [ ] ... - -**Definition of Done**: - -* ... - -**Out of Scope**: - -* ... - -**Technical Approach**: - - -**Implementation Plan (small PRs)**: - -* PR1: -* PR2: -* PR3: - -Does this look correct? If yes, I'll proceed with implementation. -``` - -### Subtask Decomposition (Complex Tasks) - -For complex tasks with multiple independent work items, create subtasks: - -```bash -# Create child tasks -CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR") -CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR") - -# Or link existing tasks -python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR" -``` - ---- - -## PRD Target Structure (final) - -`prd.md` should converge to: - -```markdown -# - -## Goal - - - -## Requirements - -* ... - -## Acceptance Criteria - -* [ ] ... - -## Definition of Done - -* ... - -## Technical Approach - - - -## Decision (ADR-lite) - -Context / Decision / Consequences - -## Out of Scope - -* ... - -## Technical Notes - - -``` - ---- - -## Anti-Patterns (Hard Avoid) - -* Asking user for code/context that can be derived from repo -* Asking user to choose an approach before presenting concrete options -* Meta questions about whether to research -* Staying narrowly on the initial request without considering evolution/edges -* Letting brainstorming drift without updating PRD - ---- - -## Integration with Start Workflow - -After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**: - -```text -Brainstorm - Step 0: Create task directory + seed PRD - Step 1–7: Discover requirements, research, converge - Step 8: Final confirmation → user approves - ↓ -Task Workflow Phase 2 (Prepare for Implementation) - Code-Spec Depth Check (if applicable) - → Research codebase (based on confirmed PRD) - → Configure code-spec context (jsonl files) - → Activate task - ↓ -Task Workflow Phase 3 (Execute) - Implement → Check → Complete -``` - -The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely. - ---- - -## Related Commands - -| Command | When to Use | -|---------|-------------| -| `/trellis:start` | Entry point that triggers brainstorm | -| `/trellis:finish-work` | After implementation is complete | -| `/trellis:update-spec` | If new patterns emerge during work | diff --git a/.claude/commands/trellis/break-loop.md b/.claude/commands/trellis/break-loop.md deleted file mode 100644 index 99057513..00000000 --- a/.claude/commands/trellis/break-loop.md +++ /dev/null @@ -1,125 +0,0 @@ -# Break the Loop - Deep Bug Analysis - -When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle. - ---- - -## Analysis Framework - -Analyze the bug you just fixed from these 5 dimensions: - -### 1. Root Cause Category - -Which category does this bug belong to? - -| Category | Characteristics | Example | -|----------|-----------------|---------| -| **A. Missing Spec** | No documentation on how to do it | New feature without checklist | -| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected | -| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites | -| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined | -| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds | - -### 2. Why Fixes Failed (if applicable) - -If you tried multiple fixes before succeeding, analyze each failure: - -- **Surface Fix**: Fixed symptom, not root cause -- **Incomplete Scope**: Found root cause, didn't cover all cases -- **Tool Limitation**: grep missed it, type check wasn't strict -- **Mental Model**: Kept looking in same layer, didn't think cross-layer - -### 3. Prevention Mechanisms - -What mechanisms would prevent this from happening again? - -| Type | Description | Example | -|------|-------------|---------| -| **Documentation** | Write it down so people know | Update thinking guide | -| **Architecture** | Make the error impossible structurally | Type-safe wrappers | -| **Compile-time** | TypeScript strict, no any | Signature change causes compile error | -| **Runtime** | Monitoring, alerts, scans | Detect orphan entities | -| **Test Coverage** | E2E tests, integration tests | Verify full flow | -| **Code Review** | Checklist, PR template | "Did you check X?" | - -### 4. Systematic Expansion - -What broader problems does this bug reveal? - -- **Similar Issues**: Where else might this problem exist? -- **Design Flaw**: Is there a fundamental architecture issue? -- **Process Flaw**: Is there a development process improvement? -- **Knowledge Gap**: Is the team missing some understanding? - -### 5. Knowledge Capture - -Solidify insights into the system: - -- [ ] Update `.trellis/spec/guides/` thinking guides -- [ ] Update `.trellis/spec/backend/` or `frontend/` docs -- [ ] Create issue record (if applicable) -- [ ] Create feature ticket for root fix -- [ ] Update check commands if needed - ---- - -## Output Format - -Please output analysis in this format: - -```markdown -## Bug Analysis: [Short Description] - -### 1. Root Cause Category -- **Category**: [A/B/C/D/E] - [Category Name] -- **Specific Cause**: [Detailed description] - -### 2. Why Fixes Failed (if applicable) -1. [First attempt]: [Why it failed] -2. [Second attempt]: [Why it failed] -... - -### 3. Prevention Mechanisms -| Priority | Mechanism | Specific Action | Status | -|----------|-----------|-----------------|--------| -| P0 | ... | ... | TODO/DONE | - -### 4. Systematic Expansion -- **Similar Issues**: [List places with similar problems] -- **Design Improvement**: [Architecture-level suggestions] -- **Process Improvement**: [Development process suggestions] - -### 5. Knowledge Capture -- [ ] [Documents to update / tickets to create] -``` - ---- - -## Core Philosophy - -> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.** - -Three levels of insight: -1. **Tactical**: How to fix THIS bug -2. **Strategic**: How to prevent THIS CLASS of bugs -3. **Philosophical**: How to expand thinking patterns - -30 minutes of analysis saves 30 hours of future debugging. - ---- - -## After Analysis: Immediate Actions - -**IMPORTANT**: After completing the analysis above, you MUST immediately: - -1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files: - - If it's a cross-platform issue → update `cross-platform-thinking-guide.md` - - If it's a cross-layer issue → update `cross-layer-thinking-guide.md` - - If it's a code reuse issue → update `code-reuse-thinking-guide.md` - - If it's domain-specific → update `backend/*.md` or `frontend/*.md` - -2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/` - -3. **Commit the spec updates** - This is the primary output, not just the analysis text - -> **The analysis is worthless if it stays in chat. The value is in the updated specs.** diff --git a/.claude/commands/trellis/check-cross-layer.md b/.claude/commands/trellis/check-cross-layer.md deleted file mode 100644 index 591d39b5..00000000 --- a/.claude/commands/trellis/check-cross-layer.md +++ /dev/null @@ -1,153 +0,0 @@ -# Cross-Layer Check - -Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill. - -> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code. - ---- - -## Related Documents - -| Document | Purpose | Timing | -|----------|---------|--------| -| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code | -| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation | -| **`/trellis:check-cross-layer`** (this) | Verification check | **After** implementation | - ---- - -## Execution Steps - -### 1. Identify Change Scope - -```bash -git status -git diff --name-only -``` - -### 2. Select Applicable Check Dimensions - -Based on your change type, execute relevant checks below: - ---- - -## Dimension A: Cross-Layer Data Flow (Required when 3+ layers) - -**Trigger**: Changes involve 3 or more layers - -| Layer | Common Locations | -|-------|------------------| -| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` | -| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` | -| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` | -| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` | -| Utility | `utils/`, `helpers/`, `common/` | - -**Checklist**: -- [ ] Read flow: Database -> Service -> API -> UI -- [ ] Write flow: UI -> API -> Service -> Database -- [ ] Types/schemas correctly passed between layers? -- [ ] Errors properly propagated to caller? -- [ ] Loading/pending states handled at each layer? - -**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md` - ---- - -## Dimension B: Code Reuse (Required when modifying constants/config) - -**Trigger**: -- Modifying UI constants (label, icon, color) -- Modifying any hardcoded value -- Seeing similar code in multiple places -- Creating a new utility/helper function -- Just finished batch modifications across files - -**Checklist**: -- [ ] Search first: How many places define this value? - ```bash - # Search in source files (adjust extensions for your project) - grep -r "value-to-change" src/ - ``` -- [ ] If 2+ places define same value -> Should extract to shared constant -- [ ] After modification, all usage sites updated? -- [ ] If creating utility: Does similar utility already exist? - -**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md` - ---- - -## Dimension B2: New Utility Functions - -**Trigger**: About to create a new utility/helper function - -**Checklist**: -- [ ] Search for existing similar utilities first - ```bash - grep -r "functionNamePattern" src/ - ``` -- [ ] If similar exists, can you extend it instead? -- [ ] If creating new, is it in the right location (shared vs domain-specific)? - ---- - -## Dimension B3: After Batch Modifications - -**Trigger**: Just modified similar patterns in multiple files - -**Checklist**: -- [ ] Did you check ALL files with similar patterns? - ```bash - grep -r "patternYouChanged" src/ - ``` -- [ ] Any files missed that should also be updated? -- [ ] Should this pattern be abstracted to prevent future duplication? - ---- - -## Dimension C: Import/Dependency Paths (Required when creating new files) - -**Trigger**: Creating new source files - -**Checklist**: -- [ ] Using correct import paths (relative vs absolute)? -- [ ] No circular dependencies? -- [ ] Consistent with project's module organization? - ---- - -## Dimension D: Same-Layer Consistency - -**Trigger**: -- Modifying display logic or formatting -- Same domain concept used in multiple places - -**Checklist**: -- [ ] Search for other places using same concept - ```bash - grep -r "ConceptName" src/ - ``` -- [ ] Are these usages consistent? -- [ ] Should they share configuration/constants? - ---- - -## Common Issues Quick Reference - -| Issue | Root Cause | Prevention | -|-------|------------|------------| -| Changed one place, missed others | Didn't search impact scope | `grep` before changing | -| Data lost at some layer | Didn't check data flow | Trace data source to destination | -| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions | -| UI/output inconsistent | Same concept in multiple places | Extract shared constants | -| Similar utility exists | Didn't search first | Search before creating | -| Batch fix incomplete | Didn't verify all occurrences | grep after fixing | - ---- - -## Output - -Report: -1. Which dimensions your changes involve -2. Check results for each dimension -3. Issues found and fix suggestions diff --git a/.claude/commands/trellis/check.md b/.claude/commands/trellis/check.md deleted file mode 100644 index 8e3e272e..00000000 --- a/.claude/commands/trellis/check.md +++ /dev/null @@ -1,25 +0,0 @@ -Check if the code you just wrote follows the development guidelines. - -Execute these steps: - -1. **Identify changed files**: - ```bash - git diff --name-only HEAD - ``` - -2. **Determine which spec modules apply** based on the changed file paths: - ```bash - python3 ./.trellis/scripts/get_context.py --mode packages - ``` - -3. **Read the spec index** for each relevant module: - ```bash - cat .trellis/spec///index.md - ``` - Follow the **"Quality Check"** section in the index. - -4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them. - -5. **Run lint and typecheck** for the affected package. - -6. **Report any violations** and fix them if found. diff --git a/.claude/commands/trellis/create-command.md b/.claude/commands/trellis/create-command.md deleted file mode 100644 index 42397f43..00000000 --- a/.claude/commands/trellis/create-command.md +++ /dev/null @@ -1,154 +0,0 @@ -# Create New Slash Command - -Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories based on user requirements. - -## Usage - -``` -/trellis:create-command -``` - -**Example**: -``` -/trellis:create-command review-pr Check PR code changes against project guidelines -``` - -## Execution Steps - -### 1. Parse Input - -Extract from user input: -- **Command name**: Use kebab-case (e.g., `review-pr`) -- **Description**: What the command should accomplish - -### 2. Analyze Requirements - -Determine command type based on description: -- **Initialization**: Read docs, establish context -- **Pre-development**: Read guidelines, check dependencies -- **Code check**: Validate code quality and guideline compliance -- **Recording**: Record progress, questions, structure changes -- **Generation**: Generate docs, code templates - -### 3. Generate Command Content - -Based on command type, generate appropriate content: - -**Simple command** (1-3 lines): -```markdown -Concise instruction describing what to do -``` - -**Complex command** (with steps): -```markdown -# Command Title - -Command description - -## Steps - -### 1. First Step -Specific action - -### 2. Second Step -Specific action - -## Output Format (if needed) - -Template -``` - -### 4. Create Files - -Create in both directories: -- `.cursor/commands/trellis-.md` -- `.claude/commands/trellis/.md` - -### 5. Confirm Creation - -Output result: -``` -[OK] Created Slash Command: / - -File paths: -- .cursor/commands/trellis-.md -- .claude/commands/trellis/.md - -Usage: -/trellis: - -Description: - -``` - -## Command Content Guidelines - -### [OK] Good command content - -1. **Clear and concise**: Immediately understandable -2. **Executable**: AI can follow steps directly -3. **Well-scoped**: Clear boundaries of what to do and not do -4. **Has output**: Specifies expected output format (if needed) - -### [X] Avoid - -1. **Too vague**: e.g., "optimize code" -2. **Too complex**: Single command should not exceed 100 lines -3. **Duplicate functionality**: Check if similar command exists first - -## Naming Conventions - -| Command Type | Prefix | Example | -|--------------|--------|---------| -| Session Start | `start` | `start` | -| Pre-development | `before-` | `before-dev` | -| Check | `check-` | `check` | -| Record | `record-` | `record-session` | -| Generate | `generate-` | `generate-api-doc` | -| Update | `update-` | `update-changelog` | -| Other | Verb-first | `review-code`, `sync-data` | - -## Example - -### Input -``` -/trellis:create-command review-pr Check PR code changes against project guidelines -``` - -### Generated Command Content -```markdown -# PR Code Review - -Check current PR code changes against project guidelines. - -## Steps - -### 1. Get Changed Files -```bash -git diff main...HEAD --name-only -``` - -### 2. Categorized Review - -**Frontend files** (`apps/web/`): -- Reference `.trellis/spec/frontend/index.md` - -**Backend files** (`packages/api/`): -- Reference `.trellis/spec/backend/index.md` - -### 3. Output Review Report - -Format: - -## PR Review Report - -### Changed Files -- [file list] - -### Check Results -- [OK] Passed items -- [X] Issues found - -### Suggestions -- [improvement suggestions] -``` diff --git a/.claude/commands/trellis/finish-work.md b/.claude/commands/trellis/finish-work.md deleted file mode 100644 index 9daea672..00000000 --- a/.claude/commands/trellis/finish-work.md +++ /dev/null @@ -1,153 +0,0 @@ -# Finish Work - Pre-Commit Checklist - -Before submitting or committing, use this checklist to ensure work completeness. - -**Timing**: After code is written and tested, before commit - ---- - -## Checklist - -### 1. Code Quality - -```bash -# Must pass -pnpm lint -pnpm type-check -pnpm test -``` - -- [ ] `pnpm lint` passes with 0 errors? -- [ ] `pnpm type-check` passes with no type errors? -- [ ] Tests pass? -- [ ] No `console.log` statements (use logger)? -- [ ] No non-null assertions (the `x!` operator)? -- [ ] No `any` types? - -### 1.5. Test Coverage - -Check if your change needs new or updated tests (see `.trellis/spec/unit-test/conventions.md`): - -- [ ] New pure function → unit test added? -- [ ] Bug fix → regression test added in `test/regression.test.ts`? -- [ ] Changed init/update behavior → integration test added/updated? -- [ ] No logic change (text/data only) → no test needed - -### 2. Code-Spec Sync - -**Code-Spec Docs**: -- [ ] Does `.trellis/spec/backend/` need updates? - - New patterns, new modules, new conventions -- [ ] Does `.trellis/spec/frontend/` need updates? - - New components, new hooks, new patterns -- [ ] Does `.trellis/spec/guides/` need updates? - - New cross-layer flows, lessons from bugs - -**Key Question**: -> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?" - -If YES -> Update the relevant code-spec doc. - -### 2.5. Code-Spec Hard Block (Infra/Cross-Layer) - -If this change touches infra or cross-layer contracts, this is a blocking checklist: - -- [ ] Spec content is executable (real signatures/contracts), not principle-only text -- [ ] Includes file path + command/API name + payload field names -- [ ] Includes validation and error matrix -- [ ] Includes Good/Base/Bad cases -- [ ] Includes required tests and assertion points - -**Block Rule**: -In pipeline mode, the finish agent will automatically detect and execute spec updates when gaps are found. -If running this checklist manually, ensure spec sync is complete before committing — run `/trellis:update-spec` if needed. - -### 3. API Changes - -If you modified API endpoints: - -- [ ] Input schema updated? -- [ ] Output schema updated? -- [ ] API documentation updated? -- [ ] Client code updated to match? - -### 4. Database Changes - -If you modified database schema: - -- [ ] Migration file created? -- [ ] Schema file updated? -- [ ] Related queries updated? -- [ ] Seed data updated (if applicable)? - -### 5. Cross-Layer Verification - -If the change spans multiple layers: - -- [ ] Data flows correctly through all layers? -- [ ] Error handling works at each boundary? -- [ ] Types are consistent across layers? -- [ ] Loading states handled? - -### 6. Manual Testing - -- [ ] Feature works in browser/app? -- [ ] Edge cases tested? -- [ ] Error states tested? -- [ ] Works after page refresh? - ---- - -## Quick Check Flow - -```bash -# 1. Code checks -pnpm lint && pnpm type-check - -# 2. View changes -git status -git diff --name-only - -# 3. Based on changed files, check relevant items above -``` - ---- - -## Common Oversights - -| Oversight | Consequence | Check | -|-----------|-------------|-------| -| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ | -| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests | -| Migration not created | Schema out of sync | Check db/migrations/ | -| Types not synced | Runtime errors | Check shared types | -| Tests not updated | False confidence | Run full test suite | -| Console.log left in | Noisy production logs | Search for console.log | - ---- - -## Relationship to Other Commands - -``` -Development Flow: - Write code -> Test -> /trellis:finish-work -> git commit -> /trellis:record-session - | | - Ensure completeness Record progress - -Debug Flow: - Hit bug -> Fix -> /trellis:break-loop -> Knowledge capture - | - Deep analysis -``` - -- `/trellis:finish-work` - Check work completeness (this command) -- `/trellis:record-session` - Record session and commits -- `/trellis:break-loop` - Deep analysis after debugging - ---- - -## Core Principle - -> **Delivery includes not just code, but also documentation, verification, and knowledge capture.** - -Complete work = Code + Docs + Tests + Verification diff --git a/.claude/commands/trellis/integrate-skill.md b/.claude/commands/trellis/integrate-skill.md deleted file mode 100644 index cacafd5a..00000000 --- a/.claude/commands/trellis/integrate-skill.md +++ /dev/null @@ -1,219 +0,0 @@ -# Integrate Claude Skill into Project Guidelines - -Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code). - -## Usage - -``` -/trellis:integrate-skill -``` - -**Examples**: -``` -/trellis:integrate-skill frontend-design -/trellis:integrate-skill mcp-builder -``` - -## Core Principle - -> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly. -> -> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md` -> - Code examples -> Place in `.trellis/spec/{target}/examples/skills//` -> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors -> -> Where `{target}` is `frontend` or `backend`, determined by skill type. - -## Execution Steps - -### 1. Read Skill Content - -```bash -openskills read -``` - -If the skill doesn't exist, prompt user to check available skills: -```bash -# Available skills are listed in AGENTS.md under -``` - -### 2. Determine Integration Target - -Based on skill type, determine which guidelines to update: - -| Skill Category | Integration Target | -|----------------|-------------------| -| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` | -| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` | -| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines | -| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) | - -### 3. Analyze Skill Content - -Extract from the skill: -- **Core concepts**: How the skill works and key concepts -- **Best practices**: Recommended approaches -- **Code patterns**: Reusable code templates -- **Caveats**: Common issues and solutions - -### 4. Execute Integration - -#### 4.1 Update Guidelines Document - -Add a new section to the corresponding `doc.md`: - -```markdown -@@@section:skill- -## # Integration Guide - -### Overview -[Core functionality and use cases of the skill] - -### Project Adaptation -[How to use this skill in the current project] - -### Usage Steps -1. [Step 1] -2. [Step 2] - -### Caveats -- [Project-specific constraints] -- [Differences from default behavior] - -### Reference Examples -See `examples/skills//` - -@@@/section:skill- -``` - -#### 4.2 Create Examples Directory (if code examples exist) - -```bash -# Directory structure ({target} = frontend or backend) -.trellis/spec/{target}/ -|-- doc.md # Add skill-related section -|-- index.md # Update index -+-- examples/ - +-- skills/ - +-- / - |-- README.md # Example documentation - |-- example-1.ts.template # Code example (use .template suffix) - +-- example-2.tsx.template -``` - -**File naming conventions**: -- Code files: `..template` (e.g., `component.tsx.template`) -- Config files: `.config.template` (e.g., `tailwind.config.template`) -- Documentation: `README.md` (normal suffix) - -#### 4.3 Update Index File - -Add to the Quick Navigation table in `index.md`: - -```markdown -| |
| `skill-` | -``` - -### 5. Generate Integration Report - ---- - -## Skill Integration Report: `` - -### # Overview -- **Skill description**: [Functionality description] -- **Integration target**: `.trellis/spec/{target}/` - -### # Tech Stack Compatibility - -| Skill Requirement | Project Status | Compatibility | -|-------------------|----------------|---------------| -| [Tech 1] | [Project tech] | [OK]/[!]/[X] | - -### # Integration Locations - -| Type | Path | -|------|------| -| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-`) | -| Code examples | `.trellis/spec/{target}/examples/skills//` | -| Index update | `.trellis/spec/{target}/index.md` | - -> `{target}` = `frontend` or `backend` - -### # Dependencies (if needed) - -```bash -# Install required dependencies (adjust for your package manager) -npm install -# or -pnpm add -# or -yarn add -``` - -### [OK] Completed Changes - -- [ ] Added `@@@section:skill-` section to `doc.md` -- [ ] Added index entry to `index.md` -- [ ] Created example files in `examples/skills//` -- [ ] Example files use `.template` suffix - -### # Related Guidelines - -- [Existing related section IDs] - ---- - -## 6. Optional: Create Usage Command - -If this skill is frequently used, create a shortcut command: - -```bash -/trellis:create-command use- Use skill following project guidelines -``` - -## Common Skill Integration Reference - -| Skill | Integration Target | Examples Directory | -|-------|-------------------|-------------------| -| `frontend-design` | `frontend` | `examples/skills/frontend-design/` | -| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` | -| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` | -| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) | - -## Example: Integrating `mcp-builder` Skill - -### Directory Structure - -``` -.trellis/spec/backend/ -|-- doc.md # Add MCP section -|-- index.md # Add index entry -+-- examples/ - +-- skills/ - +-- mcp-builder/ - |-- README.md - |-- server.ts.template - |-- tools.ts.template - +-- types.ts.template -``` - -### New Section in doc.md - -```markdown -@@@section:skill-mcp-builder -## # MCP Server Development Guide - -### Overview -Create LLM-callable tool services using MCP (Model Context Protocol). - -### Project Adaptation -- Place services in a dedicated directory -- Follow existing TypeScript and type definition conventions -- Use project's logging system - -### Reference Examples -See `examples/skills/mcp-builder/` - -@@@/section:skill-mcp-builder -``` diff --git a/.claude/commands/trellis/onboard.md b/.claude/commands/trellis/onboard.md deleted file mode 100644 index 2d4dabf8..00000000 --- a/.claude/commands/trellis/onboard.md +++ /dev/null @@ -1,358 +0,0 @@ -You are a senior developer onboarding a new team member to this project's AI-assisted workflow system. - -YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each command exists, what problem it solves at a fundamental level. - -## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS - -This onboarding has THREE equally important parts: - -**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE) -- Explain WHY this workflow exists -- Explain WHAT each command does and WHY - -**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES) -- Walk through ALL 5 examples in detail -- For EACH step in EACH example, explain: - - PRINCIPLE: Why this step exists - - WHAT HAPPENS: What the command actually does - - IF SKIPPED: What goes wrong without it - -**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES) -- Check if project guidelines are still empty templates -- If empty, guide the developer to fill them with project-specific content -- Explain the customization workflow - -DO NOT skip any part. All three parts are essential: -- Part 1 teaches the concepts -- Part 2 shows how concepts work in practice -- Part 3 ensures the project has proper guidelines for AI to follow - -After completing ALL THREE parts, ask the developer about their first task. - ---- - -## CORE PHILOSOPHY: Why This Workflow Exists - -AI-assisted development has three fundamental challenges: - -### Challenge 1: AI Has No Memory - -Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends. - -**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work. - -**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/trellis:start` command reads this history at session start, giving AI "artificial memory." - -### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge - -AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions. - -**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules. - -**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts. - -### Challenge 3: AI Context Window Is Limited - -Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential. - -**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns. - -**The Solution**: The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis:finish-work` command does a final holistic review. - ---- - -## SYSTEM STRUCTURE - -``` -.trellis/ -|-- .developer # Your identity (gitignored) -|-- workflow.md # Complete workflow documentation -|-- workspace/ # "AI Memory" - session history -| |-- index.md # All developers' progress -| +-- {developer}/ # Per-developer directory -| |-- index.md # Personal progress index -| +-- journal-N.md # Session records (max 2000 lines) -|-- tasks/ # Task tracking (unified) -| +-- {MM}-{DD}-{slug}/ # Task directory -| |-- task.json # Task metadata -| +-- prd.md # Requirements doc -|-- spec/ # "AI Training Data" - project knowledge -| |-- frontend/ # Frontend conventions -| |-- backend/ # Backend conventions -| +-- guides/ # Thinking patterns -+-- scripts/ # Automation tools -``` - -### Understanding spec/ subdirectories - -**frontend/** - Single-layer frontend knowledge: -- Component patterns (how to write components in THIS project) -- State management rules (Redux? Zustand? Context?) -- Styling conventions (CSS modules? Tailwind? Styled-components?) -- Hook patterns (custom hooks, data fetching) - -**backend/** - Single-layer backend knowledge: -- API design patterns (REST? GraphQL? tRPC?) -- Database conventions (query patterns, migrations) -- Error handling standards -- Logging and monitoring rules - -**guides/** - Cross-layer thinking guides: -- Code reuse thinking guide -- Cross-layer thinking guide -- Pre-implementation checklists - ---- - -## COMMAND DEEP DIVE - -### /trellis:start - Restore AI Memory - -**WHY IT EXISTS**: -When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state? - -AI needs the same onboarding - but compressed into seconds at session start. - -**WHAT IT ACTUALLY DOES**: -1. Reads developer identity (who am I in this project?) -2. Checks git status (what branch? uncommitted changes?) -3. Reads recent session history from `workspace/` (what happened before?) -4. Identifies active features (what's in progress?) -5. Understands current project state before making any changes - -**WHY THIS MATTERS**: -- Without /trellis:start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work. -- With /trellis:start: AI knows project context, can continue where previous session left off, avoids conflicts. - ---- - -### /trellis:before-dev - Inject Specialized Knowledge - -**WHY IT EXISTS**: -AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns. - -**WHAT IT ACTUALLY DOES**: -1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines -2. Loads project-specific patterns into AI's working context: - - Component naming conventions - - State management patterns - - Database query patterns - - Error handling standards - -**WHY THIS MATTERS**: -- Without before-dev: AI writes generic code that doesn't match project style. -- With before-dev: AI writes code that looks like the rest of the codebase. - ---- - -### /trellis:check - Combat Context Drift - -**WHY IT EXISTS**: -AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift." - -**WHAT IT ACTUALLY DOES**: -1. Re-reads the guidelines that were injected earlier -2. Compares written code against those guidelines -3. Runs type checker and linter -4. Identifies violations and suggests fixes - -**WHY THIS MATTERS**: -- Without check-*: Context drift goes unnoticed, code quality degrades. -- With check-*: Drift is caught and corrected before commit. - ---- - -### /trellis:check-cross-layer - Multi-Dimension Verification - -**WHY IT EXISTS**: -Most bugs don't come from lack of technical skill - they come from "didn't think of it": -- Changed a constant in one place, missed 5 other places -- Modified database schema, forgot to update the API layer -- Created a utility function, but similar one already exists - -**WHAT IT ACTUALLY DOES**: -1. Identifies which dimensions your change involves -2. For each dimension, runs targeted checks: - - Cross-layer data flow - - Code reuse analysis - - Import path validation - - Consistency checks - ---- - -### /trellis:finish-work - Holistic Pre-Commit Review - -**WHY IT EXISTS**: -The `/check-*` commands focus on code quality within a single layer. But real changes often have cross-cutting concerns. - -**WHAT IT ACTUALLY DOES**: -1. Reviews all changes holistically -2. Checks cross-layer consistency -3. Identifies broader impacts -4. Checks if new patterns should be documented - ---- - -### /trellis:record-session - Persist Memory for Future - -**WHY IT EXISTS**: -All the context AI built during this session will be lost when session ends. The next session's `/trellis:start` needs this information. - -**WHAT IT ACTUALLY DOES**: -1. Records session summary to `workspace/{developer}/journal-N.md` -2. Captures what was done, learned, and what's remaining -3. Updates index files for quick lookup - ---- - -## REAL-WORLD WORKFLOW EXAMPLES - -### Example 1: Bug Fix Session - -**[1/8] /trellis:start** - AI needs project context before touching code -**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference -**[3/8] /trellis:before-dev** - Inject project-specific development guidelines -**[4/8] Investigate and fix the bug** - Actual development work -**[5/8] /trellis:check** - Re-verify code against guidelines -**[6/8] /trellis:finish-work** - Holistic cross-layer review -**[7/8] Human tests and commits** - Human validates before code enters repo -**[8/8] /trellis:record-session** - Persist memory for future sessions - -### Example 2: Planning Session (No Code) - -**[1/4] /trellis:start** - Context needed even for non-coding work -**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work -**[3/4] Review docs, create subtask list** - Actual planning work -**[4/4] /trellis:record-session (with --summary)** - Planning decisions must be recorded - -### Example 3: Code Review Fixes - -**[1/6] /trellis:start** - Resume context from previous session -**[2/6] /trellis:before-dev** - Re-inject guidelines before fixes -**[3/6] Fix each CR issue** - Address feedback with guidelines in context -**[4/6] /trellis:check** - Verify fixes did not introduce new issues -**[5/6] /trellis:finish-work** - Document lessons from CR -**[6/6] Human commits, then /trellis:record-session** - Preserve CR lessons - -### Example 4: Large Refactoring - -**[1/5] /trellis:start** - Clear baseline before major changes -**[2/5] Plan phases** - Break into verifiable chunks -**[3/5] Execute phase by phase with /trellis:check after each** - Incremental verification -**[4/5] /trellis:finish-work** - Check if new patterns should be documented -**[5/5] Record with multiple commit hashes** - Link all commits to one feature - -### Example 5: Debug Session - -**[1/6] /trellis:start** - See if this bug was investigated before -**[2/6] /trellis:before-dev** - Guidelines might document known gotchas -**[3/6] Investigation** - Actual debugging work -**[4/6] /trellis:check** - Verify debug changes do not break other things -**[5/6] /trellis:finish-work** - Debug findings might need documentation -**[6/6] Human commits, then /trellis:record-session** - Debug knowledge is valuable - ---- - -## KEY RULES TO EMPHASIZE - -1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates. -2. **Guidelines before code** - /before-dev command injects project knowledge. -3. **Check after code** - /check-* commands catch context drift. -4. **Record everything** - /trellis:record-session persists memory. - ---- - -# PART 3: Customize Your Development Guidelines - -After explaining Part 1 and Part 2, check if the project's development guidelines need customization. - -## Step 1: Check Current Guidelines Status - -Check if `.trellis/spec/` contains empty templates or customized guidelines: - -```bash -# Check if files are still empty templates (look for placeholder text) -grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l -grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l -``` - -## Step 2: Determine Situation - -**Situation A: First-time setup (empty templates)** - -If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project. - -Explain to the developer: - -"I see that the development guidelines in `.trellis/spec/` are still empty templates. This is normal for a new Trellis setup! - -The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, `/before-*-dev` commands won't provide useful guidance. - -**Your first task should be to fill in these guidelines:** - -1. Look at your existing codebase -2. Identify the patterns and conventions already in use -3. Document them in the guideline files - -For example, for `.trellis/spec/backend/database-guidelines.md`: -- What ORM/query library does your project use? -- How are migrations managed? -- What naming conventions for tables/columns? - -Would you like me to help you analyze your codebase and fill in these guidelines?" - -**Situation B: Guidelines already customized** - -If guidelines have real content (no "To be filled" placeholders), this is an existing setup. - -Explain to the developer: - -"Great! Your team has already customized the development guidelines. You can start using `/before-*-dev` commands right away. - -I recommend reading through `.trellis/spec/` to familiarize yourself with the team's coding standards." - -## Step 3: Help Fill Guidelines (If Empty) - -If the developer wants help filling guidelines, create a feature to track this: - -```bash -python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines -``` - -Then systematically analyze the codebase and fill each guideline file: - -1. **Analyze the codebase** - Look at existing code patterns -2. **Document conventions** - Write what you observe, not ideals -3. **Include examples** - Reference actual files in the project -4. **List forbidden patterns** - Document anti-patterns the team avoids - -Work through one file at a time: -- `backend/directory-structure.md` -- `backend/database-guidelines.md` -- `backend/error-handling.md` -- `backend/quality-guidelines.md` -- `backend/logging-guidelines.md` -- `frontend/directory-structure.md` -- `frontend/component-guidelines.md` -- `frontend/hook-guidelines.md` -- `frontend/state-management.md` -- `frontend/quality-guidelines.md` -- `frontend/type-safety.md` - ---- - -## Completing the Onboard Session - -After covering all three parts, summarize: - -"You're now onboarded to the Trellis workflow system! Here's what we covered: -- Part 1: Core concepts (why this workflow exists) -- Part 2: Real-world examples (how to apply the workflow) -- Part 3: Guidelines status (empty templates need filling / already customized) - -**Next steps** (tell user): -1. Run `/trellis:record-session` to record this onboard session -2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines -3. [If guidelines ready] Start your first development task - -What would you like to do first?" diff --git a/.claude/commands/trellis/parallel.md b/.claude/commands/trellis/parallel.md deleted file mode 100644 index 0be6dc69..00000000 --- a/.claude/commands/trellis/parallel.md +++ /dev/null @@ -1,192 +0,0 @@ -# Multi-Agent Pipeline Orchestrator - -You are the Multi-Agent Pipeline Orchestrator Agent, running in the main repository, responsible for collaborating with users to manage parallel development tasks. - -## Role Definition - -- **You are in the main repository**, not in a worktree -- **You don't write code directly** - code work is done by agents in worktrees -- **You are responsible for planning and dispatching**: discuss requirements, create plans, configure context, start worktree agents -- **Delegate complex analysis to research agent**: finding specs, analyzing code structure - ---- - -## Operation Types - -Operations in this document are categorized as: - -| Marker | Meaning | Executor | -|--------|---------|----------| -| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) | -| `[USER]` | Slash commands executed by user | User | - ---- - -## Startup Flow - -### Step 1: Understand Trellis Workflow `[AI]` - -First, read the workflow guide to understand the development process: - -```bash -cat .trellis/workflow.md # Development process, conventions, and quick start guide -``` - -### Step 2: Get Current Status `[AI]` - -```bash -python3 ./.trellis/scripts/get_context.py -``` - -### Step 3: Read Project Guidelines `[AI]` - -```bash -python3 ./.trellis/scripts/get_context.py --mode packages # Discover available spec layers -cat .trellis/spec/guides/index.md # Thinking guides -``` - -### Step 4: Ask User for Requirements - -Ask the user: - -1. What feature to develop? -2. Which modules are involved? -3. Development type? (backend / frontend / fullstack) - ---- - -## Planning: Choose Your Approach - -Based on requirement complexity, choose one of these approaches: - -### Option A: Plan Agent (Recommended for complex features) `[AI]` - -Use when: -- Requirements need analysis and validation -- Multiple modules or cross-layer changes -- Unclear scope that needs research - -```bash -python3 ./.trellis/scripts/multi_agent/plan.py \ - --name "" \ - --type "" \ - --requirement "" -``` - -Plan Agent will: -1. Evaluate requirement validity (may reject if unclear/too large) -2. Call research agent to analyze codebase -3. Create and configure task directory -4. Write prd.md with acceptance criteria -5. Output ready-to-use task directory - -After plan.py completes, start the worktree agent: - -```bash -python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR" -``` - -### Option B: Manual Configuration (For simple/clear features) `[AI]` - -Use when: -- Requirements are already clear and specific -- You know exactly which files are involved -- Simple, well-scoped changes - -#### Step 1: Create Task Directory - -```bash -# title is task description, --slug for task directory name -TASK_DIR=$(python3 ./.trellis/scripts/task.py create "" --slug <task-name>) -``` - -#### Step 2: Configure Task - -```bash -# Initialize jsonl context files -python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <dev_type> - -# Set branch and scope -python3 ./.trellis/scripts/task.py set-branch "$TASK_DIR" feature/<name> -python3 ./.trellis/scripts/task.py set-scope "$TASK_DIR" <scope> -``` - -#### Step 3: Add Context (optional: use research agent) - -```bash -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>" -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>" -``` - -#### Step 4: Create prd.md - -```bash -cat > "$TASK_DIR/prd.md" << 'EOF' -# Feature: <name> - -## Requirements -- ... - -## Acceptance Criteria -- ... -EOF -``` - -#### Step 5: Validate and Start - -```bash -python3 ./.trellis/scripts/task.py validate "$TASK_DIR" -python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR" -``` - ---- - -## After Starting: Report Status - -Tell the user the agent has started and provide monitoring commands. - ---- - -## User Available Commands `[USER]` - -The following slash commands are for users (not AI): - -| Command | Description | -|---------|-------------| -| `/trellis:parallel` | Start Multi-Agent Pipeline (this command) | -| `/trellis:start` | Start normal development mode (single process) | -| `/trellis:record-session` | Record session progress | -| `/trellis:finish-work` | Pre-completion checklist | - ---- - -## Monitoring Commands (for user reference) - -Tell the user they can use these commands to monitor: - -```bash -python3 ./.trellis/scripts/multi_agent/status.py # Overview -python3 ./.trellis/scripts/multi_agent/status.py --log <name> # View log -python3 ./.trellis/scripts/multi_agent/status.py --watch <name> # Real-time monitoring -python3 ./.trellis/scripts/multi_agent/cleanup.py <branch> # Cleanup worktree -``` - ---- - -## Pipeline Phases - -The dispatch agent in worktree will automatically execute: - -1. implement → Implement feature -2. check → Check code quality -3. finish → Final verification -4. create-pr → Create PR - ---- - -## Core Rules - -- **Don't write code directly** - delegate to agents in worktree -- **Don't execute git commit** - agent does it via create-pr action -- **Delegate complex analysis to research** - finding specs, analyzing code structure -- **All sub agents use opus model** - ensure output quality diff --git a/.claude/commands/trellis/record-session.md b/.claude/commands/trellis/record-session.md deleted file mode 100644 index 8bea4f9b..00000000 --- a/.claude/commands/trellis/record-session.md +++ /dev/null @@ -1,62 +0,0 @@ -[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code. - -**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts. - ---- - -## Record Work Progress - -### Step 1: Get Context & Check Tasks - -```bash -python3 ./.trellis/scripts/get_context.py --mode record -``` - -[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json: -- Code committed? → Archive it (don't wait for PR) -- All acceptance criteria met? → Archive it -- Don't skip archiving just because `status` still says `planning` or `in_progress` - -```bash -python3 ./.trellis/scripts/task.py archive <task-name> -``` - -### Step 2: One-Click Add Session - -```bash -# Method 1: Simple parameters -python3 ./.trellis/scripts/add_session.py \ - --title "Session Title" \ - --commit "hash1,hash2" \ - --summary "Brief summary of what was done" - -# Method 2: Pass detailed content via stdin -cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash" -| Feature | Description | -|---------|-------------| -| New API | Added user authentication endpoint | -| Frontend | Updated login form | - -**Updated Files**: -- `packages/api/modules/auth/router.ts` -- `apps/web/modules/auth/components/login-form.tsx` -EOF -``` - -**Auto-completes**: -- [OK] Appends session to journal-N.md -- [OK] Auto-detects line count, creates new file if >2000 lines -- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully) -- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history) -- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes - ---- - -## Script Command Reference - -| Command | Purpose | -|---------|---------| -| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session | -| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** | -| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) | -| `python3 ./.trellis/scripts/task.py list` | List active tasks | diff --git a/.claude/commands/trellis/start.md b/.claude/commands/trellis/start.md deleted file mode 100644 index 1815359d..00000000 --- a/.claude/commands/trellis/start.md +++ /dev/null @@ -1,393 +0,0 @@ -# Start Session - -Initialize your AI development session and begin working on tasks. - ---- - -## Operation Types - -| Marker | Meaning | Executor | -|--------|---------|----------| -| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) | -| `[USER]` | Slash commands executed by user | User | - ---- - -## Initialization `[AI]` - -### Step 1: Understand Development Workflow - -First, read the workflow guide to understand the development process: - -```bash -cat .trellis/workflow.md -``` - -**Follow the instructions in workflow.md** - it contains: -- Core principles (Read Before Write, Follow Standards, etc.) -- File system structure -- Development process -- Best practices - -### Step 2: Get Current Context - -```bash -python3 ./.trellis/scripts/get_context.py -``` - -This shows: developer identity, git status, current task (if any), active tasks. - -### Step 3: Read Guidelines Index - -```bash -python3 ./.trellis/scripts/get_context.py --mode packages -``` - -This shows available packages and their spec layers. Read the relevant spec indexes: - -```bash -cat .trellis/spec/<package>/<layer>/index.md # Package-specific guidelines -cat .trellis/spec/guides/index.md # Thinking guides (always read) -``` - -> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). -> At this step, just read the indexes to understand what's available. -> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist. - -### Step 4: Report and Ask - -Report what you learned and ask: "What would you like to work on?" - ---- - -## Task Classification - -When user describes a task, classify it: - -| Type | Criteria | Workflow | -|------|----------|----------| -| **Question** | User asks about code, architecture, or how something works | Answer directly | -| **Trivial Fix** | Typo fix, comment update, single-line change | Direct Edit | -| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Implement | -| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** | - -### Classification Signals - -**Trivial/Simple indicators:** -- User specifies exact file and change -- "Fix the typo in X" -- "Add field Y to component Z" -- Clear acceptance criteria already stated - -**Complex indicators:** -- "I want to add a feature for..." -- "Can you help me improve..." -- Mentions multiple areas or systems -- No clear implementation path -- User seems unsure about approach - -### Decision Rule - -> **If in doubt, use Brainstorm + Task Workflow.** -> -> Task Workflow ensures code-spec context is injected to agents, resulting in higher quality code. -> The overhead is minimal, but the benefit is significant. - ---- - -## Question / Trivial Fix - -For questions or trivial fixes, work directly: - -1. Answer question or make the fix -2. If code was changed, remind user to run `/trellis:finish-work` - ---- - -## Simple Task - -For simple, well-defined tasks: - -1. Quick confirm: "I understand you want to [goal]. Shall I proceed?" -2. If no, clarify and confirm again -3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.** - - Create task directory (Phase 1 Path B, Step 2) - - Write PRD (Step 3) - - Research codebase (Phase 2, Step 5) - - Configure context (Step 6) - - Activate task (Step 7) - - Implement (Phase 3, Step 8) - - Check quality (Step 9) - - Complete (Step 10) - ---- - -## Complex Task - Brainstorm First - -For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation. - -See `/trellis:brainstorm` for the full process. Summary: - -1. **Acknowledge and classify** - State your understanding -2. **Create task directory** - Track evolving requirements in `prd.md` -3. **Ask questions one at a time** - Update PRD after each answer -4. **Propose approaches** - For architectural decisions -5. **Confirm final requirements** - Get explicit approval -6. **Proceed to Task Workflow** - With clear requirements in PRD - -> **Subtask Decomposition**: If brainstorm reveals multiple independent work items, -> consider creating subtasks using `--parent` flag or `add-subtask` command. -> See `/trellis:brainstorm` Step 8 for details. - -### Key Brainstorm Principles - -| Principle | Description | -|-----------|-------------| -| **One question at a time** | Never overwhelm with multiple questions | -| **Update PRD immediately** | After each answer, update the document | -| **Prefer multiple choice** | Easier for users to answer | -| **YAGNI** | Challenge unnecessary complexity | - ---- - -## Task Workflow (Development Tasks) - -**Why this workflow?** -- Research Agent analyzes what code-spec files are needed -- Code-spec files are configured in jsonl files -- Implement Agent receives code-spec context via Hook injection -- Check Agent verifies against code-spec requirements -- Result: Code that follows project conventions automatically - -### Overview: Two Entry Points - -``` -From Brainstorm (Complex Task): - PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete - -From Simple Task: - Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete -``` - -**Key principle: Research happens AFTER requirements are clear (PRD exists).** - ---- - -### Phase 1: Establish Requirements - -#### Path A: From Brainstorm (skip to Phase 2) - -PRD and task directory already exist from brainstorm. Skip directly to Phase 2. - -#### Path B: From Simple Task - -**Step 1: Confirm Understanding** `[AI]` - -Quick confirm: -- What is the goal? -- What type of development? (frontend / backend / fullstack) -- Any specific requirements or constraints? - -**Step 2: Create Task Directory** `[AI]` - -```bash -TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>) -``` - -**Step 3: Write PRD** `[AI]` - -Create `prd.md` in the task directory with: - -```markdown -# <Task Title> - -## Goal -<What we're trying to achieve> - -## Requirements -- <Requirement 1> -- <Requirement 2> - -## Acceptance Criteria -- [ ] <Criterion 1> -- [ ] <Criterion 2> - -## Technical Notes -<Any technical decisions or constraints> -``` - ---- - -### Phase 2: Prepare for Implementation (shared) - -> Both paths converge here. PRD and task directory must exist before proceeding. - -**Step 4: Code-Spec Depth Check** `[AI]` - -If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined. - -Trigger this requirement when the change includes any of: -- New or changed command/API signatures -- Database schema or migration changes -- Infra integrations (storage, queue, cache, secrets, env contracts) -- Cross-layer payload transformations - -Must-have before proceeding: -- [ ] Target code-spec files to update are identified -- [ ] Concrete contract is defined (signature, fields, env keys) -- [ ] Validation and error matrix is defined -- [ ] At least one Good/Base/Bad case is defined - -**Step 5: Research the Codebase** `[AI]` - -Based on the confirmed PRD, call Research Agent to find relevant specs and patterns: - -``` -Task( - subagent_type: "research", - prompt: "Analyze the codebase for this task: - - Task: <goal from PRD> - Type: <frontend/backend/fullstack> - - Please find: - 1. Relevant code-spec files in .trellis/spec/ - 2. Existing code patterns to follow (find 2-3 examples) - 3. Files that will likely need modification - - Output: - ## Relevant Code-Specs - - <path>: <why it's relevant> - - ## Code Patterns Found - - <pattern>: <example file path> - - ## Files to Modify - - <path>: <what change>", - model: "opus" -) -``` - -**Step 6: Configure Context** `[AI]` - -Initialize default context: - -```bash -python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> -# type: backend | frontend | fullstack -``` - -Add code-spec files found by Research Agent: - -```bash -# For each relevant code-spec and code pattern: -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>" -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>" -``` - -**Step 7: Activate Task** `[AI]` - -```bash -python3 ./.trellis/scripts/task.py start "$TASK_DIR" -``` - -This sets `.current-task` so hooks can inject context. - ---- - -### Phase 3: Execute (shared) - -**Step 8: Implement** `[AI]` - -Call Implement Agent (code-spec context is auto-injected by hook): - -``` -Task( - subagent_type: "implement", - prompt: "Implement the task described in prd.md. - - Follow all code-spec files that have been injected into your context. - Run lint and typecheck before finishing.", - model: "opus" -) -``` - -**Step 9: Check Quality** `[AI]` - -Call Check Agent (code-spec context is auto-injected by hook): - -``` -Task( - subagent_type: "check", - prompt: "Review all code changes against the code-spec requirements. - - Fix any issues you find directly. - Ensure lint and typecheck pass.", - model: "opus" -) -``` - -**Step 10: Complete** `[AI]` - -1. Verify lint and typecheck pass -2. Report what was implemented -3. Remind user to: - - Test the changes - - Commit when ready - - Run `/trellis:record-session` to record this session - ---- - -## Continuing Existing Task - -If `get_context.py` shows a current task: - -1. Read the task's `prd.md` to understand the goal -2. Check `task.json` for current status and phase -3. Ask user: "Continue working on <task-name>?" - -If yes, resume from the appropriate step (usually Step 7 or 8). - ---- - -## Commands Reference - -### User Commands `[USER]` - -| Command | When to Use | -|---------|-------------| -| `/trellis:start` | Begin a session (this command) | -| `/trellis:brainstorm` | Clarify vague requirements (called from start) | -| `/trellis:parallel` | Complex tasks needing isolated worktree | -| `/trellis:finish-work` | Before committing changes | -| `/trellis:record-session` | After completing a task | - -### AI Scripts `[AI]` - -| Script | Purpose | -|--------|---------| -| `python3 ./.trellis/scripts/get_context.py` | Get session context | -| `python3 ./.trellis/scripts/task.py create` | Create task directory | -| `python3 ./.trellis/scripts/task.py init-context` | Initialize jsonl files | -| `python3 ./.trellis/scripts/task.py add-context` | Add code-spec/context file to jsonl | -| `python3 ./.trellis/scripts/task.py start` | Set current task | -| `python3 ./.trellis/scripts/task.py finish` | Clear current task | -| `python3 ./.trellis/scripts/task.py archive` | Archive completed task | - -### Sub Agents `[AI]` - -| Agent | Purpose | Hook Injection | -|-------|---------|----------------| -| research | Analyze codebase | No (reads directly) | -| implement | Write code | Yes (implement.jsonl) | -| check | Review & fix | Yes (check.jsonl) | -| debug | Fix specific issues | Yes (debug.jsonl) | - ---- - -## Key Principle - -> **Code-spec context is injected, not remembered.** -> -> The Task Workflow ensures agents receive relevant code-spec context automatically. -> This is more reliable than hoping the AI "remembers" conventions. diff --git a/.claude/commands/trellis/update-spec.md b/.claude/commands/trellis/update-spec.md deleted file mode 100644 index 3f0b2e77..00000000 --- a/.claude/commands/trellis/update-spec.md +++ /dev/null @@ -1,354 +0,0 @@ -# Update Code-Spec - Capture Executable Contracts - -When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents. - -**Timing**: After completing a task, fixing a bug, or discovering a new pattern - ---- - -## Code-Spec First Rule (CRITICAL) - -In this project, "spec" for implementation work means **code-spec**: -- Executable contracts (not principle-only text) -- Concrete signatures, payload fields, env keys, and boundary behavior -- Testable validation/error behavior - -If the change touches infra or cross-layer contracts, code-spec depth is mandatory. - -### Mandatory Triggers - -Apply code-spec depth when the change includes any of: -- New/changed command or API signature -- Cross-layer request/response contract change -- Database schema/migration change -- Infra integration (storage, queue, cache, secrets, env wiring) - -### Mandatory Output (7 Sections) - -For triggered tasks, include all sections below: -1. Scope / Trigger -2. Signatures (command/API/DB) -3. Contracts (request/response/env) -4. Validation & Error Matrix -5. Good/Base/Bad Cases -6. Tests Required (with assertion points) -7. Wrong vs Correct (at least one pair) - ---- - -## When to Update Code-Specs - -| Trigger | Example | Target Spec | -|---------|---------|-------------| -| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file | -| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section | -| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` | -| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file | -| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section | -| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` | -| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) | - -**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely. - ---- - -## Spec Structure Overview - -``` -.trellis/spec/ -├── backend/ # Backend coding standards -│ ├── index.md # Overview and links -│ └── *.md # Topic-specific guidelines -├── frontend/ # Frontend coding standards -│ ├── index.md # Overview and links -│ └── *.md # Topic-specific guidelines -└── guides/ # Thinking checklists (NOT coding specs!) - ├── index.md # Guide index - └── *.md # Topic-specific guides -``` - -### CRITICAL: Code-Spec vs Guide - Know the Difference - -| Type | Location | Purpose | Content Style | -|------|----------|---------|---------------| -| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points | -| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs | - -**Decision Rule**: Ask yourself: - -- "This is **how to write** the code" → Put in `backend/` or `frontend/` -- "This is **what to consider** before writing" → Put in `guides/` - -**Example**: - -| Learning | Wrong Location | Correct Location | -|----------|----------------|------------------| -| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` | -| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` | - -**Guides should be short checklists that point to specs**, not duplicate the detailed rules. - ---- - -## Update Process - -### Step 1: Identify What You Learned - -Answer these questions: - -1. **What did you learn?** (Be specific) -2. **Why is it important?** (What problem does it prevent?) -3. **Where does it belong?** (Which spec file?) - -### Step 2: Classify the Update Type - -| Type | Description | Action | -|------|-------------|--------| -| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section | -| **Project Convention** | How we do X in this project | Add to relevant section with examples | -| **New Pattern** | A reusable approach discovered | Add to "Patterns" section | -| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section | -| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section | -| **Convention** | Agreed-upon standard | Add to relevant section | -| **Gotcha** | Non-obvious behavior | Add warning callout | - -### Step 3: Read the Target Code-Spec - -Before editing, read the current code-spec to: -- Understand existing structure -- Avoid duplicating content -- Find the right section for your update - -```bash -cat .trellis/spec/<category>/<file>.md -``` - -### Step 4: Make the Update - -Follow these principles: - -1. **Be Specific**: Include concrete examples, not just abstract rules -2. **Explain Why**: State the problem this prevents -3. **Show Contracts**: Add signatures, payload fields, and error behavior -4. **Show Code**: Add code snippets for key patterns -5. **Keep it Short**: One concept per section - -### Step 5: Update the Index (if needed) - -If you added a new section or the code-spec status changed, update the category's `index.md`. - ---- - -## Update Templates - -### Mandatory Template for Infra/Cross-Layer Work - -```markdown -## Scenario: <name> - -### 1. Scope / Trigger -- Trigger: <why this requires code-spec depth> - -### 2. Signatures -- Backend command/API/DB signature(s) - -### 3. Contracts -- Request fields (name, type, constraints) -- Response fields (name, type, constraints) -- Environment keys (required/optional) - -### 4. Validation & Error Matrix -- <condition> -> <error> - -### 5. Good/Base/Bad Cases -- Good: ... -- Base: ... -- Bad: ... - -### 6. Tests Required -- Unit/Integration/E2E with assertion points - -### 7. Wrong vs Correct -#### Wrong -... -#### Correct -... -``` - -### Adding a Design Decision - -```markdown -### Design Decision: [Decision Name] - -**Context**: What problem were we solving? - -**Options Considered**: -1. Option A - brief description -2. Option B - brief description - -**Decision**: We chose Option X because... - -**Example**: -\`\`\`typescript -// How it's implemented -code example -\`\`\` - -**Extensibility**: How to extend this in the future... -``` - -### Adding a Project Convention - -```markdown -### Convention: [Convention Name] - -**What**: Brief description of the convention. - -**Why**: Why we do it this way in this project. - -**Example**: -\`\`\`typescript -// How to follow this convention -code example -\`\`\` - -**Related**: Links to related conventions or specs. -``` - -### Adding a New Pattern - -```markdown -### Pattern Name - -**Problem**: What problem does this solve? - -**Solution**: Brief description of the approach. - -**Example**: -\`\`\` -// Good -code example - -// Bad -code example -\`\`\` - -**Why**: Explanation of why this works better. -``` - -### Adding a Forbidden Pattern - -```markdown -### Don't: Pattern Name - -**Problem**: -\`\`\` -// Don't do this -bad code example -\`\`\` - -**Why it's bad**: Explanation of the issue. - -**Instead**: -\`\`\` -// Do this instead -good code example -\`\`\` -``` - -### Adding a Common Mistake - -```markdown -### Common Mistake: Description - -**Symptom**: What goes wrong - -**Cause**: Why this happens - -**Fix**: How to correct it - -**Prevention**: How to avoid it in the future -``` - -### Adding a Gotcha - -```markdown -> **Warning**: Brief description of the non-obvious behavior. -> -> Details about when this happens and how to handle it. -``` - ---- - -## Interactive Mode - -If you're unsure what to update, answer these prompts: - -1. **What did you just finish?** - - [ ] Fixed a bug - - [ ] Implemented a feature - - [ ] Refactored code - - [ ] Had a discussion about approach - -2. **What did you learn or decide?** - - Design decision (why X over Y) - - Project convention (how we do X) - - Non-obvious behavior (gotcha) - - Better approach (pattern) - -3. **Would future AI/developers need to know this?** - - To understand how the code works → Yes, update spec - - To maintain or extend the feature → Yes, update spec - - To avoid repeating mistakes → Yes, update spec - - Purely one-off implementation detail → Maybe skip - -4. **Which area does it relate to?** - - [ ] Backend code - - [ ] Frontend code - - [ ] Cross-layer data flow - - [ ] Code organization/reuse - - [ ] Quality/testing - ---- - -## Quality Checklist - -Before finishing your code-spec update: - -- [ ] Is the content specific and actionable? -- [ ] Did you include a code example? -- [ ] Did you explain WHY, not just WHAT? -- [ ] Did you include executable signatures/contracts? -- [ ] Did you include validation and error matrix? -- [ ] Did you include Good/Base/Bad cases? -- [ ] Did you include required tests with assertion points? -- [ ] Is it in the right code-spec file? -- [ ] Does it duplicate existing content? -- [ ] Would a new team member understand it? - ---- - -## Relationship to Other Commands - -``` -Development Flow: - Learn something → /trellis:update-spec → Knowledge captured - ↑ ↓ - /trellis:break-loop ←──────────────────── Future sessions benefit - (deep bug analysis) -``` - -- `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed -- `/trellis:update-spec` - Actually makes the updates (this command) -- `/trellis:finish-work` - Reminds you to check if specs need updates - ---- - -## Core Philosophy - -> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.** - -The goal is **institutional memory**: -- What one person learns, everyone benefits from -- What AI learns in one session, persists to future sessions -- Mistakes become documented guardrails diff --git a/.claude/hooks/inject-subagent-context.py b/.claude/hooks/inject-subagent-context.py deleted file mode 100644 index f89b4c7c..00000000 --- a/.claude/hooks/inject-subagent-context.py +++ /dev/null @@ -1,803 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -""" -Multi-Agent Pipeline Context Injection Hook - -Core Design Philosophy: -- Dispatch becomes a pure dispatcher, only responsible for "calling subagents" -- Hook is responsible for injecting all context, subagent works autonomously with complete info -- Each agent has a dedicated jsonl file defining its context -- No resume needed, no segmentation, behavior controlled by code not prompt - -Trigger: PreToolUse (before Task tool call) - -Context Source: .trellis/.current-task points to task directory -- implement.jsonl - Implement agent dedicated context -- check.jsonl - Check agent dedicated context -- debug.jsonl - Debug agent dedicated context -- research.jsonl - Research agent dedicated context (optional, usually not needed) -- cr.jsonl - Code review dedicated context -- prd.md - Requirements document -- info.md - Technical design -- codex-review-output.txt - Code Review results -""" - -# IMPORTANT: Suppress all warnings FIRST -import warnings -warnings.filterwarnings("ignore") - -import json -import os -import sys -from pathlib import Path - -# IMPORTANT: Force stdout to use UTF-8 on Windows -# This fixes UnicodeEncodeError when outputting non-ASCII characters -if sys.platform == "win32": - import io as _io - if hasattr(sys.stdout, "reconfigure"): - sys.stdout.reconfigure(encoding="utf-8", errors="replace") # type: ignore[union-attr] - elif hasattr(sys.stdout, "detach"): - sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace") # type: ignore[union-attr] - -# ============================================================================= -# Path Constants (change here to rename directories) -# ============================================================================= - -DIR_WORKFLOW = ".trellis" -DIR_WORKSPACE = "workspace" -DIR_TASKS = "tasks" -DIR_SPEC = "spec" -FILE_CURRENT_TASK = ".current-task" -FILE_TASK_JSON = "task.json" - -# Agents that don't update phase (can be called at any time) -AGENTS_NO_PHASE_UPDATE = {"debug", "research"} - -# ============================================================================= -# Subagent Constants (change here to rename subagent types) -# ============================================================================= - -AGENT_IMPLEMENT = "implement" -AGENT_CHECK = "check" -AGENT_DEBUG = "debug" -AGENT_RESEARCH = "research" - -# Agents that require a task directory -AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_DEBUG) -# All supported agents -AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_DEBUG, AGENT_RESEARCH) - - -def find_repo_root(start_path: str) -> str | None: - """ - Find git repo root from start_path upwards - - Returns: - Repo root path, or None if not found - """ - current = Path(start_path).resolve() - while current != current.parent: - if (current / ".git").exists(): - return str(current) - current = current.parent - return None - - -def get_current_task(repo_root: str) -> str | None: - """ - Read current task directory path from .trellis/.current-task - - Returns: - Task directory relative path (relative to repo_root) - None if not set - """ - current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK) - if not os.path.exists(current_task_file): - return None - - try: - with open(current_task_file, "r", encoding="utf-8") as f: - content = f.read().strip() - if not content: - return None - normalized = content.replace("\\", "/") - while normalized.startswith("./"): - normalized = normalized[2:] - if normalized.startswith("tasks/"): - normalized = f".trellis/{normalized}" - return normalized - except Exception: - return None - - -def update_current_phase(repo_root: str, task_dir: str, subagent_type: str) -> None: - """ - Update current_phase in task.json based on subagent_type. - - This ensures phase tracking is always accurate, regardless of whether - dispatch agent remembers to update it. - - Logic: - - Read next_action array from task.json - - Find the next phase whose action matches subagent_type - - Only move forward, never backward - - Some agents (debug, research) don't update phase - """ - if subagent_type in AGENTS_NO_PHASE_UPDATE: - return - - task_json_path = os.path.join(repo_root, task_dir, FILE_TASK_JSON) - if not os.path.exists(task_json_path): - return - - try: - with open(task_json_path, "r", encoding="utf-8") as f: - task_data = json.load(f) - - current_phase = task_data.get("current_phase", 0) - next_actions = task_data.get("next_action", []) - - # Map action names to subagent types - # "implement" -> "implement", "check" -> "check", "finish" -> "check" - action_to_agent = { - "implement": "implement", - "check": "check", - "finish": "check", # finish uses check agent - } - - # Find the next phase that matches this subagent_type - new_phase = None - for action in next_actions: - phase_num = action.get("phase", 0) - action_name = action.get("action", "") - expected_agent = action_to_agent.get(action_name) - - # Only consider phases after current_phase - if phase_num > current_phase and expected_agent == subagent_type: - new_phase = phase_num - break - - if new_phase is not None: - task_data["current_phase"] = new_phase - - with open(task_json_path, "w", encoding="utf-8") as f: - json.dump(task_data, f, indent=2, ensure_ascii=False) - except Exception: - # Don't fail the hook if phase update fails - pass - - -def read_file_content(base_path: str, file_path: str) -> str | None: - """Read file content, return None if file doesn't exist""" - full_path = os.path.join(base_path, file_path) - if os.path.exists(full_path) and os.path.isfile(full_path): - try: - with open(full_path, "r", encoding="utf-8") as f: - return f.read() - except Exception: - return None - return None - - -def read_directory_contents( - base_path: str, dir_path: str, max_files: int = 20 -) -> list[tuple[str, str]]: - """ - Read all .md files in a directory - - Args: - base_path: Base path (usually repo_root) - dir_path: Directory relative path - max_files: Max files to read (prevent huge directories) - - Returns: - [(file_path, content), ...] - """ - full_path = os.path.join(base_path, dir_path) - if not os.path.exists(full_path) or not os.path.isdir(full_path): - return [] - - results = [] - try: - # Only read .md files, sorted by filename - md_files = sorted( - [ - f - for f in os.listdir(full_path) - if f.endswith(".md") and os.path.isfile(os.path.join(full_path, f)) - ] - ) - - for filename in md_files[:max_files]: - file_full_path = os.path.join(full_path, filename) - relative_path = os.path.join(dir_path, filename) - try: - with open(file_full_path, "r", encoding="utf-8") as f: - content = f.read() - results.append((relative_path, content)) - except Exception: - continue - except Exception: - pass - - return results - - -def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]: - """ - Read all file/directory contents referenced in jsonl file - - Schema: - {"file": "path/to/file.md", "reason": "..."} - {"file": "path/to/dir/", "type": "directory", "reason": "..."} - - Returns: - [(path, content), ...] - """ - full_path = os.path.join(base_path, jsonl_path) - if not os.path.exists(full_path): - return [] - - results = [] - try: - with open(full_path, "r", encoding="utf-8") as f: - for line in f: - line = line.strip() - if not line: - continue - try: - item = json.loads(line) - file_path = item.get("file") or item.get("path") - entry_type = item.get("type", "file") - - if not file_path: - continue - - if entry_type == "directory": - # Read all .md files in directory - dir_contents = read_directory_contents(base_path, file_path) - results.extend(dir_contents) - else: - # Read single file - content = read_file_content(base_path, file_path) - if content: - results.append((file_path, content)) - except json.JSONDecodeError: - continue - except Exception: - pass - - return results - - -def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str: - """ - Get complete context for specified agent - - Prioritize agent-specific jsonl, fallback to spec.jsonl if not exists - """ - context_parts = [] - - # 1. Try agent-specific jsonl - agent_jsonl = f"{task_dir}/{agent_type}.jsonl" - agent_entries = read_jsonl_entries(repo_root, agent_jsonl) - - # 2. If agent-specific jsonl doesn't exist or empty, fallback to spec.jsonl - if not agent_entries: - agent_entries = read_jsonl_entries(repo_root, f"{task_dir}/spec.jsonl") - - # 3. Add all files from jsonl - for file_path, content in agent_entries: - context_parts.append(f"=== {file_path} ===\n{content}") - - return "\n\n".join(context_parts) - - -def get_implement_context(repo_root: str, task_dir: str) -> str: - """ - Complete context for Implement Agent - - Read order: - 1. All files in implement.jsonl (dev specs) - 2. prd.md (requirements) - 3. info.md (technical design) - """ - context_parts = [] - - # 1. Read implement.jsonl (or fallback to spec.jsonl) - base_context = get_agent_context(repo_root, task_dir, "implement") - if base_context: - context_parts.append(base_context) - - # 2. Requirements document - prd_content = read_file_content(repo_root, f"{task_dir}/prd.md") - if prd_content: - context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}") - - # 3. Technical design - info_content = read_file_content(repo_root, f"{task_dir}/info.md") - if info_content: - context_parts.append( - f"=== {task_dir}/info.md (Technical Design) ===\n{info_content}" - ) - - return "\n\n".join(context_parts) - - -def get_check_context(repo_root: str, task_dir: str) -> str: - """ - Complete context for Check Agent - - Read order: - 1. All files in check.jsonl (check specs + dev specs) - 2. prd.md (for understanding task intent) - """ - context_parts = [] - - # 1. Read check.jsonl (or fallback to spec.jsonl + hardcoded check files) - check_entries = read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl") - - if check_entries: - for file_path, content in check_entries: - context_parts.append(f"=== {file_path} ===\n{content}") - else: - # Fallback: use hardcoded check files + spec.jsonl - check_files = [ - (".claude/commands/trellis/finish-work.md", "Finish work checklist"), - (".claude/commands/trellis/check-cross-layer.md", "Cross-layer check spec"), - (".claude/commands/trellis/check.md", "Code quality check spec"), - ] - for file_path, description in check_files: - content = read_file_content(repo_root, file_path) - if content: - context_parts.append(f"=== {file_path} ({description}) ===\n{content}") - - # Add spec.jsonl - spec_entries = read_jsonl_entries(repo_root, f"{task_dir}/spec.jsonl") - for file_path, content in spec_entries: - context_parts.append(f"=== {file_path} (Dev spec) ===\n{content}") - - # 2. Requirements document (for understanding task intent) - prd_content = read_file_content(repo_root, f"{task_dir}/prd.md") - if prd_content: - context_parts.append( - f"=== {task_dir}/prd.md (Requirements - for understanding intent) ===\n{prd_content}" - ) - - return "\n\n".join(context_parts) - - -def get_finish_context(repo_root: str, task_dir: str) -> str: - """ - Complete context for Finish phase (final check before PR) - - Read order: - 1. All files in finish.jsonl (if exists) - 2. Fallback to finish-work.md only (lightweight final check) - 3. update-spec.md (for active spec sync) - 4. prd.md (for verifying requirements are met) - """ - context_parts = [] - - # 1. Try finish.jsonl first - finish_entries = read_jsonl_entries(repo_root, f"{task_dir}/finish.jsonl") - - if finish_entries: - for file_path, content in finish_entries: - context_parts.append(f"=== {file_path} ===\n{content}") - else: - # Fallback: only finish-work.md (lightweight) - finish_work = read_file_content( - repo_root, ".claude/commands/trellis/finish-work.md" - ) - if finish_work: - context_parts.append( - f"=== .claude/commands/trellis/finish-work.md (Finish checklist) ===\n{finish_work}" - ) - - # 2. Spec update process (for active spec sync) - update_spec = read_file_content( - repo_root, ".claude/commands/trellis/update-spec.md" - ) - if update_spec: - context_parts.append( - f"=== .claude/commands/trellis/update-spec.md (Spec update process) ===\n{update_spec}" - ) - - # 3. Requirements document (for verifying requirements are met) - prd_content = read_file_content(repo_root, f"{task_dir}/prd.md") - if prd_content: - context_parts.append( - f"=== {task_dir}/prd.md (Requirements - verify all met) ===\n{prd_content}" - ) - - return "\n\n".join(context_parts) - - -def get_debug_context(repo_root: str, task_dir: str) -> str: - """ - Complete context for Debug Agent - - Read order: - 1. All files in debug.jsonl (specs needed for fixing) - 2. codex-review-output.txt (Codex Review results) - """ - context_parts = [] - - # 1. Read debug.jsonl (or fallback to spec.jsonl + hardcoded check files) - debug_entries = read_jsonl_entries(repo_root, f"{task_dir}/debug.jsonl") - - if debug_entries: - for file_path, content in debug_entries: - context_parts.append(f"=== {file_path} ===\n{content}") - else: - # Fallback: use spec.jsonl + hardcoded check files - spec_entries = read_jsonl_entries(repo_root, f"{task_dir}/spec.jsonl") - for file_path, content in spec_entries: - context_parts.append(f"=== {file_path} (Dev spec) ===\n{content}") - - check_files = [ - (".claude/commands/trellis/check.md", "Code quality check spec"), - (".claude/commands/trellis/check-cross-layer.md", "Cross-layer check spec"), - ] - for file_path, description in check_files: - content = read_file_content(repo_root, file_path) - if content: - context_parts.append(f"=== {file_path} ({description}) ===\n{content}") - - # 2. Codex review output (if exists) - codex_output = read_file_content(repo_root, f"{task_dir}/codex-review-output.txt") - if codex_output: - context_parts.append( - f"=== {task_dir}/codex-review-output.txt (Codex Review Results) ===\n{codex_output}" - ) - - return "\n\n".join(context_parts) - - -def build_implement_prompt(original_prompt: str, context: str) -> str: - """Build complete prompt for Implement""" - return f"""# Implement Agent Task - -You are the Implement Agent in the Multi-Agent Pipeline. - -## Your Context - -All the information you need has been prepared for you: - -{context} - ---- - -## Your Task - -{original_prompt} - ---- - -## Workflow - -1. **Understand specs** - All dev specs are injected above, understand them -2. **Understand requirements** - Read requirements document and technical design -3. **Implement feature** - Implement following specs and design -4. **Self-check** - Ensure code quality against check specs - -## Important Constraints - -- Do NOT execute git commit, only code modifications -- Follow all dev specs injected above -- Report list of modified/created files when done""" - - -def build_check_prompt(original_prompt: str, context: str) -> str: - """Build complete prompt for Check""" - return f"""# Check Agent Task - -You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker). - -## Your Context - -All check specs and dev specs you need: - -{context} - ---- - -## Your Task - -{original_prompt} - ---- - -## Workflow - -1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes -2. **Check against specs** - Check item by item against specs above -3. **Self-fix** - Fix issues directly, don't just report -4. **Run verification** - Run project's lint and typecheck commands - -## Important Constraints - -- Fix issues yourself, don't just report -- Must execute complete checklist in check specs -- Pay special attention to impact radius analysis (L1-L5)""" - - -def build_finish_prompt(original_prompt: str, context: str) -> str: - """Build complete prompt for Finish (final check before PR)""" - return f"""# Finish Agent Task - -You are performing the final check before creating a PR. - -## Your Context - -Finish checklist and requirements: - -{context} - ---- - -## Your Task - -{original_prompt} - ---- - -## Workflow - -1. **Review changes** - Run `git diff --name-only` to see all changed files -2. **Verify requirements** - Check each requirement in prd.md is implemented -3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions - - If new pattern/convention found: read target spec file → update it → update index.md if needed - - If infra/cross-layer change: follow the 7-section mandatory template from update-spec.md - - If pure code fix with no new patterns: skip this step -4. **Run final checks** - Execute lint and typecheck -5. **Confirm ready** - Ensure code is ready for PR - -## Important Constraints - -- You MAY update spec files when gaps are detected (use update-spec.md as guide) -- MUST read the target spec file BEFORE editing (avoid duplicating existing content) -- Do NOT update specs for trivial changes (typos, formatting, obvious fixes) -- If critical CODE issues found, report them clearly (fix specs, not code) -- Verify all acceptance criteria in prd.md are met""" - - -def build_debug_prompt(original_prompt: str, context: str) -> str: - """Build complete prompt for Debug""" - return f"""# Debug Agent Task - -You are the Debug Agent in the Multi-Agent Pipeline (issue fixer). - -## Your Context - -Dev specs and Codex Review results: - -{context} - ---- - -## Your Task - -{original_prompt} - ---- - -## Workflow - -1. **Understand issues** - Analyze issues pointed out in Codex Review -2. **Locate code** - Find positions that need fixing -3. **Fix against specs** - Fix issues following dev specs -4. **Verify fixes** - Run typecheck to ensure no new issues - -## Important Constraints - -- Do NOT execute git commit, only code modifications -- Run typecheck after each fix to verify -- Report which issues were fixed and which files were modified""" - - -def get_research_context(repo_root: str, task_dir: str | None) -> str: - """ - Context for Research Agent - - Research doesn't need much preset context, only needs: - 1. Project structure overview (where spec directories are) - 2. Optional research.jsonl (if there are specific search needs) - """ - context_parts = [] - - # 1. Project structure overview (dynamically discover spec directories) - spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}" - spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC - - # Build spec tree dynamically - tree_lines = [f"{spec_path}/"] - if spec_root.is_dir(): - pkg_dirs = sorted(d for d in spec_root.iterdir() if d.is_dir()) - for i, pkg_dir in enumerate(pkg_dirs): - is_last = i == len(pkg_dirs) - 1 - prefix = "└── " if is_last else "├── " - layers = sorted(d.name for d in pkg_dir.iterdir() if d.is_dir()) - layer_info = f" ({', '.join(layers)})" if layers else "" - tree_lines.append(f"{prefix}{pkg_dir.name}/{layer_info}") - - spec_tree = "\n".join(tree_lines) - - project_structure = f"""## Project Spec Directory Structure - -``` -{spec_tree} -``` - -To get structured package info, run: `python3 ./{DIR_WORKFLOW}/scripts/get_context.py --mode packages` - -## Search Tips - -- Spec files: `{spec_path}/**/*.md` -- Code search: Use Glob and Grep tools -- Tech solutions: Use mcp__exa__web_search_exa or mcp__exa__get_code_context_exa""" - - context_parts.append(project_structure) - - # 2. If task directory exists, try reading research.jsonl (optional) - if task_dir: - research_entries = read_jsonl_entries(repo_root, f"{task_dir}/research.jsonl") - if research_entries: - context_parts.append( - "\n## Additional Search Context (from research.jsonl)\n" - ) - for file_path, content in research_entries: - context_parts.append(f"=== {file_path} ===\n{content}") - - return "\n\n".join(context_parts) - - -def build_research_prompt(original_prompt: str, context: str) -> str: - """Build complete prompt for Research""" - return f"""# Research Agent Task - -You are the Research Agent in the Multi-Agent Pipeline (search researcher). - -## Core Principle - -**You do one thing: find and explain information.** - -You are a documenter, not a reviewer. - -## Project Info - -{context} - ---- - -## Your Task - -{original_prompt} - ---- - -## Workflow - -1. **Understand query** - Determine search type (internal/external) and scope -2. **Plan search** - List search steps for complex queries -3. **Execute search** - Execute multiple independent searches in parallel -4. **Organize results** - Output structured report - -## Search Tools - -| Tool | Purpose | -|------|---------| -| Glob | Search by filename pattern | -| Grep | Search by content | -| Read | Read file content | -| mcp__exa__web_search_exa | External web search | -| mcp__exa__get_code_context_exa | External code/doc search | - -## Strict Boundaries - -**Only allowed**: Describe what exists, where it is, how it works - -**Forbidden** (unless explicitly asked): -- Suggest improvements -- Criticize implementation -- Recommend refactoring -- Modify any files - -## Report Format - -Provide structured search results including: -- List of files found (with paths) -- Code pattern analysis (if applicable) -- Related spec documents -- External references (if any)""" - - -def main(): - try: - input_data = json.load(sys.stdin) - except json.JSONDecodeError: - sys.exit(0) - - tool_name = input_data.get("tool_name", "") - - if tool_name not in ("Task", "Agent"): - sys.exit(0) - - tool_input = input_data.get("tool_input", {}) - subagent_type = tool_input.get("subagent_type", "") - original_prompt = tool_input.get("prompt", "") - cwd = input_data.get("cwd", os.getcwd()) - - # Only handle subagent types we care about - if subagent_type not in AGENTS_ALL: - sys.exit(0) - - # Find repo root - repo_root = find_repo_root(cwd) - if not repo_root: - sys.exit(0) - - # Get current task directory (research doesn't require it) - task_dir = get_current_task(repo_root) - - # implement/check/debug need task directory - if subagent_type in AGENTS_REQUIRE_TASK: - if not task_dir: - sys.exit(0) - # Check if task directory exists - task_dir_full = os.path.join(repo_root, task_dir) - if not os.path.exists(task_dir_full): - sys.exit(0) - - # Update current_phase in task.json (system-level enforcement) - update_current_phase(repo_root, task_dir, subagent_type) - - # Check for [finish] marker in prompt (check agent with finish context) - is_finish_phase = "[finish]" in original_prompt.lower() - - # Get context and build prompt based on subagent type - if subagent_type == AGENT_IMPLEMENT: - assert task_dir is not None # validated above - context = get_implement_context(repo_root, task_dir) - new_prompt = build_implement_prompt(original_prompt, context) - elif subagent_type == AGENT_CHECK: - assert task_dir is not None # validated above - if is_finish_phase: - # Finish phase: use finish context (lighter, focused on final verification) - context = get_finish_context(repo_root, task_dir) - new_prompt = build_finish_prompt(original_prompt, context) - else: - # Regular check phase: use check context (full specs for self-fix loop) - context = get_check_context(repo_root, task_dir) - new_prompt = build_check_prompt(original_prompt, context) - elif subagent_type == AGENT_DEBUG: - assert task_dir is not None # validated above - context = get_debug_context(repo_root, task_dir) - new_prompt = build_debug_prompt(original_prompt, context) - elif subagent_type == AGENT_RESEARCH: - # Research can work without task directory - context = get_research_context(repo_root, task_dir) - new_prompt = build_research_prompt(original_prompt, context) - else: - sys.exit(0) - - if not context: - sys.exit(0) - - # Return updated input with correct Claude Code PreToolUse format - output = { - "hookSpecificOutput": { - "hookEventName": "PreToolUse", - "permissionDecision": "allow", - "updatedInput": {**tool_input, "prompt": new_prompt}, - } - } - - print(json.dumps(output, ensure_ascii=False)) - sys.exit(0) - - -if __name__ == "__main__": - main() diff --git a/.claude/hooks/ralph-loop.py b/.claude/hooks/ralph-loop.py deleted file mode 100644 index 3f903610..00000000 --- a/.claude/hooks/ralph-loop.py +++ /dev/null @@ -1,396 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -""" -Ralph Loop - SubagentStop Hook for Check Agent Loop Control - -Based on the Ralph Wiggum technique for autonomous agent loops. -Uses completion promises to control when the check agent can stop. - -Mechanism: -- Intercepts when check subagent tries to stop (SubagentStop event) -- If verify commands configured in worktree.yaml, runs them to verify -- Otherwise, reads check.jsonl to get dynamic completion markers ({reason}_FINISH) -- Blocks stopping until verification passes or all markers found -- Has max iterations as safety limit - -State file: .trellis/.ralph-state.json -- Tracks current iteration count per session -- Resets when task changes -""" - -# IMPORTANT: Suppress all warnings FIRST -import warnings -warnings.filterwarnings("ignore") - -import json -import os -import subprocess -import sys -from datetime import datetime -from pathlib import Path - -# IMPORTANT: Force stdout to use UTF-8 on Windows -# This fixes UnicodeEncodeError when outputting non-ASCII characters -if sys.platform == "win32": - import io as _io - if hasattr(sys.stdout, "reconfigure"): - sys.stdout.reconfigure(encoding="utf-8", errors="replace") # type: ignore[union-attr] - elif hasattr(sys.stdout, "detach"): - sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace") # type: ignore[union-attr] - -# ============================================================================= -# Configuration -# ============================================================================= - -MAX_ITERATIONS = 5 # Safety limit to prevent infinite loops -STATE_TIMEOUT_MINUTES = 30 # Reset state if older than this -STATE_FILE = ".trellis/.ralph-state.json" -WORKTREE_YAML = ".trellis/worktree.yaml" -DIR_WORKFLOW = ".trellis" -FILE_CURRENT_TASK = ".current-task" - -# Only control loop for check agent -TARGET_AGENT = "check" - - -def find_repo_root(start_path: str) -> str | None: - """Find git repo root from start_path upwards""" - current = Path(start_path).resolve() - while current != current.parent: - if (current / ".git").exists(): - return str(current) - current = current.parent - return None - - -def get_current_task(repo_root: str) -> str | None: - """Read current task directory path""" - current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK) - if not os.path.exists(current_task_file): - return None - - try: - with open(current_task_file, "r", encoding="utf-8") as f: - content = f.read().strip() - if not content: - return None - normalized = content.replace("\\", "/") - while normalized.startswith("./"): - normalized = normalized[2:] - if normalized.startswith("tasks/"): - normalized = f".trellis/{normalized}" - return normalized - except Exception: - return None - - -def get_verify_commands(repo_root: str) -> list[str]: - """ - Read verify commands from worktree.yaml. - - Returns list of commands to run, or empty list if not configured. - Uses simple YAML parsing without external dependencies. - """ - yaml_path = os.path.join(repo_root, WORKTREE_YAML) - if not os.path.exists(yaml_path): - return [] - - try: - with open(yaml_path, "r", encoding="utf-8") as f: - content = f.read() - - # Simple YAML parsing for verify section - # Look for "verify:" followed by list items - lines = content.split("\n") - in_verify_section = False - commands = [] - - for line in lines: - stripped = line.strip() - - # Check for section start - if stripped.startswith("verify:"): - in_verify_section = True - continue - - # Check for new section (not indented, ends with :) - if ( - not line.startswith(" ") - and not line.startswith("\t") - and stripped.endswith(":") - and stripped != "" - ): - in_verify_section = False - continue - - # If in verify section, look for list items - if in_verify_section: - # Skip comments and empty lines - if stripped.startswith("#") or stripped == "": - continue - # Parse list item (- command) - if stripped.startswith("- "): - cmd = stripped[2:].strip() - if cmd: - commands.append(cmd) - - return commands - except Exception: - return [] - - -def run_verify_commands(repo_root: str, commands: list[str]) -> tuple[bool, str]: - """ - Run verify commands and return (success, message). - - All commands must pass for success. - """ - for cmd in commands: - try: - result = subprocess.run( - cmd, - shell=True, - cwd=repo_root, - capture_output=True, - timeout=120, # 2 minute timeout per command - ) - if result.returncode != 0: - stderr = result.stderr.decode("utf-8", errors="replace") - stdout = result.stdout.decode("utf-8", errors="replace") - error_output = stderr or stdout - # Truncate long output - if len(error_output) > 500: - error_output = error_output[:500] + "..." - return False, f"Command failed: {cmd}\n{error_output}" - except subprocess.TimeoutExpired: - return False, f"Command timed out: {cmd}" - except Exception as e: - return False, f"Command error: {cmd} - {str(e)}" - - return True, "All verify commands passed" - - -def get_completion_markers(repo_root: str, task_dir: str) -> list[str]: - """ - Read check.jsonl and generate completion markers from reasons. - - Each entry's "reason" field becomes {REASON}_FINISH marker. - Example: {"file": "...", "reason": "TypeCheck"} -> "TYPECHECK_FINISH" - """ - check_jsonl_path = os.path.join(repo_root, task_dir, "check.jsonl") - markers = [] - - if not os.path.exists(check_jsonl_path): - # Fallback: if no check.jsonl, use default marker - return ["ALL_CHECKS_FINISH"] - - try: - with open(check_jsonl_path, "r", encoding="utf-8") as f: - for line in f: - line = line.strip() - if not line: - continue - try: - item = json.loads(line) - reason = item.get("reason", "") - if reason: - # Convert to uppercase and add _FINISH suffix - marker = f"{reason.upper().replace(' ', '_')}_FINISH" - if marker not in markers: - markers.append(marker) - except json.JSONDecodeError: - continue - except Exception: - pass - - # If no markers found, use default - if not markers: - markers = ["ALL_CHECKS_FINISH"] - - return markers - - -def load_state(repo_root: str) -> dict: - """Load Ralph Loop state from file""" - state_path = os.path.join(repo_root, STATE_FILE) - if not os.path.exists(state_path): - return {"task": None, "iteration": 0, "started_at": None} - - try: - with open(state_path, "r", encoding="utf-8") as f: - return json.load(f) - except Exception: - return {"task": None, "iteration": 0, "started_at": None} - - -def save_state(repo_root: str, state: dict) -> None: - """Save Ralph Loop state to file""" - state_path = os.path.join(repo_root, STATE_FILE) - try: - # Ensure directory exists - os.makedirs(os.path.dirname(state_path), exist_ok=True) - with open(state_path, "w", encoding="utf-8") as f: - json.dump(state, f, indent=2, ensure_ascii=False) - except Exception: - pass - - -def check_completion(agent_output: str, markers: list[str]) -> tuple[bool, list[str]]: - """ - Check if all completion markers are present in agent output. - - Returns: - (all_complete, missing_markers) - """ - missing = [] - for marker in markers: - if marker not in agent_output: - missing.append(marker) - - return len(missing) == 0, missing - - -def main(): - try: - input_data = json.load(sys.stdin) - except json.JSONDecodeError: - # If can't parse input, allow stop - sys.exit(0) - - # Get event info - hook_event = input_data.get("hook_event_name", "") - - # Only handle SubagentStop event - if hook_event != "SubagentStop": - sys.exit(0) - - # Get subagent info - # Field names per Claude Code SubagentStop event schema: - # agent_type, last_assistant_message, agent_id, agent_transcript_path, cwd - # The event does NOT carry a `prompt` field, so finish-phase detection - # based on a `[finish]` marker in the user prompt is no longer possible - # here; finish-phase skip logic should be reintroduced via task.json - # state (e.g. current_phase) in a follow-up. - agent_type = input_data.get("agent_type", "") - last_assistant_message = input_data.get("last_assistant_message", "") - cwd = input_data.get("cwd", os.getcwd()) - - # Only control check agent - if agent_type != TARGET_AGENT: - sys.exit(0) - - # Find repo root - repo_root = find_repo_root(cwd) - if not repo_root: - sys.exit(0) - - # Get current task - task_dir = get_current_task(repo_root) - if not task_dir: - sys.exit(0) - - # Load state - state = load_state(repo_root) - - # Reset state if task changed or state is too old - should_reset = False - if state.get("task") != task_dir: - should_reset = True - elif state.get("started_at"): - try: - started = datetime.fromisoformat(state["started_at"]) - if (datetime.now() - started).total_seconds() > STATE_TIMEOUT_MINUTES * 60: - should_reset = True - except (ValueError, TypeError): - should_reset = True - - if should_reset: - state = { - "task": task_dir, - "iteration": 0, - "started_at": datetime.now().isoformat(), - } - - # Increment iteration - state["iteration"] = state.get("iteration", 0) + 1 - current_iteration = state["iteration"] - - # Save state - save_state(repo_root, state) - - # Safety check: max iterations - if current_iteration >= MAX_ITERATIONS: - # Allow stop, reset state for next run - state["iteration"] = 0 - save_state(repo_root, state) - output = { - "decision": "allow", - "reason": f"Max iterations ({MAX_ITERATIONS}) reached. Stopping to prevent infinite loop.", - } - print(json.dumps(output, ensure_ascii=False)) - sys.exit(0) - - # Check if verify commands are configured - verify_commands = get_verify_commands(repo_root) - - if verify_commands: - # Use programmatic verification - passed, message = run_verify_commands(repo_root, verify_commands) - - if passed: - # All verify commands passed, allow stop - state["iteration"] = 0 - save_state(repo_root, state) - output = { - "decision": "allow", - "reason": "All verify commands passed. Check phase complete.", - } - print(json.dumps(output, ensure_ascii=False)) - sys.exit(0) - else: - # Verification failed, block stop - output = { - "decision": "block", - "reason": f"Iteration {current_iteration}/{MAX_ITERATIONS}. Verification failed:\n{message}\n\nPlease fix the issues and try again.", - } - print(json.dumps(output, ensure_ascii=False)) - sys.exit(0) - else: - # No verify commands, fall back to completion markers - markers = get_completion_markers(repo_root, task_dir) - all_complete, missing = check_completion(last_assistant_message, markers) - - if all_complete: - # All checks complete, allow stop - state["iteration"] = 0 - save_state(repo_root, state) - output = { - "decision": "allow", - "reason": "All completion markers found. Check phase complete.", - } - print(json.dumps(output, ensure_ascii=False)) - sys.exit(0) - else: - # Missing markers, block stop and continue - output = { - "decision": "block", - "reason": f"""Iteration {current_iteration}/{MAX_ITERATIONS}. Missing completion markers: {", ".join(missing)}. - -IMPORTANT: You must ACTUALLY run the checks, not just output the markers. -- Did you run lint? What was the output? -- Did you run typecheck? What was the output? -- Did they actually pass with zero errors? - -Only output a marker (e.g., LINT_FINISH) AFTER: -1. You have executed the corresponding command -2. The command completed with zero errors -3. You have shown the command output in your response - -Do NOT output markers just to escape the loop. The loop exists to ensure quality.""", - } - print(json.dumps(output, ensure_ascii=False)) - sys.exit(0) - - -if __name__ == "__main__": - main() diff --git a/.claude/hooks/session-start.py b/.claude/hooks/session-start.py deleted file mode 100644 index 37e920df..00000000 --- a/.claude/hooks/session-start.py +++ /dev/null @@ -1,414 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -""" -Session Start Hook - Inject structured context -""" - -# IMPORTANT: Suppress all warnings FIRST -import warnings -warnings.filterwarnings("ignore") - -import json -import os -import subprocess -import sys -from io import StringIO -from pathlib import Path - -# IMPORTANT: Force stdout to use UTF-8 on Windows -# This fixes UnicodeEncodeError when outputting non-ASCII characters -if sys.platform == "win32": - import io as _io - if hasattr(sys.stdout, "reconfigure"): - sys.stdout.reconfigure(encoding="utf-8", errors="replace") # type: ignore[union-attr] - elif hasattr(sys.stdout, "detach"): - sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace") # type: ignore[union-attr] - - -def should_skip_injection() -> bool: - return ( - os.environ.get("CLAUDE_NON_INTERACTIVE") == "1" - or os.environ.get("OPENCODE_NON_INTERACTIVE") == "1" - ) - - -def read_file(path: Path, fallback: str = "") -> str: - try: - return path.read_text(encoding="utf-8") - except (FileNotFoundError, PermissionError): - return fallback - - -def run_script(script_path: Path) -> str: - try: - if script_path.suffix == ".py": - # Add PYTHONIOENCODING to force UTF-8 in subprocess - env = os.environ.copy() - env["PYTHONIOENCODING"] = "utf-8" - cmd = [sys.executable, "-W", "ignore", str(script_path)] - else: - env = os.environ - cmd = [str(script_path)] - - result = subprocess.run( - cmd, - capture_output=True, - text=True, - encoding="utf-8", - errors="replace", - timeout=5, - cwd=script_path.parent.parent.parent, - env=env, - ) - return result.stdout if result.returncode == 0 else "No context available" - except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError): - return "No context available" - - -def _normalize_task_ref(task_ref: str) -> str: - normalized = task_ref.strip() - if not normalized: - return "" - - path_obj = Path(normalized) - if path_obj.is_absolute(): - return str(path_obj) - - normalized = normalized.replace("\\", "/") - while normalized.startswith("./"): - normalized = normalized[2:] - - if normalized.startswith("tasks/"): - return f".trellis/{normalized}" - - return normalized - - -def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path: - normalized = _normalize_task_ref(task_ref) - path_obj = Path(normalized) - if path_obj.is_absolute(): - return path_obj - if normalized.startswith(".trellis/"): - return trellis_dir.parent / path_obj - return trellis_dir / "tasks" / path_obj - - -def _get_task_status(trellis_dir: Path) -> str: - """Check current task status and return structured status string.""" - current_task_file = trellis_dir / ".current-task" - if not current_task_file.is_file(): - return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on" - - task_ref = _normalize_task_ref(current_task_file.read_text(encoding="utf-8").strip()) - if not task_ref: - return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on" - - # Resolve task directory - task_dir = _resolve_task_dir(trellis_dir, task_ref) - if not task_dir.is_dir(): - return f"Status: STALE POINTER\nTask: {task_ref}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish" - - # Read task.json - task_json_path = task_dir / "task.json" - task_data = {} - if task_json_path.is_file(): - try: - task_data = json.loads(task_json_path.read_text(encoding="utf-8")) - except (json.JSONDecodeError, PermissionError): - pass - - task_title = task_data.get("title", task_ref) - task_status = task_data.get("status", "unknown") - - if task_status == "completed": - return f"Status: COMPLETED\nTask: {task_title}\nNext: Archive with `python3 ./.trellis/scripts/task.py archive {task_dir.name}` or start a new task" - - # Check if context is configured (jsonl files exist and non-empty) - has_context = False - for jsonl_name in ("implement.jsonl", "check.jsonl", "spec.jsonl"): - jsonl_path = task_dir / jsonl_name - if jsonl_path.is_file() and jsonl_path.stat().st_size > 0: - has_context = True - break - - has_prd = (task_dir / "prd.md").is_file() - - if not has_prd: - return f"Status: NOT READY\nTask: {task_title}\nMissing: prd.md not created\nNext: Write PRD, then research → init-context → start" - - if not has_context: - return f"Status: NOT READY\nTask: {task_title}\nMissing: Context not configured (no jsonl files)\nNext: Complete Phase 2 (research → init-context → start) before implementing" - - return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check" - - -def _load_trellis_config(trellis_dir: Path) -> tuple: - """Load Trellis config for session-start decisions. - - Returns: - (is_mono, packages_dict, spec_scope, task_pkg, default_pkg) - """ - scripts_dir = trellis_dir / "scripts" - if str(scripts_dir) not in sys.path: - sys.path.insert(0, str(scripts_dir)) - - try: - from common.config import get_default_package, get_packages, get_spec_scope, is_monorepo # type: ignore[import-not-found] - from common.paths import get_current_task # type: ignore[import-not-found] - - repo_root = trellis_dir.parent - is_mono = is_monorepo(repo_root) - packages = get_packages(repo_root) or {} - scope = get_spec_scope(repo_root) - - # Get active task's package - task_pkg = None - current = get_current_task(repo_root) - if current: - task_json = repo_root / current / "task.json" - if task_json.is_file(): - try: - data = json.loads(task_json.read_text(encoding="utf-8")) - if isinstance(data, dict): - tp = data.get("package") - if isinstance(tp, str) and tp: - task_pkg = tp - except (json.JSONDecodeError, OSError): - pass - - default_pkg = get_default_package(repo_root) - return is_mono, packages, scope, task_pkg, default_pkg - except Exception: - return False, {}, None, None, None - - -def _check_legacy_spec(trellis_dir: Path, is_mono: bool, packages: dict) -> str | None: - """Check for legacy spec directory structure in monorepo. - - Returns warning message if legacy structure detected, None otherwise. - """ - if not is_mono or not packages: - return None - - spec_dir = trellis_dir / "spec" - if not spec_dir.is_dir(): - return None - - # Check for legacy flat spec dirs (spec/backend/, spec/frontend/ with index.md) - has_legacy = False - for legacy_name in ("backend", "frontend"): - legacy_dir = spec_dir / legacy_name - if legacy_dir.is_dir() and (legacy_dir / "index.md").is_file(): - has_legacy = True - break - - if not has_legacy: - return None - - # Check which packages are missing spec/<pkg>/ directory - missing = [ - name for name in sorted(packages.keys()) - if not (spec_dir / name).is_dir() - ] - - if not missing: - return None # All packages have spec dirs - - if len(missing) == len(packages): - return ( - f"[!] Legacy spec structure detected: found `spec/backend/` or `spec/frontend/` " - f"but no package-scoped `spec/<package>/` directories.\n" - f"Monorepo packages: {', '.join(sorted(packages.keys()))}\n" - f"Please reorganize: `spec/backend/` -> `spec/<package>/backend/`" - ) - return ( - f"[!] Partial spec migration detected: packages {', '.join(missing)} " - f"still missing `spec/<pkg>/` directory.\n" - f"Please complete migration for all packages." - ) - - -def _resolve_spec_scope( - is_mono: bool, - packages: dict, - scope, - task_pkg: str | None, - default_pkg: str | None, -) -> set | None: - """Resolve which packages should have their specs injected. - - Returns: - Set of package names to include, or None for full scan. - """ - if not is_mono or not packages: - return None # Single-repo: full scan - - if scope is None: - return None # No scope configured: full scan - - if isinstance(scope, str) and scope == "active_task": - if task_pkg and task_pkg in packages: - return {task_pkg} - if default_pkg and default_pkg in packages: - return {default_pkg} - return None # Fallback to full scan - - if isinstance(scope, list): - valid = set() - for entry in scope: - if entry in packages: - valid.add(entry) - else: - print( - f"Warning: spec_scope contains unknown package: {entry}, ignoring", - file=sys.stderr, - ) - - if valid: - # Warn if active task is out of scope - if task_pkg and task_pkg not in valid: - print( - f"Warning: active task package '{task_pkg}' is out of configured spec_scope", - file=sys.stderr, - ) - return valid - - # All entries invalid: fallback chain - print( - "Warning: all spec_scope entries invalid, falling back to task/default/full", - file=sys.stderr, - ) - if task_pkg and task_pkg in packages: - return {task_pkg} - if default_pkg and default_pkg in packages: - return {default_pkg} - return None # Full scan - - return None # Unknown scope type: full scan - - -def _build_workflow_toc(workflow_path: Path) -> str: - """Build a compact section index for workflow.md (lazy-load the full file on demand). - - Replaces full-file injection to keep additionalContext payload small. - The full file is accessible via: Read tool on .trellis/workflow.md - """ - content = read_file(workflow_path) - if not content: - return "No workflow.md found" - - toc_lines = [ - "# Development Workflow — Section Index", - "Full guide: .trellis/workflow.md (read on demand)", - "", - ] - for line in content.splitlines(): - if line.startswith("## "): - toc_lines.append(line) - - toc_lines += [ - "", - "To read a section: use the Read tool on .trellis/workflow.md", - ] - return "\n".join(toc_lines) - - -def main(): - if should_skip_injection(): - sys.exit(0) - - project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", ".")).resolve() - trellis_dir = project_dir / ".trellis" - - # Load config for scope filtering and legacy detection - is_mono, packages, scope_config, task_pkg, default_pkg = _load_trellis_config(trellis_dir) - allowed_pkgs = _resolve_spec_scope(is_mono, packages, scope_config, task_pkg, default_pkg) - - output = StringIO() - - output.write("""<session-context> -You are starting a new session in a Trellis-managed project. -Read and follow all instructions below carefully. -</session-context> - -""") - - # Legacy migration warning - legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages) - if legacy_warning: - output.write(f"<migration-warning>\n{legacy_warning}\n</migration-warning>\n\n") - - output.write("<current-state>\n") - context_script = trellis_dir / "scripts" / "get_context.py" - output.write(run_script(context_script)) - output.write("\n</current-state>\n\n") - - output.write("<workflow>\n") - output.write(_build_workflow_toc(trellis_dir / "workflow.md")) - output.write("\n</workflow>\n\n") - - output.write("<guidelines>\n") - output.write("**Note**: The guidelines below are index files — they list available guideline documents and their locations.\n") - output.write("During actual development, you MUST read the specific guideline files listed in each index's Pre-Development Checklist.\n\n") - - spec_dir = trellis_dir / "spec" - if spec_dir.is_dir(): - for sub in sorted(spec_dir.iterdir()): - if not sub.is_dir() or sub.name.startswith("."): - continue - - # Always include guides/ regardless of scope - if sub.name == "guides": - index_file = sub / "index.md" - if index_file.is_file(): - output.write(f"## {sub.name}\n") - output.write(read_file(index_file)) - output.write("\n\n") - continue - - index_file = sub / "index.md" - if index_file.is_file(): - # Flat spec dir (single-repo layer like spec/backend/) - output.write(f"## {sub.name}\n") - output.write(read_file(index_file)) - output.write("\n\n") - else: - # Nested package dirs (monorepo: spec/<pkg>/<layer>/index.md) - # Apply scope filter - if allowed_pkgs is not None and sub.name not in allowed_pkgs: - continue - for nested in sorted(sub.iterdir()): - if not nested.is_dir(): - continue - nested_index = nested / "index.md" - if nested_index.is_file(): - output.write(f"## {sub.name}/{nested.name}\n") - output.write(read_file(nested_index)) - output.write("\n\n") - - output.write("</guidelines>\n\n") - - # Check task status and inject structured tag - task_status = _get_task_status(trellis_dir) - output.write(f"<task-status>\n{task_status}\n</task-status>\n\n") - - output.write("""<ready> -Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them. -Wait for the user's first message, then handle it following the workflow guide. -If there is an active task, ask whether to continue it. -</ready>""") - - result = { - "hookSpecificOutput": { - "hookEventName": "SessionStart", - "additionalContext": output.getvalue(), - } - } - - # Output JSON - stdout is already configured for UTF-8 - print(json.dumps(result, ensure_ascii=False), flush=True) - - -if __name__ == "__main__": - main() diff --git a/.claude/hooks/statusline.py b/.claude/hooks/statusline.py deleted file mode 100644 index a91ef1ce..00000000 --- a/.claude/hooks/statusline.py +++ /dev/null @@ -1,218 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -""" -Trellis StatusLine — project-level status display for Claude Code. - -Reads Claude Code session JSON from stdin + Trellis task data from filesystem. -Outputs 1-2 lines: - With active task: [P1] Task title (status) + info line - Without task: info line only -Info line: model · ctx% · branch · duration · developer · tasks · rate limits -""" -from __future__ import annotations - -import io -import json -import re -import subprocess -import sys -from pathlib import Path - -# Fix: Windows Python defaults to GBK encoding, which corrupts UTF-8 -# characters like the middle dot (·). Wrap stdout/stderr with UTF-8. -if sys.platform == "win32": - sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8") - sys.stderr = io.TextIOWrapper(sys.stderr.detach(), encoding="utf-8") - - -def _read_text(path: Path) -> str: - try: - return path.read_text(encoding="utf-8").strip() - except (FileNotFoundError, PermissionError, OSError): - return "" - - -def _read_json(path: Path) -> dict: - text = _read_text(path) - if not text: - return {} - try: - return json.loads(text) - except (json.JSONDecodeError, ValueError): - return {} - - -def _normalize_task_ref(task_ref: str) -> str: - normalized = task_ref.strip() - if not normalized: - return "" - - path_obj = Path(normalized) - if path_obj.is_absolute(): - return str(path_obj) - - normalized = normalized.replace("\\", "/") - while normalized.startswith("./"): - normalized = normalized[2:] - - if normalized.startswith("tasks/"): - return f".trellis/{normalized}" - - return normalized - - -def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path: - normalized = _normalize_task_ref(task_ref) - path_obj = Path(normalized) - if path_obj.is_absolute(): - return path_obj - if normalized.startswith(".trellis/"): - return trellis_dir.parent / path_obj - return trellis_dir / "tasks" / path_obj - - -def _find_trellis_dir() -> Path | None: - """Walk up from cwd to find .trellis/ directory.""" - current = Path.cwd() - for parent in [current, *current.parents]: - candidate = parent / ".trellis" - if candidate.is_dir(): - return candidate - return None - - -def _get_current_task(trellis_dir: Path) -> dict | None: - """Load current task info. Returns dict with title/status/priority or None.""" - task_ref = _normalize_task_ref(_read_text(trellis_dir / ".current-task")) - if not task_ref: - return None - - # Resolve task directory - task_path = _resolve_task_dir(trellis_dir, task_ref) - task_data = _read_json(task_path / "task.json") - if not task_data: - return None - - return { - "title": task_data.get("title") or task_data.get("name") or "unknown", - "status": task_data.get("status", "unknown"), - "priority": task_data.get("priority", "P2"), - } - - -def _count_active_tasks(trellis_dir: Path) -> int: - """Count non-archived task directories with valid task.json.""" - tasks_dir = trellis_dir / "tasks" - if not tasks_dir.is_dir(): - return 0 - count = 0 - for d in tasks_dir.iterdir(): - if d.is_dir() and d.name != "archive" and (d / "task.json").is_file(): - count += 1 - return count - - -def _get_developer(trellis_dir: Path) -> str: - content = _read_text(trellis_dir / ".developer") - if not content: - return "unknown" - for line in content.splitlines(): - if line.startswith("name="): - return line[5:].strip() - return content.splitlines()[0].strip() or "unknown" - - -def _get_git_branch() -> str: - try: - result = subprocess.run( - ["git", "branch", "--show-current"], - capture_output=True, text=True, timeout=3, - ) - return result.stdout.strip() if result.returncode == 0 else "" - except (FileNotFoundError, subprocess.TimeoutExpired): - return "" - - -def _format_ctx_size(size: int) -> str: - if size >= 1_000_000: - return f"{size // 1_000_000}M" - if size >= 1_000: - return f"{size // 1_000}K" - return str(size) - - -def _format_duration(ms: int) -> str: - secs = ms // 1000 - hours, remainder = divmod(secs, 3600) - mins = remainder // 60 - if hours > 0: - return f"{hours}h{mins}m" - return f"{mins}m" - - -def main() -> None: - # Read Claude Code session JSON from stdin - try: - cc_data = json.loads(sys.stdin.read()) - except (json.JSONDecodeError, ValueError): - cc_data = {} - - trellis_dir = _find_trellis_dir() - SEP = " \033[90m·\033[0m " - - # --- Trellis data --- - task = _get_current_task(trellis_dir) if trellis_dir else None - dev = _get_developer(trellis_dir) if trellis_dir else "" - task_count = _count_active_tasks(trellis_dir) if trellis_dir else 0 - - # --- CC session data --- - model = cc_data.get("model", {}).get("display_name", "?") - ctx_pct = int(cc_data.get("context_window", {}).get("used_percentage") or 0) - ctx_size = _format_ctx_size(cc_data.get("context_window", {}).get("context_window_size") or 0) - duration = _format_duration(cc_data.get("cost", {}).get("total_duration_ms") or 0) - branch = _get_git_branch() - - # Avoid "Opus 4.6 (1M context) (1M)" - if re.search(r"\d+[KMG]\b", model, re.IGNORECASE): - model_label = model - else: - model_label = f"{model} ({ctx_size})" - - # Context % with color - if ctx_pct >= 90: - ctx_color = "\033[31m" - elif ctx_pct >= 70: - ctx_color = "\033[33m" - else: - ctx_color = "\033[32m" - - # Build info line: model · ctx · branch · duration · dev · tasks [· rate limits] - parts = [ - model_label, - f"ctx {ctx_color}{ctx_pct}%\033[0m", - ] - if branch: - parts.append(f"\033[35m{branch}\033[0m") - parts.append(duration) - if dev: - parts.append(f"\033[32m{dev}\033[0m") - if task_count: - parts.append(f"{task_count} task(s)") - - five_hr = cc_data.get("rate_limits", {}).get("five_hour", {}).get("used_percentage") - if five_hr is not None: - parts.append(f"5h {int(five_hr)}%") - seven_day = cc_data.get("rate_limits", {}).get("seven_day", {}).get("used_percentage") - if seven_day is not None: - parts.append(f"7d {int(seven_day)}%") - - info_line = SEP.join(parts) - - # Output: task line (only if active) + info line - if task: - print(f"\033[36m[{task['priority']}]\033[0m {task['title']} \033[33m({task['status']})\033[0m") - print(info_line) - - -if __name__ == "__main__": - main() diff --git a/.claude/settings.json b/.claude/settings.json deleted file mode 100644 index bfb9031f..00000000 --- a/.claude/settings.json +++ /dev/null @@ -1,77 +0,0 @@ -{ - "hooks": { - "SessionStart": [ - { - "matcher": "startup", - "hooks": [ - { - "type": "command", - "command": "python3 .claude/hooks/session-start.py", - "timeout": 10 - } - ] - }, - { - "matcher": "clear", - "hooks": [ - { - "type": "command", - "command": "python3 .claude/hooks/session-start.py", - "timeout": 10 - } - ] - }, - { - "matcher": "compact", - "hooks": [ - { - "type": "command", - "command": "python3 .claude/hooks/session-start.py", - "timeout": 10 - } - ] - } - ], - "PreToolUse": [ - { - "matcher": "Task", - "hooks": [ - { - "type": "command", - "command": "python3 .claude/hooks/inject-subagent-context.py", - "timeout": 30 - } - ] - }, - { - "matcher": "Agent", - "hooks": [ - { - "type": "command", - "command": "python3 .claude/hooks/inject-subagent-context.py", - "timeout": 30 - } - ] - } - ], - "SubagentStop": [ - { - "matcher": "check", - "hooks": [ - { - "type": "command", - "command": "python3 .claude/hooks/ralph-loop.py", - "timeout": 10 - } - ] - } - ] - }, - "statusLine": { - "type": "command", - "command": "python3 .claude/hooks/statusline.py" - }, - "enabledPlugins": { - "claude-mem@thedotmack": true - } -} diff --git a/.cursor/commands/trellis-before-dev.md b/.cursor/commands/trellis-before-dev.md deleted file mode 100644 index d0807655..00000000 --- a/.cursor/commands/trellis-before-dev.md +++ /dev/null @@ -1,29 +0,0 @@ -Read the relevant development guidelines before starting your task. - -Execute these steps: - -1. **Discover packages and their spec layers**: - ```bash - python3 ./.trellis/scripts/get_context.py --mode packages - ``` - -2. **Identify which specs apply** to your task based on: - - Which package you're modifying (e.g., `cli/`, `docs-site/`) - - What type of work (backend, frontend, unit-test, docs, etc.) - -3. **Read the spec index** for each relevant module: - ```bash - cat .trellis/spec/<package>/<layer>/index.md - ``` - Follow the **"Pre-Development Checklist"** section in the index. - -4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns. - -5. **Always read shared guides**: - ```bash - cat .trellis/spec/guides/index.md - ``` - -6. Understand the coding standards and patterns you need to follow, then proceed with your development plan. - -This step is **mandatory** before writing any code. diff --git a/.cursor/commands/trellis-brainstorm.md b/.cursor/commands/trellis-brainstorm.md deleted file mode 100644 index a09db1a7..00000000 --- a/.cursor/commands/trellis-brainstorm.md +++ /dev/null @@ -1,487 +0,0 @@ -# Brainstorm - Requirements Discovery (AI Coding Enhanced) - -Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows: - -* **Task-first** (capture ideas immediately) -* **Action-before-asking** (reduce low-value questions) -* **Research-first** for technical choices (avoid asking users to invent options) -* **Diverge → Converge** (expand thinking, then lock MVP) - ---- - -## When to Use - -Triggered from `/trellis-start` when the user describes a development task, especially when: - -* requirements are unclear or evolving -* there are multiple valid implementation paths -* trade-offs matter (UX, reliability, maintainability, cost, performance) -* the user might not know the best options up front - ---- - -## Core Principles (Non-negotiable) - -1. **Task-first (capture early)** - Always ensure a task exists at the start so the user's ideas are recorded immediately. - -2. **Action before asking** - If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first. - -3. **One question per message** - Never overwhelm the user with a list of questions. Ask one, update PRD, repeat. - -4. **Prefer concrete options** - For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs. - -5. **Research-first for technical choices** - If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options. - -6. **Diverge → Converge** - After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope. - -7. **No meta questions** - Do not ask "should I search?" or "can you paste the code so I can continue?" - If you need information: search/inspect. If blocked: ask the minimal blocking question. - ---- - -## Step 0: Ensure Task Exists (ALWAYS) - -Before any Q&A, ensure a task exists. If none exists, create one immediately. - -* Use a **temporary working title** derived from the user's message. -* It's OK if the title is imperfect — refine later in PRD. - -```bash -TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>) -``` - -Create/seed `prd.md` immediately with what you know: - -```markdown -# brainstorm: <short goal> - -## Goal - -<one paragraph: what + why> - -## What I already know - -* <facts from user message> -* <facts discovered from repo/docs> - -## Assumptions (temporary) - -* <assumptions to validate> - -## Open Questions - -* <ONLY Blocking / Preference questions; keep list short> - -## Requirements (evolving) - -* <start with what is known> - -## Acceptance Criteria (evolving) - -* [ ] <testable criterion> - -## Definition of Done (team quality bar) - -* Tests added/updated (unit/integration where appropriate) -* Lint / typecheck / CI green -* Docs/notes updated if behavior changes -* Rollout/rollback considered if risky - -## Out of Scope (explicit) - -* <what we will not do in this task> - -## Technical Notes - -* <files inspected, constraints, links, references> -* <research notes summary if applicable> -``` - ---- - -## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS) - -Before asking questions like "what does the code look like?", gather context yourself: - -### Repo inspection checklist - -* Identify likely modules/files impacted -* Locate existing patterns (similar features, conventions, error handling style) -* Check configs, scripts, existing command definitions -* Note any constraints (runtime, dependency policy, build tooling) - -### Documentation checklist - -* Look for existing PRDs/specs/templates -* Look for command usage examples, README, ADRs if any - -Write findings into PRD: - -* Add to `What I already know` -* Add constraints/links to `Technical Notes` - ---- - -## Step 2: Classify Complexity (still useful, not gating task creation) - -| Complexity | Criteria | Action | -| ------------ | ------------------------------------------------------ | ------------------------------------------- | -| **Trivial** | Single-line fix, typo, obvious change | Skip brainstorm, implement directly | -| **Simple** | Clear goal, 1–2 files, scope well-defined | Ask 1 confirm question, then implement | -| **Moderate** | Multiple files, some ambiguity | Light brainstorm (2–3 high-value questions) | -| **Complex** | Vague goal, architectural choices, multiple approaches | Full brainstorm | - -> Note: Task already exists from Step 0. Classification only affects depth of brainstorming. - ---- - -## Step 3: Question Gate (Ask ONLY high-value questions) - -Before asking ANY question, run the following gate: - -### Gate A — Can I derive this without the user? - -If answer is available via: - -* repo inspection (code/config) -* docs/specs/conventions -* quick market/OSS research - -→ **Do not ask.** Fetch it, summarize, update PRD. - -### Gate B — Is this a meta/lazy question? - -Examples: - -* "Should I search?" -* "Can you paste the code so I can proceed?" -* "What does the code look like?" (when repo is available) - -→ **Do not ask.** Take action. - -### Gate C — What type of question is it? - -* **Blocking**: cannot proceed without user input -* **Preference**: multiple valid choices, depends on product/UX/risk preference -* **Derivable**: should be answered by inspection/research - -→ Only ask **Blocking** or **Preference**. - ---- - -## Step 4: Research-first Mode (Mandatory for technical choices) - -### Trigger conditions (any → research-first) - -* The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention -* The user asks for "best practice", "how others do it", "recommendation" -* The user can't reasonably enumerate options - -### Research steps - -1. Identify 2–4 comparable tools/patterns -2. Summarize common conventions and why they exist -3. Map conventions onto our repo constraints -4. Produce **2–3 feasible approaches** for our project - -### Research output format (PRD) - -Add a section in PRD (either within Technical Notes or as its own): - -```markdown -## Research Notes - -### What similar tools do - -* ... -* ... - -### Constraints from our repo/project - -* ... - -### Feasible approaches here - -**Approach A: <name>** (Recommended) - -* How it works: -* Pros: -* Cons: - -**Approach B: <name>** - -* How it works: -* Pros: -* Cons: - -**Approach C: <name>** (optional) - -* ... -``` - -Then ask **one** preference question: - -* "Which approach do you prefer: A / B / C (or other)?" - ---- - -## Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding - -After you can summarize the goal, proactively broaden thinking before converging. - -### Expansion categories (keep to 1–2 bullets each) - -1. **Future evolution** - - * What might this feature become in 1–3 months? - * What extension points are worth preserving now? - -2. **Related scenarios** - - * What adjacent commands/flows should remain consistent with this? - * Are there parity expectations (create vs update, import vs export, etc.)? - -3. **Failure & edge cases** - - * Conflicts, offline/network failure, retries, idempotency, compatibility, rollback - * Input validation, security boundaries, permission checks - -### Expansion message template (to user) - -```markdown -I understand you want to implement: <current goal>. - -Before diving into design, let me quickly diverge to consider three categories (to avoid rework later): - -1. Future evolution: <1–2 bullets> -2. Related scenarios: <1–2 bullets> -3. Failure/edge cases: <1–2 bullets> - -For this MVP, which would you like to include (or none)? - -1. Current requirement only (minimal viable) -2. Add <X> (reserve for future extension) -3. Add <Y> (improve robustness/consistency) -4. Other: describe your preference -``` - -Then update PRD: - -* What's in MVP → `Requirements` -* What's excluded → `Out of Scope` - ---- - -## Step 6: Q&A Loop (CONVERGE) - -### Rules - -* One question per message -* Prefer multiple-choice when possible -* After each user answer: - - * Update PRD immediately - * Move answered items from `Open Questions` → `Requirements` - * Update `Acceptance Criteria` with testable checkboxes - * Clarify `Out of Scope` - -### Question priority (recommended) - -1. **MVP scope boundary** (what is included/excluded) -2. **Preference decisions** (after presenting concrete options) -3. **Failure/edge behavior** (only for MVP-critical paths) -4. **Success metrics & Acceptance Criteria** (what proves it works) - -### Preferred question format (multiple choice) - -```markdown -For <topic>, which approach do you prefer? - -1. **Option A** — <what it means + trade-off> -2. **Option B** — <what it means + trade-off> -3. **Option C** — <what it means + trade-off> -4. **Other** — describe your preference -``` - ---- - -## Step 7: Propose Approaches + Record Decisions (Complex tasks) - -After requirements are clear enough, propose 2–3 approaches (if not already done via research-first): - -```markdown -Based on current information, here are 2–3 feasible approaches: - -**Approach A: <name>** (Recommended) - -* How: -* Pros: -* Cons: - -**Approach B: <name>** - -* How: -* Pros: -* Cons: - -Which direction do you prefer? -``` - -Record the outcome in PRD as an ADR-lite section: - -```markdown -## Decision (ADR-lite) - -**Context**: Why this decision was needed -**Decision**: Which approach was chosen -**Consequences**: Trade-offs, risks, potential future improvements -``` - ---- - -## Step 8: Final Confirmation + Implementation Plan - -When open questions are resolved, confirm complete requirements with a structured summary: - -### Final confirmation format - -```markdown -Here's my understanding of the complete requirements: - -**Goal**: <one sentence> - -**Requirements**: - -* ... -* ... - -**Acceptance Criteria**: - -* [ ] ... -* [ ] ... - -**Definition of Done**: - -* ... - -**Out of Scope**: - -* ... - -**Technical Approach**: -<brief summary + key decisions> - -**Implementation Plan (small PRs)**: - -* PR1: <scaffolding + tests + minimal plumbing> -* PR2: <core behavior> -* PR3: <edge cases + docs + cleanup> - -Does this look correct? If yes, I'll proceed with implementation. -``` - -### Subtask Decomposition (Complex Tasks) - -For complex tasks with multiple independent work items, create subtasks: - -```bash -# Create child tasks -CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR") -CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR") - -# Or link existing tasks -python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR" -``` - ---- - -## PRD Target Structure (final) - -`prd.md` should converge to: - -```markdown -# <Task Title> - -## Goal - -<why + what> - -## Requirements - -* ... - -## Acceptance Criteria - -* [ ] ... - -## Definition of Done - -* ... - -## Technical Approach - -<key design + decisions> - -## Decision (ADR-lite) - -Context / Decision / Consequences - -## Out of Scope - -* ... - -## Technical Notes - -<constraints, references, files, research notes> -``` - ---- - -## Anti-Patterns (Hard Avoid) - -* Asking user for code/context that can be derived from repo -* Asking user to choose an approach before presenting concrete options -* Meta questions about whether to research -* Staying narrowly on the initial request without considering evolution/edges -* Letting brainstorming drift without updating PRD - ---- - -## Integration with Start Workflow - -After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**: - -```text -Brainstorm - Step 0: Create task directory + seed PRD - Step 1–7: Discover requirements, research, converge - Step 8: Final confirmation → user approves - ↓ -Task Workflow Phase 2 (Prepare for Implementation) - Code-Spec Depth Check (if applicable) - → Research codebase (based on confirmed PRD) - → Configure code-spec context (jsonl files) - → Activate task - ↓ -Task Workflow Phase 3 (Execute) - Implement → Check → Complete -``` - -The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely. - ---- - -## Related Commands - -| Command | When to Use | -|---------|-------------| -| `/trellis-start` | Entry point that triggers brainstorm | -| `/trellis-finish-work` | After implementation is complete | -| `/trellis-update-spec` | If new patterns emerge during work | diff --git a/.cursor/commands/trellis-break-loop.md b/.cursor/commands/trellis-break-loop.md deleted file mode 100644 index e09824f1..00000000 --- a/.cursor/commands/trellis-break-loop.md +++ /dev/null @@ -1,107 +0,0 @@ -# Break the Loop - Deep Bug Analysis - -When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle. - ---- - -## Analysis Framework - -Analyze the bug you just fixed from these 5 dimensions: - -### 1. Root Cause Category - -Which category does this bug belong to? - -| Category | Characteristics | Example | -|----------|-----------------|---------| -| **A. Missing Spec** | No documentation on how to do it | New feature without checklist | -| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected | -| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites | -| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined | -| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds | - -### 2. Why Fixes Failed (if applicable) - -If you tried multiple fixes before succeeding, analyze each failure: - -- **Surface Fix**: Fixed symptom, not root cause -- **Incomplete Scope**: Found root cause, didn't cover all cases -- **Tool Limitation**: grep missed it, type check wasn't strict -- **Mental Model**: Kept looking in same layer, didn't think cross-layer - -### 3. Prevention Mechanisms - -What mechanisms would prevent this from happening again? - -| Type | Description | Example | -|------|-------------|---------| -| **Documentation** | Write it down so people know | Update thinking guide | -| **Architecture** | Make the error impossible structurally | Type-safe wrappers | -| **Compile-time** | TypeScript strict, no any | Signature change causes compile error | -| **Runtime** | Monitoring, alerts, scans | Detect orphan entities | -| **Test Coverage** | E2E tests, integration tests | Verify full flow | -| **Code Review** | Checklist, PR template | "Did you check X?" | - -### 4. Systematic Expansion - -What broader problems does this bug reveal? - -- **Similar Issues**: Where else might this problem exist? -- **Design Flaw**: Is there a fundamental architecture issue? -- **Process Flaw**: Is there a development process improvement? -- **Knowledge Gap**: Is the team missing some understanding? - -### 5. Knowledge Capture - -Solidify insights into the system: - -- [ ] Update `.trellis/spec/guides/` thinking guides -- [ ] Update `.trellis/spec/backend/` or `frontend/` docs -- [ ] Create issue record (if applicable) -- [ ] Create feature ticket for root fix -- [ ] Update check commands if needed - ---- - -## Output Format - -Please output analysis in this format: - -```markdown -## Bug Analysis: [Short Description] - -### 1. Root Cause Category -- **Category**: [A/B/C/D/E] - [Category Name] -- **Specific Cause**: [Detailed description] - -### 2. Why Fixes Failed (if applicable) -1. [First attempt]: [Why it failed] -2. [Second attempt]: [Why it failed] -... - -### 3. Prevention Mechanisms -| Priority | Mechanism | Specific Action | Status | -|----------|-----------|-----------------|--------| -| P0 | ... | ... | TODO/DONE | - -### 4. Systematic Expansion -- **Similar Issues**: [List places with similar problems] -- **Design Improvement**: [Architecture-level suggestions] -- **Process Improvement**: [Development process suggestions] - -### 5. Knowledge Capture -- [ ] [Documents to update / tickets to create] -``` - ---- - -## Core Philosophy - -> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.** - -Three levels of insight: -1. **Tactical**: How to fix THIS bug -2. **Strategic**: How to prevent THIS CLASS of bugs -3. **Philosophical**: How to expand thinking patterns - -30 minutes of analysis saves 30 hours of future debugging. diff --git a/.cursor/commands/trellis-check-cross-layer.md b/.cursor/commands/trellis-check-cross-layer.md deleted file mode 100644 index bc61e28e..00000000 --- a/.cursor/commands/trellis-check-cross-layer.md +++ /dev/null @@ -1,153 +0,0 @@ -# Cross-Layer Check - -Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill. - -> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code. - ---- - -## Related Documents - -| Document | Purpose | Timing | -|----------|---------|--------| -| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code | -| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation | -| **`/trellis-check-cross-layer`** (this) | Verification check | **After** implementation | - ---- - -## Execution Steps - -### 1. Identify Change Scope - -```bash -git status -git diff --name-only -``` - -### 2. Select Applicable Check Dimensions - -Based on your change type, execute relevant checks below: - ---- - -## Dimension A: Cross-Layer Data Flow (Required when 3+ layers) - -**Trigger**: Changes involve 3 or more layers - -| Layer | Common Locations | -|-------|------------------| -| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` | -| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` | -| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` | -| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` | -| Utility | `utils/`, `helpers/`, `common/` | - -**Checklist**: -- [ ] Read flow: Database -> Service -> API -> UI -- [ ] Write flow: UI -> API -> Service -> Database -- [ ] Types/schemas correctly passed between layers? -- [ ] Errors properly propagated to caller? -- [ ] Loading/pending states handled at each layer? - -**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md` - ---- - -## Dimension B: Code Reuse (Required when modifying constants/config) - -**Trigger**: -- Modifying UI constants (label, icon, color) -- Modifying any hardcoded value -- Seeing similar code in multiple places -- Creating a new utility/helper function -- Just finished batch modifications across files - -**Checklist**: -- [ ] Search first: How many places define this value? - ```bash - # Search in source files (adjust extensions for your project) - grep -r "value-to-change" src/ - ``` -- [ ] If 2+ places define same value -> Should extract to shared constant -- [ ] After modification, all usage sites updated? -- [ ] If creating utility: Does similar utility already exist? - -**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md` - ---- - -## Dimension B2: New Utility Functions - -**Trigger**: About to create a new utility/helper function - -**Checklist**: -- [ ] Search for existing similar utilities first - ```bash - grep -r "functionNamePattern" src/ - ``` -- [ ] If similar exists, can you extend it instead? -- [ ] If creating new, is it in the right location (shared vs domain-specific)? - ---- - -## Dimension B3: After Batch Modifications - -**Trigger**: Just modified similar patterns in multiple files - -**Checklist**: -- [ ] Did you check ALL files with similar patterns? - ```bash - grep -r "patternYouChanged" src/ - ``` -- [ ] Any files missed that should also be updated? -- [ ] Should this pattern be abstracted to prevent future duplication? - ---- - -## Dimension C: Import/Dependency Paths (Required when creating new files) - -**Trigger**: Creating new source files - -**Checklist**: -- [ ] Using correct import paths (relative vs absolute)? -- [ ] No circular dependencies? -- [ ] Consistent with project's module organization? - ---- - -## Dimension D: Same-Layer Consistency - -**Trigger**: -- Modifying display logic or formatting -- Same domain concept used in multiple places - -**Checklist**: -- [ ] Search for other places using same concept - ```bash - grep -r "ConceptName" src/ - ``` -- [ ] Are these usages consistent? -- [ ] Should they share configuration/constants? - ---- - -## Common Issues Quick Reference - -| Issue | Root Cause | Prevention | -|-------|------------|------------| -| Changed one place, missed others | Didn't search impact scope | `grep` before changing | -| Data lost at some layer | Didn't check data flow | Trace data source to destination | -| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions | -| UI/output inconsistent | Same concept in multiple places | Extract shared constants | -| Similar utility exists | Didn't search first | Search before creating | -| Batch fix incomplete | Didn't verify all occurrences | grep after fixing | - ---- - -## Output - -Report: -1. Which dimensions your changes involve -2. Check results for each dimension -3. Issues found and fix suggestions diff --git a/.cursor/commands/trellis-check.md b/.cursor/commands/trellis-check.md deleted file mode 100644 index 8e3e272e..00000000 --- a/.cursor/commands/trellis-check.md +++ /dev/null @@ -1,25 +0,0 @@ -Check if the code you just wrote follows the development guidelines. - -Execute these steps: - -1. **Identify changed files**: - ```bash - git diff --name-only HEAD - ``` - -2. **Determine which spec modules apply** based on the changed file paths: - ```bash - python3 ./.trellis/scripts/get_context.py --mode packages - ``` - -3. **Read the spec index** for each relevant module: - ```bash - cat .trellis/spec/<package>/<layer>/index.md - ``` - Follow the **"Quality Check"** section in the index. - -4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them. - -5. **Run lint and typecheck** for the affected package. - -6. **Report any violations** and fix them if found. diff --git a/.cursor/commands/trellis-create-command.md b/.cursor/commands/trellis-create-command.md deleted file mode 100644 index 9e7bbfbf..00000000 --- a/.cursor/commands/trellis-create-command.md +++ /dev/null @@ -1,154 +0,0 @@ -# Create New Slash Command - -Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories based on user requirements. - -## Usage - -``` -/trellis-create-command <command-name> <description> -``` - -**Example**: -``` -/trellis-create-command review-pr Check PR code changes against project guidelines -``` - -## Execution Steps - -### 1. Parse Input - -Extract from user input: -- **Command name**: Use kebab-case (e.g., `review-pr`) -- **Description**: What the command should accomplish - -### 2. Analyze Requirements - -Determine command type based on description: -- **Initialization**: Read docs, establish context -- **Pre-development**: Read guidelines, check dependencies -- **Code check**: Validate code quality and guideline compliance -- **Recording**: Record progress, questions, structure changes -- **Generation**: Generate docs, code templates - -### 3. Generate Command Content - -Based on command type, generate appropriate content: - -**Simple command** (1-3 lines): -```markdown -Concise instruction describing what to do -``` - -**Complex command** (with steps): -```markdown -# Command Title - -Command description - -## Steps - -### 1. First Step -Specific action - -### 2. Second Step -Specific action - -## Output Format (if needed) - -Template -``` - -### 4. Create Files - -Create in both directories: -- `.cursor/commands/trellis-<command-name>.md` -- `.claude/commands/trellis/<command-name>.md` - -### 5. Confirm Creation - -Output result: -``` -[OK] Created Slash Command: /<command-name> - -File paths: -- .cursor/commands/trellis-<command-name>.md -- .claude/commands/trellis/<command-name>.md - -Usage: -/trellis-<command-name> - -Description: -<description> -``` - -## Command Content Guidelines - -### [OK] Good command content - -1. **Clear and concise**: Immediately understandable -2. **Executable**: AI can follow steps directly -3. **Well-scoped**: Clear boundaries of what to do and not do -4. **Has output**: Specifies expected output format (if needed) - -### [X] Avoid - -1. **Too vague**: e.g., "optimize code" -2. **Too complex**: Single command should not exceed 100 lines -3. **Duplicate functionality**: Check if similar command exists first - -## Naming Conventions - -| Command Type | Prefix | Example | -|--------------|--------|---------| -| Session Start | `start` | `start` | -| Pre-development | `before-` | `before-dev` | -| Check | `check-` | `check` | -| Record | `record-` | `record-session` | -| Generate | `generate-` | `generate-api-doc` | -| Update | `update-` | `update-changelog` | -| Other | Verb-first | `review-code`, `sync-data` | - -## Example - -### Input -``` -/trellis-create-command review-pr Check PR code changes against project guidelines -``` - -### Generated Command Content -```markdown -# PR Code Review - -Check current PR code changes against project guidelines. - -## Steps - -### 1. Get Changed Files -```bash -git diff main...HEAD --name-only -``` - -### 2. Categorized Review - -**Frontend files** (`apps/web/`): -- Reference `.trellis/spec/frontend/index.md` - -**Backend files** (`packages/api/`): -- Reference `.trellis/spec/backend/index.md` - -### 3. Output Review Report - -Format: - -## PR Review Report - -### Changed Files -- [file list] - -### Check Results -- [OK] Passed items -- [X] Issues found - -### Suggestions -- [improvement suggestions] -``` diff --git a/.cursor/commands/trellis-finish-work.md b/.cursor/commands/trellis-finish-work.md deleted file mode 100644 index d8df83be..00000000 --- a/.cursor/commands/trellis-finish-work.md +++ /dev/null @@ -1,143 +0,0 @@ -# Finish Work - Pre-Commit Checklist - -Before submitting or committing, use this checklist to ensure work completeness. - -**Timing**: After code is written and tested, before commit - ---- - -## Checklist - -### 1. Code Quality - -```bash -# Must pass -pnpm lint -pnpm type-check -pnpm test -``` - -- [ ] `pnpm lint` passes with 0 errors? -- [ ] `pnpm type-check` passes with no type errors? -- [ ] Tests pass? -- [ ] No `console.log` statements (use logger)? -- [ ] No non-null assertions (the `x!` operator)? -- [ ] No `any` types? - -### 2. Code-Spec Sync - -**Code-Spec Docs**: -- [ ] Does `.trellis/spec/backend/` need updates? - - New patterns, new modules, new conventions -- [ ] Does `.trellis/spec/frontend/` need updates? - - New components, new hooks, new patterns -- [ ] Does `.trellis/spec/guides/` need updates? - - New cross-layer flows, lessons from bugs - -**Key Question**: -> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?" - -If YES -> Update the relevant code-spec doc. - -### 2.5. Code-Spec Hard Block (Infra/Cross-Layer) - -If this change touches infra or cross-layer contracts, this is a blocking checklist: - -- [ ] Spec content is executable (real signatures/contracts), not principle-only text -- [ ] Includes file path + command/API name + payload field names -- [ ] Includes validation and error matrix -- [ ] Includes Good/Base/Bad cases -- [ ] Includes required tests and assertion points - -**Block Rule**: -If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `/trellis-update-spec` manually first. - -### 3. API Changes - -If you modified API endpoints: - -- [ ] Input schema updated? -- [ ] Output schema updated? -- [ ] API documentation updated? -- [ ] Client code updated to match? - -### 4. Database Changes - -If you modified database schema: - -- [ ] Migration file created? -- [ ] Schema file updated? -- [ ] Related queries updated? -- [ ] Seed data updated (if applicable)? - -### 5. Cross-Layer Verification - -If the change spans multiple layers: - -- [ ] Data flows correctly through all layers? -- [ ] Error handling works at each boundary? -- [ ] Types are consistent across layers? -- [ ] Loading states handled? - -### 6. Manual Testing - -- [ ] Feature works in browser/app? -- [ ] Edge cases tested? -- [ ] Error states tested? -- [ ] Works after page refresh? - ---- - -## Quick Check Flow - -```bash -# 1. Code checks -pnpm lint && pnpm type-check - -# 2. View changes -git status -git diff --name-only - -# 3. Based on changed files, check relevant items above -``` - ---- - -## Common Oversights - -| Oversight | Consequence | Check | -|-----------|-------------|-------| -| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ | -| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests | -| Migration not created | Schema out of sync | Check db/migrations/ | -| Types not synced | Runtime errors | Check shared types | -| Tests not updated | False confidence | Run full test suite | -| Console.log left in | Noisy production logs | Search for console.log | - ---- - -## Relationship to Other Commands - -``` -Development Flow: - Write code -> Test -> /trellis-finish-work -> git commit -> /trellis-record-session - | | - Ensure completeness Record progress - -Debug Flow: - Hit bug -> Fix -> /trellis-break-loop -> Knowledge capture - | - Deep analysis -``` - -- `/trellis-finish-work` - Check work completeness (this command) -- `/trellis-record-session` - Record session and commits -- `/trellis-break-loop` - Deep analysis after debugging - ---- - -## Core Principle - -> **Delivery includes not just code, but also documentation, verification, and knowledge capture.** - -Complete work = Code + Docs + Tests + Verification diff --git a/.cursor/commands/trellis-integrate-skill.md b/.cursor/commands/trellis-integrate-skill.md deleted file mode 100644 index d3936ad0..00000000 --- a/.cursor/commands/trellis-integrate-skill.md +++ /dev/null @@ -1,219 +0,0 @@ -# Integrate Claude Skill into Project Guidelines - -Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code). - -## Usage - -``` -/trellis-integrate-skill <skill-name> -``` - -**Examples**: -``` -/trellis-integrate-skill frontend-design -/trellis-integrate-skill mcp-builder -``` - -## Core Principle - -> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly. -> -> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md` -> - Code examples -> Place in `.trellis/spec/{target}/examples/skills/<skill-name>/` -> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors -> -> Where `{target}` is `frontend` or `backend`, determined by skill type. - -## Execution Steps - -### 1. Read Skill Content - -```bash -openskills read <skill-name> -``` - -If the skill doesn't exist, prompt user to check available skills: -```bash -# Available skills are listed in AGENTS.md under <available_skills> -``` - -### 2. Determine Integration Target - -Based on skill type, determine which guidelines to update: - -| Skill Category | Integration Target | -|----------------|-------------------| -| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` | -| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` | -| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines | -| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) | - -### 3. Analyze Skill Content - -Extract from the skill: -- **Core concepts**: How the skill works and key concepts -- **Best practices**: Recommended approaches -- **Code patterns**: Reusable code templates -- **Caveats**: Common issues and solutions - -### 4. Execute Integration - -#### 4.1 Update Guidelines Document - -Add a new section to the corresponding `doc.md`: - -```markdown -@@@section:skill-<skill-name> -## # <Skill Name> Integration Guide - -### Overview -[Core functionality and use cases of the skill] - -### Project Adaptation -[How to use this skill in the current project] - -### Usage Steps -1. [Step 1] -2. [Step 2] - -### Caveats -- [Project-specific constraints] -- [Differences from default behavior] - -### Reference Examples -See `examples/skills/<skill-name>/` - -@@@/section:skill-<skill-name> -``` - -#### 4.2 Create Examples Directory (if code examples exist) - -```bash -# Directory structure ({target} = frontend or backend) -.trellis/spec/{target}/ -|-- doc.md # Add skill-related section -|-- index.md # Update index -+-- examples/ - +-- skills/ - +-- <skill-name>/ - |-- README.md # Example documentation - |-- example-1.ts.template # Code example (use .template suffix) - +-- example-2.tsx.template -``` - -**File naming conventions**: -- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`) -- Config files: `<name>.config.template` (e.g., `tailwind.config.template`) -- Documentation: `README.md` (normal suffix) - -#### 4.3 Update Index File - -Add to the Quick Navigation table in `index.md`: - -```markdown -| <Skill-related task> | <Section name> | `skill-<skill-name>` | -``` - -### 5. Generate Integration Report - ---- - -## Skill Integration Report: `<skill-name>` - -### # Overview -- **Skill description**: [Functionality description] -- **Integration target**: `.trellis/spec/{target}/` - -### # Tech Stack Compatibility - -| Skill Requirement | Project Status | Compatibility | -|-------------------|----------------|---------------| -| [Tech 1] | [Project tech] | [OK]/[!]/[X] | - -### # Integration Locations - -| Type | Path | -|------|------| -| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-<name>`) | -| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` | -| Index update | `.trellis/spec/{target}/index.md` | - -> `{target}` = `frontend` or `backend` - -### # Dependencies (if needed) - -```bash -# Install required dependencies (adjust for your package manager) -npm install <package> -# or -pnpm add <package> -# or -yarn add <package> -``` - -### [OK] Completed Changes - -- [ ] Added `@@@section:skill-<name>` section to `doc.md` -- [ ] Added index entry to `index.md` -- [ ] Created example files in `examples/skills/<name>/` -- [ ] Example files use `.template` suffix - -### # Related Guidelines - -- [Existing related section IDs] - ---- - -## 6. Optional: Create Usage Command - -If this skill is frequently used, create a shortcut command: - -```bash -/trellis-create-command use-<skill-name> Use <skill-name> skill following project guidelines -``` - -## Common Skill Integration Reference - -| Skill | Integration Target | Examples Directory | -|-------|-------------------|-------------------| -| `frontend-design` | `frontend` | `examples/skills/frontend-design/` | -| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` | -| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` | -| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) | - -## Example: Integrating `mcp-builder` Skill - -### Directory Structure - -``` -.trellis/spec/backend/ -|-- doc.md # Add MCP section -|-- index.md # Add index entry -+-- examples/ - +-- skills/ - +-- mcp-builder/ - |-- README.md - |-- server.ts.template - |-- tools.ts.template - +-- types.ts.template -``` - -### New Section in doc.md - -```markdown -@@@section:skill-mcp-builder -## # MCP Server Development Guide - -### Overview -Create LLM-callable tool services using MCP (Model Context Protocol). - -### Project Adaptation -- Place services in a dedicated directory -- Follow existing TypeScript and type definition conventions -- Use project's logging system - -### Reference Examples -See `examples/skills/mcp-builder/` - -@@@/section:skill-mcp-builder -``` diff --git a/.cursor/commands/trellis-onboard.md b/.cursor/commands/trellis-onboard.md deleted file mode 100644 index 206c1260..00000000 --- a/.cursor/commands/trellis-onboard.md +++ /dev/null @@ -1,358 +0,0 @@ -You are a senior developer onboarding a new team member to this project's AI-assisted workflow system. - -YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each command exists, what problem it solves at a fundamental level. - -## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS - -This onboarding has THREE equally important parts: - -**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE) -- Explain WHY this workflow exists -- Explain WHAT each command does and WHY - -**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES) -- Walk through ALL 5 examples in detail -- For EACH step in EACH example, explain: - - PRINCIPLE: Why this step exists - - WHAT HAPPENS: What the command actually does - - IF SKIPPED: What goes wrong without it - -**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES) -- Check if project guidelines are still empty templates -- If empty, guide the developer to fill them with project-specific content -- Explain the customization workflow - -DO NOT skip any part. All three parts are essential: -- Part 1 teaches the concepts -- Part 2 shows how concepts work in practice -- Part 3 ensures the project has proper guidelines for AI to follow - -After completing ALL THREE parts, ask the developer about their first task. - ---- - -## CORE PHILOSOPHY: Why This Workflow Exists - -AI-assisted development has three fundamental challenges: - -### Challenge 1: AI Has No Memory - -Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends. - -**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work. - -**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/trellis-start` command reads this history at session start, giving AI "artificial memory." - -### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge - -AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions. - -**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules. - -**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts. - -### Challenge 3: AI Context Window Is Limited - -Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential. - -**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns. - -**The Solution**: The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis-finish-work` command does a final holistic review. - ---- - -## SYSTEM STRUCTURE - -``` -.trellis/ -|-- .developer # Your identity (gitignored) -|-- workflow.md # Complete workflow documentation -|-- workspace/ # "AI Memory" - session history -| |-- index.md # All developers' progress -| +-- {developer}/ # Per-developer directory -| |-- index.md # Personal progress index -| +-- journal-N.md # Session records (max 2000 lines) -|-- tasks/ # Task tracking (unified) -| +-- {MM}-{DD}-{slug}/ # Task directory -| |-- task.json # Task metadata -| +-- prd.md # Requirements doc -|-- spec/ # "AI Training Data" - project knowledge -| |-- frontend/ # Frontend conventions -| |-- backend/ # Backend conventions -| +-- guides/ # Thinking patterns -+-- scripts/ # Automation tools -``` - -### Understanding spec/ subdirectories - -**frontend/** - Single-layer frontend knowledge: -- Component patterns (how to write components in THIS project) -- State management rules (Redux? Zustand? Context?) -- Styling conventions (CSS modules? Tailwind? Styled-components?) -- Hook patterns (custom hooks, data fetching) - -**backend/** - Single-layer backend knowledge: -- API design patterns (REST? GraphQL? tRPC?) -- Database conventions (query patterns, migrations) -- Error handling standards -- Logging and monitoring rules - -**guides/** - Cross-layer thinking guides: -- Code reuse thinking guide -- Cross-layer thinking guide -- Pre-implementation checklists - ---- - -## COMMAND DEEP DIVE - -### /trellis-start - Restore AI Memory - -**WHY IT EXISTS**: -When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state? - -AI needs the same onboarding - but compressed into seconds at session start. - -**WHAT IT ACTUALLY DOES**: -1. Reads developer identity (who am I in this project?) -2. Checks git status (what branch? uncommitted changes?) -3. Reads recent session history from `workspace/` (what happened before?) -4. Identifies active features (what's in progress?) -5. Understands current project state before making any changes - -**WHY THIS MATTERS**: -- Without /trellis-start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work. -- With /trellis-start: AI knows project context, can continue where previous session left off, avoids conflicts. - ---- - -### /trellis-before-dev - Inject Specialized Knowledge - -**WHY IT EXISTS**: -AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns. - -**WHAT IT ACTUALLY DOES**: -1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines -2. Loads project-specific patterns into AI's working context: - - Component naming conventions - - State management patterns - - Database query patterns - - Error handling standards - -**WHY THIS MATTERS**: -- Without before-dev: AI writes generic code that doesn't match project style. -- With before-dev: AI writes code that looks like the rest of the codebase. - ---- - -### /trellis-check - Combat Context Drift - -**WHY IT EXISTS**: -AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift." - -**WHAT IT ACTUALLY DOES**: -1. Re-reads the guidelines that were injected earlier -2. Compares written code against those guidelines -3. Runs type checker and linter -4. Identifies violations and suggests fixes - -**WHY THIS MATTERS**: -- Without check-*: Context drift goes unnoticed, code quality degrades. -- With check-*: Drift is caught and corrected before commit. - ---- - -### /trellis-check-cross-layer - Multi-Dimension Verification - -**WHY IT EXISTS**: -Most bugs don't come from lack of technical skill - they come from "didn't think of it": -- Changed a constant in one place, missed 5 other places -- Modified database schema, forgot to update the API layer -- Created a utility function, but similar one already exists - -**WHAT IT ACTUALLY DOES**: -1. Identifies which dimensions your change involves -2. For each dimension, runs targeted checks: - - Cross-layer data flow - - Code reuse analysis - - Import path validation - - Consistency checks - ---- - -### /trellis-finish-work - Holistic Pre-Commit Review - -**WHY IT EXISTS**: -The `/check-*` commands focus on code quality within a single layer. But real changes often have cross-cutting concerns. - -**WHAT IT ACTUALLY DOES**: -1. Reviews all changes holistically -2. Checks cross-layer consistency -3. Identifies broader impacts -4. Checks if new patterns should be documented - ---- - -### /trellis-record-session - Persist Memory for Future - -**WHY IT EXISTS**: -All the context AI built during this session will be lost when session ends. The next session's `/trellis-start` needs this information. - -**WHAT IT ACTUALLY DOES**: -1. Records session summary to `workspace/{developer}/journal-N.md` -2. Captures what was done, learned, and what's remaining -3. Updates index files for quick lookup - ---- - -## REAL-WORLD WORKFLOW EXAMPLES - -### Example 1: Bug Fix Session - -**[1/8] /trellis-start** - AI needs project context before touching code -**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference -**[3/8] /trellis-before-dev** - Inject project-specific development guidelines -**[4/8] Investigate and fix the bug** - Actual development work -**[5/8] /trellis-check** - Re-verify code against guidelines -**[6/8] /trellis-finish-work** - Holistic cross-layer review -**[7/8] Human tests and commits** - Human validates before code enters repo -**[8/8] /trellis-record-session** - Persist memory for future sessions - -### Example 2: Planning Session (No Code) - -**[1/4] /trellis-start** - Context needed even for non-coding work -**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work -**[3/4] Review docs, create subtask list** - Actual planning work -**[4/4] /trellis-record-session (with --summary)** - Planning decisions must be recorded - -### Example 3: Code Review Fixes - -**[1/6] /trellis-start** - Resume context from previous session -**[2/6] /trellis-before-dev** - Re-inject guidelines before fixes -**[3/6] Fix each CR issue** - Address feedback with guidelines in context -**[4/6] /trellis-check** - Verify fixes did not introduce new issues -**[5/6] /trellis-finish-work** - Document lessons from CR -**[6/6] Human commits, then /trellis-record-session** - Preserve CR lessons - -### Example 4: Large Refactoring - -**[1/5] /trellis-start** - Clear baseline before major changes -**[2/5] Plan phases** - Break into verifiable chunks -**[3/5] Execute phase by phase with /trellis-check after each** - Incremental verification -**[4/5] /trellis-finish-work** - Check if new patterns should be documented -**[5/5] Record with multiple commit hashes** - Link all commits to one feature - -### Example 5: Debug Session - -**[1/6] /trellis-start** - See if this bug was investigated before -**[2/6] /trellis-before-dev** - Guidelines might document known gotchas -**[3/6] Investigation** - Actual debugging work -**[4/6] /trellis-check** - Verify debug changes do not break other things -**[5/6] /trellis-finish-work** - Debug findings might need documentation -**[6/6] Human commits, then /trellis-record-session** - Debug knowledge is valuable - ---- - -## KEY RULES TO EMPHASIZE - -1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates. -2. **Guidelines before code** - /before-dev command injects project knowledge. -3. **Check after code** - /check-* commands catch context drift. -4. **Record everything** - /trellis-record-session persists memory. - ---- - -# PART 3: Customize Your Development Guidelines - -After explaining Part 1 and Part 2, check if the project's development guidelines need customization. - -## Step 1: Check Current Guidelines Status - -Check if `.trellis/spec/` contains empty templates or customized guidelines: - -```bash -# Check if files are still empty templates (look for placeholder text) -grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l -grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l -``` - -## Step 2: Determine Situation - -**Situation A: First-time setup (empty templates)** - -If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project. - -Explain to the developer: - -"I see that the development guidelines in `.trellis/spec/` are still empty templates. This is normal for a new Trellis setup! - -The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, `/before-*-dev` commands won't provide useful guidance. - -**Your first task should be to fill in these guidelines:** - -1. Look at your existing codebase -2. Identify the patterns and conventions already in use -3. Document them in the guideline files - -For example, for `.trellis/spec/backend/database-guidelines.md`: -- What ORM/query library does your project use? -- How are migrations managed? -- What naming conventions for tables/columns? - -Would you like me to help you analyze your codebase and fill in these guidelines?" - -**Situation B: Guidelines already customized** - -If guidelines have real content (no "To be filled" placeholders), this is an existing setup. - -Explain to the developer: - -"Great! Your team has already customized the development guidelines. You can start using `/before-*-dev` commands right away. - -I recommend reading through `.trellis/spec/` to familiarize yourself with the team's coding standards." - -## Step 3: Help Fill Guidelines (If Empty) - -If the developer wants help filling guidelines, create a feature to track this: - -```bash -python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines -``` - -Then systematically analyze the codebase and fill each guideline file: - -1. **Analyze the codebase** - Look at existing code patterns -2. **Document conventions** - Write what you observe, not ideals -3. **Include examples** - Reference actual files in the project -4. **List forbidden patterns** - Document anti-patterns the team avoids - -Work through one file at a time: -- `backend/directory-structure.md` -- `backend/database-guidelines.md` -- `backend/error-handling.md` -- `backend/quality-guidelines.md` -- `backend/logging-guidelines.md` -- `frontend/directory-structure.md` -- `frontend/component-guidelines.md` -- `frontend/hook-guidelines.md` -- `frontend/state-management.md` -- `frontend/quality-guidelines.md` -- `frontend/type-safety.md` - ---- - -## Completing the Onboard Session - -After covering all three parts, summarize: - -"You're now onboarded to the Trellis workflow system! Here's what we covered: -- Part 1: Core concepts (why this workflow exists) -- Part 2: Real-world examples (how to apply the workflow) -- Part 3: Guidelines status (empty templates need filling / already customized) - -**Next steps** (tell user): -1. Run `/trellis-record-session` to record this onboard session -2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines -3. [If guidelines ready] Start your first development task - -What would you like to do first?" diff --git a/.cursor/commands/trellis-record-session.md b/.cursor/commands/trellis-record-session.md deleted file mode 100644 index 8bea4f9b..00000000 --- a/.cursor/commands/trellis-record-session.md +++ /dev/null @@ -1,62 +0,0 @@ -[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code. - -**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts. - ---- - -## Record Work Progress - -### Step 1: Get Context & Check Tasks - -```bash -python3 ./.trellis/scripts/get_context.py --mode record -``` - -[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json: -- Code committed? → Archive it (don't wait for PR) -- All acceptance criteria met? → Archive it -- Don't skip archiving just because `status` still says `planning` or `in_progress` - -```bash -python3 ./.trellis/scripts/task.py archive <task-name> -``` - -### Step 2: One-Click Add Session - -```bash -# Method 1: Simple parameters -python3 ./.trellis/scripts/add_session.py \ - --title "Session Title" \ - --commit "hash1,hash2" \ - --summary "Brief summary of what was done" - -# Method 2: Pass detailed content via stdin -cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash" -| Feature | Description | -|---------|-------------| -| New API | Added user authentication endpoint | -| Frontend | Updated login form | - -**Updated Files**: -- `packages/api/modules/auth/router.ts` -- `apps/web/modules/auth/components/login-form.tsx` -EOF -``` - -**Auto-completes**: -- [OK] Appends session to journal-N.md -- [OK] Auto-detects line count, creates new file if >2000 lines -- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully) -- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history) -- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes - ---- - -## Script Command Reference - -| Command | Purpose | -|---------|---------| -| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session | -| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** | -| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) | -| `python3 ./.trellis/scripts/task.py list` | List active tasks | diff --git a/.cursor/commands/trellis-start.md b/.cursor/commands/trellis-start.md deleted file mode 100644 index ebbe85ab..00000000 --- a/.cursor/commands/trellis-start.md +++ /dev/null @@ -1,373 +0,0 @@ -# Start Session - -Initialize your AI development session and begin working on tasks. - ---- - -## Operation Types - -Operations in this document are categorized as: - -| Marker | Meaning | Executor | -|--------|---------|----------| -| `[AI]` | Bash scripts or file reads executed by AI | You (AI) | -| `[USER]` | Slash commands executed by user | User | - ---- - -## Initialization - -### Step 1: Understand Trellis Workflow `[AI]` - -First, read the workflow guide to understand the development process: - -```bash -cat .trellis/workflow.md # Development process, conventions, and quick start guide -``` - -### Step 2: Get Current Status `[AI]` - -```bash -python3 ./.trellis/scripts/get_context.py -``` - -This returns: -- Developer identity -- Git status (branch, uncommitted changes) -- Recent commits -- Active tasks -- Journal file status - -### Step 3: Read Guidelines Index `[AI]` - -```bash -python3 ./.trellis/scripts/get_context.py --mode packages -``` - -This shows available packages and their spec layers. Read the relevant spec indexes: - -```bash -cat .trellis/spec/<package>/<layer>/index.md # Package-specific guidelines -cat .trellis/spec/guides/index.md # Thinking guides (always read) -``` - -> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). -> At this step, just read the indexes to understand what's available. -> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist. - -### Step 4: Check Active Tasks `[AI]` - -```bash -python3 ./.trellis/scripts/task.py list -``` - -If continuing previous work, review the task file. - -### Step 5: Report Ready Status and Ask for Tasks - -Output a summary: - -```markdown -## Session Initialized - -| Item | Status | -|------|--------| -| Developer | {name} | -| Branch | {branch} | -| Uncommitted | {count} file(s) | -| Journal | {file} ({lines}/2000 lines) | -| Active Tasks | {count} | - -Ready for your task. What would you like to work on? -``` - ---- - -## Task Classification - -When user describes a task, classify it: - -| Type | Criteria | Workflow | -|------|----------|----------| -| **Question** | User asks about code, architecture, or how something works | Answer directly | -| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit | -| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow | -| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** | - -### Decision Rule - -> **If in doubt, use Brainstorm + Task Workflow.** -> -> Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code. -> The overhead is minimal, but the benefit is significant. - -> **Subtask Decomposition**: If brainstorm reveals multiple independent work items, -> consider creating subtasks using `--parent` flag or `add-subtask` command. -> See `/trellis:brainstorm` Step 8 for details. - ---- - -## Question / Trivial Fix - -For questions or trivial fixes, work directly: - -1. Answer question or make the fix -2. If code was changed, remind user to run `/trellis-finish-work` - ---- - -## Simple Task - -For simple, well-defined tasks: - -1. Quick confirm: "I understand you want to [goal]. Shall I proceed?" -2. If no, clarify and confirm again -3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.** - - Create task directory (Phase 1 Path B, Step 2) - - Write PRD (Step 3) - - Research codebase (Phase 2, Step 5) - - Configure context (Step 6) - - Activate task (Step 7) - - Implement (Phase 3, Step 8) - - Check quality (Step 9) - - Complete (Step 10) - ---- - -## Complex Task - Brainstorm First - -For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation. Use `/trellis-brainstorm`. - -Summary: - -1. **Acknowledge and classify** - State your understanding -2. **Create task directory** - Track evolving requirements in `prd.md` -3. **Ask questions one at a time** - Update PRD after each answer -4. **Propose approaches** - For architectural decisions -5. **Confirm final requirements** - Get explicit approval -6. **Proceed to Task Workflow** - With clear requirements in PRD - ---- - -## Task Workflow (Development Tasks) - -**Why this workflow?** -- Run a dedicated research pass before coding -- Configure specs in jsonl context files -- Implement using injected context -- Verify with a separate check pass -- Result: Code that follows project conventions automatically - -### Overview: Two Entry Points - -``` -From Brainstorm (Complex Task): - PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete - -From Simple Task: - Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete -``` - -**Key principle: Research happens AFTER requirements are clear (PRD exists).** - ---- - -### Phase 1: Establish Requirements - -#### Path A: From Brainstorm (skip to Phase 2) - -PRD and task directory already exist from brainstorm. Skip directly to Phase 2. - -#### Path B: From Simple Task - -**Step 1: Confirm Understanding** `[AI]` - -Quick confirm: -- What is the goal? -- What type of development? (frontend / backend / fullstack) -- Any specific requirements or constraints? - -If unclear, ask clarifying questions. - -**Step 2: Create Task Directory** `[AI]` - -```bash -TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>) -``` - -**Step 3: Write PRD** `[AI]` - -Create `prd.md` in the task directory with: - -```markdown -# <Task Title> - -## Goal -<What we're trying to achieve> - -## Requirements -- <Requirement 1> -- <Requirement 2> - -## Acceptance Criteria -- [ ] <Criterion 1> -- [ ] <Criterion 2> - -## Technical Notes -<Any technical decisions or constraints> -``` - ---- - -### Phase 2: Prepare for Implementation (shared) - -> Both paths converge here. PRD and task directory must exist before proceeding. - -**Step 4: Code-Spec Depth Check** `[AI]` - -If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined. - -Trigger this requirement when the change includes any of: -- New or changed command/API signatures -- Database schema or migration changes -- Infra integrations (storage, queue, cache, secrets, env contracts) -- Cross-layer payload transformations - -Must-have before proceeding: -- [ ] Target code-spec files to update are identified -- [ ] Concrete contract is defined (signature, fields, env keys) -- [ ] Validation and error matrix is defined -- [ ] At least one Good/Base/Bad case is defined - -**Step 5: Research the Codebase** `[AI]` - -Based on the confirmed PRD, run a focused research pass and produce: - -1. Relevant spec files in `.trellis/spec/` -2. Existing code patterns to follow (2-3 examples) -3. Files that will likely need modification - -Use this output format: - -```markdown -## Relevant Specs -- <path>: <why it's relevant> - -## Code Patterns Found -- <pattern>: <example file path> - -## Files to Modify -- <path>: <what change> -``` - -**Step 6: Configure Context** `[AI]` - -Initialize default context: - -```bash -python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> -# type: backend | frontend | fullstack -``` - -Add specs found in your research pass: - -```bash -# For each relevant spec and code pattern: -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>" -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>" -``` - -**Step 7: Activate Task** `[AI]` - -```bash -python3 ./.trellis/scripts/task.py start "$TASK_DIR" -``` - -This sets `.current-task` so hooks can inject context. - ---- - -### Phase 3: Execute (shared) - -**Step 8: Implement** `[AI]` - -Implement the task described in `prd.md`. - -- Follow all specs injected into implement context -- Keep changes scoped to requirements -- Run lint and typecheck before finishing - -**Step 9: Check Quality** `[AI]` - -Run a quality pass against check context: - -- Review all code changes against the specs -- Fix issues directly -- Ensure lint and typecheck pass - -**Step 10: Complete** `[AI]` - -1. Verify lint and typecheck pass -2. Report what was implemented -3. Remind user to: - - Test the changes - - Commit when ready - - Run `/trellis-record-session` to record this session - ---- - -## User Available Commands `[USER]` - -The following slash commands are for users (not AI): - -| Command | Description | -|---------|-------------| -| `/trellis-start` | Start development session (this command) | -| `/trellis-brainstorm` | Clarify vague requirements before implementation | -| `/trellis-before-dev` | Read development guidelines | -| `/trellis-check` | Check code quality | -| `/trellis-check-cross-layer` | Cross-layer verification | -| `/trellis-finish-work` | Pre-commit checklist | -| `/trellis-record-session` | Record session progress | - ---- - -## AI Executed Scripts `[AI]` - -| Script | Purpose | -|--------|---------| -| `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create task directory | -| `python3 ./.trellis/scripts/task.py list` | List active tasks | -| `python3 ./.trellis/scripts/task.py archive <name>` | Archive task | -| `python3 ./.trellis/scripts/get_context.py` | Get session context | - ---- - -## Platform Detection - -Trellis auto-detects your platform based on config directories. For Cursor users, ensure detection works correctly: - -| Condition | Detected Platform | -|-----------|-------------------| -| Only `.cursor/` exists | `cursor` ✅ | -| Both `.cursor/` and `.claude/` exist | `claude` (default) | - -If auto-detection fails, set manually: - -```bash -export TRELLIS_PLATFORM=cursor -``` - -Or prefix commands: - -```bash -TRELLIS_PLATFORM=cursor python3 ./.trellis/scripts/task.py list -``` - ---- - -## Session End Reminder - -**IMPORTANT**: When a task or session is completed, remind the user: - -> Before ending this session, please run `/trellis-record-session` to record what we accomplished. diff --git a/.cursor/commands/trellis-update-spec.md b/.cursor/commands/trellis-update-spec.md deleted file mode 100644 index 84736af3..00000000 --- a/.cursor/commands/trellis-update-spec.md +++ /dev/null @@ -1,354 +0,0 @@ -# Update Code-Spec - Capture Executable Contracts - -When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents. - -**Timing**: After completing a task, fixing a bug, or discovering a new pattern - ---- - -## Code-Spec First Rule (CRITICAL) - -In this project, "spec" for implementation work means **code-spec**: -- Executable contracts (not principle-only text) -- Concrete signatures, payload fields, env keys, and boundary behavior -- Testable validation/error behavior - -If the change touches infra or cross-layer contracts, code-spec depth is mandatory. - -### Mandatory Triggers - -Apply code-spec depth when the change includes any of: -- New/changed command or API signature -- Cross-layer request/response contract change -- Database schema/migration change -- Infra integration (storage, queue, cache, secrets, env wiring) - -### Mandatory Output (7 Sections) - -For triggered tasks, include all sections below: -1. Scope / Trigger -2. Signatures (command/API/DB) -3. Contracts (request/response/env) -4. Validation & Error Matrix -5. Good/Base/Bad Cases -6. Tests Required (with assertion points) -7. Wrong vs Correct (at least one pair) - ---- - -## When to Update Code-Specs - -| Trigger | Example | Target Spec | -|---------|---------|-------------| -| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file | -| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section | -| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` | -| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file | -| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section | -| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` | -| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) | - -**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely. - ---- - -## Spec Structure Overview - -``` -.trellis/spec/ -├── backend/ # Backend coding standards -│ ├── index.md # Overview and links -│ └── *.md # Topic-specific guidelines -├── frontend/ # Frontend coding standards -│ ├── index.md # Overview and links -│ └── *.md # Topic-specific guidelines -└── guides/ # Thinking checklists (NOT coding specs!) - ├── index.md # Guide index - └── *.md # Topic-specific guides -``` - -### CRITICAL: Code-Spec vs Guide - Know the Difference - -| Type | Location | Purpose | Content Style | -|------|----------|---------|---------------| -| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points | -| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs | - -**Decision Rule**: Ask yourself: - -- "This is **how to write** the code" → Put in `backend/` or `frontend/` -- "This is **what to consider** before writing" → Put in `guides/` - -**Example**: - -| Learning | Wrong Location | Correct Location | -|----------|----------------|------------------| -| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` | -| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` | - -**Guides should be short checklists that point to specs**, not duplicate the detailed rules. - ---- - -## Update Process - -### Step 1: Identify What You Learned - -Answer these questions: - -1. **What did you learn?** (Be specific) -2. **Why is it important?** (What problem does it prevent?) -3. **Where does it belong?** (Which spec file?) - -### Step 2: Classify the Update Type - -| Type | Description | Action | -|------|-------------|--------| -| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section | -| **Project Convention** | How we do X in this project | Add to relevant section with examples | -| **New Pattern** | A reusable approach discovered | Add to "Patterns" section | -| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section | -| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section | -| **Convention** | Agreed-upon standard | Add to relevant section | -| **Gotcha** | Non-obvious behavior | Add warning callout | - -### Step 3: Read the Target Code-Spec - -Before editing, read the current code-spec to: -- Understand existing structure -- Avoid duplicating content -- Find the right section for your update - -```bash -cat .trellis/spec/<category>/<file>.md -``` - -### Step 4: Make the Update - -Follow these principles: - -1. **Be Specific**: Include concrete examples, not just abstract rules -2. **Explain Why**: State the problem this prevents -3. **Show Contracts**: Add signatures, payload fields, and error behavior -4. **Show Code**: Add code snippets for key patterns -5. **Keep it Short**: One concept per section - -### Step 5: Update the Index (if needed) - -If you added a new section or the code-spec status changed, update the category's `index.md`. - ---- - -## Update Templates - -### Mandatory Template for Infra/Cross-Layer Work - -```markdown -## Scenario: <name> - -### 1. Scope / Trigger -- Trigger: <why this requires code-spec depth> - -### 2. Signatures -- Backend command/API/DB signature(s) - -### 3. Contracts -- Request fields (name, type, constraints) -- Response fields (name, type, constraints) -- Environment keys (required/optional) - -### 4. Validation & Error Matrix -- <condition> -> <error> - -### 5. Good/Base/Bad Cases -- Good: ... -- Base: ... -- Bad: ... - -### 6. Tests Required -- Unit/Integration/E2E with assertion points - -### 7. Wrong vs Correct -#### Wrong -... -#### Correct -... -``` - -### Adding a Design Decision - -```markdown -### Design Decision: [Decision Name] - -**Context**: What problem were we solving? - -**Options Considered**: -1. Option A - brief description -2. Option B - brief description - -**Decision**: We chose Option X because... - -**Example**: -\`\`\`typescript -// How it's implemented -code example -\`\`\` - -**Extensibility**: How to extend this in the future... -``` - -### Adding a Project Convention - -```markdown -### Convention: [Convention Name] - -**What**: Brief description of the convention. - -**Why**: Why we do it this way in this project. - -**Example**: -\`\`\`typescript -// How to follow this convention -code example -\`\`\` - -**Related**: Links to related conventions or specs. -``` - -### Adding a New Pattern - -```markdown -### Pattern Name - -**Problem**: What problem does this solve? - -**Solution**: Brief description of the approach. - -**Example**: -\`\`\` -// Good -code example - -// Bad -code example -\`\`\` - -**Why**: Explanation of why this works better. -``` - -### Adding a Forbidden Pattern - -```markdown -### Don't: Pattern Name - -**Problem**: -\`\`\` -// Don't do this -bad code example -\`\`\` - -**Why it's bad**: Explanation of the issue. - -**Instead**: -\`\`\` -// Do this instead -good code example -\`\`\` -``` - -### Adding a Common Mistake - -```markdown -### Common Mistake: Description - -**Symptom**: What goes wrong - -**Cause**: Why this happens - -**Fix**: How to correct it - -**Prevention**: How to avoid it in the future -``` - -### Adding a Gotcha - -```markdown -> **Warning**: Brief description of the non-obvious behavior. -> -> Details about when this happens and how to handle it. -``` - ---- - -## Interactive Mode - -If you're unsure what to update, answer these prompts: - -1. **What did you just finish?** - - [ ] Fixed a bug - - [ ] Implemented a feature - - [ ] Refactored code - - [ ] Had a discussion about approach - -2. **What did you learn or decide?** - - Design decision (why X over Y) - - Project convention (how we do X) - - Non-obvious behavior (gotcha) - - Better approach (pattern) - -3. **Would future AI/developers need to know this?** - - To understand how the code works → Yes, update spec - - To maintain or extend the feature → Yes, update spec - - To avoid repeating mistakes → Yes, update spec - - Purely one-off implementation detail → Maybe skip - -4. **Which area does it relate to?** - - [ ] Backend code - - [ ] Frontend code - - [ ] Cross-layer data flow - - [ ] Code organization/reuse - - [ ] Quality/testing - ---- - -## Quality Checklist - -Before finishing your code-spec update: - -- [ ] Is the content specific and actionable? -- [ ] Did you include a code example? -- [ ] Did you explain WHY, not just WHAT? -- [ ] Did you include executable signatures/contracts? -- [ ] Did you include validation and error matrix? -- [ ] Did you include Good/Base/Bad cases? -- [ ] Did you include required tests with assertion points? -- [ ] Is it in the right code-spec file? -- [ ] Does it duplicate existing content? -- [ ] Would a new team member understand it? - ---- - -## Relationship to Other Commands - -``` -Development Flow: - Learn something → /trellis-update-spec → Knowledge captured - ↑ ↓ - /trellis-break-loop ←──────────────────── Future sessions benefit - (deep bug analysis) -``` - -- `/trellis-break-loop` - Analyzes bugs deeply, often reveals spec updates needed -- `/trellis-update-spec` - Actually makes the updates (this command) -- `/trellis-finish-work` - Reminds you to check if specs need updates - ---- - -## Core Philosophy - -> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.** - -The goal is **institutional memory**: -- What one person learns, everyone benefits from -- What AI learns in one session, persists to future sessions -- Mistakes become documented guardrails diff --git a/.cursor/skills/ui-ux-pro-max/SKILL.md b/.cursor/skills/ui-ux-pro-max/SKILL.md deleted file mode 100644 index f53d42ba..00000000 --- a/.cursor/skills/ui-ux-pro-max/SKILL.md +++ /dev/null @@ -1,288 +0,0 @@ -# ui-ux-pro-max - -Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations. - -## Prerequisites - -Check if Python is installed: - -```bash -python3 --version || python --version -``` - -If Python is not installed, install it based on user's OS: - -**macOS:** -```bash -brew install python3 -``` - -**Ubuntu/Debian:** -```bash -sudo apt update && sudo apt install python3 -``` - -**Windows:** -```powershell -winget install Python.Python.3.12 -``` - ---- - -## How to Use This Skill - -When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow: - -### Step 1: Analyze User Requirements - -Extract key information from user request: -- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc. -- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc. -- **Industry**: healthcare, fintech, gaming, education, etc. -- **Stack**: React, Vue, Next.js, or default to `html-tailwind` - -### Step 2: Generate Design System (REQUIRED) - -**Always start with `--design-system`** to get comprehensive recommendations with reasoning: - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"] -``` - -This command: -1. Searches 5 domains in parallel (product, style, color, landing, typography) -2. Applies reasoning rules from `ui-reasoning.csv` to select best matches -3. Returns complete design system: pattern, style, colors, typography, effects -4. Includes anti-patterns to avoid - -**Example:** -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa" -``` - -### Step 2b: Persist Design System (Master + Overrides Pattern) - -To save the design system for hierarchical retrieval across sessions, add `--persist`: - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" -``` - -This creates: -- `design-system/MASTER.md` — Global Source of Truth with all design rules -- `design-system/pages/` — Folder for page-specific overrides - -**With page-specific override:** -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard" -``` - -This also creates: -- `design-system/pages/dashboard.md` — Page-specific deviations from Master - -**How hierarchical retrieval works:** -1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md` -2. If the page file exists, its rules **override** the Master file -3. If not, use `design-system/MASTER.md` exclusively - -### Step 3: Supplement with Detailed Searches (as needed) - -After getting the design system, use domain searches to get additional details: - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>] -``` - -**When to use detailed searches:** - -| Need | Domain | Example | -|------|--------|---------| -| More style options | `style` | `--domain style "glassmorphism dark"` | -| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` | -| UX best practices | `ux` | `--domain ux "animation accessibility"` | -| Alternative fonts | `typography` | `--domain typography "elegant luxury"` | -| Landing structure | `landing` | `--domain landing "hero social-proof"` | - -### Step 4: Stack Guidelines (Default: html-tailwind) - -Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**. - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind -``` - -Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose` - ---- - -## Search Reference - -### Available Domains - -| Domain | Use For | Example Keywords | -|--------|---------|------------------| -| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service | -| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism | -| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern | -| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service | -| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof | -| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie | -| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading | -| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache | -| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize | -| `prompt` | AI prompts, CSS keywords | (style name) | - -### Available Stacks - -| Stack | Focus | -|-------|-------| -| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) | -| `react` | State, hooks, performance, patterns | -| `nextjs` | SSR, routing, images, API routes | -| `vue` | Composition API, Pinia, Vue Router | -| `svelte` | Runes, stores, SvelteKit | -| `swiftui` | Views, State, Navigation, Animation | -| `react-native` | Components, Navigation, Lists | -| `flutter` | Widgets, State, Layout, Theming | -| `shadcn` | shadcn/ui components, theming, forms, patterns | -| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition | - ---- - -## Example Workflow - -**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp" - -### Step 1: Analyze Requirements -- Product type: Beauty/Spa service -- Style keywords: elegant, professional, soft -- Industry: Beauty/Wellness -- Stack: html-tailwind (default) - -### Step 2: Generate Design System (REQUIRED) - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa" -``` - -**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns. - -### Step 3: Supplement with Detailed Searches (as needed) - -```bash -# Get UX guidelines for animation and accessibility -python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux - -# Get alternative typography options if needed -python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography -``` - -### Step 4: Stack Guidelines - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind -``` - -**Then:** Synthesize design system + detailed searches and implement the design. - ---- - -## Output Formats - -The `--design-system` flag supports two output formats: - -```bash -# ASCII box (default) - best for terminal display -python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system - -# Markdown - best for documentation -python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown -``` - ---- - -## Tips for Better Results - -1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app" -2. **Search multiple times** - Different keywords reveal different insights -3. **Combine domains** - Style + Typography + Color = Complete design system -4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues -5. **Use stack flag** - Get implementation-specific best practices -6. **Iterate** - If first search doesn't match, try different keywords - ---- - -## Common Rules for Professional UI - -These are frequently overlooked issues that make UI look unprofessional: - -### Icons & Visual Elements - -| Rule | Do | Don't | -|------|----|----- | -| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons | -| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout | -| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths | -| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly | - -### Interaction & Cursor - -| Rule | Do | Don't | -|------|----|----- | -| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements | -| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive | -| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) | - -### Light/Dark Mode Contrast - -| Rule | Do | Don't | -|------|----|----- | -| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) | -| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text | -| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter | -| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) | - -### Layout & Spacing - -| Rule | Do | Don't | -|------|----|----- | -| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` | -| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements | -| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths | - ---- - -## Pre-Delivery Checklist - -Before delivering UI code, verify these items: - -### Visual Quality -- [ ] No emojis used as icons (use SVG instead) -- [ ] All icons from consistent icon set (Heroicons/Lucide) -- [ ] Brand logos are correct (verified from Simple Icons) -- [ ] Hover states don't cause layout shift -- [ ] Use theme colors directly (bg-primary) not var() wrapper - -### Interaction -- [ ] All clickable elements have `cursor-pointer` -- [ ] Hover states provide clear visual feedback -- [ ] Transitions are smooth (150-300ms) -- [ ] Focus states visible for keyboard navigation - -### Light/Dark Mode -- [ ] Light mode text has sufficient contrast (4.5:1 minimum) -- [ ] Glass/transparent elements visible in light mode -- [ ] Borders visible in both modes -- [ ] Test both modes before delivery - -### Layout -- [ ] Floating elements have proper spacing from edges -- [ ] No content hidden behind fixed navbars -- [ ] Responsive at 375px, 768px, 1024px, 1440px -- [ ] No horizontal scroll on mobile - -### Accessibility -- [ ] All images have alt text -- [ ] Form inputs have labels -- [ ] Color is not the only indicator -- [ ] `prefers-reduced-motion` respected diff --git a/.cursor/skills/ui-ux-pro-max/data/charts.csv b/.cursor/skills/ui-ux-pro-max/data/charts.csv deleted file mode 100644 index 9463c37d..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/charts.csv +++ /dev/null @@ -1,26 +0,0 @@ -No,Data Type,Keywords,Best Chart Type,Secondary Options,Color Guidance,Performance Impact,Accessibility Notes,Library Recommendation,Interactive Level -1,Trend Over Time,"trend, time-series, line, growth, timeline, progress",Line Chart,"Area Chart, Smooth Area",Primary: #0080FF. Multiple series: use distinct colors. Fill: 20% opacity,⚡ Excellent (optimized),✓ Clear line patterns for colorblind users. Add pattern overlays.,"Chart.js, Recharts, ApexCharts",Hover + Zoom -2,Compare Categories,"compare, categories, bar, comparison, ranking",Bar Chart (Horizontal or Vertical),"Column Chart, Grouped Bar",Each bar: distinct color. Category: grouped same color. Sorted: descending order,⚡ Excellent,✓ Easy to compare. Add value labels on bars for clarity.,"Chart.js, Recharts, D3.js",Hover + Sort -3,Part-to-Whole,"part-to-whole, pie, donut, percentage, proportion, share",Pie Chart or Donut,"Stacked Bar, Treemap",Colors: 5-6 max. Contrasting palette. Large slices first. Use labels.,⚡ Good (limit 6 slices),⚠ Hard for accessibility. Better: Stacked bar with legend. Avoid pie if >5 items.,"Chart.js, Recharts, D3.js",Hover + Drill -4,Correlation/Distribution,"correlation, distribution, scatter, relationship, pattern",Scatter Plot or Bubble Chart,"Heat Map, Matrix",Color axis: gradient (blue-red). Size: relative. Opacity: 0.6-0.8 to show density,⚠ Moderate (many points),⚠ Provide data table alternative. Use pattern + color distinction.,"D3.js, Plotly, Recharts",Hover + Brush -5,Heatmap/Intensity,"heatmap, heat-map, intensity, density, matrix",Heat Map or Choropleth,"Grid Heat Map, Bubble Heat",Gradient: Cool (blue) to Hot (red). Scale: clear legend. Divergent for ±data,⚡ Excellent (color CSS),⚠ Colorblind: Use pattern overlay. Provide numerical legend.,"D3.js, Plotly, ApexCharts",Hover + Zoom -6,Geographic Data,"geographic, map, location, region, geo, spatial","Choropleth Map, Bubble Map",Geographic Heat Map,Regional: single color gradient or categorized colors. Legend: clear scale,⚠ Moderate (rendering),⚠ Include text labels for regions. Provide data table alternative.,"D3.js, Mapbox, Leaflet",Pan + Zoom + Drill -7,Funnel/Flow,funnel/flow,"Funnel Chart, Sankey",Waterfall (for flows),Stages: gradient (starting color → ending color). Show conversion %,⚡ Good,✓ Clear stage labels + percentages. Good for accessibility if labeled.,"D3.js, Recharts, Custom SVG",Hover + Drill -8,Performance vs Target,performance-vs-target,Gauge Chart or Bullet Chart,"Dial, Thermometer",Performance: Red→Yellow→Green gradient. Target: marker line. Threshold colors,⚡ Good,✓ Add numerical value + percentage label beside gauge.,"D3.js, ApexCharts, Custom SVG",Hover -9,Time-Series Forecast,time-series-forecast,Line with Confidence Band,Ribbon Chart,Actual: solid line #0080FF. Forecast: dashed #FF9500. Band: light shading,⚡ Good,✓ Clearly distinguish actual vs forecast. Add legend.,"Chart.js, ApexCharts, Plotly",Hover + Toggle -10,Anomaly Detection,anomaly-detection,Line Chart with Highlights,Scatter with Alert,Normal: blue #0080FF. Anomaly: red #FF0000 circle/square marker + alert,⚡ Good,✓ Circle/marker for anomalies. Add text alert annotation.,"D3.js, Plotly, ApexCharts",Hover + Alert -11,Hierarchical/Nested Data,hierarchical/nested-data,Treemap,"Sunburst, Nested Donut, Icicle",Parent: distinct hues. Children: lighter shades. White borders 2-3px.,⚠ Moderate,⚠ Poor - provide table alternative. Label large areas.,"D3.js, Recharts, ApexCharts",Hover + Drilldown -12,Flow/Process Data,flow/process-data,Sankey Diagram,"Alluvial, Chord Diagram",Gradient from source to target. Opacity 0.4-0.6 for flows.,⚠ Moderate,⚠ Poor - provide flow table alternative.,"D3.js (d3-sankey), Plotly",Hover + Drilldown -13,Cumulative Changes,cumulative-changes,Waterfall Chart,"Stacked Bar, Cascade",Increases: #4CAF50. Decreases: #F44336. Start: #2196F3. End: #0D47A1.,⚡ Good,✓ Good - clear directional colors with labels.,"ApexCharts, Highcharts, Plotly",Hover -14,Multi-Variable Comparison,multi-variable-comparison,Radar/Spider Chart,"Parallel Coordinates, Grouped Bar",Single: #0080FF 20% fill. Multiple: distinct colors per dataset.,⚡ Good,⚠ Moderate - limit 5-8 axes. Add data table.,"Chart.js, Recharts, ApexCharts",Hover + Toggle -15,Stock/Trading OHLC,stock/trading-ohlc,Candlestick Chart,"OHLC Bar, Heikin-Ashi",Bullish: #26A69A. Bearish: #EF5350. Volume: 40% opacity below.,⚡ Good,⚠ Moderate - provide OHLC data table.,"Lightweight Charts (TradingView), ApexCharts",Real-time + Hover + Zoom -16,Relationship/Connection Data,relationship/connection-data,Network Graph,"Hierarchical Tree, Adjacency Matrix",Node types: categorical colors. Edges: #90A4AE 60% opacity.,❌ Poor (500+ nodes struggles),❌ Very Poor - provide adjacency list alternative.,"D3.js (d3-force), Vis.js, Cytoscape.js",Drilldown + Hover + Drag -17,Distribution/Statistical,distribution/statistical,Box Plot,"Violin Plot, Beeswarm",Box: #BBDEFB. Border: #1976D2. Median: #D32F2F. Outliers: #F44336.,⚡ Excellent,"✓ Good - include stats table (min, Q1, median, Q3, max).","Plotly, D3.js, Chart.js (plugin)",Hover -18,Performance vs Target (Compact),performance-vs-target-(compact),Bullet Chart,"Gauge, Progress Bar","Ranges: #FFCDD2, #FFF9C4, #C8E6C9. Performance: #1976D2. Target: black 3px.",⚡ Excellent,✓ Excellent - compact with clear values.,"D3.js, Plotly, Custom SVG",Hover -19,Proportional/Percentage,proportional/percentage,Waffle Chart,"Pictogram, Stacked Bar 100%",10x10 grid. 3-5 categories max. 2-3px spacing between squares.,⚡ Good,✓ Good - better than pie for accessibility.,"D3.js, React-Waffle, Custom CSS Grid",Hover -20,Hierarchical Proportional,hierarchical-proportional,Sunburst Chart,"Treemap, Icicle, Circle Packing",Center to outer: darker to lighter. 15-20% lighter per level.,⚠ Moderate,⚠ Poor - provide hierarchy table alternative.,"D3.js (d3-hierarchy), Recharts, ApexCharts",Drilldown + Hover -21,Root Cause Analysis,"root cause, decomposition, tree, hierarchy, drill-down, ai-split",Decomposition Tree,"Decision Tree, Flow Chart",Nodes: #2563EB (Primary) vs #EF4444 (Negative impact). Connectors: Neutral grey.,⚠ Moderate (calculation heavy),✓ clear hierarchy. Allow keyboard navigation for nodes.,"Power BI (native), React-Flow, Custom D3.js",Drill + Expand -22,3D Spatial Data,"3d, spatial, immersive, terrain, molecular, volumetric",3D Scatter/Surface Plot,"Volumetric Rendering, Point Cloud",Depth cues: lighting/shading. Z-axis: color gradient (cool to warm).,❌ Heavy (WebGL required),❌ Poor - requires alternative 2D view or data table.,"Three.js, Deck.gl, Plotly 3D",Rotate + Zoom + VR -23,Real-Time Streaming,"streaming, real-time, ticker, live, velocity, pulse",Streaming Area Chart,"Ticker Tape, Moving Gauge",Current: Bright Pulse (#00FF00). History: Fading opacity. Grid: Dark.,⚡ Optimized (canvas/webgl),⚠ Flashing elements - provide pause button. High contrast.,Smoothed D3.js, CanvasJS -24,Sentiment/Emotion,"sentiment, emotion, nlp, opinion, feeling",Word Cloud with Sentiment,"Sentiment Arc, Radar Chart",Positive: #22C55E. Negative: #EF4444. Neutral: #94A3B8. Size = Frequency.,⚡ Good,⚠ Word clouds poor for screen readers. Use list view.,"D3-cloud, Highcharts, Nivo",Hover + Filter -25,Process Mining,"process, mining, variants, path, bottleneck, log",Process Map / Graph,"Directed Acyclic Graph (DAG), Petri Net",Happy path: #10B981 (Thick). Deviations: #F59E0B (Thin). Bottlenecks: #EF4444.,⚠ Moderate to Heavy,⚠ Complex graphs hard to navigate. Provide path summary.,"React-Flow, Cytoscape.js, Recharts",Drag + Node-Click diff --git a/.cursor/skills/ui-ux-pro-max/data/colors.csv b/.cursor/skills/ui-ux-pro-max/data/colors.csv deleted file mode 100644 index a1878457..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/colors.csv +++ /dev/null @@ -1,97 +0,0 @@ -No,Product Type,Primary (Hex),Secondary (Hex),CTA (Hex),Background (Hex),Text (Hex),Border (Hex),Notes -1,SaaS (General),#2563EB,#3B82F6,#F97316,#F8FAFC,#1E293B,#E2E8F0,Trust blue + orange CTA contrast -2,Micro SaaS,#6366F1,#818CF8,#10B981,#F5F3FF,#1E1B4B,#E0E7FF,Indigo primary + emerald CTA -3,E-commerce,#059669,#10B981,#F97316,#ECFDF5,#064E3B,#A7F3D0,Success green + urgency orange -4,E-commerce Luxury,#1C1917,#44403C,#CA8A04,#FAFAF9,#0C0A09,#D6D3D1,Premium dark + gold accent -5,Service Landing Page,#0EA5E9,#38BDF8,#F97316,#F0F9FF,#0C4A6E,#BAE6FD,Sky blue trust + warm CTA -6,B2B Service,#0F172A,#334155,#0369A1,#F8FAFC,#020617,#E2E8F0,Professional navy + blue CTA -7,Financial Dashboard,#0F172A,#1E293B,#22C55E,#020617,#F8FAFC,#334155,Dark bg + green positive indicators -8,Analytics Dashboard,#1E40AF,#3B82F6,#F59E0B,#F8FAFC,#1E3A8A,#DBEAFE,Blue data + amber highlights -9,Healthcare App,#0891B2,#22D3EE,#059669,#ECFEFF,#164E63,#A5F3FC,Calm cyan + health green -10,Educational App,#4F46E5,#818CF8,#F97316,#EEF2FF,#1E1B4B,#C7D2FE,Playful indigo + energetic orange -11,Creative Agency,#EC4899,#F472B6,#06B6D4,#FDF2F8,#831843,#FBCFE8,Bold pink + cyan accent -12,Portfolio/Personal,#18181B,#3F3F46,#2563EB,#FAFAFA,#09090B,#E4E4E7,Monochrome + blue accent -13,Gaming,#7C3AED,#A78BFA,#F43F5E,#0F0F23,#E2E8F0,#4C1D95,Neon purple + rose action -14,Government/Public Service,#0F172A,#334155,#0369A1,#F8FAFC,#020617,#E2E8F0,High contrast navy + blue -15,Fintech/Crypto,#F59E0B,#FBBF24,#8B5CF6,#0F172A,#F8FAFC,#334155,Gold trust + purple tech -16,Social Media App,#E11D48,#FB7185,#2563EB,#FFF1F2,#881337,#FECDD3,Vibrant rose + engagement blue -17,Productivity Tool,#0D9488,#14B8A6,#F97316,#F0FDFA,#134E4A,#99F6E4,Teal focus + action orange -18,Design System/Component Library,#4F46E5,#6366F1,#F97316,#EEF2FF,#312E81,#C7D2FE,Indigo brand + doc hierarchy -19,AI/Chatbot Platform,#7C3AED,#A78BFA,#06B6D4,#FAF5FF,#1E1B4B,#DDD6FE,AI purple + cyan interactions -20,NFT/Web3 Platform,#8B5CF6,#A78BFA,#FBBF24,#0F0F23,#F8FAFC,#4C1D95,Purple tech + gold value -21,Creator Economy Platform,#EC4899,#F472B6,#F97316,#FDF2F8,#831843,#FBCFE8,Creator pink + engagement orange -22,Sustainability/ESG Platform,#059669,#10B981,#0891B2,#ECFDF5,#064E3B,#A7F3D0,Nature green + ocean blue -23,Remote Work/Collaboration Tool,#6366F1,#818CF8,#10B981,#F5F3FF,#312E81,#E0E7FF,Calm indigo + success green -24,Mental Health App,#8B5CF6,#C4B5FD,#10B981,#FAF5FF,#4C1D95,#EDE9FE,Calming lavender + wellness green -25,Pet Tech App,#F97316,#FB923C,#2563EB,#FFF7ED,#9A3412,#FED7AA,Playful orange + trust blue -26,Smart Home/IoT Dashboard,#1E293B,#334155,#22C55E,#0F172A,#F8FAFC,#475569,Dark tech + status green -27,EV/Charging Ecosystem,#0891B2,#22D3EE,#22C55E,#ECFEFF,#164E63,#A5F3FC,Electric cyan + eco green -28,Subscription Box Service,#D946EF,#E879F9,#F97316,#FDF4FF,#86198F,#F5D0FE,Excitement purple + urgency orange -29,Podcast Platform,#1E1B4B,#312E81,#F97316,#0F0F23,#F8FAFC,#4338CA,Dark audio + warm accent -30,Dating App,#E11D48,#FB7185,#F97316,#FFF1F2,#881337,#FECDD3,Romantic rose + warm orange -31,Micro-Credentials/Badges Platform,#0369A1,#0EA5E9,#CA8A04,#F0F9FF,#0C4A6E,#BAE6FD,Trust blue + achievement gold -32,Knowledge Base/Documentation,#475569,#64748B,#2563EB,#F8FAFC,#1E293B,#E2E8F0,Neutral grey + link blue -33,Hyperlocal Services,#059669,#10B981,#F97316,#ECFDF5,#064E3B,#A7F3D0,Location green + action orange -34,Beauty/Spa/Wellness Service,#EC4899,#F9A8D4,#8B5CF6,#FDF2F8,#831843,#FBCFE8,Soft pink + lavender luxury -35,Luxury/Premium Brand,#1C1917,#44403C,#CA8A04,#FAFAF9,#0C0A09,#D6D3D1,Premium black + gold accent -36,Restaurant/Food Service,#DC2626,#F87171,#CA8A04,#FEF2F2,#450A0A,#FECACA,Appetizing red + warm gold -37,Fitness/Gym App,#F97316,#FB923C,#22C55E,#1F2937,#F8FAFC,#374151,Energy orange + success green -38,Real Estate/Property,#0F766E,#14B8A6,#0369A1,#F0FDFA,#134E4A,#99F6E4,Trust teal + professional blue -39,Travel/Tourism Agency,#0EA5E9,#38BDF8,#F97316,#F0F9FF,#0C4A6E,#BAE6FD,Sky blue + adventure orange -40,Hotel/Hospitality,#1E3A8A,#3B82F6,#CA8A04,#F8FAFC,#1E40AF,#BFDBFE,Luxury navy + gold service -41,Wedding/Event Planning,#DB2777,#F472B6,#CA8A04,#FDF2F8,#831843,#FBCFE8,Romantic pink + elegant gold -42,Legal Services,#1E3A8A,#1E40AF,#B45309,#F8FAFC,#0F172A,#CBD5E1,Authority navy + trust gold -43,Insurance Platform,#0369A1,#0EA5E9,#22C55E,#F0F9FF,#0C4A6E,#BAE6FD,Security blue + protected green -44,Banking/Traditional Finance,#0F172A,#1E3A8A,#CA8A04,#F8FAFC,#020617,#E2E8F0,Trust navy + premium gold -45,Online Course/E-learning,#0D9488,#2DD4BF,#F97316,#F0FDFA,#134E4A,#5EEAD4,Progress teal + achievement orange -46,Non-profit/Charity,#0891B2,#22D3EE,#F97316,#ECFEFF,#164E63,#A5F3FC,Compassion blue + action orange -47,Music Streaming,#1E1B4B,#4338CA,#22C55E,#0F0F23,#F8FAFC,#312E81,Dark audio + play green -48,Video Streaming/OTT,#0F0F23,#1E1B4B,#E11D48,#000000,#F8FAFC,#312E81,Cinema dark + play red -49,Job Board/Recruitment,#0369A1,#0EA5E9,#22C55E,#F0F9FF,#0C4A6E,#BAE6FD,Professional blue + success green -50,Marketplace (P2P),#7C3AED,#A78BFA,#22C55E,#FAF5FF,#4C1D95,#DDD6FE,Trust purple + transaction green -51,Logistics/Delivery,#2563EB,#3B82F6,#F97316,#EFF6FF,#1E40AF,#BFDBFE,Tracking blue + delivery orange -52,Agriculture/Farm Tech,#15803D,#22C55E,#CA8A04,#F0FDF4,#14532D,#BBF7D0,Earth green + harvest gold -53,Construction/Architecture,#64748B,#94A3B8,#F97316,#F8FAFC,#334155,#E2E8F0,Industrial grey + safety orange -54,Automotive/Car Dealership,#1E293B,#334155,#DC2626,#F8FAFC,#0F172A,#E2E8F0,Premium dark + action red -55,Photography Studio,#18181B,#27272A,#F8FAFC,#000000,#FAFAFA,#3F3F46,Pure black + white contrast -56,Coworking Space,#F59E0B,#FBBF24,#2563EB,#FFFBEB,#78350F,#FDE68A,Energetic amber + booking blue -57,Cleaning Service,#0891B2,#22D3EE,#22C55E,#ECFEFF,#164E63,#A5F3FC,Fresh cyan + clean green -58,Home Services (Plumber/Electrician),#1E40AF,#3B82F6,#F97316,#EFF6FF,#1E3A8A,#BFDBFE,Professional blue + urgent orange -59,Childcare/Daycare,#F472B6,#FBCFE8,#22C55E,#FDF2F8,#9D174D,#FCE7F3,Soft pink + safe green -60,Senior Care/Elderly,#0369A1,#38BDF8,#22C55E,#F0F9FF,#0C4A6E,#E0F2FE,Calm blue + reassuring green -61,Medical Clinic,#0891B2,#22D3EE,#22C55E,#F0FDFA,#134E4A,#CCFBF1,Medical teal + health green -62,Pharmacy/Drug Store,#15803D,#22C55E,#0369A1,#F0FDF4,#14532D,#BBF7D0,Pharmacy green + trust blue -63,Dental Practice,#0EA5E9,#38BDF8,#FBBF24,#F0F9FF,#0C4A6E,#BAE6FD,Fresh blue + smile yellow -64,Veterinary Clinic,#0D9488,#14B8A6,#F97316,#F0FDFA,#134E4A,#99F6E4,Caring teal + warm orange -65,Florist/Plant Shop,#15803D,#22C55E,#EC4899,#F0FDF4,#14532D,#BBF7D0,Natural green + floral pink -66,Bakery/Cafe,#92400E,#B45309,#F8FAFC,#FEF3C7,#78350F,#FDE68A,Warm brown + cream white -67,Coffee Shop,#78350F,#92400E,#FBBF24,#FEF3C7,#451A03,#FDE68A,Coffee brown + warm gold -68,Brewery/Winery,#7C2D12,#B91C1C,#CA8A04,#FEF2F2,#450A0A,#FECACA,Deep burgundy + craft gold -69,Airline,#1E3A8A,#3B82F6,#F97316,#EFF6FF,#1E40AF,#BFDBFE,Sky blue + booking orange -70,News/Media Platform,#DC2626,#EF4444,#1E40AF,#FEF2F2,#450A0A,#FECACA,Breaking red + link blue -71,Magazine/Blog,#18181B,#3F3F46,#EC4899,#FAFAFA,#09090B,#E4E4E7,Editorial black + accent pink -72,Freelancer Platform,#6366F1,#818CF8,#22C55E,#EEF2FF,#312E81,#C7D2FE,Creative indigo + hire green -73,Consulting Firm,#0F172A,#334155,#CA8A04,#F8FAFC,#020617,#E2E8F0,Authority navy + premium gold -74,Marketing Agency,#EC4899,#F472B6,#06B6D4,#FDF2F8,#831843,#FBCFE8,Bold pink + creative cyan -75,Event Management,#7C3AED,#A78BFA,#F97316,#FAF5FF,#4C1D95,#DDD6FE,Excitement purple + action orange -76,Conference/Webinar Platform,#1E40AF,#3B82F6,#22C55E,#EFF6FF,#1E3A8A,#BFDBFE,Professional blue + join green -77,Membership/Community,#7C3AED,#A78BFA,#22C55E,#FAF5FF,#4C1D95,#DDD6FE,Community purple + join green -78,Newsletter Platform,#0369A1,#0EA5E9,#F97316,#F0F9FF,#0C4A6E,#BAE6FD,Trust blue + subscribe orange -79,Digital Products/Downloads,#6366F1,#818CF8,#22C55E,#EEF2FF,#312E81,#C7D2FE,Digital indigo + buy green -80,Church/Religious Organization,#7C3AED,#A78BFA,#CA8A04,#FAF5FF,#4C1D95,#DDD6FE,Spiritual purple + warm gold -81,Sports Team/Club,#DC2626,#EF4444,#FBBF24,#FEF2F2,#7F1D1D,#FECACA,Team red + championship gold -82,Museum/Gallery,#18181B,#27272A,#F8FAFC,#FAFAFA,#09090B,#E4E4E7,Gallery black + white space -83,Theater/Cinema,#1E1B4B,#312E81,#CA8A04,#0F0F23,#F8FAFC,#4338CA,Dramatic dark + spotlight gold -84,Language Learning App,#4F46E5,#818CF8,#22C55E,#EEF2FF,#312E81,#C7D2FE,Learning indigo + progress green -85,Coding Bootcamp,#0F172A,#1E293B,#22C55E,#020617,#F8FAFC,#334155,Terminal dark + success green -86,Cybersecurity Platform,#00FF41,#0D0D0D,#FF3333,#000000,#E0E0E0,#1F1F1F,Matrix green + alert red -87,Developer Tool / IDE,#1E293B,#334155,#22C55E,#0F172A,#F8FAFC,#475569,Code dark + run green -88,Biotech / Life Sciences,#0EA5E9,#0284C7,#10B981,#F0F9FF,#0C4A6E,#BAE6FD,DNA blue + life green -89,Space Tech / Aerospace,#F8FAFC,#94A3B8,#3B82F6,#0B0B10,#F8FAFC,#1E293B,Star white + launch blue -90,Architecture / Interior,#171717,#404040,#D4AF37,#FFFFFF,#171717,#E5E5E5,Minimal black + accent gold -91,Quantum Computing,#00FFFF,#7B61FF,#FF00FF,#050510,#E0E0FF,#333344,Quantum cyan + interference purple -92,Biohacking / Longevity,#FF4D4D,#4D94FF,#00E676,#F5F5F7,#1C1C1E,#E5E5EA,Bio red/blue + vitality green -93,Autonomous Systems,#00FF41,#008F11,#FF3333,#0D1117,#E6EDF3,#30363D,Terminal green + alert red -94,Generative AI Art,#18181B,#3F3F46,#EC4899,#FAFAFA,#09090B,#E4E4E7,Canvas neutral + creative pink -95,Spatial / Vision OS,#FFFFFF,#E5E5E5,#007AFF,#888888,#000000,#CCCCCC,Glass white + system blue -96,Climate Tech,#059669,#10B981,#FBBF24,#ECFDF5,#064E3B,#A7F3D0,Nature green + solar gold diff --git a/.cursor/skills/ui-ux-pro-max/data/icons.csv b/.cursor/skills/ui-ux-pro-max/data/icons.csv deleted file mode 100644 index a85e97f8..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/icons.csv +++ /dev/null @@ -1,101 +0,0 @@ -No,Category,Icon Name,Keywords,Library,Import Code,Usage,Best For,Style -1,Navigation,menu,hamburger menu navigation toggle bars,Lucide,import { Menu } from 'lucide-react',<Menu />,Mobile navigation drawer toggle sidebar,Outline -2,Navigation,arrow-left,back previous return navigate,Lucide,import { ArrowLeft } from 'lucide-react',<ArrowLeft />,Back button breadcrumb navigation,Outline -3,Navigation,arrow-right,next forward continue navigate,Lucide,import { ArrowRight } from 'lucide-react',<ArrowRight />,Forward button next step CTA,Outline -4,Navigation,chevron-down,dropdown expand accordion select,Lucide,import { ChevronDown } from 'lucide-react',<ChevronDown />,Dropdown toggle accordion header,Outline -5,Navigation,chevron-up,collapse close accordion minimize,Lucide,import { ChevronUp } from 'lucide-react',<ChevronUp />,Accordion collapse minimize,Outline -6,Navigation,home,homepage main dashboard start,Lucide,import { Home } from 'lucide-react',<Home />,Home navigation main page,Outline -7,Navigation,x,close cancel dismiss remove exit,Lucide,import { X } from 'lucide-react',<X />,Modal close dismiss button,Outline -8,Navigation,external-link,open new tab external link,Lucide,import { ExternalLink } from 'lucide-react',<ExternalLink />,External link indicator,Outline -9,Action,plus,add create new insert,Lucide,import { Plus } from 'lucide-react',<Plus />,Add button create new item,Outline -10,Action,minus,remove subtract decrease delete,Lucide,import { Minus } from 'lucide-react',<Minus />,Remove item quantity decrease,Outline -11,Action,trash-2,delete remove discard bin,Lucide,import { Trash2 } from 'lucide-react',<Trash2 />,Delete action destructive,Outline -12,Action,edit,pencil modify change update,Lucide,import { Edit } from 'lucide-react',<Edit />,Edit button modify content,Outline -13,Action,save,disk store persist save,Lucide,import { Save } from 'lucide-react',<Save />,Save button persist changes,Outline -14,Action,download,export save file download,Lucide,import { Download } from 'lucide-react',<Download />,Download file export,Outline -15,Action,upload,import file attach upload,Lucide,import { Upload } from 'lucide-react',<Upload />,Upload file import,Outline -16,Action,copy,duplicate clipboard paste,Lucide,import { Copy } from 'lucide-react',<Copy />,Copy to clipboard,Outline -17,Action,share,social distribute send,Lucide,import { Share } from 'lucide-react',<Share />,Share button social,Outline -18,Action,search,find lookup filter query,Lucide,import { Search } from 'lucide-react',<Search />,Search input bar,Outline -19,Action,filter,sort refine narrow options,Lucide,import { Filter } from 'lucide-react',<Filter />,Filter dropdown sort,Outline -20,Action,settings,gear cog preferences config,Lucide,import { Settings } from 'lucide-react',<Settings />,Settings page configuration,Outline -21,Status,check,success done complete verified,Lucide,import { Check } from 'lucide-react',<Check />,Success state checkmark,Outline -22,Status,check-circle,success verified approved complete,Lucide,import { CheckCircle } from 'lucide-react',<CheckCircle />,Success badge verified,Outline -23,Status,x-circle,error failed cancel rejected,Lucide,import { XCircle } from 'lucide-react',<XCircle />,Error state failed,Outline -24,Status,alert-triangle,warning caution attention danger,Lucide,import { AlertTriangle } from 'lucide-react',<AlertTriangle />,Warning message caution,Outline -25,Status,alert-circle,info notice information help,Lucide,import { AlertCircle } from 'lucide-react',<AlertCircle />,Info notice alert,Outline -26,Status,info,information help tooltip details,Lucide,import { Info } from 'lucide-react',<Info />,Information tooltip help,Outline -27,Status,loader,loading spinner processing wait,Lucide,import { Loader } from 'lucide-react',<Loader className="animate-spin" />,Loading state spinner,Outline -28,Status,clock,time schedule pending wait,Lucide,import { Clock } from 'lucide-react',<Clock />,Pending time schedule,Outline -29,Communication,mail,email message inbox letter,Lucide,import { Mail } from 'lucide-react',<Mail />,Email contact inbox,Outline -30,Communication,message-circle,chat comment bubble conversation,Lucide,import { MessageCircle } from 'lucide-react',<MessageCircle />,Chat comment message,Outline -31,Communication,phone,call mobile telephone contact,Lucide,import { Phone } from 'lucide-react',<Phone />,Phone contact call,Outline -32,Communication,send,submit dispatch message airplane,Lucide,import { Send } from 'lucide-react',<Send />,Send message submit,Outline -33,Communication,bell,notification alert ring reminder,Lucide,import { Bell } from 'lucide-react',<Bell />,Notification bell alert,Outline -34,User,user,profile account person avatar,Lucide,import { User } from 'lucide-react',<User />,User profile account,Outline -35,User,users,team group people members,Lucide,import { Users } from 'lucide-react',<Users />,Team group members,Outline -36,User,user-plus,add invite new member,Lucide,import { UserPlus } from 'lucide-react',<UserPlus />,Add user invite,Outline -37,User,log-in,signin authenticate enter,Lucide,import { LogIn } from 'lucide-react',<LogIn />,Login signin,Outline -38,User,log-out,signout exit leave logout,Lucide,import { LogOut } from 'lucide-react',<LogOut />,Logout signout,Outline -39,Media,image,photo picture gallery thumbnail,Lucide,import { Image } from 'lucide-react',<Image />,Image photo gallery,Outline -40,Media,video,movie film play record,Lucide,import { Video } from 'lucide-react',<Video />,Video player media,Outline -41,Media,play,start video audio media,Lucide,import { Play } from 'lucide-react',<Play />,Play button video audio,Outline -42,Media,pause,stop halt video audio,Lucide,import { Pause } from 'lucide-react',<Pause />,Pause button media,Outline -43,Media,volume-2,sound audio speaker music,Lucide,import { Volume2 } from 'lucide-react',<Volume2 />,Volume audio sound,Outline -44,Media,mic,microphone record voice audio,Lucide,import { Mic } from 'lucide-react',<Mic />,Microphone voice record,Outline -45,Media,camera,photo capture snapshot picture,Lucide,import { Camera } from 'lucide-react',<Camera />,Camera photo capture,Outline -46,Commerce,shopping-cart,cart checkout basket buy,Lucide,import { ShoppingCart } from 'lucide-react',<ShoppingCart />,Shopping cart e-commerce,Outline -47,Commerce,shopping-bag,purchase buy store bag,Lucide,import { ShoppingBag } from 'lucide-react',<ShoppingBag />,Shopping bag purchase,Outline -48,Commerce,credit-card,payment card checkout stripe,Lucide,import { CreditCard } from 'lucide-react',<CreditCard />,Payment credit card,Outline -49,Commerce,dollar-sign,money price currency cost,Lucide,import { DollarSign } from 'lucide-react',<DollarSign />,Price money currency,Outline -50,Commerce,tag,label price discount sale,Lucide,import { Tag } from 'lucide-react',<Tag />,Price tag label,Outline -51,Commerce,gift,present reward bonus offer,Lucide,import { Gift } from 'lucide-react',<Gift />,Gift reward offer,Outline -52,Commerce,percent,discount sale offer promo,Lucide,import { Percent } from 'lucide-react',<Percent />,Discount percentage sale,Outline -53,Data,bar-chart,analytics statistics graph metrics,Lucide,import { BarChart } from 'lucide-react',<BarChart />,Bar chart analytics,Outline -54,Data,pie-chart,statistics distribution breakdown,Lucide,import { PieChart } from 'lucide-react',<PieChart />,Pie chart distribution,Outline -55,Data,trending-up,growth increase positive trend,Lucide,import { TrendingUp } from 'lucide-react',<TrendingUp />,Growth trend positive,Outline -56,Data,trending-down,decline decrease negative trend,Lucide,import { TrendingDown } from 'lucide-react',<TrendingDown />,Decline trend negative,Outline -57,Data,activity,pulse heartbeat monitor live,Lucide,import { Activity } from 'lucide-react',<Activity />,Activity monitor pulse,Outline -58,Data,database,storage server data backend,Lucide,import { Database } from 'lucide-react',<Database />,Database storage,Outline -59,Files,file,document page paper doc,Lucide,import { File } from 'lucide-react',<File />,File document,Outline -60,Files,file-text,document text page article,Lucide,import { FileText } from 'lucide-react',<FileText />,Text document article,Outline -61,Files,folder,directory organize group files,Lucide,import { Folder } from 'lucide-react',<Folder />,Folder directory,Outline -62,Files,folder-open,expanded browse files view,Lucide,import { FolderOpen } from 'lucide-react',<FolderOpen />,Open folder browse,Outline -63,Files,paperclip,attachment attach file link,Lucide,import { Paperclip } from 'lucide-react',<Paperclip />,Attachment paperclip,Outline -64,Files,link,url hyperlink chain connect,Lucide,import { Link } from 'lucide-react',<Link />,Link URL hyperlink,Outline -65,Files,clipboard,paste copy buffer notes,Lucide,import { Clipboard } from 'lucide-react',<Clipboard />,Clipboard paste,Outline -66,Layout,grid,tiles gallery layout dashboard,Lucide,import { Grid } from 'lucide-react',<Grid />,Grid layout gallery,Outline -67,Layout,list,rows table lines items,Lucide,import { List } from 'lucide-react',<List />,List view rows,Outline -68,Layout,columns,layout split dual sidebar,Lucide,import { Columns } from 'lucide-react',<Columns />,Column layout split,Outline -69,Layout,maximize,fullscreen expand enlarge zoom,Lucide,import { Maximize } from 'lucide-react',<Maximize />,Fullscreen maximize,Outline -70,Layout,minimize,reduce shrink collapse exit,Lucide,import { Minimize } from 'lucide-react',<Minimize />,Minimize reduce,Outline -71,Layout,sidebar,panel drawer navigation menu,Lucide,import { Sidebar } from 'lucide-react',<Sidebar />,Sidebar panel,Outline -72,Social,heart,like love favorite wishlist,Lucide,import { Heart } from 'lucide-react',<Heart />,Like favorite love,Outline -73,Social,star,rating review favorite bookmark,Lucide,import { Star } from 'lucide-react',<Star />,Star rating favorite,Outline -74,Social,thumbs-up,like approve agree positive,Lucide,import { ThumbsUp } from 'lucide-react',<ThumbsUp />,Like approve thumb,Outline -75,Social,thumbs-down,dislike disapprove disagree negative,Lucide,import { ThumbsDown } from 'lucide-react',<ThumbsDown />,Dislike disapprove,Outline -76,Social,bookmark,save later favorite mark,Lucide,import { Bookmark } from 'lucide-react',<Bookmark />,Bookmark save,Outline -77,Social,flag,report mark important highlight,Lucide,import { Flag } from 'lucide-react',<Flag />,Flag report,Outline -78,Device,smartphone,mobile phone device touch,Lucide,import { Smartphone } from 'lucide-react',<Smartphone />,Mobile smartphone,Outline -79,Device,tablet,ipad device touch screen,Lucide,import { Tablet } from 'lucide-react',<Tablet />,Tablet device,Outline -80,Device,monitor,desktop screen computer display,Lucide,import { Monitor } from 'lucide-react',<Monitor />,Desktop monitor,Outline -81,Device,laptop,notebook computer portable device,Lucide,import { Laptop } from 'lucide-react',<Laptop />,Laptop computer,Outline -82,Device,printer,print document output paper,Lucide,import { Printer } from 'lucide-react',<Printer />,Printer print,Outline -83,Security,lock,secure password protected private,Lucide,import { Lock } from 'lucide-react',<Lock />,Lock secure,Outline -84,Security,unlock,open access unsecure public,Lucide,import { Unlock } from 'lucide-react',<Unlock />,Unlock open,Outline -85,Security,shield,protection security safe guard,Lucide,import { Shield } from 'lucide-react',<Shield />,Shield protection,Outline -86,Security,key,password access unlock login,Lucide,import { Key } from 'lucide-react',<Key />,Key password,Outline -87,Security,eye,view show visible password,Lucide,import { Eye } from 'lucide-react',<Eye />,Show password view,Outline -88,Security,eye-off,hide invisible password hidden,Lucide,import { EyeOff } from 'lucide-react',<EyeOff />,Hide password,Outline -89,Location,map-pin,location marker place address,Lucide,import { MapPin } from 'lucide-react',<MapPin />,Location pin marker,Outline -90,Location,map,directions navigate geography location,Lucide,import { Map } from 'lucide-react',<Map />,Map directions,Outline -91,Location,navigation,compass direction pointer arrow,Lucide,import { Navigation } from 'lucide-react',<Navigation />,Navigation compass,Outline -92,Location,globe,world international global web,Lucide,import { Globe } from 'lucide-react',<Globe />,Globe world,Outline -93,Time,calendar,date schedule event appointment,Lucide,import { Calendar } from 'lucide-react',<Calendar />,Calendar date,Outline -94,Time,refresh-cw,reload sync update refresh,Lucide,import { RefreshCw } from 'lucide-react',<RefreshCw />,Refresh reload,Outline -95,Time,rotate-ccw,undo back revert history,Lucide,import { RotateCcw } from 'lucide-react',<RotateCcw />,Undo revert,Outline -96,Time,rotate-cw,redo forward repeat history,Lucide,import { RotateCw } from 'lucide-react',<RotateCw />,Redo forward,Outline -97,Development,code,develop programming syntax html,Lucide,import { Code } from 'lucide-react',<Code />,Code development,Outline -98,Development,terminal,console cli command shell,Lucide,import { Terminal } from 'lucide-react',<Terminal />,Terminal console,Outline -99,Development,git-branch,version control branch merge,Lucide,import { GitBranch } from 'lucide-react',<GitBranch />,Git branch,Outline -100,Development,github,repository code open source,Lucide,import { Github } from 'lucide-react',<Github />,GitHub repository,Outline diff --git a/.cursor/skills/ui-ux-pro-max/data/landing.csv b/.cursor/skills/ui-ux-pro-max/data/landing.csv deleted file mode 100644 index dd2e775f..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/landing.csv +++ /dev/null @@ -1,31 +0,0 @@ -No,Pattern Name,Keywords,Section Order,Primary CTA Placement,Color Strategy,Recommended Effects,Conversion Optimization -1,Hero + Features + CTA,"hero, hero-centric, features, feature-rich, cta, call-to-action","1. Hero with headline/image, 2. Value prop, 3. Key features (3-5), 4. CTA section, 5. Footer",Hero (sticky) + Bottom,Hero: Brand primary or vibrant. Features: Card bg #FAFAFA. CTA: Contrasting accent color,"Hero parallax, feature card hover lift, CTA glow on hover",Deep CTA placement. Use contrasting color (at least 7:1 contrast ratio). Sticky navbar CTA. -2,Hero + Testimonials + CTA,"hero, testimonials, social-proof, trust, reviews, cta","1. Hero, 2. Problem statement, 3. Solution overview, 4. Testimonials carousel, 5. CTA",Hero (sticky) + Post-testimonials,"Hero: Brand color. Testimonials: Light bg #F5F5F5. Quotes: Italic, muted color #666. CTA: Vibrant","Testimonial carousel slide animations, quote marks animations, avatar fade-in",Social proof before CTA. Use 3-5 testimonials. Include photo + name + role. CTA after social proof. -3,Product Demo + Features,"demo, product-demo, features, showcase, interactive","1. Hero, 2. Product video/mockup (center), 3. Feature breakdown per section, 4. Comparison (optional), 5. CTA",Video center + CTA right/bottom,Video surround: Brand color overlay. Features: Icon color #0080FF. Text: Dark #222,"Video play button pulse, feature scroll reveals, demo interaction highlights",Embedded product demo increases engagement. Use interactive mockup if possible. Auto-play video muted. -4,Minimal Single Column,"minimal, simple, direct, single-column, clean","1. Hero headline, 2. Short description, 3. Benefit bullets (3 max), 4. CTA, 5. Footer","Center, large CTA button",Minimalist: Brand + white #FFFFFF + accent. Buttons: High contrast 7:1+. Text: Black/Dark grey,Minimal hover effects. Smooth scroll. CTA scale on hover (subtle),Single CTA focus. Large typography. Lots of whitespace. No nav clutter. Mobile-first. -5,Funnel (3-Step Conversion),"funnel, conversion, steps, wizard, onboarding","1. Hero, 2. Step 1 (problem), 3. Step 2 (solution), 4. Step 3 (action), 5. CTA progression",Each step: mini-CTA. Final: main CTA,"Step colors: 1 (Red/Problem), 2 (Orange/Process), 3 (Green/Solution). CTA: Brand color","Step number animations, progress bar fill, step transitions smooth scroll",Progressive disclosure. Show only essential info per step. Use progress indicators. Multiple CTAs. -6,Comparison Table + CTA,"comparison, table, compare, versus, cta","1. Hero, 2. Problem intro, 3. Comparison table (product vs competitors), 4. Pricing (optional), 5. CTA",Table: Right column. CTA: Below table,Table: Alternating rows (white/light grey). Your product: Highlight #FFFACD (light yellow) or green. Text: Dark,"Table row hover highlight, price toggle animations, feature checkmark animations",Use comparison to show unique value. Highlight your product row. Include 'free trial' in pricing row. -7,Lead Magnet + Form,"lead, form, signup, capture, email, magnet","1. Hero (benefit headline), 2. Lead magnet preview (ebook cover, checklist, etc), 3. Form (minimal fields), 4. CTA submit",Form CTA: Submit button,Lead magnet: Professional design. Form: Clean white bg. Inputs: Light border #CCCCCC. CTA: Brand color,"Form focus state animations, input validation animations, success confirmation animation",Form fields ≤ 3 for best conversion. Offer valuable lead magnet preview. Show form submission progress. -8,Pricing Page + CTA,"pricing, plans, tiers, comparison, cta","1. Hero (pricing headline), 2. Price comparison cards, 3. Feature comparison table, 4. FAQ section, 5. Final CTA",Each card: CTA button. Sticky CTA in nav,"Free: Grey, Starter: Blue, Pro: Green/Gold, Enterprise: Dark. Cards: 1px border, shadow","Price toggle animation (monthly/yearly), card comparison highlight, FAQ accordion open/close",Recommend starter plan (pre-select/highlight). Show annual discount (20-30%). Use FAQs to address concerns. -9,Video-First Hero,"video, hero, media, visual, engaging","1. Hero with video background, 2. Key features overlay, 3. Benefits section, 4. CTA",Overlay on video (center/bottom) + Bottom section,Dark overlay 60% on video. Brand accent for CTA. White text on dark.,"Video autoplay muted, parallax scroll, text fade-in on scroll",86% higher engagement with video. Add captions for accessibility. Compress video for performance. -10,Scroll-Triggered Storytelling,"storytelling, scroll, narrative, story, immersive","1. Intro hook, 2. Chapter 1 (problem), 3. Chapter 2 (journey), 4. Chapter 3 (solution), 5. Climax CTA",End of each chapter (mini) + Final climax CTA,Progressive reveal. Each chapter has distinct color. Building intensity.,"ScrollTrigger animations, parallax layers, progressive disclosure, chapter transitions",Narrative increases time-on-page 3x. Use progress indicator. Mobile: simplify animations. -11,AI Personalization Landing,"ai, personalization, smart, recommendation, dynamic","1. Dynamic hero (personalized), 2. Relevant features, 3. Tailored testimonials, 4. Smart CTA",Context-aware placement based on user segment,Adaptive based on user data. A/B test color variations per segment.,"Dynamic content swap, fade transitions, personalized product recommendations",20%+ conversion with personalization. Requires analytics integration. Fallback for new users. -12,Waitlist/Coming Soon,"waitlist, coming-soon, launch, early-access, notify","1. Hero with countdown, 2. Product teaser/preview, 3. Email capture form, 4. Social proof (waitlist count)",Email form prominent (above fold) + Sticky form on scroll,Anticipation: Dark + accent highlights. Countdown in brand color. Urgency indicators.,"Countdown timer animation, email validation feedback, success confetti, social share buttons",Scarcity + exclusivity. Show waitlist count. Early access benefits. Referral program. -13,Comparison Table Focus,"comparison, table, versus, compare, features","1. Hero (problem statement), 2. Comparison matrix (you vs competitors), 3. Feature deep-dive, 4. Winner CTA",After comparison table (highlighted row) + Bottom,Your product column highlighted (accent bg or green). Competitors neutral. Checkmarks green.,"Table row hover highlight, feature checkmark animations, sticky comparison header",Show value vs competitors. 35% higher conversion. Be factual. Include pricing if favorable. -14,Pricing-Focused Landing,"pricing, price, cost, plans, subscription","1. Hero (value proposition), 2. Pricing cards (3 tiers), 3. Feature comparison, 4. FAQ, 5. Final CTA",Each pricing card + Sticky CTA in nav + Bottom,Popular plan highlighted (brand color border/bg). Free: grey. Enterprise: dark/premium.,"Price toggle monthly/annual animation, card hover lift, FAQ accordion smooth open",Annual discount 20-30%. Recommend mid-tier (most popular badge). Address objections in FAQ. -15,App Store Style Landing,"app, mobile, download, store, install","1. Hero with device mockup, 2. Screenshots carousel, 3. Features with icons, 4. Reviews/ratings, 5. Download CTAs",Download buttons prominent (App Store + Play Store) throughout,Dark/light matching app store feel. Star ratings in gold. Screenshots with device frames.,"Device mockup rotations, screenshot slider, star rating animations, download button pulse",Show real screenshots. Include ratings (4.5+ stars). QR code for mobile. Platform-specific CTAs. -16,FAQ/Documentation Landing,"faq, documentation, help, support, questions","1. Hero with search bar, 2. Popular categories, 3. FAQ accordion, 4. Contact/support CTA",Search bar prominent + Contact CTA for unresolved questions,"Clean, high readability. Minimal color. Category icons in brand color. Success green for resolved.","Search autocomplete, smooth accordion open/close, category hover, helpful feedback buttons",Reduce support tickets. Track search analytics. Show related articles. Contact escalation path. -17,Immersive/Interactive Experience,"immersive, interactive, experience, 3d, animation","1. Full-screen interactive element, 2. Guided product tour, 3. Key benefits revealed, 4. CTA after completion",After interaction complete + Skip option for impatient users,Immersive experience colors. Dark background for focus. Highlight interactive elements.,"WebGL, 3D interactions, gamification elements, progress indicators, reward animations",40% higher engagement. Performance trade-off. Provide skip option. Mobile fallback essential. -18,Event/Conference Landing,"event, conference, meetup, registration, schedule","1. Hero (date/location/countdown), 2. Speakers grid, 3. Agenda/schedule, 4. Sponsors, 5. Register CTA",Register CTA sticky + After speakers + Bottom,Urgency colors (countdown). Event branding. Speaker cards professional. Sponsor logos neutral.,"Countdown timer, speaker hover cards with bio, agenda tabs, early bird countdown",Early bird pricing with deadline. Social proof (past attendees). Speaker credibility. Multi-ticket discounts. -19,Product Review/Ratings Focused,"reviews, ratings, testimonials, social-proof, stars","1. Hero (product + aggregate rating), 2. Rating breakdown, 3. Individual reviews, 4. Buy/CTA",After reviews summary + Buy button alongside reviews,Trust colors. Star ratings gold. Verified badge green. Review sentiment colors.,"Star fill animations, review filtering, helpful vote interactions, photo lightbox",User-generated content builds trust. Show verified purchases. Filter by rating. Respond to negative reviews. -20,Community/Forum Landing,"community, forum, social, members, discussion","1. Hero (community value prop), 2. Popular topics/categories, 3. Active members showcase, 4. Join CTA",Join button prominent + After member showcase,"Warm, welcoming. Member photos add humanity. Topic badges in brand colors. Activity indicators green.","Member avatars animation, activity feed live updates, topic hover previews, join success celebration","Show active community (member count, posts today). Highlight benefits. Preview content. Easy onboarding." -21,Before-After Transformation,"before-after, transformation, results, comparison","1. Hero (problem state), 2. Transformation slider/comparison, 3. How it works, 4. Results CTA",After transformation reveal + Bottom,Contrast: muted/grey (before) vs vibrant/colorful (after). Success green for results.,"Slider comparison interaction, before/after reveal animations, result counters, testimonial videos",Visual proof of value. 45% higher conversion. Real results. Specific metrics. Guarantee offer. -22,Marketplace / Directory,"marketplace, directory, search, listing","1. Hero (Search focused), 2. Categories, 3. Featured Listings, 4. Trust/Safety, 5. CTA (Become a host/seller)",Hero Search Bar + Navbar 'List your item',Search: High contrast. Categories: Visual icons. Trust: Blue/Green.,Search autocomplete animation," map hover pins, card carousel, Search bar is the CTA. Reduce friction to search. Popular searches suggestions." -23,Newsletter / Content First,"newsletter, content, writer, blog, subscribe","1. Hero (Value Prop + Form), 2. Recent Issues/Archives, 3. Social Proof (Subscriber count), 4. About Author",Hero inline form + Sticky header form,Minimalist. Paper-like background. Text focus. Accent color for Subscribe.,Text highlight animations," typewriter effect, subtle fade-in, Single field form (Email only). Show 'Join X, 000 readers'. Read sample link." -24,Webinar Registration,"webinar, registration, event, training, live","1. Hero (Topic + Timer + Form), 2. What you'll learn, 3. Speaker Bio, 4. Urgency/Bonuses, 5. Form (again)",Hero (Right side form) + Bottom anchor,Urgency: Red/Orange. Professional: Blue/Navy. Form: High contrast white.,Countdown timer," speaker avatar float, urgent ticker, Limited seats logic. 'Live' indicator. Auto-fill timezone." -25,Enterprise Gateway,"enterprise, corporate, gateway, solutions, portal","1. Hero (Video/Mission), 2. Solutions by Industry, 3. Solutions by Role, 4. Client Logos, 5. Contact Sales",Contact Sales (Primary) + Login (Secondary),Corporate: Navy/Grey. High integrity. Conservative accents.,Slow video background," logo carousel, tab switching for industries, Path selection (I am a...). Mega menu navigation. Trust signals prominent." -26,Portfolio Grid,"portfolio, grid, showcase, gallery, masonry","1. Hero (Name/Role), 2. Project Grid (Masonry), 3. About/Philosophy, 4. Contact",Project Card Hover + Footer Contact,Neutral background (let work shine). Text: Black/White. Accent: Minimal.,Image lazy load reveal," hover overlay info, lightbox view, Visuals first. Filter by category. Fast loading essential." -27,Horizontal Scroll Journey,"horizontal, scroll, journey, gallery, storytelling, panoramic","1. Intro (Vertical), 2. The Journey (Horizontal Track), 3. Detail Reveal, 4. Vertical Footer",Floating Sticky CTA or End of Horizontal Track,Continuous palette transition. Chapter colors. Progress bar #000000.,"Scroll-jacking (careful), parallax layers, horizontal slide, progress indicator","Immersive product discovery. High engagement. Keep navigation visible. -28,Bento Grid Showcase,bento, grid, features, modular, apple-style, showcase"", 1. Hero, 2. Bento Grid (Key Features), 3. Detail Cards, 4. Tech Specs, 5. CTA, Floating Action Button or Bottom of Grid, Card backgrounds: #F5F5F7 or Glass. Icons: Vibrant brand colors. Text: Dark., Hover card scale (1.02), video inside cards, tilt effect, staggered reveal, Scannable value props. High information density without clutter. Mobile stack. -29,Interactive 3D Configurator,3d, configurator, customizer, interactive, product"", 1. Hero (Configurator), 2. Feature Highlight (synced), 3. Price/Specs, 4. Purchase, Inside Configurator UI + Sticky Bottom Bar, Neutral studio background. Product: Realistic materials. UI: Minimal overlay., Real-time rendering, material swap animation, camera rotate/zoom, light reflection, Increases ownership feeling. 360 view reduces return rates. Direct add-to-cart. -30,AI-Driven Dynamic Landing,ai, dynamic, personalized, adaptive, generative"", 1. Prompt/Input Hero, 2. Generated Result Preview, 3. How it Works, 4. Value Prop, Input Field (Hero) + 'Try it' Buttons, Adaptive to user input. Dark mode for compute feel. Neon accents., Typing text effects, shimmering generation loaders, morphing layouts, Immediate value demonstration. 'Show, don't tell'. Low friction start." diff --git a/.cursor/skills/ui-ux-pro-max/data/products.csv b/.cursor/skills/ui-ux-pro-max/data/products.csv deleted file mode 100644 index 6ff9ba43..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/products.csv +++ /dev/null @@ -1,97 +0,0 @@ -No,Product Type,Keywords,Primary Style Recommendation,Secondary Styles,Landing Page Pattern,Dashboard Style (if applicable),Color Palette Focus,Key Considerations -1,SaaS (General),"app, b2b, cloud, general, saas, software, subscription",Glassmorphism + Flat Design,"Soft UI Evolution, Minimalism",Hero + Features + CTA,Data-Dense + Real-Time Monitoring,Trust blue + accent contrast,Balance modern feel with clarity. Focus on CTAs. -2,Micro SaaS,"app, b2b, cloud, indie, micro, micro-saas, niche, saas, small, software, solo, subscription",Flat Design + Vibrant & Block,"Motion-Driven, Micro-interactions",Minimal & Direct + Demo,Executive Dashboard,Vibrant primary + white space,"Keep simple, show product quickly. Speed is key." -3,E-commerce,"buy, commerce, e, ecommerce, products, retail, sell, shop, store",Vibrant & Block-based,"Aurora UI, Motion-Driven",Feature-Rich Showcase,Sales Intelligence Dashboard,Brand primary + success green,Engagement & conversions. High visual hierarchy. -4,E-commerce Luxury,"buy, commerce, e, ecommerce, elegant, exclusive, high-end, luxury, premium, products, retail, sell, shop, store",Liquid Glass + Glassmorphism,"3D & Hyperrealism, Aurora UI",Feature-Rich Showcase,Sales Intelligence Dashboard,Premium colors + minimal accent,Elegance & sophistication. Premium materials. -5,Service Landing Page,"appointment, booking, consultation, conversion, landing, marketing, page, service",Hero-Centric + Trust & Authority,"Social Proof-Focused, Storytelling",Hero-Centric Design,N/A - Analytics for conversions,Brand primary + trust colors,Social proof essential. Show expertise. -6,B2B Service,"appointment, b, b2b, booking, business, consultation, corporate, enterprise, service",Trust & Authority + Minimal,"Feature-Rich, Conversion-Optimized",Feature-Rich Showcase,Sales Intelligence Dashboard,Professional blue + neutral grey,Credibility essential. Clear ROI messaging. -7,Financial Dashboard,"admin, analytics, dashboard, data, financial, panel",Dark Mode (OLED) + Data-Dense,"Minimalism, Accessible & Ethical",N/A - Dashboard focused,Financial Dashboard,Dark bg + red/green alerts + trust blue,"High contrast, real-time updates, accuracy paramount." -8,Analytics Dashboard,"admin, analytics, dashboard, data, panel",Data-Dense + Heat Map & Heatmap,"Minimalism, Dark Mode (OLED)",N/A - Analytics focused,Drill-Down Analytics + Comparative,Cool→Hot gradients + neutral grey,Clarity > aesthetics. Color-coded data priority. -9,Healthcare App,"app, clinic, health, healthcare, medical, patient",Neumorphism + Accessible & Ethical,"Soft UI Evolution, Claymorphism (for patients)",Social Proof-Focused,User Behavior Analytics,Calm blue + health green + trust,Accessibility mandatory. Calming aesthetic. -10,Educational App,"app, course, education, educational, learning, school, training",Claymorphism + Micro-interactions,"Vibrant & Block-based, Flat Design",Storytelling-Driven,User Behavior Analytics,Playful colors + clear hierarchy,Engagement & ease of use. Age-appropriate design. -11,Creative Agency,"agency, creative, design, marketing, studio",Brutalism + Motion-Driven,"Retro-Futurism, Storytelling-Driven",Storytelling-Driven,N/A - Portfolio focused,Bold primaries + artistic freedom,Differentiation key. Wow-factor necessary. -12,Portfolio/Personal,"creative, personal, portfolio, projects, showcase, work",Motion-Driven + Minimalism,"Brutalism, Aurora UI",Storytelling-Driven,N/A - Personal branding,Brand primary + artistic interpretation,Showcase work. Personality shine through. -13,Gaming,"entertainment, esports, game, gaming, play",3D & Hyperrealism + Retro-Futurism,"Motion-Driven, Vibrant & Block",Feature-Rich Showcase,N/A - Game focused,Vibrant + neon + immersive colors,Immersion priority. Performance critical. -14,Government/Public Service,"appointment, booking, consultation, government, public, service",Accessible & Ethical + Minimalism,"Flat Design, Inclusive Design",Minimal & Direct,Executive Dashboard,Professional blue + high contrast,WCAG AAA mandatory. Trust paramount. -15,Fintech/Crypto,"banking, blockchain, crypto, defi, finance, fintech, money, nft, payment, web3",Glassmorphism + Dark Mode (OLED),"Retro-Futurism, Motion-Driven",Conversion-Optimized,Real-Time Monitoring + Predictive,Dark tech colors + trust + vibrant accents,Security perception. Real-time data critical. -16,Social Media App,"app, community, content, entertainment, media, network, sharing, social, streaming, users, video",Vibrant & Block-based + Motion-Driven,"Aurora UI, Micro-interactions",Feature-Rich Showcase,User Behavior Analytics,Vibrant + engagement colors,Engagement & retention. Addictive design ethics. -17,Productivity Tool,"collaboration, productivity, project, task, tool, workflow",Flat Design + Micro-interactions,"Minimalism, Soft UI Evolution",Interactive Product Demo,Drill-Down Analytics,Clear hierarchy + functional colors,Ease of use. Speed & efficiency focus. -18,Design System/Component Library,"component, design, library, system",Minimalism + Accessible & Ethical,"Flat Design, Zero Interface",Feature-Rich Showcase,N/A - Dev focused,Clear hierarchy + code-like structure,Consistency. Developer-first approach. -19,AI/Chatbot Platform,"ai, artificial-intelligence, automation, chatbot, machine-learning, ml, platform",AI-Native UI + Minimalism,"Zero Interface, Glassmorphism",Interactive Product Demo,AI/ML Analytics Dashboard,Neutral + AI Purple (#6366F1),Conversational UI. Streaming text. Context awareness. Minimal chrome. -20,NFT/Web3 Platform,"nft, platform, web",Cyberpunk UI + Glassmorphism,"Aurora UI, 3D & Hyperrealism",Feature-Rich Showcase,Crypto/Blockchain Dashboard,Dark + Neon + Gold (#FFD700),Wallet integration. Transaction feedback. Gas fees display. Dark mode essential. -21,Creator Economy Platform,"creator, economy, platform",Vibrant & Block-based + Bento Box Grid,"Motion-Driven, Aurora UI",Social Proof-Focused,User Behavior Analytics,Vibrant + Brand colors,Creator profiles. Monetization display. Engagement metrics. Social proof. -22,Sustainability/ESG Platform,"ai, artificial-intelligence, automation, esg, machine-learning, ml, platform, sustainability",Organic Biophilic + Minimalism,"Accessible & Ethical, Flat Design",Trust & Authority,Energy/Utilities Dashboard,Green (#228B22) + Earth tones,Carbon footprint visuals. Progress indicators. Certification badges. Eco-friendly imagery. -23,Remote Work/Collaboration Tool,"collaboration, remote, tool, work",Soft UI Evolution + Minimalism,"Glassmorphism, Micro-interactions",Feature-Rich Showcase,Drill-Down Analytics,Calm Blue + Neutral grey,Real-time collaboration. Status indicators. Video integration. Notification management. -24,Mental Health App,"app, health, mental",Neumorphism + Accessible & Ethical,"Claymorphism, Soft UI Evolution",Social Proof-Focused,Healthcare Analytics,Calm Pastels + Trust colors,Calming aesthetics. Privacy-first. Crisis resources. Progress tracking. Accessibility mandatory. -25,Pet Tech App,"app, pet, tech",Claymorphism + Vibrant & Block-based,"Micro-interactions, Flat Design",Storytelling-Driven,User Behavior Analytics,Playful + Warm colors,Pet profiles. Health tracking. Playful UI. Photo galleries. Vet integration. -26,Smart Home/IoT Dashboard,"admin, analytics, dashboard, data, home, iot, panel, smart",Glassmorphism + Dark Mode (OLED),"Minimalism, AI-Native UI",Interactive Product Demo,Real-Time Monitoring,Dark + Status indicator colors,Device status. Real-time controls. Energy monitoring. Automation rules. Quick actions. -27,EV/Charging Ecosystem,"charging, ecosystem, ev",Minimalism + Aurora UI,"Glassmorphism, Organic Biophilic",Hero-Centric Design,Energy/Utilities Dashboard,Electric Blue (#009CD1) + Green,Charging station maps. Range estimation. Cost calculation. Environmental impact. -28,Subscription Box Service,"appointment, booking, box, consultation, membership, plan, recurring, service, subscription",Vibrant & Block-based + Motion-Driven,"Claymorphism, Aurora UI",Feature-Rich Showcase,E-commerce Analytics,Brand + Excitement colors,Unboxing experience. Personalization quiz. Subscription management. Product reveals. -29,Podcast Platform,"platform, podcast",Dark Mode (OLED) + Minimalism,"Motion-Driven, Vibrant & Block-based",Storytelling-Driven,Media/Entertainment Dashboard,Dark + Audio waveform accents,Audio player UX. Episode discovery. Creator tools. Analytics for podcasters. -30,Dating App,"app, dating",Vibrant & Block-based + Motion-Driven,"Aurora UI, Glassmorphism",Social Proof-Focused,User Behavior Analytics,Warm + Romantic (Pink/Red gradients),Profile cards. Swipe interactions. Match animations. Safety features. Video chat. -31,Micro-Credentials/Badges Platform,"badges, credentials, micro, platform",Minimalism + Flat Design,"Accessible & Ethical, Swiss Modernism 2.0",Trust & Authority,Education Dashboard,Trust Blue + Gold (#FFD700),Credential verification. Badge display. Progress tracking. Issuer trust. LinkedIn integration. -32,Knowledge Base/Documentation,"base, documentation, knowledge",Minimalism + Accessible & Ethical,"Swiss Modernism 2.0, Flat Design",FAQ/Documentation,N/A - Documentation focused,Clean hierarchy + minimal color,Search-first. Clear navigation. Code highlighting. Version switching. Feedback system. -33,Hyperlocal Services,"appointment, booking, consultation, hyperlocal, service, services",Minimalism + Vibrant & Block-based,"Micro-interactions, Flat Design",Conversion-Optimized,Drill-Down Analytics + Map,Location markers + Trust colors,Map integration. Service categories. Provider profiles. Booking system. Reviews. -34,Beauty/Spa/Wellness Service,"appointment, beauty, booking, consultation, service, spa, wellness",Soft UI Evolution + Neumorphism,"Glassmorphism, Minimalism",Hero-Centric Design + Social Proof,User Behavior Analytics,Soft pastels (Pink #FFB6C1 Sage #90EE90) + Cream + Gold accents,Calming aesthetic. Booking system. Service menu. Before/after gallery. Testimonials. Relaxing imagery. -35,Luxury/Premium Brand,"brand, elegant, exclusive, high-end, luxury, premium",Liquid Glass + Glassmorphism,"Minimalism, 3D & Hyperrealism",Storytelling-Driven + Feature-Rich,Sales Intelligence Dashboard,Black + Gold (#FFD700) + White + Minimal accent,Elegance paramount. Premium imagery. Storytelling. High-quality visuals. Exclusive feel. -36,Restaurant/Food Service,"appointment, booking, consultation, delivery, food, menu, order, restaurant, service",Vibrant & Block-based + Motion-Driven,"Claymorphism, Flat Design",Hero-Centric Design + Conversion,N/A - Booking focused,Warm colors (Orange Red Brown) + appetizing imagery,Menu display. Online ordering. Reservation system. Food photography. Location/hours prominent. -37,Fitness/Gym App,"app, exercise, fitness, gym, health, workout",Vibrant & Block-based + Dark Mode (OLED),"Motion-Driven, Neumorphism",Feature-Rich Showcase,User Behavior Analytics,Energetic (Orange #FF6B35 Electric Blue) + Dark bg,Progress tracking. Workout plans. Community features. Achievements. Motivational design. -38,Real Estate/Property,"buy, estate, housing, property, real, real-estate, rent",Glassmorphism + Minimalism,"Motion-Driven, 3D & Hyperrealism",Hero-Centric Design + Feature-Rich,Sales Intelligence Dashboard,Trust Blue (#0077B6) + Gold accents + White,Property listings. Virtual tours. Map integration. Agent profiles. Mortgage calculator. High-quality imagery. -39,Travel/Tourism Agency,"agency, booking, creative, design, flight, hotel, marketing, studio, tourism, travel, vacation",Aurora UI + Motion-Driven,"Vibrant & Block-based, Glassmorphism",Storytelling-Driven + Hero-Centric,Booking Analytics,Vibrant destination colors + Sky Blue + Warm accents,Destination showcase. Booking system. Itinerary builder. Reviews. Inspiration galleries. Mobile-first. -40,Hotel/Hospitality,"hospitality, hotel",Liquid Glass + Minimalism,"Glassmorphism, Soft UI Evolution",Hero-Centric Design + Social Proof,Revenue Management Dashboard,Warm neutrals + Gold (#D4AF37) + Brand accent,Room booking. Amenities showcase. Location maps. Guest reviews. Seasonal pricing. Luxury imagery. -41,Wedding/Event Planning,"conference, event, meetup, planning, registration, ticket, wedding",Soft UI Evolution + Aurora UI,"Glassmorphism, Motion-Driven",Storytelling-Driven + Social Proof,N/A - Planning focused,Soft Pink (#FFD6E0) + Gold + Cream + Sage,Portfolio gallery. Vendor directory. Planning tools. Timeline. Budget tracker. Romantic aesthetic. -42,Legal Services,"appointment, attorney, booking, compliance, consultation, contract, law, legal, service, services",Trust & Authority + Minimalism,"Accessible & Ethical, Swiss Modernism 2.0",Trust & Authority + Minimal,Case Management Dashboard,Navy Blue (#1E3A5F) + Gold + White,Credibility paramount. Practice areas. Attorney profiles. Case results. Contact forms. Professional imagery. -43,Insurance Platform,"insurance, platform",Trust & Authority + Flat Design,"Accessible & Ethical, Minimalism",Conversion-Optimized + Trust,Claims Analytics Dashboard,Trust Blue (#0066CC) + Green (security) + Neutral,Quote calculator. Policy comparison. Claims process. Trust signals. Clear pricing. Security badges. -44,Banking/Traditional Finance,"banking, finance, traditional",Minimalism + Accessible & Ethical,"Trust & Authority, Dark Mode (OLED)",Trust & Authority + Feature-Rich,Financial Dashboard,Navy (#0A1628) + Trust Blue + Gold accents,Security-first. Account overview. Transaction history. Mobile banking. Accessibility critical. Trust paramount. -45,Online Course/E-learning,"course, e, learning, online",Claymorphism + Vibrant & Block-based,"Motion-Driven, Flat Design",Feature-Rich Showcase + Social Proof,Education Dashboard,Vibrant learning colors + Progress green,Course catalog. Progress tracking. Video player. Quizzes. Certificates. Community forums. Gamification. -46,Non-profit/Charity,"charity, non, profit",Accessible & Ethical + Organic Biophilic,"Minimalism, Storytelling-Driven",Storytelling-Driven + Trust,Donation Analytics Dashboard,Cause-related colors + Trust + Warm,Impact stories. Donation flow. Transparency reports. Volunteer signup. Event calendar. Emotional connection. -47,Music Streaming,"music, streaming",Dark Mode (OLED) + Vibrant & Block-based,"Motion-Driven, Aurora UI",Feature-Rich Showcase,Media/Entertainment Dashboard,Dark (#121212) + Vibrant accents + Album art colors,Audio player. Playlist management. Artist pages. Personalization. Social features. Waveform visualizations. -48,Video Streaming/OTT,"ott, streaming, video",Dark Mode (OLED) + Motion-Driven,"Glassmorphism, Vibrant & Block-based",Hero-Centric Design + Feature-Rich,Media/Entertainment Dashboard,Dark bg + Content poster colors + Brand accent,Video player. Content discovery. Watchlist. Continue watching. Personalized recommendations. Thumbnail-heavy. -49,Job Board/Recruitment,"board, job, recruitment",Flat Design + Minimalism,"Vibrant & Block-based, Accessible & Ethical",Conversion-Optimized + Feature-Rich,HR Analytics Dashboard,Professional Blue + Success Green + Neutral,Job listings. Search/filter. Company profiles. Application tracking. Resume upload. Salary insights. -50,Marketplace (P2P),"buyers, listings, marketplace, p, platform, sellers",Vibrant & Block-based + Flat Design,"Micro-interactions, Trust & Authority",Feature-Rich Showcase + Social Proof,E-commerce Analytics,Trust colors + Category colors + Success green,Seller/buyer profiles. Listings. Reviews/ratings. Secure payment. Messaging. Search/filter. Trust badges. -51,Logistics/Delivery,"delivery, logistics",Minimalism + Flat Design,"Dark Mode (OLED), Micro-interactions",Feature-Rich Showcase + Conversion,Real-Time Monitoring + Route Analytics,Blue (#2563EB) + Orange (tracking) + Green (delivered),Real-time tracking. Delivery scheduling. Route optimization. Driver management. Status updates. Map integration. -52,Agriculture/Farm Tech,"agriculture, farm, tech",Organic Biophilic + Flat Design,"Minimalism, Accessible & Ethical",Feature-Rich Showcase + Trust,IoT Sensor Dashboard,Earth Green (#4A7C23) + Brown + Sky Blue,Crop monitoring. Weather data. IoT sensors. Yield tracking. Market prices. Sustainable imagery. -53,Construction/Architecture,"architecture, construction",Minimalism + 3D & Hyperrealism,"Brutalism, Swiss Modernism 2.0",Hero-Centric Design + Feature-Rich,Project Management Dashboard,Grey (#4A4A4A) + Orange (safety) + Blueprint Blue,Project portfolio. 3D renders. Timeline. Material specs. Team collaboration. Blueprint aesthetic. -54,Automotive/Car Dealership,"automotive, car, dealership",Motion-Driven + 3D & Hyperrealism,"Dark Mode (OLED), Glassmorphism",Hero-Centric Design + Feature-Rich,Sales Intelligence Dashboard,Brand colors + Metallic accents + Dark/Light,Vehicle showcase. 360° views. Comparison tools. Financing calculator. Test drive booking. High-quality imagery. -55,Photography Studio,"photography, studio",Motion-Driven + Minimalism,"Aurora UI, Glassmorphism",Storytelling-Driven + Hero-Centric,N/A - Portfolio focused,Black + White + Minimal accent,Portfolio gallery. Before/after. Service packages. Booking system. Client galleries. Full-bleed imagery. -56,Coworking Space,"coworking, space",Vibrant & Block-based + Glassmorphism,"Minimalism, Motion-Driven",Hero-Centric Design + Feature-Rich,Occupancy Dashboard,Energetic colors + Wood tones + Brand accent,Space tour. Membership plans. Booking system. Amenities. Community events. Virtual tour. -57,Cleaning Service,"appointment, booking, cleaning, consultation, service",Soft UI Evolution + Flat Design,"Minimalism, Micro-interactions",Conversion-Optimized + Trust,Service Analytics,Fresh Blue (#00B4D8) + Clean White + Green,Service packages. Booking system. Price calculator. Before/after gallery. Reviews. Trust badges. -58,Home Services (Plumber/Electrician),"appointment, booking, consultation, electrician, home, plumber, service, services",Flat Design + Trust & Authority,"Minimalism, Accessible & Ethical",Conversion-Optimized + Trust,Service Analytics,Trust Blue + Safety Orange + Professional grey,Service list. Emergency contact. Booking. Price transparency. Certifications. Local trust signals. -59,Childcare/Daycare,"childcare, daycare",Claymorphism + Vibrant & Block-based,"Soft UI Evolution, Accessible & Ethical",Social Proof-Focused + Trust,Parent Dashboard,Playful pastels + Safe colors + Warm accents,Programs. Staff profiles. Safety certifications. Parent portal. Activity updates. Cheerful imagery. -60,Senior Care/Elderly,"care, elderly, senior",Accessible & Ethical + Soft UI Evolution,"Minimalism, Neumorphism",Trust & Authority + Social Proof,Healthcare Analytics,Calm Blue + Warm neutrals + Large text,Care services. Staff qualifications. Facility tour. Family portal. Large touch targets. High contrast. Accessibility-first. -61,Medical Clinic,"clinic, medical",Accessible & Ethical + Minimalism,"Neumorphism, Trust & Authority",Trust & Authority + Conversion,Healthcare Analytics,Medical Blue (#0077B6) + Trust White + Calm Green,Services. Doctor profiles. Online booking. Patient portal. Insurance info. HIPAA compliant. Trust signals. -62,Pharmacy/Drug Store,"drug, pharmacy, store",Flat Design + Accessible & Ethical,"Minimalism, Trust & Authority",Conversion-Optimized + Trust,Inventory Dashboard,Pharmacy Green + Trust Blue + Clean White,Product catalog. Prescription upload. Refill reminders. Health info. Store locator. Safety certifications. -63,Dental Practice,"dental, practice",Soft UI Evolution + Minimalism,"Accessible & Ethical, Trust & Authority",Social Proof-Focused + Conversion,Patient Analytics,Fresh Blue + White + Smile Yellow accent,Services. Dentist profiles. Before/after. Online booking. Insurance. Patient testimonials. Friendly imagery. -64,Veterinary Clinic,"clinic, veterinary",Claymorphism + Accessible & Ethical,"Soft UI Evolution, Flat Design",Social Proof-Focused + Trust,Pet Health Dashboard,Caring Blue + Pet-friendly colors + Warm accents,Pet services. Vet profiles. Online booking. Pet portal. Emergency info. Friendly animal imagery. -65,Florist/Plant Shop,"florist, plant, shop",Organic Biophilic + Vibrant & Block-based,"Aurora UI, Motion-Driven",Hero-Centric Design + Conversion,E-commerce Analytics,Natural Green + Floral pinks/purples + Earth tones,Product catalog. Occasion categories. Delivery scheduling. Care guides. Seasonal collections. Beautiful imagery. -66,Bakery/Cafe,"bakery, cafe",Vibrant & Block-based + Soft UI Evolution,"Claymorphism, Motion-Driven",Hero-Centric Design + Conversion,N/A - Order focused,Warm Brown + Cream + Appetizing accents,Menu display. Online ordering. Location/hours. Catering. Seasonal specials. Appetizing photography. -67,Coffee Shop,"coffee, shop",Minimalism + Organic Biophilic,"Soft UI Evolution, Flat Design",Hero-Centric Design + Conversion,N/A - Order focused,Coffee Brown (#6F4E37) + Cream + Warm accents,Menu. Online ordering. Loyalty program. Location. Story/origin. Cozy aesthetic. -68,Brewery/Winery,"brewery, winery",Motion-Driven + Storytelling-Driven,"Dark Mode (OLED), Organic Biophilic",Storytelling-Driven + Hero-Centric,N/A - E-commerce focused,Deep amber/burgundy + Gold + Craft aesthetic,Product showcase. Story/heritage. Tasting notes. Events. Club membership. Artisanal imagery. -69,Airline,"ai, airline, artificial-intelligence, automation, machine-learning, ml",Minimalism + Glassmorphism,"Motion-Driven, Accessible & Ethical",Conversion-Optimized + Feature-Rich,Operations Dashboard,Sky Blue + Brand colors + Trust accents,Flight search. Booking. Check-in. Boarding pass. Loyalty program. Route maps. Mobile-first. -70,News/Media Platform,"content, entertainment, media, news, platform, streaming, video",Minimalism + Flat Design,"Dark Mode (OLED), Accessible & Ethical",Hero-Centric Design + Feature-Rich,Media Analytics Dashboard,Brand colors + High contrast + Category colors,Article layout. Breaking news. Categories. Search. Subscription. Mobile reading. Fast loading. -71,Magazine/Blog,"articles, blog, content, magazine, posts, writing",Swiss Modernism 2.0 + Motion-Driven,"Minimalism, Aurora UI",Storytelling-Driven + Hero-Centric,Content Analytics,Editorial colors + Brand primary + Clean white,Article showcase. Category navigation. Author profiles. Newsletter signup. Related content. Typography-focused. -72,Freelancer Platform,"freelancer, platform",Flat Design + Minimalism,"Vibrant & Block-based, Micro-interactions",Feature-Rich Showcase + Conversion,Marketplace Analytics,Professional Blue + Success Green + Neutral,Profile creation. Portfolio. Skill matching. Messaging. Payment. Reviews. Project management. -73,Consulting Firm,"consulting, firm",Trust & Authority + Minimalism,"Swiss Modernism 2.0, Accessible & Ethical",Trust & Authority + Feature-Rich,N/A - Lead generation,Navy + Gold + Professional grey,Service areas. Case studies. Team profiles. Thought leadership. Contact. Professional credibility. -74,Marketing Agency,"agency, creative, design, marketing, studio",Brutalism + Motion-Driven,"Vibrant & Block-based, Aurora UI",Storytelling-Driven + Feature-Rich,Campaign Analytics,Bold brand colors + Creative freedom,Portfolio. Case studies. Services. Team. Creative showcase. Results-focused. Bold aesthetic. -75,Event Management,"conference, event, management, meetup, registration, ticket",Vibrant & Block-based + Motion-Driven,"Glassmorphism, Aurora UI",Hero-Centric Design + Feature-Rich,Event Analytics,Event theme colors + Excitement accents,Event showcase. Registration. Agenda. Speakers. Sponsors. Ticket sales. Countdown timer. -76,Conference/Webinar Platform,"conference, platform, webinar",Glassmorphism + Minimalism,"Motion-Driven, Flat Design",Feature-Rich Showcase + Conversion,Attendee Analytics,Professional Blue + Video accent + Brand,Registration. Agenda. Speaker profiles. Live stream. Networking. Recording access. Virtual event features. -77,Membership/Community,"community, membership",Vibrant & Block-based + Soft UI Evolution,"Bento Box Grid, Micro-interactions",Social Proof-Focused + Conversion,Community Analytics,Community brand colors + Engagement accents,Member benefits. Pricing tiers. Community showcase. Events. Member directory. Exclusive content. -78,Newsletter Platform,"newsletter, platform",Minimalism + Flat Design,"Swiss Modernism 2.0, Accessible & Ethical",Minimal & Direct + Conversion,Email Analytics,Brand primary + Clean white + CTA accent,Subscribe form. Archive. About. Social proof. Sample content. Simple conversion. -79,Digital Products/Downloads,"digital, downloads, products",Vibrant & Block-based + Motion-Driven,"Glassmorphism, Bento Box Grid",Feature-Rich Showcase + Conversion,E-commerce Analytics,Product category colors + Brand + Success green,Product showcase. Preview. Pricing. Instant delivery. License management. Customer reviews. -80,Church/Religious Organization,"church, organization, religious",Accessible & Ethical + Soft UI Evolution,"Minimalism, Trust & Authority",Hero-Centric Design + Social Proof,N/A - Community focused,Warm Gold + Deep Purple/Blue + White,Service times. Events. Sermons. Community. Giving. Location. Welcoming imagery. -81,Sports Team/Club,"club, sports, team",Vibrant & Block-based + Motion-Driven,"Dark Mode (OLED), 3D & Hyperrealism",Hero-Centric Design + Feature-Rich,Performance Analytics,Team colors + Energetic accents,Schedule. Roster. News. Tickets. Merchandise. Fan engagement. Action imagery. -82,Museum/Gallery,"gallery, museum",Minimalism + Motion-Driven,"Swiss Modernism 2.0, 3D & Hyperrealism",Storytelling-Driven + Feature-Rich,Visitor Analytics,Art-appropriate neutrals + Exhibition accents,Exhibitions. Collections. Tickets. Events. Virtual tours. Educational content. Art-focused design. -83,Theater/Cinema,"cinema, theater",Dark Mode (OLED) + Motion-Driven,"Vibrant & Block-based, Glassmorphism",Hero-Centric Design + Conversion,Booking Analytics,Dark + Spotlight accents + Gold,Showtimes. Seat selection. Trailers. Coming soon. Membership. Dramatic imagery. -84,Language Learning App,"app, language, learning",Claymorphism + Vibrant & Block-based,"Micro-interactions, Flat Design",Feature-Rich Showcase + Social Proof,Learning Analytics,Playful colors + Progress indicators + Country flags,Lesson structure. Progress tracking. Gamification. Speaking practice. Community. Achievement badges. -85,Coding Bootcamp,"bootcamp, coding",Dark Mode (OLED) + Minimalism,"Cyberpunk UI, Flat Design",Feature-Rich Showcase + Social Proof,Student Analytics,Code editor colors + Brand + Success green,Curriculum. Projects. Career outcomes. Alumni. Pricing. Application. Terminal aesthetic. -86,Cybersecurity Platform,"cyber, security, platform",Cyberpunk UI + Dark Mode (OLED),"Neubrutalism, Minimal & Direct",Trust & Authority + Real-Time,Real-Time Monitoring + Heat Map,Matrix Green + Deep Black + Terminal feel,Data density. Threat visualization. Dark mode default. -87,Developer Tool / IDE,"dev, developer, tool, ide",Dark Mode (OLED) + Minimalism,"Flat Design, Bento Box Grid",Minimal & Direct + Documentation,Real-Time Monitor + Terminal,Dark syntax theme colors + Blue focus,Keyboard shortcuts. Syntax highlighting. Fast performance. -88,Biotech / Life Sciences,"biotech, biology, science",Glassmorphism + Clean Science,"Minimalism, Organic Biophilic",Storytelling-Driven + Research,Data-Dense + Predictive,Sterile White + DNA Blue + Life Green,Data accuracy. Cleanliness. Complex data viz. -89,Space Tech / Aerospace,"aerospace, space, tech",Holographic / HUD + Dark Mode,"Glassmorphism, 3D & Hyperrealism",Immersive Experience + Hero,Real-Time Monitoring + 3D,Deep Space Black + Star White + Metallic,High-tech feel. Precision. Telemetry data. -90,Architecture / Interior,"architecture, design, interior",Exaggerated Minimalism + High Imagery,"Swiss Modernism 2.0, Parallax",Portfolio Grid + Visuals,Project Management + Gallery,Monochrome + Gold Accent + High Imagery,High-res images. Typography. Space. -91,Quantum Computing Interface,"quantum, computing, physics, qubit, future, science",Holographic / HUD + Dark Mode,"Glassmorphism, Spatial UI",Immersive/Interactive Experience,3D Spatial Data + Real-Time Monitor,Quantum Blue #00FFFF + Deep Black + Interference patterns,Visualize complexity. Qubit states. Probability clouds. High-tech trust. -92,Biohacking / Longevity App,"biohacking, health, longevity, tracking, wellness, science",Biomimetic / Organic 2.0,"Minimalism, Dark Mode (OLED)",Data-Dense + Storytelling,Real-Time Monitor + Biological Data,Cellular Pink/Red + DNA Blue + Clean White,Personal data privacy. Scientific credibility. Biological visualizations. -93,Autonomous Drone Fleet Manager,"drone, autonomous, fleet, aerial, logistics, robotics",HUD / Sci-Fi FUI,"Real-Time Monitor, Spatial UI",Real-Time Monitor,Geographic + Real-Time,Tactical Green #00FF00 + Alert Red + Map Dark,Real-time telemetry. 3D spatial awareness. Latency indicators. Safety alerts. -94,Generative Art Platform,"art, generative, ai, creative, platform, gallery",Minimalism (Frame) + Gen Z Chaos,"Masonry Grid, Dark Mode",Bento Grid Showcase,Gallery / Portfolio,Neutral #F5F5F5 (Canvas) + User Content,Content is king. Fast loading. Creator attribution. Minting flow. -95,Spatial Computing OS / App,"spatial, vr, ar, vision, os, immersive, mixed-reality",Spatial UI (VisionOS),"Glassmorphism, 3D & Hyperrealism",Immersive/Interactive Experience,Spatial Dashboard,Frosted Glass + System Colors + Depth,Gaze/Pinch interaction. Depth hierarchy. Environment awareness. -96,Sustainable Energy / Climate Tech,"climate, energy, sustainable, green, tech, carbon",Organic Biophilic + E-Ink / Paper,"Data-Dense, Swiss Modernism",Interactive Demo + Data,Energy/Utilities Dashboard,Earth Green + Sky Blue + Solar Yellow,Data transparency. Impact visualization. Low-carbon web design. \ No newline at end of file diff --git a/.cursor/skills/ui-ux-pro-max/data/react-performance.csv b/.cursor/skills/ui-ux-pro-max/data/react-performance.csv deleted file mode 100644 index 671465f2..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/react-performance.csv +++ /dev/null @@ -1,45 +0,0 @@ -No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity -1,Async Waterfall,Defer Await,async await defer branch,React/Next.js,Move await into branches where actually used to avoid blocking unused code paths,Move await operations into branches where they're needed,Await at top of function blocking all branches,"if (skip) return { skipped: true }; const data = await fetch()","const data = await fetch(); if (skip) return { skipped: true }",Critical -2,Async Waterfall,Promise.all Parallel,promise all parallel concurrent,React/Next.js,Execute independent async operations concurrently using Promise.all(),Use Promise.all() for independent operations,Sequential await for independent operations,"const [user, posts] = await Promise.all([fetchUser(), fetchPosts()])","const user = await fetchUser(); const posts = await fetchPosts()",Critical -3,Async Waterfall,Dependency Parallelization,better-all dependency parallel,React/Next.js,Use better-all for operations with partial dependencies to maximize parallelism,Use better-all to start each task at earliest possible moment,Wait for unrelated data before starting dependent fetch,"await all({ user() {}, config() {}, profile() { return fetch((await this.$.user).id) } })","const [user, config] = await Promise.all([...]); const profile = await fetchProfile(user.id)",Critical -4,Async Waterfall,API Route Optimization,api route waterfall promise,React/Next.js,In API routes start independent operations immediately even if not awaited yet,Start promises early and await late,Sequential awaits in API handlers,"const sessionP = auth(); const configP = fetchConfig(); const session = await sessionP","const session = await auth(); const config = await fetchConfig()",Critical -5,Async Waterfall,Suspense Boundaries,suspense streaming boundary,React/Next.js,Use Suspense to show wrapper UI faster while data loads,Wrap async components in Suspense boundaries,Await data blocking entire page render,"<Suspense fallback={<Skeleton />}><DataDisplay /></Suspense>","const data = await fetchData(); return <DataDisplay data={data} />",High -6,Bundle Size,Barrel Imports,barrel import direct path,React/Next.js,Import directly from source files instead of barrel files to avoid loading unused modules,Import directly from source path,Import from barrel/index files,"import Check from 'lucide-react/dist/esm/icons/check'","import { Check } from 'lucide-react'",Critical -7,Bundle Size,Dynamic Imports,dynamic import lazy next,React/Next.js,Use next/dynamic to lazy-load large components not needed on initial render,Use dynamic() for heavy components,Import heavy components at top level,"const Monaco = dynamic(() => import('./monaco'), { ssr: false })","import { MonacoEditor } from './monaco-editor'",Critical -8,Bundle Size,Defer Third Party,analytics defer third-party,React/Next.js,Load analytics and logging after hydration since they don't block interaction,Load non-critical scripts after hydration,Include analytics in main bundle,"const Analytics = dynamic(() => import('@vercel/analytics'), { ssr: false })","import { Analytics } from '@vercel/analytics/react'",Medium -9,Bundle Size,Conditional Loading,conditional module lazy,React/Next.js,Load large data or modules only when a feature is activated,Dynamic import when feature enabled,Import large modules unconditionally,"useEffect(() => { if (enabled) import('./heavy.js') }, [enabled])","import { heavyData } from './heavy.js'",High -10,Bundle Size,Preload Intent,preload hover focus intent,React/Next.js,Preload heavy bundles on hover/focus before they're needed,Preload on user intent signals,Load only on click,"onMouseEnter={() => import('./editor')}","onClick={() => import('./editor')}",Medium -11,Server,React.cache Dedup,react cache deduplicate request,React/Next.js,Use React.cache() for server-side request deduplication within single request,Wrap data fetchers with cache(),Fetch same data multiple times in tree,"export const getUser = cache(async () => await db.user.find())","export async function getUser() { return await db.user.find() }",Medium -12,Server,LRU Cache Cross-Request,lru cache cross request,React/Next.js,Use LRU cache for data shared across sequential requests,Use LRU for cross-request caching,Refetch same data on every request,"const cache = new LRUCache({ max: 1000, ttl: 5*60*1000 })","Always fetch from database",High -13,Server,Minimize Serialization,serialization rsc boundary,React/Next.js,Only pass fields that client actually uses across RSC boundaries,Pass only needed fields to client components,Pass entire objects to client,"<Profile name={user.name} />","<Profile user={user} /> // 50 fields serialized",High -14,Server,Parallel Fetching,parallel fetch component composition,React/Next.js,Restructure components to parallelize data fetching in RSC,Use component composition for parallel fetches,Sequential fetches in parent component,"<Header /><Sidebar /> // both fetch in parallel","const header = await fetchHeader(); return <><div>{header}</div><Sidebar /></>",Critical -15,Server,After Non-blocking,after non-blocking logging,React/Next.js,Use Next.js after() to schedule work after response is sent,Use after() for logging/analytics,Block response for non-critical operations,"after(async () => { await logAction() }); return Response.json(data)","await logAction(); return Response.json(data)",Medium -16,Client,SWR Deduplication,swr dedup cache revalidate,React/Next.js,Use SWR for automatic request deduplication and caching,Use useSWR for client data fetching,Manual fetch in useEffect,"const { data } = useSWR('/api/users', fetcher)","useEffect(() => { fetch('/api/users').then(setUsers) }, [])",Medium-High -17,Client,Event Listener Dedup,event listener deduplicate global,React/Next.js,Share global event listeners across component instances,Use useSWRSubscription for shared listeners,Register listener per component instance,"useSWRSubscription('global-keydown', () => { window.addEventListener... })","useEffect(() => { window.addEventListener('keydown', handler) }, [])",Low -18,Rerender,Defer State Reads,state read callback subscription,React/Next.js,Don't subscribe to state only used in callbacks,Read state on-demand in callbacks,Subscribe to state used only in handlers,"const handleClick = () => { const params = new URLSearchParams(location.search) }","const params = useSearchParams(); const handleClick = () => { params.get('ref') }",Medium -19,Rerender,Memoized Components,memo extract expensive,React/Next.js,Extract expensive work into memoized components for early returns,Extract to memo() components,Compute expensive values before early return,"const UserAvatar = memo(({ user }) => ...); if (loading) return <Skeleton />","const avatar = useMemo(() => compute(user)); if (loading) return <Skeleton />",Medium -20,Rerender,Narrow Dependencies,effect dependency primitive,React/Next.js,Specify primitive dependencies instead of objects in effects,Use primitive values in dependency arrays,Use object references as dependencies,"useEffect(() => { console.log(user.id) }, [user.id])","useEffect(() => { console.log(user.id) }, [user])",Low -21,Rerender,Derived State,derived boolean subscription,React/Next.js,Subscribe to derived booleans instead of continuous values,Use derived boolean state,Subscribe to continuous values,"const isMobile = useMediaQuery('(max-width: 767px)')","const width = useWindowWidth(); const isMobile = width < 768",Medium -22,Rerender,Functional setState,functional setstate callback,React/Next.js,Use functional setState updates for stable callbacks and no stale closures,Use functional form: setState(curr => ...),Reference state directly in setState,"setItems(curr => [...curr, newItem])","setItems([...items, newItem]) // items in deps",Medium -23,Rerender,Lazy State Init,usestate lazy initialization,React/Next.js,Pass function to useState for expensive initial values,Use function form for expensive init,Compute expensive value directly,"useState(() => buildSearchIndex(items))","useState(buildSearchIndex(items)) // runs every render",Medium -24,Rerender,Transitions,starttransition non-urgent,React/Next.js,Mark frequent non-urgent state updates as transitions,Use startTransition for non-urgent updates,Block UI on every state change,"startTransition(() => setScrollY(window.scrollY))","setScrollY(window.scrollY) // blocks on every scroll",Medium -25,Rendering,SVG Animation Wrapper,svg animation wrapper div,React/Next.js,Wrap SVG in div and animate wrapper for hardware acceleration,Animate div wrapper around SVG,Animate SVG element directly,"<div class='animate-spin'><svg>...</svg></div>","<svg class='animate-spin'>...</svg>",Low -26,Rendering,Content Visibility,content-visibility auto,React/Next.js,Apply content-visibility: auto to defer off-screen rendering,Use content-visibility for long lists,Render all list items immediately,".item { content-visibility: auto; contain-intrinsic-size: 0 80px }","Render 1000 items without optimization",High -27,Rendering,Hoist Static JSX,hoist static jsx element,React/Next.js,Extract static JSX outside components to avoid re-creation,Hoist static elements to module scope,Create static elements inside components,"const skeleton = <div class='animate-pulse' />; function C() { return skeleton }","function C() { return <div class='animate-pulse' /> }",Low -28,Rendering,Hydration No Flicker,hydration mismatch flicker,React/Next.js,Use inline script to set client-only data before hydration,Inject sync script for client-only values,Use useEffect causing flash,"<script dangerouslySetInnerHTML={{ __html: 'el.className = localStorage.theme' }} />","useEffect(() => setTheme(localStorage.theme), []) // flickers",Medium -29,Rendering,Conditional Render,conditional render ternary,React/Next.js,Use ternary instead of && when condition can be 0 or NaN,Use explicit ternary for conditionals,Use && with potentially falsy numbers,"{count > 0 ? <Badge>{count}</Badge> : null}","{count && <Badge>{count}</Badge>} // renders '0'",Low -30,Rendering,Activity Component,activity show hide preserve,React/Next.js,Use Activity component to preserve state/DOM for toggled components,Use Activity for expensive toggle components,Unmount/remount on visibility toggle,"<Activity mode={isOpen ? 'visible' : 'hidden'}><Menu /></Activity>","{isOpen && <Menu />} // loses state",Medium -31,JS Perf,Batch DOM CSS,batch dom css reflow,React/Next.js,Group CSS changes via classes or cssText to minimize reflows,Use class toggle or cssText,Change styles one property at a time,"element.classList.add('highlighted')","el.style.width='100px'; el.style.height='200px'",Medium -32,JS Perf,Index Map Lookup,map index lookup find,React/Next.js,Build Map for repeated lookups instead of multiple .find() calls,Build index Map for O(1) lookups,Use .find() in loops,"const byId = new Map(users.map(u => [u.id, u])); byId.get(id)","users.find(u => u.id === order.userId) // O(n) each time",Low-Medium -33,JS Perf,Cache Property Access,cache property loop,React/Next.js,Cache object property lookups in hot paths,Cache values before loops,Access nested properties in loops,"const val = obj.config.settings.value; for (...) process(val)","for (...) process(obj.config.settings.value)",Low-Medium -34,JS Perf,Cache Function Results,memoize cache function,React/Next.js,Use module-level Map to cache repeated function results,Use Map cache for repeated calls,Recompute same values repeatedly,"const cache = new Map(); if (cache.has(x)) return cache.get(x)","slugify(name) // called 100 times same input",Medium -35,JS Perf,Cache Storage API,localstorage cache read,React/Next.js,Cache localStorage/sessionStorage reads in memory,Cache storage reads in Map,Read storage on every call,"if (!cache.has(key)) cache.set(key, localStorage.getItem(key))","localStorage.getItem('theme') // every call",Low-Medium -36,JS Perf,Combine Iterations,combine filter map loop,React/Next.js,Combine multiple filter/map into single loop,Single loop for multiple categorizations,Chain multiple filter() calls,"for (u of users) { if (u.isAdmin) admins.push(u); if (u.isTester) testers.push(u) }","users.filter(admin); users.filter(tester); users.filter(inactive)",Low-Medium -37,JS Perf,Length Check First,length check array compare,React/Next.js,Check array lengths before expensive comparisons,Early return if lengths differ,Always run expensive comparison,"if (a.length !== b.length) return true; // then compare","a.sort().join() !== b.sort().join() // even when lengths differ",Medium-High -38,JS Perf,Early Return,early return exit function,React/Next.js,Return early when result is determined to skip processing,Return immediately on first error,Process all items then check errors,"for (u of users) { if (!u.email) return { error: 'Email required' } }","let hasError; for (...) { if (!email) hasError=true }; if (hasError)...",Low-Medium -39,JS Perf,Hoist RegExp,regexp hoist module,React/Next.js,Don't create RegExp inside render - hoist or memoize,Hoist RegExp to module scope,Create RegExp every render,"const EMAIL_RE = /^[^@]+@[^@]+$/; function validate() { EMAIL_RE.test(x) }","function C() { const re = new RegExp(pattern); re.test(x) }",Low-Medium -40,JS Perf,Loop Min Max,loop min max sort,React/Next.js,Use loop for min/max instead of sort - O(n) vs O(n log n),Single pass loop for min/max,Sort array to find min/max,"let max = arr[0]; for (x of arr) if (x > max) max = x","arr.sort((a,b) => b-a)[0] // O(n log n)",Low -41,JS Perf,Set Map Lookups,set map includes has,React/Next.js,Use Set/Map for O(1) lookups instead of array.includes(),Convert to Set for membership checks,Use .includes() for repeated checks,"const allowed = new Set(['a','b']); allowed.has(id)","const allowed = ['a','b']; allowed.includes(id)",Low-Medium -42,JS Perf,toSorted Immutable,tosorted sort immutable,React/Next.js,Use toSorted() instead of sort() to avoid mutating arrays,Use toSorted() for immutability,Mutate arrays with sort(),"users.toSorted((a,b) => a.name.localeCompare(b.name))","users.sort((a,b) => a.name.localeCompare(b.name)) // mutates",Medium-High -43,Advanced,Event Handler Refs,useeffectevent ref handler,React/Next.js,Store callbacks in refs for stable effect subscriptions,Use useEffectEvent for stable handlers,Re-subscribe on every callback change,"const onEvent = useEffectEvent(handler); useEffect(() => { listen(onEvent) }, [])","useEffect(() => { listen(handler) }, [handler]) // re-subscribes",Low -44,Advanced,useLatest Hook,uselatest ref callback,React/Next.js,Access latest values in callbacks without adding to dependency arrays,Use useLatest for fresh values in stable callbacks,Add callback to effect dependencies,"const cbRef = useLatest(cb); useEffect(() => { setTimeout(() => cbRef.current()) }, [])","useEffect(() => { setTimeout(() => cb()) }, [cb]) // re-runs",Low diff --git a/.cursor/skills/ui-ux-pro-max/data/stacks/astro.csv b/.cursor/skills/ui-ux-pro-max/data/stacks/astro.csv deleted file mode 100644 index cacba81c..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/stacks/astro.csv +++ /dev/null @@ -1,54 +0,0 @@ -No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL -1,Architecture,Use Islands Architecture,Astro's partial hydration only loads JS for interactive components,Interactive components with client directives,Hydrate entire page like traditional SPA,<Counter client:load />,Everything as client component,High,https://docs.astro.build/en/concepts/islands/ -2,Architecture,Default to zero JS,Astro ships zero JS by default - add only when needed,Static components without client directive,Add client:load to everything,<Header /> (static),<Header client:load /> (unnecessary),High,https://docs.astro.build/en/basics/astro-components/ -3,Architecture,Choose right client directive,Different directives for different hydration timing,client:visible for below-fold client:idle for non-critical,client:load for everything,<Comments client:visible />,<Comments client:load />,Medium,https://docs.astro.build/en/reference/directives-reference/#client-directives -4,Architecture,Use content collections,Type-safe content management for blogs docs,Content collections for structured content,Loose markdown files without schema,const posts = await getCollection('blog'),import.meta.glob('./posts/*.md'),High,https://docs.astro.build/en/guides/content-collections/ -5,Architecture,Define collection schemas,Zod schemas for content validation,Schema with required fields and types,No schema validation,"defineCollection({ schema: z.object({...}) })",defineCollection({}),High,https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema -6,Routing,Use file-based routing,Create routes by adding .astro files in pages/,pages/ directory for routes,Manual route configuration,src/pages/about.astro,Custom router setup,Medium,https://docs.astro.build/en/basics/astro-pages/ -7,Routing,Dynamic routes with brackets,Use [param] for dynamic routes,Bracket notation for params,Query strings for dynamic content,pages/blog/[slug].astro,pages/blog.astro?slug=x,Medium,https://docs.astro.build/en/guides/routing/#dynamic-routes -8,Routing,Use getStaticPaths for SSG,Generate static pages at build time,getStaticPaths for known dynamic routes,Fetch at runtime for static content,"export async function getStaticPaths() { return [...] }",No getStaticPaths with dynamic route,High,https://docs.astro.build/en/reference/api-reference/#getstaticpaths -9,Routing,Enable SSR when needed,Server-side rendering for dynamic content,output: 'server' or 'hybrid' for dynamic,SSR for purely static sites,"export const prerender = false;",SSR for static blog,Medium,https://docs.astro.build/en/guides/server-side-rendering/ -10,Components,Keep .astro for static,Use .astro components for static content,Astro components for layout structure,React/Vue for static markup,<Layout><slot /></Layout>,<ReactLayout>{children}</ReactLayout>,High, -11,Components,Use framework components for interactivity,React Vue Svelte for complex interactivity,Framework component with client directive,Astro component with inline scripts,<ReactCounter client:load />,<script> in .astro for complex state,Medium,https://docs.astro.build/en/guides/framework-components/ -12,Components,Pass data via props,Astro components receive props in frontmatter,Astro.props for component data,Global state for simple data,"const { title } = Astro.props;",Import global store,Low,https://docs.astro.build/en/basics/astro-components/#component-props -13,Components,Use slots for composition,Named and default slots for flexible layouts,<slot /> for child content,Props for HTML content,<slot name="header" />,<Component header={<div>...</div>} />,Medium,https://docs.astro.build/en/basics/astro-components/#slots -14,Components,Colocate component styles,Scoped styles in component file,<style> in same .astro file,Separate CSS files for component styles,<style> .card { } </style>,import './Card.css',Low, -15,Styling,Use scoped styles by default,Astro scopes styles to component automatically,<style> for component-specific styles,Global styles for everything,<style> h1 { } </style> (scoped),<style is:global> for everything,Medium,https://docs.astro.build/en/guides/styling/#scoped-styles -16,Styling,Use is:global sparingly,Global styles only when truly needed,is:global for base styles or overrides,is:global for component styles,<style is:global> body { } </style>,<style is:global> .card { } </style>,Medium, -17,Styling,Integrate Tailwind properly,Use @astrojs/tailwind integration,Official Tailwind integration,Manual Tailwind setup,npx astro add tailwind,Manual PostCSS config,Low,https://docs.astro.build/en/guides/integrations-guide/tailwind/ -18,Styling,Use CSS variables for theming,Define tokens in :root,CSS custom properties for themes,Hardcoded colors everywhere,:root { --primary: #3b82f6; },color: #3b82f6; everywhere,Medium, -19,Data,Fetch in frontmatter,Data fetching in component frontmatter,Top-level await in frontmatter,useEffect for initial data,const data = await fetch(url),client-side fetch on mount,High,https://docs.astro.build/en/guides/data-fetching/ -20,Data,Use Astro.glob for local files,Import multiple local files,Astro.glob for markdown/data files,Manual imports for each file,const posts = await Astro.glob('./posts/*.md'),"import post1; import post2;",Medium, -21,Data,Prefer content collections over glob,Type-safe collections for structured content,getCollection() for blog/docs,Astro.glob for structured content,await getCollection('blog'),await Astro.glob('./blog/*.md'),High, -22,Data,Use environment variables correctly,Import.meta.env for env vars,PUBLIC_ prefix for client vars,Expose secrets to client,import.meta.env.PUBLIC_API_URL,import.meta.env.SECRET in client,High,https://docs.astro.build/en/guides/environment-variables/ -23,Performance,Preload critical assets,Use link preload for important resources,Preload fonts above-fold images,No preload hints,"<link rel=""preload"" href=""font.woff2"" as=""font"">",No preload for critical assets,Medium, -24,Performance,Optimize images with astro:assets,Built-in image optimization,<Image /> component for optimization,<img> for local images,"import { Image } from 'astro:assets';","<img src=""./image.jpg"">",High,https://docs.astro.build/en/guides/images/ -25,Performance,Use picture for responsive images,Multiple formats and sizes,<Picture /> for art direction,Single image size for all screens,<Picture /> with multiple sources,<Image /> with single size,Medium, -26,Performance,Lazy load below-fold content,Defer loading non-critical content,loading=lazy for images client:visible for components,Load everything immediately,"<img loading=""lazy"">",No lazy loading,Medium, -27,Performance,Minimize client directives,Each directive adds JS bundle,Audit client: usage regularly,Sprinkle client:load everywhere,Only interactive components hydrated,Every component with client:load,High, -28,ViewTransitions,Enable View Transitions,Smooth page transitions,<ViewTransitions /> in head,Full page reloads,"import { ViewTransitions } from 'astro:transitions';",No transition API,Medium,https://docs.astro.build/en/guides/view-transitions/ -29,ViewTransitions,Use transition:name,Named elements for morphing,transition:name for persistent elements,Unnamed transitions,"<header transition:name=""header"">",<header> without name,Low, -30,ViewTransitions,Handle transition:persist,Keep state across navigations,transition:persist for media players,Re-initialize on every navigation,"<video transition:persist id=""player"">",Video restarts on navigation,Medium, -31,ViewTransitions,Add fallback for no-JS,Graceful degradation,Content works without JS,Require JS for basic navigation,Static content accessible,Broken without ViewTransitions JS,High, -32,SEO,Use built-in SEO component,Head management for meta tags,Astro SEO integration or manual head,No meta tags,"<title>{title}",No SEO tags,High, -33,SEO,Generate sitemap,Automatic sitemap generation,@astrojs/sitemap integration,Manual sitemap maintenance,npx astro add sitemap,Hand-written sitemap.xml,Medium,https://docs.astro.build/en/guides/integrations-guide/sitemap/ -34,SEO,Add RSS feed for content,RSS for blogs and content sites,@astrojs/rss for feed generation,No RSS feed,rss() helper in pages/rss.xml.js,No feed for blog,Low,https://docs.astro.build/en/guides/rss/ -35,SEO,Use canonical URLs,Prevent duplicate content issues,Astro.url for canonical generation,"",No canonical tags,Medium, -36,Integrations,Use official integrations,Astro's integration system,npx astro add for integrations,Manual configuration,npx astro add react,Manual React setup,Medium,https://docs.astro.build/en/guides/integrations-guide/ -37,Integrations,Configure integrations in astro.config,Centralized configuration,integrations array in config,Scattered configuration,"integrations: [react(), tailwind()]",Multiple config files,Low, -38,Integrations,Use adapter for deployment,Platform-specific adapters,Correct adapter for host,Wrong or no adapter,@astrojs/vercel for Vercel,No adapter for SSR,High,https://docs.astro.build/en/guides/deploy/ -39,TypeScript,Enable TypeScript,Type safety for Astro projects,tsconfig.json with astro types,No TypeScript,Astro TypeScript template,JavaScript only,Medium,https://docs.astro.build/en/guides/typescript/ -40,TypeScript,Type component props,Define prop interfaces,Props interface in frontmatter,Untyped props,"interface Props { title: string }",No props typing,Medium, -41,TypeScript,Use strict mode,Catch errors early,strict: true in tsconfig,Loose TypeScript config,strictest template,base template,Low, -42,Markdown,Use MDX for components,Components in markdown content,@astrojs/mdx for interactive docs,Plain markdown with workarounds, in .mdx,HTML in .md files,Medium,https://docs.astro.build/en/guides/integrations-guide/mdx/ -43,Markdown,Configure markdown plugins,Extend markdown capabilities,remarkPlugins rehypePlugins in config,Manual HTML for features,remarkPlugins: [remarkToc],Manual TOC in every post,Low, -44,Markdown,Use frontmatter for metadata,Structured post metadata,Frontmatter with typed schema,Inline metadata,title date in frontmatter,# Title as first line,Medium, -45,API,Use API routes for endpoints,Server endpoints in pages/api,pages/api/[endpoint].ts for APIs,External API for simple endpoints,pages/api/posts.json.ts,Separate Express server,Medium,https://docs.astro.build/en/guides/endpoints/ -46,API,Return proper responses,Use Response object,new Response() with headers,Plain objects,return new Response(JSON.stringify(data)),return data,Medium, -47,API,Handle methods correctly,Export named method handlers,export GET POST handlers,Single default export,export const GET = async () => {},export default async () => {},Low, -48,Security,Sanitize user content,Prevent XSS in dynamic content,set:html only for trusted content,set:html with user input,"","
",High, -49,Security,Use HTTPS in production,Secure connections,HTTPS for all production sites,HTTP in production,https://example.com,http://example.com,High, -50,Security,Validate API input,Check and sanitize all input,Zod validation for API routes,Trust all input,const body = schema.parse(data),const body = await request.json(),High, -51,Build,Use hybrid rendering,Mix static and dynamic pages,output: 'hybrid' for flexibility,All SSR or all static,prerender per-page basis,Single rendering mode,Medium,https://docs.astro.build/en/guides/server-side-rendering/#hybrid-rendering -52,Build,Analyze bundle size,Monitor JS bundle impact,Build output shows bundle sizes,Ignore bundle growth,Check astro build output,No size monitoring,Medium, -53,Build,Use prefetch,Preload linked pages,prefetch integration,No prefetch for navigation,npx astro add prefetch,Manual prefetch,Low,https://docs.astro.build/en/guides/prefetch/ diff --git a/.cursor/skills/ui-ux-pro-max/data/stacks/flutter.csv b/.cursor/skills/ui-ux-pro-max/data/stacks/flutter.csv deleted file mode 100644 index b8dfd0d6..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/stacks/flutter.csv +++ /dev/null @@ -1,53 +0,0 @@ -No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL -1,Widgets,Use StatelessWidget when possible,Immutable widgets are simpler,StatelessWidget for static UI,StatefulWidget for everything,class MyWidget extends StatelessWidget,class MyWidget extends StatefulWidget (static),Medium,https://api.flutter.dev/flutter/widgets/StatelessWidget-class.html -2,Widgets,Keep widgets small,Single responsibility principle,Extract widgets into smaller pieces,Large build methods,Column(children: [Header() Content()]),500+ line build method,Medium, -3,Widgets,Use const constructors,Compile-time constants for performance,const MyWidget() when possible,Non-const for static widgets,const Text('Hello'),Text('Hello') for literals,High,https://dart.dev/guides/language/language-tour#constant-constructors -4,Widgets,Prefer composition over inheritance,Combine widgets using children,Compose widgets,Extend widget classes,Container(child: MyContent()),class MyContainer extends Container,Medium, -5,State,Use setState correctly,Minimal state in StatefulWidget,setState for UI state changes,setState for business logic,setState(() { _counter++; }),Complex logic in setState,Medium,https://api.flutter.dev/flutter/widgets/State/setState.html -6,State,Avoid setState in build,Never call setState during build,setState in callbacks only,setState in build method,onPressed: () => setState(() {}),build() { setState(); },High, -7,State,Use state management for complex apps,Provider Riverpod BLoC,State management for shared state,setState for global state,Provider.of(context),Global setState calls,Medium, -8,State,Prefer Riverpod or Provider,Recommended state solutions,Riverpod for new projects,InheritedWidget manually,ref.watch(myProvider),Custom InheritedWidget,Medium,https://riverpod.dev/ -9,State,Dispose resources,Clean up controllers and subscriptions,dispose() for cleanup,Memory leaks from subscriptions,@override void dispose() { controller.dispose(); },No dispose implementation,High, -10,Layout,Use Column and Row,Basic layout widgets,Column Row for linear layouts,Stack for simple layouts,"Column(children: [Text(), Button()])",Stack for vertical list,Medium,https://api.flutter.dev/flutter/widgets/Column-class.html -11,Layout,Use Expanded and Flexible,Control flex behavior,Expanded to fill space,Fixed sizes in flex containers,Expanded(child: Container()),Container(width: 200) in Row,Medium, -12,Layout,Use SizedBox for spacing,Consistent spacing,SizedBox for gaps,Container for spacing only,SizedBox(height: 16),Container(height: 16),Low, -13,Layout,Use LayoutBuilder for responsive,Respond to constraints,LayoutBuilder for adaptive layouts,Fixed sizes for responsive,LayoutBuilder(builder: (context constraints) {}),Container(width: 375),Medium,https://api.flutter.dev/flutter/widgets/LayoutBuilder-class.html -14,Layout,Avoid deep nesting,Keep widget tree shallow,Extract deeply nested widgets,10+ levels of nesting,Extract widget to method or class,Column(Row(Column(Row(...)))),Medium, -15,Lists,Use ListView.builder,Lazy list building,ListView.builder for long lists,ListView with children for large lists,"ListView.builder(itemCount: 100, itemBuilder: ...)",ListView(children: items.map(...).toList()),High,https://api.flutter.dev/flutter/widgets/ListView-class.html -16,Lists,Provide itemExtent when known,Skip measurement,itemExtent for fixed height items,No itemExtent for uniform lists,ListView.builder(itemExtent: 50),ListView.builder without itemExtent,Medium, -17,Lists,Use keys for stateful items,Preserve widget state,Key for stateful list items,No key for dynamic lists,ListTile(key: ValueKey(item.id)),ListTile without key,High, -18,Lists,Use SliverList for custom scroll,Custom scroll effects,CustomScrollView with Slivers,Nested ListViews,CustomScrollView(slivers: [SliverList()]),ListView inside ListView,Medium,https://api.flutter.dev/flutter/widgets/SliverList-class.html -19,Navigation,Use Navigator 2.0 or GoRouter,Declarative routing,go_router for navigation,Navigator.push for complex apps,GoRouter(routes: [...]),Navigator.push everywhere,Medium,https://pub.dev/packages/go_router -20,Navigation,Use named routes,Organized navigation,Named routes for clarity,Anonymous routes,Navigator.pushNamed(context '/home'),Navigator.push(context MaterialPageRoute()),Low, -21,Navigation,Handle back button (PopScope),Android back behavior and predictive back (Android 14+),Use PopScope widget (WillPopScope is deprecated),Use WillPopScope,"PopScope(canPop: false, onPopInvoked: (didPop) => ...)",WillPopScope(onWillPop: ...),High,https://api.flutter.dev/flutter/widgets/PopScope-class.html -22,Navigation,Pass typed arguments,Type-safe route arguments,Typed route arguments,Dynamic arguments,MyRoute(id: '123'),arguments: {'id': '123'},Medium, -23,Async,Use FutureBuilder,Async UI building,FutureBuilder for async data,setState for async,FutureBuilder(future: fetchData()),fetchData().then((d) => setState()),Medium,https://api.flutter.dev/flutter/widgets/FutureBuilder-class.html -24,Async,Use StreamBuilder,Stream UI building,StreamBuilder for streams,Manual stream subscription,StreamBuilder(stream: myStream),stream.listen in initState,Medium,https://api.flutter.dev/flutter/widgets/StreamBuilder-class.html -25,Async,Handle loading and error states,Complete async UI states,ConnectionState checks,Only success state,if (snapshot.connectionState == ConnectionState.waiting),No loading indicator,High, -26,Async,Cancel subscriptions,Clean up stream subscriptions,Cancel in dispose,Memory leaks,subscription.cancel() in dispose,No subscription cleanup,High, -27,Theming,Use ThemeData,Consistent theming,ThemeData for app theme,Hardcoded colors,Theme.of(context).primaryColor,Color(0xFF123456) everywhere,Medium,https://api.flutter.dev/flutter/material/ThemeData-class.html -28,Theming,Use ColorScheme,Material 3 color system,ColorScheme for colors,Individual color properties,colorScheme: ColorScheme.fromSeed(),primaryColor: Colors.blue,Medium, -29,Theming,Access theme via context,Dynamic theme access,Theme.of(context),Static theme reference,Theme.of(context).textTheme.bodyLarge,TextStyle(fontSize: 16),Medium, -30,Theming,Support dark mode,Respect system theme,darkTheme in MaterialApp,Light theme only,"MaterialApp(theme: light, darkTheme: dark)",MaterialApp(theme: light),Medium, -31,Animation,Use implicit animations,Simple animations,AnimatedContainer AnimatedOpacity,Explicit for simple transitions,AnimatedContainer(duration: Duration()),AnimationController for fade,Low,https://api.flutter.dev/flutter/widgets/AnimatedContainer-class.html -32,Animation,Use AnimationController for complex,Fine-grained control,AnimationController with Ticker,Implicit for complex sequences,AnimationController(vsync: this),AnimatedContainer for staggered,Medium, -33,Animation,Dispose AnimationControllers,Clean up animation resources,dispose() for controllers,Memory leaks,controller.dispose() in dispose,No controller disposal,High, -34,Animation,Use Hero for transitions,Shared element transitions,Hero for navigation animations,Manual shared element,Hero(tag: 'image' child: Image()),Custom shared element animation,Low,https://api.flutter.dev/flutter/widgets/Hero-class.html -35,Forms,Use Form widget,Form validation,Form with GlobalKey,Individual validation,Form(key: _formKey child: ...),TextField without Form,Medium,https://api.flutter.dev/flutter/widgets/Form-class.html -36,Forms,Use TextEditingController,Control text input,Controller for text fields,onChanged for all text,final controller = TextEditingController(),onChanged: (v) => setState(),Medium, -37,Forms,Validate on submit,Form validation flow,_formKey.currentState!.validate(),Skip validation,if (_formKey.currentState!.validate()),Submit without validation,High, -38,Forms,Dispose controllers,Clean up text controllers,dispose() for controllers,Memory leaks,controller.dispose() in dispose,No controller disposal,High, -39,Performance,Use const widgets,Reduce rebuilds,const for static widgets,No const for literals,const Icon(Icons.add),Icon(Icons.add),High, -40,Performance,Avoid rebuilding entire tree,Minimal rebuild scope,Isolate changing widgets,setState on parent,Consumer only around changing widget,setState on root widget,High, -41,Performance,Use RepaintBoundary,Isolate repaints,RepaintBoundary for animations,Full screen repaints,RepaintBoundary(child: AnimatedWidget()),Animation without boundary,Medium,https://api.flutter.dev/flutter/widgets/RepaintBoundary-class.html -42,Performance,Profile with DevTools,Measure before optimizing,Flutter DevTools profiling,Guess at performance,DevTools performance tab,Optimize without measuring,Medium,https://docs.flutter.dev/tools/devtools -43,Accessibility,Use Semantics widget,Screen reader support,Semantics for accessibility,Missing accessibility info,Semantics(label: 'Submit button'),GestureDetector without semantics,High,https://api.flutter.dev/flutter/widgets/Semantics-class.html -44,Accessibility,Support large fonts,MediaQuery text scaling,MediaQuery.textScaleFactor,Fixed font sizes,style: Theme.of(context).textTheme,TextStyle(fontSize: 14),High, -45,Accessibility,Test with screen readers,TalkBack and VoiceOver,Test accessibility regularly,Skip accessibility testing,Regular TalkBack testing,No screen reader testing,High, -46,Testing,Use widget tests,Test widget behavior,WidgetTester for UI tests,Unit tests only,testWidgets('...' (tester) async {}),Only test() for UI,Medium,https://docs.flutter.dev/testing -47,Testing,Use integration tests,Full app testing,integration_test package,Manual testing only,IntegrationTestWidgetsFlutterBinding,Manual E2E testing,Medium, -48,Testing,Mock dependencies,Isolate tests,Mockito or mocktail,Real dependencies in tests,when(mock.method()).thenReturn(),Real API calls in tests,Medium, -49,Platform,Use Platform checks,Platform-specific code,Platform.isIOS Platform.isAndroid,Same code for all platforms,if (Platform.isIOS) {},Hardcoded iOS behavior,Medium, -50,Platform,Use kIsWeb for web,Web platform detection,kIsWeb for web checks,Platform for web,if (kIsWeb) {},Platform.isWeb (doesn't exist),Medium, -51,Packages,Use pub.dev packages,Community packages,Popular maintained packages,Custom implementations,cached_network_image,Custom image cache,Medium,https://pub.dev/ -52,Packages,Check package quality,Quality before adding,Pub points and popularity,Any package without review,100+ pub points,Unmaintained packages,Medium, diff --git a/.cursor/skills/ui-ux-pro-max/data/stacks/html-tailwind.csv b/.cursor/skills/ui-ux-pro-max/data/stacks/html-tailwind.csv deleted file mode 100644 index 51ff57a6..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/stacks/html-tailwind.csv +++ /dev/null @@ -1,56 +0,0 @@ -No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL -1,Animation,Use Tailwind animate utilities,Built-in animations are optimized and respect reduced-motion,Use animate-pulse animate-spin animate-ping,Custom @keyframes for simple effects,animate-pulse,@keyframes pulse {...},Medium,https://tailwindcss.com/docs/animation -2,Animation,Limit bounce animations,Continuous bounce is distracting and causes motion sickness,Use animate-bounce sparingly on CTAs only,Multiple bounce animations on page,Single CTA with animate-bounce,5+ elements with animate-bounce,High, -3,Animation,Transition duration,Use appropriate transition speeds for UI feedback,duration-150 to duration-300 for UI,duration-1000 or longer for UI elements,transition-all duration-200,transition-all duration-1000,Medium,https://tailwindcss.com/docs/transition-duration -4,Animation,Hover transitions,Add smooth transitions on hover state changes,Add transition class with hover states,Instant hover changes without transition,hover:bg-gray-100 transition-colors,hover:bg-gray-100 (no transition),Low, -5,Z-Index,Use Tailwind z-* scale,Consistent stacking context with predefined scale,z-0 z-10 z-20 z-30 z-40 z-50,Arbitrary z-index values,z-50 for modals,z-[9999],Medium,https://tailwindcss.com/docs/z-index -6,Z-Index,Fixed elements z-index,Fixed navigation and modals need explicit z-index,z-50 for nav z-40 for dropdowns,Relying on DOM order for stacking,fixed top-0 z-50,fixed top-0 (no z-index),High, -7,Z-Index,Negative z-index for backgrounds,Use negative z-index for decorative backgrounds,z-[-1] for background elements,Positive z-index for backgrounds,-z-10 for decorative,z-10 for background,Low, -8,Layout,Container max-width,Limit content width for readability,max-w-7xl mx-auto for main content,Full-width content on large screens,max-w-7xl mx-auto px-4,w-full (no max-width),Medium,https://tailwindcss.com/docs/container -9,Layout,Responsive padding,Adjust padding for different screen sizes,px-4 md:px-6 lg:px-8,Same padding all sizes,px-4 sm:px-6 lg:px-8,px-8 (same all sizes),Medium, -10,Layout,Grid gaps,Use consistent gap utilities for spacing,gap-4 gap-6 gap-8,Margins on individual items,grid gap-6,grid with mb-4 on each item,Medium,https://tailwindcss.com/docs/gap -11,Layout,Flexbox alignment,Use flex utilities for alignment,items-center justify-between,Multiple nested wrappers,flex items-center justify-between,Nested divs for alignment,Low, -12,Images,Aspect ratio,Maintain consistent image aspect ratios,aspect-video aspect-square,No aspect ratio on containers,aspect-video rounded-lg,No aspect control,Medium,https://tailwindcss.com/docs/aspect-ratio -13,Images,Object fit,Control image scaling within containers,object-cover object-contain,Stretched distorted images,object-cover w-full h-full,No object-fit,Medium,https://tailwindcss.com/docs/object-fit -14,Images,Lazy loading,Defer loading of off-screen images,loading='lazy' on images,All images eager load,, without lazy,High, -15,Images,Responsive images,Serve appropriate image sizes,srcset and sizes attributes,Same large image all devices,srcset with multiple sizes,4000px image everywhere,High, -16,Typography,Prose plugin,Use @tailwindcss/typography for rich text,prose prose-lg for article content,Custom styles for markdown,prose prose-lg max-w-none,Custom text styling,Medium,https://tailwindcss.com/docs/typography-plugin -17,Typography,Line height,Use appropriate line height for readability,leading-relaxed for body text,Default tight line height,leading-relaxed (1.625),leading-none or leading-tight,Medium,https://tailwindcss.com/docs/line-height -18,Typography,Font size scale,Use consistent text size scale,text-sm text-base text-lg text-xl,Arbitrary font sizes,text-lg,text-[17px],Low,https://tailwindcss.com/docs/font-size -19,Typography,Text truncation,Handle long text gracefully,truncate or line-clamp-*,Overflow breaking layout,line-clamp-2,No overflow handling,Medium,https://tailwindcss.com/docs/text-overflow -20,Colors,Opacity utilities,Use color opacity utilities,bg-black/50 text-white/80,Separate opacity class,bg-black/50,bg-black opacity-50,Low,https://tailwindcss.com/docs/background-color -21,Colors,Dark mode,Support dark mode with dark: prefix,dark:bg-gray-900 dark:text-white,No dark mode support,dark:bg-gray-900,Only light theme,Medium,https://tailwindcss.com/docs/dark-mode -22,Colors,Semantic colors,Use semantic color naming in config,primary secondary danger success,Generic color names in components,bg-primary,bg-blue-500 everywhere,Medium, -23,Spacing,Consistent spacing scale,Use Tailwind spacing scale consistently,p-4 m-6 gap-8,Arbitrary pixel values,p-4 (1rem),p-[15px],Low,https://tailwindcss.com/docs/customizing-spacing -24,Spacing,Negative margins,Use sparingly for overlapping effects,-mt-4 for overlapping elements,Negative margins for layout fixing,-mt-8 for card overlap,-m-2 to fix spacing issues,Medium, -25,Spacing,Space between,Use space-y-* for vertical lists,space-y-4 on flex/grid column,Margin on each child,space-y-4,Each child has mb-4,Low,https://tailwindcss.com/docs/space -26,Forms,Focus states,Always show focus indicators,focus:ring-2 focus:ring-blue-500,Remove focus outline,focus:ring-2 focus:ring-offset-2,focus:outline-none (no replacement),High, -27,Forms,Input sizing,Consistent input dimensions,h-10 px-3 for inputs,Inconsistent input heights,h-10 w-full px-3,Various heights per input,Medium, -28,Forms,Disabled states,Clear disabled styling,disabled:opacity-50 disabled:cursor-not-allowed,No disabled indication,disabled:opacity-50,Same style as enabled,Medium, -29,Forms,Placeholder styling,Style placeholder text appropriately,placeholder:text-gray-400,Dark placeholder text,placeholder:text-gray-400,Default dark placeholder,Low, -30,Responsive,Mobile-first approach,Start with mobile styles and add breakpoints,Default mobile + md: lg: xl:,Desktop-first approach,text-sm md:text-base,text-base max-md:text-sm,Medium,https://tailwindcss.com/docs/responsive-design -31,Responsive,Breakpoint testing,Test at standard breakpoints,320 375 768 1024 1280 1536,Only test on development device,Test all breakpoints,Single device testing,High, -32,Responsive,Hidden/shown utilities,Control visibility per breakpoint,hidden md:block,Different content per breakpoint,hidden md:flex,Separate mobile/desktop components,Low,https://tailwindcss.com/docs/display -33,Buttons,Button sizing,Consistent button dimensions,px-4 py-2 or px-6 py-3,Inconsistent button sizes,px-4 py-2 text-sm,Various padding per button,Medium, -34,Buttons,Touch targets,Minimum 44px touch target on mobile,min-h-[44px] on mobile,Small buttons on mobile,min-h-[44px] min-w-[44px],h-8 w-8 on mobile,High, -35,Buttons,Loading states,Show loading feedback,disabled + spinner icon,Clickable during loading,,Button without loading state,High, -36,Buttons,Icon buttons,Accessible icon-only buttons,aria-label on icon buttons,Icon button without label,,,High, -37,Cards,Card structure,Consistent card styling,rounded-lg shadow-md p-6,Inconsistent card styles,rounded-2xl shadow-lg p-6,Mixed card styling,Low, -38,Cards,Card hover states,Interactive cards should have hover feedback,hover:shadow-lg transition-shadow,No hover on clickable cards,hover:shadow-xl transition-shadow,Static cards that are clickable,Medium, -39,Cards,Card spacing,Consistent internal card spacing,space-y-4 for card content,Inconsistent internal spacing,space-y-4 or p-6,Mixed mb-2 mb-4 mb-6,Low, -40,Accessibility,Screen reader text,Provide context for screen readers,sr-only for hidden labels,Missing context for icons,Close menu,No label for icon button,High,https://tailwindcss.com/docs/screen-readers -41,Accessibility,Focus visible,Show focus only for keyboard users,focus-visible:ring-2,Focus on all interactions,focus-visible:ring-2,focus:ring-2 (shows on click too),Medium, -42,Accessibility,Reduced motion,Respect user motion preferences,motion-reduce:animate-none,Ignore motion preferences,motion-reduce:transition-none,No reduced motion support,High,https://tailwindcss.com/docs/hover-focus-and-other-states#prefers-reduced-motion -43,Performance,Configure content paths,Tailwind needs to know where classes are used,Use 'content' array in config,Use deprecated 'purge' option (v2),"content: ['./src/**/*.{js,ts,jsx,tsx}']",purge: [...],High,https://tailwindcss.com/docs/content-configuration -44,Performance,JIT mode,Use JIT for faster builds and smaller bundles,JIT enabled (default in v3),Full CSS in development,Tailwind v3 defaults,Tailwind v2 without JIT,Medium, -45,Performance,Avoid @apply bloat,Use @apply sparingly,Direct utilities in HTML,Heavy @apply usage,class='px-4 py-2 rounded',@apply px-4 py-2 rounded;,Low,https://tailwindcss.com/docs/reusing-styles -46,Plugins,Official plugins,Use official Tailwind plugins,@tailwindcss/forms typography aspect-ratio,Custom implementations,@tailwindcss/forms,Custom form reset CSS,Medium,https://tailwindcss.com/docs/plugins -47,Plugins,Custom utilities,Create utilities for repeated patterns,Custom utility in config,Repeated arbitrary values,Custom shadow utility,"shadow-[0_4px_20px_rgba(0,0,0,0.1)] everywhere",Medium, -48,Layout,Container Queries,Use @container for component-based responsiveness,Use @container and @lg: etc.,Media queries for component internals,@container @lg:grid-cols-2,@media (min-width: ...) inside component,Medium,https://github.com/tailwindlabs/tailwindcss-container-queries -49,Interactivity,Group and Peer,Style based on parent/sibling state,group-hover peer-checked,JS for simple state interactions,group-hover:text-blue-500,onMouseEnter={() => setHover(true)},Low,https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state -50,Customization,Arbitrary Values,Use [] for one-off values,w-[350px] for specific needs,Creating config for single use,top-[117px] (if strictly needed),style={{ top: '117px' }},Low,https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values -51,Colors,Theme color variables,Define colors in Tailwind theme and use directly,bg-primary text-success border-cta,bg-[var(--color-primary)] text-[var(--color-success)],bg-primary,bg-[var(--color-primary)],Medium,https://tailwindcss.com/docs/customizing-colors -52,Colors,Use bg-linear-to-* for gradients,Tailwind v4 uses bg-linear-to-* syntax for gradients,bg-linear-to-r bg-linear-to-b,bg-gradient-to-* (deprecated in v4),bg-linear-to-r from-blue-500 to-purple-500,bg-gradient-to-r from-blue-500 to-purple-500,Medium,https://tailwindcss.com/docs/background-image -53,Layout,Use shrink-0 shorthand,Shorter class name for flex-shrink-0,shrink-0 shrink,flex-shrink-0 flex-shrink,shrink-0,flex-shrink-0,Low,https://tailwindcss.com/docs/flex-shrink -54,Layout,Use size-* for square dimensions,Single utility for equal width and height,size-4 size-8 size-12,Separate h-* w-* for squares,size-6,h-6 w-6,Low,https://tailwindcss.com/docs/size -55,Images,SVG explicit dimensions,Add width/height attributes to SVGs to prevent layout shift before CSS loads,,SVG without explicit dimensions,,,High, diff --git a/.cursor/skills/ui-ux-pro-max/data/stacks/jetpack-compose.csv b/.cursor/skills/ui-ux-pro-max/data/stacks/jetpack-compose.csv deleted file mode 100644 index 971ff9e3..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/stacks/jetpack-compose.csv +++ /dev/null @@ -1,53 +0,0 @@ -No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL -1,Composable,Pure UI composables,Composable functions should only render UI,Accept state and callbacks,Calling usecase/repo,Pure UI composable,Business logic in UI,High,https://developer.android.com/jetpack/compose/mental-model -2,Composable,Small composables,Each composable has single responsibility,Split into components,Huge composable,Reusable UI,Monolithic UI,Medium, -3,Composable,Stateless by default,Prefer stateless composables,Hoist state,Local mutable state,Stateless UI,Hidden state,High,https://developer.android.com/jetpack/compose/state#state-hoisting -4,State,Single source of truth,UI state comes from one source,StateFlow from VM,Multiple states,Unified UiState,Scattered state,High,https://developer.android.com/topic/architecture/ui-layer -5,State,Model UI State,Use sealed interface/data class,UiState.Loading,Boolean flags,Explicit state,Flag hell,High, -6,State,remember only UI state,remember for UI-only state,"Scroll, animation",Business state,Correct remember,Misuse remember,High,https://developer.android.com/jetpack/compose/state -7,State,rememberSaveable,Persist state across config,rememberSaveable,remember,State survives,State lost,High,https://developer.android.com/jetpack/compose/state#restore-ui-state -8,State,derivedStateOf,Optimize recomposition,derivedStateOf,Recompute always,Optimized,Jank,Medium,https://developer.android.com/jetpack/compose/performance -9,SideEffect,LaunchedEffect keys,Use correct keys,LaunchedEffect(id),LaunchedEffect(Unit),Scoped effect,Infinite loop,High,https://developer.android.com/jetpack/compose/side-effects -10,SideEffect,rememberUpdatedState,Avoid stale lambdas,rememberUpdatedState,Capture directly,Safe callback,Stale state,Medium,https://developer.android.com/jetpack/compose/side-effects -11,SideEffect,DisposableEffect,Clean up resources,onDispose,No cleanup,No leak,Memory leak,High, -12,Architecture,Unidirectional data flow,UI → VM → State,onEvent,Two-way binding,Predictable flow,Hard debug,High,https://developer.android.com/topic/architecture -13,Architecture,No business logic in UI,Logic belongs to VM,Collect state,Call repo,Clean UI,Fat UI,High, -14,Architecture,Expose immutable state,Expose StateFlow,asStateFlow,Mutable exposed,Safe API,State mutation,High, -15,Lifecycle,Lifecycle-aware collect,Use collectAsStateWithLifecycle,Lifecycle aware,collectAsState,No leak,Leak,High,https://developer.android.com/jetpack/compose/lifecycle -16,Navigation,Event-based navigation,VM emits navigation event,"VM: Channel + receiveAsFlow(), V: Collect with Dispatchers.Main.immediate",Nav in UI,Decoupled nav,Using State / SharedFlow for navigation -> event is replayed and navigation fires again (StateFlow),High,https://developer.android.com/jetpack/compose/navigation -17,Navigation,Typed routes,Use sealed routes,sealed class Route,String routes,Type-safe,Runtime crash,Medium, -18,Performance,Stable parameters,Prefer immutable/stable params,@Immutable,Mutable params,Stable recomposition,Extra recomposition,High,https://developer.android.com/jetpack/compose/performance -19,Performance,Use key in Lazy,Provide stable keys,key=id,No key,Stable list,Item jump,High, -20,Performance,Avoid heavy work,No heavy computation in UI,Precompute in VM,Compute in UI,Smooth UI,Jank,High, -21,Performance,Remember expensive objects,remember heavy objects,remember,Recreate each recomposition,Efficient,Wasteful,Medium, -22,Theming,Design system,Centralized theme,Material3 tokens,Hardcoded values,Consistent UI,Inconsistent,High,https://developer.android.com/jetpack/compose/themes -23,Theming,Dark mode support,Theme-based colors,colorScheme,Fixed color,Adaptive UI,Broken dark,Medium, -24,Layout,Prefer Modifier over extra layouts,Use Modifier to adjust layout instead of adding wrapper composables,Use Modifier.padding(),Wrap content with extra Box,Padding via modifier,Box just for padding,High,https://developer.android.com/jetpack/compose/modifiers -25,Layout,Avoid deep layout nesting,Deep layout trees increase measure & layout cost,Keep layout flat,Box ? Column ? Box ? Row,Flat hierarchy,Deep nested tree,High, -26,Layout,Use Row/Column for linear layout,Linear layouts are simpler and more performant,Use Row / Column,Custom layout for simple cases,Row/Column usage,Over-engineered layout,High, -27,Layout,Use Box only for overlapping content,Box should be used only when children overlap,Stack elements,Use Box as Column,Proper overlay,Misused Box,Medium, -28,Layout,Prefer LazyColumn over Column scroll,Lazy layouts are virtualized and efficient,LazyColumn,Column.verticalScroll(),Lazy list,Scrollable Column,High,https://developer.android.com/jetpack/compose/lists -29,Layout,Avoid nested scroll containers,Nested scrolling causes UX & performance issues,Single scroll container,Scroll inside scroll,One scroll per screen,Nested scroll,High, -30,Layout,Avoid fillMaxSize by default,fillMaxSize may break parent constraints,Use exact size,Fill max everywhere,Constraint-aware size,Overfilled layout,Medium, -31,Layout,Avoid intrinsic size unless necessary,Intrinsic measurement is expensive,Explicit sizing,IntrinsicSize.Min,Predictable layout,Expensive measure,High,https://developer.android.com/jetpack/compose/layout/intrinsics -32,Layout,Use Arrangement and Alignment APIs,Declare layout intent explicitly,Use Arrangement / Alignment,Manual spacing hacks,Declarative spacing,Magic spacing,High, -33,Layout,Extract reusable layout patterns,Repeated layouts should be shared,Create layout composable,Copy-paste layouts,Reusable scaffold,Duplicated layout,High, -34,Theming,No hardcoded text style,Use typography,MaterialTheme.typography,Hardcode sp,Scalable,Inconsistent,Medium, -35,Testing,Stateless UI testing,Composable easy to test,Pass state,Hidden state,Testable,Hard test,High,https://developer.android.com/jetpack/compose/testing -36,Testing,Use testTag,Stable UI selectors,Modifier.testTag,Find by text,Stable tests,Flaky tests,Medium, -37,Preview,Multiple previews,Preview multiple states,@Preview,Single preview,Better dev UX,Misleading,Low,https://developer.android.com/jetpack/compose/tooling/preview -38,DI,Inject VM via Hilt,Use hiltViewModel,@HiltViewModel,Manual VM,Clean DI,Coupling,High,https://developer.android.com/training/dependency-injection/hilt-jetpack -39,DI,No DI in UI,Inject in VM,Constructor inject,Inject composable,Proper scope,Wrong scope,High, -40,Accessibility,Content description,Accessible UI,contentDescription,Ignore a11y,Inclusive,A11y fail,Medium,https://developer.android.com/jetpack/compose/accessibility -41,Accessibility,Semantics,Use semantics API,Modifier.semantics,None,Testable a11y,Invisible,Medium, -42,Animation,Compose animation APIs,Use animate*AsState,AnimatedVisibility,Manual anim,Smooth,Jank,Medium,https://developer.android.com/jetpack/compose/animation -43,Animation,Avoid animation logic in VM,Animation is UI concern,Animate in UI,Animate in VM,Correct layering,Mixed concern,Low, -44,Modularization,Feature-based UI modules,UI per feature,:feature:ui,God module,Scalable,Tight coupling,High,https://developer.android.com/topic/modularization -45,Modularization,Public UI contracts,Expose minimal UI API,Interface/Route,Expose impl,Encapsulated,Leaky module,Medium, -46,State,Snapshot state only,Use Compose state,mutableStateOf,Custom observable,Compose aware,Buggy UI,Medium, -47,State,Avoid mutable collections,Immutable list/map,PersistentList,MutableList,Stable UI,Silent bug,High, -48,Lifecycle,RememberCoroutineScope usage,Only for UI jobs,UI coroutine,Long jobs,Scoped job,Leak,Medium,https://developer.android.com/jetpack/compose/side-effects#remembercoroutinescope -49,Interop,Interop View carefully,Use AndroidView,Isolated usage,Mix everywhere,Safe interop,Messy UI,Low,https://developer.android.com/jetpack/compose/interop -50,Interop,Avoid legacy patterns,No LiveData in UI,StateFlow,LiveData,Modern stack,Legacy debt,Medium, -51,Debug,Use layout inspector,Inspect recomposition,Tools,Blind debug,Fast debug,Guessing,Low,https://developer.android.com/studio/debug/layout-inspector -52,Debug,Enable recomposition counts,Track recomposition,Debug flags,Ignore,Performance aware,Hidden jank,Low, diff --git a/.cursor/skills/ui-ux-pro-max/data/stacks/nextjs.csv b/.cursor/skills/ui-ux-pro-max/data/stacks/nextjs.csv deleted file mode 100644 index 8762161a..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/stacks/nextjs.csv +++ /dev/null @@ -1,53 +0,0 @@ -No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL -1,Routing,Use App Router for new projects,App Router is the recommended approach in Next.js 14+,app/ directory with page.tsx,pages/ for new projects,app/dashboard/page.tsx,pages/dashboard.tsx,Medium,https://nextjs.org/docs/app -2,Routing,Use file-based routing,Create routes by adding files in app directory,page.tsx for routes layout.tsx for layouts,Manual route configuration,app/blog/[slug]/page.tsx,Custom router setup,Medium,https://nextjs.org/docs/app/building-your-application/routing -3,Routing,Colocate related files,Keep components styles tests with their routes,Component files alongside page.tsx,Separate components folder,app/dashboard/_components/,components/dashboard/,Low, -4,Routing,Use route groups for organization,Group routes without affecting URL,Parentheses for route groups,Nested folders affecting URL,(marketing)/about/page.tsx,marketing/about/page.tsx,Low,https://nextjs.org/docs/app/building-your-application/routing/route-groups -5,Routing,Handle loading states,Use loading.tsx for route loading UI,loading.tsx alongside page.tsx,Manual loading state management,app/dashboard/loading.tsx,useState for loading in page,Medium,https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming -6,Routing,Handle errors with error.tsx,Catch errors at route level,error.tsx with reset function,try/catch in every component,app/dashboard/error.tsx,try/catch in page component,High,https://nextjs.org/docs/app/building-your-application/routing/error-handling -7,Rendering,Use Server Components by default,Server Components reduce client JS bundle,Keep components server by default,Add 'use client' unnecessarily,export default function Page(),('use client') for static content,High,https://nextjs.org/docs/app/building-your-application/rendering/server-components -8,Rendering,Mark Client Components explicitly,'use client' for interactive components,Add 'use client' only when needed,Server Component with hooks/events,('use client') for onClick useState,No directive with useState,High,https://nextjs.org/docs/app/building-your-application/rendering/client-components -9,Rendering,Push Client Components down,Keep Client Components as leaf nodes,Client wrapper for interactive parts only,Mark page as Client Component, in Server Page,('use client') on page.tsx,High, -10,Rendering,Use streaming for better UX,Stream content with Suspense boundaries,Suspense for slow data fetches,Wait for all data before render,,await allData then render,Medium,https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming -11,Rendering,Choose correct rendering strategy,SSG for static SSR for dynamic ISR for semi-static,generateStaticParams for known paths,SSR for static content,export const revalidate = 3600,fetch without cache config,Medium, -12,DataFetching,Fetch data in Server Components,Fetch directly in async Server Components,async function Page() { const data = await fetch() },useEffect for initial data,const data = await fetch(url),useEffect(() => fetch(url)),High,https://nextjs.org/docs/app/building-your-application/data-fetching -13,DataFetching,Configure caching explicitly (Next.js 15+),Next.js 15 changed defaults to uncached for fetch,Explicitly set cache: 'force-cache' for static data,Assume default is cached (it's not in Next.js 15),fetch(url { cache: 'force-cache' }),fetch(url) // Uncached in v15,High,https://nextjs.org/docs/app/building-your-application/upgrading/version-15 -14,DataFetching,Deduplicate fetch requests,React and Next.js dedupe same requests,Same fetch call in multiple components,Manual request deduplication,Multiple components fetch same URL,Custom cache layer,Low, -15,DataFetching,Use Server Actions for mutations,Server Actions for form submissions,action={serverAction} in forms,API route for every mutation,
,
,Medium,https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations -16,DataFetching,Revalidate data appropriately,Use revalidatePath/revalidateTag after mutations,Revalidate after Server Action,'use client' with manual refetch,revalidatePath('/posts'),router.refresh() everywhere,Medium,https://nextjs.org/docs/app/building-your-application/caching#revalidating -17,Images,Use next/image for optimization,Automatic image optimization and lazy loading, component for all images,
 tags directly,{},,High,https://nextjs.org/docs/app/building-your-application/optimizing/images -18,Images,Provide width and height,Prevent layout shift with dimensions,width and height props or fill,Missing dimensions,,,High, -19,Images,Use fill for responsive images,Fill container with object-fit,fill prop with relative parent,Fixed dimensions for responsive,"",,Medium, -20,Images,Configure remote image domains,Whitelist external image sources,remotePatterns in next.config.js,Allow all domains,remotePatterns: [{ hostname: 'cdn.example.com' }],domains: ['*'],High,https://nextjs.org/docs/app/api-reference/components/image#remotepatterns -21,Images,Use priority for LCP images,Mark above-fold images as priority,priority prop on hero images,All images with priority,, on every image,Medium, -22,Fonts,Use next/font for fonts,Self-hosted fonts with zero layout shift,next/font/google or next/font/local,External font links,import { Inter } from 'next/font/google',"",Medium,https://nextjs.org/docs/app/building-your-application/optimizing/fonts -23,Fonts,Apply font to layout,Set font in root layout for consistency,className on body in layout.tsx,Font in individual pages,,Each page imports font,Low, -24,Fonts,Use variable fonts,Variable fonts reduce bundle size,Single variable font file,Multiple font weights as files,Inter({ subsets: ['latin'] }),Inter_400 Inter_500 Inter_700,Low, -25,Metadata,Use generateMetadata for dynamic,Generate metadata based on params,export async function generateMetadata(),Hardcoded metadata everywhere,generateMetadata({ params }),export const metadata = {},Medium,https://nextjs.org/docs/app/building-your-application/optimizing/metadata -26,Metadata,Include OpenGraph images,Add OG images for social sharing,opengraph-image.tsx or og property,Missing social preview images,opengraph: { images: ['/og.png'] },No OG configuration,Medium, -27,Metadata,Use metadata API,Export metadata object for static metadata,export const metadata = {},Manual head tags,export const metadata = { title: 'Page' },Page,Medium, -28,API,Use Route Handlers for APIs,app/api routes for API endpoints,app/api/users/route.ts,pages/api for new projects,export async function GET(request),export default function handler,Medium,https://nextjs.org/docs/app/building-your-application/routing/route-handlers -29,API,Return proper Response objects,Use NextResponse for API responses,NextResponse.json() for JSON,Plain objects or res.json(),return NextResponse.json({ data }),return { data },Medium, -30,API,Handle HTTP methods explicitly,Export named functions for methods,Export GET POST PUT DELETE,Single handler for all methods,export async function POST(),switch(req.method),Low, -31,API,Validate request body,Validate input before processing,Zod or similar for validation,Trust client input,const body = schema.parse(await req.json()),const body = await req.json(),High, -32,Middleware,Use middleware for auth,Protect routes with middleware.ts,middleware.ts at root,Auth check in every page,export function middleware(request),if (!session) redirect in page,Medium,https://nextjs.org/docs/app/building-your-application/routing/middleware -33,Middleware,Match specific paths,Configure middleware matcher,config.matcher for specific routes,Run middleware on all routes,matcher: ['/dashboard/:path*'],No matcher config,Medium, -34,Middleware,Keep middleware edge-compatible,Middleware runs on Edge runtime,Edge-compatible code only,Node.js APIs in middleware,Edge-compatible auth check,fs.readFile in middleware,High, -35,Environment,Use NEXT_PUBLIC prefix,Client-accessible env vars need prefix,NEXT_PUBLIC_ for client vars,Server vars exposed to client,NEXT_PUBLIC_API_URL,API_SECRET in client code,High,https://nextjs.org/docs/app/building-your-application/configuring/environment-variables -36,Environment,Validate env vars,Check required env vars exist,Validate on startup,Undefined env at runtime,if (!process.env.DATABASE_URL) throw,process.env.DATABASE_URL (might be undefined),High, -37,Environment,Use .env.local for secrets,Local env file for development secrets,.env.local gitignored,Secrets in .env committed,.env.local with secrets,.env with DATABASE_PASSWORD,High, -38,Performance,Analyze bundle size,Use @next/bundle-analyzer,Bundle analyzer in dev,Ship large bundles blindly,ANALYZE=true npm run build,No bundle analysis,Medium,https://nextjs.org/docs/app/building-your-application/optimizing/bundle-analyzer -39,Performance,Use dynamic imports,Code split with next/dynamic,dynamic() for heavy components,Import everything statically,const Chart = dynamic(() => import('./Chart')),import Chart from './Chart',Medium,https://nextjs.org/docs/app/building-your-application/optimizing/lazy-loading -40,Performance,Avoid layout shifts,Reserve space for dynamic content,Skeleton loaders aspect ratios,Content popping in,"",No placeholder for async content,High, -41,Performance,Use Partial Prerendering,Combine static and dynamic in one route,Static shell with Suspense holes,Full dynamic or static pages,Static header + dynamic content,Entire page SSR,Low,https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering -42,Link,Use next/link for navigation,Client-side navigation with prefetching," for internal links", for internal navigation,"About","About",High,https://nextjs.org/docs/app/api-reference/components/link -43,Link,Prefetch strategically,Control prefetching behavior,prefetch={false} for low-priority,Prefetch all links,,Default prefetch on every link,Low, -44,Link,Use scroll option appropriately,Control scroll behavior on navigation,scroll={false} for tabs pagination,Always scroll to top,,Manual scroll management,Low, -45,Config,Use next.config.js correctly,Configure Next.js behavior,Proper config options,Deprecated or wrong options,images: { remotePatterns: [] },images: { domains: [] },Medium,https://nextjs.org/docs/app/api-reference/next-config-js -46,Config,Enable strict mode,Catch potential issues early,reactStrictMode: true,Strict mode disabled,reactStrictMode: true,reactStrictMode: false,Medium, -47,Config,Configure redirects and rewrites,Use config for URL management,redirects() rewrites() in config,Manual redirect handling,redirects: async () => [...],res.redirect in pages,Medium,https://nextjs.org/docs/app/api-reference/next-config-js/redirects -48,Deployment,Use Vercel for easiest deploy,Vercel optimized for Next.js,Deploy to Vercel,Self-host without knowledge,vercel deploy,Complex Docker setup for simple app,Low,https://nextjs.org/docs/app/building-your-application/deploying -49,Deployment,Configure output for self-hosting,Set output option for deployment target,output: 'standalone' for Docker,Default output for containers,output: 'standalone',No output config for Docker,Medium,https://nextjs.org/docs/app/building-your-application/deploying#self-hosting -50,Security,Sanitize user input,Never trust user input,Escape sanitize validate all input,Direct interpolation of user data,DOMPurify.sanitize(userInput),dangerouslySetInnerHTML={{ __html: userInput }},High, -51,Security,Use CSP headers,Content Security Policy for XSS protection,Configure CSP in next.config.js,No security headers,headers() with CSP,No CSP configuration,High,https://nextjs.org/docs/app/building-your-application/configuring/content-security-policy -52,Security,Validate Server Action input,Server Actions are public endpoints,Validate and authorize in Server Action,Trust Server Action input,Auth check + validation in action,Direct database call without check,High, diff --git a/.cursor/skills/ui-ux-pro-max/data/stacks/nuxt-ui.csv b/.cursor/skills/ui-ux-pro-max/data/stacks/nuxt-ui.csv deleted file mode 100644 index 7146e848..00000000 --- a/.cursor/skills/ui-ux-pro-max/data/stacks/nuxt-ui.csv +++ /dev/null @@ -1,51 +0,0 @@ -No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL -1,Installation,Add Nuxt UI module,Install and configure Nuxt UI in your Nuxt project,pnpm add @nuxt/ui and add to modules,Manual component imports,"modules: ['@nuxt/ui']","import { UButton } from '@nuxt/ui'",High,https://ui.nuxt.com/docs/getting-started/installation/nuxt -2,Installation,Import Tailwind and Nuxt UI CSS,Required CSS imports in main.css file,@import tailwindcss and @import @nuxt/ui,Skip CSS imports,"@import ""tailwindcss""; @import ""@nuxt/ui"";",No CSS imports,High,https://ui.nuxt.com/docs/getting-started/installation/nuxt -3,Installation,Wrap app with UApp component,UApp provides global configs for Toast Tooltip and overlays, wrapper in app.vue,Skip UApp wrapper,, without wrapper,High,https://ui.nuxt.com/docs/components/app -4,Components,Use U prefix for components,All Nuxt UI components use U prefix by default,UButton UInput UModal,Button Input Modal,Click,,Medium,https://ui.nuxt.com/docs/getting-started/installation/nuxt -5,Components,Use semantic color props,Use semantic colors like primary secondary error,color="primary" color="error",Hardcoded colors,"","",Medium,https://ui.nuxt.com/docs/getting-started/theme/design-system -6,Components,Use variant prop for styling,Nuxt UI provides solid outline soft subtle ghost link variants,variant="soft" variant="outline",Custom button classes,"","",Medium,https://ui.nuxt.com/docs/components/button -7,Components,Use size prop consistently,Components support xs sm md lg xl sizes,size="sm" size="lg",Arbitrary sizing classes,"","",Low,https://ui.nuxt.com/docs/components/button -8,Icons,Use icon prop with Iconify format,Nuxt UI supports Iconify icons via icon prop,icon="lucide:home" icon="heroicons:user",i-lucide-home format,"","",Medium,https://ui.nuxt.com/docs/getting-started/integrations/icons/nuxt -9,Icons,Use leadingIcon and trailingIcon,Position icons with dedicated props for clarity,leadingIcon="lucide:plus" trailingIcon="lucide:arrow-right",Manual icon positioning,"","Add",Low,https://ui.nuxt.com/docs/components/button -10,Theming,Configure colors in app.config.ts,Runtime color configuration without restart,ui.colors.primary in app.config.ts,Hardcoded colors in components,"defineAppConfig({ ui: { colors: { primary: 'blue' } } })","",High,https://ui.nuxt.com/docs/getting-started/theme/design-system -11,Theming,Use @theme directive for custom colors,Define design tokens in CSS with Tailwind @theme,@theme { --color-brand-500: #xxx },Inline color definitions,@theme { --color-brand-500: #ef4444; },:style="{ color: '#ef4444' }",Medium,https://ui.nuxt.com/docs/getting-started/theme/design-system -12,Theming,Extend semantic colors in nuxt.config,Register new colors like tertiary in theme.colors,theme.colors array in ui config,Use undefined colors,"ui: { theme: { colors: ['primary', 'tertiary'] } }"," without config",Medium,https://ui.nuxt.com/docs/getting-started/theme/design-system -13,Forms,Use UForm with schema validation,UForm supports Zod Yup Joi Valibot schemas,:schema prop with validation schema,Manual form validation,"",Manual @blur validation,High,https://ui.nuxt.com/docs/components/form -14,Forms,Use UFormField for field wrapper,Provides label error message and validation display,UFormField with name prop,Manual error handling,"",
error
,Medium,https://ui.nuxt.com/docs/components/form-field -15,Forms,Handle form submit with @submit,UForm emits submit event with validated data,@submit handler on UForm,@click on submit button,"","",Medium,https://ui.nuxt.com/docs/components/form -16,Forms,Use validateOn prop for validation timing,Control when validation triggers (blur change input),validateOn="['blur']" for performance,Always validate on input,""," (validates on every keystroke)",Low,https://ui.nuxt.com/docs/components/form -17,Overlays,Use v-model:open for overlay control,Modal Slideover Drawer use v-model:open,v-model:open for controlled state,Manual show/hide logic,"",,Medium,https://ui.nuxt.com/docs/components/modal -18,Overlays,Use useOverlay composable for programmatic overlays,Open overlays programmatically without template refs,useOverlay().open(MyModal),Template ref and manual control,"const overlay = useOverlay(); overlay.open(MyModal, { props })","const modal = ref(); modal.value.open()",Medium,https://ui.nuxt.com/docs/components/modal -19,Overlays,Use title and description props,Built-in header support for overlays,title="Confirm" description="Are you sure?",Manual header content,"","",Low,https://ui.nuxt.com/docs/components/modal -20,Dashboard,Use UDashboardSidebar for navigation,Provides collapsible resizable sidebar with mobile support,UDashboardSidebar with header default footer slots,Custom sidebar implementation,,