codexkit 1.0.0

package/.codex/skills/structured-edit/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: structured-edit
+description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
+version: 1.0.0
+tags: [code-quality, workflow]
+dependencies: []
+---
+
+# Structured Edit Protocol
+
+## When to Use
+
+- Editing files where exact string matches are error-prone (e.g., str_replace failures)
+- Making targeted changes that require precise location and verification
+
+## When NOT to Use
+
+- One-line edits where a direct edit is safe and unambiguous
+- Large refactors better served by full rewrites or file splits
+
+## Overview
+
+The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.
+
+**Core principle:** Don't guess content — locate, read, verify, then edit.
+
+## Why This Exists
+
+`str_replace` failures happen when:
+
+| Cause                | Example                                    |
+| -------------------- | ------------------------------------------ |
+| Whitespace mismatch  | Tabs vs spaces, trailing spaces            |
+| Content changed      | File modified since last read              |
+| Multiple matches     | Same string appears twice in file          |
+| Encoding differences | Line endings (CRLF vs LF), invisible chars |
+| Stale context        | Editing from memory instead of fresh read  |
+
+**Result:** Wasted tokens on retries, frustrated developers, broken workflows.
+
+## The Protocol
+
+### Step 1: LOCATE
+
+Use LSP to find exact positions instead of guessing:
+
+```typescript
+// Find where a function is defined
+lsp({ operation: "goToDefinition", filePath, line, character });
+
+// Find all references to a symbol
+lsp({ operation: "findReferences", filePath, line, character });
+
+// Get all symbols in a file
+lsp({ operation: "documentSymbol", filePath, line: 1, character: 1 });
+
+// Search for symbol across workspace
+lsp({ operation: "workspaceSymbol", filePath, line: 1, character: 1 });
+```
+
+### Step 2: READ
+
+Get fresh file content at the located position:
+
+```typescript
+// Read context around target line
+read({ filePath, offset: line - 10, limit: 30 });
+```
+
+**Always include context** — don't just read the target line.
+
+### Step 3: VERIFY
+
+Confirm expected content exists at the location:
+
+```typescript
+// Check that what you expect is actually there
+if (!content.includes(expectedSubstring)) {
+  // STOP — investigate before proceeding
+}
+```
+
+### Step 4: EDIT
+
+Apply minimal, scoped change with unique context:
+
+```typescript
+// Include enough surrounding lines for uniqueness
+edit({
+  filePath,
+  oldString: "  // unique context before\n  targetLine\n  // unique context after",
+  newString: "  // unique context before\n  modifiedLine\n  // unique context after",
+});
+```
+
+**Guidelines:**
+
+- Include 2-3 lines before/after for uniqueness
+- Never use just the target line
+- Keep oldString minimal but unique
+
+### Step 5: CONFIRM
+
+Verify the edit succeeded:
+
+```typescript
+// Read back the modified section
+read({ filePath, offset: line - 5, limit: 15 });
+
+// Confirm content matches intent
+```
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Editing without reading first
+- Assuming content hasn't changed
+- Using large multi-line oldString values
+- Skipping the verify step
+- Guessing line numbers without LSP
+
+**STOP.** Return to Step 1.
+
+## Best Practices
+
+### File Size Matters
+
+From research on the "harness problem":
+
+| File Size     | Strategy                                   |
+| ------------- | ------------------------------------------ |
+| < 100 lines   | Full rewrite often easier than str_replace |
+| 100-400 lines | Structured edit with good context          |
+| > 400 lines   | Strongly prefer structured edits           |
+
+**Prefer smaller files** — composition over monoliths.
+
+### Unique Context Selection
+
+```typescript
+// BAD: Non-unique, whitespace-sensitive
+oldString: "return result;";
+
+// GOOD: Unique with surrounding context
+oldString: "  // Calculate final value\n  const result = compute(input);\n  return result;";
+```
+
+### When to Use LSP vs Direct
+
+| Scenario                  | Approach              |
+| ------------------------- | --------------------- |
+| Finding function/class    | LSP goToDefinition    |
+| Finding all usages        | LSP findReferences    |
+| Modifying specific symbol | LSP + structured edit |
+| Large refactoring         | Consider full rewrite |
+| Simple one-line change    | Direct edit OK        |
+
+## Integration with Other Skills
+
+**Use with:**
+
+- `verification-before-completion` — Always verify edits succeeded
+- `systematic-debugging` — When edit failures indicate deeper issues
+- `defense-in-depth` — Add validation after structural changes
+
+## Quick Reference
+
+```
+LOCATE  → lsp({ operation: "goToDefinition" | "findReferences", ... })
+READ    → read({ filePath, offset: line-10, limit: 30 })
+VERIFY  → Check expected content exists
+EDIT    → edit({ oldString: "...unique context...", newString: "..." })
+CONFIRM → read() again to verify success
+```
+
+## The Bottom Line
+
+**Don't trust your memory. Don't guess content. Locate, read, verify, edit, confirm.**
+
+This protocol eliminates the #1 source of LLM coding failures.

