codexkit 1.0.0

package/.codex/skills/prd/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: prd
+description: Create Product Requirements Documents (PRDs) that define the end state of a feature. Use when planning new features, migrations, or refactors. Generates structured PRDs with acceptance criteria.
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
+---
+
+# PRD Creation Skill
+
+## When to Use
+
+- After a design is validated and you need formal requirements and acceptance criteria
+- Before breaking work into tasks or plans for features, migrations, or refactors
+
+## When NOT to Use
+
+- When you already have an approved PRD and only need task conversion
+- For small, mechanical changes where a PRD would be overhead
+
+
+
+
+
+## Beads-Native Output (Recommended)
+
+When you are working on a Beads task (you have a bead id like `br-...`), the PRD should live with the task artifacts:
+
+- Write PRD to: `.beads/artifacts/<bead-id>/prd.md`
+
+This keeps requirements + execution tasks colocated with the bead.
+
+If no bead id exists, create one first: `br create "Feature Name"`, then use the artifact path.
+
+## Workflow
+
+1. Confirm if the user has an existing bead id.
+   - If yes: use `.beads/artifacts/<bead-id>/prd.md`
+   - If no: create bead with `br create "Feature Name"`, then use artifact path
+2. Read template from `.codex/context/prd.md`
+3. Ask clarifying questions (5–7 max).
+4. Explore codebase patterns and constraints.
+5. Write a PRD following the template structure, including:
+   - Bead Metadata (dependencies, parallel, conflicts)
+   - Requirements with WHEN/THEN scenarios
+   - Machine-convertible `## Tasks` section
+
+## Clarifying Questions
+
+### Problem & Motivation
+
+- What problem does this solve? Who experiences it?
+- What's the cost of NOT solving this? (user pain, revenue, tech debt)
+- Why now? What triggered this work?
+
+### Users & Stakeholders
+
+- Who are the primary users? Secondary users?
+
+### End State & Success
+
+- What does "done" look like? How will users interact with it?
+
+### Scope & Boundaries
+
+- What's explicitly OUT of scope?
+- What's deferred to future iterations?
+- Are there adjacent features that must NOT be affected?
+
+### Constraints & Requirements
+
+- Performance requirements?
+- Security requirements? (auth, data sensitivity, compliance)
+- Compatibility requirements? (browsers, versions, APIs)
+- Accessibility requirements? (WCAG level, screen readers)
+
+### Risks & Dependencies
+
+- What could go wrong? Technical risks?
+- External service dependencies?
+- What decisions are still open/contentious?
+
+## Output Format
+
+**Read the template:** `.codex/context/prd.md`
+
+Follow the template structure which includes:
+
+- Bead Metadata (dependencies, parallel execution, conflicts)
+- Problem Statement with WHEN/THEN scenarios
+- Scope (In/Out)
+- Requirements (Functional + Non-Functional)
+- Success Criteria with verification commands
+- Technical Context and Affected Files
+- Tasks section with Metadata (depends_on, parallel, files)
+
+### Task Format (Critical)
+
+Tasks must include **Metadata** for dependency tracking:
+
+````markdown
+### <Task Title> [category]
+
+<One sentence describing the end state>
+
+**Metadata:**
+
+```yaml
+depends_on: []
+parallel: true
+conflicts_with: []
+files: []
+```
+````
+
+**Verification:**
+
+- [Command or check]
+
+```
+
+## Next Steps
+
+After PRD is written, tell the user:
+
+```
+
+PRD written: .beads/artifacts/<bead-id>/prd.md
+
+Next: Convert to executable tasks:
+skill({ name: "prd-task" })
+
+Or view the full lifecycle:
+skill({ name: "development-lifecycle" })
+
+```
+
+## Key Principles
+
+- Problem Before Solution
+- Define End State, Not Process
+- Technical Context Enables Autonomy
+- Non-Goals Prevent Scope Creep
+- Risks & Alternatives Show Rigor
+- Include Metadata for parallel execution
+```

