<div align="center">
  <img src="assets/logos/logo-stack-monochrome.svg" alt="My Agent Kit Logo" width="80" />
</div>

# Changelog

All notable changes to this project will be documented in this file. The format
loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.1.0] - 2026-05-26

Sync with upstream v2.19.1 — introduces the **workflow artifact gate**, which
turns the `mk:cook` / `mk:fix` review process into a file-backed contract
instead of a prompt checklist. Reviewers now produce JSON artifacts that the
gate validates before any commit, ship, push, PR, or deploy action.

### Added

- **Workflow artifact gate** — new hook +
  `claude/hooks/workflow-artifact-gate.cjs` and four sub-modules
  (`validator`, `artifact-locator`, `stage-detector`, `artifact-schema`).
  Validates 5 required JSON artifacts before any finalize / commit / ship /
  push / pr / deploy action:

  | Artifact | Purpose |
  |---|---|
  | `context-snippets.json` | evidence the reviewer actually read code |
  | `risk-gate.json` | risk classification + `autoStopRequired` signal |
  | `verification.json` | test / typecheck / build evidence |
  | `review-decision.json` | final PASS/FAIL with criticals + warnings |
  | `adversarial-validation.json` | required when `--auto`, high-risk, or large-diff |

  Hook is **opt-in** via `.claude/.mk.json` (`hooks.workflow-artifact-gate: true`).
  Manual CLI mode always validates and exits non-zero when the gate blocks:

  ```bash
  node .claude/hooks/workflow-artifact-gate.cjs --stage finalize \
    --artifact-dir plans/<plan>/reports/harness/
  ```

  Artifact directory conventions:
  - Plan workflow: `plans/<plan-dir>/reports/harness/`
  - No-plan workflow: `plans/reports/harness/<timestamp-slug>/`
  - Active pointer: `.claude/workflow-artifacts.json`

- **Secret leak scan in validator** — refuses to validate artifacts
  containing unredacted `Authorization: Bearer …`, `Cookie: …`,
  `API_KEY=…` / `TOKEN=…` / `SECRET=…` / `PASSWORD=…`, GitHub tokens
  (`ghp_*`, `gho_*`, `ghu_*`, `ghs_*`, `github_pat_*`), OpenAI keys
  (`sk-*`), AWS access keys (`AKIA*`), or PEM private keys. Artifacts
  must redact or mask these before validation passes.

- **`workflowArtifactGate` config block** in
  `claude/hooks/lib/mk-config-utils.cjs` defaults:

  ```js
  workflowArtifactGate: {
    enabled: true,
    softStages: ['finalize', 'commit'],
    hardStages: ['ship', 'push', 'pr', 'deploy'],
    highRiskAutoStop: true
  }
  ```

- **MyKit JSON schema** at `claude/schemas/mk-config.schema.json` — full
  schema for `.claude/.mk.json`, including the new artifact gate section.
  Wire this into your editor (`"$schema"`) for autocomplete on `.mk.json`.

- **`chrome-profile` skill** — manage real Chrome profiles for browser
  automation that needs the user's actual cookies / session / extensions
  (different from `mk:agent-browser` which uses a fresh tool-managed browser).
  Includes install/uninstall scripts and `chrome_profile_cli.py`.

- **`claude/skills/_shared/references/workflow-artifacts.md`** — single
  source of truth for the artifact contract, shared by both `cook` and
  `fix` skills.

- **`settings.json` registration** — `workflow-artifact-gate.cjs` runs on
  `UserPromptSubmit` so it can advise (soft) on `finalize` / `commit`
  stages even before the user types a hard-stage command. Hard stages
  (ship / push / pr / deploy) block when artifacts are missing or invalid.

### Changed

- **`mk:cook` review cycle policy** — `score >= 9.5` is now **only a
  confidence signal**, never sufficient for approval on its own. Approval
  requires:
  - `review-decision.decision == PASS` AND
  - artifact validator passes AND
  - `critical_count == 0`
- **`mk:cook` auto mode** — high-risk diffs (auth, payments, DB schema,
  migration, public API, CI/deploy/release/production config, destructive
  FS ops, large diff) now trigger `risk-gate.autoStopRequired = true` and
  stop the auto pipeline pending human approval via `AskUserQuestion`.
  Previously `--auto` skipped all gates.
