agentic-team-templates 0.3.0

package/templates/documentation/.cursorrules/code-comments.md

@@ -0,0 +1,253 @@
+# Code Comments
+
+Guidelines for inline comments, docstrings, and API documentation.
+
+## The Comment Hierarchy
+
+### 1. Self-Documenting Code (Preferred)
+
+Good naming eliminates the need for most comments.
+
+```typescript
+// Bad: Requires comment to understand
+const d = 86400; // seconds in a day
+
+// Good: Self-documenting
+const SECONDS_PER_DAY = 86400;
+```
+
+```typescript
+// Bad: Comment explains what code does
+// Check if user is admin
+if (user.role === 'admin') { ... }
+
+// Good: Code speaks for itself
+if (user.isAdmin()) { ... }
+```
+
+### 2. Inline Comments (Why, Not What)
+
+Comments explain *why*, not *what*. The code shows what; comments show intent.
+
+```typescript
+// Good: Explains why
+// Using retry logic because the payment API is flaky during peak hours
+await retryWithBackoff(processPayment, 3);
+
+// Bad: Explains what (obvious from code)
+// Increment counter by 1
+counter++;
+
+// Bad: Outdated comment
+// Send email to user
+await sendSlackNotification(user); // Code changed, comment didn't
+```
+
+### 3. Warning Comments
+
+Flag non-obvious gotchas and constraints.
+
+```typescript
+// WARNING: This function is not thread-safe. 
+// Always call from the main thread.
+function updateGlobalState() { ... }
+
+// HACK: Workaround for Chrome bug #12345
+// Remove after Chrome 120 ships
+element.style.transform = 'translateZ(0)';
+
+// TODO(username): Refactor when API v2 launches
+// Tracking issue: #456
+```
+
+## API Documentation (Docstrings)
+
+### Purpose
+
+API documentation is **the contract** for how code must behave. It tells future developers:
+- What the function/class does
+- How to use it
+- What to expect
+
+### TypeScript/JavaScript (JSDoc/TSDoc)
+
+```typescript
+/**
+ * Calculates the total price including tax and discounts.
+ * 
+ * @param items - Array of cart items to price
+ * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
+ * @param couponCode - Optional discount coupon
+ * @returns The final price in cents
+ * @throws {InvalidCouponError} If coupon code is expired or invalid
+ * 
+ * @example
+ * ```ts
+ * const total = calculateTotal(cartItems, 0.08, 'SAVE10');
+ * ```
+ */
+function calculateTotal(
+  items: CartItem[],
+  taxRate: number,
+  couponCode?: string
+): number { ... }
+```
+
+### Python (Docstrings)
+
+```python
+def calculate_total(items: list[CartItem], tax_rate: float, coupon_code: str | None = None) -> int:
+    """
+    Calculate the total price including tax and discounts.
+
+    Args:
+        items: List of cart items to price.
+        tax_rate: Tax rate as decimal (e.g., 0.08 for 8%).
+        coupon_code: Optional discount coupon.
+
+    Returns:
+        The final price in cents.
+
+    Raises:
+        InvalidCouponError: If coupon code is expired or invalid.
+
+    Example:
+        >>> total = calculate_total(cart_items, 0.08, 'SAVE10')
+    """
+    ...
+```
+
+### Go (Godoc)
+
+```go
+// CalculateTotal computes the final price including tax and discounts.
+//
+// The taxRate should be provided as a decimal (e.g., 0.08 for 8%).
+// If couponCode is empty, no discount is applied.
+//
+// Returns an error if the coupon code is expired or invalid.
+func CalculateTotal(items []CartItem, taxRate float64, couponCode string) (int, error) {
+    ...
+}
+```
+
+## What to Document
+
+### Always Document
+
+```typescript
+/**
+ * Public functions and methods
+ * - What it does (one sentence)
+ * - Parameters and return values
+ * - Exceptions/errors thrown
+ * - Example usage for complex APIs
+ */
+
+/**
+ * Non-obvious constraints
+ * - Thread safety requirements
+ * - Performance characteristics
+ * - Valid input ranges
+ */
+
+/**
+ * Side effects
+ * - External API calls
+ * - Database modifications
+ * - File system changes
+ */
+```
+
+### Skip Documentation For
+
+```typescript
+// Obvious getters/setters (unless they have side effects)
+function getName(): string { return this.name; }
+
+// Private implementation details
+private parseInternal(data: Buffer): void { ... }
+
+// Self-explanatory one-liners
+const isActive = user.status === 'active';
+```
+
+## Class/Module Documentation
+
+```typescript
+/**
+ * Manages user authentication and session lifecycle.
+ * 
+ * This service handles login, logout, token refresh, and session
+ * validation. All methods are thread-safe.
+ * 
+ * @example Basic usage
+ * ```ts
+ * const auth = new AuthService(config);
+ * const session = await auth.login(credentials);
+ * ```
+ * 
+ * @example With token refresh
+ * ```ts
+ * auth.on('tokenExpiring', async () => {
+ *   await auth.refreshToken();
+ * });
+ * ```
+ */
+class AuthService { ... }
+```
+
+## Comment Anti-Patterns
+
+### Commented-Out Code
+
+```typescript
+// Bad: Use version control instead
+// function oldImplementation() {
+//   return legacyCalculation();
+// }
+function newImplementation() { ... }
+```
+
+### Noise Comments
+
+```typescript
+// Bad: Adds no value
+// Constructor
+constructor() { }
+
+// Bad: Repeats the obvious
+// Loop through users
+for (const user of users) { }
+```
+
+### Outdated Comments
+
+```typescript
+// Bad: Comment lies about what code does
+// Returns the user's full name
+function getDisplayName(user: User): string {
+  return user.username; // Actually returns username
+}
+```
+
+## Comment Formatting
+
+### Use Consistent Style
+
+```typescript
+// Single-line comments for brief notes
+// Use sentence case with period.
+
+/**
+ * Multi-line comments for API documentation.
+ * Keep lines under 80-100 characters.
+ * Use proper grammar and punctuation.
+ */
+
+// TODO: Use consistent format for action items
+// TODO(username): Include who if assignment needed
+// FIXME: For bugs that need fixing
+// HACK: For temporary workarounds
+// NOTE: For important clarifications
+```

