@dex-ai/coding-extensions 0.2.4

package/README.md

@@ -0,0 +1,64 @@
+# dex-ai-coding-extensions
+
+Coding workflow skills for [Dex](https://github.com/klxdev/dex-ai-coding-agent) — structured methodologies for specification, implementation, retrospectives, and more.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `spec-design-tasks` | Idea → RFC spec → technical design → task breakdown |
+| `spec-implementation` | Phased implementation: review → explore → plan → test → code → verify |
+| `retrospective` | Post-session learning extraction into Dex's memory system |
+| `skill-creator` | Create and manage Dex skills with proper structure |
+| `git-workflow` | Multi-repo git coordination patterns |
+| `debug-investigate` | Structured debugging and root-cause analysis |
+| `code-review` | Structured code review with quality checks |
+| `extension-dev` | Dex extension development patterns |
+
+## Usage
+
+```typescript
+import { codingExtensions } from '@dex-ai/coding-extensions';
+
+const agent = await Agent.create({
+  extensions: [codingExtensions(), ...otherExtensions],
+});
+```
+
+Load a subset:
+
+```typescript
+codingExtensions({ include: ['spec-implementation', 'debug-investigate'] })
+```
+
+Exclude specific skills:
+
+```typescript
+codingExtensions({ exclude: ['extension-dev'] })
+```
+
+## Structure
+
+```
+src/index.ts          # Single extension that loads all skills
+skills/
+├── spec-design/      # SKILL.md — spec & design workflow
+├── spec-impl/        # SKILL.md — implementation phases
+├── retrospective/    # SKILL.md — memory-based retrospectives
+├── skill-creator/    # SKILL.md — meta-skill for creating skills
+├── git-workflow/     # SKILL.md — multi-repo git patterns
+├── debug-investigate/# SKILL.md — structured debugging
+├── code-review/      # SKILL.md — code review checklist
+└── extension-dev/    # SKILL.md — Dex extension patterns
+```
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dex-ai/coding-extensions",
+  "version": "0.2.4",
+  "description": "Coding workflow skills for Dex — spec design, implementation, retrospectives, debugging, code review, and more.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/bun": "latest",
+    "@changesets/cli": "^2.29.0"
+  },
+  "resolutions": {
+    "@dex-ai/sdk": "file:../dex-ai-sdk"
+  },
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: code-review
+description: Structured code review — checks for correctness, edge cases, error handling, performance, style consistency, and test coverage. Produces actionable feedback with specific file/line references.
+---
+
+## What I do
+
+- Review code changes for correctness, safety, and quality
+- Check error handling, edge cases, and boundary conditions
+- Verify style consistency with the existing codebase
+- Assess test coverage for new/modified code
+- Use LSP diagnostics and type checking as part of review
+- Produce actionable feedback with specific locations and suggestions
+
+## When to use me
+
+Use this skill when:
+- Reviewing your own code before committing
+- The user asks for a code review
+- Validating changes made during an implementation
+- Checking code quality after a refactor
+
+## Core Principles
+
+### Actionable Feedback
+Every comment should be specific and actionable. Not "this could be better" but "line 42: this catch swallows the error — rethrow or log it."
+
+### Severity Levels
+Categorize findings:
+- 🔴 **Critical** — Bugs, security issues, data loss risks
+- 🟡 **Warning** — Edge cases, missing error handling, potential issues
+- 🔵 **Suggestion** — Style improvements, readability, minor optimizations
+- ✅ **Good** — Things done well (positive reinforcement)
+
+### Context-Aware
+Check findings against the project's actual patterns. Don't flag something as wrong if the codebase consistently does it that way.
+
+---
+
+## Review Workflow
+
+### Step 1: Identify Scope
+
+Determine what to review:
+- `git diff --stat` — See changed files
+- `git diff` — See actual changes
+- Or review specific files the user points to
+
+### Step 2: Understand Context
+
+Before reviewing:
+1. Understand the purpose of the change (feature, fix, refactor?)
+2. Read related code to understand the bigger picture
+3. Check for related tests
+4. Use `memory_recall_facts` for relevant project conventions
+
+### Step 3: Automated Checks
+
+Run automated quality gates:
+1. **LSP diagnostics** — `lsp_diagnostics` on modified files
+2. **Type safety** — Look for `any` types, unsafe casts, missing null checks
+3. **AST patterns** — Use `ast_grep_search` to check for known anti-patterns
+
+### Step 4: Manual Review
+
+Check each file for:
+
+#### Correctness
+- Does the logic do what it's supposed to?
+- Are all code paths handled?
+- Are assumptions documented or validated?
+- Do variable names accurately reflect their purpose?
+
+#### Error Handling
+- Are errors caught at appropriate boundaries?
+- Are caught errors handled (not swallowed)?
+- Are error messages informative?
+- Can the caller distinguish error types?
+
+#### Edge Cases
+- Empty inputs, null/undefined values
+- Boundary conditions (off-by-one, max values)
+- Concurrent access or race conditions
+- Network failures, timeouts
+
+#### Performance
+- Unnecessary allocations in loops
+- O(n²) where O(n) is possible
+- Missing early returns
+- Unnecessary awaits or blocking
+
+#### Security
+- Input validation on external data
+- No secrets in code
+- Proper sanitization
+- Authorization checks where needed
+
+#### Style & Consistency
+- Matches existing codebase patterns
+- Naming conventions followed
+- Import ordering consistent
+- No dead code or commented-out blocks
+
+#### Tests
+- New functionality has tests
+- Edge cases tested
+- Error paths tested
+- Existing tests still relevant
+
+### Step 5: Produce Report
+
+Format findings as:
+
+```markdown
+## Code Review: [Description]
+
+### Summary
+[One-paragraph overview of the change and overall assessment]
+
+### Findings
+
+#### 🔴 Critical
+1. **`path/to/file.ts:42`** — [Description]
+   ```typescript
+   // Current
+   } catch (e) {}
+   // Suggested
+   } catch (e) { throw new AppError('context', { cause: e }); }
+   ```
+
+#### 🟡 Warning
+1. **`path/to/file.ts:67`** — [Description]
+   - Suggestion: [What to do]
+
+#### 🔵 Suggestion
+1. **`path/to/file.ts:15`** — [Description]
+
+#### ✅ Good
+1. **`path/to/file.ts:30-45`** — [What's done well]
+
+### Verdict
+- [ ] Ready to merge
+- [ ] Needs changes (see critical/warnings)
+- [ ] Needs discussion
+```
+
+---
+
+## Common Anti-Patterns to Flag
+
+- `catch {}` or `catch (_) {}` — swallowed errors
+- `as any` or `as unknown as T` — unsafe type coercion
+- `// TODO` without tracking — lost intent
+- `console.log` left in production code
+- Missing `await` on async calls
+- Mutable shared state without synchronization
+- Magic numbers without named constants
+- Functions over 50 lines without clear reason
+- Deeply nested conditionals (>3 levels)
+- String concatenation for error messages (use template literals)

