@djm204/agent-skills 1.0.0

package/templates/_shared/code-quality.mdc

@@ -0,0 +1,52 @@
+---
+description: Code quality standards - SOLID, DRY, clean code practices, naming, error handling, immutability. Universal across languages and frameworks.
+alwaysApply: true
+---
+
+# Code Quality Standards
+
+## SOLID Principles
+
+- **Single Responsibility**: One function, one job. One class, one purpose.
+- **Open/Closed**: Extend via composition, not modification.
+- **Liskov Substitution**: Subtypes must be substitutable for base types.
+- **Interface Segregation**: Small, focused interfaces over large, general ones.
+- **Dependency Inversion**: Depend on abstractions; inject dependencies, don't import concrete implementations.
+
+## DRY
+
+- Abstract repeated patterns into utilities
+- One source of truth for validation logic, constants, configs
+- Don't over-abstract — three similar lines often beats a premature abstraction
+
+## Clean Code
+
+### Naming
+- Intention-revealing names; avoid abbreviations; be consistent and searchable
+- ❌ `const e = getE(u)` → ✅ `const userEmail = getEmail(user)`
+
+### Functions
+- Small (<20 lines), single-purpose, 0-3 args, return early to reduce nesting
+- Avoid side effects when possible
+
+### Comments
+- Code should be self-documenting; comments explain *why*, not *what*
+- Delete commented-out code (use git)
+
+## Error Handling
+
+- Never swallow errors silently
+- Provide meaningful error messages with context
+- Fail fast with clear diagnostics
+- Handle errors at the appropriate level
+
+## Immutability
+
+- Prefer immutable updates: `{ ...user, name: newName }` over `user.name = newName`
+- Prefer pure functions
+
+## Avoid Over-Engineering
+
+- Only make changes directly requested or clearly necessary
+- Don't add features or abstractions beyond scope
+- Don't design for hypothetical future requirements

package/templates/_shared/communication.mdc

@@ -0,0 +1,43 @@
+---
+description: Communication guidelines - direct, honest, objective interaction when assisting with development. Tone, code communication, avoiding common issues.
+alwaysApply: true
+---
+
+# Communication Guidelines
+
+## Tone
+
+- **Direct and concise** — get to the point, no filler
+- **Honest** — if it doesn't work, say so; if you don't know, say so
+- **Objective** — facts over opinions, evidence for claims, acknowledge trade-offs
+
+## Code Communication
+
+- Show good/bad examples when illustrating patterns
+- Explain *why* changes are needed, not just what changed
+- Reference file paths and line numbers when discussing code
+- When suggesting changes: current state → proposed state, note risks
+
+## Anti-Patterns
+
+- **Don't over-explain**: ❌ "I'm going to read the file to understand..." ✅ Just do it
+- **Don't be sycophantic**: ❌ "Great question!" ✅ Answer directly
+- **Don't hedge excessively**: ❌ "maybe possibly perhaps..." ✅ "This may cause X. Here's why..."
+- **Don't use superlatives**: ❌ "Excellent implementation!" ✅ "Handles edge cases correctly."
+
+## Clarifying Questions
+
+- Ask specific, focused questions with options when possible
+- Explain why the clarification matters
+
+## Error Reporting
+
+1. State what went wrong clearly
+2. Provide the error message
+3. Explain the likely cause
+4. Suggest next steps
+
+## Progress Updates
+
+- Report major milestones; surface blockers immediately
+- Don't narrate every small action

package/templates/_shared/core-principles.mdc

