thomas-agentkit 0.6.1 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 AgentKit CLI bootstraps AI-agent-ready repositories.
 
-It installs reusable instructions, planning templates, review docs, design system rules, and workflow guidance for developers using Codex, Cursor, GitHub Copilot, Claude Code, and similar coding agents.
+It installs reusable agent instructions, workflow guides, quality checklists, design system rules, planning templates, and tool adapters for developers using Codex, Cursor, GitHub Copilot, Claude Code, and similar coding agents.
 
 AgentKit is not an AI agent. It is a small scaffolding tool for making repositories easier and safer to work on with AI-assisted development.
 
@@ -35,7 +35,7 @@ Accept defaults without prompts:
 npx thomas-agentkit init --yes
 ```
 
-`--yes` keeps installed templates generic and leaves placeholders for later editing.
+`--yes` installs the `standard` template set, keeps templates generic, and leaves placeholders for later editing.
 
 Preview changes without writing files:
 
@@ -127,14 +127,17 @@ npx thomas-agentkit --list-design-systems
 
 ## Installed Files
 
-AgentKit copies these bundled files into the target project:
+AgentKit can copy these bundled files into the target project:
 
 - `AGENTS.md`
+- `CHANGE-EXPLANATION.md`
 - `CLAUDE.md`
 - `CODE-QUALITY.md`
 - `DESIGN-SYSTEM.md`
 - `IMPLEMENTATION-BRIEF-TEMPLATE.md`
 - `PRD-TEMPLATE.md`
+- `SECURITY-CHECKLIST.md`
+- `TESTING.md`
 - `WORKFLOWS.md`
 - `.cursor/rules/agentkit.md`
 - `.github/copilot-instructions.md`
@@ -163,8 +166,8 @@ Interactive personalization only applies during `agentkit init` when files are c
 Template set mappings:
 
 - `minimal`: `AGENTS.md`
-- `standard`: `AGENTS.md`, `CODE-QUALITY.md`, `DESIGN-SYSTEM.md`, `WORKFLOWS.md`
-- `full`: all bundled templates
+- `standard`: `AGENTS.md`, `CHANGE-EXPLANATION.md`, `CODE-QUALITY.md`, `DESIGN-SYSTEM.md`, `.github/pull_request_template.md`
+- `full`: all bundled templates, including AI tool adapters and planning/testing/security guides
 
 AI tool mappings:
 
@@ -173,6 +176,8 @@ AI tool mappings:
 - `claude`: `CLAUDE.md`
 - `copilot`: `.github/copilot-instructions.md`
 
+AI tool adapters are thin compatibility files that point back to `AGENTS.md` as the source of truth. They are installed when selected through AI tools or when using the `full` template set.
+
 ## Presets
 
 Presets add stack-specific guidance without scaffolding framework app files.
@@ -263,3 +268,5 @@ AgentKit should stay:
 - safe by default
 - useful immediately
 - not overengineered
+
+Installed guidance is **AGENTS-first**: `AGENTS.md` is enough for daily coding, including required change explanations after file edits. Companion files are loaded on explicit triggers (UI, review, security, stack, planning when requested), not on every task. The `full` template set adds optional guides such as `WORKFLOWS.md`, `TESTING.md`, and planning templates.

package/dist/cli.js

@@ -47,7 +47,13 @@ const aiToolFiles = {
 };
 const templateSetFiles = {
     minimal: ["AGENTS.md"],
-    standard: ["AGENTS.md", "CODE-QUALITY.md", "DESIGN-SYSTEM.md", "WORKFLOWS.md"],
+    standard: [
+        "AGENTS.md",
+        "CHANGE-EXPLANATION.md",
+        "CODE-QUALITY.md",
+        "DESIGN-SYSTEM.md",
+        ".github/pull_request_template.md",
+    ],
     full: [],
 };
 const stackGuidance = {
@@ -390,7 +396,7 @@ function cleanPersonalizationValue(value) {
 }
 function getResolvedConfig(options) {
     const config = {
-        templateSet: options.templateSet ?? "full",
+        templateSet: options.templateSet ?? "standard",
         aiTools: options.aiTools ?? [],
         designSystem: effectiveDesignSystem(options.designSystem),
     };
@@ -565,10 +571,7 @@ async function resolveInitTemplateFiles(options) {
     if (options.files) {
         return options.files;
     }
-    if (options.templateSet || options.aiTools) {
-        return getSelectedTemplateFiles(options.templateSet ?? "full", options.aiTools ?? [], allTemplateFiles);
-    }
-    return allTemplateFiles;
+    return getSelectedTemplateFiles(options.templateSet ?? "standard", options.aiTools ?? [], allTemplateFiles);
 }
 async function installTemplates(targetArg, options) {
     const targetDir = path.resolve(process.cwd(), targetArg || ".");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
   "repository": {

package/templates/.cursor/rules/agentkit.md

@@ -1,26 +1,27 @@
 # Cursor AgentKit Rules
 
-Use these rules with Cursor agents and composer workflows.
+Use this rule as a repository guidance router for Cursor agents and composer workflows.
 
-## Default Behavior
+## Primary Guidance
 
-- Read `AGENTS.md` before implementation.
-- Read `DESIGN-SYSTEM.md` before UI, styling, layout, navigation, or component work.
-- Read `CODE-QUALITY.md` before review or refactor work.
-- Create or update an implementation brief for complex work.
+- Follow `AGENTS.md` first.
+- Treat `AGENTS.md` as the source of truth for repository-wide agent behavior.
+- Do not load companion files for routine coding unless a trigger in `AGENTS.md` applies or the user asks.
 
-## Implementation Rules
+## When Relevant
 
-- Prefer the smallest complete solution.
-- Reuse existing components, utilities, and patterns.
-- Keep diffs focused and reviewable.
-- Avoid speculative abstractions and dependency bloat.
-- Do not change foundational theme, schema, or architecture without explicit approval.
+- **File edits (final message):** change-explanation format in `AGENTS.md` and `CHANGE-EXPLANATION.md`.
+- **UI / styling / layout:** `DESIGN-SYSTEM.md` or the project design-system path from `AGENTS.md`.
+- **Review / refactor / dependencies:** `CODE-QUALITY.md`.
+- **Tests / QA strategy:** `TESTING.md` if present.
+- **Auth / secrets / PII:** `SECURITY-CHECKLIST.md` if present.
+- **Stack-specific code:** `STACK.md` if present.
+- **Planning docs requested:** create from `PRD-TEMPLATE.md` or `IMPLEMENTATION-BRIEF-TEMPLATE.md` under the project's briefs path.
+- **Process map (optional):** `WORKFLOWS.md` if present.
 
-## Handoff
+## Cursor Behavior
 
-Always summarize:
-
-- Files or areas changed.
-- Checks run.
-- Known risks or follow-up work.
+- Prefer existing repository patterns over generic generated patterns.
+- Keep changes scoped and reviewable.
+- Do not change foundational architecture, schema, dependencies, or theme primitives without explicit approval.
+- After modifying files, end every task with a change explanation per `AGENTS.md` (summary, what changed, verification, risks, review focus). Scale depth to the change; do not skip for small fixes.

package/templates/.github/copilot-instructions.md

@@ -1,25 +1,9 @@
 # GitHub Copilot Instructions
 
-Follow the repository rules in `AGENTS.md`, `CODE-QUALITY.md`, and `DESIGN-SYSTEM.md`.
+Follow `AGENTS.md` first. It is the primary source of truth for this repository's AI-agent guidance.
 
-## Coding Style
+Do not load companion files for routine coding. Use `AGENTS.md` triggers: change explanation after file edits; `CODE-QUALITY.md` for review/refactors; design-system path or `DESIGN-SYSTEM.md` for UI; `TESTING.md`, `SECURITY-CHECKLIST.md`, or `STACK.md` when present and relevant; planning templates only when explicitly requested.
 
-- Prefer simple, maintainable, production-friendly code.
-- Match existing project patterns.
-- Keep changes small and explicit.
-- Avoid adding dependencies unless the benefit is clear.
-- Do not hardcode design tokens, colors, or font families in UI code.
+For files covered by additional GitHub instructions under `.github/instructions/`, apply those path-specific instructions together with this file.
 
-## Before Suggesting Code
-
-- Inspect nearby code and reuse existing utilities or components.
-- Preserve public APIs unless the task requires a change.
-- Include validation at external boundaries.
-- Include tests when behavior changes.
-
-## Avoid
-
-- Speculative abstractions.
-- Broad rewrites for narrow requests.
-- Unrelated formatting churn.
-- Placeholder logic that looks production-ready but is incomplete.
+Prefer existing repository patterns over generic suggestions. Do not introduce new dependencies, architecture, or broad rewrites unless the task explicitly requires them.

package/templates/.github/pull_request_template.md

@@ -3,17 +3,33 @@
 - [What changed?]
 - [Why?]
 
+## Linked Context
+
+- Issue:
+- PRD / brief:
+- Related discussion:
+
 ## Checks
 
-- [ ] Tests run or intentionally skipped
-- [ ] Lint/build checks run or intentionally skipped
+- [ ] Tests run or intentionally skipped with reason
+- [ ] Lint/build checks run or intentionally skipped with reason
 - [ ] Docs updated if behavior changed
 - [ ] No unrelated formatting or refactor churn
 
 ## Risk
 
-[Known risks, limitations, or rollout notes.]
+[Known risks, limitations, rollout notes, or rollback considerations.]
+
+## Reviewer Focus
+
+[Where should reviewers focus their attention?]
 
 ## Screenshots / Demo
 
 [Add screenshots, recordings, or notes for UI changes.]
+
+## Agent Checklist
+
+- [ ] Followed `AGENTS.md` and relevant companion guidance
+- [ ] Explained important decisions and trade-offs
+- [ ] Called out skipped checks or remaining uncertainty

package/templates/AGENTS.md

@@ -2,109 +2,138 @@
 
 ## Purpose
 
-This file gives coding agents the project rules they need to work safely and consistently.
+This is the primary instruction file for AI coding agents working in this repository.
 
-[Project Name] is [short project description]. Agents should optimize for fast iteration, low complexity, and production-ready delivery.
+[Project Name] is [short project description]. Agents should optimize for safe, focused, production-ready changes that follow local patterns.
 
-## Guidelines
+## Source Of Truth
 
-- Act like a high-performing senior engineer. Be concise, direct, decisive, and execution-focused.
-- Solve problems with simple, maintainable, production-friendly solutions.
-- Prefer low-complexity code that is easy to read, debug, and modify.
-- Prefer the smallest path that fully satisfies the requirement.
-- Do not overengineer. Do not introduce heavy abstractions, extra layers, broad fallbacks, or large dependencies for small features.
-- Keep implementations clean, APIs small, behavior explicit, and naming clear.
-- Avoid cleverness unless it clearly improves the outcome.
-- Write code that another strong engineer can quickly understand, safely extend, and confidently ship.
-- Treat user edits as intentional. Do not overwrite or revert work you did not make.
+Follow this file first. It defines the repository-wide operating rules for agents.
 
-## Do Not
+Use companion guides only when a trigger below applies. Do not load or restate every guide by default.
 
-- Do not add edge-case logic for scenarios outside the current requirements.
-- Do not create new components, utilities, or abstractions before checking existing patterns.
-- Do not introduce new dependencies without a clear production benefit.
-- Do not make broad theme, schema, architecture, or formatting changes without explicit approval.
-- Do not run destructive git commands unless explicitly asked.
+For routine bugfixes and small features, do not open `WORKFLOWS.md`, planning templates, or optional guides unless a trigger applies or the user asks.
 
-## Maintainability
+## When To Use Other Guides
 
-Long-term maintainability is a core priority. Keep code direct and easy to change.
+| Trigger | Action |
+| --- | --- |
+| 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.
 
-Extract shared logic when duplication is real or immediately likely, but do not create speculative abstractions. Do not be afraid to improve existing code when it helps the task, but avoid unrelated refactors.
+Do not read planning templates on every task. Copy and fill them only when planning documentation is requested.
+
+## Local Guidance
+
+This root `AGENTS.md` applies to the whole repository.
+
+If a subdirectory contains its own `AGENTS.md` or equivalent local guidance, follow the most specific local guidance for files in that subtree. When instructions conflict, prefer the more specific local guidance unless it violates repository-wide safety, security, or quality rules.
+
+## Operating Rules
+
+- Inspect existing code and patterns before changing files.
+- Prefer the smallest complete solution that satisfies the task.
+- Keep diffs focused and reviewable.
+- Preserve user changes. Do not overwrite or revert work you did not make.
+- Avoid speculative abstractions, broad rewrites, and dependency bloat.
+- 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 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. Check whether the task is linked to an issue in [issue tracker, e.g. Linear or GitHub Issues].
-2. For non-trivial work without an issue, ask whether one should be created before implementation.
-3. Create or switch to an appropriate branch:
-   - Prefer the branch generated by the issue tracker when available.
-   - Otherwise create a clear branch name, such as `feature/bookmark-dedupe` or `fix/auth-redirect`.
-4. Identify the smallest complete solution that satisfies the task.
-5. If the task touches UI, layout, styling, navigation, or components, read `[design system path, e.g. docs/design-system.md]`.
-6. If the task touches framework-specific or backend-specific code, read the local guidance for that system first.
-7. Inspect existing patterns before adding new ones.
-8. For complex or multi-file work, create a short PRD or implementation brief in `[briefs path, e.g. docs/briefs]` before implementation.
-
-Tiny fixes do not need a branch-and-brief ceremony unless the project owner asks for it.
-
-For complex work, the brief should include:
-
-- Problem
-- Scope
-- Out of scope
-- Acceptance criteria
-- Implementation plan
-- Files likely to change
-- Risks
-- Manual QA steps
+1. Confirm the task, scope, and acceptance criteria.
+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 issue-and-branch ceremony when the change is obvious and low risk.
 
 ## During Coding
 
 While implementing:
 
-- Keep the diff small and reviewable.
-- Prefer modifying existing patterns over inventing new ones.
+- Modify existing patterns before creating new ones.
+- Keep behavior explicit and easy to test.
 - Avoid unrelated formatting churn.
-- Keep behavior explicit.
-- Add validation where external input enters the system.
-- Follow `[design system path]` for UI work.
-- Use semantic styling tokens instead of hardcoded colors or fonts.
-- Preserve the project's established density, layout, and interaction patterns.
-- Add loading, empty, error, disabled, and focus states where relevant.
-- Add or update tests when touching pure logic, parsing, data transforms, search, AI output handling, or bug fixes.
-- Preserve existing UX and styling unless the task asks for changes.
+- Prefer existing utilities, components, and conventions.
+- 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 change explanation when they matter.
+
+## Approval Boundaries
+
+Ask before:
+
+- Adding a new runtime dependency.
+- Changing schemas, migrations, permissions, auth, billing, or data retention behavior.
+- Running destructive commands or deleting files.
+- Changing global design tokens, theme primitives, or foundational layout rules.
+- 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 task and acceptance criteria.
+1. Re-read the original request and acceptance criteria.
 2. Confirm the implementation satisfies the requested scope.
-3. Run the 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. Provide a clear summary of the changes made.
-7. Mention:
-   - Files or areas changed
-   - Checks run
-   - Known risks or limitations
-   - Follow-up work, if any
-
-## Working Style
-
-- Be concise, direct, and execution-focused.
-- Prefer the smallest production-ready solution that fully meets the requirement.
-- Keep code explicit, maintainable, and easy to modify.
-- Avoid speculative abstractions, edge-case overengineering, and dependency bloat.
-- Improve nearby code when helpful, but avoid unrelated refactors.
-- Use existing UI primitives from `[UI component library or path]` before creating custom UI.
-- Do not create reusable custom components unless the task actually needs them.
-- Do not change global color tokens, theme colors, or foundational layout rules without explicit approval.
+6. Include the change explanation from **After Coding (Required)** in your final message.
 
 ## Project Commands
 
@@ -129,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]
@@ -137,13 +168,3 @@ Document the real stack for this project:
 - [Styling system]
 - [Test tools]
 - [Lint/format tools]
-
-## Optional Framework Rules
-
-Add project-specific rules here when a framework or backend has important local guidance.
-
-Examples:
-
-- Always read generated backend/framework guidance before editing generated or platform-specific code.
-- Follow local generated patterns over generic assumptions.
-- Keep schemas, validators, and API boundaries strict and explicit.

package/templates/CHANGE-EXPLANATION.md

@@ -0,0 +1,95 @@
+# Change Explanation Guide
+
+## Purpose
+
+Use this guide **after every task that modifies repository files**.
+
+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 **response format** for agent messages. Do **not** create a new markdown file per task unless the project explicitly asks for one.
+
+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
+
+Briefly state the outcome in plain language. Focus on the behavior or capability delivered, not just the files edited.
+
+### What Changed
+
+List the main files, modules, or areas changed.
+
+For each important area, explain:
+
+- what changed
+- why it changed
+- how it fits existing project patterns
+
+### Key Decisions
+
+Explain notable implementation decisions.
+
+Include when relevant:
+
+- why this approach was chosen
+- alternatives considered
+- 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:
+
+- tests
+- lint
+- build/typecheck
+- manual QA
+- screenshots or visual checks for UI work
+
+If a relevant check was skipped, say why.
+
+### Risks Or Limitations
+
+Call out anything the developer should know before merging or shipping:
+
+- untested paths
+- migration concerns
+- UX edge cases
+- security or privacy considerations
+- 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.
+
+Examples:
+
+- Review the validation path in `[path]`.
+- Confirm the empty/error states match product intent.
+- Check whether the authorization behavior matches policy.
+- Verify the new abstraction is worth keeping.
+
+## Style Rules
+
+- Be concise but specific.
+- Mention file paths clearly.
+- Explain reasoning, not only actions.
+- Do not hide uncertainty or skipped validation.
+- Do not claim tests passed unless they were run and passed.
+- Prefer bullets for scanability.

package/templates/CLAUDE.md

@@ -1,44 +1,9 @@
 # CLAUDE.md
 
-## Purpose
+Claude Code guidance for this repository.
 
-Project guidance for Claude-based coding and agent workflows.
+Follow `AGENTS.md` first. It is the source of truth for operating rules, triggers for companion guides, planning artifacts, and required change explanations.
 
-## Local Commands
+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.
 
-Replace these examples with the project’s real commands:
-
-```bash
-npm install
-npm test
-npm run build
-npm run lint
-```
-
-## Coding Standards
-
-- Keep changes focused on the requested behavior.
-- Prefer clear names and direct control flow.
-- Avoid new abstractions until duplication or complexity justifies them.
-- Preserve existing public interfaces unless the task requires a change.
-- Update nearby documentation when behavior or setup changes.
-
-## Agent Development
-
-- Document each agent’s goal, inputs, outputs, tools, and permission boundaries.
-- Keep prompts and tool schemas versioned with the code that depends on them.
-- Make failure modes explicit: retries, timeouts, partial results, and user-facing errors.
-- Use deterministic tests for core orchestration logic.
-
-## Review And Verification
-
-- Run the narrowest relevant test command first.
-- For UI changes, verify responsive behavior and obvious accessibility states.
-- For agent changes, test success, tool failure, invalid input, and timeout paths.
-- Summarize verification results in the final handoff.
-
-## Secrets
-
-- Use environment variables for local credentials.
-- Do not paste secrets into prompts, logs, fixtures, or committed files.
-- Provide `.env.example` entries for required variables without real values.
+Do not duplicate repository rules here. Update `AGENTS.md` or the relevant companion guide instead.

package/templates/CODE-QUALITY.md

@@ -4,7 +4,7 @@
 
 This guide defines the baseline quality bar for changes in this repository.
 
-Agents and contributors should optimize for code that is simple, readable, testable, and safe to modify.
+Agents and contributors should optimize for code that is simple, readable, testable, secure, and safe to modify.
 
 ## Principles
 
@@ -14,31 +14,36 @@ Agents and contributors should optimize for code that is simple, readable, testa
 - Avoid speculative abstractions and dependency bloat.
 - Match existing project patterns before introducing new ones.
 - Make failure modes explicit at system boundaries.
+- Validate external input and avoid leaking secrets or private data.
+- Preserve behavior unless the task explicitly changes it.
+
+## Review Severity
+
+Use clear severity when reviewing or explaining issues:
+
+- **Blocker**: likely bug, data loss, security issue, broken build, failing tests, or unmet requirement.
+- **Concern**: maintainability, test gap, confusing behavior, or risk that should be addressed soon.
+- **Suggestion**: optional improvement that does not block shipping.
 
 ## Review Checklist
 
 - The change solves the stated problem and does not expand scope unexpectedly.
 - The diff is small enough to review confidently.
 - No unrelated formatting churn or broad refactors were introduced.
+- Existing patterns were reused where practical.
 - New behavior has relevant tests or a clear reason tests were not added.
 - External inputs are validated at boundaries.
-- Errors are actionable and do not leak secrets.
+- Authorization checks remain server-side and resource-specific.
+- Errors are actionable and do not leak secrets or sensitive data.
 - User-facing copy is clear and specific.
 - UI changes include loading, empty, error, disabled, and focus states where relevant.
+- Documentation was updated when behavior, setup, or commands changed.
 
 ## Testing Expectations
 
 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.
+Use the commands documented in `AGENTS.md` **Project Commands**. For deeper testing strategy, read `TESTING.md` when present.
 
 ## Dependency Policy
 
@@ -49,11 +54,25 @@ Before adding a dependency, confirm:
 - The package is actively maintained.
 - The API surface is small enough for the need.
 - The behavior would be meaningfully harder or riskier to implement locally.
-- The dependency does not create avoidable runtime, security, or bundle-size risk.
+- The dependency does not create avoidable runtime, security, licensing, or bundle-size risk.
+
+## AI-Specific Quality Risks
+
+Watch for common AI-generated issues:
+
+- invented APIs, commands, environment variables, or project conventions
+- placeholder logic that appears production-ready
+- broad abstractions created before duplication exists
+- tests that do not exercise the changed behavior
+- silent error swallowing or vague fallback behavior
+- client-only validation or authorization for sensitive actions
+- excessive comments explaining obvious code instead of clarifying intent
+
+## Change Explanation Standard
 
-## Handoff Standard
+Every completed change that edits files must end with a developer-facing explanation that follows `CHANGE-EXPLANATION.md` in the agent's final message.
 
-Every completed change should include:
+At minimum, cover:
 
 - What changed.
 - Why it changed.

package/templates/IMPLEMENTATION-BRIEF-TEMPLATE.md

@@ -1,13 +1,24 @@
 # 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]
 
+## Context
+
+[Relevant issue, PRD, discussion, logs, screenshots, or code paths.]
+
 ## Problem
 
 [What problem are we solving?]
 
+## Goals
+
+- [Goal]
+- [Goal]
+
 ## Scope
 
 - [In-scope item]
@@ -18,6 +29,15 @@
 - [Out-of-scope item]
 - [Out-of-scope item]
 
+## Proposed Approach
+
+[Describe the intended implementation approach and why it fits the existing codebase.]
+
+## Alternatives Considered
+
+- [Alternative]: [why not chosen]
+- [Alternative]: [why not chosen]
+
 ## Acceptance Criteria
 
 - [ ] [Concrete scenario passes]
@@ -35,14 +55,30 @@
 - `[path]`: [reason]
 - `[path]`: [reason]
 
+## API / Schema / Dependency Changes
+
+- API changes: [none or details]
+- Schema or migration changes: [none or details]
+- Dependency changes: [none or details]
+
+## Verification Plan
+
+- Automated checks: [commands]
+- Manual QA: [steps]
+- Regression coverage: [areas]
+
+## Rollback Plan
+
+[How to revert or mitigate if this causes problems.]
+
 ## Risks
 
 - [Risk]: [mitigation]
 
-## Manual QA
+## Open Questions
 
-- [Manual verification step]
-- [Manual verification step]
+- [Question]
+- [Question]
 
 ## Notes
 

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]
@@ -24,6 +26,12 @@ Describe the user problem, business problem, or technical gap this work addresse
 - Secondary users:
 - Internal operators or reviewers:
 
+## User Stories / Key Flows
+
+- As a [user], I want [capability], so that [outcome].
+- [Primary workflow]
+- [Secondary workflow]
+
 ## Requirements
 
 ### Functional
@@ -45,6 +53,7 @@ Describe the user problem, business problem, or technical gap this work addresse
 - Empty state:
 - Error state:
 - Permission or authentication state:
+- Loading or pending state:
 
 ## Technical Notes
 
@@ -52,18 +61,42 @@ Describe the user problem, business problem, or technical gap this work addresse
 - APIs or schemas:
 - Data flow:
 - Migration or compatibility concerns:
+- Dependencies:
+
+## Success Metrics
+
+- [Metric or signal]
+- [Metric or signal]
+
+## Rollout / Migration
+
+- Rollout plan:
+- Migration/backfill plan:
+- Rollback or mitigation plan:
 
 ## Risks
 
 - [Risk and mitigation]
 - [Risk and mitigation]
 
+## Decision Log
+
+| Decision | Rationale | Date |
+| --- | --- | --- |
+| [Decision] | [Why] | [Date] |
+
 ## Acceptance Criteria
 
 - [ ] [Concrete scenario passes]
 - [ ] [Concrete scenario passes]
 - [ ] Tests cover success and failure paths.
 
+## Launch Criteria
+
+- [ ] Required checks pass.
+- [ ] Documentation and release notes are updated if needed.
+- [ ] Rollout, monitoring, and rollback expectations are clear.
+
 ## Open Questions
 
 - [Question]

package/templates/SECURITY-CHECKLIST.md

@@ -0,0 +1,87 @@
+# Security Checklist
+
+## Purpose
+
+Use this checklist before and during changes that touch authentication, authorization, secrets, user data, dependencies, network boundaries, logging, or data persistence.
+
+Security-sensitive changes should be explicit, reviewed carefully, and verified with relevant tests or manual checks.
+
+## Ask Before Changing
+
+Ask for approval before:
+
+- changing authentication or authorization behavior
+- adding permissions, roles, scopes, or bypasses
+- changing data retention, deletion, export, or privacy behavior
+- adding a new dependency for security-sensitive code
+- modifying secrets management or environment variable handling
+- weakening validation, rate limits, CSP, CORS, CSRF, or other protections
+- running migrations that could expose, destroy, or transform sensitive data
+
+## Secrets
+
+- Never commit secrets, tokens, private keys, certificates, or real `.env` values.
+- Do not paste secrets into prompts, logs, fixtures, test snapshots, or documentation.
+- Keep required variables documented with placeholder values only.
+- Redact secrets from error messages and debug output.
+
+## Authentication And Authorization
+
+- Treat authentication and authorization as separate concerns.
+- Verify the caller is allowed to access or mutate the specific resource.
+- Enforce authorization on the server side, not only in UI state.
+- Include unauthorized and forbidden cases in tests when behavior changes.
+- Preserve existing tenant, workspace, organization, or ownership boundaries.
+
+## Input And Output Boundaries
+
+- Validate external input at route, action, API, webhook, CLI, and file-upload boundaries.
+- Prefer allowlists and typed schemas where practical.
+- Escape or sanitize output in contexts that can execute or render markup.
+- Avoid leaking internal errors, stack traces, tokens, or PII to users.
+
+## Data Handling And Privacy
+
+- Collect and store only data required for the feature.
+- Avoid logging PII, credentials, session tokens, or authorization headers.
+- Be explicit about data migrations and backfills.
+- Preserve auditability for sensitive operations when the project supports it.
+
+## Dependencies
+
+Before adding or upgrading a dependency, consider:
+
+- maintenance and release history
+- known vulnerabilities
+- transitive dependency risk
+- bundle/runtime impact
+- whether existing platform APIs or project utilities are sufficient
+
+## Network And Integration Boundaries
+
+- Use HTTPS for external services.
+- Keep timeouts and failure behavior explicit.
+- Validate webhook signatures when applicable.
+- Avoid sending sensitive data to third-party services unless required and approved.
+
+## Agent-Specific Pitfalls
+
+Avoid these common AI-generated security problems:
+
+- placeholder auth checks that look real
+- client-only permission enforcement
+- broad `admin` or `owner` bypasses without policy confirmation
+- logging complete request objects
+- swallowing security-relevant errors
+- adding permissive CORS or CSP rules to fix local issues
+- assuming user IDs, workspace IDs, or tenant IDs from untrusted input
+
+## Change Explanation Requirements
+
+For security-sensitive work, include in the change explanation after coding:
+
+- security-sensitive files or behavior changed
+- tests or checks run
+- authorization and validation paths reviewed
+- known risks or unverified assumptions
+- follow-up recommendations

package/templates/TESTING.md

@@ -0,0 +1,88 @@
+# Testing Guide
+
+## Purpose
+
+This guide defines how agents and contributors should choose, write, run, and report tests.
+
+Optimize for fast, meaningful feedback. Run the narrowest useful check first, then broaden validation when risk or scope requires it.
+
+## Test Selection Strategy
+
+Choose tests based on the change:
+
+| Change type | Expected verification |
+| --- | --- |
+| Pure logic, parsing, transforms | Unit tests for success and failure paths |
+| API, server actions, routes, permissions | Boundary tests for valid, invalid, unauthorized, and error cases |
+| UI behavior | Component or integration tests plus manual interaction checks when needed |
+| Data access or schema changes | Integration tests or migration validation |
+| Bug fix | Regression test that fails without the fix when practical |
+| Refactor only | Existing relevant tests plus type/lint/build checks |
+
+## Running Checks
+
+Document project-specific commands here:
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+Remove commands that do not apply.
+
+Prefer file-scoped or package-scoped commands when available. Use full-suite checks for broad, risky, or release-bound changes.
+
+## Writing Tests
+
+- Test observable behavior, not implementation details.
+- Cover at least one success path and relevant failure paths.
+- Keep tests deterministic and isolated.
+- Prefer realistic fixtures over excessive mocking.
+- Name tests by behavior or scenario.
+- Avoid snapshots unless they are stable and intentionally reviewed.
+- Do not weaken or delete tests to make a change pass unless the task explicitly updates expected behavior.
+
+## Mocks And Fixtures
+
+- Mock network, time, randomness, and external services at clear boundaries.
+- Keep fixtures small and relevant to the scenario.
+- Reuse existing fixture helpers before adding new ones.
+- Avoid global test state that can leak between tests.
+
+## UI And Accessibility Checks
+
+For UI changes, verify relevant states:
+
+- loading
+- empty
+- error
+- disabled
+- hover/active/focus
+- keyboard navigation
+- responsive layout
+- text overflow
+- light/dark themes when supported
+
+Use automated accessibility checks when available, but do not rely on automation alone for focus order, semantics, or interaction quality.
+
+## Agent-Specific Pitfalls
+
+Avoid these common AI-generated testing problems:
+
+- tests that assert mocked implementation details instead of behavior
+- tests that pass without exercising the changed code
+- broad snapshot updates without review
+- skipped tests without explanation
+- invented test utilities or commands that do not exist
+- replacing meaningful coverage with shallow smoke tests
+
+## Reporting Verification
+
+In the change explanation after coding work, include:
+
+- checks run
+- whether they passed
+- checks not run and why
+- any manual QA performed
+- remaining test gaps or follow-up recommendations

package/templates/WORKFLOWS.md

@@ -2,53 +2,22 @@
 
 ## Purpose
 
-This document defines lightweight workflows for 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.
 
-## Planning Workflow
+## Choose The Right Document
 
-Use a PRD for product or user-facing work that needs intent, requirements, and acceptance criteria.
+| Situation | Use |
+| --- | --- |
+| 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` |
 
-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.
-
-## Coding Workflow
-
-1. Read the issue, PRD, or implementation brief.
-2. Inspect existing patterns.
-3. Make the smallest complete change.
-4. Add or update tests where behavior changes.
-5. Run relevant checks.
-6. Review the diff before handoff.
-
-## Review Workflow
-
-Review for correctness first, then maintainability, tests, UX, and style.
-
-Call out:
-
-- Bugs or regressions.
-- Missing validation or error handling.
-- Overly broad abstractions.
-- Missing tests for changed behavior.
-- UI states that are missing or inaccessible.
-
-## 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.
+For branching, implementation steps, review expectations, and release checks, follow `AGENTS.md`.