thomas-agentkit 0.6.1 → 0.7.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`, `WORKFLOWS.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.

package/dist/cli.js

@@ -47,7 +47,14 @@ 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",
+        "WORKFLOWS.md",
+        ".github/pull_request_template.md",
+    ],
     full: [],
 };
 const stackGuidance = {
@@ -390,7 +397,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 +572,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.7.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
   "repository": {

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

@@ -1,26 +1,26 @@
 # 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.
+- Keep context focused. Read companion files only when relevant to the task.
 
-## Implementation Rules
+## Read 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.
+- `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.
 
-## 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.
+- Summarize changed files, checks run, risks, and review focus before handoff.

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

@@ -1,25 +1,17 @@
 # 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
+When relevant, also read:
 
-- 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.
+- `CODE-QUALITY.md`
+- `WORKFLOWS.md`
+- `CHANGE-EXPLANATION.md`
+- `DESIGN-SYSTEM.md`
+- `TESTING.md`
+- `SECURITY-CHECKLIST.md`
+- `STACK.md`
 
-## Before Suggesting Code
+For files covered by additional GitHub instructions under `.github/instructions/`, apply those path-specific instructions together with this file.
 
-- 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,105 @@
 
 ## 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 relevant to the task. 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.
+## Reference Map
 
-## Maintainability
+Read these files when the task calls for them:
 
-Long-term maintainability is a core priority. Keep code direct and easy to change.
-
-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.
+| Task type | Read first |
+| --- | --- |
+| 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 |
+
+## 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 handoff.
+- Explain completed work clearly using `CHANGE-EXPLANATION.md` when present.
 
 ## 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. 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.
+
+Tiny fixes can skip branch-and-brief 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 implementation brief, PR, or final handoff.
+
+## 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.
 
 ## 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:
+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
 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. 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.
 
 ## Project Commands
 
@@ -137,13 +133,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,79 @@
+# Change Explanation Guide
+
+## Purpose
+
+Use this guide when explaining completed work to the developer.
+
+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.
+
+This is a reusable handoff guide. Do not create a new change-explanation file for every task unless the project explicitly asks for one.
+
+## Handoff 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
+
+### 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
+
+### 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,19 @@
 # CLAUDE.md
 
-## Purpose
+Claude Code guidance for this repository.
 
-Project guidance for Claude-based coding and agent workflows.
+Follow `AGENTS.md` first. Treat it as the primary source of truth for project rules, workflows, quality standards, and handoff expectations.
 
-## Local Commands
+When relevant, also read:
 
-Replace these examples with the project’s real commands:
+- `CODE-QUALITY.md`
+- `WORKFLOWS.md`
+- `CHANGE-EXPLANATION.md`
+- `DESIGN-SYSTEM.md`
+- `TESTING.md`
+- `SECURITY-CHECKLIST.md`
+- `STACK.md`
 
-```bash
-npm install
-npm test
-npm run build
-npm run lint
-```
+Keep context focused. Do not load companion files unless they are relevant to the task.
 
-## 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,17 +14,30 @@ 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
 
@@ -40,6 +53,8 @@ npm run build
 
 Remove commands that do not apply.
 
+For deeper testing guidance, use `TESTING.md` when present.
+
 ## Dependency Policy
 
 Add a dependency only when it clearly reduces real complexity or improves correctness. Prefer existing project utilities and platform APIs for small features.
@@ -49,7 +64,19 @@ 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
 
 ## Handoff Standard
 
@@ -60,3 +87,5 @@ Every completed change should include:
 - 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

@@ -4,10 +4,19 @@
 
 [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 +27,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 +53,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

@@ -24,6 +24,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 +51,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 +59,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
+
+## Handoff Requirements
+
+For security-sensitive work, explicitly report:
+
+- 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 final handoff, 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,10 +2,33 @@
 
 ## Purpose
 
-This document defines lightweight workflows for planning, implementation, review, and release.
+This document defines lightweight workflows for research, planning, implementation, review, and release.
 
 Keep this file practical. Delete sections that do not apply to the project.
 
+## 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.
@@ -23,26 +46,43 @@ Tiny fixes can skip formal planning when the change is obvious and low risk.
   - `chore/[short-name]`
 - Keep each branch focused on one coherent change.
 
-## Coding Workflow
+## Implementation 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.
+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, and style.
+Review for correctness first, then maintainability, tests, UX, security, 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.
+- 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
 
@@ -52,3 +92,5 @@ Before release:
 - 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.