zhongwei/gh-lerianstudio-ring-tw-team
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:37:25 +08:00
commit 71961f9eff
18 changed files with 3314 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

303
skills/api-field-descriptions/SKILL.md Normal file
View File

@@ -0,0 +1,303 @@
---
name: api-field-descriptions
description: |
Patterns for writing clear, consistent API field descriptions including
types, constraints, examples, and edge cases.
trigger: |
- Writing API field documentation
- Documenting request/response schemas
- Creating data model documentation
skip_when: |
- Writing conceptual docs → use writing-functional-docs
- Full API endpoint docs → use writing-api-docs
related:
complementary: [writing-api-docs]
---
# API Field Descriptions
Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
---
## Field Description Structure
Every field description should answer:
1. **What is it?** – The field's purpose
2. **What type?** – Data type and format
3. **Required?** – Is it mandatory?
4. **Constraints?** – Limits, validations, formats
5. **Example?** – What does valid data look like?
---
## Basic Field Description Format
### Table Format (Preferred)
```markdown
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | — | The unique identifier of the Account |
| name | string | Yes | The display name of the Account (max 255 chars) |
| status | enum | — | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |
```
**Note:** Use `—` for response-only fields (not applicable for requests).
### Nested Object Format
```markdown
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| status | object | — | Account status information |
| status.code | string | — | Status code: `ACTIVE`, `INACTIVE`, `BLOCKED` |
| status.description | string | — | Optional human-readable description |
```
---
## Description Patterns by Type
### UUID Fields
```markdown
| id | uuid | — | The unique identifier of the Account |
| organizationId | uuid | Yes | The unique identifier of the Organization |
```
Pattern: "The unique identifier of the [Entity]"
---
### String Fields
**Simple string:**
```markdown
| name | string | Yes | The display name of the Account |
```
**String with constraints:**
```markdown
| code | string | Yes | The asset code (max 10 chars, uppercase, e.g., "BRL") |
| alias | string | No | A user-friendly identifier (must start with @) |
```
**String with format:**
```markdown
| email | string | Yes | Email address (e.g., "user@example.com") |
| phone | string | No | Phone number in E.164 format (e.g., "+5511999999999") |
```
---
### Enum Fields
```markdown
| type | enum | Yes | Asset type: `currency`, `crypto`, `commodity`, `others` |
| status | enum | — | Transaction status: `pending`, `completed`, `reversed` |
```
Pattern: "[Field purpose]: `value1`, `value2`, `value3`"
Always list all valid values in backticks.
---
### Boolean Fields
```markdown
| allowSending | boolean | No | If `true`, sending transactions is permitted. Default: `true` |
| allowReceiving | boolean | No | If `true`, receiving transactions is permitted. Default: `true` |
```
Pattern: "If `true`, [what happens]. Default: `[value]`"
---
### Numeric Fields
**Integer:**
```markdown
| version | integer | — | Balance version, incremented with each transaction |
| limit | integer | No | Results per page (1-100). Default: 10 |
```
**With range:**
```markdown
| scale | integer | Yes | Decimal places for the asset (0-18) |
```
---
### Timestamp Fields
```markdown
| createdAt | timestamptz | — | Timestamp of creation (UTC) |
| updatedAt | timestamptz | — | Timestamp of last update (UTC) |
| deletedAt | timestamptz | — | Timestamp of soft deletion, if applicable (UTC) |
```
Pattern: "Timestamp of [event] (UTC)"
Always specify UTC.
---
### Object Fields (JSONB)
```markdown
| metadata | jsonb | No | Key-value pairs for custom data |
| status | jsonb | — | Status information including code and description |
| address | jsonb | No | Address information (street, city, country, postalCode) |
```
For complex objects, document child fields separately or link to schema.
---
### Array Fields
```markdown
| source | array | Yes | List of source account aliases |
| operations | array | — | List of operations in the transaction |
| tags | array | No | List of string tags for categorization |
```
Specify what the array contains.
---
## Required vs Optional
### In Request Documentation
| Indicator | Meaning |
|-----------|---------|
| Yes | Field must be provided |
| No | Field is optional |
| Conditional | Required in specific scenarios (explain in description) |
**Conditional example:**
```markdown
| portfolioId | uuid | Conditional | Required when creating customer accounts |
```
### In Response Documentation
Response fields don't have "Required" – they're always returned (or null).
Use `—` in the Required column for response-only fields.
---
## Default Values
Always document defaults for optional fields:
```markdown
| limit | integer | No | Results per page. Default: 10 |
| allowSending | boolean | No | Permit sending. Default: `true` |
| type | string | No | Account type. Default: none (untyped) |
```
---
## Nullable Fields
Indicate when fields can be null:
```markdown
| deletedAt | timestamptz | — | Soft deletion timestamp, or `null` if not deleted |
| description | string | No | Optional description, or `null` if not provided |
| parentAccountId | uuid | No | Parent account ID, or `null` for root accounts |
```
---
## Deprecated Fields
Mark deprecated fields clearly:
```markdown
| chartOfAccounts | string | No | **[Deprecated]** Use `route` instead |
```
Or with more context:
```markdown
| chartOfAccountsGroupName | string | — | **[Deprecated]** This field is present for backward compatibility. Use `route` for new integrations. |
```
---
## Read-Only Fields
Indicate fields that can't be set by the client:
```markdown
| id | uuid | — | **Read-only.** Generated by the system |
| createdAt | timestamptz | — | **Read-only.** Set automatically on creation |
| version | integer | — | **Read-only.** Incremented automatically |
```
---
## Field Relationship Descriptions
When fields relate to other entities:
```markdown
| ledgerId | uuid | Yes | The unique identifier of the Ledger this account belongs to |
| portfolioId | uuid | No | The Portfolio grouping this account. See [Portfolios](link) |
| assetCode | string | Yes | References an Asset code. Must exist in the Ledger |
```
---
## Writing Good Descriptions
### Be Specific
| Vague | Specific |
|-------|----------|
| The name | The display name of the Account |
| Status info | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |
| A number | Balance version, incremented with each transaction |
### Include Constraints
| Missing Constraints | With Constraints |
|--------------------|------------------|
| The code | The asset code (max 10 chars, uppercase) |
| Page number | Page number (starts at 1) |
| Amount | Amount in smallest unit (e.g., cents for BRL) |
### Add Context
| No Context | With Context |
|------------|--------------|
| The timestamp | Timestamp of creation (UTC) |
| Account ID | The Account receiving the funds |
| Parent ID | Parent account for hierarchical structures |
---
## Quality Checklist
For each field, verify:
- [ ] Description explains the field's purpose
- [ ] Data type is accurate
- [ ] Required/optional status is clear
- [ ] Constraints are documented (max length, valid values)
- [ ] Default value noted (if optional)
- [ ] Nullable behavior explained (if applicable)
- [ ] Deprecated fields are marked
- [ ] Read-only fields are indicated
- [ ] Relationships to other entities are clear
- [ ] Example values are realistic

