@silverassist/agents-toolkit 2.0.0

package/templates/agents/CLAUDE.md

@@ -0,0 +1,213 @@
+# Claude Code Instructions
+
+This file contains project-wide instructions for Claude Code.
+
+## Agent Workflow for Complex Tasks
+
+When implementing new features, refactoring code, or fixing complex issues, **always follow this systematic workflow**:
+
+### Phase 1: Initial Analysis
+1. **Analyze the request** - Understand the full scope, dependencies, and potential impacts
+2. **Search existing code** - Use semantic search and grep to understand current implementation
+3. **Identify components** - List all files, functions, and components that need changes
+4. **Review documentation** - Check existing docs for patterns and conventions
+
+### Phase 2: Planning Documentation
+1. **Create planning document** - `docs/[feature-name]-plan.md` with:
+   - Problem statement and objectives
+   - Current architecture analysis
+   - Proposed changes with before/after code examples
+   - Risk assessment and mitigation strategies
+   - Phase breakdown if complex
+2. **Add action plan** - Detailed step-by-step implementation guide
+3. **Create TODO list** - Use the TodoWrite tool to track all phases
+4. **Commit planning** - `git commit -m "PROJECT-XXX: Add [feature] implementation plan"`
+
+### Phase 3: Implementation by Phases
+For each phase:
+1. **Mark TODO as in-progress** - Update status before starting work
+2. **Implement changes** - Make code changes following the plan
+3. **Write/update tests** - Add unit tests, ensure regression tests pass
+4. **Run tests** - `npm test` to verify no regressions
+5. **Mark TODO as completed** - Update status after successful implementation
+6. **Commit phase** - `git commit -m "PROJECT-XXX: Implement [feature] - Phase N"`
+
+### Phase 4: Final Documentation
+1. **Create final documentation** - `docs/[feature-name].md`
+2. **Update related docs** - Update `project-overview.md`, `readme.md`, etc.
+3. **Delete planning docs** - Remove temporary planning documents
+4. **Final commit** - `git commit -m "PROJECT-XXX: Add [feature] documentation"`
+
+### Key Principles
+- ✅ **One commit per phase** - Create clear checkpoint commits
+- ✅ **Test everything** - Run full test suite after each phase
+- ✅ **No breaking changes** - Ensure backward compatibility
+- ✅ **Document as you go** - Update docs with each phase
+- ✅ **Type safety** - Maintain full TypeScript coverage
+
+## Slash Commands
+
+Custom slash commands are available in `.claude/commands/`:
+
+| Command | Description |
+|---------|-------------|
+| `/analyze-ticket` | Analyze a Jira ticket without making changes |
+| `/create-plan` | Create an implementation plan for a ticket |
+| `/work-ticket` | Start working on a Jira ticket with full workflow setup |
+| `/prepare-pr` | Prepare code for pull request review |
+| `/create-pr` | Create and submit a pull request |
+| `/finalize-pr` | Finalize and merge a pull request |
+| `/review-code` | Review code for quality and issues |
+| `/fix-issues` | Fix identified code issues |
+| `/add-tests` | Add tests for existing code |
+
+## Key Technologies & Frameworks
+
+- **Next.js 15.x** with App Router for modern React development
+- **React 19** for latest React features and optimizations
+- **TypeScript** for comprehensive type safety
+- **Tailwind CSS v4** with custom CSS variables and shadcn/ui design system
+- **Jest & React Testing Library** for comprehensive testing
+
+## Domain-Driven Design (DDD) Principles
+
+This project follows **Domain-Driven Design** principles.
+
+**Core Principles**:
+1. **Group by Domain, Not by Type** - Organize files by business domain rather than technical type
+2. **Clear Boundaries** - Each domain has well-defined responsibilities
+3. **Colocation** - Related code (components, utils, tests) lives together
+
+**Quick Rules**:
+- ✅ Create domain folders that match business concepts
+- ✅ Keep domain-specific utilities inside domain folders
+- ✅ Place tests in `__tests__/` subfolders within each domain
+- ❌ Don't create generic folders like "helpers", "services", "utils" at root level
+
+## Key Conventions
+
+### Code Style & Organization
+
+- **Imports**: Always organize imports alphabetically within each group
+- **API Functions**: Must have descriptive JSDoc comments in English
+- **Types**: Define interfaces and types properly, not directly in components
+- **No `any` Type**: Always define explicit types using `type` or `interface`
+- **File Naming**: All files should use kebab-case (e.g., `use-hash.ts`, `contact-form.tsx`)
+- **Object Destructuring**: Always use destructuring when iterating over objects
+- **Error Handling**: Apply robust error handling with try/catch for async operations
+- **Import Paths**: Always use absolute imports with `@/` prefix
+
+### Component Structure & Naming
+
+**CRITICAL: All components must follow these strict conventions:**
+
+#### 1. Folder & File Naming
+
+- **Folder names**: MUST use kebab-case (e.g., `user-profile/`, `checkout-wizard/`)
+- **File structure**: Every component MUST be in its own folder with an `index.tsx` file
+- **❌ NEVER**: Use camelCase or PascalCase for folder names
+- **❌ NEVER**: Create standalone component files like `Component.tsx` at root level
+
+```
+✅ CORRECT:
+src/components/user-profile/index.tsx
+src/components/contact-form/index.tsx
+
+❌ INCORRECT:
+src/components/UserProfile.tsx
+src/components/userProfile/index.tsx
+```
+
+#### 2. Component Export Pattern
+
+- **Function name**: MUST use PascalCase for the exported function
+- **Export statement**: MUST use `export default function` for components
+- **Barrel file**: Re-export with a named alias from the domain `index.ts`
+- **Single responsibility**: Each file should export ONLY the component function
+
+```typescript
+// ✅ CORRECT: src/components/user-profile/index.tsx
+interface UserProfileProps {
+  userId: string;
+  className?: string;
+}
+
+export default function UserProfile({ userId, className }: UserProfileProps) {
+  // Component implementation
+}
+
+// ✅ CORRECT: src/components/index.ts (barrel)
+export { default as UserProfile } from "./user-profile";
+```
+
+#### 3. Props Interface Definition
+
+- **MUST**: Define props interface INSIDE the component file
+- **Interface name**: MUST match component name + "Props" suffix (PascalCase)
+- **Location**: Define interface immediately BEFORE the component function
+
+#### 4. Separation of Concerns
+
+- **Component file**: ONLY the component function and its props interface
+- **Helper functions**: Create separate `helpers.ts` or `utils.ts` in same folder
+- **Types/Interfaces**: Create separate `types.ts` if multiple types are shared
+- **Constants**: Create separate `constants.ts` for component-specific constants
+
+---
+
+## React Patterns
+
+### Hook Placement Rules (CRITICAL)
+
+**✅ Correct:** All hooks before conditional returns
+
+```typescript
+export default function Component({ data }: Props) {
+  const [state, setState] = useState(initialState);
+  const handleClick = useCallback(() => {}, []);
+
+  // Early returns AFTER all hooks
+  if (!data) return null;
+  
+  return <div>...</div>;
+}
+```
+
+**❌ Incorrect:** Hooks after conditional returns
+
+```typescript
+export function Component({ data }: Props) {
+  if (!data) return null; // ❌ Early return before hooks
+  
+  const [state, setState] = useState(initialState); // ❌ Error!
+  return <div>...</div>;
+}
+```
+
+---
+
+## Git Commit Guidelines
+
+### Commit Message Format
+
+```
+TYPE-XXX: Brief description
+
+- Detailed change 1
+- Detailed change 2
+```
+
+### Commit Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+### Branch Naming
+
+- `feature/TYPE-XXX-brief-description`
+- `bugfix/TYPE-XXX-brief-description`
+- `hotfix/TYPE-XXX-brief-description`

