Initial commit

commands/review-docs.md

@@ -0,0 +1,110 @@
+---
+name: review-docs
+description: Review existing documentation for quality, voice, tone, and completeness
+argument-hint: "[file]"
+arguments:
+  - name: file
+    description: Path to the documentation file to review
+    required: false
+---
+
+# Review Documentation Command
+
+You're reviewing documentation quality. This command dispatches the docs-reviewer agent.
+
+## Review Process
+
+The review covers five dimensions:
+
+### 1. Voice and Tone
+- Uses "you" not "users"
+- Present tense for current behavior
+- Active voice (subject does action)
+- Assertive but not arrogant
+- Sounds like helping a colleague
+
+### 2. Structure
+- Sentence case headings
+- Section dividers between major topics
+- Scannable (bullets, tables, headings)
+- Logical hierarchy
+
+### 3. Completeness
+- All sections present
+- Examples included
+- Links work
+- Next steps provided
+
+### 4. Clarity
+- Short sentences (one idea)
+- Short paragraphs (2-3 sentences)
+- Jargon explained
+- Realistic examples
+
+### 5. Technical Accuracy
+- Facts are correct
+- Code examples work
+- Links valid
+- Version info current
+
+## Dispatch Review Agent
+
+```
+Task tool:
+  subagent_type: "ring-tw-team:docs-reviewer"
+  model: "opus"
+  prompt: "Review this documentation for quality. Check:
+          1. Voice and tone (second person, active voice, present tense)
+          2. Structure (sentence case, dividers, scannable)
+          3. Completeness (examples, links, next steps)
+          4. Clarity (short sentences, no jargon)
+          5. Accuracy (facts, code, links)
+
+          Provide:
+          - VERDICT: PASS / NEEDS_REVISION / MAJOR_ISSUES
+          - Prioritized issues with locations and fixes
+          - What was done well
+
+          Documentation to review:
+          [paste or reference file content]"
+```
+
+## Quick Checklist
+
+### Voice (scan for these)
+- [ ] No "users" or "one" (should be "you")
+- [ ] No "will" for current behavior (should be present tense)
+- [ ] No "is created by" (should be active: "creates")
+
+### Structure (scan for these)
+- [ ] Headings are sentence case
+- [ ] `---` dividers present
+- [ ] Content is scannable
+
+### Completeness (check for)
+- [ ] Examples present
+- [ ] Links work
+- [ ] Next steps at end
+
+## Verdict Criteria
+
+**PASS:** No critical issues, ≤2 high-priority issues, consistent voice/tone
+
+**NEEDS_REVISION:** Has high-priority issues, some inconsistencies, minor gaps
+
+**MAJOR_ISSUES:** Critical issues, significant problems, poor structure
+
+## Common Issues Reference
+
+| Issue | Example | Fix |
+|-------|---------|-----|
+| Third person | "Users can..." | "You can..." |
+| Passive voice | "...is returned" | "...returns" |
+| Title case | "Getting Started" | "Getting started" |
+| Missing prereqs | Steps without context | Add prerequisites |
+| No examples | API without code | Add examples |
+| Long sentences | 40+ words | Split into multiple |
+
+Now proceed with reviewing documentation.
+
+$ARGUMENTS.file ? Read the file at: **$ARGUMENTS.file** : Paste or specify the documentation to review.

commands/write-api.md