287
skills/documentation-review/SKILL.md Normal file
View File

@@ -0,0 +1,287 @@
---
name: documentation-review
description: |
Comprehensive checklist and process for reviewing documentation quality
including voice, tone, structure, completeness, and technical accuracy.
trigger: |
- Reviewing draft documentation
- Pre-publication quality check
- Documentation audit
- Ensuring style guide compliance
skip_when: |
- Writing new documentation → use writing-functional-docs or writing-api-docs
- Only checking voice → use voice-and-tone
sequence:
after: [writing-functional-docs, writing-api-docs]
related:
complementary: [voice-and-tone, documentation-structure]
---
# Documentation Review Process
Review documentation systematically across multiple dimensions. A thorough review catches issues before they reach users.
---
## Review Dimensions
Documentation review covers five key areas:
1. **Voice and Tone** – Does it sound right?
2. **Structure** – Is it organized effectively?
3. **Completeness** – Is everything covered?
4. **Clarity** – Is it easy to understand?
5. **Technical Accuracy** – Is it correct?
---
## Voice and Tone Review
### Check Second Person Usage
- [ ] Uses "you" instead of "users" or "one"
- [ ] Addresses reader directly
- [ ] Creates connection with the audience
**Flag:**
> ❌ "Users can create accounts..."
>
> ✅ "You can create accounts..."
### Check Tense
- [ ] Uses present tense for current behavior
- [ ] Uses future tense only for planned features
- [ ] Avoids conditional ("would", "could") when stating facts
**Flag:**
> ❌ "The API will return a response..."
>
> ✅ "The API returns a response..."
### Check Active Voice
- [ ] Subject performs the action
- [ ] Avoids passive constructions
- [ ] Clear who/what is doing what
**Flag:**
> ❌ "An error is returned by the API..."
>
> ✅ "The API returns an error..."
### Check Tone
- [ ] Assertive but not arrogant
- [ ] Encouraging, not condescending
- [ ] Technical but human
- [ ] Sounds like helping a colleague
---
## Structure Review
### Check Hierarchy
- [ ] Logical content organization
- [ ] Clear parent-child relationships
- [ ] Appropriate nesting depth (max 3 levels)
### Check Headings
- [ ] Uses sentence case (not Title Case)
- [ ] Action-oriented where appropriate
- [ ] Descriptive and specific
- [ ] Creates scannable structure
**Flag:**
> ❌ "Account Creation Process Overview"
>
> ✅ "Creating your first account"
### Check Section Dividers
- [ ] Major sections separated with `---`
- [ ] Not overused (not every heading)
- [ ] Creates visual breathing room
### Check Navigation
- [ ] Links to related content
- [ ] Previous/Next links where appropriate
- [ ] On-this-page navigation for long content
---
## Completeness Review
### For Conceptual Documentation
- [ ] Definition/overview paragraph present
- [ ] Key characteristics listed
- [ ] "How it works" explained
- [ ] Related concepts linked
- [ ] Next steps provided
### For How-To Guides
- [ ] Prerequisites listed
- [ ] All steps included
- [ ] Verification step present
- [ ] Troubleshooting covered (if common issues exist)
- [ ] Next steps provided
### For API Documentation
- [ ] HTTP method and path documented
- [ ] All path parameters documented
- [ ] All query parameters documented
- [ ] All request body fields documented
- [ ] All response fields documented
- [ ] Required vs optional clear
- [ ] Request example provided
- [ ] Response example provided
- [ ] Error codes documented
- [ ] Deprecated fields marked
---
## Clarity Review
### Check Sentence Length
- [ ] One idea per sentence
- [ ] Sentences under 25 words (ideally)
- [ ] Complex ideas broken into multiple sentences
### Check Paragraph Length
- [ ] 2-3 sentences per paragraph
- [ ] One topic per paragraph
- [ ] White space between paragraphs
### Check Jargon
- [ ] Technical terms explained on first use
- [ ] Acronyms expanded on first use
- [ ] Common language preferred over jargon
### Check Examples
- [ ] Examples use realistic data
- [ ] Examples are complete (can be copied/used)
- [ ] Examples follow explanations immediately
---
## Technical Accuracy Review
### For Conceptual Content
- [ ] Facts are correct
- [ ] Behavior descriptions match actual behavior
- [ ] Version information is current
- [ ] Links work and go to correct destinations
### For API Documentation
- [ ] Endpoint paths are correct
- [ ] HTTP methods are correct
- [ ] Field names match actual API
- [ ] Data types are accurate
- [ ] Required/optional status is correct
- [ ] Examples are valid JSON/code
- [ ] Error codes match actual responses
### For Code Examples
- [ ] Code compiles/runs
- [ ] Output matches description
- [ ] No syntax errors
- [ ] Uses current API version
---
## Common Issues to Flag
### Voice Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Third person | "Users can..." | "You can..." |
| Passive voice | "...is returned" | "...returns" |
| Future tense | "will provide" | "provides" |
| Conditional | "would receive" | "receives" |
| Arrogant tone | "Obviously..." | Remove |
### Structure Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Title case | "Getting Started" | "Getting started" |
| Missing dividers | Wall of text | Add `---` |
| Deep nesting | H4, H5, H6 | Flatten or split |
| Vague headings | "Overview" | "Account overview" |
### Completeness Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Missing prereqs | Steps without context | Add prerequisites |
| No examples | API without code | Add examples |
| Dead links | 404 errors | Fix or remove |
| Outdated info | Old version refs | Update |
### Clarity Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Long sentences | 40+ words | Split |
| Wall of text | No bullets | Add structure |
| Undefined jargon | "DSL" unexplained | Define or link |
| Abstract examples | "foo", "bar" | Use realistic data |
---
## Review Output Format
When reviewing documentation, provide structured feedback.
> **Note:** Documentation reviews use `PASS/NEEDS_REVISION/MAJOR_ISSUES` verdicts, which differ from code review verdicts (`PASS/FAIL/NEEDS_DISCUSSION`). Documentation verdicts are graduated—most docs can be improved but may still be publishable with `NEEDS_REVISION`.
```markdown
## Review Summary
**Overall Assessment:** [PASS | NEEDS_REVISION | MAJOR_ISSUES]
### Voice and Tone
- [x] Second person usage ✓
- [ ] Active voice – Found 3 passive constructions
- [x] Appropriate tone ✓
### Issues Found
#### High Priority
1. **Line 45:** Passive voice "is created by" → "creates"
2. **Line 78:** Missing required field documentation
#### Medium Priority
1. **Line 23:** Title case in heading → sentence case
2. **Line 56:** Long sentence (42 words) → split
#### Low Priority
1. **Line 12:** Could add example for clarity
### Recommendations
1. Fix passive voice instances (3 found)
2. Add missing API field documentation
3. Convert headings to sentence case
```
---
## Quick Review Checklist
For rapid reviews, check these essentials:
**Voice (30 seconds)**
- [ ] "You" not "users"
- [ ] Present tense
- [ ] Active voice
**Structure (30 seconds)**
- [ ] Sentence case headings
- [ ] Section dividers present
- [ ] Scannable (bullets, tables)
**Completeness (1 minute)**
- [ ] Examples present
- [ ] Links work
- [ ] Next steps included
**Accuracy (varies)**
- [ ] Technical facts correct
- [ ] Code examples work
- [ ] Version info current