package/templates/agents/copilot-instructions.md

@@ -0,0 +1,83 @@
+# Copilot Instructions
+
+This file contains project-wide instructions for GitHub Copilot.
+
+## 🔄 Copilot Agent Workflow for Complex Tasks
+
+When implementing new features, refactoring code, or fixing complex issues, **always follow this systematic workflow**:
+
+### Phase 1: Initial Analysis
+1. **Analyze the request** - Understand the full scope, dependencies, and potential impacts
+2. **Search existing code** - Use semantic search and grep to understand current implementation
+3. **Identify components** - List all files, functions, and components that need changes
+4. **Review documentation** - Check existing docs for patterns and conventions
+
+### Phase 2: Planning Documentation
+1. **Create planning document** - `docs/[feature-name]-plan.md` with:
+   - Problem statement and objectives
+   - Current architecture analysis
+   - Proposed changes with before/after code examples
+   - Risk assessment and mitigation strategies
+   - Phase breakdown if complex
+2. **Add action plan** - Detailed step-by-step implementation guide
+3. **Create TODO list** - Use `manage_todo_list` tool to track all phases
+4. **Commit planning** - `git commit -m "PROJECT-XXX: Add [feature] implementation plan"`
+
+### Phase 3: Implementation by Phases
+For each phase:
+1. **Mark TODO as in-progress** - Update status before starting work
+2. **Implement changes** - Make code changes following the plan
+3. **Write/update tests** - Add unit tests, ensure regression tests pass
+4. **Run tests** - `npm test` to verify no regressions
+5. **Mark TODO as completed** - Update status after successful implementation
+6. **Commit phase** - `git commit -m "PROJECT-XXX: Implement [feature] - Phase N"`
+
+### Phase 4: Final Documentation
+1. **Create final documentation** - `docs/[feature-name].md`
+2. **Update related docs** - Update `project-overview.md`, `readme.md`, etc.
+3. **Delete planning docs** - Remove temporary planning documents
+4. **Final commit** - `git commit -m "PROJECT-XXX: Add [feature] documentation"`
+
+### Key Principles
+- ✅ **One commit per phase** - Create clear checkpoint commits
+- ✅ **Test everything** - Run full test suite after each phase
+- ✅ **No breaking changes** - Ensure backward compatibility
+- ✅ **Document as you go** - Update docs with each phase
+- ✅ **Type safety** - Maintain full TypeScript coverage
+
+## Key Technologies & Frameworks
+
+- **Next.js 15.x** with App Router for modern React development
+- **React 19** for latest React features and optimizations
+- **TypeScript** for comprehensive type safety
+- **Tailwind CSS v4** with custom CSS variables and shadcn/ui design system
+- **Jest & React Testing Library** for comprehensive testing
+
+## Domain-Driven Design (DDD) Principles
+
+This project follows **Domain-Driven Design** principles. See the `domain-driven-design` skill for detailed guidelines.
+
+**Core Principles**:
+1. **Group by Domain, Not by Type** - Organize files by business domain rather than technical type
+2. **Clear Boundaries** - Each domain has well-defined responsibilities
+3. **Colocation** - Related code (components, utils, tests) lives together
+
+**Quick Rules**:
+- ✅ Create domain folders that match business concepts
+- ✅ Keep domain-specific utilities inside domain folders
+- ✅ Place tests in `__tests__/` subfolders within each domain
+- ❌ Don't create generic folders like "helpers", "services", "utils" at root level
+
+## Barrel Export Pattern
+
+Use **barrel exports** (`index.ts`) for folders with multiple internal files:
+
+```typescript
+// src/lib/api/index.ts
+export * from "./client";
+export * from "./endpoints";
+export * from "./types";
+
+// Usage - Clean imports from domain
+import { apiClient, fetchUser } from "@/lib/api";
+```