@@ -0,0 +1,145 @@
+---
+name: write-api
+description: Start writing API reference documentation for an endpoint
+argument-hint: "[endpoint]"
+arguments:
+  - name: endpoint
+    description: The API endpoint to document (e.g., POST /accounts)
+    required: true
+---
+
+# Write API Reference Command
+
+You're starting API reference documentation. Follow these steps:
+
+## 1. Understand the Endpoint
+
+**Endpoint to document:** $ARGUMENTS.endpoint
+
+Gather information about:
+- HTTP method and path
+- Path parameters
+- Query parameters
+- Request body schema
+- Response schema
+- Error conditions
+
+## 2. Required Sections
+
+Every endpoint must include:
+
+### HTTP Method and Path
+```markdown
+`POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts`
+```
+
+### Path Parameters
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+
+### Query Parameters (if applicable)
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+
+### Request Body
+```json
+{
+  "field": "value"
+}
+```
+
+### Request Body Fields
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+
+### Response
+```json
+{
+  "field": "value"
+}
+```
+
+### Response Fields
+| Field | Type | Description |
+|-------|------|-------------|
+
+### Errors
+| Status Code | Error Code | Description |
+|-------------|------------|-------------|
+
+## 3. Field Description Patterns
+
+**UUID:** "The unique identifier of the [Entity]"
+
+**String with constraints:** "[Purpose] (max N chars, format)"
+
+**Enum:** "[Purpose]: `value1`, `value2`, `value3`"
+
+**Boolean:** "If `true`, [behavior]. Default: `value`"
+
+**Timestamp:** "Timestamp of [event] (UTC)"
+
+**Deprecated:** "**[Deprecated]** Use `newField` instead"
+
+**Read-only:** "**Read-only.** Generated by the system"
+
+## 4. Example Quality
+
+### Request examples must:
+- Use realistic data (not "foo", "bar")
+- Include all required fields
+- Be valid JSON
+
+### Response examples must:
+- Show complete structure
+- Include all fields
+- Use realistic UUIDs and timestamps
+
+## 5. Dispatch Agent
+
+For complex API documentation, dispatch the api-writer agent:
+
+```
+Task tool:
+  subagent_type: "ring-tw-team:api-writer"
+  model: "opus"
+  prompt: "Document the [endpoint] endpoint. Include:
+          - All path/query parameters
+          - Complete request body schema
+          - Complete response schema
+          - All error codes
+          - Realistic examples"
+```
+
+## 6. Review Before Publishing
+
+After writing, use the docs-reviewer agent:
+
+```
+Task tool:
+  subagent_type: "ring-tw-team:docs-reviewer"
+  model: "opus"
+  prompt: "Review this API documentation for completeness and accuracy:
+          [paste documentation]"
+```
+
+## Data Types Reference
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `uuid` | UUID v4 | `3172933b-50d2-4b17-96aa-9b378d6a6eac` |
+| `string` | Text | `"Customer Account"` |
+| `integer` | Whole number | `42` |
+| `boolean` | True/false | `true` |
+| `timestamptz` | ISO 8601 (UTC) | `2024-01-15T10:30:00Z` |
+| `jsonb` | JSON object | `{"key": "value"}` |
+| `array` | List | `["item1", "item2"]` |
+| `enum` | Predefined values | `currency`, `crypto` |
+
+## HTTP Status Codes
+
+**Success:** 200 (GET/PUT), 201 (POST), 204 (DELETE)
+
+**Errors:** 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 422 (Invalid), 429 (Rate Limited), 500 (Server Error)
+
+Now proceed with documenting: **$ARGUMENTS.endpoint**

commands/write-guide.md

@@ -0,0 +1,129 @@
+---
+name: write-guide
+description: Start writing a functional guide with voice, tone, and structure guidance
+argument-hint: "[topic]"
+arguments:
+  - name: topic
+    description: The topic or feature to document
+    required: true
+---
+
+# Write Guide Command
+
+You're starting a functional documentation task. Follow these steps:
+
+## 1. Understand the Topic
+
+**Topic to document:** $ARGUMENTS.topic
+
+First, gather context about this topic:
+- What is it and why does it matter?
+- Who is the target audience?
+- What should readers be able to do after reading?
+
+## 2. Choose Document Type
+
+Select the appropriate structure:
+
+### Conceptual Documentation
+For explaining what something is and how it works.
+
+### Getting Started Guide
+For helping users accomplish their first task.
+
+### How-To Guide
+For task-focused instructions with specific goals.
+
+### Best Practices
+For guidance on optimal usage patterns.
+
+## 3. Apply Writing Standards
+
+### Voice and Tone
+- Write like you're helping a smart colleague who just joined
+- Use "you" not "users"
+- Use present tense
+- Use active voice
+- Be assertive but not arrogant
+
+### Structure
+- Sentence case for headings
+- Short sentences (one idea each)
+- Short paragraphs (2-3 sentences)
+- Use `---` dividers between major sections
+- Include examples
+
+### Must Include
+- Clear value statement at the start
+- Key characteristics or steps
+- Working examples
+- Links to related content
+- Next steps at the end
+
+## 4. Dispatch Agent
+
+For complex documentation, dispatch the functional-writer agent:
+
+```
+Task tool:
+  subagent_type: "ring-tw-team:functional-writer"
+  model: "opus"
+  prompt: "Write a [document type] for [topic]. Target audience: [audience].
+          The reader should be able to [goal] after reading."
+```
+
+## 5. Review Before Publishing
+
+After writing, use the docs-reviewer agent:
+
+```
+Task tool:
+  subagent_type: "ring-tw-team:docs-reviewer"
+  model: "opus"
+  prompt: "Review this documentation for voice, tone, structure, and completeness:
+          [paste documentation]"
+```
+
+## Quick Reference
+
+### Document Structures
+
+**Conceptual:**
+```
+# Concept
+Definition paragraph
+## Key characteristics
+## How it works
+---
+## Related concepts
+```
+
+**Getting Started:**
+```
+# Getting started with X
+## Prerequisites
+---
+## Step 1
+## Step 2
+---
+## Next steps
+```
+
+**How-To:**
+```
+# How to X
+## Before you begin
+## Steps
+## Verification
+```
+
+**Best Practices:**
+```
+# Best practices for X
+## Practice 1
+- Mistake:
+- Best practice:
+## Summary
+```
+
+Now proceed with documenting: **$ARGUMENTS.topic**