342
skills/documentation-structure/SKILL.md Normal file
View File

@@ -0,0 +1,342 @@
---
name: documentation-structure
description: |
Patterns for organizing and structuring documentation including hierarchy,
navigation, and information architecture.
trigger: |
- Planning documentation structure
- Organizing content hierarchy
- Deciding how to split content across pages
- Creating navigation patterns
skip_when: |
- Writing content → use writing-functional-docs or writing-api-docs
- Checking voice → use voice-and-tone
related:
complementary: [writing-functional-docs, writing-api-docs]
---
# Documentation Structure
Good structure helps users find what they need quickly. Organize content by user tasks and mental models, not by internal system organization.
---
## Content Hierarchy
### Top-Level Organization
Structure documentation around user needs:
```
Documentation/
├── Welcome/ # Entry point, product overview
├── Getting Started/ # First steps, quick wins
├── Guides/ # Task-oriented documentation
│ ├── Understanding X # Conceptual documentation
│ ├── Installing X # Setup and deployment
│ ├── Use Cases # Real-world scenarios
│ ├── Core Entities # Domain concepts
│ └── Best Practices # Recommendations
├── API Reference/ # Technical reference
│ ├── Introduction # API overview
│ ├── Getting Started # Quick start
│ └── Endpoints/ # Per-resource documentation
└── Updates/ # Changelog, versioning
```
---
## Page Structure Patterns
### Overview Pages
Introduce a section and link to child pages.
```markdown
# Section Name
Brief description of what this section covers and who it's for.
---
## Content
In this section, you will find:
- [**Topic A**](link): Brief description
- [**Topic B**](link): Brief description
- [**Topic C**](link): Brief description
```
---
### Conceptual Pages
Explain a single concept thoroughly.
```markdown
# Concept Name
Lead paragraph defining the concept and its importance.
## Key characteristics
- Point 1
- Point 2
- Point 3
## How it works
Detailed explanation with diagrams.
---
## Subtopic A
Content about subtopic A.
---
## Subtopic B
Content about subtopic B.
---
## Related concepts
- [Related A](link) – Connection explanation
- [Related B](link) – Connection explanation
```
---
### Task-Oriented Pages
Guide users through a specific workflow.
```markdown
# How to [accomplish task]
Brief context on when and why.
## Prerequisites
- Requirement 1
- Requirement 2
---
## Step 1: Action name
Explanation of what to do.
## Step 2: Action name
Continue the workflow.
---
## Verification
How to confirm success.
## Next steps
- [Follow-up task](link)
- [Related task](link)
```
---
## Section Dividers
Use horizontal rules (`---`) to create visual separation between major sections.
```markdown
## Section One
Content here.
---
## Section Two
New topic content here.
```
**When to use dividers:**
- Between major topic changes
- Before "Related" or "Next steps" sections
- After introductory content
- Before prerequisites in guides
**Don't overuse:** Not every heading needs a divider. Use them for significant transitions.
---
## Navigation Patterns
### Breadcrumb Context
Always show where users are in the hierarchy:
```
Guides > Core Entities > Accounts
```
### Previous/Next Links
Connect sequential content:
```markdown
[Previous: Assets](link) | [Next: Portfolios](link)
```
### On-This-Page Navigation
For long pages, show section links:
```markdown
On this page:
- [Key characteristics](#key-characteristics)
- [How it works](#how-it-works)
- [Managing via API](#managing-via-api)
```
---
## Information Density
### Scannable Content
Users scan before they read. Make content scannable:
1. **Lead with the key point** in each section
2. **Use bullet points** for lists of 3+ items
3. **Use tables** for comparing options
4. **Use headings** every 2-3 paragraphs
5. **Use bold** for key terms on first use
---
### Progressive Disclosure
Start with essentials, then add depth:
```markdown
# Feature Overview
Essential information that 80% of users need.
---
## Advanced Configuration
Deeper details for users who need them.
### Rare Scenarios
Edge cases and special situations.
```
---
## Tables vs Lists
### Use Tables When:
- Comparing multiple items across same attributes
- Showing structured data (API fields, parameters)
- Displaying options with consistent properties
```markdown
| Model | Best For | Support Level |
|-------|----------|---------------|
| Community | Experimentation | Community |
| Enterprise | Production | Dedicated |
```
### Use Lists When:
- Items don't have comparable attributes
- Sequence matters (steps)
- Items have varying levels of detail
```markdown
## Key features
- **Central Ledger**: Real-time account and transaction management
- **Modularity**: Flexible architecture for customization
- **Scalability**: Handles large transaction volumes
```
---
## Code Examples Placement
### Inline Code
For short references within text:
> Set the `assetCode` field to your currency code.
### Code Blocks
For complete, runnable examples:
```json
{
"name": "Customer Account",
"assetCode": "BRL"
}
```
### Placement Rules:
1. Show the example immediately after explaining it
2. Keep examples minimal but complete
3. Use realistic data (not "foo", "bar")
4. Show both request and response for API docs
---
## Cross-Linking Strategy
### Link to First Mention
Link concepts when first mentioned in a section:
> Each [Account](link) is linked to a single [Asset](link).
### Don't Over-Link
Don't link every mention of a term. Once per section is enough.
### Link Destinations
| Link Type | Destination |
|-----------|-------------|
| Concept name | Conceptual documentation |
| API action | API reference endpoint |
| "Learn more" | Deeper dive documentation |
| "See also" | Related but different topics |
---
## Page Length Guidelines
| Page Type | Target Length | Reasoning |
|-----------|---------------|-----------|
| Overview | 1-2 screens | Quick orientation |
| Concept | 2-4 screens | Thorough explanation |
| How-to | 1-3 screens | Task completion |
| API endpoint | 2-3 screens | Complete reference |
| Best practices | 3-5 screens | Multiple recommendations |
If a page exceeds 5 screens, consider splitting into multiple pages.
---
## Quality Checklist
Before finalizing structure:
- [ ] Content is organized by user task, not system structure
- [ ] Overview pages link to all child content
- [ ] Section dividers separate major topics
- [ ] Headings create scannable structure
- [ ] Tables are used for comparable items
- [ ] Code examples follow explanations
- [ ] Cross-links connect related content
- [ ] Page length is appropriate for content type
- [ ] Navigation (prev/next) connects sequential content

