perstack.toml Configuration

# Global settings (optional)
model = "claude-3-5-sonnet-20241022"
temperature = 0.3
maxSteps = 50
maxRetries = 3
 
# Expert definitions
[experts."my-expert"]
version = "1.0.0"
description = "Brief description of what this expert does"
instruction = "Detailed instructions for the expert's behavior"
delegates = ["other-expert", "@org/another-expert"]
 
# Skill definitions
[experts."my-expert".skills.my-skill]
type = "mcpStdioSkill"
command = "npx"
args = ["-y", "some-mcp-server"]

# LLM model to use (optional)
model = "claude-3-5-sonnet-20241022"
 
# Generation temperature 0.0-1.0 (optional, default: 0.3)
temperature = 0.7
 
# Maximum execution steps (optional)
maxSteps = 100
 
# Maximum retries on error (optional, default: 10)
maxRetries = 5

[experts."product-analyzer"]
# Semantic version (optional, defaults to "1.0.0")
version = "2.1.0"
 
# Minimum required runtime version (optional)
minRuntimeVersion = "1.0.0"
 
# Brief description for registry and discovery (optional)
description = """
Analyzes product requirements and generates detailed specifications
with implementation recommendations.
"""
 
# Natural language instructions for the Expert (required)
instruction = """
You are a product analyst expert. Your role is to:
1. Break down product requirements into actionable items
2. Identify potential edge cases and risks
3. Suggest technical implementation approaches
4. Create clear acceptance criteria
 
Always prioritize user needs and technical feasibility.
"""

[experts."my-expert".skills.search]
type = "mcpStdioSkill"
 
# Brief description of the skill (optional)
description = "Web search capability"
 
# Natural language rules for using this skill (optional)
rule = """
Always search in English unless specified otherwise.
Prefer recent results from the last year.
Focus on authoritative sources.
"""
 
# Command to execute
command = "npx"
 
# Package name for npx (optional)
packageName = "exa-mcp-server"
 
# Command arguments (optional)
args = ["-y", "--verbose"]
 
# Required environment variables (optional)
requiredEnv = ["EXA_API_KEY"]
 
# Include only specific tools from the MCP server (optional)
pick = ["search", "find_similar"]
 
# Exclude specific tools (optional)
omit = ["debug_tools"]

[experts."my-expert".skills.api]
type = "mcpSseSkill"
 
description = "Connect to custom API server"
 
# SSE endpoint URL
endpoint = "https://api.example.com/mcp/sse"
 
# Optional: filter tools
pick = ["query", "update"]
omit = ["admin_tools"]

[experts."my-expert".skills.approval]
type = "interactiveSkill"
 
description = "Request human approval for actions"
 
rule = """
Use this when making significant changes or decisions
that require human oversight.
"""
 
# Define individual tools within the skill
[experts."my-expert".skills.approval.tools.request_approval]
description = "Request approval for a proposed action"
inputJsonSchema = """
{
  "type": "object",
  "properties": {
    "action": { "type": "string", "description": "Action requiring approval" },
    "reason": { "type": "string", "description": "Justification for the action" },
    "risk_level": { 
      "type": "string", 
      "enum": ["low", "medium", "high"],
      "description": "Assessed risk level"
    }
  },
  "required": ["action", "reason"]
}
"""

[experts."project-manager"]
delegates = [
  "requirement-analyzer",      # Local expert in same file
  "@perstack/code-generator",  # Registry expert
  "@my-org/custom-validator"   # Organization expert
]

# Global configuration
model = "claude-3-5-sonnet-20241022"
temperature = 0.3
maxSteps = 100
 
# Main research coordinator
[experts."@my-org/research-coordinator"]
version = "1.0.0"
description = "Coordinates comprehensive research projects"
 
instruction = """
You coordinate research by:
1. Breaking down research questions
2. Delegating to specialized researchers
3. Synthesizing findings
4. Producing comprehensive reports
"""
 
delegates = ["web-researcher", "data-analyst"]
 
[experts."@my-org/research-coordinator".skills.planner]
type = "mcpStdioSkill"
command = "npx"
packageName = "@my-org/research-planner"
rule = "Create detailed research plans with clear objectives"
 
# Web research specialist
[experts."web-researcher"]
version = "1.0.0"
description = "Performs targeted web research"
 
instruction = """
Search and analyze web content based on specific queries.
Focus on credible sources and recent information.
"""
 
[experts."web-researcher".skills.search]
type = "mcpStdioSkill"
command = "npx"
packageName = "exa-mcp-server"
requiredEnv = ["EXA_API_KEY"]
rule = "Prefer .edu, .gov, and established news sources"
 
[experts."web-researcher".skills.browse]
type = "mcpStdioSkill"
command = "uvx"
args = ["-y", "mcp-server-fetch"]
 
# Data analysis expert
[experts."data-analyst"]
version = "1.0.0"
description = "Analyzes data and generates insights"
 
instruction = """
Process data to find patterns and insights.
Create clear visualizations and summaries.
"""
 
[experts."data-analyst".skills.python]
type = "mcpStdioSkill"
command = "python"
args = ["-m", "mcp_server_python"]
rule = "Use pandas for data manipulation, matplotlib for visualization"

instruction = """
You are a code reviewer specializing in TypeScript.
 
Your process:
1. Check for logic errors and edge cases
2. Verify type safety
3. Assess performance implications
4. Suggest improvements
 
Focus on constructive feedback with examples.
"""

[experts."my-expert".skills.database]
rule = """
- Always use parameterized queries
- Limit results to 1000 unless specified
- Log all write operations
- Prefer read replicas for analytics
"""

version = "1.2.3"
# 1 = Major (breaking changes)
# 2 = Minor (new features)  
# 3 = Patch (bug fixes)

# ✅ Good: Focused expert
[experts."typescript-linter"]
description = "Performs TypeScript linting and style checks"
 
# ❌ Bad: Too broad
[experts."coding-assistant"]
description = "Helps with all programming tasks"

requiredEnv = ["API_KEY", "API_SECRET"]