agentic-team-templates 0.3.0

package/templates/_shared/communication.md

@@ -0,0 +1,114 @@
+# Communication Guidelines
+
+How to communicate effectively when assisting with development tasks.
+
+## Tone and Style
+
+### Be Direct and Concise
+- Get to the point quickly
+- Avoid unnecessary filler words
+- Use clear, simple language
+- Prefer short paragraphs
+
+### Be Honest
+- If something doesn't work, say it doesn't work
+- If you don't know something, say you don't know
+- If there's a better approach, suggest it
+- Don't hide problems or risks
+
+### Be Objective
+- Focus on facts, not opinions
+- Provide evidence for claims
+- Acknowledge trade-offs
+- Present alternatives when relevant
+
+## Code Communication
+
+### When Showing Code Examples
+
+Always show both good and bad examples when illustrating patterns:
+
+```
+// Good: Clear intention
+const isActive = user.status === 'active';
+
+// Bad: Unclear
+const x = user.status === 'active';
+```
+
+### When Explaining Code
+
+- Start with what the code does at a high level
+- Then explain the details
+- Use code references with file paths and line numbers
+- Example: "The authentication check happens in `src/auth/middleware.ts:45`"
+
+### When Suggesting Changes
+
+- Explain *why* the change is needed
+- Show the current state and proposed state
+- Note any risks or considerations
+- Be specific about file locations
+
+## Avoiding Common Communication Issues
+
+### Don't Over-Explain
+❌ "I'm going to read the file to understand the code structure so I can make the changes you requested."
+✅ "Let me check the file." [then read it]
+
+### Don't Be Sycophantic
+❌ "That's a great question! You're absolutely right that..."
+✅ "The answer is..."
+
+### Don't Use Unnecessary Superlatives
+❌ "This is an excellent implementation!"
+✅ "This implementation handles the edge cases correctly."
+
+### Don't Hedge Excessively
+❌ "I think maybe this could potentially be an issue perhaps..."
+✅ "This may cause a race condition. Here's why..."
+
+## Asking Clarifying Questions
+
+When requirements are unclear:
+- Ask specific, focused questions
+- Provide options when possible
+- Explain why the clarification matters
+
+```
+Good: "Should the retry logic use exponential backoff or fixed intervals? Exponential is better for rate-limited APIs, fixed is simpler."
+
+Bad: "How do you want me to implement the retry logic?"
+```
+
+## Reporting Errors
+
+When something fails:
+1. State what went wrong clearly
+2. Provide the relevant error message
+3. Explain the likely cause
+4. Suggest next steps
+
+```
+The build failed with a TypeScript error in `src/api/users.ts:23`:
+
+  Type 'string' is not assignable to type 'number'.
+
+The `userId` parameter expects a number but is receiving a string from the URL params. We need to parse it: `const userId = parseInt(params.id, 10);`
+```
+
+## Progress Updates
+
+For longer tasks:
+- Indicate what you're doing at major steps
+- Report completion of significant milestones
+- Surface blockers immediately
+- Don't narrate every small action
+
+## Documentation
+
+When writing documentation:
+- Lead with the most important information
+- Use clear headings and structure
+- Include working code examples
+- Keep it up-to-date or delete it

package/templates/_shared/core-principles.md

@@ -0,0 +1,62 @@
+# 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.md

