@jgamaraalv/ts-dev-kit 2.3.0 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
     "url": "https://github.com/jgamaraalv"
   },
   "metadata": {
-    "description": "TypeScript fullstack development agents and skills for Claude Code"
+    "description": "15 agents and 21 skills for TypeScript fullstack development with Claude Code"
   },
   "plugins": [
     {
       "name": "ts-dev-kit",
       "source": "./",
-      "description": "13 specialized agents and 16 skills for TypeScript fullstack development",
-      "version": "2.2.0",
+      "description": "15 specialized agents and 21 skills for TypeScript fullstack development",
+      "version": "3.0.0",
       "author": {
         "name": "jgamaraalv"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ts-dev-kit",
-  "version": "2.2.0",
-  "description": "13 specialized agents and 16 skills for TypeScript fullstack development with Fastify, Next.js, PostgreSQL, Redis, and more.",
+  "version": "3.0.0",
+  "description": "15 specialized agents and 21 skills for TypeScript fullstack development with Fastify, Next.js, PostgreSQL, Redis, and more.",
   "author": {
     "name": "jgamaraalv",
     "url": "https://github.com/jgamaraalv"

package/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [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).
 
+## [3.0.0] - 2026-02-27
+
+### Added
+
+- `/codebase-adapter` skill: surgically adapts plugin agent/skill files to the host project on installation — updates domain area tables, skill maps, MCP references, quality gate commands, and package names without touching workflow logic
+- `/core-web-vitals` skill: LCP, INP, CLS reference covering thresholds, field vs lab tooling, diagnosis guides, and optimization patterns; includes `scripts/visualize.py` for generating interactive HTML reports from metric values or Lighthouse JSON output
+- `/debug` skill: end-to-end debugging workflow with multi-layer triage, single/multi-layer execution modes, and agent dispatch templates for backend, frontend, queue, and E2E layers
+- `/generate-prd` skill: produces structured Product Requirements Documents from feature descriptions or user stories
+- `/generate-task` skill: breaks PRD features into granular, agent-ready task files with acceptance criteria, affected packages, and quality gate commands
+- Dynamic context injection (`!`command`` syntax) to `/conventional-commits`: staged diff summary, full staged diff (up to 300 lines), and recent commit log are pre-injected before Claude receives the prompt
+- Dynamic context injection to `/debug`: last 10 git commits and working tree status are pre-injected at invocation time to accelerate triage
+- Dynamic context injection to `/codebase-adapter`: working directory, detected lockfile, installed agents, configured MCP servers, and `package.json` are pre-injected to reduce manual discovery
+- `allowed-tools` frontmatter to `/conventional-commits`, `/debug`, `/codebase-adapter`, and `/core-web-vitals` — whitelists the shell commands needed for dynamic injection and script execution
+- `scripts/` subdirectory convention for skills that bundle executable tools (Python, bash)
+
+### Changed
+
+- Renamed skill `/task` → `/execute-task` (update any project references or task files that invoke this command)
+
+### Breaking Changes
+
+- `/task` slash command removed; use `/execute-task` instead
+
+## [2.3.0] - 2026-02-26
+
+### Added
+
+- `/tanstack-query` skill: TanStack Query v5 (React Query) reference covering `useQuery`, `useMutation`, `useInfiniteQuery`, `QueryClient`, SSR/hydration with Next.js, optimistic updates, cache invalidation, and TypeScript patterns
+
+## [2.2.0] - 2026-02-26
+
+### Changed
+
+- Enforce mandatory agent delegation in all `/execute-task` execution modes — tasks are always dispatched to specialized agents; direct implementation by the orchestrator is no longer permitted
+
+## [2.1.0] - 2026-02-25
+
+### Added
+
+- Baseline capture phase to `/execute-task`: records the state of quality gates before any changes
+- Post-change verification phase to `/execute-task`: re-runs quality gates after the fix and diffs against baseline to confirm no regressions were introduced
+
+## [2.0.0] - 2026-02-24
+
+### Changed
+
+- Make all 15 agents fully repository-agnostic: agents now discover project conventions dynamically from `CLAUDE.md`, `package.json`, and the codebase — no hardcoded paths, package names, or workspace commands remain in any agent definition
+
+### Breaking Changes
+
+- Any project-specific overrides embedded directly in agent files are no longer applied; configure project context in your project's `CLAUDE.md` instead
+
 ## [1.2.1] - 2026-02-24
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # ts-dev-kit
 
-> 15 specialized agents + 14 curated skills for TypeScript fullstack development
+> 15 specialized agents + 21 curated skills for TypeScript fullstack development
 
 [![npm version](https://img.shields.io/npm/v/@jgamaraalv/ts-dev-kit)](https://www.npmjs.com/package/@jgamaraalv/ts-dev-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -30,48 +30,92 @@
 | typescript-pro          | Generics, type inference, conditional types             |
 | ux-optimizer            | User flows, form UX, friction reduction                 |
 
-### Skills (14)
-
-| Skill                  | Slug                      | Domain                                       |
-| ---------------------- | ------------------------- | -------------------------------------------- |
-| BullMQ                 | `/bullmq`                 | Redis job queues, workers, flows, schedulers |
-| Composition Patterns   | `/composition-patterns`   | React compound components, render props      |
-| Conventional Commits   | `/conventional-commits`   | Commit message spec, types, SemVer           |
-| Docker                 | `/docker`                 | Dockerfiles, compose, optimization, security |
-| Drizzle ORM            | `/drizzle-pg`             | PostgreSQL ORM schemas, queries, migrations  |
-| Fastify Best Practices | `/fastify-best-practices` | Routes, plugins, hooks, validation           |
-| ioredis                | `/ioredis`                | Redis client, pipelines, Pub/Sub, Cluster    |
-| Next.js Best Practices | `/nextjs-best-practices`  | App Router, RSC, data patterns               |
-| OWASP Security Review  | `/owasp-security-review`  | Top 10:2025 vulnerability checklist          |
-| PostgreSQL             | `/postgresql`             | Queries, schemas, indexes, JSONB             |
-| React Best Practices   | `/react-best-practices`   | React 19 performance, rendering              |
-| Service Worker         | `/service-worker`         | PWA caching, push notifications              |
-| TypeScript Conventions | `/typescript-conventions` | Strict config, patterns, best practices      |
-| UI/UX Guidelines       | `/ui-ux-guidelines`       | Accessibility, layout, forms                 |
+### Skills (21)
+
+| Skill                  | Slug                      | Domain                                            |
+| ---------------------- | ------------------------- | ------------------------------------------------- |
+| BullMQ                 | `/bullmq`                 | Redis job queues, workers, flows, schedulers      |
+| Codebase Adapter       | `/codebase-adapter`       | Adapt plugin to your project on installation      |
+| Composition Patterns   | `/composition-patterns`   | React compound components, render props           |
+| Conventional Commits   | `/conventional-commits`   | Commit message spec, types, SemVer — with live staged diff |
+| Core Web Vitals        | `/core-web-vitals`        | LCP, INP, CLS reference + HTML report generator  |
+| Debug                  | `/debug`                  | Full-stack debugging workflow, multi-agent triage |
+| Docker                 | `/docker`                 | Dockerfiles, compose, optimization, security      |
+| Drizzle ORM            | `/drizzle-pg`             | PostgreSQL ORM schemas, queries, migrations       |
+| Execute Task           | `/execute-task`           | Orchestrate agents to implement a task file       |
+| Fastify Best Practices | `/fastify-best-practices` | Routes, plugins, hooks, validation                |
+| Generate PRD           | `/generate-prd`           | Product Requirements Documents from descriptions  |
+| Generate Task          | `/generate-task`          | Break PRD features into agent-ready task files    |
+| ioredis                | `/ioredis`                | Redis client, pipelines, Pub/Sub, Cluster         |
+| Next.js Best Practices | `/nextjs-best-practices`  | App Router, RSC, data patterns                    |
+| OWASP Security Review  | `/owasp-security-review`  | Top 10:2025 vulnerability checklist               |
+| PostgreSQL             | `/postgresql`             | Queries, schemas, indexes, JSONB                  |
+| React Best Practices   | `/react-best-practices`   | React 19 performance, rendering                   |
+| Service Worker         | `/service-worker`         | PWA caching, push notifications                   |
+| TanStack Query         | `/tanstack-query`         | React Query v5, caching, SSR/hydration            |
+| TypeScript Conventions | `/typescript-conventions` | Strict config, patterns, best practices           |
+| UI/UX Guidelines       | `/ui-ux-guidelines`       | Accessibility, layout, forms                      |
 
 ---
 
-## Installation
+## Workflow
+
+This is the recommended end-to-end flow — from a blank project to a committed feature:
 
-### Method 1: skills.sh (works with Claude Code, Cursor, Windsurf)
+### 1. Install the plugin
 
 ```bash
-# Install all skills
-npx skills add jgamaraalv/ts-dev-kit
+/plugin marketplace add jgamaraalv/ts-dev-kit
+/plugin install ts-dev-kit@ts-dev-kit
+```
 
-# List available skills
-npx skills add jgamaraalv/ts-dev-kit --list
+### 2. Adapt to your project (recommended)
 
-# Install a specific skill
-npx skills add jgamaraalv/ts-dev-kit --skill fastify-best-practices
+Run once after installing to align agents and skills with your actual stack, package names, paths, and MCPs:
 
-# Install globally
-npx skills add jgamaraalv/ts-dev-kit --global
+```
+/codebase-adapter
 ```
 
-> **Note:** skills.sh installs skills only, not agents.
+The skill reads your `package.json`, lockfile, `.claude/agents/`, and MCP config, then surgically patches the plugin's agent and skill files to match your project — without touching any workflow logic.
+
+### 3. Define what to build
+
+Generate a PRD from a description:
+
+```
+/generate-prd Add a user notification system that sends emails and in-app alerts
+```
+
+Then break it into agent-ready task files:
+
+```
+/generate-task
+```
+
+This produces structured task files with acceptance criteria, affected packages, quality gate commands, and a suggested agent.
+
+### 4. Execute the task
+
+```
+/execute-task tasks/notifications-api.md
+```
+
+The skill picks the right execution mode (single-agent or multi-agent), dispatches the appropriate agents, and runs quality gates (typecheck, lint, test) before declaring the task done.
 
-### Method 2: Claude Code Plugin (agents + skills)
+### 5. Commit
+
+```
+/conventional-commits
+```
+
+The skill pre-injects your staged diff and the last 8 commits so Claude sees the actual changes before suggesting a message — no copy-pasting needed.
+
+---
+
+## Installation
+
+### Method 1: Claude Code Plugin (agents + skills)
 
 ```bash
 /plugin marketplace add jgamaraalv/ts-dev-kit
@@ -84,6 +128,21 @@ Or via CLI:
 claude plugin install ts-dev-kit --scope user
 ```
 
+### Method 2: skills.sh (skills only — works with Claude Code, Cursor, Windsurf)
+
+```bash
+# Install all skills
+npx skills add jgamaraalv/ts-dev-kit
+
+# Install a specific skill
+npx skills add jgamaraalv/ts-dev-kit --skill fastify-best-practices
+
+# Install globally
+npx skills add jgamaraalv/ts-dev-kit --global
+```
+
+> **Note:** skills.sh installs skills only, not agents.
+
 ### Method 3: npm
 
 ```bash
@@ -104,12 +163,14 @@ claude --plugin-dir ./ts-dev-kit
 
 Some agents and skills reference external MCP tools for documentation lookup, browser debugging, E2E testing, and web fetching. These are **optional** — skills degrade gracefully without them — but installing them unlocks the full experience.
 
-| MCP Server    | Used By                                  | Purpose                              |
-| ------------- | ---------------------------------------- | ------------------------------------ |
-| context7      | Most skills (doc lookup)                 | Query up-to-date library docs        |
-| playwright    | playwright-expert, debugger, test-generator | Browser automation and E2E testing |
-| chrome-devtools | debugger                               | Frontend debugging, screenshots      |
-| firecrawl     | task skill                               | Web fetching and scraping            |
+| MCP Server      | Used by                                          | Purpose                              |
+| --------------- | ------------------------------------------------ | ------------------------------------ |
+| context7        | Most skills (doc lookup)                         | Query up-to-date library docs        |
+| playwright      | playwright-expert, debugger, test-generator      | Browser automation and E2E testing   |
+| chrome-devtools | debugger                                         | Frontend debugging, screenshots      |
+| firecrawl       | execute-task                                     | Web fetching and scraping            |
+| sentry          | debugger, debug skill                            | Error tracking and stack traces      |
+| posthog         | debugger                                         | User impact and error frequency      |
 
 ### Installing as Claude Code plugins
 
@@ -136,26 +197,21 @@ claude mcp add firecrawl --env FIRECRAWL_API_KEY=your-key -- npx -y firecrawl-mc
 
 ---
 
-## Customizing for Your Project
-
-This kit ships with a project orchestration template at `docs/rules/orchestration.md.template`. It defines quality gates, workspace commands, and dependency ordering that you can adapt to your own monorepo or project.
+## Dynamic Context Injection
 
-To use it:
+Several skills use the `!`command`` syntax to pre-inject live data before Claude receives the prompt. This means Claude already has the real context when it starts — no manual copy-pasting required.
 
-1. Copy the template into your project:
-   ```bash
-   cp node_modules/ts-dev-kit/docs/rules/orchestration.md.template \
-      .claude/rules/orchestration.md
-   ```
-2. Open `.claude/rules/orchestration.md` and replace the `@myapp/*` placeholders with your actual workspace package names.
-3. Update the dependency graph to match your monorepo structure.
-4. Adjust the quality gate commands to match your project's tooling (e.g., swap `yarn` for `pnpm` or `npm`).
+| Skill | What gets injected |
+| ----- | ------------------ |
+| `/conventional-commits` | Staged diff summary, full staged diff, last 8 commit messages |
+| `/debug` | Last 10 git commits, working tree status |
+| `/codebase-adapter` | Working directory, lockfile, installed agents, MCP servers, `package.json` |
 
 ---
 
 ## Tech Stack Covered
 
-TypeScript, Fastify 5, Next.js (App Router), React 19, PostgreSQL, Redis (ioredis), BullMQ, Drizzle ORM, Docker, Playwright, WCAG 2.1
+TypeScript, Fastify 5, Next.js (App Router), React 19, PostgreSQL 16, Redis (ioredis), BullMQ, Drizzle ORM, TanStack Query v5, Docker, Playwright, Service Workers, Core Web Vitals, WCAG 2.1, OWASP Top 10:2025, Tailwind CSS v4
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jgamaraalv/ts-dev-kit",
-  "version": "2.3.0",
-  "description": "Claude Code plugin: 13 agents + 16 skills for TypeScript fullstack development",
+  "version": "3.0.0",
+  "description": "Claude Code plugin: 15 agents + 21 skills for TypeScript fullstack development",
   "author": "jgamaraalv",
   "license": "MIT",
   "repository": {

package/skills/codebase-adapter/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: codebase-adapter
+description: "Adapts ts-dev-kit plugin files to the host project where it is installed. Use when: (1) installing ts-dev-kit in a new project for the first time, (2) project tech stack or structure has changed, (3) agents reference wrong paths, unavailable skills, or missing MCPs, (4) the user says 'adapt the plugin', 'configure ts-dev-kit for this project', 'sync plugin to this codebase', or 'update plugin context'. Surgically edits specific sections in plugin skills and agent definitions — domain area tables, skill/MCP references, quality gate commands, project paths, and package names — without touching any workflow logic, execution protocols, or dispatch patterns."
+disable-model-invocation: true
+argument-hint: "[optional: path to project root — defaults to current directory]"
+allowed-tools: Bash(ls *), Bash(cat *), Bash(node *), Bash(python3 *)
+---
+
+<system>
+You are a plugin configuration specialist. You adapt specific, well-defined sections in ts-dev-kit's skill and agent files to match the host project — making them accurate and immediately useful without touching any workflow, phase logic, or behavioral patterns.
+</system>
+
+<context>
+**User-provided path:** $ARGUMENTS
+
+**Pre-injected project snapshot (verify in phase 2 — do not skip discovery):**
+
+Working directory: !`pwd`
+
+Lockfile detected: !`ls bun.lock pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null | head -1 || echo "none"`
+
+Agents installed: !`ls .claude/agents/ 2>/dev/null | tr '\n' ' ' || echo "(not found)"`
+
+MCP servers configured: !`python3 -c "import json; s=json.load(open('.claude/settings.json')); print(', '.join(s.get('mcpServers',{}).keys()) or '(none)')" 2>/dev/null || echo "(not found)"`
+
+package.json:
+!`cat package.json 2>/dev/null || echo "(not found)"`
+</context>
+
+<boundaries>
+**You MAY edit:**
+- `<domain_areas>` table in `execute-task` — agent names and key skills per sub-area
+- `<skill_map>` in `execute-task` — which skills map to which sub-areas
+- `<available_mcps>` in `execute-task` — only MCPs actually configured in this project
+- `skills:` frontmatter list in agent definitions
+- Quality gate command examples in agent bodies (e.g., `yarn workspace @myapp/api test`)
+- Project path references in agent bodies (e.g., `apps/api/src/routes/`)
+- Package name references in agent bodies (e.g., `@myapp/api`, `@myapp/shared`)
+- Tech-specific import/version notes in agent bodies (Zod v3 vs v4, ESM flag)
+- Workspace command pattern in `generate-task` (e.g., `yarn workspace <name>` → `pnpm --filter <name>`)
+
+**You MUST NOT change:**
+- Any `<phase_*>` logic or step sequences
+- Dispatch protocols, decomposition rules, execution mode decisions
+- Core agent principles, role descriptions, or behavior narratives
+- Output template formats or section headers
+- Skill descriptions or their trigger conditions
+- XML tag structures (`<workflow>`, `<domain_areas>`, `<skill_map>`, etc.)
+</boundaries>
+
+<workflow>
+
+<phase_1_locate_plugin>
+Find the plugin root. Try in order:
+1. `skills/execute-task/SKILL.md` exists in current directory → user is inside the ts-dev-kit repo.
+2. `node_modules/@jgamaraalv/ts-dev-kit/` → installed via npm.
+3. Search upward and in siblings for a directory containing `plugin.json` with `"name": "ts-dev-kit"`.
+
+Store the resolved plugin root. All edits in phases 3–5 use paths relative to it.
+</phase_1_locate_plugin>
+
+<phase_2_project_discovery>
+Determine the target project root (`$ARGUMENTS` if provided, otherwise current working directory).
+
+Discover with Read, Glob, Grep — verify everything, assume nothing.
+
+**Package manager** — detect from lockfile: `bun.lock` → bun, `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm.
+
+**Monorepo** — check for `workspaces` in `package.json`, `pnpm-workspace.yaml`, or `turbo.json`. Record workspace names and their paths.
+
+**Tech stack** — read `package.json` dependencies in root and each workspace:
+- HTTP framework: Fastify, Express, Hono, Elysia, or none
+- ORM/DB: Drizzle, Prisma, Kysely + database type (PostgreSQL, MySQL, SQLite)
+- Frontend: Next.js (detect App Router via `app/` directory), Vite + React, or none
+- Validation: Zod (check version — v3 imports `from "zod"`, v4 imports `from "zod/v4"`), Valibot
+- Queue: BullMQ, or none
+- Cache: ioredis, @upstash/redis, or none
+- Testing: Vitest or Jest; Playwright or Cypress
+- Docker: check for `Dockerfile` or `docker-compose.yml`
+
+**Project paths** (verify with Glob — record exact paths):
+- Backend source root (e.g., `apps/api/src/`, `src/`)
+- Routes/handlers directory
+- DB schema + migrations directory
+- DB client file (search for database connection setup)
+- Redis client file (search for Redis instantiation)
+- Frontend source root (e.g., `apps/web/`, `src/`)
+- Shared package: directory path and package name (e.g., `packages/shared/`, `@acme/shared`)
+
+**Quality gates** — read `scripts` from each workspace's `package.json`:
+- typecheck, lint, test, build command names
+- Compose the full run command per workspace (e.g., `pnpm --filter @acme/api typecheck`)
+
+**Available skills** — list directories in `[plugin-root]/skills/`
+
+**Available agents** — list files in `[plugin-root]/.claude/agents/`
+
+**Available MCPs** — read `.claude/settings.json` in project root (and `~/.claude/settings.json` as fallback). Extract `mcpServers` keys.
+</phase_2_project_discovery>
+
+<phase_3_adapt_execute_task>
+Edit `[plugin-root]/skills/execute-task/SKILL.md`.
+
+**`<domain_areas>` block (lines between the opening and closing tags)**
+
+Rebuild the Backend and Frontend tables:
+- "Agent type" column: only include agents whose `.md` file exists in `[plugin-root]/.claude/agents/`
+- "Key skills" column: only include skills whose directory exists in `[plugin-root]/skills/` AND are relevant to the discovered tech stack
+- Remove rows for sub-areas with no matching tech (e.g., remove "Queues" row if BullMQ is absent; remove "Pages/routing" row if no frontend framework is detected)
+- Keep the "When" column text unchanged
+- Keep the surrounding narrative text and the Cross-cutting specialists table unchanged
+
+**`<skill_map>` block**
+
+Update each sub-area's skill list:
+- Remove skills not present in `[plugin-root]/skills/`
+- Remove skills not relevant to discovered tech (e.g., remove `/bullmq` if BullMQ not installed)
+- Keep the exact slash-command format (e.g., `/drizzle-pg`, `/fastify-best-practices`)
+
+**`<available_mcps>` block**
+
+Replace the bullet list with only MCPs found in `mcpServers`. Keep the same format: `- [name] — [one-line purpose]`. If context7 is configured, always keep its usage instructions below the list intact.
+
+**`<required_skills>` example block**
+
+Update the example `Skill()` calls to reflect the project's actual primary backend skills (e.g., replace `fastify-best-practices` if Fastify is not the framework).
+</phase_3_adapt_execute_task>
+
+<phase_4_adapt_agents>
+For each file in `[plugin-root]/.claude/agents/`:
+
+**`skills:` frontmatter list**
+Remove skills not installed in `[plugin-root]/skills/` or not relevant to the discovered tech stack. Do not add skills not already listed. If all skills remain valid, skip this file.
+
+**Quality gate command examples**
+Find patterns like `yarn workspace @myapp/api test` or `yarn workspace @myapp/api tsc`. Replace with the actual workspace run command composed in phase 2. Use real workspace package names where known.
+
+**Project path references**
+Find and replace generic placeholder paths with actual discovered paths:
+| Placeholder | Replace with |
+|-------------|-------------|
+| `apps/api/src/` | actual backend source root |
+| `apps/api/src/routes/` | actual routes directory |
+| `apps/api/src/lib/db.ts` | actual DB client file path |
+| `apps/api/src/lib/redis.ts` | actual Redis client file path |
+| `packages/shared/src/` | actual shared package source path |
+
+**Package name references**
+Replace placeholder names with actual package names:
+| Placeholder | Replace with |
+|-------------|-------------|
+| `@myapp/api` | actual API workspace package name |
+| `@myapp/shared` | actual shared workspace package name |
+
+**Tech-specific notes**
+- Zod import: update to match discovered version (`from "zod"` for v3, `from "zod/v4"` for v4)
+- ESM flag: match `"type": "module"` presence in the workspace's `package.json`
+
+Skip any agent where none of the above patterns are found — do not force edits.
+</phase_4_adapt_agents>
+
+<phase_5_adapt_generate_task>
+Edit `[plugin-root]/skills/generate-task/SKILL.md`.
+
+Find the workspace command pattern example (text like `yarn workspace <name> <script>`, `pnpm --filter <name> <script>`). Replace all occurrences with the actual package manager syntax discovered in phase 2. Use `<name>` and `<script>` as placeholders where the real values would vary.
+</phase_5_adapt_generate_task>
+
+<phase_6_update_claude_md>
+Append a "## Claude Code Workflow Architecture" section to the project's `CLAUDE.md` (located at the project root). If `CLAUDE.md` does not exist, create it with only this section. If the section already exists, replace it in-place with the updated version.
+
+Use the data already gathered in phases 1–2 to fill in the values:
+
+**Agent count** — count `.md` files in the project's `.claude/agents/` directory (this includes both plugin-installed agents and any locally defined agents).
+
+**Skill count** — count directories in the project's `.claude/skills/` directory (this includes both plugin-installed skills and any locally defined skills).
+
+**agent-memory** — check whether `agent-memory/` exists at the project root. If it does, count its subdirectories and note which agents are excluded (agents without a matching subdirectory).
+
+**Paths** — use the actual plugin-root-relative paths discovered in phase 2 (e.g., real `skills/`, `agents/`, `.claude/` locations).
+
+Generate the section using this template, substituting bracketed placeholders with real values:
+
+```markdown
+## Claude Code Workflow Architecture
+
+### Content Layout
+
+\`\`\`
+.claude/
+  agents/          ← [AGENT_COUNT] agent definitions (markdown, YAML frontmatter)
+  skills/          ← [SKILL_COUNT] skill directories (symlinked from skills/)
+  settings.local.json  ← Permission allowlist for Claude Code
+
+.claude-plugin/
+  plugin.json      ← Claude Code plugin manifest
+  marketplace.json ← Marketplace listing metadata
+
+agents/            ← Published copy of .claude/agents (included in npm package)
+[AGENT_MEMORY_LINE]
+skills/            ← [SKILL_COUNT] skill directories (each has SKILL.md + optional references/ and scripts/)
+\`\`\`
+
+### Agent Definitions (\`.claude/agents/*.md\`)
+
+Each agent is a single markdown file with YAML frontmatter:
+
+\`\`\`yaml
+---
+name: agent-name
+color: named-color       # Visual identification in Claude Code UI
+description: "..."
+skills:                  # Optional — skills loaded when agent is invoked
+  - skill-slug
+---
+\`\`\`
+
+Body contains: role description, core principles, workflow steps, quality gates, output format, and a reference to \`agent-memory/<name>/MEMORY.md\`.
+
+### Skill Definitions (\`skills/<name>/\`)
+
+Each skill directory contains:
+- \`SKILL.md\` — main content with YAML frontmatter (\`name\`, \`description\`, optional \`argument-hint\`, optional \`allowed-tools\`)
+- \`references/\` — deep-dive sub-files linked from SKILL.md
+- \`scripts/\` — optional executables Claude can run (Python, bash) for visual output or automation
+```
+
+Where `[AGENT_MEMORY_LINE]` is:
+- If `agent-memory/` exists: `agent-memory/      ← [SUBDIR_COUNT] persistent memory directories (one per agent[EXCLUSION_NOTE])`
+  - `[EXCLUSION_NOTE]` = `, excluded: [list agents without a subdirectory]` if any are missing, otherwise omit
+- If `agent-memory/` does not exist: omit that line entirely
+</phase_6_update_claude_md>
+
+<phase_7_report>
+Produce the completion report using the template in [template.md](template.md).
+</phase_7_report>
+
+</workflow>

package/skills/codebase-adapter/template.md

@@ -0,0 +1,25 @@
+## Codebase Adapter — Completed
+
+**Project**: [name] | [monorepo / single package] | [package manager]
+**Plugin root**: [resolved path]
+
+### Files edited
+| File | Sections changed |
+|------|-----------------|
+| skills/execute-task/SKILL.md | domain_areas, skill_map, available_mcps |
+| .claude/agents/api-builder.md | paths, package names, quality gates |
+| ... | ... |
+
+### Files skipped
+| File | Reason |
+|------|--------|
+| .claude/agents/docker-expert.md | No Docker files found |
+| ... | ... |
+
+### Discoveries
+- **Backend**: [framework] at [path], package [name]
+- **Frontend**: [framework] at [path], package [name]
+- **Shared**: [name] at [path]
+- **Quality gates**: [pm] commands — [typecheck / lint / test / build]
+- **MCPs configured**: [list or "none"]
+- **Skills available**: [N] skills | **Agents available**: [N] agents

package/skills/conventional-commits/SKILL.md

@@ -1,8 +1,20 @@
 ---
 name: conventional-commits
 description: "Write, review, and validate commit messages following the Conventional Commits v1.0.0 specification. Use when: (1) crafting a git commit message for any change, (2) reviewing or correcting an existing commit message, (3) choosing the right commit type for a change, (4) deciding how to mark a breaking change, (5) writing multi-line commits with body and footers, or (6) understanding how commits map to SemVer bumps (PATCH/MINOR/MAJOR). Covers all standard types: feat, fix, docs, chore, refactor, perf, test, build, ci, style, revert."
+allowed-tools: Bash(git *)
 ---
 
+<live_context>
+**Staged changes (summary):**
+!`git diff --cached --stat 2>/dev/null || echo "(nothing staged)"`
+
+**Staged diff:**
+!`git diff --cached 2>/dev/null | head -300 || echo "(nothing staged)"`
+
+**Recent commits (style reference):**
+!`git log --oneline -8 2>/dev/null || echo "(no commits yet)"`
+</live_context>
+
 ## Table of Contents
 
 - [Format](#format)