thomas-agentkit 0.7.0 → 0.9.0-alpha.0

package/templates/AGENTS.md

@@ -10,24 +10,44 @@ This is the primary instruction file for AI coding agents working in this reposi
 
 Follow this file first. It defines the repository-wide operating rules for agents.
 
-Use companion guides only when relevant to the task. Do not load or restate every guide by default.
+Use companion guides only when a trigger below applies. Do not load or restate every guide by default.
 
-## Reference Map
+For routine bugfixes and small features, do not open `WORKFLOWS.md`, planning templates, or optional guides unless a trigger applies or the user asks.
 
-Read these files when the task calls for them:
+## When To Use Other Guides
 
-| Task type | Read first |
+| Trigger | Action |
 | --- | --- |
-| Any implementation | `AGENTS.md` |
-| Code quality, refactors, review, dependencies | `CODE-QUALITY.md` |
-| Planning, branching, implementation, review, release | `WORKFLOWS.md` |
-| Final handoff or PR explanation | `CHANGE-EXPLANATION.md` |
-| UI, styling, layout, navigation, components | `[design system path, e.g. docs/design-system.md]` |
-| Tests, fixtures, mocks, QA strategy | `TESTING.md` |
-| Auth, permissions, secrets, PII, data handling | `SECURITY-CHECKLIST.md` |
-| Complex engineering execution | `IMPLEMENTATION-BRIEF-TEMPLATE.md` |
-| Product or user-facing feature definition | `PRD-TEMPLATE.md` |
-| Stack-specific work | `STACK.md` when present |
+| Any file edits (final message) | Use the change-explanation format in **After Coding (Required)**; see `CHANGE-EXPLANATION.md` for detail |
+| UI, components, styling, layout | Read `[design system path, e.g. docs/design-system.md]` or `DESIGN-SYSTEM.md` |
+| Review, refactor, dependencies | Read `CODE-QUALITY.md` |
+| Tests, fixtures, QA strategy | Read `TESTING.md` if present |
+| Auth, permissions, secrets, PII | Read `SECURITY-CHECKLIST.md` if present |
+| Stack-specific code | Read `STACK.md` if present |
+| User or issue requests a PRD | Create from `PRD-TEMPLATE.md` under `[briefs path, e.g. docs/briefs]` |
+| User or issue requests an implementation brief | Create from `IMPLEMENTATION-BRIEF-TEMPLATE.md` under `[briefs path, e.g. docs/briefs]` |
+| Release or branching process (optional) | Read `WORKFLOWS.md` if present |
+
+### Optional Guides (Full Template Set)
+
+These files are not installed with the standard template set. Do not assume they exist unless present in the repository:
+
+- `TESTING.md`
+- `SECURITY-CHECKLIST.md`
+- `PRD-TEMPLATE.md`
+- `IMPLEMENTATION-BRIEF-TEMPLATE.md`
+- `WORKFLOWS.md`
+
+## Planning Artifacts
+
+Use this decision tree before creating planning documents:
+
+- **Tiny obvious fix** — implement directly; no PRD or brief required.
+- **Product uncertainty** — create a PRD from `PRD-TEMPLATE.md` only when the user, issue, or task explicitly requests planning documentation. Save it under `[briefs path, e.g. docs/briefs]`.
+- **Multi-file engineering with meaningful risk** — create an implementation brief from `IMPLEMENTATION-BRIEF-TEMPLATE.md` only when the user, issue, or task explicitly requests it. Save it under `[briefs path, e.g. docs/briefs]`.
+- **Security-sensitive change** — follow `SECURITY-CHECKLIST.md` if present.
+
+Do not read planning templates on every task. Copy and fill them only when planning documentation is requested.
 
 ## Local Guidance
 
@@ -45,23 +65,23 @@ If a subdirectory contains its own `AGENTS.md` or equivalent local guidance, fol
 - Validate external input at system boundaries.
 - Keep public APIs and persisted data shapes stable unless the task requires a change.
 - Ask before destructive commands, broad refactors, schema changes, dependency additions, or security-sensitive changes.
