codexkit 1.0.0

package/.codex/skills/docs-handoff/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: docs-handoff
+description: Session handoff and resume protocol with explicit status, blockers, and next actions.
+---
+
+# docs-handoff
+
+## Purpose
+Preserve execution context so another contributor can resume work in minutes without rediscovery.
+
+## Use This Skill When
+- Ending a session with unfinished work
+- Handing implementation from one contributor to another
+- Pausing for external dependency (review, CI, infra, product decision)
+- Resuming after interruption or context loss
+
+## Workflow Phases
+1. Capture state
+2. Record blockers
+3. Define next steps
+4. Resume validation
+
+## Expected Outputs
+- Handoff note with concrete state and evidence
+- Clear blockers with owner and unblock condition
+- Ordered next actions for the next contributor
+- Resume checklist with first executable command
+
+## Success Indicators
+- A new contributor can execute the first next step without asking questions
+- Handoff references exact files, branches, and commands
+- Open decisions are explicit, not hidden in prose
+- Resumption starts with verification, not assumptions
+
+## Fast Start
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline -10
+```
+
+## Handoff Workflow
+
+### 1) Capture State
+Document what is done, in progress, and untouched.
+
+Required fields:
+- Current branch
+- Last good verification commands and outcomes
+- Files modified + purpose
+- Pending work item at stopping point
+
+### 2) Record Blockers
+For each blocker, include:
+- Blocker description
+- Owner (person/team/system)
+- Unblock condition (specific event)
+- Workaround status
+
+### 3) Define Next Steps
+Provide top 3-7 actions in strict order.
+Each step should be executable and measurable.
+
+### 4) Resume Validation
+Specify the first commands the next contributor must run to re-establish trust.
+
+## Handoff Document Template (Short)
+```markdown
+## Status
+- Branch: <name>
+- Progress: <done>/<total>
+- Current task: <one sentence>
+
+## Completed
+- <change + file path>
+- <change + file path>
+
+## In Progress
+- <what is partially done>
+- Last edit point: <file:line or function>
+
+## Blockers
+- <blocker> | Owner: <x> | Unblock when: <condition>
+
+## Next Steps
+1. <exact action>
+2. <exact action>
+3. <exact action>
+
+## Verification
+- Last passing: `<command>` -> <result>
+- Re-run first: `<command>`
+```
+
+## Handoff Document Template (Release-Critical)
+```markdown
+## Operational Status
+- Environment impacted:
+- Risk level:
+- Rollback state:
+
+## What Changed
+- Config/runtime changes:
+- Data changes/migrations:
+- External dependencies touched:
+
+## Safety Notes
+- Known failure modes:
+- Alert thresholds to watch:
+- Manual checks required:
+
+## Resume Plan
+1. Validate baseline health
+2. Continue pending implementation
+3. Re-run full verification gates
+4. Prepare review packet
+```
+
+## State Preservation Checklist
+- [ ] Branch name and divergence from base captured
+- [ ] Modified files listed with reason
+- [ ] Exact stopping point recorded (`file:line` or symbol)
+- [ ] Last known good command outputs included
+- [ ] Blockers include owner + unblock condition
+- [ ] Next action is singular and immediately executable
+- [ ] Any temporary flags/toggles documented
+
+## Resume Protocol
+1. Read latest handoff note fully.
+2. Check repository state (`git status`, current branch, untracked files).
+3. Run baseline verification commands from handoff.
+4. Confirm blockers still valid; update if status changed.
+5. Execute only step 1 from “Next Steps”, then reassess.
+
+## Context File Update Patterns
+Use these patterns when updating project context documents:
+
+### Worklog update pattern
+- Add timestamped entry: what changed, why, what remains.
+- Include verification commands actually run.
+- Keep to factual bullets (no long narrative).
+
+### Decision log pattern
+- Record only durable decisions.
+- Include alternatives considered and why rejected.
+- Add impact scope (modules, teams, release risk).
+
+### State snapshot pattern
+- Update active task, blockers, and next action.
+- Remove stale blockers immediately.
+- Ensure “next action” has one clear owner.
+
+## Quality Rules
+- Prefer concrete nouns over pronouns (“payment-retry job” not “it”).
+- Never write “continue later” without exact next command.
+- If uncertain, label as assumption and add validation step.
+- Keep handoff scannable: short bullets, stable headings.
+
+## Anti-Patterns
+- Vague blocker notes (“waiting on backend”).
+- Missing owner/unblock condition.
+- Mixing historical narrative with actionable next steps.
+- Omitting failed attempts and known dead ends.
+
+## Good vs Bad Next Step Examples
+- Good: `Run npm test src/commands/init.test.ts and fix failing assertion in parseConfig().`
+- Bad: `Check tests and fix stuff.`
+- Good: `Rebase branch on main, resolve conflict in src/cli.ts, rerun typecheck.`
+- Bad: `Sync branch.`
+
+## Exit Criteria
+- Handoff note is complete, actionable, and verifiable.
+- Another contributor can resume without synchronous clarification.
+- Risks and blockers are explicit with ownership.

package/.codex/skills/executing-plans/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: executing-plans
+description: Use when a complete implementation plan exists — parses dependency waves, executes independent tasks in parallel via subagents, runs review checkpoints between waves
+version: 2.0.0
+tags: [workflow, planning, parallel]
+dependencies: [writing-plans]
+---
+
+# Executing Plans
+
+> **Replaces** sequential task-by-task implementation — detects parallelizable waves and dispatches subagents concurrently within each wave
+
+## When to Use
+
+- A complete implementation plan exists (`.beads/artifacts/<id>/plan.md` or provided directly)
+- The plan has a dependency graph with wave assignments from `/plan`
+
+## When NOT to Use
+
+- No plan yet (use `writing-plans` or `prd` first)
+- All tasks are tightly sequential with no parallelism opportunity
+- Fewer than 3 tasks (just execute directly, overhead not worth it)
+
+## Overview
+
+Load plan → parse dependency waves → execute each wave (parallel within, sequential between) → review after each wave → next wave.
+
+**Core principle:** Parallel within waves, sequential between waves, review at wave boundaries.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+#### Plan Review Checklist
+
+- [ ] Read the plan file end-to-end
+- [ ] Identify goal, deliverables, risks, and missing pieces
+- [ ] If concerns, ask via `question()` and wait for decision
+- [ ] If no concerns, proceed to wave parsing
+
+1. Read plan file
+2. Review critically — identify any questions or concerns
+3. If concerns: raise them with `question()` tool
+4. If no concerns: proceed
+
+### Step 2: Parse Dependency Graph
+
+Look for the dependency graph section in the plan. The `/plan` command generates this format:
+
+```
+## Dependency Graph
+
+Task A: needs nothing, creates src/models/X.ts
+Task B: needs Task A, creates src/api/X.ts
+Task C: needs nothing, creates src/utils/Y.ts
+Task D: needs Task B + Task C, creates src/routes/Z.ts
+
+Wave 1: A, C  (independent)
+Wave 2: B     (depends on A)
+Wave 3: D     (depends on B, C)
+```
+
+**Extract:**
+- Which tasks belong to each wave
+- Which files each task modifies (for conflict detection)
+- Dependencies between tasks
+
+**If no dependency graph found:** Fall back to sequential execution (batch of 3 tasks).
+
+**File conflict check:** Tasks in the same wave MUST NOT modify the same files. If they do, move one to the next wave.
+
+### Step 3: Create TodoWrite
+
+Create todos for all tasks, grouped by wave:
+
+```typescript
+todowrite({
+  todos: [
+    { content: "Wave 1: Task A — [description]", status: "pending", priority: "high" },
+    { content: "Wave 1: Task C — [description]", status: "pending", priority: "high" },
+    { content: "Wave 1 review checkpoint", status: "pending", priority: "high" },
+    { content: "Wave 2: Task B — [description]", status: "pending", priority: "high" },
+    { content: "Wave 2 review checkpoint", status: "pending", priority: "high" },
+    // ...
+  ]
+});
+```
+
+### Step 4: Execute Wave
+
+**Before starting a wave:** create a git tag for safe rollback:
+
+```bash
+git tag wave-${WAVE_NUMBER}-start
+```
+
+#### Single-task wave (no parallelism needed)
+
+Execute directly in the current agent context. No subagent overhead.
+
+#### Multi-task wave (2+ independent tasks)
+
+Dispatch parallel subagents — one per task:
+
+```typescript
+// Dispatch all tasks in this wave simultaneously
+task({
+  subagent_type: "general",
+  description: `Wave ${N}: Task A — ${taskTitle}`,
+  prompt: `You are implementing Task A from the plan.
+
+## Task
+${taskDescription}
+
+## Files to modify
+${taskFiles.join('\n')}
+
+## Constraints
+- ONLY modify files listed above
+- Follow each step exactly as written in the task
+- Run verification commands specified in the task
+- Commit your changes: git add <specific-files> && git commit -m "feat: ${taskTitle}"
+
+## Report back
+- What you implemented
+- Files changed
+- Verification results (pass/fail)
+- Commit hash
+- Any issues or blockers`
+});
+// ...dispatch other tasks in this wave simultaneously
+```
+
+**Critical rules for parallel dispatch:**
+
+| Rule | Why |
+| --- | --- |
+| Non-overlapping files | Subagents editing same file = merge conflicts |
+| Exact file list per subagent | Prevents scope creep into other tasks |
+| Each subagent commits independently | Clean git history per task |
+| Never `git add .` | Only stage files from this task |
+
+#### Wave Execution Checklist
+
+- [ ] Create wave start tag: `git tag wave-${WAVE_NUMBER}-start`
+- [ ] Dispatch subagents for all tasks in this wave (parallel)
+- [ ] Collect results from all subagents
+- [ ] Check for failures — if any task failed, stop and report
+- [ ] Run verification gates (typecheck + lint in parallel, then tests)
+- [ ] Create wave complete tag: `git tag wave-${WAVE_NUMBER}-complete`
+- [ ] Mark wave tasks as completed in TodoWrite
+
+### Step 5: Review Wave
+
+After each wave completes:
+
+1. **Synthesize results** from all subagents
+2. **Run verification gates** on the combined changes:
+   ```bash
+   # Parallel: typecheck + lint
+   npm run typecheck & npm run lint & wait
+   # Sequential: tests
+   npm test
+   ```
+3. **Report to user:**
+   - Tasks completed in this wave
+   - Verification results
+   - Wave tag created
+   - Any issues found
+4. **Wait for feedback** before proceeding to next wave
+
+### Step 6: Next Wave
+
+Based on feedback:
+- Apply corrections if needed
+- Execute next wave (repeat Steps 4-5)
+- Continue until all waves complete
+
+### Step 7: Complete Development
+
+After all waves complete and verified:
+
+- Announce: "I'm using finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use skill({ name: "finishing-a-development-branch" })
+- Follow that skill to verify tests, present options, execute choice
+
+## Wave-Level Rollback with Git Tags
+
+Git tags act as checkpoints between waves. If a wave fails irrecoverably, roll back to the last known-good state.
+
+### Tag Protocol
+
+| When                         | Command                         | Purpose                   |
+| ---------------------------- | ------------------------------- | ------------------------- |
+| Before starting any wave     | `git tag wave-N-start`          | Mark rollback point       |
+| After wave passes all gates  | `git tag wave-N-complete`       | Seal confirmed-good state |
+| On irrecoverable failure     | `git reset --hard wave-N-start` | Restore to pre-wave state |
+| Listing all wave checkpoints | `git tag --list "wave-*"`       | Audit trail of execution  |
+
+### When to Rollback
+
+Roll back (with user confirmation) when:
+- Verification gates fail twice consecutively in the same wave
+- Subagent made destructive changes outside its file scope
+- Tests were broken and the cause is unclear
+
+**Always ask the user before running `git reset --hard`** — it discards uncommitted changes irreversibly.
+
+## Sequential Fallback
+
+If the plan has no dependency graph or waves:
+
+1. Group tasks into batches of 3
+2. Execute each batch sequentially (no parallel subagents)
+3. Review between batches
+4. Same wave-tag protocol applies
+
+This preserves backward compatibility with plans that don't have wave assignments.
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Subagent reports a blocker or failure
+- File conflict detected between parallel tasks
+- Verification fails twice in the same wave
+- Plan has critical gaps preventing starting
+
+**Ask for clarification rather than guessing.**
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Dispatching parallel subagents for tasks that share files | Edit conflicts, lost changes, merge chaos | Move conflicting tasks to separate waves |
+| Skipping verification between waves | Broken code compounds across waves | Run all gates after each wave before proceeding |
+| Giving subagents the full plan instead of their task | Context pollution, scope creep | Extract only the specific task + file list |
+| Running all tasks in one wave regardless of dependencies | Later tasks fail because prerequisites aren't ready | Respect the dependency graph strictly |
+| Not committing per-task | Can't rollback individual tasks, messy git history | Each subagent commits its own changes |
+
+## See Also
+
+- `writing-plans` — Create detailed, zero-ambiguity implementation plans before execution
+- `swarm-coordination` — For 10+ task scenarios with full PARL orchestration
+- `subagent-driven-development` — For sequential per-task execution with review between each
+- `verification-before-completion` — Run final verification gates before claiming completion

package/.codex/skills/figma/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: figma
+description: Access Figma design data via Framelink MCP. Fetch layout, styles, components from Figma files/frames. Use when implementing UI from Figma designs, extracting design tokens, or downloading assets.
+mcp:
+  figma:
+    command: npx
+    args: ["-y", "figma-developer-mcp", "--stdio"]
+    env:
+      FIGMA_API_KEY: "${FIGMA_API_KEY}"
+version: 1.0.0
+tags: [design, mcp, integration]
+dependencies: []
+---
+
+# Figma Design Data (MCP)
+
+## When to Use
+
+- When you need to fetch layout, styles, or assets from a Figma file via MCP.
+
+## When NOT to Use
+
+- When no Figma file key/node ID is available or design data isn't required.
+
+
+## Prerequisites
+
+Set your Figma API key as an environment variable:
+
+```bash
+export FIGMA_API_KEY="your-figma-personal-access-token"
+```
+
+To create a Figma Personal Access Token:
+
+1. Go to Figma → Settings → Account → Personal access tokens
+2. Create a new token with read access
+3. See: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
+
+## Quick Start
+
+After loading this skill, use `skill_mcp` to invoke Figma tools:
+
+```
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "1234:5678"}')
+```
+
+## Available Tools
+
+### get_figma_data
+
+Fetch comprehensive Figma file data including layout, content, visuals, and component information.
+
+| Parameter | Type   | Required | Description                                                                                       |
+| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `fileKey` | string | Yes      | The Figma file key (from URL: `figma.com/file/<fileKey>/...` or `figma.com/design/<fileKey>/...`) |
+| `nodeId`  | string | No       | Specific node ID (from URL param `node-id=<nodeId>`). Format: `1234:5678` or `1234-5678`          |
+| `depth`   | number | No       | Levels deep to traverse. Only use if explicitly requested by user.                                |
+
+**Returns:** YAML-formatted design data with:
+
+- `metadata` - File/node information
+- `nodes` - Simplified node tree with layout, styles, text content
+- `globalVars` - Shared styles and variables
+
+### download_figma_images
+
+Download SVG and PNG images/icons from a Figma file.
+
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `fileKey`   | string | Yes      | The Figma file key                            |
+| `nodes`     | array  | Yes      | Array of node objects to download (see below) |
+| `localPath` | string | Yes      | Absolute path to save images                  |
+| `pngScale`  | number | No       | Export scale for PNGs (default: 2)            |
+
+**Node object structure:**
+
+```json
+{
+  "nodeId": "1234:5678",
+  "fileName": "icon-name.svg",
+  "imageRef": "optional-for-image-fills"
+}
+```
+
+## Workflow
+
+### 1. Extract File Key and Node ID from Figma URL
+
+Figma URLs follow these patterns:
+
+- `https://www.figma.com/file/<fileKey>/<fileName>?node-id=<nodeId>`
+- `https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>`
+
+Example: `https://www.figma.com/design/abc123xyz/MyDesign?node-id=1234-5678`
+
+- `fileKey`: `abc123xyz`
+- `nodeId`: `1234-5678` (or `1234:5678` - both formats work)
+
+### 2. Fetch Design Data
+
+```
+# Fetch specific frame/component
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz", "nodeId": "1234:5678"}')
+
+# Fetch entire file (use sparingly - can be large)
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz"}')
+```
+
+### 3. Download Assets (Optional)
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "abc123xyz",
+  "nodes": [
+    {"nodeId": "1234:5678", "fileName": "hero-image.png"},
+    {"nodeId": "5678:9012", "fileName": "icon-arrow.svg"}
+  ],
+  "localPath": "/absolute/path/to/assets"
+}')
+```
+
+## Examples
+
+### Implement a Component from Figma
+
+```
+# User provides: https://www.figma.com/design/abc123/Dashboard?node-id=100-200
+
+# 1. Fetch the design data
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "100-200"}')
+
+# 2. Review the returned YAML for:
+#    - Layout structure (flex, grid, spacing)
+#    - Typography (font, size, weight, line-height)
+#    - Colors (fills, strokes)
+#    - Dimensions and constraints
+
+# 3. Implement the component using the extracted data
+```
+
+### Extract Design Tokens
+
+```
+# Fetch a design system file
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "designSystemKey"}')
+
+# The globalVars section contains:
+# - Color styles
+# - Typography styles
+# - Effect styles (shadows, blurs)
+```
+
+### Download Icons
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "iconLibraryKey",
+  "nodes": [
+    {"nodeId": "10:20", "fileName": "icon-home.svg"},
+    {"nodeId": "10:30", "fileName": "icon-settings.svg"},
+    {"nodeId": "10:40", "fileName": "icon-user.svg"}
+  ],
+  "localPath": "/project/src/assets/icons",
+  "pngScale": 2
+}')
+```
+
+## Data Structure
+
+The `get_figma_data` tool returns simplified, AI-optimized data:
+
+```yaml
+metadata:
+  name: "Component Name"
+  lastModified: "2024-01-15T..."
+
+nodes:
+  - id: "1234:5678"
+    name: "Button"
+    type: "FRAME"
+    layout:
+      mode: "HORIZONTAL"
+      padding: { top: 12, right: 24, bottom: 12, left: 24 }
+      gap: 8
+    size: { width: 120, height: 48 }
+    fills:
+      - type: "SOLID"
+        color: { r: 0.2, g: 0.4, b: 1, a: 1 }
+    cornerRadius: 8
+    children:
+      - id: "1234:5679"
+        name: "Label"
+        type: "TEXT"
+        content: "Click me"
+        textStyle:
+          fontFamily: "Inter"
+          fontSize: 16
+          fontWeight: 600
+
+globalVars:
+  styles:
+    "S:abc123": { name: "Primary", fills: [...] }
+```
+
+## Tips
+
+- **Always use nodeId** when provided - fetching entire files is slow and context-heavy
+- **Node IDs with `-` or `:`** both work - the MCP handles conversion
+- **Check globalVars** for reusable styles before hardcoding values
+- **Use depth parameter sparingly** - only when explicitly needed
+- **For images/icons**, identify nodes with `imageRef` in the data for proper downloading
+- **SVG vs PNG**: Use `.svg` for icons/vectors, `.png` for photos/complex images
+
+## Troubleshooting
+
+**"Invalid API key"**: Ensure `FIGMA_API_KEY` environment variable is set correctly.
+
+**"File not found"**: Verify the fileKey is correct and you have access to the file.
+
+**"Node not found"**: Check the nodeId format. Try both `1234:5678` and `1234-5678`.
+
+**Large response**: Use `nodeId` to fetch specific frames instead of entire files.

package/.codex/skills/figma/mcp.json

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