@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/documentation-templates/POWER.md

@@ -2,196 +2,227 @@
 ---
 inclusion: manual
 name: documentation-templates
-description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
-allowed-tools: Read, Glob, Grep
+description: Create API documentation, architecture decision records, runbooks, onboarding guides, and technical writing using proven templates and standards.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Documentation Templates
 
-> Templates and structure guidelines for common documentation types.
+## Purpose
 
----
+Provide templates and guidance for technical documentation: API docs, architecture decision records (ADRs), runbooks, README files, onboarding guides, and inline code documentation.
+
+## When to Use
+
+- Writing or improving a project README
+- Creating API documentation
+- Recording architecture decisions (ADRs)
+- Building operational runbooks
+- Writing onboarding guides for new team members
+- Documenting complex systems or workflows
 
-## 1. README Structure
+## Instructions
 
-### Essential Sections (Priority Order)
+### Step 1 — Choose the Right Template
 
-| Section | Purpose |
-|---------|---------|
-| **Title + One-liner** | What is this? |
-| **Quick Start** | Running in <5 min |
-| **Features** | What can I do? |
-| **Configuration** | How to customize |
-| **API Reference** | Link to detailed docs |
-| **Contributing** | How to help |
-| **License** | Legal |
+| Document Type    | Audience                          | When                       |
+| ---------------- | --------------------------------- | -------------------------- |
+| README           | New contributors, users           | Every project              |
+| API docs         | API consumers (internal/external) | Every API                  |
+| ADR              | Future developers                 | Every significant decision |
+| Runbook          | On-call engineers                 | Every production system    |
+| Onboarding guide | New team members                  | Every team                 |
+| RFC / Design doc | Reviewers before implementation   | Complex features           |
 
-### README Template
+### Step 2 — README Template
 
 ```markdown
 # Project Name
 
-Brief one-line description.
+One-line description of what this project does.
 
 ## Quick Start
 
-[Minimum steps to run]
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
 
 ## Features
 
-- Feature 1
-- Feature 2
+- Feature 1: brief description
+- Feature 2: brief description
 
-## Configuration
+## Architecture
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| PORT | Server port | 3000 |
+Brief overview or link to architecture docs.
 
-## Documentation
+## Development
 
-- [API Reference](./docs/api.md)
-- [Architecture](./docs/architecture.md)
+### Prerequisites
 
-## License
+- Node.js >= 20
+- PostgreSQL >= 15
 
-MIT
-```
+### Setup
 
----
+Step-by-step local development setup.
 
-## 2. API Documentation Structure
+### Testing
 
-### Per-Endpoint Template
+How to run tests.
 
-```markdown
-## GET /users/:id
+### Deployment
+
+How to deploy (or link to deployment docs).
 
-Get a user by ID.
+## Contributing
 
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| id | string | Yes | User ID |
+Link to CONTRIBUTING.md or brief guidelines.
 
-**Response:**
-- 200: User object
-- 404: User not found
+## License
 
-**Example:**
-[Request and response example]
+MIT (or appropriate license)
 ```
 
----
+### Step 3 — Architecture Decision Record (ADR)
 
-## 3. Code Comment Guidelines
-
-### JSDoc/TSDoc Template
-
-```typescript
-/**
- * Brief description of what the function does.
- * 
- * @param paramName - Description of parameter
- * @returns Description of return value
- * @throws ErrorType - When this error occurs
- * 
- * @example
- * const result = functionName(input);
- */
-```
+```markdown
+# ADR-001: Use PostgreSQL for primary datastore
 
-### When to Comment
+## Status
 
-| ✅ Comment | ❌ Don't Comment |
-|-----------|-----------------|
-| Why (business logic) | What (obvious) |
-| Complex algorithms | Every line |
-| Non-obvious behavior | Self-explanatory code |
-| API contracts | Implementation details |
+Accepted | Proposed | Deprecated | Superseded by ADR-xxx
 
----
+## Context
 
-## 4. Changelog Template (Keep a Changelog)
+What is the problem? What constraints exist?
 
-```markdown
-# Changelog
-
-## [Unreleased]
-### Added
-- New feature
-
-## [1.0.0] - 2025-01-01
-### Added
-- Initial release
-### Changed
-- Updated dependency
-### Fixed
-- Bug fix
+## Decision
+
+What did we decide and why?
+
+## Consequences
+
+What are the trade-offs? What becomes easier/harder?
+
+## Alternatives Considered
+
+What else did we evaluate and why did we reject it?
 ```
 
----
+**Rules**:
 
-## 5. Architecture Decision Record (ADR)
+- ADRs are immutable — supersede, don't edit
+- Number sequentially (ADR-001, ADR-002)
+- Title should be a decision, not a question
+- Keep it short (1-2 pages max)
+
+### Step 4 — Runbook Template
 
 ```markdown
