thomas-agentkit 0.6.0 → 0.7.0

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]