216
skills/using-tw-team/SKILL.md Normal file
View File

@@ -0,0 +1,216 @@
---
name: using-tw-team
description: |
Technical writing specialists for functional and API documentation. Dispatch when
you need to create guides, conceptual docs, or API references following established
documentation standards.
trigger: |
- Need to write functional documentation (guides, conceptual docs, tutorials)
- Need to write API reference documentation
- Need to review existing documentation quality
- Writing or updating product documentation
skip_when: |
- Writing code → use dev-team agents
- Writing plans → use pm-team agents
- General code review → use default plugin reviewers
related:
similar: [using-ring, using-dev-team]
---
# Using Ring Technical Writing Specialists
The ring-tw-team plugin provides specialized agents for technical documentation. Use them via `Task tool with subagent_type:`.
**Remember:** Follow the **ORCHESTRATOR principle** from `using-ring`. Dispatch agents to handle documentation tasks; don't write complex documentation directly.
---
## 3 Documentation Specialists
### 1. Functional Writer
**`ring-tw-team:functional-writer`**
**Specializations:**
- Conceptual documentation and guides
- Getting started tutorials
- Feature explanations
- Best practices documentation
- Use case documentation
- Workflow and process guides
**Use When:**
- Writing new product guides
- Creating tutorials for features
- Documenting best practices
- Writing conceptual explanations
- Creating "how to" documentation
**Example dispatch:**
```
Task tool:
subagent_type: "ring-tw-team:functional-writer"
model: "opus"
prompt: "Write a getting started guide for the authentication feature"
```
---
### 2. API Writer
**`ring-tw-team:api-writer`**
**Specializations:**
- REST API reference documentation
- Endpoint descriptions and examples
- Request/response schema documentation
- Error code documentation
- Field-level descriptions
- API integration guides
**Use When:**
- Documenting new API endpoints
- Writing request/response examples
- Documenting error codes
- Creating API field descriptions
- Writing integration guides
**Example dispatch:**
```
Task tool:
subagent_type: "ring-tw-team:api-writer"
model: "opus"
prompt: "Document the POST /accounts endpoint with request/response examples"
```
---
### 3. Documentation Reviewer
**`ring-tw-team:docs-reviewer`**
**Specializations:**
- Voice and tone compliance
- Structure and hierarchy review
- Completeness assessment
- Clarity and readability analysis
- Consistency checking
- Technical accuracy verification
**Use When:**
- Reviewing draft documentation
- Checking documentation quality
- Ensuring style guide compliance
- Validating documentation completeness
- Pre-publication review
**Example dispatch:**
```
Task tool:
subagent_type: "ring-tw-team:docs-reviewer"
model: "opus"
prompt: "Review this guide for voice, tone, structure, and completeness"
```
---
## Decision Matrix: Which Specialist?
| Need | Specialist | Use Case |
|------|-----------|----------|
| Guides, tutorials, concepts | Functional Writer | Product documentation |
| API endpoints, schemas, errors | API Writer | Technical API reference |
| Quality check, style compliance | Docs Reviewer | Pre-publication review |
---
## Documentation Standards Summary
These agents enforce the following standards:
### Voice and Tone
- **Assertive, but never arrogant** – Say what needs to be said, clearly
- **Encouraging and empowering** – Guide users through complexity
- **Tech-savvy, but human** – Use technical terms when needed, prioritize clarity
- **Humble and open** – Confident but always learning
### Capitalization
- **Sentence case** for all headings and titles
- Only first letter and proper nouns are capitalized
- ✅ "Getting started with the API"
- ❌ "Getting Started With The API"
### Structure Patterns
1. Lead with a clear definition paragraph
2. Use bullet points for key characteristics
3. Separate sections with `---` dividers
4. Include info boxes and warnings where needed
5. Link to related API reference
6. Add code examples for technical topics
---
## Dispatching Multiple Specialists
For comprehensive documentation, dispatch in **parallel** (single message, multiple Task calls):
```
✅ CORRECT:
Task #1: ring-tw-team:functional-writer (write the guide)
Task #2: ring-tw-team:api-writer (write API reference)
(Both run in parallel)
Then:
Task #3: ring-tw-team:docs-reviewer (review both)
```
---
## ORCHESTRATOR Principle
Remember:
- **You're the orchestrator** – Dispatch specialists, don't write directly
- **Let specialists apply standards** – They know voice, tone, and structure
- **Combine with other plugins** – API writers + backend engineers for accuracy
### Good Example (ORCHESTRATOR):
> "I need documentation for the new feature. Let me dispatch functional-writer to create the guide."
### Bad Example (OPERATOR):
> "I'll manually write all the documentation myself."
---
## Available in This Plugin
**Agents:**
- functional-writer
- api-writer
- docs-reviewer
**Skills:**
- using-tw-team: Plugin introduction and agent selection
- writing-functional-docs: Functional documentation patterns
- writing-api-docs: API reference documentation patterns
- documentation-structure: Document hierarchy and organization
- voice-and-tone: Voice and tone guidelines
- documentation-review: Documentation quality checklist
- api-field-descriptions: Field description patterns
**Commands:**
- /ring-tw-team:write-guide: Start writing a functional guide
- /ring-tw-team:write-api: Start writing API documentation
- /ring-tw-team:review-docs: Review existing documentation
---
## Integration with Other Plugins
- **using-ring** (default) – ORCHESTRATOR principle for ALL agents
- **using-dev-team** – Developer agents for technical accuracy
- **using-pm-team** – Pre-dev planning before documentation
Dispatch based on your need:
- Documentation writing → ring-tw-team agents
- Technical implementation → ring-dev-team agents
- Feature planning → ring-pm-team agents