-# ADR-001: [Title]
+# Runbook: [System/Alert Name]
 
-## Status
-Accepted / Deprecated / Superseded
+## Overview
 
-## Context
-Why are we making this decision?
+What this system does and why it matters.
 
-## Decision
-What did we decide?
+## Alerts
 
-## Consequences
-What are the trade-offs?
-```
+| Alert           | Severity | Meaning                   |
+| --------------- | -------- | ------------------------- |
+| high_error_rate | Critical | Error rate > 5% for 5 min |
+| high_latency    | Warning  | p95 > 2s for 10 min       |
 
----
+## Diagnosis Steps
 
-## 6. AI-Friendly Documentation (2025)
+1. Check dashboards: [link]
+2. Check logs: `kubectl logs -l app=service-name --tail=100`
+3. Check dependencies: [list of upstream services]
 
-### llms.txt Template
+## Common Fixes
 
-For AI crawlers and agents:
+### High error rate
 
-```markdown
-# Project Name
-> One-line objective.
+1. Check recent deployments: `git log --since="2 hours ago"`
+2. If recent deploy caused it: rollback with `./deploy rollback`
+3. If not deployment-related: check database connections
+
+### High latency
+
+1. Check database slow query log
+2. Check connection pool saturation
+3. Scale up if under heavy load: `kubectl scale --replicas=5`
 
-## Core Files
-- [src/index.ts]: Main entry
-- [src/api/]: API routes
-- [docs/]: Documentation
+## Escalation
 
-## Key Concepts
-- Concept 1: Brief explanation
-- Concept 2: Brief explanation
+- L1: On-call engineer (PagerDuty)
+- L2: Service owner (@team-backend)
+- L3: Infrastructure team (@team-infra)
 ```
 
-### MCP-Ready Documentation
+### Step 5 — API Documentation
 
-For RAG indexing:
-- Clear H1-H3 hierarchy
-- JSON/YAML examples for data structures
-- Mermaid diagrams for flows
-- Self-contained sections
+**Document every endpoint with**:
 
----
+```markdown
+## POST /api/users
+
+Create a new user account.
+
+### Request
+
+**Headers**:
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | application/json |
+
+**Body**:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| email | string | Yes | Valid email address |
+| name | string | Yes | Full name (2-100 chars) |
+| role | string | No | "user" (default) or "admin" |
+
+**Example**:
+\`\`\`json
+{ "email": "alice@example.com", "name": "Alice Smith" }
+\`\`\`
+
+### Response
+
+**201 Created**:
+\`\`\`json
+{ "id": "usr_abc123", "email": "alice@example.com", "name": "Alice Smith", "role": "user" }
+\`\`\`
+
+**400 Bad Request**:
+\`\`\`json
+{ "error": { "code": "VALIDATION_ERROR", "message": "Email already registered" } }
+\`\`\`
+
+**401 Unauthorized**:
+\`\`\`json
+{ "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired token" } }
+\`\`\`
+```
 
-## 7. Structure Principles
+## Output Format
 
-| Principle | Why |
-|-----------|-----|
-| **Scannable** | Headers, lists, tables |
-| **Examples first** | Show, don't just tell |
-| **Progressive detail** | Simple → Complex |
-| **Up to date** | Outdated = misleading |
+Use the appropriate template from above, filled in with project-specific details. Always include examples with realistic (not lorem ipsum) content.
 
----
+## Examples
+
+**User**: "Write a README for our API project"
+
+**Response approach**: Use the README template. Fill in actual project details. Include quick start with real commands. Link to API docs. Add architecture overview if the system has multiple components.
+
+**User**: "We need to document why we chose MongoDB over PostgreSQL"
 
-> **Remember:** Templates are starting points. Adapt to your project's needs.
+**Response approach**: Use the ADR template. Document the context (data model flexibility needs), decision (MongoDB for document storage), consequences (eventual consistency trade-off), and alternatives considered (PostgreSQL with JSONB).
 ````