docs/gen3 draft for wrapped commands/tools

.cycodmdignore

@@ -1,2 +1,2 @@
-**/chat-history*.jsonl
-**/trajectory*.md
+**/*chat-history*.jsonl
+**/*trajectory*.md

docs/gen3/custom-tools-spec-draft-1-critique-1.md

@@ -0,0 +1,71 @@
+# Critique of CYCOD Custom Tools Specification - Draft 1
+
+## Overview
+
+The CYCOD Custom Tools Specification draft is comprehensive and well-structured. It clearly defines the purpose, implementation, and usage of the custom tools feature. Here's my detailed critique:
+
+## Strengths
+
+1. **Clear Structure**: The document follows a logical progression from conceptual overview to specific implementation details.
+
+2. **Comprehensive Examples**: The inclusion of various examples covering simple and complex use cases helps illustrate the concepts effectively.
+
+3. **Complete CLI Documentation**: The command-line interface is thoroughly documented with options and examples.
+
+4. **Security Integration**: The specification correctly integrates with CYCOD's existing security model for function calling.
+
+5. **Help Text**: Including draft help text is valuable for showing how the feature will be presented to users.
+
+## Areas for Improvement
+
+1. **Parameter Substitution Clarity**: 
+   - The spec uses curly braces `{PARAM}` for parameter substitution but doesn't explicitly state how this interacts with shell-specific syntax that might also use curly braces.
+   - Consider adding examples of escaping curly braces when they're part of the command syntax.
+
+2. **Boolean Parameter Handling**:
+   - In the "Complex Parameter Handling" example, there are comments about converting boolean values to command-line flags (`-i` for false, `-w` for true), but the mechanism for this conversion isn't specified.
+   - Consider explicitly defining how boolean parameters are transformed into command arguments.
+
+3. **Parameter Validation**:
+   - The specification doesn't address parameter validation behavior. Will there be any validation for parameter types (e.g., ensuring a number parameter contains a valid number)?
+   - Consider clarifying whether validation occurs or is left to the shell command execution.
+
+4. **Step Output Buffering**:
+   - For multi-step tools, there's no mention of potential memory considerations when capturing large outputs from steps.
+   - Consider addressing potential limitations or buffering strategies for large outputs.
+
+5. **Run Conditions**:
+   - The run-condition syntax (`"{step1.exit-code} == 0"`) implies complex condition evaluation, but the mechanism for this evaluation isn't specified.
+   - Consider clarifying how conditions are evaluated (simple string comparison vs. expression parsing).
+
+6. **Platform-Specific Behavior**:
+   - While the specification includes platform tags, it doesn't address how to handle platform-specific command variations within a single tool.
+   - Consider adding guidance for creating tools that work across platforms with different command syntax.
+
+7. **Integration with Function Calling**:
+   - The specification doesn't fully address how tools will appear in function calling schemas for LLMs.
+   - Consider adding details about the JSON Schema representation for LLM function calling.
+
+## Suggested Additions
+
+1. **Tool Testing**:
+   - Add guidance on testing custom tools before using them with LLMs.
+   - Consider a test command like `cycod tool test NAME [parameters]`.
+
+2. **Tool Sharing Mechanism**:
+   - Consider addressing how tools might be shared between users or teams beyond the scope system.
+
+3. **Environment Variable Support**:
+   - Add support for environment variables in tool definitions that would be set before command execution.
+
+4. **Tool Dependencies**:
+   - Consider adding a mechanism for tools to declare dependencies (e.g., required executables or other tools).
+
+5. **Tool Versioning**:
+   - Add support for tool versioning to track changes and compatibility.
+
+## Conclusion
+
+The CYCOD Custom Tools Specification provides a solid foundation for implementing this feature. With some clarifications and additions as suggested above, it will be a comprehensive guide for both implementation and user documentation.
+
+The multi-step tool support with output capturing and conditional execution is particularly powerful and sets this feature apart from simple command wrapping. The integration with CYCOD's existing scope and security models shows thoughtful design.

docs/gen3/custom-tools-spec-draft-1-critique-2.md