- **`mk:fix` review cycle** — now writes the same 5-artifact set after
  diagnose AND after fix steps, with the artifact gate validating both.
- **`code-reviewer` agent** — emits `review-decision.json` and
  `adversarial-validation.json` instead of free-form prose. Score remains
  in the artifact but no longer triggers auto-approve.
- **`subagent-init.cjs`** — passes workflow context (current stage,
  artifact dir pointer) into subagent system prompts so reviewers know
  which artifact directory to write to.
- **`descriptive-name.cjs`** — minor tweak to file-naming guidance text.
- **`lib/context-builder.cjs`** — small refactor to share helpers with
  the new artifact gate.

### Synced files from upstream v2.19.1

| Path | Notes |
|---|---|
| `claude/skills/cook/SKILL.md` + `README.md` | new HARD-GATE wording, artifact contract |
| `claude/skills/cook/references/review-cycle.md` | + Required Review Artifacts section, new approval policy |
| `claude/skills/cook/references/workflow-steps.md` | auto mode now respects `autoStopRequired` |
| `claude/skills/cook/references/intent-detection.md` | minor edits |
| `claude/skills/cook/references/subagent-patterns.md` | new file |
| `claude/skills/fix/SKILL.md` | new HARD-GATEs aligned with cook |
| `claude/skills/fix/references/{review-cycle,prevention-gate,workflow-deep,workflow-standard,workflow-ui}.md` | artifact wiring |
| `claude/skills/code-review/SKILL.md` + 14 reference files | synced from upstream `ck-code-review/` (folder renamed to `code-review/` for MK) |
| `claude/skills/mk-plan/SKILL.md` | minor edits |
| `claude/skills/mk-debug/SKILL.md` | minor edits |
| `claude/skills/test/SKILL.md` | minor edits |
| `claude/agents/code-reviewer.md` | JSON artifact emission |
| `claude/hooks/subagent-init.cjs` | workflow context passing |
| `claude/hooks/descriptive-name.cjs` | guidance tweak |
| `claude/hooks/lib/context-builder.cjs` | shared helpers |

### Identity normalization

All upstream `ck` markers stripped during the sync:

- `(?<![a-zA-Z])ck:` slash-command pattern → `mk:` (does not touch
  `check:`, `block:`, `track:`, `feedback:`)
- `require('./lib/ck-config-utils.cjs')` → `require('./lib/mk-config-utils.cjs')`
- `ck-code-review/` references → `code-review/` (MK's folder name; the
  skill itself was already `name: mk:code-review`)
- `claudekit` / `ClaudeKit` / `ClaudeKit Engineer` → `my-kit` / `MyKit`
- `.ck.json` / `.ckignore` → `.mk.json` / `.mkignore`
- `claudekit.cc` → `my-kit.local`
- `\`ck\` unavailable` CLI fallback messages → `\`mk\` unavailable`

Verified zero leaks across all production files (`grep` exclusion list
includes only the `strip-identity` skill itself, which intentionally
contains the patterns it strips).

### Migration

Existing v2.0.x installs upgrade cleanly with:

```bash
npx my-agent-kit@latest init . --upgrade --force
```

The artifact gate is **off by default** — no existing workflow changes
unless you opt in. To enable per project:

```jsonc
// .claude/.mk.json
{
  "hooks": {
    "workflow-artifact-gate": true
  }
}
```

Once enabled, `mk:cook` and `mk:fix` reviews will write artifacts; finalize
/ commit / ship / push / PR / deploy actions block until the validator
passes. To verify manually before a release:

```bash
node .claude/hooks/workflow-artifact-gate.cjs --stage ship \
  --artifact-dir plans/<your-plan>/reports/harness/
```

### Behavioral note (not breaking, but worth knowing)

If you previously relied on `mk:cook --auto` racing through high-risk
changes (auth / payments / DB schema / CI / deploy / destructive FS) it
will now stop on the first risk trigger and ask. To preserve old behavior
you can leave the artifact gate off, but the new policy is the
recommended default.

---

## [2.0.1] - 2026-05-19

Patch release fixing an incomplete identity rename in v2.0.0.

### Fixed