package/templates/documentation/.cursorrules/maintenance.md

@@ -0,0 +1,260 @@
+# Documentation Maintenance
+
+Guidelines for keeping documentation fresh, accurate, and useful.
+
+## Core Principle
+
+> Dead docs are bad. They misinform, they slow down, they incite despair in
+> engineers and laziness in team leads. — Google Documentation Guide
+
+## The Same-Commit Rule
+
+**Documentation changes belong in the same commit as code changes.**
+
+```bash
+# Good: Docs updated with code
+git commit -m "feat: add payment retry logic
+
+- Add exponential backoff for failed payments
+- Update API docs with new retry behavior
+- Add example to README"
+
+# Bad: Docs updated separately (or never)
+git commit -m "feat: add payment retry logic"
+# ... 3 weeks later ...
+git commit -m "docs: update payment docs"  # If remembered at all
+```
+
+## Delete Dead Documentation
+
+### Signs of Dead Docs
+
+- References to removed features
+- Code examples that don't compile
+- Broken links
+- Outdated screenshots
+- Instructions that don't work
+- "TODO: update this" comments
+
+### Deletion Strategy
+
+1. **Default to delete** when uncertain
+2. **Archive important history** in ADRs if needed
+3. **Don't preserve for nostalgia** — that's what git history is for
+
+```markdown
+<!-- Bad: Leaving dead docs -->
+## Legacy Authentication (Deprecated)
+
+> Note: This section is outdated. See new auth docs below.
+
+The old auth system used...
+
+<!-- Good: Delete and move on -->
+## Authentication
+
+Current auth system uses JWT tokens...
+```
+
+## Regular Maintenance
+
+### Quarterly Review Checklist
+
+- [ ] All README quick-start instructions work
+- [ ] Code examples compile and run
+- [ ] Links resolve (use `npx linkinator`)
+- [ ] Screenshots match current UI
+- [ ] API docs match implementation
+- [ ] No TODO/FIXME comments older than 90 days
+
+### Automated Checks
+
+```yaml
+# .github/workflows/docs.yml
+name: Documentation Health
+
+on:
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly
+  push:
+    paths:
+      - 'docs/**'
+      - '*.md'
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx linkinator . --recurse --skip "^(?!http)"
+      
+  check-markdown:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx markdownlint '**/*.md'
+      
+  test-code-examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm run test:docs  # Test code examples compile
+```
+
+## Documentation Ownership
+
+### Every Doc Has an Owner
+
+```markdown
+---
+owner: @payments-team
+last-reviewed: 2024-01-15
+---
+
+# Payment Processing Guide
+```
+
+### Review Triggers
+
+Docs should be reviewed when:
+- Related code changes
+- User reports confusion
+- New team member struggles
+- 90 days since last review
+
+## Preventing Documentation Decay
+
+### Link to Source of Truth
+
+```markdown
+<!-- Bad: Duplicates information that will drift -->
+## Supported Node Versions
+- Node 18
+- Node 20
+- Node 22
+
+<!-- Good: Links to canonical source -->
+## Requirements
+See `engines` field in [package.json](./package.json) for supported versions.
+```
+
+### Generate When Possible
+
+```typescript
+// Generate CLI help from code
+const commands = {
+  build: {
+    description: 'Build the project',
+    options: [
+      { name: '--watch', description: 'Watch for changes' },
+    ],
+  },
+};
+
+// README generated from this object
+```
+
+### Use Versioned References
+
+```markdown
+<!-- Bad: Will break on next release -->
+See the [API docs](https://docs.example.com/api)
+
+<!-- Good: Pinned to version -->
+See the [API docs for v2.x](https://docs.example.com/v2/api)
+```
+
+## Handling Outdated Docs
+
+### Triage Process
+
+```
+┌─────────────────────┐
+│ Is it still needed? │
+└─────────┬───────────┘
+          │
+    ┌─────┴─────┐
+    │           │
+   Yes          No
+    │           │
+    ▼           ▼
+┌───────────┐ ┌────────┐
+│ Update it │ │ Delete │
+└───────────┘ └────────┘
+```
+
+### Update vs. Rewrite
+
+**Update when:**
+- Core information is correct
+- Structure is sound
+- Just needs minor corrections
+
+**Rewrite when:**
+- Fundamental approach changed
+- More than 50% needs changes
+- Structure doesn't fit current reality
+
+## Team Documentation Habits
+
+### Code Review Checklist
+
+Reviewers should check:
+- [ ] Docstrings added/updated for changed functions
+- [ ] README reflects new features
+- [ ] API docs updated for endpoint changes
+- [ ] No commented-out documentation
+- [ ] Examples are tested
+
+### PR Template
+
+```markdown
+## Documentation
+
+- [ ] README updated (if applicable)
+- [ ] API docs updated (if applicable)
+- [ ] Code comments updated
+- [ ] No documentation needed (explain why)
+```
+
+### Definition of Done
+
+A feature is not complete until:
+- Public APIs are documented
+- README reflects the change (if user-facing)
+- Relevant code comments updated
+- Examples work correctly
+
+## Anti-Patterns
+
+### "We'll Document It Later"
+
+```
+Later === Never
+```
+
+Document as you code. If it's too complex to document, it's too complex.
+
+### Documentation-Only PRs
+
+Large documentation PRs are a smell. They indicate docs weren't updated with code.
+
+```markdown
+<!-- Bad: 6 months of accumulated debt -->
+PR: "Update all documentation"
+Files changed: 47
+
+<!-- Good: Incremental updates -->
+PR: "feat: add payment retry logic"
+Files changed: 3 (including docs)
+```
+
+### Separate Doc Repos
+
+Keeping docs in a separate repository:
+- Creates sync issues
+- Removes accountability
+- Makes "update docs with code" impossible
+
+Docs belong with code unless there's a compelling reason otherwise.