@@ -0,0 +1,92 @@
+# Critique of CYCOD Custom Tools Specification - Draft 1
+
+## Overall Assessment
+
+The CYCOD Custom Tools Specification is well-developed and provides a clear path for implementing a powerful feature. The specification demonstrates a good understanding of user needs and technical integration requirements.
+
+## Technical Considerations
+
+1. **Tool Output Handling**:
+   - The specification describes accessing step outputs via `{step-name.output}`, but doesn't address how large outputs are managed.
+   - Consider adding details about output truncation or streaming for memory-intensive operations.
+
+2. **Parameter Type Handling**:
+   - While parameter types (string, number, boolean, array) are defined, the specification doesn't detail how these types are translated to command-line arguments.
+   - For example, how are array parameters passed to commands? As space-separated values, comma-separated, or another format?
+
+3. **Execution Environment**:
+   - The specification mentions working directory but doesn't address other execution environment details like environment variables, user context, or resource limitations.
+   - Consider adding support for specifying environment variables in tool definitions.
+
+4. **Error Handling and Debugging**:
+   - The specification includes basic error handling (continue-on-error, run-condition) but lacks detailed error reporting mechanisms.
+   - Consider adding a verbose mode for tools that provides detailed execution information for debugging.
+
+5. **Security Considerations**:
+   - While the security tagging system is good, consider adding guidance on escaping shell metacharacters in parameter values to prevent injection attacks.
+   - Add explicit warnings about security implications of certain operations.
+
+## Usability Considerations
+
+1. **Tool Discovery**:
+   - The specification includes `tool list` but doesn't address searchability or categorization for discovering appropriate tools.
+   - Consider adding search capabilities like `cycod tool search KEYWORD`.
+
+2. **Parameter Documentation**:
+   - The parameter description field is good, but consider adding support for more detailed help text that explains parameter usage in context.
+   - Examples of valid values for parameters would be helpful.
+
+3. **Tool Composition**:
+   - While multi-step tools are supported, the specification doesn't address whether tools can invoke other tools.
+   - Consider adding support for tool composition or referencing other tools as steps.
+
+4. **Command-Line Usability**:
+   - The `tool add` command has many options that might be cumbersome to use in practice.
+   - Consider supporting an interactive mode or a file-based definition mode.
+
+5. **UI Considerations**:
+   - The specification focuses on CLI, but doesn't address potential UI representations for tools in graphical interfaces.
+   - Consider adding guidance on tool representation in UIs.
+
+## Documentation Suggestions
+
+1. **Introduction to Custom Tools**:
+   - Consider adding a more basic introduction that explains the concept for first-time users.
+   - Include a simple "Getting Started" guide with the most common use cases.
+
+2. **Best Practices Section**:
+   - Add guidelines for creating effective tools including naming conventions, parameter design, and error handling.
+   - Include advice on when to use a custom tool versus other CYCOD features.
+
+3. **Troubleshooting Guide**:
+   - Add a section on common issues and how to resolve them.
+   - Include examples of common errors and their solutions.
+
+4. **Migration Guide**:
+   - If users currently implement similar functionality through other means, provide guidance on migrating to custom tools.
+
+## Feature Enhancement Suggestions
+
+1. **Tool Templates**:
+   - Consider adding support for tool templates that provide starting points for common use cases.
+   - Example: `cycod tool create from-template github-api`.
+
+2. **Parameterized Default Values**:
+   - Allow default values to reference other parameters or environment values.
+   - Example: `default: "{REPO}-backup"` where `REPO` is another parameter.
+
+3. **Output Formatting Options**:
+   - Add support for output formatting directives to standardize tool outputs.
+   - Example: JSON, table, or plain text formatting options.
+
+4. **Input Validation Patterns**:
+   - Add support for regex or pattern validation of parameter inputs before execution.
+   - This would prevent invalid inputs from reaching the shell command.
+
+5. **Tool Aliasing**:
+   - Allow creating aliases for tools with preset parameter values.
+   - Example: `cycod tool alias create gh-my-repo github-repo-clone --OWNER=myusername`.
+
+## Conclusion
+
+The CYCOD Custom Tools Specification provides a strong foundation for implementing a powerful feature. With some refinements to address the considerations above, it will be a comprehensive and user-friendly addition to the CYCOD ecosystem.

docs/gen3/custom-tools-spec-draft-1-critique-3.md