-- Run the narrowest useful checks before handoff.
-- Explain completed work clearly using `CHANGE-EXPLANATION.md` when present.
+- Run the narrowest useful checks before finishing (use **Project Commands** below).
+- After any coding work that changes files, end with a change explanation per **After Coding (Required)**. Do not skip this for small fixes.
+- Watch for common AI mistakes: invented APIs or commands, placeholder logic that looks production-ready, client-only authorization, and tests that do not exercise changed behavior.
+- When reviewing or flagging issues, use severity: **Blocker** (must fix), **Concern** (should fix soon), **Suggestion** (optional).
+- For review, refactor, or dependency work, read `CODE-QUALITY.md` for the full checklist.
 
 ## Before Coding
 
 Before making meaningful code changes:
 
 1. Confirm the task, scope, and acceptance criteria.
-2. Check whether the task is linked to an issue in [issue tracker, e.g. Linear or GitHub Issues].
-3. For non-trivial work without an issue, ask whether one should be created before implementation.
-4. Create or switch to an appropriate branch when the workflow expects branches.
-5. Inspect nearby code, tests, and existing patterns.
-6. Read relevant companion guidance from the Reference Map.
-7. Identify the smallest complete approach.
-8. Ask for clarification if requirements, risk, or approval boundaries are unclear.
+2. Inspect nearby code, tests, and existing patterns.
+3. Read at most one triggered companion from **When To Use Other Guides** if it applies.
+4. For non-trivial work: link to or create an issue in [issue tracker, e.g. Linear or GitHub Issues] and use an appropriate branch when the project expects branches.
+5. Ask for clarification if requirements, risk, or approval boundaries are unclear.
 
-Tiny fixes can skip branch-and-brief ceremony when the change is obvious and low risk.
+Tiny fixes can skip issue-and-branch ceremony when the change is obvious and low risk.
 
 ## During Coding
 
@@ -74,7 +94,7 @@ While implementing:
 - Add or update tests when behavior changes.
 - For UI work, follow `[design system path, e.g. docs/design-system.md]` and preserve existing interaction patterns.
 - For stack-specific work, read `STACK.md` when present.
-- Document meaningful decisions in the implementation brief, PR, or final handoff.
+- Document meaningful decisions in the change explanation when they matter.
 
 ## Approval Boundaries
 
@@ -87,20 +107,33 @@ Ask before:
 - Performing broad refactors or large formatting-only rewrites.
 - Editing generated, vendored, or external-source files unless the task explicitly requires it.
 
+## After Coding (Required)
+
+If you modified any files in the repository, your **final message** must include a change explanation.
+
+This is how developers catch up on agent work. It is required for bugfixes, refactors, and small edits—not only large features or PRs. Scale section depth to the change; do not omit the explanation because the diff is small.
+
+Do not write a separate change-explanation file unless the project asks for one. Use this structure in your reply:
+
+- **Summary** — outcome in plain language (behavior delivered, not only files touched).
+- **What changed** — main files or areas; what, why, and how each fits existing patterns.
+- **Key decisions** — approach, alternatives, trade-offs (skip when straightforward).
+- **Verification** — checks run and results; note any skipped checks and why.
+- **Risks or limitations** — merge blockers, untested paths, follow-up (use "None identified" for trivial low-risk fixes when appropriate).
+- **Suggested review focus** — where the developer should look first.
+
+See `CHANGE-EXPLANATION.md` for examples and style rules.
+
 ## Before Finishing
 
 Before marking work complete:
 
 1. Re-read the original request and acceptance criteria.
 2. Confirm the implementation satisfies the requested scope.
-3. Run the narrowest relevant checks:
-   - `[test command, e.g. npm test]`
-   - `[lint command, e.g. npm run lint]`
-   - `[build/check command, e.g. npm run build]` for larger changes
+3. Run the narrowest relevant checks from **Project Commands**.
 4. Review the diff for unrelated changes.
 5. Confirm no unnecessary dependencies, schema changes, theme changes, or broad refactors were introduced.
