agentic-team-templates 0.3.0

package/templates/documentation/.cursorrules/adr.md

@@ -0,0 +1,277 @@
+# Architecture Decision Records (ADRs)
+
+Guidelines for documenting architectural decisions and their rationale.
+
+## Purpose
+
+ADRs capture **architecturally significant decisions** — choices that affect:
+- System structure and organization
+- Non-functional characteristics (performance, security, scalability)
+- External dependencies and integrations
+- Development and deployment approaches
+- Standards and conventions
+
+## Why ADRs Matter
+
+- **Future developers** understand why decisions were made
+- **Prevents rehashing** the same debates
+- **Documents tradeoffs** that aren't obvious from code
+- **Creates accountability** for decisions
+- **Enables learning** from past choices
+
+## ADR Format (MADR Template)
+
+Use the Markdown Architectural Decision Records (MADR) format:
+
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+
+Accepted
+
+## Context
+
+We need to choose a primary database for storing user data, transactions,
+and application state. Key requirements:
+
+- ACID compliance for financial transactions
+- Support for complex queries and joins
+- Horizontal read scaling
+- Strong ecosystem and tooling
+
+Currently evaluating:
+- PostgreSQL
+- MySQL
+- MongoDB
+
+## Decision
+
+We will use **PostgreSQL** as our primary database.
+
+## Rationale
+
+### Considered Options
+
+#### PostgreSQL
+- **Pros**: ACID compliant, excellent query planner, JSONB for flexible schemas,
+  strong extension ecosystem (PostGIS, pg_tron), read replicas
+- **Cons**: Vertical scaling limits, more complex than MySQL
+
+#### MySQL
+- **Pros**: Widely adopted, good performance, simpler operations
+- **Cons**: Weaker JSON support, fewer advanced features
+
+#### MongoDB
+- **Pros**: Flexible schema, horizontal scaling, document model
+- **Cons**: Not ACID by default, eventual consistency concerns for financial data
+
+### Decision Drivers
+
+1. **ACID compliance is non-negotiable** for financial transactions
+2. **JSONB** allows flexible metadata without sacrificing query performance
+3. **Team expertise** — 4 of 5 engineers have PostgreSQL experience
+4. **Ecosystem** — Better tooling for our stack (Prisma, TypeORM)
+
+## Consequences
+
+### Positive
+- Strong consistency guarantees
+- Can use advanced features (CTEs, window functions)
+- Familiar to most team members
+
+### Negative
+- Need to plan for vertical scaling limits
+- More operational complexity than managed MongoDB
+- Schema migrations required for structural changes
+
+### Neutral
+- Will use read replicas for scaling reads
+- Need to establish connection pooling strategy
+
+## Related Decisions
+
+- ADR-002: Use Prisma as ORM
+- ADR-005: Database connection pooling strategy
+```
+
+## Minimal ADR Format
+
+For simpler decisions, use the Nygard format:
+
+```markdown
+# ADR-003: Use TypeScript Strict Mode
+
+## Status
+
+Accepted
+
+## Context
+
+We need to decide on TypeScript configuration for the project.
+Strict mode catches more errors but requires more explicit typing.
+
+## Decision
+
+Enable TypeScript strict mode for all new code.
+
+## Consequences
+
+- Catches null/undefined errors at compile time
+- Requires explicit return types on functions
+- May slow initial development slightly
+- Significantly reduces runtime errors
+```
+
+## Y-Statement Format (Ultra-Minimal)
+
+For quick documentation of smaller decisions:
+
+```markdown
+# ADR-004: JWT Token Storage
+
+In the context of **user authentication**,
+facing **the need to persist auth tokens across page refreshes**,
+we decided for **httpOnly cookies**
+to achieve **XSS protection**,
+accepting **CSRF token overhead**.
+```
+
+## File Organization
+
+### Directory Structure
+
+```
+docs/
+└── adr/
+    ├── README.md           # Index of all ADRs
+    ├── adr-001-database.md
+    ├── adr-002-orm.md
+    ├── adr-003-typescript.md
+    └── templates/
+        ├── madr.md         # Full template
+        └── minimal.md      # Minimal template
+```
+
+### Naming Convention
+
+```
+adr-NNN-short-title.md
+
+Examples:
+- adr-001-use-postgresql.md
+- adr-002-authentication-strategy.md
+- adr-003-api-versioning.md
+```
+
+### Index File
+
+```markdown
+# Architecture Decision Records
+
+| ADR | Title | Status | Date |
+|-----|-------|--------|------|
+| [001](./adr-001-database.md) | Use PostgreSQL | Accepted | 2024-01-15 |
+| [002](./adr-002-orm.md) | Use Prisma ORM | Accepted | 2024-01-16 |
+| [003](./adr-003-auth.md) | JWT Authentication | Superseded by 007 | 2024-01-20 |
+```
+
+## ADR Lifecycle
+
+### Statuses
+
+| Status | Meaning |
+|--------|---------|
+| **Proposed** | Under discussion, not yet decided |
+| **Accepted** | Decision made, being implemented |
+| **Deprecated** | Still valid but no longer preferred |
+| **Superseded** | Replaced by a newer ADR |
+| **Rejected** | Considered but not accepted |
+
+### Updating ADRs
+
+```markdown
+## Status
+
+Superseded by [ADR-007](./adr-007-session-auth.md)
+
+## Supersession Note
+
+Added 2024-03-15: After 2 months in production, JWT refresh token
+management proved more complex than anticipated. Moving to
+session-based auth. See ADR-007 for details.
+```
+
+**Never delete ADRs** — they document the decision history, including mistakes.
+
+## When to Write an ADR
+
+### Write an ADR When
+
+- Choosing between multiple valid approaches
+- Making decisions with long-term consequences
+- Introducing new patterns or technologies
+- Deviating from established conventions
+- Multiple team members have different opinions
+
+### Skip the ADR When
+
+- Following established patterns
+- Making easily reversible choices
+- Standard library/framework usage
+- Implementation details (not architecture)
+
+## Decision Criteria to Document
+
+Always capture:
+
+1. **Requirements/Constraints** — What must the solution do?
+2. **Options Considered** — What alternatives were evaluated?
+3. **Decision Drivers** — What factors influenced the choice?
+4. **Tradeoffs** — What are we giving up?
+5. **Consequences** — What changes as a result?
+
+## Anti-Patterns
+
+### Documenting After the Fact
+
+```markdown
+<!-- Bad: Written 6 months later -->
+## Context
+We needed a database. We picked PostgreSQL.
+
+<!-- Good: Written during decision -->
+## Context
+Evaluating databases for user data storage. Requirements:
+- ACID for transactions
+- JSON support for flexible metadata
+- Team has PostgreSQL experience
+```
+
+### Missing Alternatives
+
+```markdown
+<!-- Bad: No alternatives -->
+## Decision
+Use React.
+
+<!-- Good: Shows the analysis -->
+## Considered Options
+1. React — Large ecosystem, team experience
+2. Vue — Simpler learning curve
+3. Svelte — Better performance, smaller ecosystem
+```
+
+### Vague Consequences
+
+```markdown
+<!-- Bad: Not actionable -->
+## Consequences
+This will have some impact on performance.
+
+<!-- Good: Specific and measurable -->
+## Consequences
+- Initial page load increases ~50KB (React bundle)
+- Need to implement code splitting for routes
+- Requires React testing library for component tests
+```

package/templates/documentation/.cursorrules/api-documentation.md

@@ -0,0 +1,411 @@
+# API Documentation
+
+Guidelines for documenting APIs, including REST endpoints, GraphQL schemas, and library interfaces.
+
+## Design-First Approach
+
+**Write the API specification before implementation.** This:
+- Catches design issues early
+- Enables parallel frontend/backend development
+- Creates documentation as a natural byproduct
+- Prevents implementation details from leaking into contracts
+
+## OpenAPI/Swagger Specification
+
+### Basic Structure
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Payment API
+  version: 1.0.0
+  description: |
+    API for processing payments and managing transactions.
+    
+    ## Authentication
+    All endpoints require Bearer token authentication.
+    
+    ## Rate Limits
+    - Standard: 100 requests/minute
+    - Burst: 200 requests/minute
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://api.staging.example.com/v1
+    description: Staging
+
+paths:
+  /payments:
+    post:
+      summary: Create a payment
+      description: |
+        Initiates a new payment transaction.
+        
+        The payment will be processed asynchronously. Use the
+        returned `payment_id` to check status via GET /payments/{id}.
+      operationId: createPayment
+      tags:
+        - Payments
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreatePaymentRequest'
+            examples:
+              credit_card:
+                summary: Credit card payment
+                value:
+                  amount: 1000
+                  currency: USD
+                  method: credit_card
+                  card_token: tok_visa_4242
+      responses:
+        '201':
+          description: Payment created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+```
+
+### Schema Documentation
+
+```yaml
+components:
+  schemas:
+    Payment:
+      type: object
+      description: Represents a payment transaction
+      required:
+        - id
+        - amount
+        - currency
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique payment identifier
+          example: "pay_1234567890"
+        amount:
+          type: integer
+          description: Amount in smallest currency unit (cents for USD)
+          minimum: 1
+          example: 1000
+        currency:
+          type: string
+          description: ISO 4217 currency code
+          enum: [USD, EUR, GBP]
+          example: USD
+        status:
+          type: string
+          description: Current payment status
+          enum: [pending, processing, completed, failed]
+          example: completed
+        created_at:
+          type: string
+          format: date-time
+          description: When the payment was created
+          example: "2024-01-15T10:30:00Z"
+```
+
+## Endpoint Documentation Requirements
+
+### Every Endpoint Must Have
+
+1. **Summary** - One-line description
+2. **Description** - Detailed behavior explanation
+3. **Parameters** - All path, query, header parameters
+4. **Request body** - Schema with examples
+5. **Responses** - All possible response codes
+6. **Authentication** - Required auth method
+7. **Examples** - Real-world usage examples
+
+### Response Documentation
+
+Document all response codes:
+
+```yaml
+responses:
+  '200':
+    description: Success
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/User'
+  '400':
+    description: |
+      Bad Request. Possible reasons:
+      - Missing required field
+      - Invalid field format
+      - Business rule violation
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/Error'
+        examples:
+          missing_field:
+            summary: Missing required field
+            value:
+              error: validation_error
+              message: "Field 'email' is required"
+              field: email
+          invalid_format:
+            summary: Invalid format
+            value:
+              error: validation_error
+              message: "Invalid email format"
+              field: email
+  '401':
+    description: Authentication required or token invalid
+  '403':
+    description: Authenticated but not authorized for this resource
+  '404':
+    description: Resource not found
+  '429':
+    description: Rate limit exceeded
+  '500':
+    description: Internal server error
+```
+
+## GraphQL Documentation
+
+### Schema Documentation
+
+```graphql
+"""
+A user account in the system.
+
+Users can have multiple roles and belong to organizations.
+"""
+type User {
+  """Unique identifier"""
+  id: ID!
+  
+  """User's email address (unique, used for login)"""
+  email: String!
+  
+  """Display name shown in the UI"""
+  displayName: String
+  
+  """
+  User's current status.
+  
+  ACTIVE users can log in and perform actions.
+  SUSPENDED users cannot log in until reactivated.
+  """
+  status: UserStatus!
+  
+  """Organizations this user belongs to"""
+  organizations: [Organization!]!
+  
+  """When the account was created"""
+  createdAt: DateTime!
+}
+
+"""
+Possible states for a user account
+"""
+enum UserStatus {
+  """User can log in and use the system"""
+  ACTIVE
+  
+  """User is blocked from logging in"""
+  SUSPENDED
+  
+  """User has been soft-deleted"""
+  DELETED
+}
+```
+
+### Query/Mutation Documentation
+
+```graphql
+type Query {
+  """
+  Retrieve a user by ID.
+  
+  Returns null if user doesn't exist or caller lacks permission.
+  """
+  user(id: ID!): User
+  
+  """
+  Search users with optional filters.
+  
+  Results are paginated. Use `after` cursor for subsequent pages.
+  Maximum 100 results per page.
+  """
+  users(
+    """Filter by organization membership"""
+    organizationId: ID
+    
+    """Filter by status"""
+    status: UserStatus
+    
+    """Number of results (max 100)"""
+    first: Int = 20
+    
+    """Cursor for pagination"""
+    after: String
+  ): UserConnection!
+}
+
+type Mutation {
+  """
+  Create a new user account.
+  
+  Sends a verification email to the provided address.
+  User cannot log in until email is verified.
+  
+  Requires ADMIN role.
+  """
+  createUser(input: CreateUserInput!): CreateUserPayload!
+}
+```
+
+## Library/SDK Documentation
+
+### Function Documentation
+
+```typescript
+/**
+ * Payment processing client.
+ * 
+ * @example Basic usage
+ * ```ts
+ * const client = new PaymentClient({ apiKey: 'sk_test_...' });
+ * const payment = await client.createPayment({
+ *   amount: 1000,
+ *   currency: 'usd',
+ * });
+ * ```
+ * 
+ * @example With error handling
+ * ```ts
+ * try {
+ *   const payment = await client.createPayment(params);
+ * } catch (error) {
+ *   if (error instanceof CardDeclinedError) {
+ *     // Handle declined card
+ *   }
+ * }
+ * ```
+ */
+class PaymentClient {
+  /**
+   * Creates a new payment client instance.
+   * 
+   * @param options - Configuration options
+   * @param options.apiKey - Your API key (starts with sk_)
+   * @param options.timeout - Request timeout in ms (default: 30000)
+   * @param options.maxRetries - Max retry attempts (default: 3)
+   */
+  constructor(options: PaymentClientOptions);
+
+  /**
+   * Creates a new payment.
+   * 
+   * @param params - Payment parameters
+   * @returns The created payment object
+   * @throws {CardDeclinedError} Card was declined by issuer
+   * @throws {InvalidParameterError} Invalid parameter provided
+   * @throws {RateLimitError} Rate limit exceeded
+   * 
+   * @see {@link https://docs.example.com/payments | Payment Guide}
+   */
+  async createPayment(params: CreatePaymentParams): Promise<Payment>;
+}
+```
+
+## Documentation Anti-Patterns
+
+### Missing Error Documentation
+
+```yaml
+# Bad: Only documents success
+responses:
+  '200':
+    description: Success
+
+# Good: Documents all outcomes
+responses:
+  '200':
+    description: Success
+  '400':
+    description: Invalid request parameters
+  '401':
+    description: Missing or invalid authentication
+  '404':
+    description: Resource not found
+  '500':
+    description: Internal server error
+```
+
+### Vague Descriptions
+
+```yaml
+# Bad: Doesn't help the developer
+description: Gets the thing
+
+# Good: Specific and actionable
+description: |
+  Retrieves a user by their unique ID.
+  
+  Returns the full user profile including email, display name,
+  and organization memberships. Requires read:users scope.
+```
+
+### No Examples
+
+```yaml
+# Bad: No examples
+schema:
+  type: object
+  properties:
+    status:
+      type: string
+
+# Good: Clear examples
+schema:
+  type: object
+  properties:
+    status:
+      type: string
+      enum: [pending, active, cancelled]
+      example: active
+  example:
+    status: active
+    created_at: "2024-01-15T10:30:00Z"
+```
+
+## Keeping API Docs in Sync
+
+### Single Source of Truth
+
+- Generate docs from code annotations when possible
+- Use OpenAPI spec as source, generate code from it
+- Never maintain parallel documentation
+
+### CI Integration
+
+```yaml
+# .github/workflows/api-docs.yml
+- name: Validate OpenAPI spec
+  run: npx @redocly/cli lint openapi.yaml
+
+- name: Check for breaking changes
+  run: npx @redocly/cli diff openapi.yaml main:openapi.yaml
+```
+
+### Versioning
+
+- Document version in API path (`/v1/`, `/v2/`)
+- Maintain docs for all supported versions
+- Clearly mark deprecated endpoints
+- Include migration guides for breaking changes