tomevault-io Output Format Guide
All plugin outputs should be visually clear and beautiful. Choose the format that best fits the content.
EXECUTION INSTRUCTIONS
When generating output for any OAS plugin command, Claude MUST:
- Select appropriate format based on content type (see Format Selection below)
- Use consistent styling within a single output
- Keep width under 80 characters for terminal compatibility
- Use emojis sparingly - only for status indicators
- Add blank lines between sections for readability
This is a REFERENCE skill - use it to format outputs from other commands.
Format Selection
Content Type → Best Format
─────────────────────────────────────
Key-Value pairs → Table or Aligned
Process/Steps → Flow Diagram
Hierarchy/Structure → Tree
Before/After → Comparison
Status/Progress → Progress Bar
Summary → Box
List with status → Checklist
Timeline → Timeline
1. Tables (Structured Data)
For structured key-value or multi-column data:
┌──────────────┬─────────────────────────────────────┐
│ Item │ Content │
├──────────────┼─────────────────────────────────────┤
│ File │ src/api/user-api.ts │
│ Location │ getUserById() function (line 45-52) │
│ Reason │ Response type: email field added │
└──────────────┴─────────────────────────────────────┘
Simple aligned format (for fewer columns):
File: src/api/user-api.ts
Location: getUserById() function (line 45-52)
Reason: Response type: email field added
2. Flow Diagrams (Process/Steps)
Horizontal flow:
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Fetch │───▶│ Parse │───▶│ Diff │───▶│ Generate│
│ Spec │ │ Schema │ │ Compare │ │ Code │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
Vertical flow with details:
┌──────────────────────────────┐
│ 1. Fetch OpenAPI Spec │
│ GET /openapi.json │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ 2. Compare with Cache │
│ Hash: abc123 → def456 │
└──────────────┬───────────────┘
│
┌───────┴───────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ Changed │ │ No Change│
│ Continue │ │ Done │
└────┬─────┘ └──────────┘
│
▼
┌──────────────────────────────┐
│ 3. Generate Code │
└──────────────────────────────┘
Decision flow:
┌─────────────┐
│ Cache exists?│
└──────┬──────┘
│
┌────────────┼────────────┐
▼ │ ▼
[ Yes ] │ [ No ]
│ │ │
▼ │ ▼
┌─────────────────┐ │ ┌─────────────────┐
│ Compare hash │ │ │ Full fetch │
└────────┬────────┘ │ └────────┬────────┘
│ │ │
└─────────────┴─────────────┘
│
▼
┌─────────────┐
│ Output │
└─────────────┘
3. Tree Structure (Hierarchy)
File tree:
src/entities/user/
├── api/
│ ├── user-api.ts ← 8 functions
│ ├── user-api-paths.ts ← 8 paths
│ └── user-queries.ts ← 8 hooks
├── model/
│ └── user-types.ts ← 12 types
└── index.ts
Nested structure with status:
📦 API Coverage
│
├── ✅ user (100%)
│ ├── getUser
│ ├── updateUser
│ └── deleteUser
│
├── ⚠️ workspace (75%)
│ ├── ✅ getWorkspace
│ ├── ✅ createWorkspace
│ ├── ❌ inviteUser ← missing
│ └── ✅ deleteWorkspace
│
└── ❌ billing (0%)
├── ❌ getPlans
├── ❌ subscribe
└── ❌ cancelSubscription
4. Comparison (Diff)
Side-by-side diff:
┌─────────────────────────────┬─────────────────────────────┐
│ Before │ After │
├─────────────────────────────┼─────────────────────────────┤
│ interface User { │ interface User { │
│ id: string; │ id: string; │
│ name: string; │ name: string; │
│ │ + email: string; │
│ │ + avatar?: string; │
│ } │ } │
└─────────────────────────────┴─────────────────────────────┘
Inline diff:
GET /users/{id}
Response: UserResponse
+ email: string (added)
+ avatar?: string (added, optional)
~ name: string → string | null (changed to nullable)
- legacy_id: number (removed)
5. Progress & Status
Progress bar:
Syncing API endpoints...
user ████████████████████ 100% ✅
workspace ████████████░░░░░░░░ 60% ⏳
billing ░░░░░░░░░░░░░░░░░░░░ 0% ⏸️
Overall: ██████████████░░░░░░ 70% (21/30 endpoints)
Status summary:
╔═══════════════════════════════════════════════╗
║ Sync Complete ║
╠═══════════════════════════════════════════════╣
║ ✅ Generated: 24 files ║
║ ⚠️ Warnings: 3 (nullable handling) ║
║ ❌ Errors: 0 ║
║ ⏱️ Duration: 2.3s ║
╚═══════════════════════════════════════════════╝
6. Summary Box
Simple header:
═══════════════════════════════════════════════════
📊 API Diff Report
═══════════════════════════════════════════════════
Info box:
┌─────────────────────────────────────────────────┐
│ 💡 TIP │
│ │
│ Use --force to regenerate all endpoints, │
│ ignoring cache. │
└─────────────────────────────────────────────────┘
Warning box:
⚠️ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Breaking Changes Detected!
3 endpoints removed:
- DELETE /users/{id}/sessions
- GET /legacy/auth
- POST /v1/login
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
7. Checklist
Task list:
📋 Sync Checklist
[✓] Fetch OpenAPI spec
[✓] Parse endpoints (42 found)
[✓] Compare with existing code
[ ] Generate user-api.ts
[ ] Generate workspace-api.ts
[ ] Update type definitions
Validation result:
🔍 Validation Results
✅ PASS Type safety All types match spec
✅ PASS Path coverage 42/42 endpoints covered
⚠️ WARN Nullable handling 3 fields need attention
❌ FAIL Response format getUserById() returns wrong type
❌ FAIL Missing endpoint POST /users not implemented
8. Timeline
📅 Sync History
Jan 13, 10:30 ●───── Full sync (42 endpoints)
│
Jan 12, 15:22 ●───── Partial sync: +2 workspace endpoints
│
Jan 10, 09:15 ●───── Initial setup
│
Jan 08, 14:00 ○───── Failed: spec unreachable
9. Impact Analysis
═══════════════════════════════════════════════════════════════
🔍 Impact Analysis Report
═══════════════════════════════════════════════════════════════
Spec Change: GET /users/{id} response updated
+ email: string
+ preferences: UserPreferences
┌─────────────────────────────────────────────────────────────┐
│ Affected Files │
├───────────────────────────────┬─────────────────────────────┤
│ File │ Required Changes │
├───────────────────────────────┼─────────────────────────────┤
│ src/api/user-api.ts:45 │ Update return type │
│ src/types/user.ts:12 │ Add email, preferences │
│ src/hooks/useUser.ts:23 │ No change (auto-inferred) │
└───────────────────────────────┴─────────────────────────────┘
Code Changes Required:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 src/types/user.ts
interface User {
id: string;
name: string;
+ email: string; // ← Add
+ preferences: UserPreferences; // ← Add
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Next Steps:
1. Run /oas:sync --tag=user to auto-generate
2. Or manually update the files above
Character Reference
Box Drawing:
┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ │ ─
╔ ╗ ╚ ╝ ╠ ╣ ╦ ╩ ╬ ║ ═
Arrows:
→ ← ↑ ↓ ↔ ↕
▶ ◀ ▲ ▼
───▶ ◀─── │
▼
Progress:
█ ░ ▓ ▒
Status Icons:
✅ ❌ ⚠️ ⏳ ⏸️ 💡 📦 📋 🔍 📊 📁 🔌 📝 🏷️
Bullets:
• ○ ● ◦ ▪ ▫
Lines:
─ ━ ═ ┄ ┅ ┈ ┉
Best Practices
- Consistency: Use same style within one output
- Breathing room: Add blank lines between sections
- Alignment: Align columns for readability
- Icons sparingly: Don't overuse emojis
- Width: Keep under 80 chars for terminal compatibility
- Context-appropriate: Tables for data, flows for processes
Converted and distributed by TomeVault — claim your Tome and manage your conversions.