release: v0.9.0 — 5-Layer enrichment, Tier 2/3 content, evolution system

- Tier 2 enrichment: 21 skills with verification/checklist.md, examples/good-output.md, examples/common-mistakes.md
- Tier 3 enrichment: 5 technical skills with scripts/ and templates/ (executable helpers)
- Evolution system: /evolve-skill workflow + gotchas-template.md
- Tooling: validate-pack.mjs with v2 section lint + category breakdown
- Docs sync: CHANGELOG, README, CONTRIBUTING, web docs updated
- RELEASE-v0.9.0.md: release announcement with before/after comparison

Author: Hoa Dang DNA PC

CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-03-22
+
+### Added
+
+- **Tier 2 enrichment for 20 core skills**: Domain-specific `verification/checklist.md`, `examples/good-output.md`, and `examples/common-mistakes.md` for: bug-hunt, high-signal-review, execution-planner, okr-writer, sprint-planning-assistant, financial-statement-analyzer, contract-risk-review, data-quality-auditor, dashboard-kpi-designer, a-b-test-planner, go-to-market-planner, campaign-brief-writer, incident-postmortem, root-cause-analyzer, onboarding-plan-creator, repo-onboarding, survey-analyzer, business-case-writer, process-mapper, and customer-journey-mapper.
+- **Tier 3 enrichment for 5 technical skills**: Executable assets including `coverage-gap-finder.sh` (test-hardening), `query-validator.sql` (sql-query-builder), `readme-template.md` + `changelog-template.md` (docs-shipper), `automation-spec.md` (automation-designer), `charter-template.md` + `raci-template.md` (project-governance-pilot).
+- **Gotchas template**: `templates/gotchas-template.md` for capturing real-world edge cases and workarounds per skill.
+- **`/evolve-skill` workflow**: Structured process for updating skills after discovering issues, edge cases, or improvements — includes change classification, version bumping, changelog updates, and validation.
+- **v2 section lint**: `validate-pack.mjs` now warns on missing v2 sections (Quality Criteria, Verification 4C, Edge Cases, Changelog).
+- **Category breakdown**: Pack validation output now shows per-category skill counts.
+- **Community contribution guide**: CONTRIBUTING.md expanded with tier enrichment guide and community call-to-action for skills needing enrichment.
+
+### Changed
+
+- 21 skills now have `verification/` folders (20 Tier 2 enriched + 1 exemplar).
+- 21 skills now have `examples/` folders with domain-specific good output and common mistakes.
+- 5 skills now have `scripts/` or `templates/` folders with executable Tier 3 assets.
+- CONTRIBUTING.md refactored with community contribution opportunities and enrichment guide.
+- README updated with v0.9.0 enrichment stats, contribution call-to-action, and release instructions.
+
+## [0.8.0] - 2026-03-22
+
+### Added
+
+- **5-Layer Skill Framework**: Every skill now addresses Intent, Knowledge, Execution, Verification (4C), and Evolution layers.
+- **SKILL.md v2 Template**: `templates/SKILL-TEMPLATE.md` — 10-section template with Quality Criteria, Verification (4C), Edge Cases, and Changelog sections.
+- **Deep Research Master Prompt**: `templates/deep-research-prompt.md` — universal prompt for ChatGPT Deep Research / Gemini / Perplexity Pro that generates structured domain knowledge mapping directly into SKILL.md sections.
+- **Exemplar skill**: `codexkit-skill-template` — working reference implementation demonstrating full Tier 2 folder structure (SKILL.md, verification/, examples/, CHANGELOG.md).
+- **Skill categories**: 8-category taxonomy (`knowledge`, `verification`, `data`, `automation`, `scaffolding`, `review`, `runbook`, `infra`) added to skill frontmatter.
+- **3-tier skill structure**: Tier 1 (all skills — SKILL.md + agents/), Tier 2 (~20 high-value — + verification/ + examples/), Tier 3 (~5–10 technical — + templates/ + scripts/).
+
+### Changed
+
+- Skill count increased from 81 to 82 (added `codexkit-skill-template` exemplar).
+- `CONTRIBUTING.md` expanded with comprehensive skill authoring guide (7-step process, folder structure guide).
+- `skill-finder.md` updated with category taxonomy section and exemplar skill entry.
+- README updated with new "Skill architecture" section.
+
 ## [0.7.1] - 2026-03-20
 
 ### Fixed