package/.codex/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: subagent-driven-development
+description: Use when executing implementation plans with independent tasks in the current session - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates
+version: 1.0.0
+tags: [workflow, agent-coordination]
+dependencies: [executing-plans]
+---
+
+# Subagent-Driven Development
+
+> **Replaces** monolithic single-agent implementation sessions that grow stale — dispatches fresh subagents per task with code review gates between them
+
+## When to Use
+
+- Executing a plan with mostly independent tasks in the same session
+- You want a fresh subagent per task plus review checkpoints
+
+## When NOT to Use
+
+- The plan requires review or revisions first (use executing-plans)
+- Tasks are tightly coupled and need manual sequencing
+
+## Overview
+
+**vs. Executing Plans (parallel session):**
+
+- Same session (no context switch)
+- Fresh subagent per task (no context pollution)
+- Code review after each task (catch issues early)
+- Faster iteration (no human-in-loop between tasks)
+
+## The Process
+
+### 1. Load Plan
+
+Read plan file, create TodoWrite with all tasks.
+
+**Context file pattern:** If the plan exceeds ~500 tokens, write it to `.beads/artifacts/<id>/plan-context.md` and reference by path in subagent prompts instead of inlining. This saves tokens when dispatching multiple subagents from the same plan.
+
+### 2. Execute Task with Subagent
+
+For each task:
+
+**Dispatch fresh subagent:**
+
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N from [plan-file].
+
+    Read that task carefully. Your job is to:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Report back
+
+    Work from: [directory]
+
+    [Include Structured Termination Contract from AGENTS.md]
+```
+
+**After subagent reports back** — follow the **Worker Distrust Protocol** from AGENTS.md:
+
+1. Read changed files directly (don't trust the report)
+2. Run verification on modified files (typecheck + lint minimum)
+3. Check acceptance criteria against original task spec
+4. Only then mark the task as complete
+
+### 3. Review Subagent's Work
+
+**Dispatch review subagent:**
+
+Use template at requesting-code-review/review.md
+
+WHAT_WAS_IMPLEMENTED: [from subagent's report]
+PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+BASE_SHA: [commit before task]
+HEAD_SHA: [current commit]
+DESCRIPTION: [task summary]
+
+```
+
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
+
+### 4. Apply Review Feedback
+
+**If issues found:**
+
+- Fix Critical issues immediately
+- Fix Important issues before next task
+- Note Minor issues
+
+**Dispatch follow-up subagent if needed:**
+
+```
+
+"Fix issues from code review: [list issues]"
+
+```
+
+### 5. Mark Complete, Next Task
+
+- Mark task as completed in TodoWrite
+- Move to next task
+- Repeat steps 2-5
+
+### 6. Final Review
+
+After all tasks complete, dispatch final review:
+
+- Reviews entire implementation
+- Checks all plan requirements met
+- Validates overall architecture
+
+### 7. Complete Development
+
+After final review passes:
+
+- 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
+
+## Example Workflow
+
+```
+
+You: I'm using Subagent-Driven Development to execute this plan.
+
+[Load plan, create TodoWrite]
+
+Task 1: Hook installation script
+
+[Dispatch implementation subagent]
+Subagent: Implemented install-hook with tests, 5/5 passing
+
+[Get git SHAs, dispatch review]
+Reviewer: Strengths: Good test coverage. Issues: None. Ready.
+
+[Mark Task 1 complete]
+
+Task 2: Recovery modes
+
+[Dispatch implementation subagent]
+Subagent: Added verify/repair, 8/8 tests passing
+
+[Dispatch review]
+Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
+
+[Dispatch fix subagent]
+Fix subagent: Added progress every 100 conversations
+
+[Verify fix, mark Task 2 complete]
+
+...
+
+[After all tasks]
+[Dispatch final review]
+Final reviewer: All requirements met, ready to merge
+
+Done!
+
+```
+
+## Advantages
+
+**vs. Manual execution:**
+
+- Subagents follow TDD naturally
+- Fresh context per task (no confusion)
+- Parallel-safe (subagents don't interfere)
+
+**vs. Executing Plans:**
+
+- Same session (no handoff)
+- Continuous progress (no waiting)
+- Review checkpoints automatic
+
+**Cost:**
+
+- More subagent invocations
+- But catches issues early (cheaper than debugging later)
+
+## Red Flags
+
+**Never:**
+
+- Skip code review between tasks
+- Proceed with unfixed Critical issues
+- Dispatch multiple implementation subagents in parallel (conflicts)
+- Implement without reading plan task
+
+**If subagent fails task:**
+
+- Dispatch fix subagent with specific instructions
+- Don't try to fix manually (context pollution)
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Dispatching subagents for tasks with shared state/files | Creates edit conflicts, race conditions, and unclear ownership | Keep shared-state work sequential under one subagent at a time |
+| Skipping code review between subagent tasks | Lets defects accumulate and compounds later fixes | Run a review gate after each task before moving on |
+| Giving subagents vague prompts without file paths or acceptance criteria | Produces off-target changes and repeated back-and-forth | Provide exact file paths, task scope, and acceptance criteria |
+| Not verifying subagent output before moving to next task | Carries regressions forward into later tasks | Validate output immediately before starting the next task |
+
+## Verification
+
+- After each subagent completes: review its changes, run typecheck + lint on modified files
+- After all tasks: run full test suite to catch integration issues
+- Check: no conflicting edits between subagent outputs
+
+## Integration
+
+**Required workflow skills:**
+
+- **writing-plans** - REQUIRED: Creates the plan that this skill executes
+- **requesting-code-review** - REQUIRED: Review after each task (see Step 3)
+- **finishing-a-development-branch** - REQUIRED: Complete development after all tasks (see Step 7)
+
+**Subagents must use:**
+
+- **test-driven-development** - Subagents follow TDD for each task
+
+**Alternative workflow:**
+
+- **executing-plans** - Use for parallel session instead of same-session execution
+
+See review template: requesting-code-review/review.md
+```
+
+## See Also
+
+- **dispatching-parallel-agents** — for parallel investigation
+- **executing-plans** — for batch execution with checkpoints
+- **requesting-code-review** — for review between subagent tasks

package/.codex/skills/supabase/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: supabase
+description: Comprehensive Supabase platform MCP for database operations, edge functions, development tools, debugging, and project management. Use when working with Supabase projects, databases, or APIs.
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
+---
+
+# Supabase Platform (MCP)
+
+## When to Use
+
+- When you need to manage Supabase projects, databases, or edge functions via MCP.
+
+## When NOT to Use
+
+- When the backend is not Supabase or MCP access is unavailable.
+
+
+## Available Tools
+
+### Account & Projects
+
+- `list_projects` - Lists all Supabase projects
+- `get_project` - Gets details for a specific project
+- `list_organizations` - Lists all organizations
+
+### Database
+
+- `list_tables` - Lists all tables in specified schemas
+- `list_extensions` - Lists PostgreSQL extensions
+- `list_migrations` - Lists database migrations
+- `execute_sql` - Executes raw SQL queries
+
+### Development
+
+- `get_project_url` - Gets the API URL for a project
+- `get_publishable_keys` - Gets anonymous API keys (client-safe)
+- `generate_typescript_types` - Generates TypeScript types from schema
+
+### Edge Functions
+
+- `list_edge_functions` - Lists all Edge Functions
+- `get_edge_function` - Retrieves Edge Function file contents
+- `deploy_edge_function` - Deploys or updates an Edge Function
+
+### Debugging
+
+- `get_logs` - Retrieves logs by service type
+- `get_advisors` - Gets security/performance advisory notices
+
+### Documentation
+
+- `search_docs` - Searches Supabase documentation
+
+## Workflow
+
+### Quick Start
+
+```
+# List projects
+skill_mcp(skill_name="supabase", tool_name="list_projects")
+
+# List tables in database
+skill_mcp(skill_name="supabase", tool_name="list_tables")
+
+# Execute SQL query
+skill_mcp(skill_name="supabase", tool_name="execute_sql", arguments='{"query": "SELECT * FROM users LIMIT 10"}')
+
+# Generate TypeScript types
+skill_mcp(skill_name="supabase", tool_name="generate_typescript_types")
+
+# Search docs
+skill_mcp(skill_name="supabase", tool_name="search_docs", arguments='{"query": "auth custom claims"}')
+```
+
+### Get Project Credentials
+
+```
+# Get API URL and keys for project
+skill_mcp(skill_name="supabase", tool_name="get_project_url")
+skill_mcp(skill_name="supabase", tool_name="get_publishable_keys")
+
+# List Edge Functions
+skill_mcp(skill_name="supabase", tool_name="list_edge_functions")
+
+# Deploy Edge Function
+skill_mcp(skill_name="supabase", tool_name="deploy_edge_function", arguments='{"name": "my-function", "import_map": {...}, "entrypoint": "index.ts"}')
+```
+
+### Debug Issues
+
+```
+# Get logs by service
+skill_mcp(skill_name="supabase", tool_name="get_logs", arguments='{"service": "postgres", "limit": 100}')
+
+# Check advisories
+skill_mcp(skill_name="supabase", tool_name="get_advisors")
+```
+
+## Security Notes
+
+- **Read-only mode**: Set `"read_only": true` in mcp.json to disable write operations
+- **Project scoping**: Use `project_ref` to limit access to specific projects
+- **Environment variables**: Set `SUPABASE_ACCESS_TOKEN` for authentication
+
+## Server Options
+
+For advanced usage, modify `mcp.json`:
+
+```json
+{
+  "supabase": {
+    "command": "npx",
+    "args": ["-y", "@supabase/mcp@latest"],
+    "env": {
+      "SUPABASE_ACCESS_TOKEN": "your-token-here"
+    },
+    "includeTools": ["list_tables", "execute_sql", "..."]
+  }
+}
+```
+
+Configuration options:
+
+- `project_ref` - Scope to specific project (recommended)
+- `read_only` - Restrict to read-only operations (recommended)
+- `features` - Enable specific tool groups
+
+> **Note**: This skill loads 14 essential tools. Excludes experimental (branching) and storage tools that require paid plans.

package/.codex/skills/supabase/mcp.json

@@ -0,0 +1,27 @@
+{
+	"supabase": {
+		"command": "npx",
+		"args": ["-y", "@supabase/mcp-server-supabase@latest"],
+		"env": {
+			"SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
+		},
+		"includeTools": [
+			"list_projects",
+			"get_project",
+			"list_organizations",
+			"list_tables",
+			"list_extensions",
+			"list_migrations",
+			"execute_sql",
+			"get_project_url",
+			"get_publishable_keys",
+			"generate_typescript_types",
+			"list_edge_functions",
+			"get_edge_function",
+			"deploy_edge_function",
+			"get_logs",
+			"get_advisors",
+			"search_docs"
+		]
+	}
+}