229
skills/voice-and-tone/SKILL.md Normal file
View File

@@ -0,0 +1,229 @@
---
name: voice-and-tone
description: |
Voice and tone guidelines for technical documentation. Ensures consistent,
clear, and human writing across all documentation.
trigger: |
- Need to check voice and tone compliance
- Writing new documentation
- Reviewing existing documentation for style
skip_when: |
- Only checking structure → use documentation-structure
- Only checking technical accuracy → use docs-reviewer agent
related:
complementary: [writing-functional-docs, writing-api-docs, documentation-review]
---
# Voice and Tone Guidelines
Write the way you work: with confidence, clarity, and care. Good documentation sounds like a knowledgeable colleague helping you solve a problem.
---
## Core Tone Principles
### Assertive, But Never Arrogant
Say what needs to be said, clearly and without overexplaining. Be confident in your statements.
**Good:**
> Midaz uses a microservices architecture, which allows each component to be self-sufficient and easily scalable.
**Avoid:**
> Midaz might use what some people call a microservices architecture, which could potentially allow components to be somewhat self-sufficient.
---
### Encouraging and Empowering
Guide users to make progress, especially when things get complex. Acknowledge difficulty but show the path forward.
**Good:**
> This setup isn't just technically solid; it's built for real-world use. You can add new components as needed without disrupting what's already in place.
**Avoid:**
> This complex setup requires careful understanding of multiple systems before you can safely make changes.
---
### Tech-Savvy, But Human
Talk to developers, not at them. Use technical terms when needed, but always aim for clarity over jargon.
**Good:**
> Each Account is linked to exactly one Asset type.
**Avoid:**
> The Account entity maintains a mandatory one-to-one cardinality with the Asset entity.
---
### Humble and Open
Be confident in your solutions but always assume there's more to learn.
**Good:**
> As Midaz evolves, new fields and tables may be added.
**Avoid:**
> The system is complete and requires no further development.
---
## The Golden Rule
> When in doubt, write like you're helping a smart colleague who just joined the team.
This colleague is:
- Technical and can handle complexity
- New to this specific system
- Busy and appreciates efficiency
- Capable of learning quickly with good guidance
---
## Writing Mechanics
### Use Second Person ("You")
Address the reader directly. This creates connection and clarity.
| Use | Avoid |
|-----|-------|
| You can create as many accounts... | Users can create as many accounts... |
| Your configuration should look like... | The configuration should look like... |
| If you're working with an earlier release... | If one is working with an earlier release... |
---
### Use Present Tense
Describe current behavior, not hypothetical futures.
| Use | Avoid |
|-----|-------|
| Midaz uses Helm Charts | Midaz will use Helm Charts |
| The system returns an error | The system would return an error |
| Each Account holds one Asset type | Each Account will hold one Asset type |
---
### Use Active Voice
Put the subject first. Active voice is clearer and more direct.
| Use | Avoid |
|-----|-------|
| The API returns a JSON response | A JSON response is returned by the API |
| Create an account before... | An account should be created before... |
| Midaz enforces financial discipline | Financial discipline is enforced by Midaz |
---
### Keep Sentences Short
One idea per sentence. Break complex thoughts into multiple sentences.
**Good:**
> External accounts represent accounts outside your organization. They're used to track money coming in or going out.
**Avoid:**
> External accounts in Midaz represent accounts outside your organization's structure, and they're used to track money that's coming in or going out, typically tied to users, partners, or financial providers beyond your internal ledger.
---
## Capitalization Rules
### Sentence Case for Headings
Only capitalize the first letter and proper nouns.
| Correct | Avoid |
|---------|-------|
| Getting started with the API | Getting Started With The API |
| Using the transaction builder | Using The Transaction Builder |
| Managing account types | Managing Account Types |
### Applies to:
- Page titles
- Section headings
- Card titles
- Navigation labels
- Table headers
---
## Terminology Consistency
### Product Names
Always capitalize product names as proper nouns:
- Midaz (not "midaz" or "MIDAZ")
- Console (when referring to the product)
- Reporter, Matcher, Flowker
### Entity Names
Capitalize entity names when referring to the specific concept:
- Account, Ledger, Asset, Portfolio, Segment
- Transaction, Operation, Balance
**Example:**
> Each Account is linked to a single Asset.
But use lowercase for general references:
> You can create multiple accounts within a ledger.
---
## Contractions
Use contractions naturally. They make writing feel more conversational.
| Natural | Stiff |
|---------|-------|
| You'll find... | You will find... |
| It's important... | It is important... |
| Don't delete... | Do not delete... |
| That's because... | That is because... |
---
## Emphasis
### Bold for UI Elements and Key Terms
> Click **Create Account** to open the form.
>
> The **metadata** field accepts key-value pairs.
### Code Formatting for Technical Terms
> Use the `POST /accounts` endpoint.
>
> Set `allowSending` to `true`.
### Avoid Overusing Emphasis
If everything is bold or emphasized, nothing stands out.
---
## Info Boxes and Warnings
### Tips (Helpful Information)
> **Tip:** You can use account aliases to make transactions more readable.
### Notes (Important Context)
> **Note:** You're viewing documentation for the current version.
### Warnings (Potential Issues)
> **Warning:** External accounts cannot be deleted or changed.
### Deprecated Notices
> **Deprecated:** This field will be removed in v4. Use `route` instead.
---
## Quality Checklist
Before publishing, verify your writing:
- [ ] Uses second person ("you") consistently
- [ ] Uses present tense for current behavior
- [ ] Uses active voice (subject does the action)
- [ ] Sentences are short (one idea each)
- [ ] Headings use sentence case
- [ ] Technical terms are used appropriately
- [ ] Contractions are used naturally
- [ ] Emphasis is used sparingly
- [ ] Sounds like helping a colleague, not lecturing

