agent-skill-kit 3.9.135

package/.agent/skills/doc-templates/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: doc-templates
+description: >-
+  Documentation templates: README, API docs, Mermaid diagrams, changelogs, and code comments.
+  Use when creating documentation, generating README files, or editing Mermaid diagrams.
+  NOT for marketing copy (use copywriting) or code comments style (use code-craft).
+category: documentation
+triggers: ["template", "README", "documentation", "API docs", "changelog", "ADR", "mermaid", "diagram", "flowchart", "preview", "markdown viewer", "view plans", "kanban", "dashboard"]
+coordinates_with: ["project-planner", "code-craft", "system-design"]
+success_metrics: ["100% templates follow required sections", "100% diagrams render correctly"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Doc Templates — Documentation, Diagrams & Preview
+
+> Fixed templates per document type. Mermaid diagrams. Markdown preview. Plan dashboards.
+
+---
+
+## Prerequisites
+
+**Required:** Node.js 18+ (for diagram editor and preview server scripts).
+
+---
+
+## When to Use
+
+| Document Type | Template | Required Sections |
+|--------------|----------|-------------------|
+| New project README | README template | 6 sections |
+| API endpoint docs | API doc template | Method, path, params, response |
+| Architecture decisions | ADR template | Status, Context, Decision, Consequences |
+| Release notes | Changelog template | Version, date, changes |
+| AI agent context | llms.txt template | Project summary, structure |
+| Mermaid diagrams | Diagram editor | 9 types supported |
+| Documentation preview | Preview server | Markdown rendering |
+| Plan progress | Plan dashboard | Phase tracking |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Template structure (5 document types) | Content writing |
+| Section order and requirements | Auto-documentation (→ /chronicle) |
+| Comment guidelines (why vs what) | Project structure (→ project-planner) |
+| AI-friendly doc format (llms.txt) | Code quality (→ code-craft) |
+| Mermaid diagram editing (9 types) | Architecture decisions (→ system-design) |
+| Markdown preview server | File system permissions |
+| Plan dashboard server | Plan creation (→ project-planner) |
+
+**Hybrid skill:** Templates are pure decision; diagram/preview are automation (HTTP servers).
+
+---
+
+## README Template (6 Required Sections)
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+
+## License
+
+MIT
+```
+
+---
+
+## API Endpoint Template
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:** 200: User object, 404: Not found
+```
+
+---
+
+## ADR Template
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## Comment Guidelines
+
+| ✅ Comment | ❌ Don't Comment |
+|-----------|--------------------|
+| Why (business logic) | What (obvious code) |
+| Complex algorithms | Every line |
+| API contracts | Implementation details |
+
+---
+
+## Mermaid Diagram Editor (Absorbed from mermaid-editor)
+
+### Diagram Types (9 — Fixed)
+
+| # | Type | Keyword |
+|---|------|---------|
+| 1 | Flowchart | `flowchart LR` |
+| 2 | Sequence | `sequenceDiagram` |
+| 3 | Class | `classDiagram` |
+| 4 | State | `stateDiagram-v2` |
+| 5 | ER | `erDiagram` |
+| 6 | Gantt | `gantt` |
+| 7 | Pie | `pie` |
+| 8 | Mindmap | `mindmap` |
+| 9 | Timeline | `timeline` |
+
+### Editor Server
+
+```bash
+# Open editor (empty)
+node .agent/skills/doc-templates/scripts/editor-server.ts --open
+
+# Edit existing file
+node .agent/skills/doc-templates/scripts/editor-server.ts --file diagram.mmd --open
+
+# Stop server
+node .agent/skills/doc-templates/scripts/editor-server.ts --stop
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--file <path>` | — | Open .mmd file |
+| `--port <n>` | 3457 | Server port |
+| `--open` | false | Auto-open browser |
+| `--stop` | — | Stop all servers |
+
+---
+
+## Markdown Preview Server (Absorbed from markdown-novel-viewer)
+
+```bash
+# View a file
+node .agent/skills/doc-templates/scripts/markdown-server.ts --file ./README.md --open
+
+# Browse a directory
+node .agent/skills/doc-templates/scripts/markdown-server.ts --dir ./docs --open
+
+# Stop all servers
+node .agent/skills/doc-templates/scripts/markdown-server.ts --stop
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--file <path>` | — | Markdown file |
+| `--dir <path>` | — | Directory to browse |
+| `--port <n>` | 3456 | Server port (3456-3500) |
+| `--open` | false | Auto-open browser |
+| `--stop` | — | Stop all servers |
+
+**Theme:** Libre Baskerville (headings), Inter (body), JetBrains Mono (code). Light/dark toggle.
+
+---
+
+## Plan Dashboard (Absorbed from plans-kanban)
+
+Visual dashboard for plan directories with progress tracking and phase status indicators.
+
+```bash
+node .agent/skills/doc-templates/scripts/kanban-server.ts --dir ./docs/plans --open
+```
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_REFERENCE_NOT_FOUND` | No | Reference file missing |
+| `ERR_PORT_UNAVAILABLE` | Yes | Port in use (editor/preview) |
+| `ERR_FILE_NOT_FOUND` | Yes | File not found |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Skip Quick Start in README | Always include Quick Start |
+| Undocumented API parameters | Document all params with types |
+| ADR without Consequences | Always include trade-offs |
+| Comment what code does | Comment why code exists |
+| No changelog | Maintain structured changelog |
+| Leave servers orphaned | Use --stop to clean up |
+| Assume port is free | Check or use --port |
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [doc.md](rules/doc.md) | Full templates and examples | Detailed template reference |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+| [editor-server.ts](scripts/editor-server.ts) | Mermaid editor server | Diagram implementation |
+| [markdown-server.ts](scripts/markdown-server.ts) | Preview server | Preview implementation |
+| [diagram-reference.md](../mermaid-editor/rules/diagram-reference.md) | 9 diagram types syntax | Writing diagrams |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `/chronicle` | Workflow | Auto-documentation generation |
+| `project-planner` | Skill | Project structure planning |
+| `code-craft` | Skill | Code quality and comments |
+| `system-design` | Skill | Architecture diagrams |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/doc-templates/rules/_sections.md

@@ -0,0 +1,20 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. General (general)
+
+**Impact:** LOW  
+**Description:** General patterns and best practices.
+
+## 2. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/doc-templates/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/doc-templates/rules/doc.md

@@ -0,0 +1,355 @@
+---
+name: doc-templates-reference
+description: Full templates and examples for README, API docs, ADR, changelog, llms.txt, and comment guidelines
+title: "Doc Templates - Full Reference"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: doc
+---
+
+# Doc Templates — Full Reference
+
+> Complete templates with examples. Fill in content, not structure.
+
+---
+
+## 1. README Template (6 Required Sections)
+
+Every README must contain these 6 sections in this order:
+
+```markdown
+# Project Name
+
+Brief one-line description of what this project does.
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/org/project.git
+cd project
+npm install
+
+# Configure
+cp .env.example .env
+
+# Run
+npm run dev
+```
+
+## Features
+
+- **Feature 1** — Brief description
+- **Feature 2** — Brief description
+- **Feature 3** — Brief description
+
+## Configuration
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `PORT` | Server port | `3000` | No |
+| `DATABASE_URL` | PostgreSQL connection string | — | Yes |
+| `API_KEY` | External API key | — | Yes |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture Decisions](./docs/adr/)
+- [Contributing Guide](./CONTRIBUTING.md)
+
+## License
+
+MIT © 2025 Your Organization
+```
+
+### README Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|------|
+| Skip Quick Start | Always include runnable steps |
+| List features without description | One line per feature explaining value |
+| Hardcode config values | Use env variables with table |
+| Link to non-existent docs | Verify all links before commit |
+
+---
+
+## 2. API Endpoint Template
+
+Every endpoint must document: method, path, parameters, response codes.
+
+### Single Endpoint
+
+```markdown
+## GET /api/users/:id
+
+Get a user by ID.
+
+**Authentication:** Bearer token required
+
+**Parameters:**
+
+| Name | In | Type | Required | Description |
+|------|----|------|----------|-------------|
+| `id` | path | string (UUID) | Yes | User ID |
+| `include` | query | string | No | Comma-separated relations: `posts,profile` |
+
+**Response:**
+
+| Status | Description | Body |
+|--------|-------------|------|
+| `200` | Success | `{ id, name, email, createdAt }` |
+| `401` | Unauthorized | `{ error: "Invalid token" }` |
+| `404` | Not found | `{ error: "User not found" }` |
+
+**Example:**
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.example.com/api/users/abc-123
+```
+```
+
+### Batch Endpoint
+
+```markdown
+## POST /api/users/batch
+
+Create multiple users in a single request.
+
+**Request Body:**
+
+```json
+{
+  "users": [
+    { "name": "Alice", "email": "alice@example.com" },
+    { "name": "Bob", "email": "bob@example.com" }
+  ]
+}
+```
+
+**Response:** `201` — Array of created user objects
+```
+
+### API Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|------|
+| Undocumented parameters | Document all params with types |
+| Missing error responses | List every possible status code |
+| No example request | Include curl or fetch example |
+| Assume auth is obvious | State auth requirement explicitly |
+
+---
+
+## 3. ADR Template (4 Required Sections)
+
+Architecture Decision Records capture **why** decisions were made.
+
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+
+Accepted | 2025-01-15
+
+## Context
+
+We need a primary database for the user service. Requirements:
+- ACID compliance for financial transactions
+- JSON support for flexible user profiles
+- Proven at scale (>10M rows)
+- Team has existing expertise
+
+Alternatives considered:
+1. **MySQL** — Less JSON support, team less experienced
+2. **MongoDB** — No ACID, schema flexibility unnecessary
+3. **PostgreSQL** — Meets all requirements
+
+## Decision
+
+Use **PostgreSQL 16** with Prisma ORM.
+
+- Connection pooling via PgBouncer
+- Read replicas for analytics queries
+- JSONB columns for extensible metadata
+
+## Consequences
+
+**Positive:**
+- Strong ACID guarantees for transactions
+- JSONB enables schema evolution without migrations
+- Team already proficient
+
+**Negative:**
+- Vertical scaling limits (mitigated by read replicas)
+- More complex setup than SQLite for local dev
+- Requires connection pool management
+```
+
+### ADR Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|------|
+| Skip Consequences | Always include trade-offs |
+| No alternatives listed | Show what was considered |
+| Vague context | Quantify requirements |
+| No date on status | Include decision date |
+
+---
+
+## 4. Changelog Template
+
+Follow [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.2.0] - 2025-01-20
+
+### Added
+- User profile photo upload (max 5MB, JPEG/PNG)
+- Email verification flow with 24h expiry
+
+### Changed
+- Upgraded Prisma from 5.x to 6.x
+- Password hashing from bcrypt to argon2id
+
+### Fixed
+- Race condition in concurrent checkout (#234)
+- Memory leak in WebSocket handler (#256)
+
+### Deprecated
+- `GET /api/v1/users` — Use `GET /api/v2/users` instead
+
+## [1.1.0] - 2025-01-10
+
+### Added
+- Two-factor authentication via TOTP
+```
+
+### Changelog Categories (Fixed Order)
+
+| Category | When to Use |
+|----------|-------------|
+| **Added** | New features |
+| **Changed** | Changes to existing functionality |
+| **Deprecated** | Features to be removed |
+| **Removed** | Features removed |
+| **Fixed** | Bug fixes |
+| **Security** | Vulnerability patches |
+
+---
+
+## 5. llms.txt Template (AI Context)
+
+Provide AI agents with project context:
+
+```markdown
+# Project Name
+
+> One-line description
+
+## Tech Stack
+
+- **Runtime:** Node.js 20
+- **Framework:** Next.js 15 (App Router)
+- **Database:** PostgreSQL 16 + Prisma 6
+- **Auth:** NextAuth.js v5
+- **Styling:** Tailwind CSS v4
+
+## Project Structure
+
+```
+src/
+├── app/           # Next.js App Router pages
+├── components/    # Shared React components
+├── lib/           # Utility functions
+├── server/        # Server-side logic
+│   ├── api/       # API route handlers
+│   └── db/        # Database queries
+└── types/         # TypeScript type definitions
+```
+
+## Key Patterns
+
+- Server Components by default, `'use client'` only when needed
+- All database access through `src/server/db/`
+- Feature-based directory structure within `app/`
+- Environment variables in `.env.local` (see `.env.example`)
+
+## Important Files
+
+- `prisma/schema.prisma` — Database schema
+- `src/lib/auth.ts` — Authentication configuration
+- `src/server/api/router.ts` — API route definitions
+```
+
+---
+
+## 6. Comment Guidelines
+
+### What to Comment (Why)
+
+```typescript
+// Business rule: orders over $500 require manager approval
+// due to fraud prevention policy (POLICY-2024-03)
+if (order.total > 500) {
+  await requireApproval(order, 'manager');
+}
+
+// Quadratic probe instead of linear for better cache behavior
+// when load factor > 0.7 (measured 2x throughput improvement)
+const index = quadraticProbe(hash, table.length);
+
+// WARNING: This endpoint is called by the legacy billing system
+// which sends dates as MM/DD/YYYY. Do not change the format
+// without updating the billing service first.
+function parseLegacyDate(dateStr: string): Date {
+```
+
+### What NOT to Comment (What)
+
+```typescript
+// ❌ Don't: states the obvious
+// Increment counter by 1
+counter++;
+
+// ❌ Don't: restates the code
+// Set user name to the input value
+user.name = input.value;
+
+// ❌ Don't: comments every line
+// Get the users
+const users = await getUsers();
+// Filter active users
+const active = users.filter(u => u.active);
+// Return the active users
+return active;
+```
+
+### Comment Decision Table
+
+| Situation | Comment? | Example |
+|-----------|----------|---------|
+| Business rule | ✅ Yes | Why this threshold/limit exists |
+| Complex algorithm | ✅ Yes | Why this approach, not the obvious one |
+| API contract | ✅ Yes | External dependencies, format requirements |
+| Workaround/hack | ✅ Yes | Why, and link to tracking issue |
+| Obvious code | ❌ No | `i++`, `return result` |
+| Well-named function | ❌ No | `calculateTotalWithTax()` |
+| Type declarations | ❌ No | Types are self-documenting |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [engineering-spec.md](engineering-spec.md) | Full engineering spec and contracts |
+| [../SKILL.md](../SKILL.md) | Quick reference and anti-patterns |
+
+---
+
+⚡ PikaKit v3.9.134