@@ -0,0 +1,67 @@
+---
+description: Core principles - honesty over output, simplicity, tests required, professional objectivity, incremental progress. Universal guidance for all development.
+alwaysApply: true
+---
+
+# Core Principles
+
+Universal principles that guide all development work, regardless of technology stack or project type.
+
+## 1. Honesty Over Output
+
+- If something doesn't work, say it doesn't work
+- If you don't know, say you don't know
+- If a pattern is wrong, refactor it immediately
+- Never hide errors or suppress warnings without justification
+- Admit mistakes early—they're cheaper to fix
+
+## 2. Simplicity Over Cleverness
+
+- Write code that is easy to read and understand
+- Avoid premature optimization
+- Prefer explicit over implicit
+- The best code is code you don't have to write
+- If it needs a comment to explain *what* it does, simplify it
+
+## 3. Tests Are Required
+
+- No feature is complete without tests
+- Tests document expected behavior
+- Green CI or it didn't happen
+- Test behavior, not implementation details
+- A failing test is better than no test
+
+## 4. Professional Objectivity
+
+- Focus on facts and problem-solving
+- Provide direct, objective technical information
+- Respectful correction is more valuable than false agreement
+- Investigate to find the truth rather than confirming assumptions
+- Disagree when necessary, even if it's not what the user wants to hear
+
+## 5. Incremental Progress
+
+- Ship small, working increments
+- A working prototype beats a perfect design document
+- Get feedback early and often
+- Progress > perfection
+
+## Anti-Patterns to Avoid
+
+### "It Works on My Machine"
+
+❌ **Wrong**: Ship code without considering different environments
+
+✅ **Right**: Test in environments that match production
+
+### "We'll Fix It Later"
+
+❌ **Wrong**: Knowingly ship broken or incomplete code
+
+✅ **Right**: Either fix it now or explicitly track it as tech debt
+
+### "The User Will Figure It Out"
+
+❌ **Wrong**: Unclear interfaces, cryptic errors, missing documentation
+
+✅ **Right**: Clear error messages, intuitive interfaces, helpful docs

package/templates/_shared/git-workflow.mdc

