codexkit 1.0.0

package/.codex/skills/safe-implementation/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: safe-implementation
+description: TDD-first implementation procedure with deviation handling and validation gates.
+---
+
+# safe-implementation
+
+## Purpose
+Implement code changes safely using tests, minimal diffs, and explicit deviation rules.
+
+## Use This Skill When
+- Adding a feature
+- Fixing a bug
+- Updating production behavior
+- Changing business logic
+
+## Workflow Phases
+1. RED
+2. GREEN
+3. REFACTOR
+4. VERIFY
+
+## Expected Outputs
+- Passing tests
+- Minimal production diff
+- Documented deviations
+- Verification evidence
+
+## Success Indicators
+- Test fails before implementation
+- Minimal code to pass
+- No behavior drift after refactor
+- All relevant gates pass
+
+## Fast Start
+Run these commands to establish immediate context:
+
+```bash
+npm test -- <target>
+npm run typecheck
+npm run lint
+git diff --stat
+```
+
+## Deviation Rules
+
+| Rule | Trigger | Action |
+|---|---|---|
+| 1 | Bug discovered during task | Fix inline, add test, continue |
+| 2 | Missing critical validation/auth/error handling | Add minimal guardrail, continue |
+| 3 | Blocking type/import/dependency issue | Apply smallest unblock change |
+| 4 | Architecture-level change required | Stop, present options, request decision |
+
+## Commit Protocol by Phase
+- RED: `test: add failing test for <behavior>`
+- GREEN: `feat: implement <behavior>` or `fix: implement <behavior>`
+- REFACTOR: `refactor: simplify <area>`
+
+## RED Checklist
+- Can the behavior be expressed as an assertion?
+- Does the new test fail for the right reason?
+- Is failure output captured in notes?
+
+## GREEN Checklist
+- Smallest change that satisfies the test.
+- No speculative optimization.
+- Re-run target tests after each edit.
+
+## Process Table
+
+| Step | Action | Artifact |
+|---|---|---|
+| 1 | Execute red activities | Notes + evidence for red |
+| 2 | Execute green activities | Notes + evidence for green |
+| 3 | Execute refactor activities | Notes + evidence for refactor |
+| 4 | Execute verify activities | Notes + evidence for verify |
+
+## 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/session-management/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: session-management
+description: "Merged into context-management. Load that skill instead."
+---
+
+# Session Management
+
+> This skill has been merged into `context-management` which now covers both context and session lifecycle management.
+> 
+> Load `context-management` instead.

package/.codex/skills/sharing-skills/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: sharing-skills
+description: Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository
+version: 1.0.0
+tags: [workflow, git]
+dependencies: []
+---
+
+# Sharing Skills
+
+## When to Use
+
+- When a skill is broadly useful and ready to be contributed upstream via pull request.
+
+## When NOT to Use
+
+- When the skill is project-specific, experimental, or contains sensitive information.
+
+## Overview
+
+Contribute skills from your local branch back to the upstream repository.
+
+**Workflow:** Branch → Edit/Create skill → Commit → Push → PR
+
+## When to Share
+
+**Share when:**
+
+- Skill applies broadly (not project-specific)
+- Pattern/technique others would benefit from
+- Well-tested and documented
+- Follows writing-skills guidelines
+
+**Keep personal when:**
+
+- Project-specific or organization-specific
+- Experimental or unstable
+- Contains sensitive information
+- Too narrow/niche for general use
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated
+- Working directory is `.codex/skills/` (your project skills)
+- **REQUIRED:** Skill has been tested using writing-skills TDD process
+
+## Sharing Workflow
+
+### 1. Ensure You're on Main and Synced
+
+```bash
+cd .codex/skills/
+git checkout main
+git pull upstream main
+git push origin main  # Push to your fork
+```
+
+### 2. Create Feature Branch
+
+```bash
+# Branch name: add-skillname-skill
+skill_name="your-skill-name"
+git checkout -b "add-${skill_name}-skill"
+```
+
+### 3. Create or Edit Skill
+
+```bash
+# Work on your skill in skills/
+# Create new skill or edit existing one
+# Skill should be in skills/category/skill-name/SKILL.md
+```
+
+### 4. Commit Changes
+
+```bash
+# Add and commit
+git add skills/your-skill-name/
+git commit -m "Add ${skill_name} skill
+
+$(cat <<'EOF'
+Brief description of what this skill does and why it's useful.
+
+Tested with: [describe testing approach]
+EOF
+)"
+```
+
+### 5. Push to Your Fork
+
+```bash
+git push -u origin "add-${skill_name}-skill"
+```
+
+### 6. Create Pull Request
+
+```bash
+# Create PR to upstream using gh CLI
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add ${skill_name} skill" \
+  --body "$(cat <<'EOF'
+## Summary
+Brief description of the skill and what problem it solves.
+
+## Testing
+Describe how you tested this skill (pressure scenarios, baseline tests, etc.).
+
+## Context
+Any additional context about why this skill is needed and how it should be used.
+EOF
+)"
+```
+
+## Complete Example
+
+Here's a complete example of sharing a skill called "async-patterns":
+
+```bash
+# 1. Sync with upstream
+cd .codex/skills/
+git checkout main
+git pull upstream main
+git push origin main
+
+# 2. Create branch
+git checkout -b "add-async-patterns-skill"
+
+# 3. Create/edit the skill
+# (Work on skills/async-patterns/SKILL.md)
+
+# 4. Commit
+git add skills/async-patterns/
+git commit -m "Add async-patterns skill
+
+Patterns for handling asynchronous operations in tests and application code.
+
+Tested with: Multiple pressure scenarios testing agent compliance."
+
+# 5. Push
+git push -u origin "add-async-patterns-skill"
+
+# 6. Create PR
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add async-patterns skill" \
+  --body "## Summary
+Patterns for handling asynchronous operations correctly in tests and application code.
+
+## Testing
+Tested with multiple application scenarios. Agents successfully apply patterns to new code.
+
+## Context
+Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
+```
+
+## After PR is Merged
+
+Once your PR is merged:
+
+1. Sync your local main branch:
+
+```bash
+cd .codex/skills/
+git checkout main
+git pull upstream main
+git push origin main
+```
+
+2. Delete the feature branch:
+
+```bash
+git branch -d "add-${skill_name}-skill"
+git push origin --delete "add-${skill_name}-skill"
+```
+
+## Troubleshooting
+
+**"gh: command not found"**
+
+- Install GitHub CLI: https://cli.github.com/
+- Authenticate: `gh auth login`
+
+**"Permission denied (publickey)"**
+
+- Check SSH keys: `gh auth status`
+- Set up SSH: https://docs.github.com/en/authentication
+
+**"Skill already exists"**
+
+- You're creating a modified version
+- Consider different skill name or coordinate with the skill's maintainer
+
+**PR merge conflicts**
+
+- Rebase on latest upstream: `git fetch upstream && git rebase upstream/main`
+- Resolve conflicts
+- Force push: `git push -f origin your-branch`
+
+## Multi-Skill Contributions
+
+**Do NOT batch multiple skills in one PR.**
+
+Each skill should:
+
+- Have its own feature branch
+- Have its own PR
+- Be independently reviewable
+
+**Why?** Individual skills can be reviewed, iterated, and merged independently.
+
+## Related Skills
+
+- **writing-skills** - REQUIRED: How to create well-tested skills before sharing