@@ -144,7 +182,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Cross-platform skill installation scripts and a validation script.
 - New docs site positioned for OpenAI Codex and ChatGPT users.
 
-[Unreleased]: https://github.com/hoavdc/CodexKit/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/hoavdc/CodexKit/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/hoavdc/CodexKit/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/hoavdc/CodexKit/compare/v0.7.1...v0.8.0
 [0.7.1]: https://github.com/hoavdc/CodexKit/releases/tag/v0.7.1
 [0.7.0]: https://github.com/hoavdc/CodexKit/releases/tag/v0.7.0
 [0.6.0]: https://github.com/hoavdc/CodexKit/releases/tag/v0.6.0

CONTRIBUTING.md

@@ -10,6 +10,28 @@ CodexKit is meant to stay opinionated and useful. Contributions are welcome when
 4. Prefer small, composable additions over broad prompt dumps.
 5. Use the issue and pull request templates so context is structured from the start.
 
+## Authoring a new skill
+
+1. **Start from the template.** Copy [`templates/SKILL-TEMPLATE.md`](templates/SKILL-TEMPLATE.md) into `skills/codexkit-{your-skill}/SKILL.md`.
+2. **Fill all 10 sections.** Purpose, When to Use, Procedure, Inputs, Output, Quality Criteria, Verification (4C), Edge Cases, Examples, Changelog.
+3. **Assign a category** in frontmatter — one of: `knowledge`, `verification`, `data`, `automation`, `scaffolding`, `review`, `runbook`, `infra`.
+4. **Set version** to `1.0.0` in frontmatter.
+5. **Use Deep Research** (optional but recommended). Copy [`templates/deep-research-prompt.md`](templates/deep-research-prompt.md), fill in your skill's domain, and paste into ChatGPT Deep Research / Gemini / Perplexity Pro. Map the 6 output sections back into your SKILL.md.
+6. **Add `agents/openai.yaml`** with the interface block.
+7. **Run validation:** `node ./scripts/validate-pack.mjs`
+
+### Skill folder structure
+
+Minimum (all skills): `SKILL.md` + `agents/openai.yaml`
+
+For high-value skills, consider adding:
+- `verification/checklist.md` — domain-specific 4C checklist
+- `examples/good-output.md` and `examples/common-mistakes.md`
+- `templates/` — output templates or starter files
+- `CHANGELOG.md` — version history
+
+See [`templates/SKILL-TEMPLATE.md`](templates/SKILL-TEMPLATE.md) for the full tier guide.
+
 ## Contribution guidelines
 
 - Add new skills only when they cover a distinct workflow.
@@ -27,6 +49,31 @@ CodexKit is meant to stay opinionated and useful. Contributions are welcome when
 - clarify docs
 - add narrowly scoped templates
 
+## Community enrichment — where help is most needed
+
+### Tier 2 enrichment (61 skills need this)
+
+21 of 82 skills already have `verification/` and `examples/` folders. The other 61 do not. To enrich a skill:
+
+1. Pick a skill you have domain expertise in.
+2. Create `verification/checklist.md` — answer four domain-specific questions for each of the 4C gates (Correctness, Completeness, Context-fit, Consequence).
+3. Create `examples/good-output.md` — provide a realistic, annotated example of what a well-executed output looks like.
+4. Create `examples/common-mistakes.md` — document 3 anti-patterns with explanations and fixes.
+5. Reference `skills/codexkit-skill-template/` for the expected format.
+
+### Tier 3 enrichment (technical skills)
+
+5 skills have `scripts/` or `templates/` folders. Other technical skills would benefit from:
+- Reusable helpers in `scripts/` (linters, validators, analyzers)
+- Starter templates in `templates/` (output formats, spec documents)
+
+### Gotchas
+
+If you discover an edge case or workaround while using a skill:
+1. Copy `templates/gotchas-template.md` into the skill folder as `gotchas.md`.
+2. Add a `GOTCHA-001` entry with discovery date, symptom, root cause, workaround, and status.
+3. Use the `/evolve-skill` workflow to handle versioning.
+
 ## Pull request expectations
 
 - Link the issue or explain why no issue was needed.

