codexkit 1.0.0

package/.codex/skills/prompt-leverage/scripts/augment_prompt.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import re
+from textwrap import dedent
+
+
+TASK_KEYWORDS = {
+    "coding": ["code", "bug", "repo", "refactor", "test", "implement", "fix", "function", "api"],
+    "research": ["research", "compare", "find", "latest", "sources", "analyze market", "look up"],
+    "writing": ["write", "rewrite", "draft", "email", "memo", "blog", "copy", "tone"],
+    "review": ["review", "audit", "critique", "inspect", "evaluate", "assess"],
+    "planning": ["plan", "roadmap", "strategy", "framework", "outline"],
+    "analysis": ["analyze", "explain", "break down", "diagnose", "root cause"],
+}
+
+
+def detect_task(prompt: str) -> str:
+    lowered = prompt.lower()
+    scores = {
+        task: sum(1 for keyword in keywords if keyword in lowered)
+        for task, keywords in TASK_KEYWORDS.items()
+    }
+    best_task, best_score = max(scores.items(), key=lambda item: item[1])
+    return best_task if best_score > 0 else "analysis"
+
+
+def infer_intensity(prompt: str, task: str) -> str:
+    lowered = prompt.lower()
+    if any(token in lowered for token in ["careful", "deep", "thorough", "high stakes", "production", "critical"]):
+        return "Deep"
+    if task in {"coding", "research", "review"}:
+        return "Standard"
+    return "Light"
+
+
+def build_tool_rules(task: str) -> str:
+    if task == "coding":
+        return "Inspect the relevant files and dependencies first. Validate the final change with the narrowest useful checks before broadening scope."
+    if task == "research":
+        return "Retrieve evidence from reliable sources before concluding. Do not guess facts that can be checked."
+    if task == "review":
+        return "Read enough surrounding context to understand intent before critiquing. Distinguish confirmed issues from plausible risks."
+    return "Use tools or extra context only when they materially improve correctness or completeness."
+
+
+def build_output_contract(task: str) -> str:
+    if task == "coding":
+        return "Return the result in a practical execution format: concise summary, concrete changes or code, validation notes, and any remaining risks."
+    if task == "research":
+        return "Return a structured synthesis with key findings, supporting evidence, uncertainty where relevant, and a concise bottom line."
+    if task == "writing":
+        return "Return polished final copy in the requested tone and format. If useful, include a short rationale for major editorial choices."
+    if task == "review":
+        return "Return findings grouped by severity or importance, explain why each matters, and suggest the smallest credible next step."
+    return "Return a clear, well-structured response matched to the task, with no unnecessary verbosity."
+
+
+def upgrade_prompt(raw_prompt: str, task: str | None) -> str:
+    normalized = re.sub(r"\s+", " ", raw_prompt).strip()
+    detected_task = task or detect_task(normalized)
+    intensity = infer_intensity(normalized, detected_task)
+    tool_rules = build_tool_rules(detected_task)
+    output_contract = build_output_contract(detected_task)
+
+    return dedent(
+        f"""
+        Objective:
+        - Complete this task: {normalized}
+        - Optimize for a correct, useful result rather than a merely plausible one.
+
+        Context:
+        - Preserve the user's original intent and constraints.
+        - Surface any key assumptions if required information is missing.
+
+        Work Style:
+        - Task type: {detected_task}
+        - Effort level: {intensity}
+        - Understand the problem broadly enough to avoid narrow mistakes, then go deep where the risk or complexity is highest.
+        - Use first-principles reasoning before proposing changes.
+        - For non-trivial work, review the result once with fresh eyes before finalizing.
+
+        Tool Rules:
+        - {tool_rules}
+
+        Output Contract:
+        - {output_contract}
+
+        Verification:
+        - Check correctness, completeness, and edge cases.
+        - Improve obvious weaknesses if a better approach is available within scope.
+
+        Done Criteria:
+        - Stop only when the response satisfies the task, matches the requested format, and passes the verification step.
+        """
+    ).strip()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Upgrade a raw prompt into a framework-backed execution prompt.")
+    parser.add_argument("prompt", help="Raw prompt text to upgrade.")
+    parser.add_argument("--task", choices=sorted(TASK_KEYWORDS.keys()), help="Optional explicit task type.")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    print(upgrade_prompt(args.prompt, args.task))
+
+
+if __name__ == "__main__":
+    main()

