codexkit 1.0.0

package/.codex/skills/ui-ux-research/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ui-ux-research
+description: "Merged into design-system-audit. Load that skill instead."
+---
+
+# UI/UX Research
+
+## Status
+
+This skill remains as a compatibility redirect for older references.
+
+## Replacement
+
+Load `design-system-audit` instead.
+
+## Why It Moved
+
+`design-system-audit` now covers the practical work that used to live here:
+
+- UI pattern analysis
+- design token auditing
+- visual comparison
+- component consistency checks
+
+## How to Proceed
+
+When a task mentions `ui-ux-research`, treat it as:
+
+1. Load `design-system-audit`.
+2. Reuse `accessibility-audit` if the task also includes accessibility review.
+3. Prefer `visual-analysis` when screenshots or mockups are the main input.
+
+## Note
+
+This file intentionally stays small, but it is substantive enough to explain the redirect and preserve backward compatibility.

package/.codex/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
+version: 1.0.0
+tags: [git, workflow]
+dependencies: []
+---
+
+# Using Git Worktrees
+
+## When to Use
+
+- When starting feature work that needs an isolated workspace or before executing an implementation plan.
+
+## When NOT to Use
+
+- When a simple change can safely be done in the current working tree or the repo does not allow worktrees.
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check AGENTS.md
+
+```bash
+grep -i "worktree.*director" AGENTS.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no AGENTS.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.codex/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify .gitignore before creating worktree:**
+
+```bash
+# Check if directory pattern in .gitignore
+grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
+```
+
+**If NOT in .gitignore:**
+
+Per Jesse's rule "Fix broken things immediately":
+
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.codex/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.codex/worktrees/*)
+    path="~/.codex/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+## Worktree Tracking
+
+After creating a worktree, persist its absolute path for session resume:
+
+```bash
+# After creating worktree
+mkdir -p .beads/artifacts/$BEAD_ID
+echo "/absolute/path/to/worktree" > .beads/artifacts/$BEAD_ID/worktree.txt
+```
+
+On session resume, restore the active worktree if tracking exists:
+
+```bash
+# Check if worktree exists for active bead
+if [ -f .beads/artifacts/$BEAD_ID/worktree.txt ]; then
+  WORKTREE_PATH=$(cat .beads/artifacts/$BEAD_ID/worktree.txt)
+  cd "$WORKTREE_PATH"
+fi
+```
+
+On worktree cleanup (after merge), remove the tracking file:
+
+```bash
+rm -f .beads/artifacts/$BEAD_ID/worktree.txt
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation                   | Action                      |
+| --------------------------- | --------------------------- |
+| `.worktrees/` exists        | Use it (verify .gitignore)  |
+| `worktrees/` exists         | Use it (verify .gitignore)  |
+| Both exist                  | Use `.worktrees/`           |
+| Neither exists              | Check AGENTS.md → Ask user  |
+| Directory not in .gitignore | Add it immediately + commit |
+| Tests fail during baseline  | Report failures + ask       |
+| No package.json/Cargo.toml  | Skip dependency install     |
+
+## Common Mistakes
+
+**Skipping .gitignore verification**
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always grep .gitignore before creating project-local worktree
+
+**Assuming directory location**
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > AGENTS.md > ask
+
+**Proceeding with failing tests**
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+**Hardcoding setup commands**
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify .gitignore - contains .worktrees/]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+
+- Create worktree without .gitignore verification (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip AGENTS.md check
+
+**Always:**
+
+- Follow directory priority: existing > AGENTS.md > ask
+- Verify .gitignore for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- Any skill needing isolated workspace
+
+**Pairs with:**
+
+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
+- **executing-plans** or **subagent-driven-development** - Work happens in this worktree

package/.codex/skills/using-skills/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: using-skills
+description: Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists
+version: 1.0.0
+tags: [workflow, context]
+dependencies: []
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+# Getting Started with Skills
+
+## When to Use
+
+- At the start of any conversation or task to determine applicable skills
+- Whenever you are about to act and need to check for mandatory workflows
+
+## When NOT to Use
+
+- After you already loaded the correct skill and are executing it
+- For a task that explicitly says to follow a different skill workflow
+
+## MANDATORY FIRST RESPONSE PROTOCOL
+
+Before responding to ANY user message, you MUST complete this checklist:
+
+1. ☐ List available skills in your mind
+2. ☐ Ask yourself: "Does ANY skill match this request?"
+3. ☐ If yes → Use the Skill tool to read and run the skill file
+4. ☐ Announce which skill you're using
+5. ☐ Follow the skill exactly
+
+**Responding WITHOUT completing this checklist = automatic failure.**
+
+## Critical Rules
+
+1. **Follow mandatory workflows.** Brainstorming before coding. Check for relevant skills before ANY task.
+
+2. Execute skills with the Skill tool
+
+## Common Rationalizations That Mean You're About To Fail
+
+If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Check for and use the skill.
+
+- "This is just a simple question" → WRONG. Questions are tasks. Check for skills.
+- "I can check git/files quickly" → WRONG. Files don't have conversation context. Check for skills.
+- "Let me gather information first" → WRONG. Skills tell you HOW to gather information. Check for skills.
+- "This doesn't need a formal skill" → WRONG. If a skill exists for it, use it.
+- "I remember this skill" → WRONG. Skills evolve. Run the current version.
+- "This doesn't count as a task" → WRONG. If you're taking action, it's a task. Check for skills.
+- "The skill is overkill for this" → WRONG. Skills exist because simple things become complex. Use it.
+- "I'll just do this one thing first" → WRONG. Check for skills BEFORE doing anything.
+
+**Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
+
+If a skill for your task exists, you must use it or you will fail at your task.
+
+## Skills with Checklists
+
+If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
+
+**Don't:**
+
+- Work through checklist mentally
+- Skip creating todos "to save time"
+- Batch multiple items into one todo
+- Mark complete without doing them
+
+**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.
+
+## Announcing Skill Usage
+
+Before using a skill, announce that you are using it.
+"I'm using [Skill Name] to [what you're doing]."
+
+**Examples:**
+
+- "I'm using the brainstorming skill to refine your idea into a design."
+- "I'm using the test-driven-development skill to implement this feature."
+
+**Why:** Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.
+
+# About these skills
+
+**Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
+
+**Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
+
+The skill itself tells you which type it is.
+
+## Instructions ≠ Permission to Skip Workflows
+
+Your human partner's specific instructions describe WHAT to do, not HOW.
+
+"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
+
+**Red flags:** "Instruction was specific" • "Seems simple" • "Workflow is overkill"
+
+**Why:** Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.
+
+## Summary
+
+**Starting any task:**
+
+1. If relevant skill exists → Use the skill
+2. Announce you're using it
+3. Follow what it says
+
+**Skill has checklist?** TodoWrite for every item.
+
+**Finding a relevant skill = mandatory to read and use it. Not optional.**

package/.codex/skills/v0/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: v0
+description: AI-powered UI generation via v0 MCP. Create chats, generate React components, get design assistance. Use when building UI components, dashboards, or need AI design help.
+mcp:
+  v0:
+    command: npx
+    args: ["mcp-remote", "https://mcp.v0.dev", "--header", "Authorization: Bearer ${V0_API_KEY}"]
+    env:
+      V0_API_KEY: "${V0_API_KEY}"
+version: 1.0.0
+tags: [ui, mcp, design]
+dependencies: []
+---
+
+# v0 AI Code Generation (MCP)
+
+## When to Use
+
+- When you need AI-generated UI components or chat-based design iteration via v0.
+
+## When NOT to Use
+
+- When you need to implement UI from a fixed design system without AI generation.
+
+
+## Prerequisites
+
+Set your v0 API key as an environment variable:
+
+```bash
+export V0_API_KEY="your-v0-api-key"
+```
+
+To get your v0 API key:
+
+1. Go to [v0 account settings](https://v0.app/chat/settings/keys)
+2. Create a new API key
+3. Copy and set as environment variable
+
+## Quick Start
+
+After loading this skill, list available tools:
+
+```
+skill_mcp(skill_name="v0", list_tools=true)
+```
+
+Then invoke tools:
+
+```
+skill_mcp(skill_name="v0", tool_name="create_chat", arguments='{"prompt": "Create a React dashboard component with a sidebar"}')
+```
+
+## Available Tools
+
+### create_chat
+
+Create a new v0 chat with a prompt.
+
+| Parameter | Type   | Required | Description                        |
+| --------- | ------ | -------- | ---------------------------------- |
+| `prompt`  | string | Yes      | The prompt for v0 to generate code |
+
+**Example:**
+
+```
+skill_mcp(skill_name="v0", tool_name="create_chat", arguments='{"prompt": "Build a responsive navbar with dark mode toggle"}')
+```
+
+### get_chat
+
+Get details about an existing chat.
+
+| Parameter | Type   | Required | Description    |
+| --------- | ------ | -------- | -------------- |
+| `chatId`  | string | Yes      | The v0 chat ID |
+
+**Example:**
+
+```
+skill_mcp(skill_name="v0", tool_name="get_chat", arguments='{"chatId": "abc123"}')
+```
+
+### find_chats
+
+Search through your v0 chats.
+
+| Parameter | Type   | Required | Description  |
+| --------- | ------ | -------- | ------------ |
+| `query`   | string | No       | Search query |
+
+**Example:**
+
+```
+skill_mcp(skill_name="v0", tool_name="find_chats", arguments='{"query": "React components"}')
+```
+
+### send_message
+
+Continue a conversation in an existing chat.
+
+| Parameter | Type   | Required | Description     |
+| --------- | ------ | -------- | --------------- |
+| `chatId`  | string | Yes      | The v0 chat ID  |
+| `message` | string | Yes      | Message to send |
+
+**Example:**
+
+```
+skill_mcp(skill_name="v0", tool_name="send_message", arguments='{"chatId": "abc123", "message": "Add dark mode support"}')
+```
+
+## Workflow
+
+### 1. Generate a New Component
+
+```
+# Create a new chat with your requirements
+skill_mcp(skill_name="v0", tool_name="create_chat", arguments='{"prompt": "Create a modern pricing table with 3 tiers using Tailwind CSS"}')
+
+# The response includes a chat ID and generated code
+```
+
+### 2. Iterate on Design
+
+```
+# Send follow-up messages to refine
+skill_mcp(skill_name="v0", tool_name="send_message", arguments='{"chatId": "chat-id-here", "message": "Make the recommended tier more prominent with a gradient border"}')
+```
+
+### 3. Search Previous Work
+
+```
+# Find relevant previous chats
+skill_mcp(skill_name="v0", tool_name="find_chats", arguments='{"query": "dashboard"}')
+```
+
+## Use Cases
+
+- **Component Generation**: Create React/Next.js components from descriptions
+- **UI Prototyping**: Rapidly prototype UI ideas
+- **Design Iteration**: Refine designs through conversation
+- **Code Assistance**: Get help with Tailwind CSS, responsive design, etc.
+
+## Tips
+
+- **Be specific** in prompts - include framework (React, Next.js), styling (Tailwind, CSS), and functionality details
+- **Iterate** using `send_message` rather than creating new chats for refinements
+- **Search first** with `find_chats` to reuse previous work
+- **Include context** about your existing design system or component patterns
+
+## Troubleshooting
+
+**"Invalid API key"**: Ensure `V0_API_KEY` environment variable is set correctly.
+
+**"Rate limit exceeded"**: v0 has usage limits. Wait a few minutes or check your plan.
+
+**"Chat not found"**: Verify the chat ID is correct. Use `find_chats` to list available chats.

package/.codex/skills/v0/mcp.json

@@ -0,0 +1,6 @@
+{
+  "server": {
+    "command": "npx",
+    "args": ["-y", "@v0/mcp"]
+  }
+}