package/skills/debug-investigate/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: debug-investigate
+description: Structured debugging and root-cause analysis — reproduce, hypothesize, investigate, fix, verify. Uses AST search, LSP navigation, and memory to systematically diagnose issues.
+---
+
+## What I do
+
+- Systematically diagnose bugs and unexpected behavior
+- Form and test hypotheses using code analysis tools
+- Trace execution paths to find root causes
+- Propose minimal fixes that address the root cause (not symptoms)
+- Store debugging patterns in memory for future reference
+
+## When to use me
+
+Use this skill when:
+- Something isn't working and the cause isn't obvious
+- An error message needs investigation
+- A test is failing unexpectedly
+- Behavior doesn't match expectations
+- Performance issues need diagnosis
+
+## Core Principles
+
+### Reproduce First
+Never guess at fixes without understanding the problem. Reproduce the issue or at minimum understand the exact symptoms.
+
+### Hypothesize, Don't Grep Randomly
+Form specific hypotheses about what could cause the behavior, then test each one. Don't just search the codebase randomly hoping to stumble on the answer.
+
+### Root Cause, Not Symptoms
+Fix the underlying cause. If a null check would "fix" the crash, ask WHY the value is null in the first place.
+
+### Minimal Fix
+Change as little as possible. The fix should be proportional to the bug.
+
+---
+
+## Debugging Workflow
+
+### Phase 1: Understand the Symptoms
+
+1. **Collect information:**
+   - What is the exact error message or unexpected behavior?
+   - What is the expected behavior?
+   - When did it start happening? (recent change?)
+   - Is it consistent or intermittent?
+
+2. **Reproduce (if possible):**
+   - Run the failing command/test
+   - Note the exact output
+   - Identify the entry point
+
+### Phase 2: Form Hypotheses
+
+Based on the symptoms, generate 2-4 specific hypotheses:
+
+```markdown
+## Hypotheses
+
+1. **[Most likely]**: [Description of what might be wrong]
+   - Evidence for: [What supports this]
+   - How to test: [What to look at]
+
+2. **[Alternative]**: [Description]
+   - Evidence for: [What supports this]
+   - How to test: [What to look at]
+```
+
+Prioritize hypotheses by:
+- Recent changes (most bugs come from recent code)
+- Simplest explanation (Occam's razor)
+- Matching error patterns
+
+### Phase 3: Investigate
+
+Test each hypothesis systematically:
+
+1. **Trace the code path** — Use `lsp_navigation` (definition, references, call hierarchy) to follow execution
+2. **Search for patterns** — Use `ast_grep_search` to find related code
+3. **Check types** — Use `lsp_diagnostics` and hover for type information
+4. **Read relevant code** — Read the actual implementation, don't assume
+5. **Check git history** — `git log --oneline -10 -- path/to/file` for recent changes
+6. **Recall context** — `memory_recall_facts` for known issues or patterns
+
+For each hypothesis, either:
+- **Confirmed** — Found the root cause, move to Phase 4
+- **Eliminated** — Evidence disproves this hypothesis, move to next
+- **Needs more info** — Ask the user ONE specific question
+
+### Phase 4: Root Cause Analysis
+
+Once the root cause is found:
+
+```markdown
+## Root Cause
+
+**What**: [One-sentence description of the bug]
+**Where**: `path/to/file.ts:line` — [specific location]
+**Why**: [Why this code produces the wrong behavior]
+**When introduced**: [If identifiable — commit, PR, or "existing"]
+```
+
+### Phase 5: Fix
+
+1. **Propose the fix** — Explain what needs to change and why
+2. **Implement minimally** — Change only what's necessary
+3. **Consider edge cases** — Does the fix handle related scenarios?
+4. **Check for similar bugs** — Use `ast_grep_search` to find similar patterns that might have the same issue
+
+### Phase 6: Verify
+
+1. **Run the failing test/command** — Does it pass now?
+2. **Run related tests** — No regressions?
+3. **Run typecheck** — No type errors introduced?
+4. **Run LSP diagnostics** — Clean on modified files?
+
+### Phase 7: Learn
+
+If the bug revealed a pattern worth remembering:
+- Store the debugging pattern via `memory_remember_fact`
+- If it's a multi-step diagnosis process, store as a procedure
+
+---
+
+## Common Debugging Patterns
+
+### "It worked before"
+→ Check `git log` for recent changes to the affected files
+
+### "It works in isolation but fails in integration"
+→ Look for shared state, import order issues, or missing initialization
+
+### "The type says X but runtime shows Y"
+→ Look for `as` casts, `any` types, or mismatched generics
+
+### "It fails silently"
+→ Look for swallowed errors: `catch {}`, `.catch(() => {})`, missing `await`
+
+### "It works sometimes"
+→ Race conditions, timing issues, or uninitialized state
+
+---
+
+## Anti-Patterns to Avoid
+
+- **Shotgun debugging** — Making random changes hoping something works
+- **Symptom fixing** — Adding null checks without understanding why null
+- **Cargo cult fixes** — Copying solutions without understanding them
+- **Over-fixing** — Rewriting the whole module when one line is wrong
+- **Assuming without reading** — "I think this function does X" — read it

package/skills/extension-dev/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: extension-dev
+description: Dex extension development patterns — creating tools, skills, providers, and lifecycle hooks. Covers the SDK interfaces, wiring into the CLI, testing, and publishing.
+---
+
+## What I do
+
+- Guide creation of new Dex extensions (tools, skills, providers, events)
+- Explain SDK interfaces and patterns
+- Show how to wire extensions into the CLI loader
+- Cover testing patterns for extensions
+- Guide publishing to Verdaccio
+
+## When to use me
+
+Use this skill when:
+- Creating a new Dex extension from scratch
+- Adding tools, skills, or providers to an existing extension
+- Understanding how extensions are loaded and initialized
+- Debugging extension lifecycle issues
+- Publishing extension packages
+
+## Extension Anatomy
+
+An extension is an object conforming to the `Extension` interface:
+
+```typescript
+import type { Extension, Tool, Skill } from "@dex-ai/sdk";
+
+export function myExtension(): Extension {
+  return {
+    name: "my-extension",
+
+    // Tools the agent can call
+    tools: [/* Tool[] */],
+
+    // Skills injected into the system prompt
+    skills: [/* Skill[] */],
+
+    // Event handlers
+    on: {
+      agentStart(ctx) { /* ... */ },
+      agentEnd(ctx) { /* ... */ },
+      toolCall(ctx, call) { /* ... */ },
+    },
+
+    // Lifecycle
+    init(ctx) { /* async setup */ },
+    dispose() { /* cleanup */ },
+  };
+}
+```
+
+## Creating a Tool
+
+```typescript
+import { z } from "zod";
+import type { Tool } from "@dex-ai/sdk";
+
+const myTool: Tool = {
+  name: "my_tool",
+  description: "What the tool does — be specific for the LLM",
+  access: "read", // "read" = no side effects, "write" = modifies state
+  parameters: z.object({
+    input: z.string().describe("Description shown to the model"),
+    optional: z.number().optional().describe("Optional param"),
+  }),
+  execute(input, gctx) {
+    // input is already parsed & validated via zod
+    // gctx provides access to agent state, config, etc.
+    return { type: "text", value: "result" };
+    // or: { type: "error-text", value: "error message" }
+    // or: { type: "json", value: { key: "value" } }
+  },
+};
+```
+
+### Tool Access Levels
+- `"read"` — Safe, no side effects (search, read, inspect)
+- `"write"` — Modifies state (edit files, run commands, git operations)
+
+## Creating a Skill
+
+A skill injects markdown instructions into the system prompt:
+
+```typescript
+const skill: Skill = {
+  name: "my-skill",
+  description: "Short description for the catalog",
+  content: "## Instructions\n\nMarkdown content here...",
+  when: (actx) => true, // Optional: conditional activation
+};
+```
+
+Or load from a SKILL.md file:
+
+```typescript
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const raw = readFileSync(join(import.meta.dir, "..", "skills", "my-skill", "SKILL.md"), "utf-8");
+const body = raw.replace(/^---[\s\S]*?---\s*/, ""); // strip frontmatter
+```
+
+## Extension Loading
+
+Extensions are loaded in the CLI via `createCliExtensions()` in `dex-ai-coding-agent/packages/cli/bin/dex.ts`. The loader imports from:
+- Built-in packages (always loaded)
+- `~/.dex/extensions/` (global user extensions)
+- `<project>/.dex/extensions/` (project-scoped)
+
+To add a new built-in extension:
+1. Create the package (or add to existing)
+2. Add to the imports in `dex.ts`
+3. Add to the extensions array
+
+## State & Context
+
+Extensions can use agent state for cross-extension communication:
+
+```typescript
+// In init or tool execute:
+gctx.agent.state.set("my-key", value);
+const val = gctx.agent.state.get("my-key");
+```
+
+## Testing Extensions
+
+```typescript
+import { describe, it, expect } from "bun:test";
+
+describe("my-tool", () => {
+  it("should return expected result", () => {
+    const tool = myTool;
+    const result = tool.execute({ input: "test" }, mockGctx);
+    expect(result).toEqual({ type: "text", value: "expected" });
+  });
+});
+```
+
+For tools that need agent context, create a minimal mock:
+```typescript
+const mockGctx = {
+  agent: {
+    state: new Map(),
+    config: { /* minimal config */ },
+  },
+} as any;
+```
+
+## Publishing
+
+```bash
+# Bump version
+# Then publish to Verdaccio:
+bun publish --registry http://localhost:4873
+
+# Update consumers:
+cd ../dex-ai-coding-agent
+bun install
+```
+
+## Common Patterns
+
+### Extension with both tools and skills
+Most extensions provide both — tools for actions and skills for instructions on when/how to use them.
+
+### Conditional skills
+Use `when` to only inject a skill when relevant (e.g., only when certain files exist in the project).
+
+### Extension options
+Use a factory function pattern for configurable extensions:
+```typescript
+export function myExtension(opts: { verbose?: boolean } = {}): Extension {
+  return { name: "my-ext", tools: [/* use opts here */] };
+}
+```