thomas-agentkit 0.6.0 → 0.7.0

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.