syntaxis/shared/templates/TEMPLATE_README.md

Tools Templates Reference

Complete documentation of all available templates for creating new Tools in the Tools ecosystem.

Quick Overview

shared/templates/
├── rust-core/              # Rust library templates (Tier 1)
├── rust-cli/               # Rust CLI templates (Tier 3)
├── rust-api/               # Rust REST API templates (Tier 2)
├── nushell-tool/           # NuShell complete tool
├── documentation/          # Documentation templates
└── TEMPLATE_README.md      # This file

Rust Core Library Templates (rust-core/)

Purpose

Create the core library (Tier 1) - reusable business logic without UI/API.

Files Included

1. Cargo.toml.template

Purpose: Workspace and dependencies configuration

When to use:

• Creating crates/tool-core/Cargo.toml
• First file to copy from template

Key content:

• Workspace version inheritance
• tools-shared dependency
• serde, tokio, uuid, chrono dependencies
• Forbid unsafe code
• Clippy warnings configuration

Customization:

# Variables to replace
{{TOOL_NAME}}           → Your tool name (e.g., tracking-manager)
{{tool_name_kebab}}     → kebab-case (e.g., tracking-manager)

# Example:
{{TOOL_NAME}}-core becomes tracking-manager-core
lib name becomes tracking_manager_core

2. lib.rs.template

Purpose: Main library entry point with module structure

When to use:

• Creating crates/tool-core/src/lib.rs
• Second file to copy and customize

Key content:

• Module declarations (error, types, handlers)
• Public API re-exports
• Documentation with examples
• Feature descriptions
• VERSION constant
• Unit tests

Customization:

// Update these sections:
//! {{TOOL_NAME}} Core Library       → Your tool description
//! A production-ready library for [description of what this tool does]

// Update Features:
//! - [Feature 1]
//! - [Feature 2]
//! - [Feature 3]

// Update Quick Start example:
pub use {{TOOL_NAME}}_core::{{MainType}};

3. error.rs.template

Purpose: Canonical error struct pattern following Microsoft Pragmatic Rust Guidelines

When to use:

• Creating crates/tool-core/src/error.rs
• Defines all error types for your tool

Key content:

• {{ToolName}}Error struct with context and backtrace
• {{ToolName}}ErrorKind enum with error variants
• Proper Display and Error trait implementations
• Backtrace support for debugging
• Source chain for error context

Error Variants (customize for your domain):

#[derive(Debug)]
#[non_exhaustive]
pub enum {{ToolName}}ErrorKind {
    ConfigError(String),       // Configuration issues
    IoError(String),           // File I/O errors
    ValidationError(String),   // Input validation
    DatabaseError(String),     // Database operations
    Unknown(String),           // Catch-all
}

Adding custom variant:

// 1. Add to enum
CustomError(String),

// 2. Add to Display impl
Self::CustomError(msg) => write!(f, "Custom error: {}", msg),

// 3. Add test
#[test]
fn test_custom_error() { ... }

Customization: Replace {{ToolName}} with your tool name (CamelCase)

4. src/types.rs.template

Purpose: Domain types and data structures

When to use:

• Creating crates/tool-core/src/types.rs
• Defines the primary domain type ({{MainType}})

Key content:

• {{MainType}} struct with standard fields
• UUID-based identification
• Timestamp tracking (created_at, updated_at)
• Serialization support (serde)
• Builder-like mutation methods
• Metadata field for extensibility
• Comprehensive tests

Standard Fields (in template):

pub id: String,                    // UUID v4
pub name: String,                  // Display name
pub description: String,           // Description
pub metadata: serde_json::Value,   // Extensibility
pub created_at: DateTime<Utc>,     // Creation time
pub updated_at: DateTime<Utc>,     // Last modified

Customization:

// 1. Add domain-specific fields:
pub status: ItemStatus,
pub priority: u8,
pub tags: Vec<String>,

// 2. Add domain-specific methods:
pub fn publish(&mut self) { ... }
pub fn archive(&mut self) { ... }

// 3. Add domain-specific tests:
#[test]
fn test_publish() { ... }