package/templates/shared/instructions/css-styling.instructions.md

@@ -0,0 +1,142 @@
+---
+applyTo: "**/*.{css,tsx}"
+---
+# Tailwind CSS & shadcn/ui Standards
+
+## Use Design Tokens (Semantic Colors)
+
+**✅ ALWAYS use semantic color tokens** instead of hardcoded colors:
+
+```tsx
+// ✅ CORRECT: Semantic tokens
+<div className="bg-background text-foreground" />
+<div className="bg-card text-card-foreground border-border" />
+<div className="bg-primary text-primary-foreground" />
+<div className="bg-destructive text-destructive-foreground" />
+<div className="bg-muted text-muted-foreground" />
+
+// ❌ INCORRECT: Hardcoded colors
+<div className="bg-white text-black" />
+<div className="bg-blue-500 text-white" />
+```
+
+## Use cn() Utility for Conditional Classes
+
+**✅ ALWAYS use cn()** from `@/lib/utils` for conditional styling:
+
+```tsx
+import { cn } from "@/lib/utils";
+
+// ✅ CORRECT: Using cn() utility
+<button
+  className={cn(
+    "px-4 py-2 rounded-md font-medium",
+    "bg-primary text-primary-foreground",
+    isDisabled && "opacity-50 cursor-not-allowed",
+    isActive && "ring-2 ring-ring ring-offset-2",
+    className  // Allow prop override
+  )}
+/>
+
+// ❌ INCORRECT: Template literals
+<button
+  className={`px-4 py-2 ${isDisabled ? 'opacity-50' : ''}`}
+/>
+```
+
+### Setting Up cn() Utility
+
+If you don't have the `cn()` utility yet (it's installed automatically with shadcn/ui):
+
+```bash
+npm install clsx tailwind-merge
+```
+
+```typescript
+// src/lib/utils.ts
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Merges and combines Tailwind CSS classes.
+ * Uses clsx for conditional classes and tailwind-merge to handle conflicts.
+ * @param inputs - The Tailwind CSS classes to merge
+ * @returns The merged Tailwind CSS classes
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+```
+
+## Responsive Design (Mobile-First)
+
+**✅ ALWAYS use mobile-first responsive design**:
+
+```tsx
+// ✅ CORRECT: Mobile-first (sm → md → lg → xl)
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4" />
+<div className="text-sm md:text-base lg:text-lg" />
+<div className="p-4 md:p-6 lg:p-8" />
+<div className="flex flex-col md:flex-row" />
+
+// ❌ INCORRECT: Desktop-first (working backwards)
+<div className="grid grid-cols-4 lg:grid-cols-3 md:grid-cols-2 sm:grid-cols-1" />
+```
+
+## shadcn/ui Component Usage
+
+**✅ IMPORT from component path**:
+
+```tsx
+// ✅ CORRECT: Import from component path
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader } from "@/components/ui/card";
+
+// Use with variants
+<Button variant="default">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+```
+
+## Typography
+
+**✅ USE prose classes for content** and utility classes for UI:
+
+```tsx
+// ✅ CORRECT: UI typography
+<h1 className="text-3xl font-bold tracking-tight" />
+<p className="text-sm text-muted-foreground" />
+
+// ✅ CORRECT: Content typography (prose)
+<article className="prose prose-lg dark:prose-invert" />
+
+// ✅ Font families
+<div className="font-sans" />   // Default font
+<code className="font-mono" />  // Monospace font
+```
+
+## Avoiding Common Mistakes
+
+```tsx
+// ❌ AVOID: Conflicting classes
+<div className="p-4 p-6" />  // Which one wins?
+
+// ❌ AVOID: Redundant classes
+<div className="flex flex-row" />  // flex-row is default
+
+// ❌ AVOID: Inline styles when Tailwind works
+<div style={{ padding: '16px' }} />  // Use className="p-4"
+```
+
+## Styling Checklist
+
+Before committing styled components, verify:
+
+- [ ] Using semantic color tokens (not hardcoded)
+- [ ] Using `cn()` for conditional classes
+- [ ] Mobile-first responsive design
+- [ ] Consistent spacing from Tailwind scale
+- [ ] shadcn/ui components imported correctly
+- [ ] No conflicting or redundant classes