README.md

@@ -2,15 +2,15 @@
 
 Open-source operating kit for people using OpenAI Codex and ChatGPT to think, write, analyze, decide, automate routine work, and ship better output with more consistency.
 
-CodexKit is a fresh project rebuilt around the surfaces that matter in Codex today: local Skills, high-signal playbooks, automation recipes, operational templates, department starter workspaces, repo guardrails, and MCP onboarding guidance. The pack covers 81 skills across 13 domains: engineering workflows, high-reasoning work, and low-reasoning office automation across project management, finance, legal, HR, operations, supply chain, strategy, analytics, marketing, data, customer success, IT & admin, training & development, and cross-functional work. It follows the official Codex Skills layout with `SKILL.md`, optional `agents/openai.yaml`, and standard `.agents/skills` discovery paths.
+CodexKit is a fresh project rebuilt around the surfaces that matter in Codex today: local Skills, high-signal playbooks, automation recipes, operational templates, department starter workspaces, repo guardrails, and MCP onboarding guidance. The pack covers 82 skills across 13 domains: engineering workflows, high-reasoning work, and low-reasoning office automation across project management, finance, legal, HR, operations, supply chain, strategy, analytics, marketing, data, customer success, IT & admin, training & development, and cross-functional work. It follows the official Codex Skills layout with `SKILL.md`, optional `agents/openai.yaml`, and standard `.agents/skills` discovery paths.
 
 ## What is included
 
-- `skills/`: 81 installable Codex Skills across 13 domains — engineering, high-reasoning business work, and low-reasoning office automation.
+- `skills/`: 82 installable Codex Skills across 13 domains — engineering, high-reasoning business work, and low-reasoning office automation.
 - `playbooks/`: copy-ready prompts for clarify, execute, review, decision, delegation, and release work.
 - `automations/`: recurring task recipes for engineering plus weekly business, close, hiring, legal intake, operations, and marketing routines.
 - `mcp/`: practical guidance for choosing and rolling out MCP servers without overloading the team.
-- `templates/`: reusable department templates for PM, finance, HR, legal, operations, marketing, and cross-functional work.
+- `templates/`: reusable templates including department templates (PM, finance, HR, legal, operations, marketing, cross-functional), the SKILL.md v2 template, and a deep research master prompt for skill authoring.
 - `workspaces/`: starter workspace kits for PM, finance, HR, legal, ops, and marketing teams.
 - `scripts/`: cross-platform skill installers, workspace quick-start scripts, and a pack validator.
 - `web/`: a Next.js docs site for publishing the kit as a public open-source project.
@@ -31,12 +31,12 @@ CodexKit is a fresh project rebuilt around the surfaces that matter in Codex tod
 If you do not want to use Git commands or remember terminal steps, use the GitHub release package:
 
 1. Open the Releases page for this repository.
-2. Download `codexkit-starter-pack-v0.7.1.zip`.
+2. Download `codexkit-starter-pack-v0.9.0.zip`.
 3. Unzip it anywhere on your computer.
 4. On Windows, double-click `START-HERE-WINDOWS.cmd`.
    - If Codex is not installed, the script will show installation instructions.
 5. Restart Codex.
-6. In Codex, type `/skills` to confirm all 81 skills appear.
+6. In Codex, type `/skills` to confirm all 82 skills appear.
 7. Open `skill-finder.md` to browse skills by situation.
 7. Optional: double-click `CREATE-WORKSPACE-WINDOWS.cmd` to create a starter workspace.
 
@@ -197,6 +197,53 @@ CodexKit/
 - Automations must include guardrails, not just schedules.
 - MCP adoption should be intentional, observable, and reversible.
 