5. src/handlers/mod.rs.template

Purpose: Handlers module structure and organization

When to use:

• Creating crates/tool-core/src/handlers/mod.rs
• Organizes business logic layer

Key content:

• Module declarations (service)
• Public API exports
• Re-export pattern for clean API

Customization:

// Add more modules as needed:
pub mod service;
pub mod validators;  // Add validation logic
pub mod processors;  // Add processing logic

pub use service::{{MainType}}Service;
pub use validators::*;
pub use processors::*;

6. src/handlers/service.rs.template

Purpose: Service layer with CRUD operations

When to use:

• Creating crates/tool-core/src/handlers/service.rs
• Main business logic implementation

Key content:

• {{MainType}}Service struct with in-memory storage
• CRUD operations: create, get, list, update, delete
• Async/await with tokio
• Proper error handling
• 7+ comprehensive tests

Standard Operations:

pub async fn create(&self, name, description) -> Result<{{MainType}}>
pub async fn get(&self, id) -> Result<{{MainType}}>
pub async fn list(&self) -> Result<Vec<{{MainType}}>
pub async fn update(&self, id, name, description) -> Result<{{MainType}}>
pub async fn delete(&self, id) -> Result<()>

Customization:

1. Replace in-memory HashMap with persistent storage (SQLite, PostgreSQL)
2. Add domain-specific operations
3. Implement search, filtering, sorting
4. Add transaction support
5. Extend tests for new features

Storage Options:

• In-memory (template default) - for dev/testing
• SQLite (recommended) - for single-user
• PostgreSQL - for production/multi-user
• SurrealDB - for advanced features

---

Rust CLI Template (rust-cli/)

Purpose

Create the CLI layer (Tier 3) - user-friendly command-line interface.

Files Included

main.rs.template

Purpose: Complete CLI entry point with command parsing and configuration discovery

When to use:

• Creating crates/tool-cli/src/main.rs
• Provides user interface to core library

Key content:

• clap CLI parser with derive macros
• Configuration discovery using tools-shared
• Verbose logging support
• Help text with configuration search order
• Example subcommands (list, summary, create, version)
• Proper error handling

Subcommands (customize for your domain):

Commands::List { filter, limit } → List items with optional filtering
Commands::Summary { group_by }  → Show statistics
Commands::Create { name, description } → Create new item
Commands::Version               → Show version

Key Features:

// Configuration discovery (REQUIRED for all Rust CLIs):
let config_path = find_config_path("tool-name.toml")
    .unwrap_or_else(|| PathBuf::from(".project/tool-name.toml"));

// Help text with search order (REQUIRED):
#[command(long_about = r#"TOOL_NAME

CONFIGURATION SEARCH:
  Looks for config in order (uses first found):

  1. .project/tool-name.toml
  2. .vapora/tool-name.toml
  3. .coder/tool-name.toml
  4. ./tool-name.toml
"#)]

// Logging support:
let log_level = if cli.verbose { "debug" } else { "info" };

Customization:

1. Add domain-specific subcommands
2. Implement command handlers that use core service
3. Add output formatting (JSON, table, etc.)
4. Add configuration loading and validation
5. Add more options and flags as needed

Important Requirements:

• ✅ MUST use tools-shared for config discovery
• ✅ MUST have help text with configuration search order
• ✅ MUST include verbose logging
• ✅ MUST handle errors gracefully
• ✅ MUST show version from Cargo.toml

---

Rust API Template (rust-api/)

Purpose

Create REST API layer (Tier 2, optional) - HTTP server interface.

Files Included

Cargo.toml.template

Purpose: API server dependencies

Key dependencies:

• axum - Web framework
• tokio - Async runtime
• serde/serde_json - Serialization
• tracing - Structured logging

main.rs.template

Purpose: Complete REST API server

When to use:

• Creating crates/tool-api/src/main.rs
• Provides HTTP interface to core library

Key content:

• axum router with CRUD routes
• Proper HTTP status codes
• JSON request/response
• Error handling
• Health check endpoint
• State management with Arc