-6. Summarize what changed, why it changed, checks run, risks, and follow-up work.
-7. If `CHANGE-EXPLANATION.md` exists, follow it for the final handoff.
+6. Include the change explanation from **After Coding (Required)** in your final message.
 
 ## Project Commands
 
@@ -125,7 +158,9 @@ Never commit API keys, tokens, private keys, or local `.env` values. Keep secret
 
 ## Stack
 
-Document the real stack for this project:
+When `STACK.md` is present (for example after a preset install), read it before changing stack-specific code.
+
+Otherwise document the real stack for this project:
 
 - [Primary framework]
 - [Language/runtime]

package/templates/CHANGE-EXPLANATION.md

@@ -2,13 +2,25 @@
 
 ## Purpose
 
-Use this guide when explaining completed work to the developer.
+Use this guide **after every task that modifies repository files**.
 
-The goal is to help the developer understand what changed, why it changed, how the implementation works, what was verified, and what deserves review attention.
+The goal is to help the developer get up to speed quickly: what changed, why it changed, how it works, what was verified, and what deserves review attention.
 
-This is a reusable handoff guide. Do not create a new change-explanation file for every task unless the project explicitly asks for one.
+This is a **response format** for agent messages. Do **not** create a new markdown file per task unless the project explicitly asks for one.
 
-## Handoff Format
+Research-only tasks that do not edit files do not require this format.
+
+## When Required
+
+| Situation | Change explanation |
+| --- | --- |
+| Any bugfix, feature, refactor, config, or doc edit in the repo | **Required** — follow this guide in your final message |
+| Research, options, or questions with no file edits | Not required |
+| User asks only to explain existing code (no edits) | Not required |
+
+Scale depth to the size of the change. A one-line fix still needs a short explanation; a large feature needs full sections.
+
+## Change Explanation Format
 
 ### Summary
 
@@ -35,6 +47,8 @@ Include when relevant:
 - trade-offs or constraints
 - assumptions made because requirements were unclear
 
+Skip this section when the change is straightforward and has no meaningful trade-offs.
+
 ### Verification
 
 List checks run, such as:
@@ -58,6 +72,8 @@ Call out anything the developer should know before merging or shipping:
 - performance concerns
 - follow-up cleanup
 
+Use "None identified" when appropriate for very small, low-risk changes.
+
 ### Suggested Review Focus
 
 Tell the developer where to focus review attention.

package/templates/CLAUDE.md

@@ -2,18 +2,8 @@
 
 Claude Code guidance for this repository.
 
-Follow `AGENTS.md` first. Treat it as the primary source of truth for project rules, workflows, quality standards, and handoff expectations.
+Follow `AGENTS.md` first. It is the source of truth for operating rules, triggers for companion guides, planning artifacts, and required change explanations.
 
-When relevant, also read:
-
-- `CODE-QUALITY.md`
-- `WORKFLOWS.md`
-- `CHANGE-EXPLANATION.md`
-- `DESIGN-SYSTEM.md`
-- `TESTING.md`
-- `SECURITY-CHECKLIST.md`
-- `STACK.md`
-
-Keep context focused. Do not load companion files unless they are relevant to the task.
+Do not load companion files for routine coding. Read or create from other guides only when `AGENTS.md` **When To Use Other Guides** applies or the user asks.
 
 Do not duplicate repository rules here. Update `AGENTS.md` or the relevant companion guide instead.

package/templates/CODE-QUALITY.md

@@ -43,17 +43,7 @@ Use clear severity when reviewing or explaining issues:
 
 Run the narrowest useful checks first, then broaden verification for larger changes.
 
-Document project commands here:
-
-```bash
-npm test
-npm run lint
-npm run build
-```
-
-Remove commands that do not apply.
-
-For deeper testing guidance, use `TESTING.md` when present.
+Use the commands documented in `AGENTS.md` **Project Commands**. For deeper testing strategy, read `TESTING.md` when present.
 
 ## Dependency Policy
 
@@ -78,14 +68,14 @@ Watch for common AI-generated issues:
 - client-only validation or authorization for sensitive actions
 - excessive comments explaining obvious code instead of clarifying intent
 
