codexkit 1.0.0

package/.codex/skills/debugging/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: debugging
+description: Scientific debugging workflow emphasizing measurement, hypothesis testing, and proof before fixes.
+---
+
+# debugging
+
+## Purpose
+Identify true root cause using disciplined experiments instead of guesswork.
+
+## Use This Skill When
+- Unexpected runtime behavior
+- Intermittent failures
+- Complex integration defects
+- Non-obvious regressions
+
+## Workflow Phases
+1. Observe
+2. Hypothesize
+3. Test
+4. Conclude
+
+## Expected Outputs
+- Validated root cause
+- Rejected hypotheses log
+- Minimal fix direction
+- Verification plan
+
+## Success Indicators
+- At least two hypotheses considered
+- Evidence gathered for each test
+- Root cause proven with reproducible experiment
+- Fix verified with targeted test
+
+## Fast Start
+Run these commands to establish immediate context:
+
+```bash
+npm test -- --runInBand
+grep -R "error" logs
+node --trace-warnings
+```
+
+## Scientific Loop
+- **Observe**: capture facts only.
+- **Hypothesize**: propose falsifiable explanations.
+- **Test**: run smallest decisive experiment.
+- **Conclude**: accept/reject hypothesis with evidence.
+
+## Binary Search Debugging
+- Split call chain in half.
+- Instrument midpoint.
+- If midpoint is good, move downstream; else upstream.
+- Repeat until defective step isolated.
+
+## Delta Debugging
+- Start from failing input/config.
+- Remove half the variables.
+- Re-test and keep failing subset.
+- Continue until minimal failure-inducing set remains.
+
+## Anti-Guess Rules
+- No code changes before first confirmed hypothesis.
+- No "probably" language without a test artifact.
+- Every proposed fix must map to observed evidence.
+
+## Process Table
+
+| Step | Action | Artifact |
+|---|---|---|
+| 1 | Execute observe activities | Notes + evidence for observe |
+| 2 | Execute hypothesize activities | Notes + evidence for hypothesize |
+| 3 | Execute test activities | Notes + evidence for test |
+| 4 | Execute conclude activities | Notes + evidence for conclude |
+
+## Validation Checklist
+
+- [ ] Commands execute successfully in local environment
+- [ ] Evidence is attached to claims
+- [ ] Constraints from `.codex/context/` are respected
+- [ ] Changes are minimal and scoped to objective
+- [ ] Outstanding risks are disclosed explicitly
+
+## Examples
+
+### Example A — Minimal Scope
+
+```text
+Input: small bugfix request in one module
+Action: run focused workflow, collect evidence, ship minimal patch
+Output: concise summary + verification commands
+```
+
+### Example B — Multi-Step Scope
+
+```text
+Input: multi-file update with dependencies
+Action: plan sequence, execute in waves, verify after each wave
+Output: dependency-aware report with risks and follow-ups
+```
+
+## Decision Tree
+
+```text
+Start
+  |
+  +-- Is scope and objective clear? -- no --> Clarify objective and constraints
+  |                                           |                                      yes
+  +-- Are prerequisites available? -- no --> Gather missing context/evidence first
+  |                                           |                                      yes
+  +-- Execute workflow phases in order
+  |
+  +-- Did verification pass? -- no --> Iterate with smallest corrective change
+  |                                     |                                yes
+  +-- Publish output artifact and next action
+```
+
+## Command Snippets
+
+```bash
+# read current context
+ls -la
+cat .codex/context/index.md
+
+# inspect repository health
+git status --short
+git diff --stat
+
+# standard validation gates
+npm run typecheck
+npm test
+```
+
+## Checklist
+
+- [ ] Objective and scope captured in one sentence
+- [ ] Inputs and constraints explicitly listed
+- [ ] Workflow phases executed in order
+- [ ] Edge cases considered for touched behavior
+- [ ] Validation command output captured
+- [ ] Risks documented with mitigation
+- [ ] Next action identified
+
+## Common Pitfalls
+
+| Pitfall | Symptom | Prevention |
+|---|---|---|
+| Guessing instead of verifying | Fast but wrong conclusions | Require command evidence |
+| Oversized scope | Long-running changes with unclear finish | Split into smaller batches |
+| Hidden dependencies | “Works locally” but breaks elsewhere | Write explicit needs/creates |
+| Incomplete verification | Claims done without proof | Use fixed verification checklist |
+
+## Output Contract
+
+Return a concise structured summary:
+
+```markdown
+## Summary
+-
+
+## Evidence
+- Commands run and outcomes
+
+## Risks
+-
+
+## Next Action
+-
+```
+
+## Advanced Guidance
+
+### Risk Register Template
+
+| Risk | Likelihood | Impact | Mitigation | Owner |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+### Communication Template
+
+- **Context:**
+- **Decision:**
+- **Why:**
+- **Trade-offs:**
+- **Follow-up:**
+
+## Evidence Standards
+
+- Prefer direct command output over narrative claims.
+- Prefer file paths and line references for non-trivial assertions.
+- Prefer before/after comparisons when behavior changed.
+
+## Integration Points
+
+- Read foundational context from `.codex/context/index.md`.
+- Use `.codex/context/worklog.md` for session continuity.
+- Align with neighboring procedures in the canonical `.codex/skills/` inventory when chaining workflows.
+
+## Exit Criteria
+
+- Objective met and verifiable.
+- No unresolved blocker hidden in notes.
+- Next contributor can continue without re-discovery.

