https://github.com/pitimon/8-habit-ai-dev

Stop vibe coding — 13 skills, 7 steps, 8 habits. Structured AI-assisted development powered by Covey's proven principles.
https://github.com/pitimon/8-habit-ai-dev

ai-development anti-vibe-coding best-practices claude-code claude-code-plugin code-review covey-habits cross-verification developer-tools productivity software-engineering tdd whole-person workflow

Last synced: 7 days ago
JSON representation

Stop vibe coding — 13 skills, 7 steps, 8 habits. Structured AI-assisted development powered by Covey's proven principles.

Host: GitHub
URL: https://github.com/pitimon/8-habit-ai-dev
Owner: pitimon
License: mit
Created: 2026-03-21T22:21:32.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-06-06T01:00:17.000Z (10 days ago)
Last Synced: 2026-06-06T02:23:54.259Z (10 days ago)
Topics: ai-development, anti-vibe-coding, best-practices, claude-code, claude-code-plugin, code-review, covey-habits, cross-verification, developer-tools, productivity, software-engineering, tdd, whole-person, workflow
Language: Shell
Size: 1.45 MB
Stars: 3
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md

Awesome Lists containing this project

README

# 8 Habits of Effective AI-Assisted Development

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-7C3AED)](https://github.com/pitimon/8-habit-ai-dev)
[![Skills](https://img.shields.io/badge/Skills-24-blue)]()
[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-ready-green)]()
[![Habits](https://img.shields.io/badge/Habits-8-orange)]()
[![Version](https://img.shields.io/badge/Version-2.21.18-brightgreen)](https://github.com/pitimon/8-habit-ai-dev/releases/tag/v2.21.18)
[![Wiki](https://img.shields.io/badge/docs-Wiki-informational)](https://github.com/pitimon/8-habit-ai-dev/wiki)

📖 **Full documentation**: **[Wiki](https://github.com/pitimon/8-habit-ai-dev/wiki)** — deep-dive guides per step, [FAQ](https://github.com/pitimon/8-habit-ai-dev/wiki/FAQ), [Troubleshooting](https://github.com/pitimon/8-habit-ai-dev/wiki/Troubleshooting), and the [8 Habits Reference](https://github.com/pitimon/8-habit-ai-dev/wiki/Habits-Reference).

> **"ทำเสร็จ ≠ ทำดี"** — Shipping code is not the same as shipping _good_ code.
>
> AI coding tools are powerful — but "build me X" without requirements, review, or staging creates fast, fragile code. This plugin adds the discipline AI lacks: **24 skills** across a **7-step workflow**, grounded in **Covey's 8 Habits** of effective development.

---

## Table of Contents

**Get Started**

- [The Problem](#the-problem) — Why this exists
- [Quick Start](#quick-start) — Install in 3 steps, verify in 1
- [Not using Claude Code?](AGENTS.md) — Entry point for Codex, Cursor, Windsurf, Aider, etc.

**The Framework**

- [Design Principle](#design-principle) — Thin harness, fat skills
- [7-Step Workflow](#the-7-step-workflow) — Visual pipeline from research to monitoring
- [Skills Reference](#skills-reference) — All 24 skills with habit mappings
- [Use Cases](#use-cases-which-skill-when) — Common scenarios and recommended paths
- [The 8 Habits](#the-8-habits) — Principles behind the workflow
- [Maturity Model](#the-maturity-model) — Dependence to Significance

**Deep Dives**

- [Cross-Verification](#cross-verification) — 17-question checklist + scoring
- [Whole Person Assessment](#whole-person-assessment) — Body/Mind/Heart/Spirit + worked example
- [Agents](#agents) — Read-only reviewers that analyze your work
- [Architecture](#architecture) — File tree + design decisions
- [Companion Plugins](#companion-plugins) — Working with `claude-governance` + `devsecops-ai-team`

**Reference**

- [What's New](#whats-new-in-v22112) — Version history
- [Not a Checklist](#not-a-checklist) — Principles, not gates
- [Origin](#origin) — Where these habits come from
- [Limitations](https://github.com/pitimon/8-habit-ai-dev/wiki/Limitations) — Runtime boundaries and evidence expectations
- [FAQ](#faq) — Common questions answered
- [Glossary](#glossary) — Key terms defined
- [Alternative Setup](#alternative-setup-without-plugin) | [Contributing](#contributing) | [License](#license)

---

## The Problem

AI coding tools (Claude Code, Cursor, Copilot, Codex) are powerful — but they amplify whatever process you bring to them. No process? You get fast, fragile code that works in demo but breaks in production.

The 7 most common mistakes:

1. **No requirements** — jumping straight to "build me X"
2. **No design** — letting AI decide architecture
3. **No task breakdown** — one giant prompt for everything
4. **No context** — AI doesn't know your codebase
5. **No review** — shipping AI output without reading it
6. **No staging** — deploying directly to production
7. **No monitoring** — "it works on my machine" mindset

This plugin provides a **skill for each step** — not as a gate, but as a habit.

---

## Design Principle

We follow the **"Thin Harness, Fat Skills"** pattern — the session hook is bounded (≤300 tokens, enforced in [`hooks/session-start.sh`](hooks/session-start.sh) and documented in `CLAUDE.md`), and the intelligence lives in on-demand markdown skills loaded when you invoke them. The harness gets out of the way; the skills do the work.

The same principle is documented independently by Garry Tan (President & CEO, Y Combinator) in his 2026 essay [_"Thin Harness, Fat Skills"_](https://github.com/garrytan/gbrain/blob/master/docs/ethos/THIN_HARNESS_FAT_SKILLS.md) and shipped in [gbrain](https://github.com/garrytan/gbrain). We arrived at it from workflow discipline; he arrived at it from building a brain — same conclusion.

The same shift is happening industry-wide under the name **Spec-Driven Development (SDD)**: after "vibe coding" entered the vocabulary in early 2025, tools like GitHub spec-kit, AWS Kiro, and Tessl emerged to generate code from specs. Those are spec-first _tooling_ — this plugin is spec-first _discipline_: tool-agnostic guidance that helps any of them (or none of them) produce better specs in the first place. It adds no enforcement and spawns no role-agents — that is the companion [`claude-governance`](https://github.com/pitimon/claude-governance). We arrived here from workflow discipline; they arrived from building codegen tools — same discipline layer, different delivery.

---

## Quick Start

**Install for Claude Code:**

```bash
claude plugin marketplace add pitimon/8-habit-ai-dev
claude plugin install 8-habit-ai-dev@pitimon-8-habit-ai-dev
```

**Install for Codex:**

```bash
codex plugin marketplace add pitimon/8-habit-ai-dev
codex plugin add 8-habit-ai-dev@pitimon-8-habit-ai-dev
```

**Use in Claude Code** (restart Claude Code, then invoke a skill by slash command):

```
/requirements # Before you build anything
/review-ai # Before you commit anything
/cross-verify # Before you ship anything
/whole-person-check # Assess Body/Mind/Heart/Spirit balance
```

**Use in Codex** (restart Codex after installing; plugin skills are not top-level `/skill` slash commands):

```text
/skills
```

Pick `requirements`, `review-ai`, `cross-verify`, or another installed skill from the selector. You can also mention the skill explicitly in your prompt:

```text
$cross-verify ตรวจแผนนี้ก่อน commit
```

or use plain intent:

```text
Use the cross-verify skill to check this release plan.
```

**Verify Claude Code installation**: After restarting, you should see `## 8-Habit AI Dev Active` in the session banner with the 7-step workflow reminder. For Codex, run `codex plugin list` and confirm `8-habit-ai-dev@pitimon-8-habit-ai-dev` is installed.

**New to the plugin?** Start with `/workflow` for a guided walkthrough, or see [Use Cases](#use-cases-which-skill-when) to find the right skill for your situation.

Two commands to install per platform. Claude Code also loads a session reminder; both platforms make 24 skills available. For exact runtime boundaries, see the [runtime compatibility matrix](docs/compatibility-matrix.md), [Codex integration guide](docs/codex-integration.md), and wiki [Limitations](https://github.com/pitimon/8-habit-ai-dev/wiki/Limitations): Codex gets native packaging, the same markdown skills, and a narrow `SessionStart` JSON adapter if the host invokes the hook; it does not get Claude hook feature parity or runtime enforcement.

### Keeping the plugin updated

This plugin is maintained through regular releases. Check the [GitHub Releases](https://github.com/pitimon/8-habit-ai-dev/releases), the [wiki changelog](https://github.com/pitimon/8-habit-ai-dev/wiki/Changelog), or the "What's New" sections below to see recent changes.

**Claude Code:**

```bash
claude plugin update 8-habit-ai-dev@pitimon-8-habit-ai-dev
```

Restart Claude Code after updating so hook and skill changes are loaded.

**Codex:**

Codex currently has no `codex plugin update` command. Refresh the Git marketplace snapshot, then reinstall the plugin from that refreshed snapshot:

```bash
codex plugin marketplace upgrade pitimon-8-habit-ai-dev
codex plugin list
codex plugin remove 8-habit-ai-dev@pitimon-8-habit-ai-dev
codex plugin add 8-habit-ai-dev@pitimon-8-habit-ai-dev
codex plugin list
```

Use `codex plugin marketplace list` if you need to confirm the configured marketplace name.

---

## The 7-Step Workflow

Each step maps to one of Covey's 8 Habits — the habit explains _why_ the step matters.

```
Step 0 Step 1 Step 2 Step 3
/research ───→ /requirements ─→ /design ────→ /breakdown
H5:Understand H2:End in Mind H8:Find Voice H3:First Things

Step 4 Step 5 Step 6 Step 7
/build-brief ─→ /review-ai ───→ /deploy-guide → /monitor-setup
H5:Understand H4:Win-Win H1:Proactive H7:Sharpen Saw
```

You don't need all steps every time. Start with **`requirements` before building** and **`review-ai` before committing** — those two alone eliminate most Vibe Coding problems. In Claude Code that usually means `/requirements` and `/review-ai`; in Codex, select them through `/skills`, mention `$requirements` / `$review-ai`, or ask in natural language.

---

## Skills Reference

Skill names below use Claude Code slash notation because that is the shortest label for the skill corpus. In Codex, these are installed skills, not plugin-provided top-level slash commands. Use `/skills`, mention the skill such as `$cross-verify`, or ask Codex to use the named skill.

### Workflow Skills (Steps 0-7)

| Skill | Step | Habit | Purpose |
| ---------------- | ---- | ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `/research` | 0 | H5: Seek First to Understand | Investigate with depth levels (Quick/Standard/Deep), modes (General/Compare/Audit), and source verification |
| `/requirements` | 1 | H2: Begin with End in Mind | Draft PRD — what, why, who, scope, success criteria |
| `/design` | 2 | H8: Find Your Voice | Surface architecture decisions for **human** judgment |
| `/breakdown` | 3 | H3: Put First Things First | Decompose into atomic tasks, prioritize by importance |
| `/build-brief` | 4 | H5: Seek First to Understand | Problem statement gate + context brief before implementing |
| `/review-ai` | 5 | H4: Think Win-Win | 4-level verdict (PASS/CONCERNS/REWORK/FAIL) + dimension balance |
| `/deploy-guide` | 6 | H1: Be Proactive | Staging-first deployment with rollback, plus provider reconciliation gates for production canaries |
| `/monitor-setup` | 7 | H7: Sharpen the Saw | Set up health checks, alerting, error tracking |

### Assessment Skills (Use Anytime)

| Skill | Habit | Purpose |
| --------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/cross-verify` | H1-H8 | 17-question checklist + dimension summary (Body/Mind/Heart/Spirit) |
| `/consistency-check` | H5 + H1 | Cross-artifact analyzer over persisted PRD↔design↔tasks, plus incident/config hotfix mode for symptom↔evidence↔root-cause↔fix↔verification drift (v2.20.1) |
| `/operational-state` | H1 + H5 + H8 | **Operational finding classifier** — choose Watch, Fix Candidate, Active Incident, Resolved, Handoff, Known Accepted Issue, False Positive, or Self-Resolved before action. Maps evidence, allowed/prohibited actions, approval gates, artifacts, escalation criteria, and closure criteria. Read-only guidance; no runtime state engine or production mutation. |
| `/whole-person-check` | H8: Find Your Voice | 4-dimension assessment (1-5 scale) with AI Blind Spot detection |
| `/security-check` | H1: Be Proactive | Focused OWASP security lens — secrets, injection, auth, deps |
| `/reflect` | H7: Sharpen the Saw | 5-question micro-retrospective (5 min max) with action tracking |
| `/workflow` | All | Guided 7-step walkthrough — invoke or skip each step |
| `/calibrate` | H8: Find Your Voice | Self-assessment (5-7 questions) → writes `~/.claude/habit-profile.md` so other skills adapt verbosity to your maturity level |
| `/using-8-habits` | H5 + H8 | Onboarding meta-skill — all 24 skills + decision tree for "which skill next?" |
| `/eu-ai-act-check` | H1 + H8 (Spirit) | Redirect stub — migrated to [`pitimon/claude-governance`](https://github.com/pitimon/claude-governance) v3.1.0+ on 2026-05-02 (ADR-012). Install that plugin for the canonical 9-obligation checklist. |
| `/ai-dev-log` | H4 + H1 | Generate AI-assisted dev log from git history for audit trail |
| `/save-spec` | H8 + H2 | **Deployment-mode helper (not a workflow step)** — scaffold a project-root `SPEC.md` digest when the repo fits the project-orientation hub mode. Generator-only Phase 1 (v2.16.0); refuses to overwrite. **Skip if you already have a memory-MCP + short `CLAUDE.md`** (v2.16.4 — see `/save-spec` "When to Skip" for details) |
| `/diagnose` | H1 + H5 | **Active bug investigation** — 6-phase methodology (feedback-loop → reproduce → hypothesise → instrument → fix-with-regression-test → cleanup). Closes the gap between research (too broad) and post-mortem (too late). Phase 1 (feedback-loop-first) enforced before hypothesis generation. Hands off to post-mortem once fix lands. Adapt-with-attribution from [mattpocock/skills](https://github.com/mattpocock/skills) SHA `b8be62ff` (v2.18.0, ADR-015 — n=1 friction-driven adoption) |
| `/post-mortem` | H4 + H7 | **Engineering RCA writeup** — canonical record of a fixed bug (root cause, mechanism, fix, validation, how it slipped through). Refuses to draft without 4 inputs (reliable repro, known cause, identified fix, validated outcome). Inspired by [9arm-skills](https://github.com/thananon/9arm-skills) (v2.17.0) |
| `/scrutinize` | H5 + H8 | **Outsider-perspective review** — questions whether the change should exist at all (Step 1) before line-by-line review. Pairs with review-ai (scope-question vs diff-local). 4-step workflow: Intent → Trace → Verify → Report. Inspired by [9arm-skills](https://github.com/thananon/9arm-skills) (v2.17.0) |
| `/management-talk` | H4 + H6 | **Channel-aware audience reshape** — engineer-to-engineer content → leadership channel (JIRA / Slack / standup / email / meeting). Strips function/file/SHA but keeps JIRA keys, PR numbers, workload names. Inspired by [9arm-skills](https://github.com/thananon/9arm-skills) (v2.17.0) |

---

## Use Cases: Which Skill When?

Start from **your situation**, not the skill name.

| I want to... | Start with | Then | Habit |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------- |
| Build a new feature from scratch | `/requirements` | `/design` → `/breakdown` | H2: Define done first |
| Review code before committing | `/review-ai` | `/security-check` if needed | H4: Never skip review |
| Understand an unfamiliar codebase | `/research` | `/build-brief` | H5: Read before writing |
| Deploy / provider canary | `/deploy-guide` | `/monitor-setup` | H1: Stage, rollback, reconcile |
| Assess overall project health | `/cross-verify` | `/whole-person-check` | All 8 habits |
| Classify an operational finding | `/operational-state` | `/deploy-guide` or `/post-mortem` | H1 + H5 + H8 |
| Fix a production bug | `/build-brief` | Reproduce first | H5: Understand first |
| Something feels off about a plan | `/cross-verify` | Check dimension scores | H1-H8 |
| Learn the full workflow | `/workflow` | (guided walkthrough) | All |
| Survive `/clear` and `/compact` | See [`guides/spec-digest-pattern.md`](guides/spec-digest-pattern.md) (project-orientation hub) or [`current-state.md`](guides/persistence-convention.md#current-state-file-optional-user-owned) (feature-spec mode) | Adopt one based on repo archetype | H5: Understand first |

### Recommended Paths

**Minimum Viable Discipline** — `/requirements` before building + `/review-ai` before committing. Two skills, biggest impact.

**Full Workflow** — `/research` through `/monitor-setup` via `/workflow`. For new features or greenfield projects.

**Quality Gate** — `/cross-verify` + `/whole-person-check`. For pre-PR or pre-release assessment.

For the full 15-situation map, see [`guides/situation-map.md`](guides/situation-map.md).

---

## The 8 Habits

Based on Stephen Covey's _The 7 Habits of Highly Effective People_ + Habit 8 (_The 8th Habit: From Effectiveness to Greatness_), adapted for AI-assisted development from real experience building a production system over 910 man-day-equivalents.

### Private Victory (Self-Management)

| Habit | Principle | In Practice |
| ----------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------- |
| **H1**: [Be Proactive](habits/h1-be-proactive.md) | Act on what you can control | Trace all callers of a bug fix, handle edge cases, update docs _during_ implementation |
| **H2**: [Begin with End in Mind](habits/h2-begin-with-end.md) | Define done before starting | Write success criteria and test plans _before_ the first prompt |
| **H3**: [Put First Things First](habits/h3-first-things-first.md) | Important over interesting | Tests and CI gates prevent future crises — don't skip them for speed |

### Public Victory (Collaboration)

| Habit | Principle | In Practice |
| ----------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| **H4**: [Think Win-Win](habits/h4-win-win.md) | Every interaction is a deposit | Error messages that help, issue closures with rationale, actionable review feedback |
| **H5**: [Seek First to Understand](habits/h5-understand-first.md) | Read before you write | Understand existing code and patterns before proposing changes |
| **H6**: [Synergize](habits/h6-synergize.md) | Together > apart | Human judgment + AI execution. Parallel agents for independent tasks |

### Renewal & Significance

| Habit | Principle | In Practice |
| --------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------- |
| **H7**: [Sharpen the Saw](habits/h7-sharpen-saw.md) | Invest in capability | Monitor production, track tech debt, automate what you learned |
| **H8**: [Find Your Voice](habits/h8-find-voice.md) | From effective to significant | Understand _why_ before implementing. Share patterns. Empower others |

### The Maturity Model

```
Dependence → Independence → Interdependence → Significance
```

| Stage | Mindset | AI Relationship |
| --------------- | -------------------- | --------------------------------------- |
| Dependence | "AI writes my code" | Blind acceptance, no review |
| Independence | "I use AI as a tool" | Selective adoption, human judgment |
| Interdependence | "We build together" | Complementary strengths, shared process |
| Significance | "We empower others" | Publishing patterns, raising the bar |

---

## Cross-Verification

The `/cross-verify` skill runs **17 questions** across all 8 habits, with **dimension mapping** (Body/Mind/Heart/Spirit) and **scoring bands**.

| Category | Questions | Dimensions | Habits |
| --------------- | ----------- | ------------ | ----------------------------------------------- |
| Private Victory | 8 questions | Body, Mind | H1 (scope), H2 (criteria), H3 (priority) |
| Public Victory | 6 questions | Mind, Heart | H4 (feedback), H5 (understanding), H6 (synergy) |
| Renewal | 3 questions | Body, Spirit | H7 (learning), H8 (meaning) |

**Scoring Bands**: 15-17 (proceed) → 12-14 (address gaps) → 8-11 (revisit plan) → <8 (stop and rethink)

**Confidence Levels** _(v1.9.0)_: For high-stakes reviews, mark each Pass as ✓V (Verified), ✓I (Inferred), or ✓U (Unverified) — inspired by [Feynman's](https://github.com/getcompanion-ai/feynman) honest uncertainty principle.

**Domain Packs**: Optional question sets for [API](guides/cross-verify-packs/api.md), [Frontend](guides/cross-verify-packs/frontend.md), [Infrastructure](guides/cross-verify-packs/infra.md), [AI/ML](guides/cross-verify-packs/ai-ml.md), and [Mobile](guides/cross-verify-packs/mobile.md) work.

Full checklist: [guides/cross-verification.md](guides/cross-verification.md)

---

## Whole Person Assessment

The `/whole-person-check` skill evaluates work across Covey's 4 dimensions — the plugin's **unique differentiator**. No other engineering tool covers all four.

| Dimension | What It Measures | AI Strength |
| ----------------------- | ------------------------------------------- | ------------------- |
| **Body** (Discipline) | CI, tests, monitoring, quality gates | Strong — AI excels |
| **Mind** (Vision) | Architecture, ADRs, roadmap, tech debt | Strong — AI excels |
| **Heart** (Passion) | Craft quality, empathetic errors, UX, DX | Weak — needs humans |
| **Spirit** (Conscience) | Security-first, ethics, compliance, sharing | Weak — needs humans |

AI-assisted development systematically neglects Heart and Spirit. This assessment makes the gap visible so teams can compensate.

### Worked Example: A REST API Feature

After building a user authentication API, `/whole-person-check` might produce:

| Dimension | Score | Finding |
| --------- | ----- | ----------------------------------------------------------- |
| Body | 4/5 | CI green, 85% coverage, but no load test |
| Mind | 5/5 | ADR documented, JWT vs session decision recorded |
| Heart | 2/5 | Error messages return raw 500s, no onboarding guide |
| Spirit | 3/5 | Input validation present, but no rate limiting or audit log |

**AI Blind Spot visible**: Body and Mind scored high (AI's strength). Heart and Spirit scored low (needs human attention).

**Action**: Before shipping, add user-friendly error messages (Heart) and rate limiting with audit logging (Spirit). These are the gaps AI won't catch on its own.

### Maturity Rubrics

3 levels per dimension (Reactive → Proactive → Significant): [guides/whole-person-rubrics.md](guides/whole-person-rubrics.md)

### Plugin's Own Progression

```
v1.2.0 ████████████░░░░░░░░ 3.0 (honest reassessment after inflated 4.5)
v1.9.0 ██████████████████░░ 4.5 (evidence grounding + integrity)
v2.0.0 ██████████████████░░ 4.625 (orchestration + meta-system)
v2.1.0 ███████████████████░ 4.75 (verification agent + research rigor)
v2.2.0 ████████████████████ 5.0 (content validation + fitness functions)
```

Full self-assessment: [SELF-CHECK.md](SELF-CHECK.md)

---

## Agents

The plugin includes two specialized agents — **read-only reviewers** that analyze without modifying your code.

### 8-habit-reviewer

Deep cross-verification reviewer. Evaluates plans, implementations, or PRs against all 8 habits.

- **When it runs**: Invoked by `/cross-verify` or manually via the Agent tool
- **What it produces**: Score out of 17, dimension summary, failed items with `file:line` evidence
- **Tools**: Read, Glob, Grep (read-only)

### research-verifier

Source verification agent _(v2.1.0)_. Validates every citation in a research brief.

- **When it runs**: Automatically during `/research` Deep mode
- **What it produces**: Verification report — Verified / Dead / Not Found / Redirected per source
- **Tools**: Read, Glob, Grep, WebFetch (read-only)
- **Principle**: Feynman standard — _"The first principle is that you must not fool yourself"_

Both Claude Code agent definitions use the `opus` model because they run high-stakes review and citation-integrity gates. This model selection is a Claude Code agent surface; Codex still consumes the shared markdown skills and does not gain Claude subagent model parity from this setting.

---

## Architecture

```
8-habit-ai-dev/
├── .claude-plugin/
│ ├── plugin.json # Plugin metadata (v2.15.0)
│ └── marketplace.json # Marketplace listing
├── .codex-plugin/
│ └── plugin.json # Native Codex plugin metadata (v2.19.0)
├── .agents/plugins/
│ └── marketplace.json # Native Codex marketplace listing
├── skills/ # 24 skills (8 workflow + 16 standalone)
│ ├── research/SKILL.md # Step 0 → H5 (depth levels + modes)
│ ├── requirements/SKILL.md # Step 1 → H2
│ ├── design/SKILL.md # Step 2 → H8
│ ├── breakdown/SKILL.md # Step 3 → H3 (orchestration classification)
│ ├── build-brief/SKILL.md # Step 4 → H5 (context boundaries)
│ ├── review-ai/SKILL.md # Step 5 → H4 (4-level verdict)
│ ├── deploy-guide/SKILL.md # Step 6 → H1 (staging, rollback, reconciliation)
│ ├── monitor-setup/SKILL.md # Step 7 → H7
│ ├── cross-verify/SKILL.md # All habits (17Q + dimension summary)
│ ├── consistency-check/SKILL.md # H5+H1: spec + incident/config consistency (v2.20.1)
│ ├── operational-state/SKILL.md # H1+H5+H8: operational state classifier (v2.20.0)
│ ├── whole-person-check/SKILL.md # H8: Body/Mind/Heart/Spirit
│ ├── security-check/SKILL.md # H1: OWASP security lens
│ ├── reflect/SKILL.md # H7: micro-retrospective + lesson persistence
│ ├── calibrate/SKILL.md # H8: maturity self-assessment → habit-profile.md
│ ├── using-8-habits/SKILL.md # H5+H8: onboarding + smart-routing mode (v2.14.0)
│ ├── eu-ai-act-check/SKILL.md # H1+H8: EU AI Act 9-obligation checklist
│ ├── ai-dev-log/SKILL.md # H4+H1: AI dev log from git history (Art. 11)
│ └── workflow/SKILL.md # Guided 7-step walkthrough
├── agents/
│ ├── 8-habit-reviewer.md # Deep cross-verification agent
│ └── research-verifier.md # Source verification agent (v2.1.0)
├── hooks/
│ ├── hooks.json # SessionStart hook registration
│ └── session-start.sh # Workflow reminder + progress indicators
├── habits/ # Reference content (loaded on-demand)
│ ├── h1-be-proactive.md # through h8-find-voice.md
│ └── ... # (8 files, one per habit)
├── guides/
│ ├── cross-verification.md # 17-point checklist detail
│ ├── whole-person-rubrics.md # 4-dimension maturity rubrics
│ ├── integrity-principles.md # 13 AI Integrity Commandments
│ ├── quick-reference.md # 19 prioritized rules (scannable)
│ ├── situation-map.md # 15 situations → right habit/skill
│ ├── orchestration-patterns.md # Multi-agent orchestration (v2.0.0)
│ ├── templates/ # Output templates
│ │ ├── prd-template.md # For /requirements
│ │ ├── adr-template.md # For /design
│ │ ├── task-list-template.md # For /breakdown
│ │ ├── review-report-template.md # For /review-ai
│ │ └── research-brief-template.md # For /research (v2.1.0)
│ └── cross-verify-packs/ # Domain question packs (5 questions each)
│ ├── api.md # API development
│ ├── frontend.md # Frontend/UI
│ ├── infra.md # Infrastructure
│ ├── ai-ml.md # AI/ML systems
│ └── mobile.md # Mobile apps
├── tests/
│ ├── validate-structure.sh # Structure validation (13 checks, pure bash)
│ └── validate-content.sh # Content validation + fitness functions (v2.2.0)
├── docs/
│ ├── INTEGRATION.md # Canonical plugin-integration guide (companion plugins)
│ └── adr/ # Architecture Decision Records (ADR-001 .. ADR-013)
│ ├── ADR-001-orchestration-patterns.md
│ ├── ADR-002-research-modes.md
│ └── ADR-003-content-validation.md
├── rules/
│ └── effective-development.md # Auto-loaded Claude Code rules
├── CLAUDE.md # Plugin development guide
├── CONTRIBUTING.md # Skill authoring guide
├── SELF-CHECK.md # Meta cross-verification
└── README.md # This file
```

**Design decisions:**

- **Skills are empowering, not restrictive** — reminders and tools, not blocking gates
- **Habit content loaded on-demand** — skills reference `habits/*.md` only when invoked, keeping session context lean
- **Session hook under 300 tokens** — light reminder with progress indicators, not a wall of text
- **Handoff contracts** — each skill declares what it expects from its predecessor and produces for its successor
- **Definition of Done** — every skill has 3-5 verifiable checkbox items
- **When to Skip** — honest conditions prevent compliance theater (H8: contribution over compliance)
- **Output templates** — structured formats for PRD, ADR, task list, review report, research brief
- **Dimension mapping** — all 17 cross-verify questions tagged with Body/Mind/Heart/Spirit
- **Zero dependencies** — pure markdown + bash. No npm, no pip, no runtime requirements

---

## Companion Plugins

`8-habit-ai-dev` works **standalone** — no hard dependency. For higher-assurance projects, it composes with two companion plugins (also by pitimon):

| Plugin | Layer | When to add |
| ------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
| `claude-governance` | Policy / Enforcement (fitness functions, ADRs, compliance) | When you need durable policy + audit trail |
| `devsecops-ai-team` | Operational tooling (SAST/DAST/SCA/Container/IaC + SBOM/AIBOM/VEX) | When you need automated scans or regulator evidence |

**Single source of truth for integration:** see [`docs/INTEGRATION.md`](docs/INTEGRATION.md) — covers layer map, choosing-your-stack matrix, integration points, Three Loops asymmetry, EU AI Act scope split, and suggested integrated flow.

Tested against `claude-governance` 3.3.0 and `devsecops-ai-team` 10.12.0+.

> **Naming note (v2.16.5)**: in `devsecops-ai-team` v10.12.0, the `/workflow` skill was renamed to `/security-workflow` to resolve a cross-plugin naming collision with this plugin's `/workflow` (the 7-step Covey practice). If you have both plugins installed, type `/workflow` for the 7-step walkthrough or `/security-workflow` for devsecops's scan orchestration. Legacy `/workflow` in devsecops continues as a deprecation stub through v10.x (removed in v11.0.0). See devsecops ADR-014.

---

## What's New in v2.21.18

**Theme: Epistemic footer and Shadow Self-Check**

v2.21.18 tightens evidence labeling and self-critique in the verification path.

- **High-stakes confidence footer** — `/cross-verify` now requires the `V/I/U` confidence footer for high-stakes reviews and records open unknowns explicitly.
- **Shadow Self-Check** — `/cross-verify` now asks for the strongest counter-argument to its own verdict and who is harmed if the verdict is wrong before recommending action.
- **Research template alignment** — research briefs gain a mandatory Confidence & Open Unknowns block, and integrity principle #7 now uses the shared `V/I/U` vocabulary.
- **Boundary retained** — markdown guidance only; no runtime enforcement, hooks, orchestration engine, policy gate, or duplicated `/scrutinize` gate.

## What's New in v2.21.17

**Theme: Software ecology guardrail**

v2.21.17 adds a lightweight guardrail for AI acceleration effects around the code, not just inside the diff.

- **Research scan** — `/research` now asks what AI acceleration may amplify: review load, validation cost, handoff drift, internal contracts, and human attention.
- **Design label** — `/design` uses `software ecology impact` only when acceleration changes boundaries, API contracts, validation, release, or ownership.
- **Review signals** — `/review-ai` now checks for review burden, validator brittleness, generated-content noise, and contract drift.
- **Boundary retained** — markdown guidance only; no runtime enforcement, hooks, orchestration engine, policy gate, or hook parity claim.

## What's New in v2.21.16

**Theme: Requirements intake mode split**

v2.21.16 extends the `/design` claim-discipline work upstream into `/requirements`.

- **Existing-system mode** — requirements for real systems should cite source evidence where available and keep unverifiable statements visible as assumptions or questions.
- **Idea-mode** — raw ideas preserve intent and label assumptions before turning them into constraints.
- **Mixed work guard** — confirmed system facts stay separate from proposed behavior so `/design` does not inherit speculative claims as architecture truth.
- **Validator pins** — content validation now checks the new mode names and evidence/assumption discipline.

## What's New in v2.21.15

**Theme: SessionStart dead variable cleanup**

v2.21.15 removes two ShellCheck SC2034 dead variables from the SessionStart hook without changing rendered reminder behavior.

- **Dead code removed** — `BRIEF` and `PROGRESS` assignments are gone from `hooks/session-start.sh`.
- **Behavior preserved** — workflow artifact markers still render through the existing inline `${PRD:+ ✓}` / `${ADR:+ ✓}` / `${TASKS:+ ✓}` expressions.
- **Regression coverage retained** — `tests/test-verbosity-hook.sh` continues to cover root fallback, Codex JSON output, version rendering, and workflow hints.

## What's New in v2.21.14

**Theme: Codex SessionStart version fallback**

v2.21.14 completes the SessionStart root fallback by making the banner version work in Codex package roots that expose `.codex-plugin/plugin.json` but not `.claude-plugin/plugin.json`.

- **Version fallback** — `hooks/session-start.sh` now reads `.claude-plugin/plugin.json` first, then `.codex-plugin/plugin.json`.
- **No `vunknown`** — installed Codex cache smoke now renders `8-Habit AI Dev Active (v2.21.14)` instead of `vunknown`.
- **Regression coverage** — `tests/test-verbosity-hook.sh` now builds a fake Codex-only package root and executes the registered SessionStart command against it.

## What's New in v2.21.13

**Theme: SessionStart root fallback**

v2.21.13 fixes a startup-path regression where a host invoking the package SessionStart hook without `CLAUDE_PLUGIN_ROOT` could expand the command to `/hooks/session-start.sh` and exit 127.

- **Root fallback** — `hooks/hooks.json` now resolves the package root from `CLAUDE_PLUGIN_ROOT`, then `CODEX_MANAGED_PACKAGE_ROOT`, then the current package directory.
- **Behavior preserved** — the existing markdown reminder and Codex JSON adapter are unchanged; this is command-path compatibility only.
- **Regression coverage** — `tests/test-verbosity-hook.sh` now executes the registered hook command with `CLAUDE_PLUGIN_ROOT` unset.

## What's New in v2.21.12

**Theme: QA polish and design wiki example**

v2.21.12 finishes the post-release QA polish from the `/design` claim-discipline release.

- **Design walkthrough** — the Step 2 Design wiki page now includes a concrete claim-discipline example with pass level, claim labels, evidence strength, `Verify first: Yes/No`, question priority, and Mermaid traceability guidance.
- **Validator polish** — `/diagnose` and `/research` Definition of Done lists are compacted to remove existing validator warnings without changing their behavior.
- **Skill complexity polish** — `/ai-dev-log` now keeps script internals and report-template detail in `reference.md`, reducing the main skill body while preserving customization guidance.
- **Boundary held** — no new skill, runtime enforcement, hook behavior change, or semantic change to `/diagnose`, `/research`, or `/ai-dev-log`.

## What's New in v2.21.11

**Theme: Design architecture claim discipline**

v2.21.11 strengthens `/design` with portable architecture-review discipline adapted from `aetox-skills/senior-architect-agent`, while keeping this plugin markdown-only and cross-runtime for Claude Code and Codex.

- **Right-sized design passes** — `/design` now chooses `Scan`, `Focus`, or `Full` and promotes only when evidence, explicit user request, or the risk of staying smaller justifies more scope.
- **Claim traceability** — load-bearing architecture claims now carry labels, evidence strength, and `Verify first: Yes/No` so assumptions and proposals do not masquerade as confirmed system facts.
- **ADR support** — the ADR template adds optional Architecture Claims and Decisions Requiring Approval sections for handoff-ready architecture decisions.

## What's New in v2.21.10

**Theme: Linux Claude Code install compatibility**

v2.21.10 removes the root `plugin -> .` symlink from the published repo shape because Claude Code on Linux can fail during install while materializing that self-symlink.

- **Claude Code install fix** — replaces the root symlink with a real `plugin/` child directory so Claude Code no longer packages a self-referential root link.
- **Codex compatibility preserved** — `plugin/.codex-plugin/plugin.json` keeps the required child-source shape for Codex marketplace installs and ships a real `plugin/skills/` copy so installed caches contain the skills.
- **Validator coverage** — `tests/validate-structure.sh` now fails if `plugin` is a symlink, checks the child Codex manifest, and detects drift between the root skill corpus and the packaged child copy.

## What's New in v2.21.9

**Theme: Codex skill invocation guidance**

v2.21.9 clarifies how Codex users invoke this plugin's skills without assuming Claude Code slash-command parity.

- **Codex command UX** — README and [`docs/codex-integration.md`](docs/codex-integration.md) now show `/skills`, `$skill-name`, and natural-language examples for Codex.
- **Runtime boundary** — compatibility docs now record skill invocation UX as host-specific: Claude Code uses top-level slash notation, while Codex uses native skill selection and mentions.
- **No local prompt workaround** — docs explicitly avoid `~/.codex/prompts` as this plugin's distribution path because custom prompts are local-only and deprecated for reusable shared workflows.

## What's New in v2.21.8

**Theme: Opus reviewer agents**

v2.21.8 moves the two read-only Claude Code reviewer agents from Sonnet to Opus for stronger high-stakes review.

- **Reviewer model upgrade** — `agents/8-habit-reviewer.md` and `agents/research-verifier.md` now use `model: opus`.
- **Docs boundary** — README and compatibility docs clarify that this is a Claude Code agent-surface choice. Codex still consumes the shared markdown skills and does not receive Claude subagent model parity from this setting.
- **Validation** — existing agent validation already accepts `opus`; validators continue to verify the frontmatter model value.

## What's New in v2.21.7

**Theme: issue tracking and tracer-bullet planning**

v2.21.7 tightens the next-agent handoff path inspired by `mattpocock/skills`, while staying inside the markdown-only plugin boundary.

- **Issue tracking comments** — adds [`guides/templates/issue-tracking-comments.md`](guides/templates/issue-tracking-comments.md) with pickup, progress/blocker, and completion comment drafts for issue-based work.
- **Context-aware requirements** — `/requirements` now applies the interview protocol's glossary, ADR, scenario, and code-contradiction challenge gate when repo context files exist.
- **Vertical slices** — `/breakdown` now prefers backlog-bound tasks that deliver a thin, independently verifiable path instead of horizontal layer tickets.
- **TDD tracer bullets** — adds [`guides/tdd-tracer-bullet.md`](guides/tdd-tracer-bullet.md) and teaches `/build-brief` to load it for TDD, red-green-refactor, or test-first work.
- **Bundled maintenance** — includes the Codex update-flow clarification plus link-check exclusion hardening and Node 24-compatible `actions/checkout` v5 workflow updates.
- **Boundary** — markdown guidance only: no issue auto-mutation, no setup engine, no test runner, no runtime enforcement, and no dynamic orchestration.

## What's New in v2.21.6

**Theme: Codex SessionStart JSON compatibility**

v2.21.6 fixes a Codex v0.137.0 startup compatibility bug where `hooks/session-start.sh` could emit raw markdown to a host expecting JSON.

- **Codex hook JSON** — `hooks/session-start.sh` now wraps the existing reminder in `hookSpecificOutput.additionalContext` when Codex runtime environment variables are present or `HABIT_HOOK_OUTPUT=codex-json` is set.
- **Claude/default behavior preserved** — default non-Codex runs still emit the markdown banner directly; `HABIT_HOOK_OUTPUT=markdown` can force markdown output for smoke tests or unusual parent environments.
- **Regression coverage** — `tests/test-verbosity-hook.sh` now verifies Codex JSON parses and contains `hookSpecificOutput.additionalContext`.
- **Boundary** — this is a narrow hook-output adapter, not runtime enforcement, dynamic orchestration, policy authorization, or Claude hook feature parity inside Codex.

## What's New in v2.21.5

**Theme: project context contract for glossary and issue-readiness awareness**

v2.21.5 adds a guide-first context layer inspired by `mattpocock/skills`, adapted to this plugin's markdown-only boundary.

- **Project context contract** — [`guides/project-context-contract.md`](guides/project-context-contract.md) defines optional repo-local files for glossary, issue tracker, triage labels, domain-doc routing, and ADR awareness.
- **Skill awareness** — `/requirements`, `/design`, `/breakdown`, `/build-brief`, `/diagnose`, and `/scrutinize` now read those context files when present instead of guessing project vocabulary or issue readiness.
- **Delegation readiness** — `/breakdown` and the AGENT-BRIEF template now distinguish `ready-for-agent`, `ready-for-human`, and `needs-info` before backlog-bound work is filed.
- **Boundary** — markdown guidance only: no setup engine, no automatic issue mutation, no runtime enforcement, and no Claude hook port to Codex.

## What's New in v2.21.4

**Theme: release decision gate**

v2.21.4 adds explicit release classification to prevent "every PR releases" and "version bumped but release not finished" drift.

- **Deploy-guide gate** — `/deploy-guide` now requires `Release now`, `Bundle later`, or `No release` before bumping plugin version files.
- **Contributor checklist** — `CONTRIBUTING.md` records the same decision categories before the release checklist.
- **Validator pin** — `tests/validate-content.sh` checks that the deploy-guide release gate keeps all three categories and the no-version-bump invariant.

## What's New in v2.21.3

**Theme: Codex project context files**

v2.21.3 ships concise repo-local context for Codex and other non-Claude agents.

- **Fast re-entry** — adds `SPEC.md` as a project digest and `DOMAIN.md` as the invariant/safety-boundary summary.
- **ADR discoverability** — adds `docs/adr/README.md` and ADR-025 to record why these context files exist.
- **Codex setup note** — adds `.codex/README.md` for repo-local Codex setup and the Claude-hook boundary.
- **LLM index** — updates `llms.txt` so remote agents can discover the new context files.

## What's New in v2.21.2

**Theme: Codex installed-cache validator context**

v2.21.2 fixes a false validation failure when `tests/validate-structure.sh` is run from Codex's installed plugin cache.

- **Installed-cache shape** — Check 28 now treats a missing `plugin` child source as expected only under `~/.codex/plugins/cache/...`, where Codex has already copied the plugin root.
- **Source/marketplace strictness preserved** — source and marketplace snapshots still require a real `plugin/` child source because `.agents/plugins/marketplace.json` points at `./plugin`.
- **Docs clarified** — `docs/codex-integration.md` and `docs/compatibility-matrix.md` now explain when to validate source/marketplace publishability versus installed-cache user artifacts.

## What's New in v2.21.1

**Theme: cross-agent evidence discipline**

v2.21.1 adds explicit user-facing boundaries and real-behavior proof expectations inspired by the Headroom architecture review, while keeping the plugin markdown-only and guidance-only.

- **Limitations page** — wiki documentation now states what the plugin helps with, what it does not enforce, and which evidence belongs in release/PR proof.
- **Runtime comparison matrix** — `docs/compatibility-matrix.md` now compares shared markdown skills, Claude Code packaging, Codex packaging, hooks, memory, enforcement, and release evidence across host platforms.
- **Real behavior proof** — `CONTRIBUTING.md` and the release checklist now require concrete validator/catalog/install evidence when user-facing surfaces change.
- **Validator coverage** — `tests/validate-structure.sh` now treats the wiki Limitations page as part of the required wiki skeleton.
- **Skill-effectiveness maintenance** — harvested one previously untallied lesson signal for `/whole-person-check` and aligned the report with the current 24-skill inventory.

## What's New in v2.21.0

**Theme: cross-agent discovery and portability contract**

v2.21.0 adds a conservative discovery/export layer inspired by Mercury Skills while preserving the plugin boundary: the same markdown skill corpus works in Claude Code and Codex, and host-side tooling should stay portable across macOS, Linux, and WSL.

- **Frontmatter contract** — `CONTRIBUTING.md`, `guides/skill-authoring.md`, and `docs/compatibility-matrix.md` now define required, optional, cross-agent, and Codex-ingestible `SKILL.md` fields.
- **Generated skill catalog** — `docs/data/skills.json` is generated from `skills/*/SKILL.md` by `scripts/generate-skill-catalog.js` for cross-agent discovery.
- **Freshness check** — `tests/validate-structure.sh` Check 30 verifies the generated catalog is current.
- **Handoff integrity** — `guides/structured-output-protocol.md` adds a compact handoff note pattern for state, decisions, assumptions, evidence, confidence, next skill, and rejection path.
- **AI-work health** — `/review-ai`, `/reflect`, and `guides/quick-reference.md` add observable loop/retry/compaction/audit-trail signals without adding runtime metering or enforcement.
- **Boundary** — markdown guidance and generated metadata only: no runtime dispatcher, no Claude-hook port to Codex, no budget enforcement, and no policy gate.

## What's New in v2.20.2

**Theme: production canary reconciliation gates** ([#250](https://github.com/pitimon/8-habit-ai-dev/issues/250))

Extends `/deploy-guide` with a production canary / capacity-change template for provider-managed infrastructure where a human can choose a canary but the cloud provider may mutate a different eligible resource.

- **Deploy type classifier** — adds `production canary / capacity change` for EKS nodegroups, ASGs, Kubernetes nodes, and similar provider-managed work.
- **Approval gates** — separates cordon, observation, drain, provider-side change, reconciliation, and postcheck gates.
- **Provider reconciliation** — compares planned target vs actual provider-selected target and checks desired/min/max, schedulable capacity, all nodes Ready, and no unintended `SchedulingDisabled` nodes.
- **Closure discipline** — distinguishes provider scale/update success from canary reconciliation success.
- **Evidence wording** — adds a production ops closure snippet for intended canary, provider-selected target, reconciliation state, mitigation readiness, and `/operational-state` handoff.

## What's New in v2.20.1

**Theme: incident/config consistency-lite for operational hotfix PRs** ([#253](https://github.com/pitimon/8-habit-ai-dev/issues/253))

Extends `/consistency-check` with a lightweight incident/config hotfix mode for cases that do not have persisted PRD/design/tasks artifacts. The mode checks that an operational PR or closure note does not hide drift between symptom, evidence, root cause, actual fix, deploy path, and live verification.

- **No new skill** — keeps the check inside `/consistency-check` to avoid operational skill sprawl after `/operational-state`.
- **Hotfix output table** — emits `symptom | evidence | root cause | fix | verification | drift`.
- **Overclaim guard** — flags PR/changelog text that says more than the live verification proves.
- **Operational state handoff** — unresolved adjacent state is classified or handed to `/operational-state` instead of being hidden.
- **Worked example** — adds a generic WorkerDown/Alertmanager-style alert/config hotfix example.

## What's New in v2.20.0

**Theme: operational state model for incident and daily-fix work** ([#251](https://github.com/pitimon/8-habit-ai-dev/issues/251))

Adds `/operational-state`, a read-only skill for classifying operational findings before acting or closing them. It keeps production users out of the false binary of "fix now" vs "done" by naming explicit states and evidence thresholds.

- **`/operational-state`** — classifies findings as `Watch`, `Fix Candidate`, `Active Incident`, `Resolved`, `Handoff`, `Known Accepted Issue`, `False Positive`, or `Self-Resolved`.
- **State-to-action mapping** — each state names required evidence, allowed/prohibited actions, approval gates, artifacts, escalation criteria, and closure criteria.
- **Operational guardrails** — "Running is not healthy", "recovered is not fixed", source-of-truth drift stays visible, and report hygiene is separated from production mutations.
- **Boundary** — markdown guidance only: no runtime state engine, policy enforcement, cloud execution, or automatic production writes.

## What's New in v2.19.2

**Theme: operational doctrine patch from open issues**

v2.19.2 tightens four existing skills for operational incidents without adding runtime automation or a new operational-state skill. It ships the low-risk doctrine from issues #252, #254, #255, and #256 while leaving the broader operational model issues for a separate design pass.

- **`/deploy-guide`** — adds a deploy-type classifier before rollout planning and clarifies that config/template changes with runtime impact still need deploy planning.
- **`/security-check`** — expands the trigger surface to alerting/email templates, SMTP, webhooks, container/orchestrator config, env interpolation, mounted config, rendered config, and source-of-truth drift.
- **`/reflect`** — keeps the six-question contract while splitting Q6 into `most_useful`, `least_or_confusing`, and `missed_skill` so missed-skill signals survive lesson consolidation.
- **`/management-talk`** — adds an operational incident closure example rendered as Slack, standup, email, and meeting talking points.

## What's New in v2.19.1

**Theme: Codex runtime compatibility contract** ([ADR-024](docs/adr/ADR-024-codex-runtime-adapter-boundary.md))

v2.19.0 made Codex installation native. v2.19.1 makes the runtime promise explicit: this plugin is complete as a cross-agent markdown workflow-discipline system, but it does not claim Claude runtime feature parity inside Codex.

- **Compatibility matrix** — [`docs/compatibility-matrix.md`](docs/compatibility-matrix.md) documents what works in Claude Code, Codex, and other markdown-capable agents.
- **Codex integration guide** — [`docs/codex-integration.md`](docs/codex-integration.md) gives the Codex install, verify, routing, and release-flow contract.
- **ADR-024** — defines the future adapter boundary: routing, validation, release reconciliation, and curated memory deposit are acceptable adapter responsibilities; policy enforcement, compliance execution, irreversible-action auth, and orchestration engines stay outside the markdown skill core.
- **Validator coverage** — `tests/validate-structure.sh` Check 29 pins the compatibility docs and entrypoint links so the boundary cannot silently drift.
- **Entrypoint sync** — README, `AGENTS.md`, and `llms.txt` now point Codex users to the same compatibility contract.

## What's New in v2.19.0

**Theme: native Codex plugin packaging** ([ADR-023](docs/adr/ADR-023-codex-native-packaging.md))

The same markdown-only workflow discipline now installs natively in Codex. This release adds Codex packaging without rewriting the skills or adding runtime enforcement.

- **Codex manifest** — `.codex-plugin/plugin.json` exposes the existing `skills/` directory with Codex interface metadata.
- **Codex marketplace** — `.agents/plugins/marketplace.json` lets users install from the Git repo with `codex plugin marketplace add pitimon/8-habit-ai-dev` then `codex plugin add 8-habit-ai-dev@pitimon-8-habit-ai-dev`. It points to the real `./plugin` child directory because Codex ignores root-path marketplace entries.
- **Codex ingestion compatibility** — `/ai-dev-log` and `/save-spec` now declare `disable-model-invocation: false`; ADR-014 already recorded the previous `true` flag as decorative for Claude plugin skills, while Codex rejects `true` during validation.
- **Validator coverage** — `tests/validate-structure.sh` now checks Codex packaging exists, keeps `.codex-plugin/plugin.json` version-aligned with the Claude package, and treats Codex packaging as consumer-doctrine for bump enforcement.
- **Version convention** — release version now lives in 6 files: Claude manifest, Claude marketplace, source Codex manifest, child Codex manifest, README, and SELF-CHECK.

## What's New in v2.18.9

**Theme: a copy-pasteable worked example for `/diagnose`'s independent-source check** ([guide](guides/independent-source-verification.md))

A craft follow-up to v2.18.8. The independent-source verification step shipped in v2.18.8 told the reader _what_ to do; v2.18.9 adds a worked one-liner showing _how_ — so a first-time `/diagnose` user internalizes the technique without leaving the skill.

- **`skills/diagnose` Phase 4** — gains a runnable example (`docker run ` vs `docker exec `, compare-and-flag-divergence) plus a one-line generalization (compile-from-source vs installed package; DB row vs API response): _read the claim twice from sources that can't share the same mistake, and only believe it when they agree._ Boundary-safe per [ADR-021](docs/adr/ADR-021-dynamic-workflow-positioning.md) — independence-of-source, not agent orchestration.
- **Consumer-doctrine bump** — `skills/` edit per [ADR-019](docs/adr/ADR-019-doctrine-only-scope-refinement.md); patch bump v2.18.8 → v2.18.9 atomic across 4 files.

For the v2.18.8 discipline this builds on, see [CHANGELOG.md](CHANGELOG.md). PR closes the `/whole-person-check` Heart-dimension follow-up.

## What's New in v2.18.6

**Theme: v2.18.5 fast-follow fix — body-measure `awk` made frontmatter-aware so ADRs and guides count correctly** ([skill](skills/requirements/SKILL.md), [test](tests/validate-content.sh))

QA on v2.18.5 (issue [#239](https://github.com/pitimon/8-habit-ai-dev/issues/239)) caught a correctness defect in the freshly-shipped step 4a body-measure command: `awk '/^---$/{c++; next} c>=2'` returned `0` for files without YAML frontmatter (ADRs, guides) — 2 of the 3 artifact types the same sub-step names. A contributor following 4a literally on an ADR precedent (the case study's own example) would measure `0` instead of ~150 → set the FR ceiling at `0 × 1.20 = 0`, defeating the calibration the sub-step exists to enforce.

- **Awk fix** — `skills/requirements/SKILL.md:80` now uses `awk 'NR==1 && $0=="---"{f=1; next} f && $0=="---"{f=0; next} !f'` which strips frontmatter only when the file actually starts with `---`. Verified: ADR-017 → 152, ADR-018 → 145, `cross-verification.md` → 95, `requirements/SKILL.md` → 131 (frontmatter correctly stripped, mid-body `---` thematic breaks correctly counted as body).
- **Regression test** — `tests/validate-content.sh` Check 22 closes the gap explicitly named in #239 (_"tests/\*\* was untouched, so no validator caught it"_): runs the prescribed awk against 4 representative files spanning all 3 artifact types and asserts body counts match expected; also grep-checks that SKILL.md carries the new variant and is free of the broken v2.18.5 form.
- **Template note** — `guides/templates/prd-template.md` clarifies that ADR/guide precedents have no frontmatter (body count = `wc -l`), only skills strip; cites #239 for the rationale.
- **Consumer-doctrine bump** — `skills/**` edit per [ADR-019](docs/adr/ADR-019-doctrine-only-scope-refinement.md); patch bump v2.18.5 → v2.18.6 atomic across 4 files; Check 27 passes.
- **Lesson** — prescribed commands embedded in skill prose are production guidance and need regression tests, the same way runtime code does. The plugin's "tests" surface is structural validators, not unit tests in the pytest sense; Check 22 establishes the precedent that future `awk`/`grep`/`jq` snippets in skill prose ship with a paired assertion.

PR closes [#239](https://github.com/pitimon/8-habit-ai-dev/issues/239).

## What's New in v2.18.5

**Theme: PRD calibration checkpoint — measure precedent before setting numeric ceilings on markdown artifacts** ([skill](skills/requirements/SKILL.md), [template](guides/templates/prd-template.md))

Adds a `4a. Calibrate numeric ceilings against precedent` step to `/requirements` Process. When an EARS criterion sets an upper bound on lines/words/characters of a markdown artifact (ADR, guide, skill), the skill now nudges the author to identify the closest precedent (`docs/adr/ADR-0*.md` for ADR ceilings, `guides/*.md` for guide ceilings, `skills/*/SKILL.md` for skill ceilings), measure the body excluding YAML frontmatter (`awk '/^---$/{c++; next} c>=2' | wc -l`), and set the ceiling at `precedent_max × 1.20` — because aspirational round numbers contaminate `/consistency-check` runs once the artifact lands at its actual required size.

- **Case study** — FR-007 in `docs/specs/skill-authoring-guide-235/prd.md` shipped at ≤50 lines body against an ADR-017 precedent of ~150 lines and required pre-merge amendment to ≤150. The `8-habit-reviewer` cross-verify caught it as PRD-vs-reality drift; future runs will contaminate `/consistency-check` signal until amended (lesson `~/.claude/lessons/2026-05-24-v218-4-skill-authoring-double-rescue.md` §5).
- **Opt-out** preserved — when no precedent exists (genuinely novel artifact type), or when the cap is set by a different constraint (hook token budget, validator string limit), declare the rationale in a one-line FR comment instead of measuring.
- **Template example** — `guides/templates/prd-template.md` Success Criteria section now shows a calibrated vs. uncalibrated FR-007 example side by side.
- **Plugin-boundary respected** — no validator extension, no PreToolUse hook (runtime enforcement belongs in `pitimon/claude-governance`); this ship is authoring-discipline only.
- **Consumer-doctrine bump** — `skills/**` and `guides/**` edits per [ADR-019](docs/adr/ADR-019-doctrine-only-scope-refinement.md); patch bump v2.18.4 → v2.18.5 atomic across 4 files; Check 27 passes.

PR closes [#237](https://github.com/pitimon/8-habit-ai-dev/issues/237).

## What's New in v2.18.4

**Theme: Skill authoring guide — close N1+P2 gaps from Vibe Coding Thailand audit** ([guide](guides/skill-authoring.md), [ADR-020](docs/adr/ADR-020-skill-authoring-guide.md))

Adds `guides/skill-authoring.md` documenting (a) Ben AI's Pre-Building Preparation pattern (draft reference docs collaboratively before opening SKILL.md), (b) the canonical SKILL.md skeleton including a dedicated `## Objective` section (distinct from the trigger-rubric `description` enforced by Check 25 and the `**Habit**: H?` label), (c) the authoring lifecycle wiring `/research` → reference docs → SKILL.md → `/reflect` → SKILL-EFFECTIVENESS feedback. Triggered by a 2026-05-24 audit of Vibe Coding Thailand's "คู่มือสร้าง Claude Skills ให้เก่งกว่าคนทั่วไป" article.

- **N1 (Pre-Building Preparation)** — closed via the new guide. 23 skills exist but no discoverable authoring methodology existed; `CONTRIBUTING.md` template was structural-only.
- **P2 (Objective conflated with trigger)** — closed via `CONTRIBUTING.md` template diff (new `## Objective` section in the skill skeleton) + matching skeleton in the guide.
- **Cross-verify reconciliation** — the source brief's first draft recommended "ship nothing" on friction-first grounds. `@8-habit-reviewer` scored it 12/17 and identified the same selective-strictness pattern that rescued the ADR-017 draft four days earlier. Revised verdict applies [ADR-014](docs/adr/ADR-014-external-prior-art-audit.md) / [ADR-017](docs/adr/ADR-017-anthropic-skill-patterns-audit.md) "ship with zero friction as forward guardrail" precedent consistently.
- **Sunset 2026-11-24** — per ADR-020 §"Forward-Guardrail Sunset" (ADR-017 mechanism, not ADR-016 eviction). Reversal criteria: no `/reflect` cite, no contributor PR reference, no new skill using the Pre-Building Preparation pattern.
- **Consumer-doctrine bump** — `guides/**` edit per [ADR-019](docs/adr/ADR-019-doctrine-only-scope-refinement.md); patch bump v2.18.3 → v2.18.4 atomic across 4 files; Check 27 passes.

PR closes [#235](https://github.com/pitimon/8-habit-ai-dev/issues/235).

## What's New in v2.18.3

**Theme: Anthropic engineering doctrine audit guide — defensive citation surface for ADR-018 "Earn each line"** ([guide](guides/anthropic-engineering-doctrine-audit.md))

Adds `guides/anthropic-engineering-doctrine-audit.md` cataloguing which Anthropic / Karpathy / Claude Code engineering blog patterns are **already operational** in the plugin (Table 1: 12 rows) vs **evaluated and deferred** (Table 2: 7 rows). Closes a documented [ADR-018](docs/adr/ADR-018-memory-layer-activation.md) gap: without the catalogue, future blog-reading contributors re-propose adopted patterns. Complements [ADR-017](docs/adr/ADR-017-anthropic-skill-patterns-audit.md) (narrower `github.com/anthropics/skills` 5-pattern audit).

- **N6 reclassification** — original `/research` brief proposed "skill description routing audit" as T1 with "weak n=1". `@8-habit-reviewer` cross-verify flagged cherry-picking: the cited 2026-04-22 lesson records `skills/RESOLVER.md` as a proactive discoverability feature (issue #135), not a friction patch. N6 sits at T2 in the guide with explicit rationale — H8 modeling deposit (apply friction-first to ourselves the same way we apply it to incoming proposals).
- **Consumer-doctrine bump** — `guides/**` is consumer-doctrine per [ADR-019](docs/adr/ADR-019-doctrine-only-scope-refinement.md), so v2.18.3 patch bump + CHANGELOG are mandatory (not elective). Validator Check 27 confirmed pre-push.
- **Scope reduction** — original execution plan included CLAUDE.md "Proposed" entries and `/audit-skill-descriptions` skill design; both dropped per reviewer findings (HIGH redundancy + CRITICAL cherry-picking). Single-PR scope ships.

PR closes [#231](https://github.com/pitimon/8-habit-ai-dev/issues/231).

## What's New in v2.18.2

**Theme: ADR-019 doctrine-only scope refinement — split contributor vs consumer doctrine** ([ADR-019](docs/adr/ADR-019-doctrine-only-scope-refinement.md))

Refines [ADR-017 §C5](docs/adr/ADR-017-anthropic-skill-patterns-audit.md). The original rule "doctrine-only commits don't need version bump" carried an implicit assumption — **doctrine ⇒ contributor-only audience** — that was about to break at the next PR: [ADR-018 §"Context"](docs/adr/ADR-018-memory-layer-activation.md) explicitly names `rules/effective-development.md` (~200 lines, auto-loaded into every consumer session) as the next "Earn each line" audit target. Under the original §C5, that audit would have shipped as "doctrine-only" → silent user-facing behavioral shift.

- **Contributor-doctrine** (no bump, preserves §C5 intent): `CLAUDE.md`, `CONTRIBUTING.md`, `docs/adr/**`, `docs/out-of-scope/**`, `docs/wiki/**`, `.github/**`, `SELF-CHECK.md`, `AGENTS.md`, `llms.txt`, `tests/**`
- **Consumer-doctrine** (MUST bump + CHANGELOG, even if "doctrine refinement"): `rules/**`, `skills/**`, `hooks/**`, `habits/**`, `guides/**`, `agents/**`
- **`tests/validate-structure.sh` Check 27** — compares diff against last release tag; if any consumer-doctrine path touched AND version-4-files unchanged → FAIL with citation to ADR-019. Skipped on first-release case. 358 PASS / 0 FAIL.
- **Elective bump rationale**: this PR touches only contributor-doctrine. Bump is meta-signal that CI behavior changed (new validator added) — contributors should know. Patch grain since no skill/runtime change.

Forward-Guardrail Sunset 2026-11-24 per ADR-017 convention. Stays in `8-habit-ai-dev` (workflow discipline, not enforcement — claude-governance owns runtime hooks).

## What's New in v2.18.1

**Theme: Anthropic skills 5-pattern audit — Tier 1 P3 ship, P4 OOS, P5 T2** ([ADR-017](docs/adr/ADR-017-anthropic-skill-patterns-audit.md))

A user-prompted Deep+Audit `/research` evaluated 23 skills against [github.com/anthropics/skills](https://github.com/anthropics/skills) (specifically `skills/{pdf,pptx,docx}`) 5 SKILL.md patterns. Pattern 1 + 2 already shipped via ADR-014 Check 25 and ADR-009 split convention. Pattern 3 (NEVER/MUST + reason) promoted to Tier 1 as a forward guardrail consistent with ADR-014 precedent. Pattern 4 (embedded `scripts/`) out-of-scope per plugin charter. Pattern 5 (fix-verify loop) split: language-nudge half deferred to T2 bag with drop date 2026-11-23 per ADR-016, runtime-hook half filed as companion [pitimon/claude-governance#37](https://github.com/pitimon/claude-governance/issues/37).

- **`tests/validate-structure.sh` Check 26** (warning-only) — flags skills with ≥4 soft-language verbs (`should`/`consider`/`may`/`might`/`could`) and 0 reason markers (`MUST`/`NEVER`/`ALWAYS`/`Why:`/`Rationale:`/`because`). Currently flags `/post-mortem` + `/reflect` as informational (discretion-heavy register; non-blocking). Validator suite: 357 PASS / 0 FAIL.
- **`/scrutinize` Operating Rules** — 6 MUST/NEVER + Why blocks added, replacing soft phrasings. Rationale per each rule (e.g., "**NEVER rubber-stamp.** Why: rubber-stamps appear identical to genuine "I traced everything" — the reader cannot tell which one happened").
- **`/diagnose` Phase 6 cleanup** — hardened with MUST re-run Phase 1 feedback loop, citing Anthropic pptx ~line 243 ("Do not declare success until you've completed at least one fix-and-verify cycle"). New Definition of Done checkbox.
- **`docs/out-of-scope/anthropic-pattern-4-scripts.md`** — preserves Pattern 4 (embedded scripts) rejection rationale per plugin charter ("Skills are read-only guidance — they tell Claude how to approach a task, they do not modify files themselves").

**Honest framing**: 8-habit-reviewer cross-verify pushed back on the original "documentation-only" recommendation, surfacing that ADR-014 itself shipped 4 patterns 4 days earlier with the same zero-friction score as forward guardrails. Holding Anthropic patterns to a stricter standard would be selective strictness (H8/Spirit work-avoidance). The reconciliation paragraph in the research brief documents the resolution. All Tier 1 shipments inherit ADR-016 drop date 2026-11-23 — if no friction signal accumulates by then, Check 26 + skill edits drop per the cost-of-correction asymmetry gate.

**Citation precision** (recorded for future readers): the triggering Thai-language blog cited Anthropic skills under a `document-skills/` URL prefix (real path: `skills/`) and 4/7 pptx line numbers off by 40-61 lines. Quoted text is verbatim correct; URL/line precision is not.

PR [#219](https://github.com/pitimon/8-habit-ai-dev/pull/219) merged as `8540f9e`. Companion issue [pitimon/claude-governance#37](https://github.com/pitimon/claude-governance/issues/37) tracks the cross-plugin H6 deposit.

---

## What's New in v2.18.0

**Theme: `/diagnose` skill — friction-driven external adoption** ([ADR-015](docs/adr/ADR-015-diagnose-skill-adoption-and-n1-framing.md))

A second-pass Deep `/research` audit of [mattpocock/skills](https://github.com/mattpocock/skills) (SHA [`b8be62ff`](https://github.com/mattpocock/skills/tree/b8be62ffacb0118fa3eaa29a0923c87c8c11985c)) identified `engineering/diagnose` as a candidate **not covered by ADR-014's P1–P10 grid** — and unlike the v2.17.0 bundle, this candidate has a **first-person friction citation**: `~/.claude/lessons/2026-04-12-compression-worker-420-investigation.md` explicitly states _"Most useful: n/a (no 8-habit skills invoked during the fix session)"_ and _"Could have been found in 5 minutes by comparing the two SQL queries side-by-side instead of 30 minutes of log analysis."_

- **`/diagnose`** (H1 + H5) — 6-phase active bug investigation: feedback-loop → reproduce → hypothesise → instrument → fix-with-regression-test → cleanup. Closes the documented gap between `/research` (too broad — investigates solution space) and `/post-mortem` (too late — assumes fix landed). Hands off to `/post-mortem` once the fix lands and the Phase 1 loop passes. Adapt-with-attribution from mattpocock SHA `b8be62ff` per [design.md Decision-5](docs/specs/diagnose-skill-v2-18-0/design.md).

**Honest framing** ([ADR-015](docs/adr/ADR-015-diagnose-skill-adoption-and-n1-framing.md)): the friction signal is **n=1, below ADR-014's preferred n≥2 bar** but unusually strong — a first-person retrospective admission of an absent-skill gap, not third-party pattern attractiveness. ADR-015 records the framing transparently and enumerates 4 future-reversal conditions (zero recorded uses at 6 months → consider deprecation; n≥2 friction → validates retroactively; user confusion vs `/post-mortem` → revise boundary; upstream SHA churn → re-audit).

**Spec chain** (persisted): `docs/specs/diagnose-skill-v2-18-0/{prd,design,tasks}.md`. **Research brief** (source): `~/.claude/plans/deep-mattpocock-skills-second-pass-2026-05-23.md` (Deep mode, 12/14 sources verified, SHA-pinned for citation-rot resistance).

Plugin total: **23 skills**. H1 (Be Proactive — prevent recurrence, not just patch the symptom) + H5 (Seek First to Understand — reproduce before fixing). Sets precedent for friction-first external prior-art adoption.

---

## What's New in v2.17.0

**Theme: External prior-art audit — 4 patterns adopted from mattpocock/skills as forward guardrails** ([ADR-014](docs/adr/ADR-014-external-prior-art-audit.md))

A 2026-05-20 Deep-mode audit of [mattpocock/skills](https://github.com/mattpocock/skills) (95.5k★, MIT) evaluated 10 candidate patterns. Four ship as additive guardrails; three explicitly deferred; three rejected and catalogued in the new `docs/out-of-scope/`. Honest framing: all 4 adoptions ship without prior friction-signal evidence — they are **forward guardrails, not fixes for observed weakness**. ADR-014 records this discipline for future audits.

- **P1 AGENT-BRIEF template** — new `guides/templates/agent-brief-template.md` (habit-mapped, ≤120 lines): durable issue spec for backlog-bound work; behavioral-not-procedural rule preserved. Referenced from `/breakdown` Handoff.
- **P3 `disable-model-invocation: true`** — applied to `/save-spec` and `/ai-dev-log` (deterministic scaffolders). **Honest disclosure**: per [anthropics/claude-code#22345](https://github.com/anthropics/claude-code/issues/22345) (OPEN), plugin skills don't currently honor this field — declaration is intent-marking until #22345 closes.
- **P4-lite `docs/out-of-scope/`** — new directory with 3 seed entries (brainstorm-removal, agentskills no-go, EU AI Act migration). Per-decision rejection rationale; distinct from ADRs (verbs: "we DID decide X" vs "we deliberately WON'T do Y"). CONTRIBUTING.md explains the distinction.
- **P5 description rubric** — new validator Check 25 in `tests/validate-structure.sh`: SKILL.md `description` ≤1024 chars + trigger phrase from empirically-grounded set (Use when / Use AFTER / Use BEFORE / Use to / Use for / Use as / Read this first / Assess / migrated). Activates as forward guardrail; pre-shipment audit found 0/19 drift.
- **Validator additions**: Check 24 (`disable-model-invocation` value validation), Check 25 (description rubric). Pure bash; zero new dependencies.

**Spec chain** (persisted): `docs/specs/mattpocock-t1-v2-17-0/{prd,design,tasks}.md`. **Research brief** (source): `~/.claude/plans/deep-https-github-com-mattpocock-skills-glimmering-prism.md` (13/14 sources verified by `research-verifier` agent).

H5 (Understand First) + H7 (Sharpen Saw) — external audit as renewal discipline.

### Companion bundle — 3 discipline-skill ports from [thananon/9arm-skills](https://github.com/thananon/9arm-skills)

A 2026-05-20 Deep-mode research pass evaluated 4 candidate skills from `9arm-skills` (700★, no LICENSE — patterns adapted, not copied). Three ship as new standalone skills filling gaps the 7-step workflow doesn't address; one (`/debug-mantra`) filtered out (ceremony-heavy "recite verbatim" pattern conflicts with Significance profile + `rules/effective-development.md` H1 anti-pattern guidance).

- **`/post-mortem`** (H4 + H7) — canonical engineering RCA writeup. Refuses to draft without 4 inputs (reliable repro, known root cause, identified fix, validated outcome). Engineer-audience artifact; code identifiers welcome. Pairs with `/reflect` — that captures 5-min micro-retro signal; this captures canonical bug record for grep-back-in-6-months future-you.
- **`/scrutinize`** (H5 + H8) — outsider-perspective end-to-end review. Step 1 (Intent) mandates a simpler-alternative pass before line-by-line review; Steps 2–4 trace the actual call graph not just the diff. Pairs with `/review-ai` — that catches security/quality/perf on the diff; this asks whether the change should exist at all.
- **`/management-talk`** (H4 + H6) — channel-aware audience reshape. Same engineering content → JIRA / Slack / standup / email / meeting. Strips function/file/SHA, keeps JIRA keys / PR numbers / workload identifiers. Pairs after `/post-mortem` (engineering record → leadership reframe) or `/reflect` (retro → status update).

All 3 standalone (`prev/next-skill: any`), invoked on demand, never block the 7-step chain. Plugin total: **22 skills**.

**Research brief** (source): `~/.claude/plans/deep-https-github-com-thananon-9arm-skil-misty-taco.md` (Deep mode, `research-verifier` agent confirmed citation integrity + 3 inaccuracies corrected).

H5 (Understand First) — outsider audit found patterns 8-habit could absorb. H6 (Synergize) — adapt-not-copy fuses 9arm discipline patterns with 8-habit conventions (`prev-skill`/`next-skill` handoff, Habit map, bilingual title).

---

## What's New in v2.16.5

**Theme: Companion announcement — devsecops `/workflow` → `/security-workflow`** (paired release)

Docs-only patch. Closes the paired-announcement promise from `devsecops-ai-team` v10.12.0's CHANGELOG. The cross-plugin `/workflow` naming collision has been resolved by devsecops renaming its skill to `/security-workflow`.

- **`docs/INTEGRATION.md`** — devsecops peg bumped 10.10.0 → 10.12.0+ with inline rename note
- **`skills/workflow/SKILL.md`** — new "See Also (Cross-Plugin)" footer pointing users who meant scan-orchestration to devsecops's `/security-workflow`
- **`README.md` Companion Plugins** — updated tested-version peg + naming-note callout
- Companion PR `devsecops-ai-team` v10.12.1 (paired) adds devsecops's symmetric "Companion Plugins" README section + skill-level "See also" callouts in `/eu-ai-act-assess` and `/security-workflow`

Pattern captured: companion-announcement step is now part of Definition of Done for any cross-plugin slash-command rename. See post-release lesson `cross-plugin-companion-announcement-pattern` in `~/.claude/lessons/`.

H4 (Win-Win) reciprocity — every interaction is a deposit; closing this promise is a deposit to users tracking both plugins.

---

## What's New in v2.16.4

**Theme: `/save-spec` suite-positioning honesty patch (Adopter #2 third-repo dogfood)** ([#207](https://github.com/pitimon/8-habit-ai-dev/issues/207))

Docs-only patch. Adopter #2's third-repo dogfood (operational VA/PT workspace with `claude-mem` active + 284-line `CLAUDE.md`) surfaced two real overlap cases the docs didn't acknowledge. P1 + P2 ship; P3 explicitly deferred per adopter recommendation.

- **P1 (docs only)** — `skills/save-spec/SKILL.md` "When to Skip" gains a memory-MCP-overlap entry: skip if you already have `claude-mem`/`memforge` active AND a short `CLAUDE.md` (<150 lines), because §4 (Current state) becomes the only net-value section over what you already have.
- **P2 (docs only)** — Suite-positioning clarification across SKILL.md + README + using-8-habits/reference.md: `/save-spec` is a **deployment-mode helper orthogonal to the 7-step workflow**, alongside `/calibrate` + `/reflect` as state-write skills run on user demand (NOT alongside assessment skills).
- **P3 (defer)** — `--skip-empty-sections` flag explicitly deferred per adopter recommendation pending demand signal.

Pattern: **H8 Conscience applied to marketing copy** — the SKILL.md's own H8 Checkpoint admitted "the value depends on the user's habit of updating it"; this release extends that honesty to "When to Skip".

**Arc-close criterion validated**: v2.16.3 said "round 6 deferred unless 3rd adopter surfaces friction" — that condition triggered within ~2 hours of v2.16.3 release. Pattern continues at n=3 evidence base. Adopter's `/cross-verify` on the issue: 13/15 = 86.7%. Maintainer's `/cross-verify` on implementation posture: 15/15 = 100%.

## What's New in v2.16.3

**Theme: `/save-spec` Round-5 arc-close polish (Adopter #2 closure pass)** ([#205](https://github.com/pitimon/8-habit-ai-dev/issues/205))

Patch release. Adopter #2 closure pass on the 5-round v2.16.x QA arc surfaced 1 MEDIUM bug + 2 LOW items + an arc-close meta. All 3 fixed; arc closed per Adopter #2 recommendation.

- **R5-3 (MEDIUM bug, fixed)** — Scaffolded `SPEC.md` §2 markdown table rendered broken on every empty-decisions scaffold (`reference.md:30` blank line separated alignment row from substitution marker). Final fix uses table-row-shaped substitution marker because the formatter persistently re-wedged blanks around HTML-blocks AND `<...>` markers. New validator Check 12c.1 regression check added.
- **R5-1 (LOW-MEDIUM doc, fixed)** — Template assembly markers consolidated to explicit `ASSEMBLY-DIRECTIVE` phrasing + "NEVER appears in output" language; visually distinct from F1-class pre-fix placeholders.
- **R5-2 (LOW doc, fixed)** — FR-017 target-dir validation now uses a separate pre-flight error template ("Directory not found: …") with correct register, not the Decision-4 Write-failure wording.

Pattern: **formatter-vs-substitution-marker arms race resolved via table-row-shaped marker.** When a marker must be adjacent to a formatter-stable construct, make the marker itself look like that construct. DoD-must-execute self-test caught **zero bugs this round** — convergence is the expected pattern when discipline holds.

**5-round arc closed** per Adopter #2 recommendation. Rounds 1–5: #197 → v2.16.0; #201 → v2.16.1; #203 → v2.16.2; #205 → v2.16.3. Round 6 deferred unless a third independent adopter surfaces friction.

## What's New in v2.16.2

**Theme: `/save-spec` Round-3 polish + Guide Check 2 BSD-awk fix (Adopter #3 dogfood)** ([#203](https://github.com/pitimon/8-habit-ai-dev/issues/203))

Patch release. Adopter #3 dogfood pass on `/save-spec` (first round from **real skill execution**, not docs review) surfaced 1 correctness bug + 1 friction enhancement; the pre-PR self-test (DoD-must-execute action item from same-day /reflect lesson) surfaced 1 additional verification-command bug. All 3 fixed.

- **F1 (MEDIUM bug, fixed)** — Scaffolded `SPEC.md` shipped 6 literal angle-bracket placeholder sites contradicting the read-first-context purpose. Hybrid fix: §2/§3 skip-stubs use plain prose italic markers; §1 narrative + §4 fill-required sites use `` HTML comments (invisible at render, visible to editor).
- **F2 (LOW-MEDIUM enhancement)** — `/save-spec [project-name] [target-dir]` accepts optional second positional argument. Multi-repo portfolio adopters no longer need a per-repo session switch.
- **F3 (MEDIUM bonus, surfaced by pre-PR self-test)** — Guide's Check 2 awk range collapsed to 1 line on BSD awk (macOS default) because the end-regex matched the start line. Replaced with `sed -n` (consistent cross-platform). All macOS adopters silently affected since v2.15.9.
- **W2 (doc softening)** — N2 timestamp warning reframed; Adopter #3 verified correct Bangkok offset in real use.

Pattern: **DoD-must-execute principle empirically validated within 24h of being coined.** The v2.16.1 /reflect action item caught F3 — a BSD-awk regression no static review would have surfaced. Lesson loop closed same day.

## What's New in v2.16.1

**Theme: `/save-spec` Phase 1 polish — Adopter #2 dogfood fixes** ([#201](https://github.com/pitimon/8-habit-ai-dev/issues/201))

Patch release. Adopter #2 dogfood pass on the v2.16.0 `/save-spec` skill surfaced 1 correctness bug + 3 quality items — all four fixed in this single PR.

- **N1 (MEDIUM bug, fixed)** — §1 empty stub previously used `` `.md` `` which Check 4's backtick-path grep extracted as `.md` (literal angle brackets), making the Definition of Done's "passes 5 verification commands" claim provably false on the default scaffold. Stub now reads `_§1 is empty — add project-specific pointers as the repo grows._` with no backticked .md path. DoD claim is now true.
- **N2 (LOW, documented)** — Timestamp reliability profile documented. The skill (no `Bash`) substitutes the `**Last updated**` value from Claude's session-injected current-time context; when absent, output may carry `+00:00` or a wrong offset. Adopters: verify offset after scaffold, edit manually if wrong. Phase 2 hook for adding `Bash` if feedback warrants.
- **N3 (LOW UX, fixed)** — Q2 (§1 pointer confirmation) now accepts an "Other (free-text)" affordance for newline-separated project-specific paths. Motivated by ops/infra repos with non-canonical naming (`server-state.md`, `playbooks/change-management.md`, `runbooks/ops-runbook.md`).
- **N4 (LOW doc, fixed)** — PRD FR-003 deduplicated against reference.md Decision-3. Single source of truth.

Pattern: **patch-release dogfood discipline** — the adopter report surfaced N1 in <2 hours after v2.16.0; same-day correctness fix. Sibling closure: [#197](https://github.com/pitimon/8-habit-ai-dev/issues/197) now closeable — all 5 of its items addressed in v2.16.0 + #198.

## What's New in v2.16.0

**Theme: `/save-spec` skill — project-orientation hub mode promoted from guide to skill** ([#199](https://github.com/pitimon/8-habit-ai-dev/issues/199))

Minor version bump (new skill). All three v2.15.9 promotion criteria met after Adopter #2 report ([#197](https://github.com/pitimon/8-habit-ai-dev/issues/197)):

- **`/save-spec`** (new, Phase 1 minimum viable) — user-invoked skill that scaffolds a project-root `SPEC.md` following the spec-digest-pattern archetype. Hybrid auto-detect: globs for `PLAYBOOK.md`, `CONTRACTS.md`, `LESSONS.md`, `CHANGELOG.md`, `README.md` and asks the user to confirm §1 pointers. AskUserQuestion seeds project name, up to 3 §2 decisions, up to 3 §3 backlog items. §4 gets a timestamped template-stub. Refuses to overwrite an existing `SPEC.md` (Phase 2 `--update` deferred). Emits the CLAUDE.md auto-update recipe stanza to conversation only — does NOT modify your `CLAUDE.md`.
- **Scope question closed in writing** — `guides/spec-digest-pattern.md` now states explicitly that feature-spec mode (`--persist `) and project-orientation hub mode (root `SPEC.md`) are disjoint in practice; multi-mode repos are out of scope for tooling. Both n=2 adopters used project-orientation mode standalone.
- **ADR-013 follow-up addendum** — clarifies that the v2.16.0 `/save-spec` promotion stays within the existing ADR scope (user-invoked write is outside Alt-4's auto-write-hook rejection). No new ADR required.
- **`tests/validate-structure.sh` Check 23** — pins the canonical contract for `/save-spec`: frontmatter array, 8-step Process count (Decision-7 sticky), Decision-3 refusal phrase, Decision-4 error phrase, Decision-2 skip-sentinels documentation. Drift requires a new `/design` cycle.

Pattern: **promotion via maturity ladder, not aesthetic preference.** v2.15.9 documented the pattern + deferred the skill with explicit promotion criteria; v2.16.0 ships the skill only after the criteria were objectively met (n=2 adoption + scope resolved + friction lesson captured). Decision-driven, data-backed.

Dogfood: the PRD/design/tasks for this skill itself were persisted via `--persist save-spec` (the convention `/save-spec` does NOT use — feature-spec mode dogfooding project-orientation tooling), then `/consistency-check save-spec` ran clean (0 CRITICAL, 0 HIGH, 4 LOW for missing alternatives markers in 4 design decisions — accepted as informational).

## What's New in v2.15.9

**Theme: Project-Orientation Hub Mode Documentation** ([#194](https://github.com/pitimon/8-habit-ai-dev/issues/194), [PR #195](https://github.com/pitimon/8-habit-ai-dev/pull/195))

Docs-only patch. Documents a second spec-persistence deployment mode as complement to v2.15.2's feature-spec mode. No new skill, no hook, no enforcement.

- **`guides/spec-digest-pattern.md`** (new, ~180 lines) — project-root `SPEC.md` digest with §1 Architecture (pointer), §2 Decisions snapshot (compact ADR digest table), §3 Live backlog, §4 Current state save point ("Read this section first after `/clear` or `/compact`"). Template paraphrased from a production artifact (`scanopy/netbox-sit/SPEC.md`, 153 lines) that independently arrived at this four-section shape after repeated `/clear`/`/compact` flushing pain.
- **ADR-013 addendum** — additive 2026-05-17 note clarifying ADR-013's rejections (Alt-1 unified spec.md merge, Alt-4 always-on auto-write hook, CHANGELOG v2.15.0 `/save-point` skill rejection) cover the feature-spec mode specifically. The digest-layer-above-detail-files archetype is a different deployment mode those alternatives did not evaluate. **No change to the original Decision section.**
- **Cross-links** — `guides/persistence-convention.md` notes the two modes are complementary; `README.md` Use Cases table gets a "Survive `/clear` and `/compact`" row.
- **`/save-spec ` skill** — explicitly deferred until ≥2 independent project adoptions, per working-with-pitimon "minimal additions, user-demand-driven" stance + PR #111 local-maximum lesson. Promotion criteria documented in the new guide.

Pattern: **empirical-evidence-driven discipline addition**. A real-world artifact from another session revealed a deployment mode the plugin did not document. The plan was revised twice (after `8-habit-reviewer` flagged write-vs-read scope, after advisor flagged n=1 commitment level) before settling on guide-first as the right commitment for the available evidence.

## What's New in v2.15.8

**Theme: `/reflect` Auto-Consolidation — One-Command Flow** ([#191](https://github.com/pitimon/8-habit-ai-dev/issues/191), [PR #192](https://github.com/pitimon/8-habit-ai-dev/pull/192))

UX patch removing the two-step friction in the reflection loop. Step 7 of `/reflect` now runs the 4-phase consolidation cycle automatically after saving each lesson file, instead of printing a nudge and waiting for a separate `/reflect consolidate` invocation.

- **Auto-run when `count > 10`** — Orient → Gather → Consolidate runs inline. No merges found → `~/.claude/lessons/INDEX.md` updated automatically + 1-line summary printed. Done in a single command.
- **Human-approval gate preserved** — If genuine duplicates are detected (merges/deletions proposed), the cycle stops and presents a plan for explicit approval before writing or deleting anything. In-the-Loop per ADR-002 — deletion is irreversible.
- **Explicit `/reflect consolidate` still works** — Same 4-phase cycle with verbose Consolidation Report output (Before/After/Merged/Pruned/Kept), for manual runs when full detail is needed.
- **Definition of Done updated** — "Consolidation auto-ran" replaces "Consolidation check performed" — the new bullet is testable with two concrete outcomes.

Pattern: **PC² — invest in the capability that builds capability.** The reflection loop is the system that captures lessons; reducing friction in that loop is H7 applied to H7 itself. Root cause was a threshold (10) that mature repos cross quickly — the fix makes auto-run safe for the common case (INDEX update, non-destructive) while keeping the gate for the rare case (deletions).

## What's New in v2.15.7

**Theme: Vendor Portability Discipline for Managed Agent Platforms** ([#188](https://github.com/pitimon/8-habit-ai-dev/issues/188), [PR #189](https://github.com/pitimon/8-habit-ai-dev/pull/189))

Doc-only patch responding to the indu

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pitimon/8-habit-ai-dev

Awesome Lists containing this project

README