Standard Endpoints (customize for your domain):

GET  /health              → Health check (200 OK)
GET  /{{main_type_plural}}         → List all items
GET  /{{main_type_plural}}/:id     → Get specific item
POST /{{main_type_plural}}         → Create new item
PUT  /{{main_type_plural}}/:id     → Update item
DELETE /{{main_type_plural}}/:id   → Delete item

Customization:

1. Add domain-specific endpoints
2. Add request/response validation
3. Add filtering, sorting, pagination
4. Add authentication/authorization
5. Add error response formatting
6. Add structured logging

---

NuShell Tool Template (nushell-tool/)

Purpose

Create complete NuShell-based tool (single-file implementation).

Files Included

tool.nu.template

Purpose: Complete NuShell tool with configuration discovery

When to use:

• Creating scripts/tool-id.nu
• For simple utilities or scripts
• Alternative to Rust for lightweight tools

Key content:

• Configuration discovery (same search order as Rust)
• Standard functions: list, create, summary, validate config
• Main entry point with help
• Proper error handling with logging

Customization:

1. Add domain-specific functions
2. Implement actual logic instead of placeholders
3. Add validation functions
4. Add data persistence if needed
5. Add comprehensive documentation in function comments

---

Documentation Templates (documentation/)

Purpose

Provide consistent structure for README, QUICKSTART, and other documentation.

Files Included

README.md.template

Purpose: Complete feature reference documentation

Sections:

1. Title & Description - What is this tool?
2. Features - List 5-10 key features with descriptions
3. Architecture - Explain 3-tier structure
4. Installation - Step-by-step setup
5. Configuration - Configuration discovery section (REQUIRED)
6. CLI Commands - Reference for all commands
7. API Endpoints - If REST API included
8. Examples - Real-world usage examples
9. Troubleshooting - Common problems and solutions
10. Development - How to extend/contribute