package/.codex/skills/prd-task/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: prd-task
+description: Convert a Beads PRD markdown file to executable JSON tasks for autonomous execution. Use after writing `.beads/artifacts/<bead-id>/prd.md`.
+references:
+  - references/prd-schema.json
+version: 1.0.0
+tags: [planning, workflow]
+dependencies: [prd]
+---
+
+# PRD Task Skill (Beads-Native)
+
+## When to Use
+
+- After a PRD is complete at `.beads/artifacts/<bead-id>/prd.md` and you need executable tasks
+- When you need to generate `prd.json` and initialize `progress.txt` for a bead
+
+## When NOT to Use
+
+- Before a PRD exists or when requirements are still being gathered
+- If you only need a human-readable plan (use writing-plans instead)
+
+
+
+
+## Beads-Native File Locations (Recommended)
+
+This template uses Beads artifacts (no `.codex/state`).
+
+```
+.beads/artifacts/<bead-id>/
+├── prd.md         # PRD created by `prd` skill
+├── prd.json       # Generated task list with passes field
+└── progress.txt   # Cross-iteration memory (append-only)
+```
+
+## Workflow
+
+1. Input: bead id (`br-...`).
+2. Read `.beads/artifacts/<bead-id>/prd.md`.
+3. Extract tasks from `## Tasks`.
+4. Write `.beads/artifacts/<bead-id>/prd.json`.
+5. Ensure `.beads/artifacts/<bead-id>/progress.txt` exists (create if missing).
+
+## Input Format
+
+`prd-task` expects a `## Tasks` section with tasks of the form:
+
+```markdown
+## Tasks
+
+### User Registration [functional]
+
+User can register with email and password.
+
+**Verification:**
+
+- POST /api/auth/register with valid email/password
+- Verify 201 response with user object
+- Attempt duplicate email, verify 409
+```
+
+## Output Format
+
+Write JSON to `.beads/artifacts/<bead-id>/prd.json`.
+
+```json
+{
+  "beadId": "br-...",
+  "prdName": "<optional-slug>",
+  "tasks": [
+    {
+      "id": "functional-1",
+      "category": "functional",
+      "description": "User can register with email and password",
+      "steps": [
+        "POST /api/auth/register with valid email/password",
+        "Verify 201 response with user object",
+        "Attempt duplicate email, verify 409"
+      ],
+      "passes": false,
+      "metadata": {
+        "depends_on": [],
+        "parallel": true,
+        "conflicts_with": [],
+        "files": ["src/routes/auth.ts", "src/db/users.ts"]
+      }
+    }
+  ],
+  "context": {
+    "patterns": ["API routes: src/routes/"],
+    "keyFiles": ["src/db/schema.ts"],
+    "nonGoals": ["OAuth/social login"]
+  },
+  "beadMetadata": {
+    "depends_on": [],
+    "parallel": true,
+    "conflicts_with": [],
+    "blocks": [],
+    "estimated_hours": 4
+  }
+}
+```
+
+## Task Schema
+
+See `references/prd-schema.json`.
+
+## Conversion Rules
+
+### Tasks from Markdown
+
+- Each `### Title [category]` becomes a task
+- Generate `id` as `<category>-<number>` (e.g., `api-1`, `db-2`) or a descriptive slug
+- Text after title becomes `description`
+- Items under `**Verification:**` become `steps`
+- `passes` always starts `false`
+- Extract `**Metadata:**` yaml block for dependency info:
+  - `depends_on`: Task titles or IDs that must complete first
+  - `parallel`: Can run concurrently (default: true)
+  - `conflicts_with`: Tasks modifying same files
+  - `files`: Files this task will modify
+
+### Bead Metadata
+
+Extract the `## Bead Metadata` yaml block from the PRD header:
+
+```yaml
+depends_on: [] # Bead IDs
+parallel: true
+conflicts_with: [] # Bead IDs
+blocks: []
+estimated_hours: 2
+```
+
+Store in `beadMetadata` field in the JSON output.
+
+### Steps Are Verification
+
+Steps must be written as **verification steps**, not implementation instructions.
+
+Bad: "Add a controller and write a service"
+Good: "POST /api/foo returns 201" / "bun test passes"
+
+## Progress File
+
+If `.beads/artifacts/<bead-id>/progress.txt` does not exist, create it with:
+
+```markdown
+# Progress Log
+
+Bead: <bead-id>
+Started: <YYYY-MM-DD>
+
+## Codebase Patterns
+
+<!-- Consolidate reusable patterns here -->
+
+---
+
+<!-- Task logs below - APPEND ONLY -->
+```
+
+## After Conversion
+
+Tell the user:
+
+```
+PRD converted:
+  - .beads/artifacts/<bead-id>/prd.md
+  - .beads/artifacts/<bead-id>/prd.json
+  - .beads/artifacts/<bead-id>/progress.txt
+
+Next: Create detailed implementation plan
+  skill({ name: "writing-plans" })
+
+Or start execution directly:
+  /start <bead-id>
+
+Full lifecycle reference:
+  skill({ name: "development-lifecycle" })
+```