+## Skill architecture
+
+CodexKit uses a **5-Layer Skill Framework** with a tiered structure:
+
+### Layers
+
+Every skill addresses five concerns: **Intent** (clear purpose), **Knowledge** (domain expertise), **Execution** (step-by-step procedure), **Verification** (4C quality gates — Correctness, Completeness, Context-fit, Consequence), and **Evolution** (versioned changelog).
+
+### Tiers
+
+| Tier | Structure | Current coverage |
+|------|-----------|------------------|
+| **1** | `SKILL.md` + `agents/openai.yaml` | All 82 skills |
+| **2** | + `verification/` + `examples/` | 21 high-value skills |
+| **3** | + `templates/` + `scripts/` | 5 technical skills |
+
+### Categories
+
+| Category | Skills |
+|----------|--------|
+| `knowledge` | 17 |
+| `data` | 14 |
+| `scaffolding` | 14 |
+| `runbook` | 10 |
+| `verification` | 9 |
+| `automation` | 8 |
+| `review` | 6 |
+| `infra` | 4 |
+
+### Authoring new skills
+
+Use `templates/SKILL-TEMPLATE.md` as the starting point. Optionally, use `templates/deep-research-prompt.md` with an external AI research tool (ChatGPT Deep Research, Gemini, Perplexity Pro) to generate domain knowledge — the 6-section output maps directly into the SKILL.md sections. See `skills/codexkit-skill-template/` for a working reference implementation.
+
+Full authoring guide: [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Contributing
+
+CodexKit is open-source and community-driven. There are several ways to help:
+
+- **Enrich existing skills**: 61 skills still need Tier 2 content (`verification/`, `examples/`). Pick a skill you know well, create domain-specific checklists and examples, and open a PR.
+- **Add Tier 3 assets**: Technical skills benefit from `scripts/` and `templates/`. Build a reusable helper or output template.
+- **Create new skills**: Use `templates/SKILL-TEMPLATE.md` + `templates/deep-research-prompt.md` to author a skill for a domain you are expert in.
+- **Add gotchas**: If you encounter a real-world edge case while using a skill, document it using `templates/gotchas-template.md` and add it to the skill folder.
+- **Improve docs or translations**: The docs site, playbooks, and the Vietnamese guide all benefit from review.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
+
 ## Open-source quality bar
 
 - MIT license
@@ -217,19 +264,19 @@ CodexKit/
 - Replace placeholder maintainer details where needed.
 - Add screenshots or a short demo GIF to the docs site.
 - Commit and push the release candidate branch or `main`.
-- Tag `v0.7.1` after validating the pack and docs build.
+- Tag `v0.9.0` after validating the pack and docs build.
 - Push the tag to trigger the GitHub release workflow.
 
 ## Release process
 
 1. Update `package.json`, `web/package.json`, and `CHANGELOG.md`.
 2. Run `npm run check`.
 3. Commit and push the release commit.
-4. Create the tag: `git tag v0.7.1`
-5. Push the tag: `git push origin v0.7.1`
+4. Create the tag: `git tag v0.9.0`
+5. Push the tag: `git push origin v0.9.0`
 6. GitHub Actions publishes:
-   `codexkit-source-v0.7.1.zip`
-   `codexkit-starter-pack-v0.7.1.zip`
+   `codexkit-source-v0.9.0.zip`
+   `codexkit-starter-pack-v0.9.0.zip`
 
 ## Related files
 

RELEASE-v0.9.0.md

@@ -0,0 +1,96 @@
+# CodexKit v0.9.0 — Skills That Actually Verify Themselves
+
+> **82 skills. 5 layers. 21 domain-enriched. Community-ready.**
+
+## What's new
+
+This release transforms CodexKit from a flat collection of prompts into a **layered skill operating system** where every skill knows how to verify its own output and evolve from real-world usage.
+
+### Domain-specific quality gates for 21 core skills
+
+The 20 most impactful skills now ship with three companion files — written by domain experts, not generic templates:
+
+| Asset | What it does |
+|-------|-------------|
+| `verification/checklist.md` | 4C quality gates (Correctness, Completeness, Context-fit, Consequence) with questions specific to each skill's domain |
+| `examples/good-output.md` | Annotated real-world scenarios showing what a well-executed output looks like |
+| `examples/common-mistakes.md` | Three anti-patterns per skill — the mistakes that waste the most time — with explanations and fixes |
+
+**Example**: The `codexkit-incident-postmortem` checklist doesn't ask generic quality questions — it asks "Does the timeline include detection-to-resolution with timestamps?" and "Are action items assigned with owners and deadlines, not vague 'we should improve' language?"
+
+### Executable Tier 3 assets for technical skills
+
+5 technical skills now ship with runnable scripts and starter templates:
+
+- **test-hardening** → `coverage-gap-finder.sh` — multi-language coverage report generator
+- **sql-query-builder** → `query-validator.sql` — checks execution plans, NULL traps, cardinality explosions
+- **docs-shipper** → `readme-template.md` + `changelog-template.md` — Keep a Changelog format
+- **automation-designer** → `automation-spec.md` — full automation specification template
+- **project-governance-pilot** → `charter-template.md` + `raci-template.md` — project charter + RACI matrix
+
+### Evolution system: skills that learn from usage
+
+- **`/evolve-skill` workflow**: When you discover an edge case, the workflow classifies the change type, applies the right version bump, updates the changelog, and validates the result.
+- **`gotchas-template.md`**: Accumulate real-world workarounds per skill — each entry captures the symptom, root cause, and fix so the knowledge doesn't get lost.
+
+### Smarter validation
+
+- `validate-pack.mjs` now **lints v2 sections** — warns if a skill is missing Quality Criteria, Verification (4C), Edge Cases, or Changelog.
+- Pack stats now show a **per-category skill breakdown** so you can see which domains are strongest and which need attention.
+
+## Before vs After
+
+| | v0.8.0 | v0.9.0 |
+|---|--------|--------|
+| Skill files | `SKILL.md` + `agents/` only | 3-tier system with verification, examples, scripts, templates |
+| Output verification | Manual — hope for the best | 4C checklists with domain questions |
+| Learning from mistakes | None | `gotchas.md` + `/evolve-skill` workflow |
+| Validation depth | Frontmatter + structure | + v2 section lint + category breakdown |
+| Anti-patterns documented | 0 | 60 anti-patterns across 20 skills |
+| Executable helpers | 0 | 7 scripts/templates for 5 technical skills |
+
+## Community contribution opportunity
+
+**61 skills** still need Tier 2 enrichment. This is the single highest-impact way to contribute to CodexKit.
+
+### How to contribute a Tier 2 enrichment
+
+1. Pick a skill you know well from the [skill list](./skill-finder.md)
+2. Create `verification/checklist.md` — domain-specific 4C questions
+3. Create `examples/good-output.md` — annotated scenario
+4. Create `examples/common-mistakes.md` — 3 anti-patterns with fixes
+5. Reference `skills/codexkit-skill-template/` for the expected format
+6. Run `node scripts/validate-pack.mjs` and open a PR
+
+### Skills most in need of enrichment
+
+| Domain | Skills needing enrichment |
+|--------|--------------------------|
+| Finance & Legal | fpa-scenario-modeling, fpa-rolling-forecast, audit-readiness-checker, contract-drafter, legal-memo-writer, legal-due-diligence |
+| HR & Operations | job-description-writer, performance-review-writer, interview-guide-builder, supplier-evaluation, procurement-rfp-writer |
+| Strategy & Marketing | strategic-analysis-porter, competitor-intelligence, campaign-brief-writer |
+| Engineering | architecture-decision-writer, api-design-reviewer |
+| Cross-functional | decision-log, crisis-communication, policy-document-writer |
+
+### Deep Research shortcut
+
+Use [`templates/deep-research-prompt.md`](./templates/deep-research-prompt.md) with ChatGPT Deep Research, Gemini, or Perplexity Pro to generate the domain knowledge for any skill enrichment. The 6-section output maps directly into the SKILL.md and companion files.
+
+## Install / Update
+
+```bash
+# New install
+bash ./START-HERE.sh
+
+# Update existing
+bash ./UPDATE.sh
+
+# Validate
+node scripts/validate-pack.mjs
+```
+
+Windows users: double-click `START-HERE-WINDOWS.cmd` or `UPDATE-WINDOWS.cmd`.
+
+## Full changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the complete list of changes.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexkit",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "private": true,
   "repository": {
     "type": "git",