339
skills/writing-api-docs/SKILL.md Normal file
View File

@@ -0,0 +1,339 @@
---
name: writing-api-docs
description: |
Patterns and structure for writing API reference documentation including
endpoint descriptions, request/response schemas, and error documentation.
trigger: |
- Documenting REST API endpoints
- Writing request/response examples
- Documenting error codes
- Creating API field descriptions
skip_when: |
- Writing conceptual guides → use writing-functional-docs
- Reviewing documentation → use documentation-review
- Writing code → use dev-team agents
sequence:
before: [documentation-review]
related:
similar: [writing-functional-docs]
complementary: [api-field-descriptions, documentation-structure]
---
# Writing API Reference Documentation
API reference documentation describes what each endpoint does, its parameters, request/response formats, and error conditions. It focuses on the "what" rather than the "why."
---
## API Reference Principles
### RESTful and Predictable
- Follow standard HTTP methods and status codes
- Use consistent URL patterns
- Document idempotency behavior
### Consistent Formats
- Requests and responses use JSON
- Clear typing and structures
- Standard error format
### Explicit Versioning
- Document version in URL path
- Note backward compatibility
- Mark deprecated fields clearly
---
## Endpoint Documentation Structure
### Basic Structure
```markdown
# Endpoint Name
Brief description of what this endpoint does.
## Request
### HTTP Method and Path
`POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts`
### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| organizationId | uuid | Yes | The unique identifier of the Organization |
| ledgerId | uuid | Yes | The unique identifier of the Ledger |
### Request Body
```json
{
"name": "string",
"assetCode": "string",
"type": "string"
}
```
### Request Body Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | The name of the Account |
| assetCode | string | Yes | The code of the Asset (e.g., "BRL", "USD") |
| type | string | No | The account type classification |
## Response
### Success Response (201 Created)
```json
{
"id": "3172933b-50d2-4b17-96aa-9b378d6a6eac",
"name": "Customer Account",
"assetCode": "BRL",
"status": {
"code": "ACTIVE"
},
"createdAt": "2024-01-15T10:30:00Z"
}
```
### Response Fields
| Field | Type | Description |
|-------|------|-------------|
| id | uuid | The unique identifier of the created Account |
| name | string | The name of the Account |
| createdAt | timestamptz | Timestamp of creation (UTC) |
## Errors
| Status Code | Error Code | Description |
|-------------|------------|-------------|
| 400 | INVALID_REQUEST | Request body validation failed |
| 404 | LEDGER_NOT_FOUND | The specified Ledger does not exist |
| 409 | ACCOUNT_EXISTS | An account with this alias already exists |
```
---
## Field Description Patterns
### Basic Field Description
```markdown
| name | string | The name of the Account |
```
### Field with Constraints
```markdown
| code | string | The asset code (max 10 characters, uppercase) |
```
### Field with Example
```markdown
| email | string | User email address (e.g., "user@example.com") |
```
### Required vs Optional
```markdown
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | The name of the Account |
| alias | string | No | A user-friendly identifier. If omitted, uses the account ID |
```
### Deprecated Fields
```markdown
| chartOfAccountsGroupName | string | **[Deprecated]** Use `route` instead. The name of the group. |
```
---
## Data Types Reference
Use consistent type names across all documentation:
| Type | Description | Example |
|------|-------------|---------|
| `uuid` | UUID v4 identifier | `3172933b-50d2-4b17-96aa-9b378d6a6eac` |
| `string` | Text value | `"Customer Account"` |
| `text` | Long text value | `"Detailed description..."` |
| `integer` | Whole number | `42` |
| `boolean` | True/false value | `true` |
| `timestamptz` | ISO 8601 timestamp (UTC) | `2024-01-15T10:30:00Z` |
| `jsonb` | JSON object | `{"key": "value"}` |
| `array` | List of values | `["item1", "item2"]` |
| `enum` | One of predefined values | `currency`, `crypto`, `commodity` |
---
## Request/Response Examples
### Complete Request Example
Always show a realistic, working example:
```json
{
"name": "João Silva - Checking",
"assetCode": "BRL",
"type": "checking",
"alias": "@joao_checking",
"metadata": {
"customerId": "cust_123456",
"branch": "0001"
}
}
```
### Complete Response Example
Show all fields that would be returned:
```json
{
"id": "3172933b-50d2-4b17-96aa-9b378d6a6eac",
"organizationId": "7c3e4f2a-1b8d-4e5c-9f0a-2d3e4f5a6b7c",
"ledgerId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"name": "João Silva - Checking",
"assetCode": "BRL",
"type": "checking",
"alias": "@joao_checking",
"status": {
"code": "ACTIVE",
"description": null
},
"metadata": {
"customerId": "cust_123456",
"branch": "0001"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"deletedAt": null
}
```
---
## Error Documentation
### Standard Error Format
```json
{
"code": "ACCOUNT_NOT_FOUND",
"message": "The specified account does not exist",
"details": {
"accountId": "invalid-uuid"
}
}
```
### Error Table Format
| Status Code | Error Code | Description | Resolution |
|-------------|------------|-------------|------------|
| 400 | INVALID_REQUEST | Request validation failed | Check request body format |
| 401 | UNAUTHORIZED | Missing or invalid authentication | Provide valid API key |
| 403 | FORBIDDEN | Insufficient permissions | Contact admin for access |
| 404 | NOT_FOUND | Resource does not exist | Verify the resource ID |
| 409 | CONFLICT | Resource already exists | Use a different identifier |
| 422 | UNPROCESSABLE_ENTITY | Business rule violation | Check business constraints |
| 500 | INTERNAL_ERROR | Server error | Retry or contact support |
---
## HTTP Status Codes
### Success Codes
| Code | Usage |
|------|-------|
| 200 OK | Successful GET, PUT, PATCH |
| 201 Created | Successful POST that creates a resource |
| 204 No Content | Successful DELETE |
### Error Codes
| Code | Usage |
|------|-------|
| 400 Bad Request | Malformed request syntax |
| 401 Unauthorized | Missing or invalid authentication |
| 403 Forbidden | Valid auth but insufficient permissions |
| 404 Not Found | Resource does not exist |
| 409 Conflict | Resource state conflict (e.g., duplicate) |
| 422 Unprocessable Entity | Valid syntax but invalid semantics |
| 429 Too Many Requests | Rate limit exceeded |
| 500 Internal Server Error | Server-side error |
---
## Pagination Documentation
When an endpoint returns paginated results:
```markdown
### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | integer | 10 | Number of results per page (max 100) |
| page | integer | 1 | Page number to retrieve |
### Pagination Response
```json
{
"items": [...],
"page": 1,
"limit": 10,
"totalItems": 150,
"totalPages": 15
}
```
```
---
## API Versioning Notes
When documenting versioned APIs:
```markdown
> **Note:** You're viewing documentation for the **current version** (v3).
> For previous versions, use the version switcher.
```
For deprecated endpoints:
```markdown
> **Deprecated:** This endpoint will be removed in v4. Use [/v3/accounts](link) instead.
```
---
## Quality Checklist
Before finishing API documentation, verify:
- [ ] HTTP method and path are correct
- [ ] All path parameters documented
- [ ] All query parameters documented
- [ ] All request body fields documented with types
- [ ] All response fields documented with types
- [ ] Required vs optional fields are clear
- [ ] Realistic request/response examples included
- [ ] All error codes documented
- [ ] Deprecated fields are marked
- [ ] Links to related endpoints included