package/templates/shared/instructions/documentation-language.instructions.md

@@ -0,0 +1,216 @@
+---
+description: Language policy (English-only for technical content), documentation standards, commit messages, and PR conventions for Silver Assist plugins
+name: Documentation & Language Policy
+applyTo: "**"
+---
+
+# Documentation & Language Policy — Silver Assist Plugins
+
+---
+
+## Language Policy
+
+### English-Only Rule
+
+**ALL technical project files MUST be written in ENGLISH:**
+
+- Code comments (PHP, JavaScript, CSS)
+- Documentation files (`.md`)
+- Commit messages
+- Pull Request descriptions
+- Issue descriptions
+- GitHub Actions workflows (`.yml`)
+- Scripts (`.sh`, `.php`)
+- README files
+- Code variable/function names
+
+**Exception — Spanish allowed:**
+- User-facing content in WordPress admin (translation files `.pot`, `.po`)
+- Content entered by end users
+
+---
+
+## Documentation Standards
+
+### File Naming
+
+- Major docs: `UPPERCASE.md` (README, CHANGELOG, LICENSE, CONTRIBUTING)
+- Specific guides: `lowercase-with-hyphens.md`
+- Always use `.md` extension, no spaces
+
+### Markdown Best Practices
+
+- One `# H1` per file (document title)
+- Specify language in code blocks (```php, ```bash)
+- Use `**Bold**` for important terms, `` `code` `` for inline code
+- Use numbered lists for sequential steps, bullet lists for non-sequential
+
+### Callout Conventions
+
+```markdown
+**⚠️ WARNING**: Important warning message
+**✅ TIP**: Best practice
+**❌ AVOID**: Things to avoid
+**🔥 CRITICAL**: Critical information
+```
+
+---
+
+## Commit Message Standards (Conventional Commits)
+
+### Format
+
+```
+type(scope): brief description
+
+Detailed explanation (optional)
+
+Closes #issue-number (if applicable)
+```
+
+### Types
+
+| Type | Usage | Example |
+|------|-------|---------|
+| `feat` | New features | `feat: Add search by sender name` |
+| `fix` | Bug fixes | `fix: Resolve N+1 query in log table` |
+| `docs` | Documentation only | `docs: Update README with new features` |
+| `style` | Code style (no logic change) | `style: Format PHP files with PHPCS` |
+| `refactor` | Code refactoring | `refactor: Extract LogWriter from RequestLogger` |
+| `perf` | Performance improvements | `perf: Cache resolved error IDs` |
+| `test` | Add or update tests | `test: Add unit tests for sender search` |
+| `build` | Build system changes | `build: Update composer dependencies` |
+| `ci` | CI/CD changes | `ci: Pin actions to SHA hashes` |
+| `chore` | Maintenance tasks | `chore: Update dependencies` |
+
+### Examples
+
+**Good:**
+```
+feat: Add unresolved errors filter with resolved badge
+
+- Add "Unresolved" tab in logs table
+- Show green "Resolved" badge for errors with successful retry
+- Cache resolved IDs to prevent N+1 queries
+
+Closes #56
+```
+
+**Bad:**
+```
+updates
+Fixed bug
+Added new feature
+```
+
+---
+
+## Jira-Based Commits (WordPress Website Projects)
+
+For WordPress website backend projects (aa-wp, familyassets-wp, osa-wp, assistedlivingorg-wp), use Jira ticket prefixes:
+
+### Format
+
+```
+WEB-XXX: Brief description
+```
+
+### Examples
+
+```bash
+# Good
+WEB-726: Setup WordPress 6.8.2 headless backend with Docker
+WEB-734: Fix GraphQL query error in nextjs-graphql-hooks plugin
+WEB-740: Add Elementor integration for headless CMS
+WEB-758: Update Docker configuration for PHP 8.3
+
+# Bad
+updates
+Fixed bug
+WEB-726 (missing colon)
+```
+
+### Branch Naming
+
+```
+feature/WEB-XXX-description  # New features
+bugfix/WEB-XXX-description   # Bug fixes
+```
+
+### Protected Branches (Never Commit Directly)
+
+- `main`, `master`, `dev`, `stg`, `staging`
+
+---
+
+## Pull Request Standards
+
+### PR Title
+
+Same convention as commit messages: `type: brief description`
+
+### PR Description Template
+
+```markdown
+## Description
+Brief summary of changes (1-2 sentences).
+
+## Changes
+- Specific change 1
+- Specific change 2
+
+## Testing
+- [ ] PHPCS passes (0 errors)
+- [ ] PHPStan Level 8 passes
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+
+## Related Issues
+Closes #issue-number
+
+## Checklist
+- [ ] Code follows WordPress Coding Standards
+- [ ] Documentation updated
+- [ ] Tests added/updated
+```
+
+---
+
+## Code Comments Standards
+
+### Class Headers
+
+```php
+/**
+ * Class description.
+ *
+ * @since X.Y.Z
+ */
+class ClassName {
+}
+```
+
+### Method/Function Comments
+
+```php
+/**
+ * Brief description of what the method does.
+ *
+ * @since X.Y.Z
+ *
+ * @param string $param1 Description.
+ * @param array  $param2 Description.
+ * @return bool True on success, false on failure.
+ */
+public function method_name( string $param1, array $param2 ): bool {
+}
+```
+
+### Inline Comments
+
+```php
+// Single-line comment ending with period.
+
+// TODO: Future enhancement description.
+// FIXME: Known issue that needs fixing.
+```