package/.codex/skills/skill-creator/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. Use when creating a new skill or updating an existing skill that extends an agent's capabilities with specialized knowledge, workflows, or tool integrations.
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
+---
+
+# Skill Creator
+
+## When to Use
+
+- When creating a new skill or updating an existing skill with specialized workflows or tool integrations.
+
+## When NOT to Use
+
+- When making routine project changes that don't require a reusable skill.
+
+
+
+## What Skills Provide
+
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Company-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex tasks
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation loaded as needed
+    └── assets/           - Files used in output (templates, icons)
+```
+
+## Requirements
+
+- `SKILL.md` should be **less than 200 lines**
+- Use `references/` for detailed documentation
+- Each script or reference file also **less than 200 lines**
+- Descriptions must be specific about WHEN to use the skill
+
+## SKILL.md Format
+
+**REQUIRED - DO NOT SKIP**
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it. Use third-person.
+---
+```
+
+**Required fields:**
+
+- `name` — hyphen-case identifier matching directory name
+- `description` — activation trigger; be specific about WHEN to use
+
+**Optional fields:**
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it.
+references:
+  - references/guide.md
+  - references/api.md
+license: Apache-2.0
+---
+```
+
+**INVALID - Do NOT use:**
+
+- XML-style tags (`<purpose>`, `<references>`)
+- Missing `---` delimiters
+- Frontmatter that doesn't start at line 1
+
+## Bundled Resources
+
+### Scripts (`scripts/`)
+
+- When the same code is being rewritten repeatedly
+- When deterministic reliability is needed
+- Prefer Node.js or Python over Bash (Windows support)
+
+### References (`references/`)
+
+- Documentation that agent should reference while working
+- Database schemas, API docs, domain knowledge
+- If files are large (>10k words), include grep patterns in SKILL.md
+
+### Assets (`assets/`)
+
+- Files used in the final output (not loaded into context)
+- Templates, images, icons, boilerplate code
+
+## Progressive Disclosure
+
+Skills use three-level loading:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by agent (Unlimited)
+
+## Skill Creation Process
+
+### Step 1: Understand with Examples
+
+- "What functionality should the skill support?"
+- "Can you give examples of how this would be used?"
+- "What would a user say that should trigger this skill?"
+
+### Step 2: Plan Reusable Contents
+
+For each example, identify:
+
+- What scripts would be helpful to store?
+- What references/documentation needed?
+- What assets/templates needed?
+
+### Step 3: Create the Skill
+
+```bash
+mkdir -p .codex/skills/my-skill
+touch .codex/skills/my-skill/SKILL.md
+```
+
+### Step 4: Edit SKILL.md
+
+Answer these questions:
+
+1. What is the purpose of the skill?
+2. When should it be used?
+3. How should the agent use it?
+
+### Step 5: Iterate
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Update SKILL.md or bundled resources
+4. Test again
+
+## Pre-Submission Checklist
+
+- [ ] **SKILL.md starts with `---`** (YAML frontmatter, line 1)
+- [ ] **`name:` field present** and matches directory name
+- [ ] **`description:` field present** with specific activation triggers
+- [ ] **Closing `---`** after frontmatter
+- [ ] **No XML-style tags**
+- [ ] **SKILL.md under 200 lines**
+- [ ] **All referenced files exist**