-## Handoff Standard
+## Change Explanation Standard
 
-Every completed change should include:
+Every completed change that edits files must end with a developer-facing explanation that follows `CHANGE-EXPLANATION.md` in the agent's final message.
+
+At minimum, cover:
 
 - What changed.
 - Why it changed.
 - What checks were run.
 - Known risks or limitations.
 - Follow-up work, if any.
-
-Use `CHANGE-EXPLANATION.md` when present for the final developer-facing handoff.

package/templates/IMPLEMENTATION-BRIEF-TEMPLATE.md

@@ -1,5 +1,7 @@
 # Implementation Brief
 
+Copy this file into `[briefs path, e.g. docs/briefs]` when the user, issue, or task explicitly requests an implementation brief. Agents should not read this template on every task.
+
 ## Title
 
 [Feature or fix name]

package/templates/PRD-TEMPLATE.md

@@ -1,5 +1,7 @@
 # PRD Template
 
+Copy this file into `[briefs path, e.g. docs/briefs]` when the user, issue, or task explicitly requests a PRD. Agents should not read this template on every task.
+
 ## Title
 
 [Project or feature name]

package/templates/SECURITY-CHECKLIST.md

@@ -76,9 +76,9 @@ Avoid these common AI-generated security problems:
 - adding permissive CORS or CSP rules to fix local issues
 - assuming user IDs, workspace IDs, or tenant IDs from untrusted input
 
-## Handoff Requirements
+## Change Explanation Requirements
 
-For security-sensitive work, explicitly report:
+For security-sensitive work, include in the change explanation after coding:
 
 - security-sensitive files or behavior changed
 - tests or checks run

package/templates/TESTING.md

@@ -79,7 +79,7 @@ Avoid these common AI-generated testing problems:
 
 ## Reporting Verification
 
-In the final handoff, include:
+In the change explanation after coding work, include:
 
 - checks run
 - whether they passed

package/templates/WORKFLOWS.md

@@ -2,95 +2,22 @@
 
 ## Purpose
 
-This document defines lightweight workflows for research, planning, implementation, review, and release.
+Optional process reference for repositories that installed the **full** AgentKit template set.
 
-Keep this file practical. Delete sections that do not apply to the project.
+`AGENTS.md` is the canonical source of truth for daily agent work. Use this file only when you need a quick map of which companion guide fits a situation.
 
 ## Choose The Right Document
 
 | Situation | Use |
 | --- | --- |