- **Slash command prefix leak** — 246 files still referenced the old `ck:`
  command prefix (e.g. `/ck:cook`, `ck:docs-seeker`) instead of `mk:`. The
  v2.0.0 identity sweep used a word-boundary regex that silently skipped the
  `ck:` slash-command pattern. Users saw `/ck:docs` in the command palette
  instead of `/mk:docs`. All 246 files corrected with a boundary-safe
  substitution (does not touch `check:`, `block:`, `track:`, `feedback:`).
- **Config filename references** — documentation and helper scripts pointed
  users at `.ck.json` / `.ckignore`, but the actual kit ships `.mk.json` /
  `.mkignore`. Following the old docs created config files the kit never read.
  All references corrected.

### Upgrade

```bash
npx my-agent-kit init . --upgrade --force
```

No behavior change beyond correct command names — purely a naming-consistency
fix. If you installed v2.0.0 and saw `/ck:` commands, upgrade to v2.0.1.

## [2.0.0] - 2026-05-12

Major release synchronizing with upstream v2.17 plus a structural refactor of
the kit layout. **Contains breaking changes for existing installs** — see the
migration guide below.

### Highlights

- **6 new skills** ported from upstream: `agentize`, `cti-expert`, `excalidraw`,
  `graphify`, `show-off`, `xia`
- **`fix` skill v2.0** — rewritten with a structured diagnosis pipeline (root
  cause → reproduction → minimal fix → regression test)
- **`mk:plan` overhaul** — scoped plans, verification roles, canonical phase-file
  template, CLI-only plan creation
- **Statusline** — refactored to a config-driven modular renderer with theme
  parity across compact / minimal / full modes
- **Signal-driven simplify gate** — opt-in hook (`simplify-gate.cjs`) that
  suggests code simplification only when activity signals warrant it
- **Quality gates** — schema contract for skills, format compliance check,
  cross-reference integrity, metadata deletion verification
- **Worktree skill** — `--base` flag, `status prune` subcommand, submodule
  setup, forward-slash branch names

### Added

#### New skills

| Skill | What it does |
|---|---|
| `agentize` | Convert an existing codebase into a CLI tool and MCP server |
| `cti-expert` | Cyber Threat Intelligence / OSINT investigation playbook |
| `excalidraw` | Generate Excalidraw `.excalidraw` diagram files |
| `graphify` | Build a knowledge graph from notes, code, or docs |
| `show-off` | Showcase / demo presentation generation with readiness chain |
| `xia` | Repo-porting and repo-analysis workflow |

#### New rules

- `claude/rules/skill-domain-routing.md` — intent-based decision tree for
  picking the right skill from a problem description
- `claude/rules/skill-workflow-routing.md` — routing rules for chaining skills
  into a workflow

#### New agents

- `code-simplifier` — proactive code simplification specialist (replaces
  `simplifier`, with stronger signal-driven invocation)
- `journal-writer` — writes development journal entries
- `mcp-manager` — manages MCP server registration

#### New hooks

- `simplify-gate.cjs` — signal-driven simplify suggestion gate (opt-in, default
  off)
- `usage-quota-cache-refresh.cjs` — refreshes API usage quota cache between
  sessions
- Hardened `scout-block.cjs` — fixed Windows absolute paths handling

#### Install / build

- `mk-init.sh --upgrade` — clean upgrade mode. Reads `claude/metadata.json`
  deletions list and drops removed paths from the target's `.claude/` before
  copying fresh content
- `claude/metadata.json` — kit manifest with version, deletions list (for clean
  upgrades), and build metadata
- `claude/statusline.cjs` — modular, config-driven statusline renderer

### Changed

#### Repository layout (BREAKING)

The canonical kit content moved from `.claude/` to `claude/` (no leading dot).

```
Before                              After
─────────────────────              ───────────────────────
my-agent-kit/.claude/   →          my-agent-kit/claude/
  └─ (kit content)                   └─ (kit content — source of truth)

Target project (unchanged)
target/.claude/                    target/.claude/    ← still here, created by mk-init.sh
```

**Why:** separates source-of-truth kit content (`claude/`) from runtime Claude
Code config (`.claude/`). The installer (`mk-init.sh`) copies `claude/* →
<target>/.claude/*`, so end users see no change in how Claude Code reads the
kit.

