codexkit 1.0.0

package/README.md

@@ -0,0 +1,641 @@
+# Codexkit
+
+> Professional configuration kit for OpenAI Codex CLI — profiles, agents, skills, prompts, and context management.
+
+[![Codex CLI](https://img.shields.io/badge/target-Codex%20CLI-blue)](https://github.com/openai/codex)
+[![Version](https://img.shields.io/badge/version-1.0.0-green)](CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+---
+
+## What is Codexkit?
+
+Codexkit is a complete, opinionated configuration kit for the [OpenAI Codex CLI](https://github.com/openai/codex). It provides battle-tested profiles, structured prompts, reusable skills, lifecycle hooks, context management, and MCP integrations — everything you need to get the most out of Codex from day one. Drop it into any project and start shipping with a professional agent workflow.
+
+Maintained by **QuangThai**.
+
+---
+
+## Quick Start
+
+### Access Model
+
+Codexkit can be distributed as a public npm package even if the source repository remains private.
+That means end users can install the packaged CLI from npm without GitHub repository access, while repository history and collaboration can remain private.
+
+### Preferred Install Flow
+
+For a single project, the simplest installation path is:
+
+```bash
+# One-time on the machine
+npm install -g codexkit
+
+# Inside the project that should use Codexkit
+cd /path/to/your-project
+codexkit install
+
+# Optional: create a project-local MCP env file
+cp .codex/.env.example .codex/.env
+
+# Start Codex from the target project
+codexkit run
+```
+
+If you want multiple projects to share the same root inventory from `~/.codex`, add a one-time global install first:
+
+```bash
+# One-time on the machine
+npm install -g codexkit
+codexkit install-global
+
+# Inside any git repo you want to use with Codexkit
+cd /path/to/your-project
+codexkit install
+```
+
+If you are working directly from a source checkout, you can still clone the repo locally and run the shipped installers:
+
+```bash
+# Authorized user only
+git clone git@github.com:QuangThai/codexkit.git
+cd codexkit
+
+# One-time per machine: install shared root inventory
+bash install/install-global.sh
+
+# Inside any git repo you want to use with Codexkit
+bash install/install-project.sh /path/to/your-project
+
+# Optional: create a project-local MCP env file
+cd /path/to/your-project
+cp .codex/.env.example .codex/.env
+
+# Start Codex from the target project
+codexkit run
+```
+
+If you intentionally want a self-contained project-local install, use `codexkit install --full-local`.
+
+### Remote Installer
+
+Use the remote installer when you want to bootstrap from a prepared archive instead of npm or a local source checkout.
+
+```bash
+# From a local archive prepared by an authorized user
+bash install/install-remote.sh --archive /path/to/codexkit.tar.gz --global
+bash install/install-remote.sh --archive /path/to/codexkit.tar.gz /path/to/your-project
+```
+
+### Packaged CLI
+
+If you prefer a Git-based install from source instead of the public npm package, this flow still works for users who have repository access or a working auth token for Git-based npm installs.
+
+```bash
+# One-time per machine
+npm install -g github:QuangThai/codexkit#v1.0.0
+
+codexkit install-global
+
+# Inside any git repo you want to use with Codexkit
+cd /path/to/your-project
+codexkit install
+
+# Verify from the target project
+codexkit doctor
+
+# Compact a completed bead into durable project context
+codexkit bead-sync br-123
+
+# Launch Codex with project-local MCP env
+codexkit run --profile explore
+```
+
+> **Important:** `codexkit install` is enough for a project-local setup. `codexkit install-global` is optional and only needed when you want multiple repos to reuse shared inventory from `~/.codex/`.
+> **MCP auth:** keep project MCP secrets in `.codex/.env` and start Codex with `codexkit run`. Do not assume `codex` will auto-load project `.env` files by itself.
+> **No root env file:** Codexkit does not use `./.env` or `./.env.example` for MCP bootstrap. The supported location is `.codex/.env`.
+> **Git-based access:** GitHub-based npm installs and private archive flows still require repository or artifact access. The public npm package does not.
+
+### `codexkit run` vs `codex`
+
+Use `codexkit run` as the default launch command when the project relies on MCP credentials from `.codex/.env`.
+The wrapper reads `.codex/.env`, exports those variables into the process environment, and then launches `codex`.
+
+If you launch `codex` directly, the `.codex/.env` file may exist on disk but will not be loaded automatically unless you already export those variables through another mechanism such as your shell profile, `direnv`, or another env loader.
+
+If you prefer typing `codex`, you can create an alias:
+
+```bash
+alias codex="codexkit run"
+```
+
+That keeps the familiar command name while preserving Codexkit's project-local env bootstrap behavior.
+
+`codexkit doctor` reports both validation and ownership:
+
+- `full-local` — the project keeps shared agents, prompts, and skills locally
+- `root-shared` — the project reuses shared inventory from `~/.codex`
+- `mixed-legacy` — root shared inventory exists, but the project still contains legacy local shared files
+- patch inventory and duplicate/override counts for local shared files
+
+`codexkit bead-sync <id>` compacts a bead's raw artifacts into
+`.codex/memory/research/beads/<id>.md`, so future work can reuse the durable summary
+without scanning raw `.beads/artifacts/` trees first.
+
+`codexkit bead-close <id> --reason "..."` syncs the bead summary, closes the
+bead, and flushes bead state in one step.
+
+`codexkit bead-search "<query>" --limit 3` ranks prior synced bead summaries
+and durable context docs so `/create` can pull forward the most relevant prior work.
+
+`codexkit bead-start <id>` validates the bead PRD, claims the bead, and prepares
+the default execution branch.
+
+`codexkit bead-verify <id> --full` runs project gates plus PRD `Verify:` commands
+and records a PASS stamp in `.beads/verify.log`.
+
+### Local Source Alternative
+
+If you keep a local checkout of Codexkit, you can still install directly from it:
+
+```bash
+cd /path/to/your-project
+bash /absolute/path/to/codexkit/install/install-project.sh
+```
+
+### Distribution Policy
+
+- Codexkit can be published as a public npm package for the packaged CLI distribution path.
+- The source repository can remain private even when the npm package is public.
+- Public npm users do not need repository access.
+- Git-based installs from the repository still require repository read access or an equivalent credential.
+
+---
+
+## Profiles
+
+Six presets that configure model, sandbox, and approval policy:
+
+| Profile              | Model         | Sandbox         | Approval   | Use Case                |
+| -------------------- | ------------- | --------------- | ---------- | ----------------------- |
+| `default`           | gpt-5.3-codex | workspace-write | on-request | Daily driver            |
+| `explore`            | gpt-5.3-codex | read-only       | never      | Codebase understanding  |
+| `plan`               | gpt-5.4       | read-only       | never      | Architecture & planning |
+| `build`              | gpt-5.3-codex | workspace-write | on-request | Implementation          |
+| `review`             | gpt-5.4       | read-only       | never      | Code review & audit     |
+| `ship`               | gpt-5.3-codex | workspace-write | on-request | Release & PR prep       |
+
+```bash
+# Use a profile
+codex --profile explore "how does the auth system work?"
+codex --profile build "implement the payments API"
+codex --profile review "review the last 3 commits"
+```
+
+See [docs/profiles.md](docs/profiles.md) for detailed descriptions and customization.
+
+---
+
+## Prompts
+
+19 structured workflow entry points — the **"what"** of your development process.
+
+> **Note:** Prompts require global installation. Run `bash install/install-global.sh`, use an authorized archive-based remote install with `--global`, or use `codexkit install-global`.
+
+| Category          | Prompt            | Purpose                                           |
+| ----------------- | ----------------- | ------------------------------------------------- |
+| **Setup**         | `init`            | Initialize project context (once per repo)        |
+|                   | `init-user`       | Create user profile for personalization           |
+|                   | `init-context`    | Set up planning context (project, roadmap, state) |
+| **Task Creation** | `create`          | Create task specification with requirements       |
+|                   | `start`           | Begin working on a task                           |
+|                   | `plan`            | Optional compatibility shim for durable `plan.md` |
+|                   | `research`        | Optional compatibility shim for persisted research |
+| **Execution**     | `ship`            | Implement + verify + review in one pass           |
+|                   | `verify`          | Verify implementation correctness                 |
+|                   | `review-codebase` | Structured code review                            |
+|                   | `pr`              | Prepare and create pull request                   |
+|                   | `lfg`             | Full autonomous: plan → ship → review → PR        |
+| **Design**        | `ui-inspire`      | Search external UI references grounded in repo patterns |
+|                   | `design`          | UI/UX visual design with code output              |
+|                   | `ui-review`       | Review UI/UX for quality and accessibility        |
+| **Session**       | `handoff`         | Save progress and context for next session        |
+|                   | `resume`          | Resume work from a previous session               |
+|                   | `status`          | Show project status dashboard                     |
+|                   | `compound`        | Extract and persist learnings                     |
+
+### Standard Development Flow
+
+```
+/prompts:init     → Set up project context (once per repo)
+     ↓
+/prompts:create   → Specify a task with requirements
+     ↓
+/prompts:start    → Claim task and prepare workspace
+     ↓
+/prompts:ship     → Implement + verify + review
+     ↓
+/prompts:verify   → Verify implementation correctness
+     ↓
+/prompts:pr       → Prepare and create pull request
+     ↓
+/prompts:compound → Extract and persist learnings
+```
+
+`/prompts:create`, `/prompts:start`, `/prompts:ship`, and `/prompts:verify` auto-bootstrap beads state when `.beads/` is missing.
+
+`/prompts:plan` and `/prompts:research` still exist, but only as optional compatibility shims when you want persisted `plan.md` or research artifacts.
+
+### Quick Ship Flow
+
+```
+/prompts:ship    → Implement + verify + review in one pass
+/prompts:lfg     → Full autonomous: plan → implement → verify → review → PR
+```
+
+### Session Management
+
+```
+/prompts:handoff → Save progress for next session
+/prompts:resume  → Resume from a previous session
+/prompts:status  → Show project status dashboard
+```
+
+See [docs/prompts.md](docs/prompts.md) for full prompt descriptions.
+
+---
+
+## Skills
+
+88 reusable procedures — the **"how"** of your development process. Invoked with the `$` prefix.
+
+| Category           | Skill                      | Purpose                                     |
+| ------------------ | -------------------------- | ------------------------------------------- |
+| **Planning**       | `$repo-orientation`        | Understand codebase before working          |
+|                    | `$task-planning`           | Goal-backward planning methodology          |
+|                    | `$writing-plans`           | Zero-ambiguity plan creation with TDD       |
+|                    | `$executing-plans`         | Wave-based parallel plan execution          |
+|                    | `$brainstorming`           | Collaborative idea refinement               |
+| **Implementation** | `$safe-implementation`     | TDD + deviation rules                       |
+|                    | `$test-strategy`           | Testing approach selection                  |
+|                    | `$test-driven-development` | RED → GREEN → REFACTOR cycle                |
+|                    | `$testing-anti-patterns`   | Avoid common testing mistakes               |
+|                    | `$frontend-design`         | UI implementation patterns                  |
+|                    | `$ui-inspiration-scout`    | Codebase-grounded external UI scouting      |
+| **Debugging**      | `$bug-triage`              | Systematic bug investigation                |
+|                    | `$debugging`               | Scientific debugging method                 |
+|                    | `$systematic-debugging`    | 4-phase debug framework                     |
+|                    | `$root-cause-tracing`      | Trace bugs backward to source               |
+| **Quality**        | `$code-review`             | Review methodology with severity levels     |
+|                    | `$verification`            | Goal-backward verification (3-level)        |
+|                    | `$refactoring`             | Safe refactoring patterns                   |
+| **Session**        | `$docs-handoff`            | Session handoff and resume                  |
+|                    | `$session-management`      | Session start/pause/resume lifecycle        |
+|                    | `$context-management`      | Token budget and context health             |
+|                    | `$memory-system`           | Memory search and observation creation      |
+| **Release**        | `$git-pr-prep`             | PR preparation and review gates             |
+|                    | `$dependency-upgrades`     | Safe dependency update workflow             |
+| **Task Tracking**  | `$beads`                          | Multi-agent task coordination with `br` CLI |
+|                    | `$beads-bridge`                   | Beads + agent bridge for cross-session work |
+|                    | `$prd`                            | Product Requirements Document creation      |
+|                    | `$prd-task`                       | PRD to executable JSON task conversion      |
+|                    | `$swarm-coordination`             | Parallel agent orchestration patterns       |
+| **Workflow**       | `$development-lifecycle`          | Full feature lifecycle orchestration        |
+|                    | `$finishing-a-development-branch` | Branch completion and merge workflow        |
+|                    | `$using-git-worktrees`            | Git worktree isolation workflow             |
+| **Research**       | `$deep-research`                  | Structured LSP exploration and analysis     |
+| **Review**         | `$requesting-code-review`         | Dispatch scoped review agents               |
+|                    | `$receiving-code-review`          | Handle review feedback with rigor           |
+|                    | `$verification-before-completion` | Evidence-based completion verification      |
+
+Skills can be chained: `$task-planning → $safe-implementation → $verification`
+
+See [docs/skills.md](docs/skills.md) for detailed descriptions and how to create custom skills.
+
+## Patch Workflow
+
+Codexkit can snapshot local overrides to managed core files and re-apply them after upgrades.
+
+```bash
+# From your project root
+codexkit patch create "custom auth - Preserve local auth flow"
+codexkit patch list
+codexkit patch diff custom-auth
+
+# Upgrade Codexkit, then re-apply all enabled patches
+codexkit upgrade --auto-apply-patches
+```
+
+Each patch is stored under `Codexkit_patches/<name>/` with:
+
+- `patch.patch` — unified diff against the managed Codexkit source file(s)
+- `metadata.json` — name, description, version, enabled state, and target files
+
+Use `codexkit patch disable <name>` to keep a patch on disk without auto-applying it.
+
+---
+
+## Context Management
+
+Codexkit maintains curated project knowledge in `.codex/context/`:
+
+| File                    | Purpose                               |
+| ----------------------- | ------------------------------------- |
+| `index.md`              | Map of available docs (start here)    |
+| `architecture.md`       | System boundaries and key modules     |
+| `conventions.md`        | Coding norms and repo patterns        |
+| `current-priorities.md` | What matters right now                |
+| `decision-log.md`       | Durable architecture decision records |
+| `worklog.md`            | Session-level human-readable trail    |
+| `gotchas.md`            | Footguns, edge-cases, and known traps |
+
+The agent reads `context/index.md` at session start and updates `worklog.md` after significant milestones. This gives every session — and every new contributor — instant project context.
+
+### Memory Positioning
+
+Codexkit's default memory model is:
+- Codex-native primitives such as `AGENTS.md`, config layering, history, `codex resume`, and compaction
+- repo-visible durable docs in `.codex/context/` and `.codex/memory/`
+
+This is intentionally different from a semantic memory product. Repo docs remain the source of truth for architecture, conventions, state, and decisions.
+
+Optional MCP-backed memory is supported, but only as an additive retrieval layer. It should not replace repo-visible project knowledge.
+
+See [docs/memory.md](docs/memory.md) for the default memory strategy and
+[docs/memory-mcp.md](docs/memory-mcp.md) for optional MCP-backed memory.
+
+For maintenance, run:
+
+```bash
+bash .codex/scripts/audit_memory_hygiene.sh
+```
+
+This audits line budgets and boundary drift across `worklog.md`, `decision-log.md`, `session-context.md`, and `state.md`.
+
+For lightweight local retrieval, run:
+
+```bash
+bash .codex/scripts/build_memory_index.sh
+bash .codex/scripts/memory_search.sh "your query"
+```
+
+This index is derived from repo docs and is safe to rebuild or delete.
+
+---
+
+## Hooks
+
+Optional lifecycle automation scripts in `.codex/hooks/`:
+
+| Hook                | Trigger                              |
+| ------------------- | ------------------------------------ |
+| `after_agent.sh`    | After the agent completes a response |
+| `after_tool_use.sh` | After any tool invocation            |
+
+Codex CLI supports only two hook events: `AfterAgent` and `AfterToolUse`. Hooks are opt-in. Codexkit works without them. See [docs/hooks.md](docs/hooks.md) for details.
+
+---
+
+## MCP Integrations
+
+Opt-in external capabilities via [Model Context Protocol](https://modelcontextprotocol.io):
+
+| Integration | Transport | Purpose                          |
+| ----------- | --------- | -------------------------------- |
+| Tilth       | stdio     | AST-aware code navigation        |
+| Context7    | HTTP      | Library documentation lookup     |
+| Exa         | HTTP      | Web search and code examples     |
+| Ref         | stdio     | Documentation search and reading |
+
+**Two-tier architecture:**
+
+- **Project-level** (`.codex/config.toml`): Tilth only — no API keys needed
+- **User-level** (`~/.codex/config.toml`): Context7, Exa, Ref server definitions
+- **Project env** (`.codex/.env`): API keys loaded by `codexkit run` before `codex` starts
+
+Example configs are in `.codex/mcp/`. Copy `.codex/.env.example` to `.codex/.env`, fill in the keys you need, then launch with `codexkit run`. See [docs/mcp.md](docs/mcp.md) for setup guides and
+[docs/memory-mcp.md](docs/memory-mcp.md) for optional retrieval memory.
+
+---
+
+## Project Structure
+
+```
+codexkit/
+├── AGENTS.md                          # Operating rules (always loaded)
+├── CLAUDE.md                          # Claude/Amp agent instructions
+├── AGENTS.override.md.example         # Personal override template
+├── README.md                          # This file
+├── .gitignore
+│
+├── .codex/
+│   ├── config.toml                    # Profiles, agents, hooks, MCP
+│   ├── prompts/                       # 19 workflow prompts
+│   │   ├── init.md
+│   │   ├── init-user.md
+│   │   ├── init-context.md
+│   │   ├── research.md
+│   │   ├── create.md
+│   │   ├── plan.md
+│   │   ├── start.md
+│   │   ├── ship.md
+│   │   ├── verify.md
+│   │   ├── review-codebase.md
+│   │   ├── pr.md
+│   │   ├── lfg.md
+│   │   ├── ui-inspire.md
+│   │   ├── design.md
+│   │   ├── ui-review.md
+│   │   ├── handoff.md
+│   │   ├── resume.md
+│   │   ├── status.md
+│   │   └── compound.md
+│   ├── agents/                        # 11 agent definitions
+│   │   ├── planner.toml
+│   │   ├── reviewer.toml
+│   │   ├── shipper.toml
+│   │   ├── scout.toml
+│   │   ├── vision.toml
+│   │   ├── debugger.toml
+│   │   ├── refactorer.toml
+│   │   ├── builder.toml
+│   │   ├── runner.toml
+│   │   ├── general.toml
+│   │   └── painter.toml
+│   ├── context/                       # 8 curated project knowledge files
+│   │   ├── index.md
+│   │   ├── architecture.md
+│   │   ├── conventions.md
+│   │   ├── current-priorities.md
+│   │   ├── decision-log.md
+│   │   ├── worklog.md
+│   │   ├── gotchas.md
+│   │   └── session-context.md
+│   ├── skills/                        # 87 canonical reusable skills
+│   │   ├── repo-orientation/
+│   │   ├── task-planning/
+│   │   ├── safe-implementation/
+│   │   ├── verification/
+│   │   └── ...
+│   ├── hooks/                         # 2 lifecycle scripts
+│   │   ├── README.md
+│   │   ├── after_agent.sh
+│   │   └── after_tool_use.sh
+│   ├── scripts/                       # Utility scripts
+│   │   ├── build_startup_brief.sh
+│   │   ├── append_worklog.sh
+│   │   └── detect_changed_files.sh
+│   └── mcp/                           # MCP server examples
+│       ├── README.md
+│       ├── tilth.toml.example
+│       ├── context7.toml.example
+│       ├── exa.toml.example
+│       └── ref.toml.example
+├── install/                           # Installers
+│   ├── install-global.sh              # Install to ~/.codex/ (prompts + config)
+│   ├── install-project.sh             # Install to .codex/ (project-level)
+│   ├── install-remote.sh              # Download + install into current repo
+│   └── validate.sh                    # Validate installation
+├── bin/
+│   └── codexkit                       # Packaged CLI entrypoint
+│
+├── templates/                         # Scaffolding templates
+│   ├── global/
+│   │   ├── README.md
+│   │   └── AGENTS.override.md
+│   └── project/
+│       ├── README.md
+│       ├── .codex-config-template.toml
+│       └── AGENTS.md.template
+│
+├── docs/                              # Documentation
+│   ├── architecture.md
+│   ├── compaction-guide.md
+│   ├── config-reference.md
+│   ├── dcp-guidance.md
+│   ├── hooks.md
+│   ├── mcp-advanced.md
+│   ├── mcp.md
+│   ├── memory-mcp.md
+│   ├── memory.md
+│   ├── migration-legacy.md
+│   ├── migration-map.md
+│   ├── plan-storage.md
+│   ├── profiles.md
+│   ├── agents.md
+│   ├── skills.md
+│   ├── prompts.md
+│   ├── release-checklist.md
+│   ├── troubleshooting.md
+│   └── tui-configuration.md
+│
+└── tests/                             # Tests
+    ├── run_release_gate.sh            # Release-grade full gate runner
+    ├── smoke/
+    │   ├── test_structure.sh
+    │   └── test_scripts.sh
+    └── integration/
+        ├── test_bead_close_idempotency.sh
+        ├── test_bead_context_search.sh
+        ├── test_cli.sh
+        ├── test_create_prior_related_work.sh
+        ├── test_install.sh
+        ├── test_hooks.sh
+        ├── test_inventory_consistency.sh
+        ├── test_memory_runtime.sh
+        ├── test_patch.sh
+        ├── test_profiles.sh
+        ├── test_remote_install.sh
+        ├── test_docs_behavior.sh
+        ├── test_docs_inventory.sh
+        ├── test_docs_policy.sh
+        ├── test_prompt_agent_contracts.sh
+        ├── test_prompt_inventory.sh
+        ├── test_release_process.sh
+        ├── test_skill_catalog.sh
+        ├── test_start_ship_verify_e2e.sh
+        ├── test_start_workflow.sh
+        ├── test_verify_workflow.sh
+        └── test_workflow_runtime.sh
+```
+
+
+---
+
+## Verification
+
+Run the whole shipped verification suite:
+
+```bash
+bash tests/run_release_gate.sh
+```
+
+The release gate covers:
+- structure and executable scripts
+- prompt quality, agent quality, docs consistency, and inventory consistency
+- install workflow, packaged CLI install, remote installer, and beads-backed runtime workflow
+- release process validation and project wiring
+
+---
+
+## Customization
+
+### Adding a Custom Profile
+
+Edit `.codex/config.toml`:
+
+```toml
+[profiles.my-custom]
+model = "gpt-5.3-codex"
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+```
+
+### Adding a Custom Skill
+
+```bash
+mkdir -p .codex/skills/my-skill/
+```
+
+Create `.codex/skills/my-skill/SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+trigger: When to activate this skill
+---
+
+# My Skill
+
+## Steps
+
+1. ...
+```
+
+### Personal Overrides
+
+Copy `AGENTS.override.md.example` to `AGENTS.override.md` (gitignored) to add personal instructions that layer on top of the base `AGENTS.md`.
+
+---
+
+## Migration from Prior Frameworks
+
+If you're migrating from a prior agent framework, see [docs/migration-map.md](docs/migration-map.md) for a complete mapping of old → new file locations, renamed concepts, and upgrade steps.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes — follow the conventions in `AGENTS.md`
+4. Open a pull request
+
+Please keep changes focused and well-scoped. One PR per concern.
+
+---
+
+## License
+
+MIT © QuangThai