package/.codex/skills/deep-research/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: deep-research
+description: >
+  Use when analyzing unfamiliar code, implementing complex features, or entering thorough research mode.
+  Provides structured LSP exploration (all 9 operations), memory-first protocol, and confidence-scored findings.
+  Integrates with scout agent deep mode and research command --thorough flag.
+version: 1.0.0
+tags: [research, workflow]
+dependencies: []
+---
+
+# Deep Research - Comprehensive Code Understanding
+
+## When to Use
+
+- **Complex implementation**: Feature touches 3+ files or unfamiliar modules
+- **Thorough mode**: `/research <topic> --thorough` or scout deep mode
+- **Pre-edit understanding**: Before modifying code you don't fully understand
+- **Architecture exploration**: Understanding how systems connect
+- **Debugging**: Tracing behavior through multiple layers
+
+## When NOT to Use
+
+- Quick syntax lookup (use quick mode instead)
+- Well-understood code with obvious changes
+- Time-constrained fixes (accept lower confidence)
+
+## Core Protocol
+
+### Phase 1: Memory First (Skip External If Found)
+
+```typescript
+// Search past research on this topic
+memory_search({ query: "<topic keywords>", limit: 5 });
+
+// Check for related observations
+memory_search({ query: "<topic> gotchas patterns", limit: 3 });
+
+// Load relevant project context
+memory_read({ file: "project/architecture" });
+memory_read({ file: "project/gotchas" });
+```
+
+**Stop condition**: If memory returns high-confidence findings on this exact topic, synthesize and skip to documentation. Only proceed to exploration if:
+
+- No relevant memory found
+- Memory findings are outdated or incomplete
+- Question requires fresh analysis
+
+### Phase 2: LSP Exploration (Delegate to Explore Agent)
+
+**Delegate to explore agent** for comprehensive LSP analysis instead of manual operations:
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "LSP analysis of <target>",
+  prompt: `Very thorough LSP analysis of <symbol/module>.
+
+Target files:
+- src/path/to/file.ts
+- src/related/module.ts
+
+Questions to answer:
+1. What is the type signature of <symbol>?
+2. What calls this function? (incoming calls)
+3. What does this function call? (outgoing calls)
+4. Where is this symbol referenced across the codebase?
+5. Are there interface implementations to consider?
+
+Return structured findings with file:line references.`,
+});
+```
+
+The explore agent will run:
+
+- `documentSymbol` - File structure overview
+- `goToDefinition` - Symbol definitions
+- `findReferences` - All usages across codebase
+- `hover` - Type info and documentation
+- `workspaceSymbol` - Workspace-wide search
+- Call hierarchy (incoming/outgoing calls)
+
+**When to run LSP manually instead:**
+
+- Single symbol lookup (quick mode)
+- Explore agent unavailable
+- Need specific operation only
+
+### Phase 3: Pattern Discovery
+
+```typescript
+// Find similar patterns in codebase (use project's file extension: *.ts, *.py, *.rs, *.go, *.java, etc.)
+grep({ pattern: "<relevant pattern>", include: "*.<ext>" });
+
+// Locate related files
+glob({ pattern: "src/**/*<topic>*" });
+
+// Check tests for usage examples (adapt glob to project conventions)
+// JS/TS: **/*.test.ts, **/*.spec.ts  |  Python: **/test_*.py  |  Rust: **/tests/**
+// Go: **/*_test.go  |  Java: **/src/test/**/*.java
+glob({ pattern: "**/*test*" });
+grep({ pattern: "<function name>", include: "*test*" });
+```
+
+### Phase 4: External Research (If Needed)
+
+Only if internal exploration doesn't answer the question:
+
+```typescript
+// Official docs
+context7({ operation: "resolve", libraryName: "<lib>" });
+context7({ operation: "query", libraryId: "<id>", topic: "<specific question>" });
+
+// Real-world patterns (adapt language parameter to project)
+codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
+grepsearch({ query: "<code pattern>", language: "<project language>" });
+```
+
+## Confidence Levels
+
+Score every finding:
+
+| Level      | Criteria                                   | Action               |
+| ---------- | ------------------------------------------ | -------------------- |
+| **High**   | LSP confirmed + tests exist + docs match   | Proceed confidently  |
+| **Medium** | LSP confirmed but untested or undocumented | Proceed with caution |
+| **Low**    | Inference only, no LSP/test confirmation   | Verify before using  |
+| **None**   | Speculation without evidence               | Discard              |
+
+## Stop Conditions
+
+Stop research when ANY of these are true:
+
+- All questions answered with Medium+ confidence
+- Tool budget exhausted (~100 calls for thorough)
+- Last 5 tool calls yielded no new insights
+- Blocked and need human input
+
+## Tool Budget Guidelines
+
+| Mode     | Tool Calls | Use Case                           |
+| -------- | ---------- | ---------------------------------- |
+| Quick    | ~10        | Single question, syntax lookup     |
+| Default  | ~30        | Moderate exploration               |
+| Thorough | ~100+      | Comprehensive analysis, new domain |
+
+Track your tool count and stop at budget.
+
+## Output Template
+
+Document findings in structured format:
+
+```markdown
+# Deep Research: [Topic]
+
+**Mode:** thorough
+**Tool calls:** [N]
+**Duration:** [time]
+
+## Questions Addressed
+
+1. [Q1] → Answered (High confidence)
+2. [Q2] → Partial (Medium confidence)
+3. [Q3] → Unanswered (needs: [what would resolve])
+
+## LSP Findings
+
+### Symbol: [name]
+
+**Location:** `src/path/file.ts:42`
+**Type:** [type signature from hover]
+
+**Callers (incoming):**
+
+- `src/a.ts:10` - [context]
+- `src/b.ts:25` - [context]
+
+**Dependencies (outgoing):**
+
+- `src/utils.ts:15` - [what it calls]
+
+**References:** [N] usages across [M] files
+
+---
+
+## Pattern Analysis
+
+### Pattern 1: [Name]
+
+**Files:** `src/a.ts`, `src/b.ts`
+**Confidence:** High
+**Evidence:** [LSP + grep findings]
+
+[Description of pattern]
+
+---
+
+## Key Findings
+
+### [Finding 1]
+
+**Confidence:** High
+**Sources:** LSP goToDefinition, findReferences
+**Evidence:** `src/file.ts:42-56`
+
+[Finding with code evidence]
+
+---
+
+## Recommendations
+
+Based on LSP analysis:
+
+1. [Recommendation 1] - because [LSP evidence]
+2. [Recommendation 2] - because [pattern found]
+
+## Open Items
+
+- [Remaining question] - needs: [specific tool/info]
+```
+
+## Integration Points
+
+### Scout Agent Deep Mode
+
+When scout enters deep mode, load this skill:
+
+```typescript
+skill({ name: "deep-research" });
+```
+
+Scout then follows the protocol for external + internal analysis.
+
+### Research Command --thorough
+
+When `/research <topic> --thorough` is invoked:
+
+```typescript
+skill({ name: "deep-research" });
+// Follow full protocol with ~100 tool budget
+```
+
+### Pre-Edit Verification
+
+Before any complex edit:
+
+```typescript
+skill({ name: "deep-research" });
+// Run Phase 2 (LSP) on all symbols being modified
+// Proceed only when all 9 operations complete
+```
+
+## Workflow Example
+
+**Scenario:** Understanding authentication middleware before adding rate limiting.
+
+```typescript
+// Phase 1: Memory check
+memory_search({ query: "authentication middleware rate limiting" });
+memory_read({ file: "project/architecture" });
+
+// Phase 2: Delegate LSP exploration to explore agent
+task({
+  subagent_type: "explore",
+  description: "Analyze auth middleware",
+  prompt: `Very thorough LSP analysis of authentication middleware.
+
+Target: src/middleware/auth.ts
+
+Questions:
+1. What functions are exported from auth.ts?
+2. What calls the auth middleware? (incoming calls)
+3. What does it depend on? (outgoing calls)
+4. Are there existing rate limiting patterns?
+
+Return file:line references for all findings.`,
+});
+
+// Phase 3: Pattern discovery (parallel with Phase 2)
+grep({ pattern: "middleware", include: "*.<ext>" });
+grep({ pattern: "rateLimit", include: "*.<ext>" });
+glob({ pattern: "src/middleware/*" });
+
+// Phase 4: External (if patterns unclear)
+context7({ operation: "resolve", libraryName: "express" });
+context7({ operation: "query", libraryId: "/expressjs/express", topic: "middleware" });
+
+// Document findings
+write({
+  filePath: ".beads/artifacts/<id>/research.md",
+  content: "# Deep Research: Auth Middleware...",
+});
+```
+
+## Anti-Patterns
+
+### DON'T: Skip LSP Exploration
+
+```typescript
+// Bad: Reading file without LSP analysis
+read({ filePath: "src/auth.ts" });
+// Then immediately editing...
+
+// Good: Delegate to explore agent first
+task({
+  subagent_type: "explore",
+  description: "Analyze auth.ts",
+  prompt: "Very thorough LSP analysis of src/auth.ts...",
+});
+// Then edit with understanding
+```
+
+### DON'T: Ignore Memory
+
+```typescript
+// Bad: Jumping straight to exploration
+grep({ pattern: "auth", include: "*.ts" });
+
+// Good: Check memory first
+memory_search({ query: "authentication patterns" });
+// Only explore if memory doesn't answer
+```
+
+### DON'T: Mix Confidence Levels
+
+```typescript
+// Bad: Treating speculation as fact
+"This function definitely handles X"; // Without LSP verification
+
+// Good: Explicit confidence
+"Based on LSP findReferences (High confidence): This function is called from...";
+"Inference (Low confidence): This might also handle X, needs verification";
+```
+
+### DON'T: Exceed Budget Without Stopping
+
+```typescript
+// Bad: 150 tool calls on thorough mode
+// Keep going indefinitely...
+
+// Good: Track and stop
+// Tool call 95: Still finding new insights, continue
+// Tool call 100: Stopping at budget, documenting partial findings
+```
+
+## Success Criteria
+
+Research is complete when:
+
+- [ ] Memory checked before exploration
+- [ ] All 9 LSP operations run on target symbols
+- [ ] Confidence scores assigned to all findings
+- [ ] Tool budget respected
+- [ ] Findings documented with evidence
+- [ ] Open items listed with resolution paths
+
+## Quick Reference
+
+```
+PROTOCOL:
+1. Memory first → skip if found
+2. Delegate LSP to @explore (very thorough)
+3. Patterns → grep + glob (parallel)
+4. External → only if needed
+
+DELEGATION:
+task({ subagent_type: "explore", prompt: "Very thorough LSP analysis..." })
+
+CONFIDENCE:
+High = LSP + tests + docs
+Medium = LSP only
+Low = inference
+None = discard
+
+BUDGET:
+quick ~10 | default ~30 | thorough ~100
+
+STOP WHEN:
+- Questions answered (Medium+)
+- Budget exhausted
+- 5 calls with no new insights
+- Blocked on human input
+```