#### Rewrites

- **`fix` skill** → v2.0 with structured diagnosis pipeline
- **`mk:plan` skill** → scoped plans with verification roles, CLI-only plan
  creation enforced
- **Statusline** → config-driven, theme-aware, supports compact / minimal / full
  modes via user-configured `lines[][]` config format
- **Skills format compliance** → all 90+ skill descriptions hardened against
  the new schema contract
- **Rules format** → flat domain tables replaced with intent-based decision
  trees in `skill-domain-routing.md` and `skill-workflow-routing.md`

#### Renames / removals

- `simplifier` agent → renamed to `code-simplifier`
- Removed agents: `copywriter`, `database-admin`, `scout`, `scout-external`
  (consolidated into other roles)
- `mk:loop` skill → renamed to `mk:autoresearch` (old name still archived)
- `frontend-design` skill — improved with new guidance
- Bundled `opencode` artifacts removed from the kit

### Migration guide (1.0.0 → 2.0.0)

#### For end users of the kit (installed via `npx my-agent-kit init`)

The target project's `.claude/` directory layout is unchanged — Claude Code
still reads from `.claude/`. To upgrade an existing install:

```bash
# Option 1: clean upgrade — drops files that were removed upstream
npx my-agent-kit init . --upgrade --force

# Option 2: full reinstall (loses any local customizations to .claude/)
npx my-agent-kit init . --force
```

After upgrade:
- Old slash command `/mk:loop` → use `/mk:autoresearch`
- Old agent name `simplifier` → use `code-simplifier`
- Removed agents (`scout`, `scout-external`, `copywriter`, `database-admin`)
  are gone — replace references in custom workflows

#### For kit developers / maintainers (working in this repo)

- Edit files in **`claude/`** (canonical), not `.claude/` — the latter does not
  exist in this repo anymore
- After upstream syncs, always run identity-stripping (see
  `CLAUDE.md` → "Upstream sync workflow")
- `package.json` "files" array points to `claude/` not `.claude/`
- Hooks library path: `claude/hooks/lib/mk-config-utils.cjs` (renamed from
  `ck-config-utils.cjs`)
- Schemas: `claude/schemas/mk-config.schema.json` (renamed from
  `ck-config.schema.json`)
- Root config files: `claude/.mk.json` and `claude/.mkignore` (renamed from
  `.ck.json` / `.ckignore`)

### Removed

- `.claude/` directory at repo root (replaced by `claude/`)
- `simplifier` agent (renamed to `code-simplifier`)
- `copywriter`, `database-admin`, `scout`, `scout-external` agents
- Old `mk-help` skill folder structure (consolidated to
  `claude/command-archive/mk-help/`)
- All `ck-*` / `.ck*` legacy naming (renamed to `mk-*` / `.mk*`)
- Bundled opencode artifacts

### Internal

- 1500+ files refactored across the kit
- 125-entry `metadata.json` deletions list ensures clean upgrades drop removed
  files instead of leaving stale references
- CI quality gates added: skill schema validation, cross-reference integrity,
  metadata deletion check

---

## [1.0.0] - 2026-04-02

### Added

- Initial public release
- 14 specialist agents (planner, tester, code-reviewer, debugger, researcher, scout, fullstack-developer, docs-manager, git-manager, brainstormer, project-manager, simplifier, team-lead, scout-external)
- 80+ domain knowledge skills (cook, fix, test, ship, deploy, debug, plan, and more)
- 15 event-driven hooks (session-init, privacy-block, dev-rules-reminder, etc.)
- 5 workflow rule files (primary-workflow, development-rules, orchestration-protocol, documentation-management, team-coordination)
- `mk-init.sh` installer with `--copilot`, `--codex`, `--all` cross-tool support
- `npx my-agent-kit init` — one-command installation via npm
- `AGENTS.md` universal instructions (read by Codex CLI, Cursor, Windsurf, and 5+ other tools)
- `templates/` directory for project-specific CLAUDE.md and AGENTS.md
- Documentation site at phuc-nt.github.io/my-agent-kit-docs/
- 33 workflow guides for 9 personas (Developer, Solopreneur, Tech Lead, PM, Designer, QA, DevOps, Tech Writer, Researcher)