-| Tiny obvious fix | No formal planning doc required |
-| User-facing feature or product uncertainty | `PRD-TEMPLATE.md` |
-| Known engineering work with multiple files or risks | `IMPLEMENTATION-BRIEF-TEMPLATE.md` |
-| UI, styling, layout, navigation, components | `DESIGN-SYSTEM.md` |
-| Security-sensitive change | `SECURITY-CHECKLIST.md` |
-| Test strategy or test implementation | `TESTING.md` |
-| Final handoff or PR explanation | `CHANGE-EXPLANATION.md` |
-
-## Research-Only Workflow
-
-Use this when the task asks for investigation, options, or recommendations without coding.
-
-1. Confirm the research question and scope.
-2. Inspect relevant code, docs, tests, and history.
-3. Use external sources only when current ecosystem knowledge is needed.
-4. Separate facts from recommendations.
-5. Summarize trade-offs, risks, and a recommended path.
-6. Do not edit files unless the task changes from research to implementation.
-
-## Planning Workflow
-
-Use a PRD for product or user-facing work that needs intent, requirements, and acceptance criteria.
-
-Use an implementation brief for engineering work that is already understood but needs a clear execution plan.
-
-Tiny fixes can skip formal planning when the change is obvious and low risk.
-
-## Branch Workflow
-
-- Prefer an issue-linked branch when available.
-- Use short, descriptive branch names:
-  - `feature/[short-name]`
-  - `fix/[short-name]`
-  - `chore/[short-name]`
-- Keep each branch focused on one coherent change.
-
-## Implementation Workflow
-
-1. Read the issue, PRD, or implementation brief.
-2. Inspect existing patterns and nearby tests.
-3. Read relevant companion guidance from `AGENTS.md`.
-4. Make the smallest complete change.
-5. Add or update tests where behavior changes.
-6. Run relevant checks.
-7. Review the diff before handoff.
-8. Explain the change using `CHANGE-EXPLANATION.md` when present.
-
-## Pause And Ask Triggers
-
-Pause and ask before:
-
-- expanding scope beyond the request
-- adding dependencies
-- changing schemas or migrations
-- changing auth, permissions, privacy, billing, or data retention behavior
-- running destructive commands
-- changing design tokens, themes, or foundational layout rules
-- performing broad refactors or formatting-only rewrites
-- removing tests or weakening validation
-
-## Review Workflow
-
-Review for correctness first, then maintainability, tests, UX, security, and style.
-
-Call out:
-
-- bugs or regressions
-- missing validation or error handling
-- missing authorization checks
-- overly broad abstractions
-- missing tests for changed behavior
-- UI states that are missing or inaccessible
-- unclear handoff, risks, or rollout notes
-
-## Release Workflow
-
-Before release:
-
-- Confirm tests and build pass.
-- Confirm docs match behavior.
-- Confirm environment variables and migrations are documented.
-- Confirm no secrets or local-only files are included.
-- Confirm changelog or release notes are updated when the project expects them.
-- Confirm rollback or mitigation steps for risky changes.
+| Daily implementation, approval boundaries, change explanations | `AGENTS.md` |
+| Tiny obvious fix | Implement directly; no formal planning doc |
+| User-facing feature or product uncertainty (planning requested) | Create from `PRD-TEMPLATE.md` under `[briefs path, e.g. docs/briefs]` |
+| Multi-file engineering with risk (planning requested) | Create from `IMPLEMENTATION-BRIEF-TEMPLATE.md` under `[briefs path, e.g. docs/briefs]` |
+| UI, styling, layout, navigation, components | `DESIGN-SYSTEM.md` or project design-system path |
+| Security-sensitive change | `SECURITY-CHECKLIST.md` if present |
+| Test strategy or test implementation | `TESTING.md` if present |
+| Review, refactor, dependencies | `CODE-QUALITY.md` |
+| Any task that edits repository files | Change-explanation format in `AGENTS.md` and `CHANGE-EXPLANATION.md` |
+
+For branching, implementation steps, review expectations, and release checks, follow `AGENTS.md`.

