agentic-team-templates 0.3.0

package/templates/documentation/.cursorrules/readme-standards.md

@@ -0,0 +1,306 @@
+# README Standards
+
+Guidelines for writing effective README files that orient users and provide essential information.
+
+## Purpose
+
+A README is the front door to your project. It should:
+- Orient new users immediately
+- Provide essential "getting started" information
+- Link to more detailed documentation
+- Be scannable in under 2 minutes
+
+## File Naming
+
+- **Always name it `README.md`** (case-sensitive)
+- Place in the repository root
+- Each major directory can have its own README
+
+## Required Sections
+
+### Minimum Viable README
+
+Every README must contain:
+
+1. **Project name and one-line description**
+2. **Quick start** (how to install/run)
+3. **Basic usage example**
+
+### Complete README Template
+
+```markdown
+# Project Name
+
+One-line description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+npm install project-name
+\`\`\`
+
+\`\`\`typescript
+import { something } from 'project-name';
+something.doThing();
+\`\`\`
+
+## Features
+
+- Feature one
+- Feature two
+- Feature three
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- PostgreSQL 14+
+
+### Setup
+
+\`\`\`bash
+# Clone the repository
+git clone https://github.com/org/project.git
+cd project
+
+# Install dependencies
+npm install
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your values
+
+# Run migrations
+npm run db:migrate
+
+# Start development server
+npm run dev
+\`\`\`
+
+## Usage
+
+### Basic Example
+
+\`\`\`typescript
+// Show the most common use case first
+\`\`\`
+
+### Advanced Example
+
+\`\`\`typescript
+// Show more complex usage
+\`\`\`
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | `3000` |
+| `DATABASE_URL` | PostgreSQL connection string | Required |
+
+## API Reference
+
+See [API Documentation](./docs/api.md) for full details.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - see [LICENSE](./LICENSE)
+```
+
+## Section Guidelines
+
+### Project Name and Description
+
+```markdown
+# PaymentGateway
+
+A lightweight payment processing library supporting Stripe, PayPal, and Square.
+```
+
+- Use the actual project name
+- One sentence describing what it does
+- Avoid buzzwords and marketing speak
+
+### Quick Start
+
+Show the fastest path to "hello world":
+
+```markdown
+## Quick Start
+
+\`\`\`bash
+npx create-my-app my-project
+cd my-project
+npm start
+\`\`\`
+```
+
+- Maximum 3-5 commands
+- Copy-pasteable commands
+- Should work on first try
+
+### Installation
+
+Be specific about:
+
+```markdown
+## Installation
+
+### Prerequisites
+
+- Node.js 18+ (check with `node --version`)
+- Docker and Docker Compose
+- A Stripe account with API keys
+
+### Steps
+
+1. Clone the repository
+2. Install dependencies
+3. Configure environment
+4. Run setup commands
+```
+
+### Usage Examples
+
+```markdown
+## Usage
+
+### Simple Case
+
+Always show the simplest use case first:
+
+\`\`\`typescript
+const client = new Client();
+await client.send('Hello');
+\`\`\`
+
+### With Options
+
+Then progressively more complex:
+
+\`\`\`typescript
+const client = new Client({
+  timeout: 5000,
+  retries: 3,
+});
+\`\`\`
+```
+
+### Configuration
+
+Use tables for configuration options:
+
+```markdown
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `retries` | `number` | `0` | Number of retry attempts |
+| `debug` | `boolean` | `false` | Enable debug logging |
+```
+
+## Directory READMEs
+
+For READMEs inside project directories:
+
+```markdown
+# /src/components/
+
+React components for the application UI.
+
+## Structure
+
+- `ui/` - Primitive components (Button, Input, Card)
+- `features/` - Feature-specific components
+- `layouts/` - Page layout components
+
+## Conventions
+
+- One component per file
+- Use TypeScript for all components
+- Include tests in `__tests__/` subdirectory
+
+## Key Files
+
+- `index.ts` - Public exports
+- `theme.ts` - Design tokens
+```
+
+## Anti-Patterns
+
+### Stale Information
+
+```markdown
+<!-- Bad: Will become outdated -->
+## Supported Node Versions
+- Node 14
+- Node 16
+
+<!-- Good: Link to source of truth -->
+## Requirements
+See `engines` field in [package.json](./package.json)
+```
+
+### Wall of Text
+
+```markdown
+<!-- Bad: No one will read this -->
+This project was started in 2019 when we realized that the existing
+solutions for payment processing were inadequate for our needs. After
+extensive research and development spanning several months...
+
+<!-- Good: Get to the point -->
+Payment processing library supporting Stripe, PayPal, and Square.
+```
+
+### Missing Examples
+
+```markdown
+<!-- Bad: No examples -->
+## Installation
+Install with npm.
+
+<!-- Good: Copy-pasteable -->
+## Installation
+\`\`\`bash
+npm install payment-gateway
+\`\`\`
+```
+
+### Broken Links
+
+```markdown
+<!-- Bad: Links rot -->
+See our [wiki](http://internal-wiki.company.com/project) for details.
+
+<!-- Good: Link to files in repo -->
+See [ARCHITECTURE.md](./docs/ARCHITECTURE.md) for details.
+```
+
+## Badges (Optional)
+
+If using badges, keep them meaningful:
+
+```markdown
+[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](...)
+[![npm version](https://badge.fury.io/js/package.svg)](...)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](...)
+```
+
+- CI status - Shows project health
+- Version - Shows current release
+- License - Shows usage rights
+- Avoid decorative/vanity badges
+
+## Maintenance
+
+- Update README when behavior changes
+- Test all code examples periodically
+- Verify links work
+- Remove outdated sections