package/.codex/skills/prd-task/references/prd-schema.json

@@ -0,0 +1,124 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "PRD Task Schema",
+	"description": "Executable task list converted from PRD markdown",
+	"type": "object",
+	"required": ["beadId", "tasks"],
+	"properties": {
+		"beadId": {
+			"type": "string",
+			"description": "Bead identifier (e.g., br-abc123)"
+		},
+		"prdName": {
+			"type": "string",
+			"description": "Optional slug for the PRD"
+		},
+		"tasks": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["id", "category", "description", "steps", "passes"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"description": "Task identifier (e.g., functional-1, api-2)"
+					},
+					"category": {
+						"type": "string",
+						"description": "Task category (e.g., functional, api, db, ui)"
+					},
+					"description": {
+						"type": "string",
+						"description": "One sentence describing the end state"
+					},
+					"steps": {
+						"type": "array",
+						"items": { "type": "string" },
+						"description": "Verification steps that prove the task is complete"
+					},
+					"passes": {
+						"type": "boolean",
+						"default": false,
+						"description": "Whether all verification steps pass"
+					},
+					"metadata": {
+						"type": "object",
+						"description": "Task dependency and execution metadata",
+						"properties": {
+							"depends_on": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Task IDs that must complete first"
+							},
+							"parallel": {
+								"type": "boolean",
+								"default": true,
+								"description": "Can run concurrently with other parallel tasks"
+							},
+							"conflicts_with": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Task IDs that modify same files (cannot parallelize)"
+							},
+							"files": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Files this task will modify"
+							}
+						}
+					}
+				}
+			}
+		},
+		"context": {
+			"type": "object",
+			"description": "Technical context from the PRD",
+			"properties": {
+				"patterns": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Existing codebase patterns to follow"
+				},
+				"keyFiles": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Key files to reference"
+				},
+				"nonGoals": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Explicitly out of scope items"
+				}
+			}
+		},
+		"beadMetadata": {
+			"type": "object",
+			"description": "Bead-level metadata from PRD",
+			"properties": {
+				"depends_on": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Bead IDs that must complete before this one"
+				},
+				"parallel": {
+					"type": "boolean",
+					"description": "Can run concurrently with other parallel beads"
+				},
+				"conflicts_with": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Bead IDs that modify same files"
+				},
+				"blocks": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Bead IDs waiting on this one"
+				},
+				"estimated_hours": {
+					"type": "number",
+					"description": "Time estimate for planning"
+				}
+			}
+		}
+	}
+}

package/.codex/skills/prompt-leverage/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: prompt-leverage
+description: Strengthen a raw user prompt into an execution-ready instruction set for Amp, Claude Code, or another AI agent. Use when the user wants to improve an existing prompt, build a reusable prompting framework, wrap the current request with better structure, add clearer tool rules, or create a hook that upgrades prompts before execution.
+---
+
+# Prompt Leverage
+
+Turn the user's current prompt into a stronger working prompt without changing the underlying intent. Preserve the task, fill in missing execution structure, and add only enough scaffolding to improve reliability.
+
+## Workflow
+
+1. Read the raw prompt and identify the real job to be done.
+2. Infer the task type: coding, research, writing, analysis, planning, or review.
+3. Rebuild the prompt with the framework blocks in `references/framework.md`.
+4. Keep the result proportional: do not over-specify a simple task.
+5. Return both the improved prompt and a short explanation of what changed when useful.
+
+## Transformation Rules
+
+- Preserve the user's objective, constraints, and tone unless they conflict.
+- Prefer adding missing structure over rewriting everything stylistically.
+- Add context requirements only when they improve correctness.
+- Add tool rules only when tool use materially affects correctness.
+- Add verification and completion criteria for non-trivial tasks.
+- Keep prompts compact enough to be practical in repeated use.
+
+## Framework Blocks
+
+Use these blocks selectively.
+
+- `Objective`: state the task and what success looks like.
+- `Context`: list sources, files, constraints, and unknowns.
+- `Work Style`: set depth, breadth, care, and first-principles expectations.
+- `Tool Rules`: state when tools, browsing, or file inspection are required.
+- `Output Contract`: define structure, formatting, and level of detail.
+- `Verification`: require checks for correctness, edge cases, and better alternatives.
+- `Done Criteria`: define when the agent should stop.
+
+## Output Modes
+
+Choose one mode based on the user request.
+
+- `Inline upgrade`: provide the upgraded prompt only.
+- `Upgrade + rationale`: provide the prompt plus a brief list of improvements.
+- `Template extraction`: convert the prompt into a reusable fill-in-the-blank template.
+- `Hook spec`: explain how to apply the framework automatically before execution.
+
+## Hook Pattern
+
+When the user asks for a hook, model it as a pre-processing layer:
+
+1. Accept the current prompt.
+2. Classify the task and risk level.
+3. Expand the prompt using the framework blocks.
+4. Return the upgraded prompt for execution.
+5. Optionally keep a diff or summary of injected structure.
+
+Use `scripts/augment_prompt.py` when a deterministic first-pass rewrite is helpful.
+
+## Quality Bar
+
+Before finalizing, check the upgraded prompt:
+
+- still matches the original intent
+- does not add unnecessary ceremony
+- includes the right verification level for the task
+- gives the agent a clear definition of done
+
+If the prompt is already strong, say so and make only minimal edits.

