thomas-agentkit 0.7.0 → 0.8.0

package/README.md

@@ -166,7 +166,7 @@ Interactive personalization only applies during `agentkit init` when files are c
 Template set mappings:
 
 - `minimal`: `AGENTS.md`
-- `standard`: `AGENTS.md`, `CHANGE-EXPLANATION.md`, `CODE-QUALITY.md`, `DESIGN-SYSTEM.md`, `WORKFLOWS.md`, `.github/pull_request_template.md`
+- `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:
@@ -268,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

@@ -52,7 +52,6 @@ const templateSetFiles = {
         "CHANGE-EXPLANATION.md",
         "CODE-QUALITY.md",
         "DESIGN-SYSTEM.md",
-        "WORKFLOWS.md",
         ".github/pull_request_template.md",
     ],
     full: [],

package/package.json

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

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

@@ -6,21 +6,22 @@ Use this rule as a repository guidance router for Cursor agents and composer wor
 
 - Follow `AGENTS.md` first.
 - Treat `AGENTS.md` as the source of truth for repository-wide agent behavior.
-- Keep context focused. Read companion files only when relevant to the task.
+- Do not load companion files for routine coding unless a trigger in `AGENTS.md` applies or the user asks.
 
-## Read When Relevant
+## When Relevant
 
-- `CODE-QUALITY.md`: code quality, review, refactors, dependencies.
-- `WORKFLOWS.md`: planning, implementation, review, release.
-- `CHANGE-EXPLANATION.md`: final handoff and developer-facing explanation.
-- `DESIGN-SYSTEM.md`: UI, styling, layout, navigation, components.
-- `TESTING.md`: tests, fixtures, mocks, QA strategy.
-- `SECURITY-CHECKLIST.md`: auth, permissions, secrets, PII, data handling.
-- `STACK.md`: stack-specific rules when present.
+- **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.
 
 ## Cursor Behavior
 
 - 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.
-- Summarize changed files, checks run, risks, and review focus before handoff.
+- 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

@@ -2,15 +2,7 @@
 
 Follow `AGENTS.md` first. It is the primary source of truth for this repository's AI-agent guidance.
 
-When relevant, also read:
-
-- `CODE-QUALITY.md`
-- `WORKFLOWS.md`
-- `CHANGE-EXPLANATION.md`
-- `DESIGN-SYSTEM.md`
-- `TESTING.md`
-- `SECURITY-CHECKLIST.md`
-- `STACK.md`
+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.
 
 For files covered by additional GitHub instructions under `.github/instructions/`, apply those path-specific instructions together with this file.
 

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`.