package/.codex/skills/ralph/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: ralph
+description: Use when running autonomous agent loops for extended task completion without human intervention - handles PRD-driven development, migration tasks, or batch operations
+version: 1.0.0
+tags: [workflow, automation]
+dependencies: []
+---
+
+# Ralph Wiggum - Autonomous Agent Loop
+
+## When to Use
+
+- **PRD-driven development**: Work through a product requirements document task by task
+- **Migration tasks**: "Migrate all Jest tests to Vitest" - agent works until done
+- **Batch operations**: Process multiple files/components with the same pattern
+- **Away-from-keyboard work**: Let the agent work autonomously while you're away
+
+## When NOT to Use
+
+- Simple single-step tasks (just do them directly)
+- Tasks requiring frequent human decisions
+- Exploratory work where the goal isn't clear
+- Critical production changes (requires human oversight)
+
+
+## Quick Start
+
+Invoke the workflow with:
+
+```
+/ralph Migrate all Jest tests to Vitest --prd PRD.md
+```
+
+Or manually follow the loop pattern below.
+
+## The Loop Pattern
+
+```
+┌─────────────────────────────────────────────────┐
+│  1. Read PRD/task list + progress.txt           │
+│  2. Pick highest-priority incomplete task       │
+│  3. Implement ONE feature only                  │
+│  4. Run feedback: test → typecheck → lint       │
+│  5. If pass → commit + update progress.txt      │
+│  6. If all done → output <promise>COMPLETE      │
+│  7. Otherwise → repeat from step 1              │
+└─────────────────────────────────────────────────┘
+```
+
+## Using LSP Tools (Experimental)
+
+Codex provides LSP-style code intelligence tools for code navigation and impact analysis.
+
+### Available Operations
+
+```typescript
+// Understand file structure before editing
+lsp({
+  operation: "documentSymbol",
+  filePath: "src/auth.ts",
+  line: 1,
+  character: 1,
+});
+
+// Find where a symbol is defined
+lsp({
+  operation: "goToDefinition",
+  filePath: "src/auth.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all usages of a symbol (impact analysis)
+lsp({
+  operation: "findReferences",
+  filePath: "src/auth.ts",
+  line: 42,
+  character: 10,
+});
+
+// Get type info and documentation
+lsp({ operation: "hover", filePath: "src/auth.ts", line: 42, character: 10 });
+
+// Find implementations of interface/abstract
+lsp({
+  operation: "goToImplementation",
+  filePath: "src/types.ts",
+  line: 15,
+  character: 10,
+});
+
+// Search symbols across entire workspace
+lsp({
+  operation: "workspaceSymbol",
+  filePath: "src/index.ts",
+  line: 1,
+  character: 1,
+});
+
+// Call hierarchy analysis
+lsp({
+  operation: "prepareCallHierarchy",
+  filePath: "src/api.ts",
+  line: 20,
+  character: 5,
+});
+lsp({
+  operation: "incomingCalls",
+  filePath: "src/api.ts",
+  line: 20,
+  character: 5,
+});
+lsp({
+  operation: "outgoingCalls",
+  filePath: "src/api.ts",
+  line: 20,
+  character: 5,
+});
+```
+
+### LSP-First Workflow
+
+Before editing ANY file in the loop:
+
+```
+1. Read the file
+2. Use documentSymbol to understand structure
+3. Use findReferences to check impact
+4. Use hover for type info
+5. THEN make edits
+```
+
+This prevents breaking changes and ensures you understand the code before modifying it.
+
+## Smart Language Detection
+
+Codex auto-detects languages via LSP/file semantics based on file extensions. Use this to determine the project type:
+
+### Primary Detection (File Extensions)
+
+| Language   | Extensions                    | LSP Server    |
+| ---------- | ----------------------------- | ------------- |
+| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | typescript    |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | typescript    |
+| Python     | `.py`, `.pyi`                 | pyright       |
+| Rust       | `.rs`                         | rust-analyzer |
+| Go         | `.go`                         | gopls         |
+| C/C++      | `.c`, `.cpp`, `.h`, `.hpp`    | clangd        |
+| Java       | `.java`                       | jdtls         |
+| C#         | `.cs`                         | csharp        |
+| Ruby       | `.rb`, `.rake`                | ruby-lsp      |
+| PHP        | `.php`                        | intelephense  |
+| Swift      | `.swift`                      | sourcekit-lsp |
+| Kotlin     | `.kt`, `.kts`                 | kotlin-ls     |
+| Elixir     | `.ex`, `.exs`                 | elixir-ls     |
+| Dart       | `.dart`                       | dart          |
+| Zig        | `.zig`                        | zls           |
+| Gleam      | `.gleam`                      | gleam         |
+| Lua        | `.lua`                        | lua-ls        |
+| Clojure    | `.clj`, `.cljs`, `.cljc`      | clojure-lsp   |
+| OCaml      | `.ml`, `.mli`                 | ocaml-lsp     |
+| Svelte     | `.svelte`                     | svelte        |
+| Vue        | `.vue`                        | vue           |
+| Astro      | `.astro`                      | astro         |
+
+### Secondary Detection (Lock Files → Package Manager)
+
+| Lock File           | Package Manager | Runtime |
+| ------------------- | --------------- | ------- |
+| `bun.lockb`         | Bun             | Bun     |
+| `yarn.lock`         | Yarn            | Node    |
+| `pnpm-lock.yaml`    | pnpm            | Node    |
+| `package-lock.json` | npm             | Node    |
+| `deno.json`         | Deno            | Deno    |
+| `Cargo.toml`        | Cargo           | Rust    |
+| `go.mod`            | Go Modules      | Go      |
+| `pyproject.toml`    | Poetry/pip      | Python  |
+| `Gemfile.lock`      | Bundler         | Ruby    |
+| `composer.lock`     | Composer        | PHP     |
+| `Package.swift`     | SwiftPM         | Swift   |
+| `mix.lock`          | Mix             | Elixir  |
+| `pubspec.lock`      | Pub             | Dart    |
+
+### Validation Commands by Language
+
+```bash
+# TypeScript/JavaScript (Bun)
+bun test && bun run typecheck && bun run lint
+
+# TypeScript/JavaScript (npm)
+npm test && npm run typecheck && npm run lint
+
+# TypeScript/JavaScript (Deno)
+deno test && deno check . && deno lint
+
+# Python
+pytest && ruff check . && mypy .
+
+# Rust
+cargo test && cargo check && cargo clippy --all-targets
+
+# Go
+go test ./... && go vet ./... && golangci-lint run
+
+# Ruby
+bundle exec rspec && bundle exec rubocop
+
+# PHP
+composer test && composer phpstan && composer phpcs
+
+# Swift
+swift test && swift build
+
+# Elixir
+mix test && mix credo && mix dialyzer
+
+# Dart
+dart test && dart analyze
+
+# Java (Maven)
+mvn test && mvn compile && mvn checkstyle:check
+
+# Java (Gradle)
+./gradlew test && ./gradlew check
+
+# C# (.NET)
+dotnet test && dotnet build && dotnet format --verify-no-changes
+```
+
+## Required Files
+
+### PRD File (Recommended)
+
+Create a `PRD.md` with clear task list:
+
+```markdown
+# Migration PRD
+
+## Tasks
+
+- [ ] Convert test-utils.test.js
+- [ ] Convert api.test.js
+- [ ] Update CI config
+- [ ] Remove Jest dependencies
+```
+
+### Progress File (Agent-maintained)
+
+Agent creates/updates `progress.txt`:
+
+```markdown
+# Progress Log
+
+## Session Started: 2026-01-10
+
+### Project: TypeScript with Bun
+
+### Commands: bun test | bun run typecheck | bun run lint
+
+### Completed Tasks
+
+- [x] test-utils.test.js - migrated, 12 tests passing
+- [x] api.test.js - migrated, 8 tests passing
+
+### Notes for Next Iteration
+
+- CI config needs Vitest runner update
+```
+
+## Completion Signal
+
+The loop ends when agent outputs:
+
+```
+<promise>COMPLETE</promise>
+```
+
+## Best Practices
+
+1. **Use LSP for detection**: Check file extensions, not just lock files
+2. **Small steps**: ONE feature per iteration (prevents context rot)
+3. **Quality gates**: Test, typecheck, lint MUST pass before commit
+4. **Prioritize risk**: Hard tasks first, easy wins last
+5. **Track progress**: Update progress.txt every iteration
+6. **Explicit scope**: Vague tasks loop forever
+7. **Graceful fallbacks**: If a command doesn't exist, skip and note it
+
+## Troubleshooting
+
+| Issue                | Solution                                    |
+| -------------------- | ------------------------------------------- |
+| Loop not progressing | Break task into smaller pieces              |
+| Tests failing        | Fix before continuing, don't skip           |
+| Context getting long | Summarize progress, restart session         |
+| Stuck on decision    | Note in progress.txt, ask user next session |
+| Unknown language     | Check file extensions against LSP table     |