Initial commit

2025-11-30 08:37:25 +08:00
commit 71961f9eff
18 changed files with 3314 additions and 0 deletions
--- a/commands/write-api.md
+++ b/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**