package/templates/documentation/CLAUDE.md

@@ -0,0 +1,120 @@
+# Documentation Development Guide
+
+Guidelines for writing and maintaining technical documentation.
+
+## Philosophy
+
+> "Say what you mean, simply and directly." — Brian Kernighan
+
+Documentation exists to help humans understand code. Write for the busy engineer who just wants to get back to coding.
+
+## Core Principles
+
+### 1. Minimum Viable Documentation
+
+A small set of fresh, accurate docs is better than a large assembly in various states of disrepair. Write only what's needed, keep it current, delete the rest.
+
+### 2. Write for Humans First
+
+Code tells computers what to do. Documentation tells humans *why*.
+
+### 3. Same-Commit Rule
+
+Documentation changes belong in the same commit as code changes. This keeps docs fresh and ensures they never drift from reality.
+
+### 4. Delete Dead Docs
+
+Stale documentation is worse than no documentation. It misinforms, slows down, and erodes trust. When in doubt, delete.
+
+## The Documentation Hierarchy
+
+From least to most formal:
+
+1. **Self-documenting code** — Good naming eliminates most comments
+2. **Inline comments** — Explain *why*, not *what*
+3. **API documentation** — Function/class contracts (JSDoc, docstrings)
+4. **README files** — Project orientation
+5. **Guides and tutorials** — How to accomplish tasks
+6. **ADRs** — Why we made architectural decisions
+
+## Quick Reference
+
+### When to Document
+
+**Always document:**
+- Public APIs and interfaces
+- Non-obvious business logic
+- Architectural decisions (ADRs)
+- Setup and installation
+- Configuration options
+
+**Skip documentation for:**
+- What the code literally does
+- Obvious behavior types express
+- Implementation details that change often
+
+### Comment Guidelines
+
+```typescript
+// Good: Explains WHY
+// Retry with backoff because payment API is flaky during peak hours
+await retryWithBackoff(processPayment, 3);
+
+// Bad: Explains WHAT (code already shows this)
+// Increment counter by 1
+counter++;
+```
+
+### README Essentials
+
+Every README needs:
+1. Project name + one-line description
+2. Quick start (install + basic usage)
+3. Example code
+
+### ADR Format
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted | Proposed | Deprecated | Superseded
+
+## Context
+What's the situation? What problem are we solving?
+
+## Decision
+What did we decide?
+
+## Consequences
+What happens as a result? (Good, bad, neutral)
+```
+
+## Definition of Done
+
+Documentation is complete when:
+
+- [ ] New public APIs have docstrings
+- [ ] README reflects current state
+- [ ] Complex logic has explanatory comments
+- [ ] Setup instructions tested and working
+- [ ] No outdated information remains
+- [ ] All links are valid
+
+## Anti-Patterns to Avoid
+
+- **"We'll document it later"** — Later means never
+- **Commented-out code** — Use version control
+- **Comments that lie** — Update or delete
+- **Noise comments** — `// increment counter` adds nothing
+- **Separate doc repos** — Keep docs with code
+
+## Review Checklist
+
+When reviewing code:
+
+- [ ] Docstrings added/updated for changed functions?
+- [ ] README updated if behavior changes?
+- [ ] API docs reflect endpoint changes?
+- [ ] Code examples still work?
+- [ ] No dead documentation created?