306
skills/writing-functional-docs/SKILL.md Normal file
View File

@@ -0,0 +1,306 @@
---
name: writing-functional-docs
description: |
Patterns and structure for writing functional documentation including guides,
conceptual explanations, tutorials, and best practices documentation.
trigger: |
- Writing a new guide or tutorial
- Creating conceptual documentation
- Documenting best practices
- Writing "how to" content
skip_when: |
- Writing API reference → use writing-api-docs
- Reviewing documentation → use documentation-review
- Writing code → use dev-team agents
sequence:
before: [documentation-review]
related:
similar: [writing-api-docs]
complementary: [voice-and-tone, documentation-structure]
---
# Writing Functional Documentation
Functional documentation explains concepts, guides users through workflows, and helps them understand "why" and "how" things work. This differs from API reference, which documents "what" each endpoint does.
---
## Document Types
### 1. Conceptual Documentation
Explains core concepts, architecture, and how things work together.
**Structure:**
```markdown
# Concept Name
Brief definition paragraph explaining what this concept is and why it matters.
## Key characteristics
- Characteristic 1: Brief explanation
- Characteristic 2: Brief explanation
- Characteristic 3: Brief explanation
## How it works
Detailed explanation of mechanics, with diagrams if helpful.
## Related concepts
- [Related Concept 1](link) – Brief connection explanation
- [Related Concept 2](link) – Brief connection explanation
```
**Example (from Accounts documentation):**
> In banking terms, an Account represents a financial product, such as a checking account, savings account, or loan account.
---
### 2. Getting Started Guides
Helps users accomplish their first task with the product.
**Structure:**
```markdown
# Getting started with [Feature]
Brief intro explaining what users will accomplish.
## Prerequisites
- Requirement 1
- Requirement 2
## Step 1: First action
Explanation of what to do and why.
[Code example or screenshot]
## Step 2: Second action
Continue the workflow.
## Next steps
- [Advanced topic 1](link)
- [Advanced topic 2](link)
```
---
### 3. How-To Guides
Task-focused documentation for specific goals.
**Structure:**
```markdown
# How to [accomplish task]
Brief context on when and why you'd do this.
## Before you begin
Prerequisites or context needed.
## Steps
1. **Action name**: Description of what to do
2. **Action name**: Description of what to do
3. **Action name**: Description of what to do
## Verification
How to confirm success.
## Troubleshooting
Common issues and solutions.
```
---
### 4. Best Practices
Guidance on optimal usage patterns.
**Structure:**
```markdown
# Best practices for [topic]
Brief intro on why these practices matter.
## Practice 1: Name
- **Mistake:** What users commonly do wrong
- **Best practice:** What to do instead and why
## Practice 2: Name
- **Mistake:** Common error pattern
- **Best practice:** Correct approach
## Summary
Key takeaways in bullet form.
```
---
## Writing Patterns
### Lead with Value
Start every document with a clear statement of what the reader will learn or accomplish.
**Good:**
> This guide shows you how to create your first transaction in under 5 minutes.
**Avoid:**
> In this document, we will discuss the various aspects of transaction creation.
---
### Use Second Person ("You")
Address the reader directly.
**Good:**
> You can create as many accounts as your structure demands.
**Avoid:**
> Users can create as many accounts as their structure demands.
---
### Present Tense
Use present tense for current behavior.
**Good:**
> Midaz uses a microservices architecture.
**Avoid:**
> Midaz will use a microservices architecture.
---
### Action-Oriented Headings
Headings should indicate what the section covers or what users will do.
**Good:**
> ## Creating your first account
**Avoid:**
> ## Account creation process overview
---
### Short Paragraphs
Keep paragraphs to 2-3 sentences maximum. Use bullet points for lists.
**Good:**
> Each Account is linked to exactly one Asset type. Accounts are uniquely identified within a Ledger.
**Avoid:**
> Each Account is linked to exactly one Asset type, and accounts are uniquely identified within a Ledger, which tracks and consolidates all balances and operations for the organization.
---
## Visual Elements
### Info Boxes
Use for helpful tips or additional context.
```markdown
> **Tip:** You can use account aliases to make transactions more readable.
```
### Warning Boxes
Use for important cautions.
```markdown
> **Warning:** External accounts cannot be deleted or changed.
```
### Code Examples
Always include working examples for technical concepts.
```markdown
```json
{
"name": "Customer Account",
"assetCode": "BRL",
"type": "checking"
}
```
```
### Tables
Use for comparing options or showing structured data.
```markdown
| Option | When to Use |
|--------|-------------|
| Community | Developers, startups, experimentation |
| Enterprise | Production, compliance, dedicated support |
```
---
## Section Dividers
Use horizontal rules (`---`) to separate major sections. This improves scannability.
```markdown
## Section One
Content here.
---
## Section Two
Content here.
```
---
## Linking Patterns
### Internal Links
Link to related documentation when mentioning concepts.
**Good:**
> Each Account is linked to a single [Asset](link-to-assets), defining the type of value it holds.
### API Reference Links
Connect functional docs to API reference.
**Good:**
> You can manage your Accounts via [API](link) or through the [Console](link).
### Next Steps
End guides with clear next steps.
```markdown
## Next steps
- [Learn about Portfolios](link) – Group accounts for easier management
- [Create your first Transaction](link) – Move funds between accounts
```
---
## Quality Checklist
Before finishing functional documentation, verify:
- [ ] Leads with clear value statement
- [ ] Uses second person ("you")
- [ ] Uses present tense
- [ ] Headings are action-oriented (sentence case)
- [ ] Paragraphs are short (2-3 sentences)
- [ ] Includes working code examples
- [ ] Links to related documentation
- [ ] Ends with next steps
- [ ] Follows voice and tone guidelines