@@ -0,0 +1,165 @@
+# Git Workflow
+
+Universal git practices for maintaining clean, traceable project history.
+
+**Note**: For comprehensive commit and PR standards including semantic versioning, see the main `.cursorrules` directory:
+- [Commit Standards](../../.cursorrules/commit-standards.md)
+- [PR Standards](../../.cursorrules/pr-standards.md)
+
+## Commit Practices
+
+### Small, Meaningful Commits
+
+Commits should be atomic and focused:
+- One logical change per commit
+- Each commit should compile and pass tests
+- Separate refactoring from feature changes
+- Separate tests from implementation
+
+**Good commit examples:**
+- `feat(auth): add login button component`
+- `test(auth): add login button tests`
+- `fix(api): handle rate limit errors`
+- `refactor(utils): extract date formatting`
+
+**Bad commit examples:**
+- `WIP` or `fix stuff`
+- `add feature and fix bugs and update tests`
+- Giant commits with 50+ file changes
+
+### Commit Message Format (Conventional Commits)
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `test`: Tests
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Performance improvement
+- `chore`: Build process or auxiliary tool changes
+- `style`: Formatting, missing semicolons, etc. (no code change)
+- `ci`: CI configuration changes
+
+**Example:**
+```
+feat(auth): add OAuth integration
+
+- Implement OAuth callback handler
+- Add token validation
+- Set secure HTTP-only cookies
+
+Closes #123
+```
+
+## Branch Strategy
+
+### Feature Branches
+
+```bash
+# Create feature branch from main
+git checkout main
+git pull origin main
+git checkout -b feat/user-authentication
+
+# Work in small commits
+git add src/auth/login.ts
+git commit -m "feat(auth): add login component"
+
+git add tests/auth/login.test.ts
+git commit -m "test(auth): add login component tests"
+
+# Push and create PR
+git push origin feat/user-authentication
+```
+
+### Branch Naming
+
+- `feat/description` - New features
+- `fix/description` - Bug fixes
+- `refactor/description` - Code refactoring
+- `docs/description` - Documentation updates
+- `chore/description` - Maintenance tasks
+
+## Pull Request Guidelines
+
+### Before Creating PR
+
+- [ ] All tests pass locally
+- [ ] Code compiles without errors
+- [ ] Linting passes
+- [ ] Code is formatted
+- [ ] Self-review completed
+
+### PR Description Template
+
+```markdown
+## Summary
+Brief description of changes
+
+## Changes
+- Bullet points of specific changes
+
+## Testing
+How were these changes tested?
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+```
+
+## Safety Rules
+
+### Never Do These Without Explicit Permission
+
+- `git push --force` (especially to main/master)
+- `git reset --hard`
+- `git checkout .` or `git restore .`
+- `git clean -f`
+- `git branch -D`
+- Skip hooks (`--no-verify`)
+
+### Staging Best Practices
+
+- Stage specific files by name rather than `git add -A` or `git add .`
+- Review staged changes before committing: `git diff --staged`
+- Avoid accidentally staging sensitive files (.env, credentials, etc.)
+
+## Handling Mistakes
+
+### Amending Commits
+
+Only amend the most recent unpushed commit:
+```bash
+git add forgotten-file.ts
+git commit --amend --no-edit
+```
+
+### Fixing Pre-Commit Hook Failures
+
+When a pre-commit hook fails:
+1. The commit did NOT happen
+2. Fix the issue identified by the hook
+3. Re-stage the changes
+4. Create a NEW commit (don't amend the previous commit)
+
+### Undoing Local Changes
+
+```bash
+# Discard changes to a specific file
+git checkout -- path/to/file
+
+# Unstage a file (keep changes)
+git reset HEAD path/to/file
+
+# Undo last commit (keep changes)
+git reset --soft HEAD~1
+```

package/templates/_shared/security-fundamentals.md

@@ -0,0 +1,173 @@
+# Security Fundamentals
+
+Universal security practices applicable to all software development.
+
+## Core Security Principles
+
+### 1. Zero Trust
+Every input is hostile until proven otherwise.
+
+### 2. Defense in Depth
+Multiple layers of security, never rely on a single control.
+
+### 3. Least Privilege
+Grant minimum permissions necessary for the task.
+
+### 4. Fail Secure
+When something fails, fail to a secure state.
+
+## Input Validation
+
+### Validate Everything
+
+All external input must be validated:
+- User input (forms, URL parameters, headers)
+- API requests
+- File uploads
+- Environment variables at startup
+- Configuration files
+
+```
+// Good: Validate at system boundaries
+function createUser(input: unknown): Result<User, ValidationError> {
+  const parsed = UserSchema.safeParse(input);
+  if (!parsed.success) {
+    return err(new ValidationError(parsed.error));
+  }
+  return ok(processUser(parsed.data));
+}
+
+// Bad: Trust input
+function createUser(input: any): User {
+  return processUser(input);  // What if input is malicious?
+}
+```
+
+### Sanitize Output
+
+Always sanitize data before rendering or returning:
+- HTML encode for web display
+- Parameterize database queries
+- Encode for the target context (URL, JSON, XML, etc.)
+
+## Common Vulnerabilities (OWASP Top 10)
+
+### Injection (SQL, Command, etc.)
+
+❌ **Vulnerable:**
+```
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+exec(`convert ${filename} output.pdf`);
+```
+
+✅ **Secure:**
+```
+const query = 'SELECT * FROM users WHERE id = ?';
+db.query(query, [userId]);
+
+// Use libraries that handle escaping
+execFile('convert', [sanitizedFilename, 'output.pdf']);
+```
+
+### Cross-Site Scripting (XSS)
+
+❌ **Vulnerable:**
+```
+element.innerHTML = userInput;
+```
+
+✅ **Secure:**
+```
+element.textContent = userInput;
+// Or use a sanitization library for HTML
+element.innerHTML = DOMPurify.sanitize(userInput);
+```
+
+### Broken Authentication
+
+- Use established authentication libraries
+- Implement proper session management
+- Use secure, HTTP-only, SameSite cookies
+- Implement rate limiting on auth endpoints
+- Use CSRF tokens for state-changing operations
+
+### Sensitive Data Exposure
+
+- Never log sensitive data (passwords, tokens, PII)
+- Use HTTPS everywhere
+- Encrypt sensitive data at rest
+- Use secure password hashing (bcrypt, argon2)
+
+## Secrets Management
+
+### Never Commit Secrets
+
+- No API keys in code
+- No passwords in configuration files
+- No tokens in version control
+- Use `.gitignore` for sensitive files
+
+### Environment Variables
+
+```
+# .env.local (never committed)
+DATABASE_URL=postgres://...
+API_KEY=sk_live_...
+
+# .env.example (committed, no real values)
+DATABASE_URL=postgres://user:pass@localhost/db
+API_KEY=your_api_key_here
+```
+
+### Secret Rotation
+
+- Support secret rotation without downtime
+- Have a plan for compromised credentials
+- Audit secret access
+
+## Error Handling for Security
+
+### Don't Leak Information
+
+❌ **Leaky:**
+```
+catch (e) {
+  res.status(500).json({ error: e.stack });  // Reveals internals
+}
+
+// Login error
+res.json({ error: 'Password incorrect for user admin' });  // Confirms username exists
+```
+
+✅ **Secure:**
+```
+catch (e) {
+  logger.error('Internal error', { error: e, requestId });
+  res.status(500).json({ error: 'Internal server error', requestId });
+}
+
+// Login error
+res.json({ error: 'Invalid credentials' });  // Generic message
+```
+
+## Dependency Security
+
+- Keep dependencies updated
+- Audit dependencies regularly (`npm audit`, `pip-audit`, etc.)
+- Review new dependencies before adding
+- Prefer well-maintained, widely-used packages
+- Lock dependency versions
+
+## Security Checklist
+
+Before deployment:
+- [ ] All inputs validated
+- [ ] Outputs properly encoded
+- [ ] Authentication implemented correctly
+- [ ] Authorization checked on all protected resources
+- [ ] Secrets not in code or logs
+- [ ] HTTPS enforced
+- [ ] Security headers set (CSP, HSTS, etc.)
+- [ ] Dependencies audited
+- [ ] Rate limiting in place
+- [ ] Logging (without sensitive data) enabled