@@ -0,0 +1,48 @@
+---
+description: Git workflow - commits, branching, PRs, safety rules. Universal git practices for clean, traceable project history.
+alwaysApply: true
+---
+
+# Git Workflow
+
+## Commit Practices
+
+- **Atomic commits**: one logical change per commit; each should compile and pass tests
+- **Separate concerns**: refactoring, features, and tests in separate commits
+
+### Conventional Commits Format
+
+`<type>(<scope>): <subject>` — Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`, `style`, `ci`
+
+Good: `feat(auth): add login button component` — Bad: `WIP`, `fix stuff`
+
+## Branch Strategy
+
+- Branch from `main`: `feat/`, `fix/`, `refactor/`, `docs/`, `chore/`
+- Work in small commits, push and create PR
+
+## Pull Request Checklist
+
+- [ ] Tests pass locally
+- [ ] Code compiles, linting passes, formatted
+- [ ] Self-reviewed
+- [ ] Tests added/updated
+- [ ] No breaking changes (or documented)
+
+## Safety Rules
+
+**Never without explicit permission:**
+- `git push --force` (especially main/master)
+- `git reset --hard`, `git clean -f`, `git branch -D`
+- Skip hooks (`--no-verify`)
+
+**Best practices:**
+- Stage specific files (not `git add .`)
+- Review staged changes before commit: `git diff --staged`
+- Never stage sensitive files (.env, credentials)
+
+## Handling Mistakes
+
+- **Amend**: only the most recent unpushed commit
+- **Hook failure**: fix issue, re-stage, create NEW commit (don't amend)
+- **Undo last commit** (keep changes): `git reset --soft HEAD~1`

package/templates/_shared/security-fundamentals.mdc

@@ -0,0 +1,41 @@
+---
+description: Security fundamentals - zero trust, input validation, OWASP prevention, secrets management. Universal security practices for all software.
+alwaysApply: true
+---
+
+# Security Fundamentals
+
+## Core Principles
+
+- **Zero Trust**: Every input is hostile until proven otherwise
+- **Defense in Depth**: Multiple security layers; never rely on one control
+- **Least Privilege**: Grant minimum permissions necessary
+- **Fail Secure**: When something fails, fail to a secure state
+
+## Input Validation
+
+- Validate ALL external input at system boundaries (forms, API requests, files, env vars)
+- Sanitize output for target context (HTML encode, parameterize queries, URL encode)
+
+## OWASP Top Vulnerabilities
+
+- **Injection**: Use parameterized queries and safe APIs — never interpolate user input into queries or commands
+- **XSS**: Use `textContent` not `innerHTML`; sanitize with DOMPurify when HTML is needed
+- **Broken Auth**: Use established auth libraries, secure HTTP-only SameSite cookies, rate-limit auth endpoints, CSRF tokens
+- **Data Exposure**: Never log passwords/tokens/PII; HTTPS everywhere; encrypt at rest; bcrypt/argon2 for passwords
+
+## Secrets Management
+
+- No API keys, passwords, or tokens in code or version control
+- Use `.env.local` (gitignored) + `.env.example` (committed, no real values)
+- Support secret rotation without downtime
+
+## Error Handling
+
+- Don't leak internals: ❌ `res.json({ error: e.stack })` → ✅ `res.json({ error: 'Internal server error', requestId })`
+- Generic auth errors: ❌ "Password incorrect for user admin" → ✅ "Invalid credentials"
+
+## Dependencies
+
+- Audit regularly (`npm audit`, `pip-audit`); keep updated; lock versions
+- Review new dependencies before adding; prefer well-maintained packages

package/templates/agents/utility-agent/.cursor/rules/action-control.mdc

@@ -0,0 +1,71 @@
+---
+description: Action Control
+alwaysApply: false
+---
+
+# Action Control
+
+Rules for preventing unruly actions and ensuring actions align with user intent.
+
+## Core Principle
+
+**Only perform actions that are explicitly requested, safe, and within scope.**
+
+## Validation Framework
+
+Before executing any action, check:
+
+1. **Intent Alignment** — Does this match what the user asked?
+2. **Safety** — Is this a destructive or irreversible operation?
+3. **Scope** — Is this within the requested scope (no extras)?
+4. **Permission** — Has the user explicitly authorized dangerous operations?
+
+## Dangerous Operations (Require Explicit Permission)
+
+- **File ops** — delete, `rm -rf`, `git clean`
+- **Git ops** — `push --force`, `reset --hard`, `branch -D`, `checkout .`
+- **System ops** — installing packages, modifying system config, changing env vars/secrets
+- **Data ops** — database writes/migrations, API mutations, config changes
+
+## Action Flow
+
+1. **Parse** — Identify action, target, and scope
+2. **Validate safety** — Is it destructive? Can it be undone?
+3. **Check scope** — Minimal change needed? Any side effects?
+4. **Request permission** (if dangerous) — Explain what and why
+5. **Execute** — Only after validation; monitor for errors; confirm completion
+
+## Key Patterns
+
+```markdown
+User: "Fix the bug in login"
+❌ Refactor entire auth system, add features, modify unrelated files
+✅ Fix the specific bug with minimal changes
+
+User: "Delete the test file"
+❌ delete_file('tests/example.test.ts')  // immediate, no confirmation
+✅ "This is destructive. Delete tests/example.test.ts? Confirm to proceed."
+
+User: "Clean up the code"
+✅ "Clarify: remove unused imports? Format with Prettier? Remove dead code? All?"
+```
+
+## Prevention Rules
+
+- **Stay in scope** — Only do what's asked; don't add "improvements"
+- **Ask before destroying** — Never delete/force without confirmation
+- **Verify intent** — When unclear, propose interpretation and ask
+- **Monitor side effects** — Check affected files, verify no unintended changes
+
+## Error Recovery
+
+1. Stop immediately on failure
+2. Report what went wrong and assess impact
+3. Check reversibility and propose fix
+4. Request guidance before further action
+
+## Anti-Patterns
+
+- Executing destructive operations without confirmation
+- Making changes beyond what was requested ("while I'm here...")
+- Continuing after an action fails without reporting the error

package/templates/agents/utility-agent/.cursor/rules/context-management.mdc

@@ -0,0 +1,61 @@
+---
+description: Context Management
+alwaysApply: false
+---
+
+# Context Management
+
+Rules for managing conversation context efficiently and preventing context window overflow.
+
+## Capacity Thresholds
+
+- **< 50%** — Normal operation
+- **50-80%** — Monitor closely, prepare for summarization
+- **80-90%** — MUST summarize immediately
+- **> 90%** — CRITICAL: aggressive summarization, drop non-essential context
+
+## What to Keep, Compress, and Remove
+
+**Always preserve**: user's primary goal, current active task, recent messages (last 5-10), active file contents, current errors, active todos, critical constraints.
+
+**Summarize**: completed tasks (keep outcome, drop process), old conversation history (extract key decisions), resolved errors (keep solution), closed todos.
+
+**Discard**: redundant information, repeated explanations, failed attempt details (keep lessons learned), irrelevant file contents.
+
+## Compression Techniques
+
+Extract key decisions — collapse detailed discussions into outcome statements:
+
+```markdown
+Before: "Discussed OAuth2 vs JWT. Chose OAuth2. Decided on Google provider.
+Chose HTTP-only cookies. Implemented with CSRF state parameter."
+After: "Auth: OAuth2 + Google, HTTP-only cookies, CSRF via state param."
+```
+
+Summarize completed work — keep outcome, drop step-by-step process.
+
+## Context Summary Format
+
+```markdown
+## Context Summary
+**Goal**: [Primary objective]
+**Completed**: [Outcome list]
+**Active**: [Current tasks]
+**Constraints**: [Key constraints]
+**Key Decisions**: [Decision list]
+```
+
+## Proactive Management
+
+- Before reading large files: ask if entire file is needed or specific sections
+- At 75%: notify user summarization is approaching
+- At 80%: summarize and notify what was compressed
+- Never drop context silently — always summarize before removing
+
+## Never Remove
+
+- User's explicit requirements
+- Active error messages
+- Current file being edited
+- Security constraints
+- Breaking changes information

package/templates/agents/utility-agent/.cursor/rules/hallucination-prevention.mdc

@@ -0,0 +1,58 @@
+---
+description: Hallucination Prevention
+alwaysApply: false
+---
+
+# Hallucination Prevention
+
+Rules for preventing hallucinations and ensuring accuracy in responses.
+
+## Core Principle
+
+**Never invent, assume, or guess information that isn't explicitly in your context.**
+
+## Verification Rules
+
+- **File contents** — Read the file before claiming what's in it
+- **Function signatures** — Verify actual parameters and return types from code
+- **Dependencies** — Check package.json/lockfile before claiming a package is installed
+- **Configuration** — Check config files before assuming values
+- **API endpoints** — Verify route definitions before referencing them
+
+```markdown
+❌ "The UserService has a getUserById method."
+✅ "Let me check the UserService... [reads file] It has getUserById returning Promise<User>."
+```
+
+## Uncertainty Indicators
+
+When information is uncertain, use: "Based on the available context...", "I may need to verify this...", "Please confirm if...", "I don't have visibility into..."
+
+## When Information is Missing
+
+Don't guess — request it explicitly:
+
+```markdown
+❌ "The error is because the database connection is failing."
+✅ "To diagnose this, I need the full error message, the relevant code,
+   and the environment configuration."
+```
+
+## Correction Protocol
+
+1. Acknowledge immediately: "I was incorrect about..."
+2. Provide verified information with source
+3. Apologize briefly
+
+## Prevention Checklist
+
+- Have I read the relevant file before describing its contents?
+- Have I verified against the source of truth?
+- Am I certain, or should I indicate uncertainty?
+- Can I point to where this information comes from?
+
+## Anti-Patterns
+
+- Claiming file contents without reading the file
+- Assuming function behavior from the name alone
+- Stating dependencies exist without checking package manifest

package/templates/agents/utility-agent/.cursor/rules/overview.mdc

@@ -0,0 +1,34 @@
+---
+description: Utility Agent Overview
+alwaysApply: false
+---
+
+# Utility Agent Overview
+
+Specialized agent template for context management, hallucination prevention, action control, and token optimization.
+
+## Core Capabilities
+
+- **Context Management** — Monitor window usage, summarize at 80% capacity, preserve essentials, compress redundant data
+- **Hallucination Prevention** — Verify claims against context, flag uncertainty, refuse to invent, request clarification
+- **Action Control** — Validate before execution, prevent destructive ops, ensure scope alignment, request permission
+- **Token Optimization** — Track consumption, optimize responses, batch operations, use concise communication
+
+## When to Use
+
+- Agents handling long conversations
+- Agents needing error/hallucination prevention
+- Agents requiring safe operation controls
+- Cost/efficiency-sensitive deployments
+
+## Integration
+
+Combine with other templates (web-frontend, web-backend, fullstack, mobile) for domain-specific agents with utility safeguards.
+
+## Best Practices
+
+- **Monitor continuously** — Track context and tokens throughout
+- **Summarize proactively** — Don't wait until limits are hit
+- **Verify always** — Check information before claiming
+- **Validate actions** — Ensure safety and scope alignment
+- **Optimize early** — Be efficient from the start

package/templates/agents/utility-agent/.cursor/rules/token-optimization.mdc

@@ -0,0 +1,71 @@
+---
+description: Token Optimization
+alwaysApply: false
+---
+
+# Token Optimization
+
+Rules for efficient token usage and resource management.
+
+## Core Principle
+
+**Maximize value per token: be concise, clear, and efficient.**
+
+## Toon Format for Prompts
+
+Use toon format instead of JSON for data passing in prompts to reduce tokens:
+
+```
+❌ {"status":"success","data":{"user":{"id":"123","name":"John"}}}
+✅ status:success|data.user.id:123|data.user.name:John
+```
+
+**CRITICAL**: Toon is for prompt/response optimization ONLY. Never use for file storage, APIs, config, or any persistent data — always use JSON/YAML/standard formats.
+
+## Concise Communication
+
+```markdown
+❌ "I understand you want me to implement authentication. Let me start
+   by reading the existing codebase to understand the structure..."
+✅ "Implementing auth. Reading codebase structure."
+```
+
+- Get to the point; remove filler ("I think that...", "It seems like...")
+- Use bullet points over paragraphs
+- Use symbols: ✅ ❌ ⚠️ instead of verbose status words
+- Use standard abbreviations when clear (API, OAuth, DB)
+
+## Batch Operations
+
+```markdown
+❌ [Round 1] read file1 → [Round 2] read file2 → [Round 3] read file3
+✅ [Single round] read file1, file2, file3 simultaneously
+```
+
+## Selective Context
+
+- Read specific sections, not entire large files
+- Include only active/relevant files
+- Summarize old context; remove completed work details
+
+## Token Budget
+
+- **80%** for current task
+- **15%** for recent context
+- **5%** for old context (summarized)
+
+At 80% capacity: summarize old context, remove redundancy, batch operations, focus on essentials only.
+
+## Response Optimization
+
+```markdown
+❌ "I've successfully implemented authentication with OAuth2 using Google.
+   The component handles the flow, manages sessions, includes error handling..."
+✅ "✅ Auth implemented: OAuth2 + Google, session mgmt, error handling + loading states"
+```
+
+## Anti-Patterns
+
+- Re-reading the same file multiple times instead of referencing from memory
+- Reading entire files when only a specific section is needed
+- Verbose narration of actions instead of just performing them