package/templates/skills/agentkit/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: agentkit
+description: Use when creating, syncing, auditing, repairing, or learning AgentKit-managed repository guidance and codebase changes in an agent session, especially after `agentkit skill install`, when `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, or `/agentkit learn` is requested, or when AGENTS.md, STACK.md, companion guides, managed blocks, commands, placeholders, AI tool adapters, recent diffs, or completed changes need context-aware maintenance or explanation.
+compatibility: Requires agentkit CLI and agentkit.config.json with installMode skill, or existing AgentKit-managed files with block markers.
+metadata:
+  author: thomas-agentkit
+  version: "1.0"
+---
+
+# AgentKit Skill
+
+Create, sync, audit, repair, and teach AgentKit-managed repository guidance and codebase changes using live repository context.
+
+## When to use
+
+- User ran `agentkit skill install`
+- User asks `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, or `/agentkit learn`
+- `AGENTS.md`, `STACK.md`, companion guides, or AI adapters are missing
+- Guidance has stale commands, stack details, project paths, placeholders, or broken references
+- Managed blocks need context-aware update, audit, or repair
+- User wants to understand recent codebase changes, a completed implementation, a diff, a bug fix, or the session
+
+## When not to use
+
+- User wants terminal template install -> direct them to CLI `agentkit init`
+- User wants terminal template update -> direct them to CLI `agentkit update` unless config says `installMode: skill`
+- Generic documentation requests unrelated to AgentKit guidance
+- Code review findings, debugging, or feature implementation requests
+- Short summaries that do not require a guided teaching workflow
+
+## Route
+
+Always read `references/file-contract.md` before editing or auditing AgentKit-managed files. Do not act from `SKILL.md` alone.
+
+1. User asks to **initialize** missing guidance files from repo context
+   → `references/init.md`
+
+2. User asks to **update** or **sync** existing guidance with current repo context
+   → `references/update.md`
+
+3. User asks to **doctor**, **audit**, **review**, **diagnose**, or **health check** guidance quality
+   → `references/doctor.md`
+
+4. User asks to **repair**, **fix malformed blocks**, **convert unmanaged guidance**, or **fix adapters**
+   → `references/repair.md`
+
+5. User asks to **learn**, **understand recent changes**, **explain the session**, **teach me what changed**, **ELI5**, **ELI14**, **explain like an intern**, or **check my understanding**
+   → `references/learn.md`
+
+6. Unsure which workflow applies
+   → If no guidance files exist: `references/init.md`
+   → If guidance exists but commands, stack, files, placeholders, adapters, or references are stale: `references/update.md`
+   → If user wants audit, doctor, health check, diagnosis, or review: `references/doctor.md`
+   → If managed blocks are malformed or unmanaged files need conversion: `references/repair.md`
+   → If user wants to understand completed changes or a session: `references/learn.md`
+
+## Non-negotiables
+
+- `AGENTS.md` is the source of truth; AI tool adapters stay thin pointers
+- Read the route reference and `references/file-contract.md` before file edits
+- Preserve user content **outside** AgentKit managed blocks
+- Skip unmanaged existing files unless conversion is explicitly requested
+- Defer malformed managed blocks to `references/repair.md`
+- Commands in guidance must come from `package.json` scripts or `agentkit.config.json` personalization — never invent scripts
+- Prefer repo facts over config personalization
+- Do not modify app source, lockfiles, package manifests, or CI config during AgentKit workflows
+- `/agentkit learn` is read-only by default and keeps learning checklists in the conversation unless the user explicitly asks for notes
+- CLI `agentkit init` installs **templates**; this skill's `agentkit init` **creates guidance files** — never confuse them
+
+## Gotchas
+
+| Gotcha | Reality |
+| --- | --- |
+| `installMode: skill` but no `.md` files yet | Expected after `agentkit skill install`; run `/agentkit init` |
+| `templateSet: minimal` | `AGENTS.md` only, plus selected adapters if explicitly configured |
+| `templateSet: standard` | Core companions only; not testing/security/workflow docs |
+| `templateSet: full` | Full guidance docs; adapters still follow `aiTools` |
+| AI tool adapters | Thin pointers to `AGENTS.md`; never duplicate full guidance |
+| `STACK.md` | Create/update when preset is configured, user asks, or stack is confidently inferred |
+| Existing unmanaged files | Skip unless user asks to convert |
+| Malformed managed blocks | Use `/agentkit repair` before update/refresh |
+| Learning workflow | `/agentkit learn` teaches from diffs and code; it does not create notes or files by default |
+| Docs-only guidance workflow | Does not require running project tests/builds |
+
+## Quick reference
+
+| User says | Load |
+| --- | --- |
+| "/agentkit init" / "set up AGENTS.md" | `references/init.md` |
+| "/agentkit update" / "sync guidance" | `references/update.md` |
+| "/agentkit doctor" / "audit AgentKit guidance" | `references/doctor.md` |
+| "/agentkit repair" / "fix managed blocks" | `references/repair.md` |
+| "/agentkit learn" / "teach me what changed" | `references/learn.md` |
+| Before any file edit | `references/file-contract.md` |

package/templates/skills/agentkit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AgentKit"
+  short_description: "Create, maintain, and learn repo guidance"
+  default_prompt: "Use $agentkit to initialize, sync, audit, repair, or learn repository guidance and changes."

package/templates/skills/agentkit/references/doctor.md