@@ -0,0 +1,103 @@
+# Critique of CYCOD Custom Tools Specification - Draft 1
+
+## Strengths and Positive Aspects
+
+The CYCOD Custom Tools Specification is well-structured and comprehensive. It provides a clear vision for implementing custom tools that can significantly enhance CYCOD's functionality. Key strengths include:
+
+1. **Comprehensive Schema**: The YAML schema is well-defined and covers essential aspects including command execution, parameters, error handling, and metadata.
+
+2. **Multi-step Tools**: The support for multi-step tools with output capturing and conditional execution is a powerful feature that enables complex workflows.
+
+3. **Parameter System**: The parameter definition system is robust, supporting types, descriptions, required flags, and default values.
+
+4. **Security Integration**: The specification integrates well with CYCOD's existing security model through tagging and auto-approve mechanisms.
+
+5. **Clear Documentation**: The help text examples are thorough and follow the existing CYCOD conventions.
+
+## Areas for Refinement
+
+Despite its strengths, several aspects of the specification could benefit from refinement:
+
+### 1. Command Execution and Shell Integration
+
+- **Shell Escaping**: The specification doesn't address how special characters in parameters are escaped for shell execution.
+- **Command Output Capture**: The mechanism for capturing and processing command output (especially for error handling) could be more clearly defined.
+- **Interactive Commands**: There's no mention of how tools might handle interactive commands that expect user input.
+
+### 2. Parameter and Value Handling
+
+- **Complex Parameter Types**: While basic types are covered, there's no mechanism for handling more complex types like JSON objects or structured data.
+- **Parameter Transformation**: The specification doesn't detail how parameters might be transformed before substitution (e.g., encoding URLs, formatting dates).
+- **Dynamic Default Values**: Consider supporting dynamic defaults that could be computed at runtime.
+
+### 3. Technical Implementation Considerations
+
+- **Performance Impact**: The specification doesn't address potential performance considerations for multi-step tools or large output capturing.
+- **Error Propagation**: More detail on how errors propagate through multi-step tools would be beneficial.
+- **Resource Management**: There's no discussion of resource constraints or cleanup for long-running tools.
+
+### 4. User Experience Enhancements
+
+- **Tool Categories**: Beyond tags, consider a more structured categorization system for better organization.
+- **Tool Discoverability**: Add mechanisms for discovering relevant tools beyond simple listing.
+- **Example Parameter Values**: The schema could include example values for parameters to aid users.
+- **Input Validation**: Consider adding parameter validation rules to prevent common errors.
+
+### 5. Advanced Features to Consider
+
+- **Tool Composition**: Allow tools to reference and execute other tools as part of their workflow.
+- **Template Support**: Add support for tool templates to simplify creation of similar tools.
+- **Version Control**: Include tool versioning to track changes and manage dependencies.
+- **Parameterized Scripts**: Consider supporting script templates with more advanced parameter substitution.
+- **Tool Testing Framework**: Add a mechanism for testing tools with sample inputs and expected outputs.
+
+## Specific Recommendations
+
+1. **Shell Handling Clarity**:
+   ```yaml
+   shell-options:
+     escape-special-chars: true  # Whether to escape special shell characters
+     inherit-environment: true   # Whether to inherit environment variables
+   ```
+
+2. **Enhanced Parameter Validation**:
+   ```yaml
+   parameters:
+     URL:
+       type: string
+       description: Website URL
+       required: true
+       pattern: "^https?://.+"  # Regex validation pattern
+       examples: ["https://example.com"]
+   ```
+
+3. **Tool Categories Structure**:
+   ```yaml
+   categories:
+     primary: networking
+     secondary: [diagnostics, web]
+   security-category: read  # Explicit security categorization
+   ```
+
+4. **Resource Controls**:
+   ```yaml
+   resources:
+     timeout: 60000
+     max-output-size: 10MB
+     cleanup-script: "rm -rf {temp-files}"
+   ```
+
+5. **Tool Dependencies**:
+   ```yaml
+   dependencies:
+     tools: [git-clone, jq-parse]
+     executables: [curl, jq]
+     minimum-versions:
+       curl: "7.0.0"
+   ```
+
+## Conclusion
+
+The CYCOD Custom Tools Specification provides an excellent foundation for implementing a powerful feature that will significantly enhance CYCOD's capabilities. With refinements addressing the points above, it will be even more robust, flexible, and user-friendly.
+
+The multi-step tool support with conditional execution is particularly valuable and sets this feature apart from simple command wrappers. By addressing the technical considerations and adding some advanced features, this specification could evolve into a truly exceptional system for extending CYCOD's functionality.