package/templates/documentation/.cursorrules/overview.md

@@ -0,0 +1,82 @@
+# Documentation Standards
+
+Guidelines for writing effective technical documentation across all project types.
+
+## Philosophy
+
+> "Say what you mean, simply and directly." — Brian Kernighan
+
+### Core Principles
+
+1. **Minimum Viable Documentation** - A small set of fresh, accurate docs beats a large assembly in various states of disrepair
+2. **Write for Humans First** - Code tells computers what to do; documentation tells humans why
+3. **Radical Simplicity** - Fewer distractions make for better writing and more productive reading
+4. **Better is Better Than Best** - Incremental improvement beats prolonged debate
+
+### The Documentation Spectrum
+
+Documentation exists on a spectrum from terse to detailed:
+
+1. **Meaningful names** - Self-documenting code through good naming
+2. **Inline comments** - Why the code exists, not what it does
+3. **API documentation** - Method/class contracts (JSDoc, docstrings)
+4. **README files** - Orientation for new users
+5. **Guides and tutorials** - How to accomplish specific tasks
+6. **Architecture Decision Records** - Why we chose this approach
+
+## Scope
+
+This ruleset applies to:
+
+- Code comments and docstrings
+- README files
+- API documentation
+- Architecture Decision Records (ADRs)
+- User guides and tutorials
+- Runbooks and operational docs
+
+## When to Document
+
+### Always Document
+
+- Public APIs and interfaces
+- Non-obvious business logic
+- Architectural decisions and tradeoffs
+- Setup and installation procedures
+- Configuration options
+- Breaking changes
+
+### Don't Document
+
+- What the code literally does (the code says that)
+- Obvious behavior that types already express
+- Temporary workarounds without context
+- Implementation details that change frequently
+
+## Documentation as Code
+
+### Same Commit Rule
+
+**Change documentation in the same commit as the code change.** This:
+- Keeps docs fresh
+- Provides context for reviewers
+- Ensures docs and code stay in sync
+
+### Review Checklist
+
+When reviewing code changes, verify:
+- [ ] Docstrings updated for changed functions
+- [ ] README updated if behavior changes
+- [ ] API docs reflect new endpoints/parameters
+- [ ] ADR created for significant decisions
+
+## Definition of Done
+
+Documentation is complete when:
+
+- [ ] New public APIs have docstrings
+- [ ] README reflects current state
+- [ ] Complex logic has explanatory comments
+- [ ] Setup instructions are tested and work
+- [ ] Links are valid and point to correct resources
+- [ ] No outdated information remains