@@ -0,0 +1,133 @@
+# agentkit doctor (skill workflow)
+
+Audit AgentKit guidance quality against the current repository context and `references/file-contract.md`. This workflow is read-only by default.
+
+Use doctor when the user asks to audit, review, check, validate, diagnose, or inspect AgentKit guidance.
+
+## Preconditions
+
+- Read `references/file-contract.md` before auditing.
+- Read `agentkit.config.json` when present.
+- Inspect repository facts before judging guidance quality.
+- Do not edit files unless the user explicitly asks for fixes after the audit.
+
+## Non-negotiables
+
+- Report findings before suggesting fixes.
+- Do not modify guidance files by default.
+- Do not modify application source files, lockfiles, package manifests, or CI config.
+- Never invent missing scripts or assume commands exist.
+- Treat malformed managed blocks as blocking issues for update/refresh on that file.
+
+## Procedure
+
+### 1. Build Repo Profile
+
+Collect:
+
+- Project name and description from `package.json`, README, or directory name
+- Package manager from lockfiles
+- Scripts from `package.json`
+- Framework/runtime signals, such as Next.js, SvelteKit, Express, Convex, Vite, React, Node, TypeScript
+- Source layout, such as `src/`, `app/`, `pages/`, `convex/`, `test/`, `docs/`
+- Test, lint, build, typecheck, and dev tooling
+- UI/design system signals
+- Backend/data/auth signals
+- Existing docs, workflow files, PR templates, and agent guidance files
+
+Prefer repository facts over config personalization.
+
+### 2. Read AgentKit State
+
+Inspect:
+
+- `agentkit.config.json`
+- `AGENTS.md`
+- `STACK.md`
+- companion guidance files
+- AI tool adapters
+- managed block markers in every AgentKit guidance file
+
+Record:
+
+- Files present
+- Files missing for configured `templateSet`, `preset`, and `aiTools`
+- Files with valid managed blocks
+- Files without managed blocks
+- Files with malformed managed blocks
+- Companion references in `AGENTS.md`
+
+### 3. Audit Checks
+
+Check for:
+
+- Missing `AGENTS.md`
+- Missing files required by configured `templateSet`
+- Missing `STACK.md` when `preset` is configured or stack is confidently inferred
+- Missing AI adapters required by `aiTools`
+- Invalid or unknown config values
+- `installMode: template` when the user expects a skill-path workflow
+- Malformed managed block markers
+- Unmanaged existing guidance files that cannot be safely updated
+- Bracket placeholders left in AgentKit-managed content
+- Commands that do not match `package.json` scripts or explicit config/user personalization
+- Stale project name, description, source layout, stack, design, testing, security, or workflow guidance
+- `AGENTS.md` references to missing companion files
+- AI adapters that duplicate operating rules instead of pointing to `AGENTS.md`
+- Generic guidance that ignores obvious repository facts
+
+### 4. Severity
+
+Classify findings:
+
+- `Critical`: Update/refresh is unsafe or blocked, such as malformed managed blocks, missing `AGENTS.md`, or destructive-risk instructions.
+- `High`: Guidance is likely wrong in daily use, such as invalid commands, broken routing, missing required configured files, or adapter duplication.
+- `Medium`: Guidance is incomplete or stale, such as outdated stack/design/test/workflow details or missing optional companions.
+- `Low`: Polish issues, unclear assumptions, minor generic language, or non-blocking placeholders.
+
+If there are no findings, report that AgentKit guidance looks healthy and mention any residual uncertainty.
+
+### 5. Recommended Next Action
+
+Recommend one primary next action:
+
+- `/agentkit init` when configured guidance files are missing.
+- `/agentkit update` when managed guidance exists but facts are stale.
+- `/agentkit repair` when malformed managed blocks block safe updates.
+- Manual config edit when `agentkit.config.json` values are wrong.
+- No action when guidance is healthy.
+
+Do not perform the recommended action unless the user asks.
+
+### 6. Report Format
+
+Use this concise format:
+
+```md
+## AgentKit Doctor
+
+Status: Healthy | Needs attention | Blocked
+
+Critical
+- ...
+
+High
+- ...
+
+Medium
+- ...
+
+Low
+- ...
+
+Recommended next action:
+- ...
+
+Checked:
+- Config values used
+- Stack and package manager inferred
+- Commands inferred
+- Files inspected
+```
+
+Omit empty severity sections.