Required Sections (don't skip):

• Configuration discovery with search order
• Installation from source
• Example usage

QUICKSTART.md.template

Purpose: 5-10 minute setup guide

Sections:

1. Installation - Fastest setup path
2. Basic Usage - Minimal working example
3. Configuration - Quick config setup
4. First Command - "Hello World" equivalent
5. Next Steps - Links to full documentation

Important: Must be doable in 5-10 minutes end-to-end

architecture.md.template

Purpose: Detailed system design documentation

Sections:

1. Overview - High-level description
2. 3-Tier Architecture - Explain each tier
3. Data Flow - How data moves through system
4. Component Diagram - ASCII or link to diagram
5. Module Organization - Directory structure
6. Error Handling - How errors propagate
7. Configuration - Configuration system explanation
8. Extension Points - How to extend tool

configuration.md.template

Purpose: Configuration system documentation

Sections:

1. Configuration Files - TOML structure
2. Search Order - Where tool looks for config
3. Environment Variables - ENV var support
4. Default Values - What defaults are used
5. Validation - Config validation rules
6. Examples - Real config examples
7. Troubleshooting - Config problems

examples/config.toml.template

Purpose: Annotated configuration example

Content:

• Complete, valid TOML configuration
• Comments explaining each section
• All available options documented
• Ready to copy and modify

Structure:

# Section 1: Main settings
[tool_name]
setting1 = "value1"
setting2 = 42

# Section 2: Advanced options
[tool_name.advanced]
feature_flag = true

# Section 3: Database
[database]
type = "sqlite"
path = ".project/tool.db"

---

Template Variable Reference

Standard Variables (Use in ALL templates)

Variable	Type	Example	Where Used
{{TOOL_NAME}}	Module name	TrackingManager	error.rs, lib.rs, help text
{{ToolName}}	CamelCase type	TrackingManager	error.rs (ErrorKind, Error structs)
{{tool_name_kebab}}	Command name	tracking-manager	main.rs, config file names, commands
{{MainType}}	Domain type	TrackingItem	types.rs (struct name), service.rs
{{main_type_plural}}	Plural	items	API routes, help text
{{SHORT_DESCRIPTION}}	One-liner	Unified change tracking	Help text, README

Replacement Examples

For a "Blog" tool:

{{TOOL_NAME}}           → Blog
{{ToolName}}            → Blog
{{tool_name_kebab}}     → blog
{{MainType}}            → BlogPost
{{main_type_plural}}    → posts
{{SHORT_DESCRIPTION}}   → Create and manage blog posts

For "Analytics Tool":

{{TOOL_NAME}}           → AnalyticsTool
{{ToolName}}            → AnalyticsTool
{{tool_name_kebab}}     → analytics-tool
{{MainType}}            → AnalyticsEvent
{{main_type_plural}}    → events
{{SHORT_DESCRIPTION}}   → Collect and analyze usage metrics

---

How to Use Templates

Quick Start (5 minutes)

1. Copy template to your project:

   cp /Users/Akasha/Tools/shared/templates/rust-core/lib.rs.template \
      crates/my-tool-core/src/lib.rs
   

2. Replace variables (find & replace):

   # Use your editor's find & replace
   {{TOOL_NAME}}        → MyTool
   {{ToolName}}         → MyTool
   {{tool_name_kebab}}  → my-tool
   {{MainType}}         → MyItem
   

3. Customize for your domain:

   • Add domain-specific fields to types.rs
   • Implement business logic in service.rs
   • Add domain-specific commands to CLI

4. Test:

   cargo check
   cargo test
   

Detailed Process

1. Read the template - Understand what it does
2. Review variables - See what needs replacement
3. Copy to project - Use exact filename from template
4. Replace all variables - Use find & replace systematically
5. Customize content - Add domain-specific logic
6. Add tests - Extend test coverage
7. Verify compilation - cargo check && cargo test
8. Documentation - Update doc comments
9. Quality check - cargo clippy && cargo fmt
10. Commit - Save your work

---

Template Quality Guarantees

All templates in this directory are:

• ✅ Production-ready code
• ✅ Follow Microsoft Pragmatic Rust Guidelines
• ✅ No unsafe code
• ✅ Comprehensive tests included
• ✅ 100% API documented
• ✅ Properly error handled
• ✅ Compiled and verified
• ✅ Integrated with tools-shared (Rust)

---

Testing Templates

Before using a template in your project:

# Verify template compiles and runs tests
cd /Users/Akasha/Tools/shared/templates/rust-core
cargo test --template  # (if implemented)

---

Common Customizations

Add a new error variant:

In error.rs:

pub enum {{ToolName}}ErrorKind {
    // ... existing
    NetworkError(String),  // ← Add this
}

impl fmt::Display for {{ToolName}}ErrorKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            // ... existing
            Self::NetworkError(msg) => write!(f, "Network error: {}", msg),
        }
    }
}

Add a new service method:

In handlers/service.rs:

impl {{MainType}}Service {
    pub async fn search(&self, query: &str) -> Result<Vec<{{MainType}}>> {
        let items = self.items.lock().await;
        Ok(items.values()
            .filter(|item| item.name.contains(query))
            .cloned()
            .collect())
    }
}

Add a new CLI command:

In main.rs:

#[derive(Subcommand)]
enum Commands {
    // ... existing
    Search {
        query: String,
    },
}

match cli.command {
    Commands::Search { query } => {
        println!("Searching for: {}", query);
    }
}

---

Next Steps

1. Choose a template - Decide Rust vs NuShell
2. Copy files - Copy from shared/templates/ to your project
3. Replace variables - Systematically replace all {{VARIABLE}}
4. Customize - Add your domain logic
5. Test - cargo test --workspace
6. Document - Fill in your specific details
7. Validate - Run /validate-tool command
8. Integrate - Add to Tools ecosystem

---

Reference

• Complete Guideline: /Users/Akasha/Tools/NEW_TOOL_GUIDELINE.md
• Tool Creator Skill: .claude/skills/new-tool-creator.md
• Template Usage Skill: .claude/skills/template-usage.md
• New Tool Command: /new-tool
• Example Tools: tracking-manager, doc-syntaxis, presentation-generator