package/.codex/skills/prompt-leverage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Prompt Leverage"
+  short_description: "Upgrade raw prompts for execution"
+  default_prompt: "Take the current prompt and upgrade it into a stronger execution-ready prompt with clear objective, context, work style, tool rules, output contract, verification, and done criteria."

package/.codex/skills/prompt-leverage/references/framework.md

@@ -0,0 +1,91 @@
+# Prompt Leverage Framework
+
+Use this reference to combine the two source ideas into one practical execution framework.
+
+## Source Synthesis
+
+- Agent Flywheel contributes behavior controls: intensity, wider search, deeper analysis, fresh eyes, first-principles thinking, and future-self clarity.
+- OpenAI prompt guidance contributes execution controls: clear objectives, explicit output contracts, tool persistence, dependency checks, verification loops, and completion criteria.
+
+Treat the final framework as:
+
+`Goal -> Context -> Work Style -> Tool Rules -> Output Contract -> Verification -> Done`
+
+## Block Definitions
+
+### Objective
+
+State the task in one or two lines. Define success in observable terms.
+
+### Context
+
+Specify relevant files, URLs, constraints, assumptions, and information boundaries. Say when the agent must retrieve facts instead of guessing.
+
+### Work Style
+
+Control how the agent approaches the task.
+
+- Go broad first when system understanding matters.
+- Go deep where risk or complexity is highest.
+- Use first-principles reasoning before changing things.
+- Re-check with fresh eyes for non-trivial tasks.
+
+### Tool Rules
+
+Define when browsing, file inspection, tests, or external tools are required. Prevent skipping prerequisite checks.
+
+### Output Contract
+
+Define exact structure, tone, formatting, depth, and any required sections or schemas.
+
+### Verification
+
+Require checks for correctness, grounding, completeness, side effects, and better alternatives.
+
+### Done Criteria
+
+Define what must be true before the agent stops.
+
+## Intensity Levels
+
+Use the minimum level that matches the task.
+
+- `Light`: simple edits, formatting, quick rewrites.
+- `Standard`: typical coding, research, and drafting tasks.
+- `Deep`: debugging, architecture, complex research, or high-stakes outputs.
+
+## Task-Type Adjustments
+
+### Coding
+
+- Emphasize repo context, file inspection, smallest correct change, validation, and edge cases.
+
+### Research
+
+- Emphasize source quality, evidence gathering, synthesis, uncertainty, and citations.
+
+### Writing
+
+- Emphasize audience, tone, structure, constraints, and revision criteria.
+
+### Review
+
+- Emphasize fresh-eyes critique, failure modes, alternatives, and explicit severity.
+
+## Prompt Upgrade Heuristics
+
+- Add missing blocks only when they materially improve execution.
+- Do not turn a one-line request into a giant spec unless the task is genuinely complex.
+- Preserve user language where possible so the upgraded prompt still feels native.
+- Prefer concrete completion criteria over vague quality adjectives.
+
+## Upgrade Rubric
+
+An upgraded prompt is good when it:
+
+1. preserves original intent
+2. reduces ambiguity
+3. sets the right depth and care level
+4. defines the expected output clearly
+5. includes an appropriate verification step
+6. tells the agent when to stop