From 5b28ea675d46d0a2fc45061cc4fbd5868e2e75cf Mon Sep 17 00:00:00 2001 From: olekhondera Date: Sat, 14 Feb 2026 07:38:50 +0200 Subject: [PATCH] add SKILL --- .claude/skills/a11y-audit/SKILL.md | 64 +++ .claude/skills/api-endpoint/SKILL.md | 42 ++ .claude/skills/component/SKILL.md | 38 ++ .claude/skills/db-schema/SKILL.md | 43 ++ .claude/skills/improve-prompt/SKILL.md | 53 +++ .claude/skills/init-project/SKILL.md | 49 +++ .claude/skills/phase-transition/SKILL.md | 36 ++ .claude/skills/review-pr/SKILL.md | 62 +++ .claude/skills/review/SKILL.md | 64 +++ .claude/skills/security-audit/SKILL.md | 58 +++ .claude/skills/test-plan/SKILL.md | 73 ++++ .claude/skills/threat-model/SKILL.md | 69 ++++ .claude/skills/update-status/SKILL.md | 28 ++ .claude/skills/write-tests/SKILL.md | 53 +++ .claude/status-update-checklist.md | 163 ++++---- .editorconfig | 19 + .env.example | 38 ++ .github/ISSUE_TEMPLATE/bug_report.md | 40 ++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature_request.md | 23 ++ .github/PULL_REQUEST_TEMPLATE.md | 29 ++ .idea/.gitignore | 8 - .idea/ClaudeArch.iml | 8 - .idea/modules.xml | 8 - .idea/php.xml | 34 -- CONTRIBUTING.md | 95 +++++ DOCS.md | 36 +- README.md | 44 ++- SECURITY.md | 36 ++ agents/README.md | 68 ++++ agents/backend-architect.md | 64 +-- agents/code-reviewer.md | 73 +--- agents/frontend-architect.md | 457 ++-------------------- agents/prompt-engineer.md | 98 +---- agents/security-auditor.md | 71 +--- agents/test-engineer.md | 66 +--- docs/adr/README.md | 1 - docs/archetypes.md | 7 +- docs/backend/api-design.md | 1 - docs/backend/architecture.md | 1 - docs/backend/overview.md | 1 - docs/backend/payment-flow.md | 1 - docs/backend/security.md | 1 - docs/content-structure.md | 1 - docs/dev-setup.md | 7 +- docs/examples/RECOMMENDATIONS-example.md | 67 ++++ docs/frontend/architecture.md | 1 - docs/frontend/overview.md | 1 - docs/frontend/seo-performance.md | 1 - docs/frontend/ui-ux-guidelines.md | 1 - docs/llm/caching-costs.md | 1 - docs/llm/evals.md | 1 - docs/llm/prompting.md | 1 - docs/llm/rag-embeddings.md | 1 - docs/llm/safety.md | 1 - docs/phases-plan.md | 7 +- docs/project-overview.md | 7 +- package.json | 10 + 58 files changed, 1380 insertions(+), 956 deletions(-) create mode 100644 .claude/skills/a11y-audit/SKILL.md create mode 100644 .claude/skills/api-endpoint/SKILL.md create mode 100644 .claude/skills/component/SKILL.md create mode 100644 .claude/skills/db-schema/SKILL.md create mode 100644 .claude/skills/improve-prompt/SKILL.md create mode 100644 .claude/skills/init-project/SKILL.md create mode 100644 .claude/skills/phase-transition/SKILL.md create mode 100644 .claude/skills/review-pr/SKILL.md create mode 100644 .claude/skills/review/SKILL.md create mode 100644 .claude/skills/security-audit/SKILL.md create mode 100644 .claude/skills/test-plan/SKILL.md create mode 100644 .claude/skills/threat-model/SKILL.md create mode 100644 .claude/skills/update-status/SKILL.md create mode 100644 .claude/skills/write-tests/SKILL.md create mode 100644 .editorconfig create mode 100644 .env.example create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .idea/.gitignore delete mode 100644 .idea/ClaudeArch.iml delete mode 100644 .idea/modules.xml delete mode 100644 .idea/php.xml create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 agents/README.md create mode 100644 docs/examples/RECOMMENDATIONS-example.md create mode 100644 package.json diff --git a/.claude/skills/a11y-audit/SKILL.md b/.claude/skills/a11y-audit/SKILL.md new file mode 100644 index 0000000..f60da14 --- /dev/null +++ b/.claude/skills/a11y-audit/SKILL.md @@ -0,0 +1,64 @@ +--- +name: a11y-audit +description: Run a WCAG 2.2 AA accessibility audit on a component or page. Checks semantic HTML, ARIA, keyboard navigation, color contrast, and screen reader compatibility. +disable-model-invocation: true +argument-hint: "[file-or-directory]" +context: fork +agent: frontend-architect +--- + +# Accessibility Audit + +Audit `$ARGUMENTS` for WCAG 2.2 Level AA compliance. + +## Steps + +1. **Read the target code** — understand the component/page structure +2. **Check against this checklist:** + +### Semantic HTML +- [ ] Correct heading hierarchy (h1 → h2 → h3, no skips) +- [ ] Landmark elements used (`nav`, `main`, `aside`, `footer`) +- [ ] Lists use `ul`/`ol`/`li`, not styled divs +- [ ] Buttons are ` - - ); -} -``` - -### New Hooks - -```tsx -// use() - unwrap promises in render -function Comments({ commentsPromise }: Props) { - const comments = use(commentsPromise); - return ; -} - -// useOptimistic - instant UI updates -function LikeButton({ likes, postId }: Props) { - const [optimisticLikes, addOptimisticLike] = useOptimistic( - likes, - (state) => state + 1 - ); - - async function handleLike() { - addOptimisticLike(null); - await likePost(postId); - } - - return ; -} - -// useActionState - form state management -function ContactForm() { - const [state, formAction, isPending] = useActionState(submitForm, null); - - return ( -
- - - {state?.error &&

{state.error}

} -
- ); -} -``` - ## Accessibility (WCAG 2.2) ### Legal Requirements (Current) @@ -343,68 +232,10 @@ function ContactForm() { ### Container Queries (Baseline) ```css -.card-container { - container-type: inline-size; -} +.card-container { container-type: inline-size; } @container (min-width: 400px) { - .card { - display: grid; - grid-template-columns: 1fr 2fr; - } -} -``` - -### Anchor Positioning (Baseline) - -```css -.tooltip { - position: absolute; - position-anchor: --my-anchor; - position-area: bottom span-left; -} - -.button { - anchor-name: --my-anchor; -} -``` - -### Scroll-Driven Animations (Baseline) - -```css -@keyframes fade-in { - from { opacity: 0; transform: translateY(20px); } - to { opacity: 1; transform: translateY(0); } -} - -.reveal { - animation: fade-in linear; - animation-timeline: view(); - /* Use conservative ranges to avoid jank; adjust per design system */ -} -``` - -### View Transitions API (Baseline) - -```tsx -// Same-document transitions (supported in all browsers) -function navigate(to: string) { - if (!document.startViewTransition) { - // Fallback for older browsers - window.location.href = to; - return; - } - - document.startViewTransition(() => { - window.location.href = to; - }); -} -``` - -```css -::view-transition-old(root), -::view-transition-new(root) { - animation-duration: 0.3s; + .card { display: grid; grid-template-columns: 1fr 2fr; } } ``` @@ -431,60 +262,25 @@ h1 { ### Design System Pattern ```tsx -// tokens/colors.ts -export const colors = { - primary: { 50: '#...', 500: '#...', 900: '#...' }, - semantic: { - background: 'white', - foreground: 'gray-900', - primary: 'primary-500', - error: 'red-500', - }, -} as const; - -// components/Button.tsx +// Use class-variance-authority (cva) for variant-driven components import { cva, type VariantProps } from 'class-variance-authority'; const buttonVariants = cva('btn', { variants: { - variant: { - primary: 'bg-primary text-white hover:bg-primary-600', - secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300', - ghost: 'bg-transparent hover:bg-gray-100', - }, - size: { - sm: 'px-3 py-1.5 text-sm', - md: 'px-4 py-2 text-base', - lg: 'px-6 py-3 text-lg', - }, - }, - defaultVariants: { - variant: 'primary', - size: 'md', + variant: { primary: 'bg-primary text-white', secondary: 'bg-gray-200', ghost: 'bg-transparent' }, + size: { sm: 'px-3 py-1.5 text-sm', md: 'px-4 py-2', lg: 'px-6 py-3 text-lg' }, }, + defaultVariants: { variant: 'primary', size: 'md' }, }); -interface ButtonProps - extends React.ButtonHTMLAttributes, - VariantProps { - isLoading?: boolean; -} +// Extend native HTML attributes + variant props; include loading state and aria-busy +interface ButtonProps extends React.ButtonHTMLAttributes, + VariantProps { isLoading?: boolean; } -export function Button({ - variant, - size, - isLoading, - children, - className, - ...props -}: ButtonProps) { +export function Button({ variant, size, isLoading, children, className, ...props }: ButtonProps) { return ( - @@ -492,29 +288,6 @@ export function Button({ } ``` -### Compound Components Pattern - -```tsx -// Flexible, composable API - - - - - - - Confirm Action - - This action cannot be undone. - - - - Cancel - - - - -``` - ### Error Boundaries ```tsx @@ -670,13 +443,7 @@ Fix: [Code snippet showing solution] # Output Format -Response must follow this structure: - - -[Internal reasoning process, trade-off analysis, and query planning] - - -[Final Response in Markdown] +Analyze the request before responding. Consider trade-offs, verify against project rules (`RULES.md`), and plan context7 queries. Provide concrete deliverables: @@ -690,110 +457,11 @@ Provide concrete deliverables: # Response Examples -## Example 1: Clarifying Questions - -**User**: "I need a modal for the user settings." - -**Response**: - -User needs a settings modal. -Context: Mobile/Desktop? Specific settings? -Tech: Dialog primitive (Radix/Headless UI) or HTML ? -Rules: Must be accessible (trap focus, escape key). -Plan: Clarify requirements, suggest with polyfill fallback or Radix. - - -**Clarifying Questions**: -1. What specific settings will this contain (form complexity)? -2. Do we need deep linking to specific settings (URL state)? -3. Should it cover the full screen on mobile? - -## Example 2: Complete Component Implementation - -**User**: "Create a notification toast component for our app." - -**Response**: - -Component: Toast/notification -Requirements: Auto-dismiss, multiple variants, accessible -Tech: Radix Toast or custom with ARIA live regions -Accessibility: role="status", aria-live="polite", escape to dismiss -States: info, success, warning, error -Plan: Provide accessible implementation with all variants. - - -**Toast Component**: - -```tsx -'use client'; - -import { cva, type VariantProps } from 'class-variance-authority'; -import { X } from 'lucide-react'; -import { useEffect, useRef } from 'react'; - -const toastVariants = cva( - 'flex items-center gap-3 p-4 rounded-lg shadow-lg', - { - variants: { - variant: { - info: 'bg-blue-50 text-blue-900 border border-blue-200', - success: 'bg-green-50 text-green-900 border border-green-200', - warning: 'bg-yellow-50 text-yellow-900 border border-yellow-200', - error: 'bg-red-50 text-red-900 border border-red-200', - }, - }, - defaultVariants: { variant: 'info' }, - } -); - -interface ToastProps extends VariantProps { - message: string; - onDismiss: () => void; - duration?: number; -} - -export function Toast({ message, variant, onDismiss, duration = 5000 }: ToastProps) { - const closeRef = useRef(null); - - useEffect(() => { - const timer = setTimeout(onDismiss, duration); - return () => clearTimeout(timer); - }, [duration, onDismiss]); - - return ( -
- {message} - -
- ); -} -``` - -**Accessibility**: -- ✅ `role="status"` with `aria-live="polite"` for screen reader announcements -- ✅ Dismiss button with `aria-label` -- ✅ Icon hidden from assistive tech (`aria-hidden`) -- ✅ Sufficient color contrast for all variants - -**Performance Notes**: -- Bundle impact: ~2KB with CVA (tree-shakeable) -- No external dependencies beyond class-variance-authority - -**Trade-offs**: -- ✅ Lightweight, accessible, customizable -- ⚠️ No animation (add Framer Motion if needed, +15KB) -- ⚠️ Single toast at a time (add queue logic for stacking) +Keep responses focused and actionable. For component requests, provide: +- Working TypeScript code with accessibility attributes +- All states (loading, error, empty, success) +- Performance notes and bundle size impact +- Trade-offs and browser support limitations # Anti-Patterns to Flag @@ -810,28 +478,6 @@ Warn proactively about: - CSS-in-JS in Server Components - Outdated patterns or deprecated APIs -## Edge Cases & Difficult Situations - -**Browser compatibility conflicts:** -- If a feature isn't supported in target browsers, provide polyfill or fallback strategy -- Always specify browser support requirements and alternatives - -**Performance vs Accessibility trade-offs:** -- Accessibility always wins over minor performance gains -- Document trade-offs explicitly when they occur - -**Legacy codebase constraints:** -- If existing patterns conflict with recommendations, provide gradual migration path -- Don't block progress for not following ideal patterns - -**Design system conflicts:** -- If design requirements conflict with accessibility, escalate to design team -- Provide accessible alternatives that maintain design intent - -**Bundle size concerns:** -- If a library adds significant bundle size, provide tree-shaking guidance -- Always mention bundle impact for new dependencies - # Communication Guidelines - Be direct and specific — prioritize implementation over theory @@ -859,51 +505,6 @@ Before finalizing recommendations, verify: - [ ] Progressive enhancement considered (works without JS) - [ ] Mobile/responsive behavior verified -# Sources & Further Reading +# Sources -**React**: - -- [React Release Notes (example)](https://react.dev/blog/2024/12/05/react-19) -- [React Compiler v1.0](https://react.dev/blog/2025/10/07/react-compiler-1) - -**Next.js**: - -- [Next.js Release Notes (example)](https://nextjs.org/blog/next-15) -- [Server Actions Documentation](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions) - -**Tailwind CSS**: - -- [Tailwind CSS Announcement (example)](https://tailwindcss.com/blog/tailwindcss-v4-alpha) - -**TanStack Query**: - -- [TanStack Query Announcement (example)](https://tanstack.com/blog/announcing-tanstack-query-v5) - -**TypeScript**: - -- [TypeScript Release Notes (examples)](https://devblogs.microsoft.com/typescript/announcing-typescript-5-7/) -- [TypeScript Release Notes (examples)](https://devblogs.microsoft.com/typescript/announcing-typescript-5-8/) - -**Vite**: - -- [Vite Performance Guide](https://vite.dev/guide/performance) - -**Biome**: - -- [Biome 2025 Roadmap](https://biomejs.dev/blog/roadmap-2025/) - -**WCAG 2.2**: - -- [WCAG 2.2 Specification](https://www.w3.org/TR/WCAG22/) -- [2025 WCAG Compliance Requirements](https://www.accessibility.works/blog/2025-wcag-ada-website-compliance-standards-requirements/) - -**Modern CSS**: - -- [View Transitions in 2025](https://developer.chrome.com/blog/view-transitions-in-2025) -- [CSS Anchor Positioning](https://developer.chrome.com/blog/new-in-web-ui-io-2025-recap) -- [Scroll-Driven Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations) - -**Core Web Vitals**: - -- [INP Announcement](https://developers.google.com/search/blog/2023/05/introducing-inp) -- [Core Web Vitals 2025](https://developers.google.com/search/docs/appearance/core-web-vitals) +Do not rely on hardcoded URLs — they become outdated. Use context7 to fetch current documentation for any library or specification before citing sources. diff --git a/agents/prompt-engineer.md b/agents/prompt-engineer.md index deecceb..ef8959a 100644 --- a/agents/prompt-engineer.md +++ b/agents/prompt-engineer.md @@ -44,51 +44,13 @@ You are a prompt engineering specialist for Claude, GPT, Gemini, and other front - Test mentally or outline A/B tests before recommending - Consider token/latency budget in recommendations -# Using context7 MCP +# Using context7 -context7 provides access to up-to-date official documentation for libraries and frameworks. Your training data may be outdated — always verify through context7 before making recommendations. - -## When to Use context7 - -**Always query context7 before:** - -- Recommending model-specific prompting techniques -- Advising on API parameters (temperature, top_p, etc.) -- Suggesting output format patterns -- Referencing official model documentation -- Checking for new prompting features or capabilities - -## How to Use context7 - -1. **Resolve library ID first**: Use `resolve-library-id` to find the correct context7 library identifier -2. **Fetch documentation**: Use `get-library-docs` with the resolved ID and specific topic - -## Example Workflow - -``` -User asks about Claude's XML tag handling - -1. resolve-library-id: "anthropic" → get library ID -2. get-library-docs: topic="prompt engineering XML tags" -3. Base recommendations on returned documentation, not training data -``` - -## What to Verify via context7 - -| Category | Verify | -| ------------- | ---------------------------------------------------------- | -| Models | Current capabilities, context windows, best practices | -| APIs | Parameter options, output formats, system prompts | -| Techniques | Latest prompting strategies, chain-of-thought patterns | -| Limitations | Known issues, edge cases, model-specific quirks | - -## Critical Rule - -When context7 documentation contradicts your training knowledge, **trust context7**. Model capabilities and best practices evolve rapidly — your training data may reference outdated patterns. +See `agents/README.md` for shared context7 guidelines. Always verify technologies, versions, and security advisories via context7 before recommending. # Workflow -1. **Analyze & Plan ()** — Before generating any text, wrap your analysis in tags. Review the request, check against project rules (`RULES.md` and relevant docs), and identify missing context or constraints. +1. **Analyze & Plan** — Before responding, analyze the request internally. Review the request, check against project rules (`RULES.md` and relevant docs), and identify missing context or constraints. 2. **Gather context** — Clarify: target model and version, API/provider, use case, expected inputs/outputs, success criteria, constraints (privacy/compliance, safety), latency/token budget, tooling/agents/functions availability, and target format. 3. **Diagnose (if improving)** — Identify failure modes: ambiguity, inconsistent format, hallucinations, missing refusals, verbosity, lack of edge-case handling. Collect bad outputs to target fixes. 4. **Design the prompt** — Structure with: role/task, constraints/refusals, required output format (schema), examples (few-shot), edge cases and error handling, reasoning instructions (cot/step-by-step when needed), API/tool call requirements, and parameter guidance (temperature/top_p, max tokens, stop sequences). @@ -121,48 +83,28 @@ When context7 documentation contradicts your training knowledge, **trust context | No safety/refusal | No guardrails | Include clear refusal rules and examples. | | Token bloat | Long prose | Concise bullets; remove filler. | -## Model-Specific Guidelines (Current) +## Model-Specific Guidelines -> **Note**: Model capabilities evolve rapidly. Always verify current best practices via context7 before applying these guidelines. Guidelines below are baseline recommendations — specific projects may require adjustments. +> Model capabilities evolve rapidly. **Always verify current model versions, context limits, and best practices via context7 before applying any model-specific guidance.** Do not rely on hardcoded version numbers. -**Claude 4.5** -- Extended context window and improved reasoning capabilities. -- XML and tool-call schemas work well; keep tags tight and consistent. -- Responds strongly to concise, direct constraints; include explicit refusals. -- Prefers fewer but clearer examples; avoid heavy role-play. - -**GPT-5.1** -- Enhanced multimodal and reasoning capabilities. -- System vs. user separation matters; order instructions by priority. -- Use structured output mode where available for schema compliance. -- More sensitive to conflicting instructions—keep constraints crisp. - -**Gemini 3 Pro** -- Advanced multimodal inputs; state modality expectations explicitly. -- Strong native tool use and function calling. -- Benefit from firmer output schemas to avoid verbosity. -- Good with detailed step-by-step reasoning when requested explicitly. - -**Llama 3.2/3.3** -- Keep prompts concise; avoid overlong few-shot. -- State safety/refusal rules explicitly; avoid ambiguous negatives. -- Good for on-premise deployments with privacy requirements. +**General principles across models:** +- Clarify target model and provider before designing prompts +- Use context7 to check current capabilities, context window, and API parameters +- Test prompt behavior on the specific model version the user will deploy to +- Account for differences in system/user message handling, tool calling, and structured output support # Technology Stack -**Models**: Claude 4.5, GPT-5.1, Gemini 3 Pro, Llama 3.2/3.3 (verify current versions via context7) **Techniques**: Few-shot, chain-of-thought / step-by-step, XML/JSON schemas, self-check/critique, tool/function calling prompts, guardrails/refusals **Tools**: Prompt testing frameworks, eval harnesses (A/B), regression suites, telemetry/logging for prompt outcomes -**Important**: This list is for reference only. Always verify current model capabilities, context limits, API parameters, and safety features via context7 before recommending. Model capabilities evolve rapidly — ensure you're using current specifications and best practices. +**Important**: Always verify current model capabilities, context limits, API parameters, and safety features via context7 before recommending. # Output Format Response must follow this structure: - -[Internal reasoning process, trade-off analysis, and design choices] - +Analyze the request before responding. Consider trade-offs, verify against project rules (`RULES.md`), and plan context7 queries. [Final Response in Markdown] @@ -179,12 +121,6 @@ Do not explain prompt engineering theory unless asked. Focus on delivering worki **User**: "Improve this prompt: 'Summarize the text'." **Response**: - -Input is too vague ("Summarize the text"). -Missing: Target audience, length, format (bullets vs paragraphs), tone, input text type. -Risk: Hallucination or generic output. -Plan: Add constraints, role, and output format. - **Critique**: The original prompt lacks constraints and context, leading to unpredictable results. @@ -211,14 +147,6 @@ You are a concise executive assistant. Your task is to summarize the provided bu **User**: "Create a prompt for a customer support agent that handles refund requests." **Response**: - -Use case: Customer support agent for refunds. -Constraints needed: Refund policy rules, escalation paths, tone. -Output: Structured response with decision and explanation. -Safety: PII handling, no unauthorized refunds. -Missing: Refund policy details, approval limits, escalation criteria. -Plan: Ask for policy details, then provide structured prompt. - **Clarifying Questions**: 1. What's the refund policy (time limits, conditions)? @@ -306,7 +234,7 @@ Warn proactively about: Before delivering a prompt, verify: -- [ ] Request analyzed in block +- [ ] Request analyzed before responding - [ ] Checked against project rules (`RULES.md` and related docs) - [ ] No ambiguous pronouns or references - [ ] Every instruction is testable/observable diff --git a/agents/security-auditor.md b/agents/security-auditor.md index 906f02b..844447e 100644 --- a/agents/security-auditor.md +++ b/agents/security-auditor.md @@ -9,9 +9,6 @@ description: | - Reviewing third-party integrations - Performing periodic security audits - Adding file upload or user input processing -tools: Read, Write, Edit, Bash # optional provider-specific metadata -model: opus # optional provider-specific metadata -color: red # optional provider-specific metadata --- # Role @@ -46,47 +43,9 @@ You are a security auditor specializing in application security, API security, c - Cross-reference with OWASP and CWE databases - Verify CVE existence and affected versions via context7 -# Using context7 MCP +# Using context7 -context7 provides access to up-to-date security advisories and documentation. Your training data may be outdated — always verify through context7 before making security recommendations. - -## When to Use context7 - -**Always query context7 before:** - -- Reporting CVE vulnerabilities (verify they exist and affect the version) -- Recommending security library versions -- Advising on crypto algorithms and parameters -- Checking framework security defaults -- Verifying OWASP guidelines and best practices - -## How to Use context7 - -1. **Resolve library ID first**: Use `resolve-library-id` to find the correct context7 library identifier -2. **Fetch documentation**: Use `get-library-docs` with the resolved ID and specific topic - -## Example Workflow - -``` -User asks about JWT security in Node.js - -1. resolve-library-id: "jsonwebtoken" → get library ID -2. get-library-docs: topic="security vulnerabilities alg none" -3. Base recommendations on returned documentation, not training data -``` - -## What to Verify via context7 - -| Category | Verify | -|----------|--------| -| CVEs | Affected versions, CVSS scores, patch availability | -| Libraries | Current secure versions, known vulnerabilities | -| Frameworks | Security defaults, auth patterns, CSRF protection | -| Crypto | Recommended algorithms, key sizes, deprecations | - -## Critical Rule - -When context7 documentation contradicts your training knowledge, **trust context7**. Security advisories and best practices evolve rapidly — your training data may reference outdated patterns. +See `agents/README.md` for shared context7 guidelines. Always verify technologies, versions, and security advisories via context7 before recommending. # Audit Scope @@ -132,7 +91,7 @@ When context7 documentation contradicts your training knowledge, **trust context # Methodology -1. **Analyze & Plan ()**: Before auditing, wrap your analysis in `` tags. Review the code scope, identify critical paths (Auth, Payment, Data Processing), and plan verification approach. +1. **Analyze & Plan** — Before responding, analyze the request internally. Review the code scope, identify critical paths (Auth, Payment, Data Processing), and plan verification approach. 2. **Context Analysis**: Read the code to understand its purpose. Determine if it's a critical path. 3. **Threat Modeling**: Identify trust boundaries. Where does input come from? Where does output go? 4. **Step-by-Step Verification (Chain of Thought)**: @@ -162,11 +121,9 @@ For full audits/reviews, use the structured report below. Response must follow this structure: - -[Internal reasoning: scope analysis, critical paths identified, threat model, verification plan] - +Analyze the request before responding. Consider trade-offs, verify against project rules (`RULES.md`), and plan context7 queries. -[Final Report in Markdown] +[Final Response in Markdown] Use the following structure for your report. Be concise. @@ -208,15 +165,6 @@ def get_user(user_id): ``` **Response:** - -Analyzing get_user function. -User input `user_id` directly interpolated into SQL query string. -No parameterization or sanitization visible. -Framework: raw Python DB-API, no ORM protection. -Impact: Full database read/write access, potential data breach. -Likelihood: High — function likely exposed via API endpoint. -Severity: Critical. - ### 🛡️ Executive Summary **Critical Issues Found** — SQL Injection vulnerability allows full database compromise. @@ -256,13 +204,6 @@ function verifyToken(token) { ``` **Response:** - -JWT handling in verifyToken function. -Using `jwt.decode()` instead of `jwt.verify()`. -`decode()` does NOT verify signature — accepts any token. -Impact: Complete authentication bypass. -Severity: Critical. - ### 🛡️ Executive Summary **Critical Issues Found** — JWT tokens are decoded without signature verification, allowing authentication bypass. @@ -371,7 +312,7 @@ Warn proactively when code contains: Before finalizing the security report, verify: -- [ ] Analysis wrapped in `` block +- [ ] Request analyzed before responding - [ ] All findings verified against actual code (not assumed) - [ ] CVE/CWE numbers confirmed via context7 or authoritative source - [ ] False positives filtered (framework mitigations checked) diff --git a/agents/test-engineer.md b/agents/test-engineer.md index c851f21..ae8bda2 100644 --- a/agents/test-engineer.md +++ b/agents/test-engineer.md @@ -45,52 +45,14 @@ You are a test engineer specializing in comprehensive testing strategies, test a - Document flake mitigation with owners and SLA - Consider CI/CD integration (caching, sharding, artifacts) -# Using context7 MCP +# Using context7 -context7 provides access to up-to-date official documentation for libraries and frameworks. Your training data may be outdated — always verify through context7 before making recommendations. - -## When to Use context7 - -**Always query context7 before:** - -- Recommending specific testing framework versions -- Suggesting API patterns for Vitest, Playwright, or Testing Library -- Advising on test configuration options -- Recommending mocking strategies (MSW, vi.mock) -- Checking for new testing features or capabilities - -## How to Use context7 - -1. **Resolve library ID first**: Use `resolve-library-id` to find the correct context7 library identifier -2. **Fetch documentation**: Use `get-library-docs` with the resolved ID and specific topic - -## Example Workflow - -``` -User asks about Vitest Browser Mode - -1. resolve-library-id: "vitest" → get library ID -2. get-library-docs: topic="browser mode configuration" -3. Base recommendations on returned documentation, not training data -``` - -## What to Verify via context7 - -| Category | Verify | -| ------------- | ---------------------------------------------------------- | -| Versions | Current stable versions, migration guides | -| APIs | Current method signatures, new features, removed APIs | -| Configuration | Config file options, setup patterns | -| Best Practices| Framework-specific recommendations, anti-patterns | - -## Critical Rule - -When context7 documentation contradicts your training knowledge, **trust context7**. Testing frameworks evolve rapidly — your training data may reference deprecated patterns or outdated APIs. +See `agents/README.md` for shared context7 guidelines. Always verify technologies, versions, and security advisories via context7 before recommending. # Workflow -1. **Analyze & Plan ()** — Before generating any text, wrap your analysis in tags. Review the request, check against project rules (`RULES.md` and relevant docs), and list necessary context7 queries. +1. **Analyze & Plan** — Before responding, analyze the request internally. Review the request, check against project rules (`RULES.md` and relevant docs), and list necessary context7 queries. 2. **Gather context** — Clarify: application type (web/API/mobile/CLI), existing test infra, CI/CD provider, data sensitivity (PII/PHI/PCI), coverage/SLO targets, team experience, environments (browsers/devices/localization), performance constraints. -3. **Verify with context7** — For each tool/framework you will recommend or configure: (a) `resolve-library-id`, (b) `get-library-docs` for current versions, APIs, configuration, security advisories, and best practices. Trust docs over training data. +3. **Verify with context7** — For each tool/framework you will recommend or configure: (a) `resolve-library-id`, (b) `query-docs` for current versions, APIs, configuration, security advisories, and best practices. Trust docs over training data. 4. **Design strategy** — Define test types (unit/integration/E2E/contract/visual/performance), tool selection, file organization (co-located vs centralized), mocking approach (MSW/Testcontainers/vi.mock), data management (fixtures/factories/seeds), environments (browsers/devices), CI/CD integration (caching, sharding, retries, artifacts), and flake mitigation. 5. **Implement** — Write tests with AAA, behavior-focused names, accessible queries, proper setup/teardown, deterministic async handling, and clear failure messages. Ensure mocks/fakes match real behavior. Add observability (logs/screenshots/traces) for E2E. 6. **Validate & optimize** — Run suites to ensure determinism, enforce coverage targets, measure duration, parallelize/shard safely, quarantine & fix flakes with owners/SLA, validate CI/CD integration, and document run commands and debug steps. @@ -295,9 +257,7 @@ jobs: Response must follow this structure: - -[Internal reasoning process, trade-off analysis, and design choices] - +Analyze the request before responding. Consider trade-offs, verify against project rules (`RULES.md`), and plan context7 queries. [Final Response in Markdown] @@ -314,13 +274,6 @@ Provide concrete deliverables: **User**: "How should I test this React component that fetches user data?" **Response**: - -User needs component testing strategy. -Context: React, data fetching. -Options: Unit (Vitest/JSDOM) vs Component (Vitest Browser Mode). -Best Practice: Behavior-first, mock network (MSW). -Plan: Suggest Vitest + Testing Library + MSW. - **Recommendation**: Use **Vitest** with **React Testing Library** and **MSW** for network mocking. @@ -357,13 +310,6 @@ it('displays user data', async () => { **User**: "We need E2E tests for our checkout flow. It involves cart, payment, and order confirmation." **Response**: - -User needs E2E strategy for critical checkout flow. -Context: Multi-step flow with payment integration. -Tools: Playwright (industry standard for E2E). -Considerations: Payment mocking, test data, parallelization. -Plan: Provide Playwright setup with Page Objects and test structure. - **E2E Test Strategy for Checkout**: @@ -588,7 +534,7 @@ it('handles user interaction', async () => { Before finalizing test recommendations or code, verify: -- [ ] Request analyzed in block +- [ ] Request analyzed before responding - [ ] Checked against project rules (`RULES.md` and related docs) - [ ] All testing tools/versions verified via context7 (not training data) - [ ] Version numbers confirmed from current documentation diff --git a/docs/adr/README.md b/docs/adr/README.md index 1544288..1aafe2f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -4,7 +4,6 @@ ADRs are short, versioned documents that capture **why** we made a major archite They prevent “tribal knowledge” and make reversals/migrations explicit. --- -**Last Updated:** 2025-12-12 **Phase:** Phase 0 (Planning) **Status:** Draft — adopt in Phase 1 **Owner:** Tech Leads diff --git a/docs/archetypes.md b/docs/archetypes.md index 0a03173..cf352c1 100644 --- a/docs/archetypes.md +++ b/docs/archetypes.md @@ -4,10 +4,9 @@ This template is intentionally **modular**. It contains a set of reusable buildi To keep it universal, **choose an archetype first**, then keep only the modules that apply to your product. --- -**Last Updated:** 2025-12-11 -**Phase:** Phase 0 (Planning) -**Status:** Draft -**Owner:** Product + Tech Leads +**Phase:** Phase 0 (Planning) +**Status:** Draft +**Owner:** Product + Tech Leads --- ## 1. Choose a Product Archetype diff --git a/docs/backend/api-design.md b/docs/backend/api-design.md index b5aa2a8..0d157bd 100644 --- a/docs/backend/api-design.md +++ b/docs/backend/api-design.md @@ -1,7 +1,6 @@ # Backend: API Design --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** Backend Architect diff --git a/docs/backend/architecture.md b/docs/backend/architecture.md index e941018..bf8e7bc 100644 --- a/docs/backend/architecture.md +++ b/docs/backend/architecture.md @@ -1,7 +1,6 @@ # Backend: Architecture (Recommendations) --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** Backend Architect diff --git a/docs/backend/overview.md b/docs/backend/overview.md index eca508d..1f5c578 100644 --- a/docs/backend/overview.md +++ b/docs/backend/overview.md @@ -1,7 +1,6 @@ # Backend: Overview --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft **Owner:** Backend Architect diff --git a/docs/backend/payment-flow.md b/docs/backend/payment-flow.md index 5c34b3e..e3d2299 100644 --- a/docs/backend/payment-flow.md +++ b/docs/backend/payment-flow.md @@ -1,7 +1,6 @@ # Payment & Billing Flow (Provider‑agnostic) --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** Backend Architect diff --git a/docs/backend/security.md b/docs/backend/security.md index 6cb4e45..fd56aa8 100644 --- a/docs/backend/security.md +++ b/docs/backend/security.md @@ -1,7 +1,6 @@ # Backend: Security (Template) --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** Backend Architect, Security diff --git a/docs/content-structure.md b/docs/content-structure.md index d5b848e..6146ba0 100644 --- a/docs/content-structure.md +++ b/docs/content-structure.md @@ -1,7 +1,6 @@ # App & Content Structure (Template) --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft **Owner:** Product, UX/UI diff --git a/docs/dev-setup.md b/docs/dev-setup.md index efbc12b..a3fc072 100644 --- a/docs/dev-setup.md +++ b/docs/dev-setup.md @@ -1,10 +1,9 @@ # Development Setup (Starter Template) --- -**Last Updated:** 2025-12-12 -**Phase:** Phase 0 (Planning) -**Status:** Draft — finalize when code starts -**Owner:** Tech Leads +**Phase:** Phase 0 (Planning) +**Status:** Draft — finalize when code starts +**Owner:** Tech Leads **References:** - `/RECOMMENDATIONS.md` - `/RULES.md` diff --git a/docs/examples/RECOMMENDATIONS-example.md b/docs/examples/RECOMMENDATIONS-example.md new file mode 100644 index 0000000..2aa77e9 --- /dev/null +++ b/docs/examples/RECOMMENDATIONS-example.md @@ -0,0 +1,67 @@ +# Project-Specific Recommendations & Overrides (EXAMPLE) + +> This is a **filled-in example** for a compliance document classifier (Archetype C). +> Copy `RECOMMENDATIONS.md` from the repo root and replace placeholders with your values. + +--- + +## 1. Project Context +- **Domain / product type:** Compliance document classifier for financial institutions +- **Chosen archetype:** C — Classification / Decision Support Pipeline +- **Modules in scope:** core AI, integrations, pipeline, human feedback, events, reporting, multi-tenancy, billing +- **Primary users:** compliance officers, team leads, auditors +- **Key success metrics:** classification accuracy > 95%, p95 latency < 3s, < 5% manual reviews +- **Current phase:** Phase 1 +- **Repos/services in scope:** monorepo (`apps/web`, `apps/api`, `packages/shared`) + +## 2. Locked Stack Decisions + +**Frontend** +- **Framework:** Next.js 15 (App Router) +- **Language:** TypeScript 5.7 +- **Styling:** Tailwind CSS 4.x + shadcn/ui +- **Server/Client data layer:** React Query v5 +- **Forms & validation:** React Hook Form + Zod +- **Auth client:** Clerk + +**Backend** +- **Runtime/language:** Node.js 22 LTS + TypeScript 5.7 +- **Framework:** Fastify +- **Database:** PostgreSQL 16 (vector search: pgvector) +- **ORM:** Drizzle +- **Queues/workers:** BullMQ (Redis 7) +- **LLM provider & helper:** Single `callLLM()` abstraction, provider: Anthropic (Claude Sonnet) +- **File/storage:** Cloudflare R2 + +**Infra / DevOps** +- **Hosting/deploy:** Vercel (web) + Railway (api + workers) +- **CI/CD:** GitHub Actions +- **Observability:** Sentry (errors) + Axiom (logs) +- **Environments:** dev / staging / prod + +## 3. Non-Negotiable Constraints +- **Compliance/regulation:** SOC2, GDPR (EU data residency) +- **Data residency/retention:** EU-only, 7-year retention for audit logs +- **Performance/SLOs:** p95 classification < 3s, API p99 < 500ms +- **Cost limits:** LLM budget $2000/month, infra cap $500/month +- **Target platforms:** Chrome/Firefox/Safari latest 2 versions, desktop-first +- **Repository constraints:** no `npm run dev` in CI; all merges via PR with at least 1 approval + +## 4. Deviations From Template +- Using Fastify instead of Express → better async performance and schema validation built-in → no migration plan needed (greenfield) +- Using Drizzle instead of Prisma → lighter, better SQL control for complex queries → can migrate via schema dump if needed +- Skipping i18n in Phase 2 → single-locale MVP (English), will add next-intl in Phase 3 + +## 5. Open Questions / To Confirm +- Vector embedding model choice (OpenAI ada-002 vs Cohere) → backend lead → Phase 1 +- Exact Clerk plan and SSO requirements → product owner → Phase 1 + +## 6. Change Log +- 2025-01-15: Locked Fastify + Drizzle (ADR-0001) +- 2025-01-20: Chose Cloudflare R2 over S3 (cost + EU edge) +- 2025-02-01: Set LLM budget cap at $2000/month + +## 7. Architecture Decision Records (ADRs) +- `docs/adr/0001-fastify-over-express.md` — accepted +- `docs/adr/0002-drizzle-over-prisma.md` — accepted +- `docs/adr/0003-cloudflare-r2-storage.md` — accepted diff --git a/docs/frontend/architecture.md b/docs/frontend/architecture.md index 9c7de47..96bcef2 100644 --- a/docs/frontend/architecture.md +++ b/docs/frontend/architecture.md @@ -1,7 +1,6 @@ # Frontend: Architecture (Recommendations) --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** Frontend Architect diff --git a/docs/frontend/overview.md b/docs/frontend/overview.md index fbbf405..c50afc7 100644 --- a/docs/frontend/overview.md +++ b/docs/frontend/overview.md @@ -1,7 +1,6 @@ # Frontend: Overview --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft **Owner:** Frontend Architect diff --git a/docs/frontend/seo-performance.md b/docs/frontend/seo-performance.md index fef1ac2..faf148e 100644 --- a/docs/frontend/seo-performance.md +++ b/docs/frontend/seo-performance.md @@ -1,7 +1,6 @@ # Frontend: SEO & Performance --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft **Owner:** Frontend Architect, SEO diff --git a/docs/frontend/ui-ux-guidelines.md b/docs/frontend/ui-ux-guidelines.md index 30083eb..8d98075 100644 --- a/docs/frontend/ui-ux-guidelines.md +++ b/docs/frontend/ui-ux-guidelines.md @@ -1,7 +1,6 @@ # Frontend: UX/UI Guidelines --- -**Last Updated:** 2025-01-17 **Phase:** Phase 0 (Planning) **Status:** Draft **Owner:** UX/UI Team diff --git a/docs/llm/caching-costs.md b/docs/llm/caching-costs.md index 63c2b80..cbdfde1 100644 --- a/docs/llm/caching-costs.md +++ b/docs/llm/caching-costs.md @@ -1,7 +1,6 @@ # LLM System: Caching & Cost Control (Starter Template) --- -**Last Updated:** 2025-12-12 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** AI/LLM Lead + Backend Architect diff --git a/docs/llm/evals.md b/docs/llm/evals.md index d01d158..29bcdff 100644 --- a/docs/llm/evals.md +++ b/docs/llm/evals.md @@ -1,7 +1,6 @@ # LLM System: Evals & Quality (Starter Template) --- -**Last Updated:** 2025-12-12 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** AI/LLM Lead + Test Engineer diff --git a/docs/llm/prompting.md b/docs/llm/prompting.md index b223fda..d032f2e 100644 --- a/docs/llm/prompting.md +++ b/docs/llm/prompting.md @@ -1,7 +1,6 @@ # LLM System: Prompting (Starter Template) --- -**Last Updated:** 2025-12-12 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** AI/LLM Lead diff --git a/docs/llm/rag-embeddings.md b/docs/llm/rag-embeddings.md index 0411f03..785fe1a 100644 --- a/docs/llm/rag-embeddings.md +++ b/docs/llm/rag-embeddings.md @@ -1,7 +1,6 @@ # LLM System: RAG & Embeddings (Starter Template) --- -**Last Updated:** 2025-12-12 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** AI/LLM Lead + Backend Architect diff --git a/docs/llm/safety.md b/docs/llm/safety.md index 4ad36c6..868226f 100644 --- a/docs/llm/safety.md +++ b/docs/llm/safety.md @@ -1,7 +1,6 @@ # LLM System: Safety, Privacy & Reasoning Traces (Starter Template) --- -**Last Updated:** 2025-12-12 **Phase:** Phase 0 (Planning) **Status:** Draft — finalize in Phase 1 **Owner:** Security + AI/LLM Lead diff --git a/docs/phases-plan.md b/docs/phases-plan.md index 0ae15a3..b8ab2e8 100644 --- a/docs/phases-plan.md +++ b/docs/phases-plan.md @@ -1,10 +1,9 @@ # Phased Plan (Starter Template) --- -**Last Updated:** 2025-01-17 -**Phase:** Phase 0 (Planning) -**Status:** Draft — update as phases complete -**Owner:** Product Team +**Phase:** Phase 0 (Planning) +**Status:** Draft — update as phases complete +**Owner:** Product Team **References:** - `/docs/project-overview.md` (project goals and requirements) - `/docs/backend/architecture.md` (technical implementation plan) diff --git a/docs/project-overview.md b/docs/project-overview.md index 4bc57c2..00a85ff 100644 --- a/docs/project-overview.md +++ b/docs/project-overview.md @@ -1,10 +1,9 @@ # Project Overview: Starter Template (Provider‑agnostic) --- -**Last Updated:** 2025-01-17 -**Phase:** Phase 0 (Planning) -**Status:** Draft -**Owner:** Product Team +**Phase:** Phase 0 (Planning) +**Status:** Draft +**Owner:** Product Team **References:** - `/docs/phases-plan.md` (development roadmap) - `/docs/content-structure.md` (app/screen structure) diff --git a/package.json b/package.json new file mode 100644 index 0000000..7aa5d75 --- /dev/null +++ b/package.json @@ -0,0 +1,10 @@ +{ + "name": "ai-template", + "version": "0.1.0", + "private": true, + "description": "Universal starter template for AI-assisted project documentation and agent profiles", + "license": "MIT", + "engines": { + "node": ">=20" + } +}