@maincode-ai/matilda-code 0.21.13 → 0.22.0

package/bundled/mainy/docs/features/sub-agents.md

@@ -1,737 +0,0 @@
-# Subagents
-
-Subagents are specialized AI assistants that handle specific types of tasks within Matilda Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors.
-
-## What are Subagents?
-
-Subagents are independent AI assistants that:
-
-- **Specialize in specific tasks** - Each Subagent is configured with a focused system prompt for particular types of work
-- **Have separate context** - They maintain their own conversation history, separate from your main chat
-- **Use controlled tools** - You can configure which tools each Subagent has access to
-- **Work autonomously** - Once given a task, they work independently until completion or failure
-- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
-
-## Fork Subagent
-
-In addition to named subagents, Matilda Code supports **forking** — selected explicitly with `subagent_type: "fork"` (available in interactive sessions). A fork inherits the parent's full conversation context and runs detached in the background. Omitting `subagent_type` does **not** fork; it launches the general-purpose subagent, which runs to completion and returns its result inline.
-
-### How Fork Differs from Named Subagents
-
-|               | Named Subagent                    | Fork Subagent                                         |
-| ------------- | --------------------------------- | ----------------------------------------------------- |
-| Context       | Starts fresh, no parent history   | Inherits parent's full conversation history           |
-| System prompt | Uses its own configured prompt    | Uses parent's exact system prompt (for cache sharing) |
-| Execution     | Blocks the parent until done      | Runs in background, parent continues immediately      |
-| Use case      | Specialized tasks (testing, docs) | Parallel tasks that need the current context          |
-
-### When Fork is Used
-
-The AI automatically uses fork when it needs to:
-
-- Run multiple research tasks in parallel (e.g., "investigate module A, B, and C")
-- Perform background work while continuing the main conversation
-- Delegate tasks that require understanding of the current conversation context
-
-### Prompt Cache Sharing
-
-All forks share the parent's exact API request prefix (system prompt, tools, conversation history), enabling Matilda-compatible prompt cache hits. When 3 forks run in parallel, the shared prefix is cached once and reused — saving 80%+ token costs compared to independent subagents.
-
-### Recursive Fork Prevention
-
-Fork children cannot create further forks. This is enforced at runtime — if a fork attempts to spawn another fork, it receives an error instructing it to execute tasks directly.
-
-### Current Limitations
-
-- **No result feedback**: Fork results are reflected in the UI progress display but are not automatically fed back into the main conversation. The parent AI sees a placeholder message and cannot act on the fork's output.
-- **No worktree isolation**: Forks share the parent's working directory. Concurrent file modifications from multiple forks may conflict.
-
-## Key Benefits
-
-- **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.)
-- **Context Isolation**: Keep specialized work separate from your main conversation
-- **Context Inheritance**: Fork subagents inherit the full conversation for context-heavy parallel tasks
-- **Prompt Cache Sharing**: Fork subagents share the parent's cache prefix, reducing token costs
-- **Reusability**: Save and reuse agent configurations across projects and sessions
-- **Controlled Access**: Limit which tools each agent can use for security and focus
-- **Progress Visibility**: Monitor agent execution with real-time progress updates
-
-## How Subagents Work
-
-1. **Configuration**: You create Subagents configurations that define their behavior, tools, and system prompts
-2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents — or fork itself (`subagent_type: "fork"`) when it wants to inherit the full conversation context and discard the intermediate output
-3. **Execution**: Subagents work independently, using their configured tools to complete tasks
-4. **Results**: They return results and execution summaries back to the main conversation
-
-## Getting Started
-
-### Quick Start
-
-1. **Create your first Subagent**:
-
-   `/agents create`
-
-   Follow the guided wizard to create a specialized agent.
-
-2. **Manage existing agents**:
-
-   `/agents manage`
-
-   View and manage your configured Subagents.
-
-3. **Use Subagents automatically**: Simply ask the main AI to perform tasks that match your Subagents' specializations. The AI will automatically delegate appropriate work.
-
-### Example Usage
-
-```
-User: "Please write comprehensive tests for the authentication module"
-AI: I'll delegate this to your testing specialist Subagents.
-[Delegates to "testing-expert" Subagents]
-[Shows real-time progress of test creation]
-[Returns with completed test files and execution summary]`
-```
-
-## Management
-
-### CLI Commands
-
-Subagents are managed through the `/agents` slash command and its subcommands:
-
-**Usage:**：`/agents create`。Creates a new Subagent through a guided step wizard.
-
-**Usage:**：`/agents manage`。Opens an interactive management dialog for viewing and managing existing Subagents.
-
-### Storage Locations
-
-Subagents are stored as Markdown files in multiple locations:
-
-- **Project-level**: `.matilda/agents/` (highest precedence)
-- **User-level**: `~/.matilda/agents/` (fallback)
-- **Extension-level**: Provided by installed extensions
-
-This allows you to have project-specific agents, personal agents that work across all projects, and extension-provided agents that add specialized capabilities.
-
-### Extension Subagents
-
-Extensions can provide custom subagents that become available when the extension is enabled. These agents are stored in the extension's `agents/` directory and follow the same format as personal and project agents.
-
-Extension subagents:
-
-- Are automatically discovered when the extension is enabled
-- Appear in the `/agents manage` dialog under "Extension Agents" section
-- Cannot be edited directly (edit the extension source instead)
-- Follow the same configuration format as user-defined agents
-
-To see which extensions provide subagents, check the extension's `matilda-extension.json` file for an `agents` field.
-
-### File Format
-
-Subagents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor.
-
-#### Basic Structure
-
-```
----
-name: agent-name
-description: Brief description of when and how to use this agent
-model: inherit # Optional: inherit, fast, modelId, or authType:modelId
-approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo, bubble
-tools:         # Optional: allowlist of tools
-  - tool1
-  - tool2
-disallowedTools: # Optional: blocklist of tools
-  - tool3
----
-
-System prompt content goes here.
-Multiple paragraphs are supported.
-```
-
-#### Model Selection
-
-Use the optional `model` frontmatter field to control which model a subagent uses:
-
-- `inherit`: Use the same model as the main conversation.
-- Omit the field: Same as `inherit`.
-- `fast`: Use the configured `fastModel`. If no valid fast model is configured,
-  the subagent falls back to `inherit`.
-- `glm-5`: Use that model ID. Matilda Code first checks the main conversation's
-  auth type; if the model is not available there, it can resolve the model from
-  another configured provider.
-- `openai:gpt-4o`: Use an explicit provider and model ID. This is useful when a
-  subagent should run on a model registered under a different auth type from the
-  main conversation.
-
-For example:
-
-```
----
-name: fast-reviewer
-description: Reviews small diffs with the configured fast model
-model: fast
-tools:
-  - read_file
-  - grep_search
----
-```
-
-```
----
-name: openai-researcher
-description: Uses an OpenAI-compatible provider for research tasks
-model: openai:gpt-4o
-tools:
-  - read_file
-  - grep_search
-  - glob
----
-```
-
-The `fast` selector uses the same `fastModel` setting configured in
-`settings.json` or with `/model --fast`. That setting may itself refer to a
-model under another configured auth type, such as `openai:deepseek-v4-flash`.
-When the selector resolves to another auth type, Matilda Code creates a dedicated
-runtime provider for that subagent request and sends the provider only the bare
-model ID.
-
-#### Permission Mode
-
-Use the optional `approvalMode` frontmatter field to control how a subagent's tool calls are approved. Valid values:
-
-- `default`: Tools require interactive approval (same as the main session default)
-- `plan`: Analyze-only mode — the agent plans but does not execute changes
-- `auto-edit`: Tools are auto-approved without prompting (recommended for most agents)
-- `yolo`: All tools auto-approved, including potentially destructive ones
-- `bubble`: Background-agent tool approvals are surfaced in the parent session
-
-If you omit this field, the subagent's permission mode is determined automatically:
-
-- If the parent session is in **yolo** or **auto-edit** mode, the subagent inherits that mode. A permissive parent stays permissive.
-- If the parent session is in **plan** mode, the subagent stays in plan mode. An analyze-only session cannot mutate files through a delegated agent.
-- If the parent session is in **default** mode (in a trusted folder), the subagent gets **auto-edit** so it can work autonomously.
-
-When you do set `approvalMode`, the parent's permissive modes still take priority. For example, if the parent is in yolo mode, a subagent with `approvalMode: plan` will still run in yolo mode.
-
-```
----
-name: cautious-reviewer
-description: Reviews code without making changes
-approvalMode: plan
-tools:
-  - read_file
-  - grep_search
-  - glob
----
-
-You are a code reviewer. Analyze the code and report findings.
-Do not modify any files.
-```
-
-#### Tool Configuration
-
-Use `tools` and `disallowedTools` to control which tools a subagent can access.
-
-**`tools` (allowlist):** When specified, the subagent can only use the listed tools. When omitted, the subagent inherits all available tools from the parent session.
-
-```
----
-name: reader
-description: Read-only agent for code exploration
-tools:
-  - read_file
-  - grep_search
-  - glob
-  - list_directory
----
-```
-
-**`disallowedTools` (blocklist):** When specified, the listed tools are removed from the subagent's tool pool. This is useful when you want "everything except X" without listing every permitted tool.
-
-```
----
-name: safe-worker
-description: Agent that cannot modify files
-disallowedTools:
-  - write_file
-  - edit
-  - run_shell_command
----
-```
-
-If both `tools` and `disallowedTools` are set, the allowlist is applied first, then the blocklist removes from that set.
-
-**MCP tools** follow the same rules. If a subagent has no `tools` list, it inherits all MCP tools from the parent session. If a subagent has an explicit `tools` list, it only gets MCP tools that are explicitly named in that list.
-
-The `disallowedTools` field supports MCP server-level patterns:
-
-- `mcp__server__tool_name` — blocks a specific MCP tool
-- `mcp__server` — blocks all tools from that MCP server
-
-```
----
-name: no-slack
-description: Agent without Slack access
-disallowedTools:
-  - mcp__slack
----
-```
-
-#### Claude Code Compatibility Fields
-
-Matilda Code accepts the Claude Code 2.1.168 frontmatter fields below so you
-can drop a CC agent file into `.matilda/agents/` and have the supported fields
-parse identically. Optional fields with invalid values are silently dropped
-at parse time rather than rejected — the same lenient posture CC uses.
-
-| Field            | Type             | Notes                                                                                                                                                                                                                                                                            |
-| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `permissionMode` | enum string      | `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`. Mapped to `approvalMode` at parse time; when both are set, the explicit `approvalMode` wins.                                                                                                           |
-| `maxTurns`       | positive integer | Caps the agent's turn budget. Wired into `runConfig.max_turns` at runtime; when both are set, the top-level field wins. The legacy nested value is pruned from the on-disk file on save to avoid two sources of truth.                                                           |
-| `color`          | enum string      | Display color. Allowlist: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (mirrors CC's `_Y`). The legacy matilda sentinel `auto` is preserved for backward compatibility. Other values are silently dropped on parse.                                      |
-| `mcpServers`     | record of specs  | Per-agent MCP server overrides. Merged with the session-level MCP server set when the agent spawns; on key collision the agent's spec wins (matching CC's `scope: 'agent'` semantics). Malformed entries are dropped per-key with a warning rather than failing the whole agent. |
-| `hooks`          | record of arrays | Per-agent hooks. Keys are CC hook event names (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, …); values are arrays of `{ matcher?, hooks: [...] }` definitions in the same shape as `settings.json`'s `hooks` field. Registered while the agent runs, removed when it stops.  |
-
-Example with all of the above:
-
-```
----
-name: rigorous-reviewer
-description: Deep code review with a turn cap
-permissionMode: plan
-maxTurns: 50
-color: cyan
-tools:
-  - read_file
-  - grep_search
-  - glob
-mcpServers:
-  filesystem:
-    type: stdio
-    command: node
-    args: [/usr/local/lib/mcp-fs/server.js]
-hooks:
-  PreToolUse:
-    - matcher: Bash
-      hooks:
-        - type: command
-          command: echo "review-agent about to run a shell command"
----
-
-You are a code reviewer. Analyze the code thoroughly and report findings
-ordered by severity.
-```
-
-The remaining CC frontmatter fields — `effort`, `skills`, `initialPrompt`,
-`memory`, `isolation` — are documented in the declarative-agent design doc
-and land in follow-up PRs once the prerequisite infrastructure exists
-(`effort` needs a model-layer parameter; `memory` needs a scoped memory
-subsystem; `--agent` CLI flag enables `initialPrompt`; etc.).
-
-> **`hooks` v1 limitation.** While a subagent declaring `hooks` is running,
-> its hook entries fire for every matching event in the session, not only
-> for that subagent's own tool calls. If two subagents with different
-> per-agent hook sets run concurrently, both sets fire for both agents.
-> Per-agent scope filtering at hook-firing time is left to a follow-up;
-> for v1, prefer per-agent hooks that are safe to fire globally for the
-> duration of the agent's run (e.g. logging) over hooks that mutate
-> behavior.
-
-#### Example Usage
-
-```
----
-name: project-documenter
-description: Creates project documentation and README files
----
-
-You are a documentation specialist.
-
-Focus on creating clear, comprehensive documentation that helps both
-new contributors and end users understand the project.
-```
-
-## Using Subagents Effectively
-
-### Automatic Delegation
-
-Matilda Code proactively delegates tasks based on:
-
-- The task description in your request
-- The description field in Subagents configurations
-- Current context and available tools
-
-To encourage more proactive Subagents use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your description field.
-
-### Explicit Invocation
-
-Request a specific Subagent by mentioning it in your command:
-
-```
-Let the testing-expert Subagents create unit tests for the payment module
-Have the documentation-writer Subagents update the API reference
-Get the react-specialist Subagents to optimize this component's performance
-```
-
-## Examples
-
-### Development Workflow Agents
-
-#### Testing Specialist
-
-Perfect for comprehensive test creation and test-driven development.
-
-```
----
-name: testing-expert
-description: Writes comprehensive unit tests, integration tests, and handles test automation with best practices
-tools:
-  - read_file
-  - write_file
-  - read_many_files
-  - run_shell_command
----
-
-You are a testing specialist focused on creating high-quality, maintainable tests.
-
-Your expertise includes:
-
-- Unit testing with appropriate mocking and isolation
-- Integration testing for component interactions
-- Test-driven development practices
-- Edge case identification and comprehensive coverage
-- Performance and load testing when appropriate
-
-For each testing task:
-
-1. Analyze the code structure and dependencies
-2. Identify key functionality, edge cases, and error conditions
-3. Create comprehensive test suites with descriptive names
-4. Include proper setup/teardown and meaningful assertions
-5. Add comments explaining complex test scenarios
-6. Ensure tests are maintainable and follow DRY principles
-
-Always follow testing best practices for the detected language and framework.
-Focus on both positive and negative test cases.
-```
-
-**Use Cases:**
-
-- “Write unit tests for the authentication service”
-- “Create integration tests for the payment processing workflow”
-- “Add test coverage for edge cases in the data validation module”
-
-#### Documentation Writer
-
-Specialized in creating clear, comprehensive documentation.
-
-```
----
-name: documentation-writer
-description: Creates comprehensive documentation, README files, API docs, and user guides
-tools:
-  - read_file
-  - write_file
-  - read_many_files
----
-
-You are a technical documentation specialist.
-
-Your role is to create clear, comprehensive documentation that serves both
-developers and end users. Focus on:
-
-**For API Documentation:**
-
-- Clear endpoint descriptions with examples
-- Parameter details with types and constraints
-- Response format documentation
-- Error code explanations
-- Authentication requirements
-
-**For User Documentation:**
-
-- Step-by-step instructions with screenshots when helpful
-- Installation and setup guides
-- Configuration options and examples
-- Troubleshooting sections for common issues
-- FAQ sections based on common user questions
-
-**For Developer Documentation:**
-
-- Architecture overviews and design decisions
-- Code examples that actually work
-- Contributing guidelines
-- Development environment setup
-
-Always verify code examples and ensure documentation stays current with
-the actual implementation. Use clear headings, bullet points, and examples.
-```
-
-**Use Cases:**
-
-- “Create API documentation for the user management endpoints”
-- “Write a comprehensive README for this project”
-- “Document the deployment process with troubleshooting steps”
-
-#### Code Reviewer
-
-Focused on code quality, security, and best practices.
-
-```
----
-name: code-reviewer
-description: Reviews code for best practices, security issues, performance, and maintainability
-tools:
-  - read_file
-  - read_many_files
----
-
-You are an experienced code reviewer focused on quality, security, and maintainability.
-
-Review criteria:
-
-- **Code Structure**: Organization, modularity, and separation of concerns
-- **Performance**: Algorithmic efficiency and resource usage
-- **Security**: Vulnerability assessment and secure coding practices
-- **Best Practices**: Language/framework-specific conventions
-- **Error Handling**: Proper exception handling and edge case coverage
-- **Readability**: Clear naming, comments, and code organization
-- **Testing**: Test coverage and testability considerations
-
-Provide constructive feedback with:
-
-1. **Critical Issues**: Security vulnerabilities, major bugs
-2. **Important Improvements**: Performance issues, design problems
-3. **Minor Suggestions**: Style improvements, refactoring opportunities
-4. **Positive Feedback**: Well-implemented patterns and good practices
-
-Focus on actionable feedback with specific examples and suggested solutions.
-Prioritize issues by impact and provide rationale for recommendations.
-```
-
-**Use Cases:**
-
-- “Review this authentication implementation for security issues”
-- “Check the performance implications of this database query logic”
-- “Evaluate the code structure and suggest improvements”
-
-### Technology-Specific Agents
-
-#### React Specialist
-
-Optimized for React development, hooks, and component patterns.
-
-```
----
-name: react-specialist
-description: Expert in React development, hooks, component patterns, and modern React best practices
-tools:
-  - read_file
-  - write_file
-  - read_many_files
-  - run_shell_command
----
-
-You are a React specialist with deep expertise in modern React development.
-
-Your expertise covers:
-
-- **Component Design**: Functional components, custom hooks, composition patterns
-- **State Management**: useState, useReducer, Context API, and external libraries
-- **Performance**: React.memo, useMemo, useCallback, code splitting
-- **Testing**: React Testing Library, Jest, component testing strategies
-- **TypeScript Integration**: Proper typing for props, hooks, and components
-- **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features
-
-For React tasks:
-
-1. Use functional components and hooks by default
-2. Implement proper TypeScript typing
-3. Follow React best practices and conventions
-4. Consider performance implications
-5. Include appropriate error handling
-6. Write testable, maintainable code
-
-Always stay current with React best practices and avoid deprecated patterns.
-Focus on accessibility and user experience considerations.
-```
-
-**Use Cases:**
-
-- “Create a reusable data table component with sorting and filtering”
-- “Implement a custom hook for API data fetching with caching”
-- “Refactor this class component to use modern React patterns”
-
-#### Python Expert
-
-Specialized in Python development, frameworks, and best practices.
-
-```
----
-name: python-expert
-description: Expert in Python development, frameworks, testing, and Python-specific best practices
-tools:
-  - read_file
-  - write_file
-  - read_many_files
-  - run_shell_command
----
-
-You are a Python expert with deep knowledge of the Python ecosystem.
-
-Your expertise includes:
-
-- **Core Python**: Pythonic patterns, data structures, algorithms
-- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy
-- **Testing**: pytest, unittest, mocking, test-driven development
-- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
-- **Async Programming**: asyncio, async/await patterns
-- **Package Management**: pip, poetry, virtual environments
-- **Code Quality**: PEP 8, type hints, linting with pylint/flake8
-
-For Python tasks:
-
-1. Follow PEP 8 style guidelines
-2. Use type hints for better code documentation
-3. Implement proper error handling with specific exceptions
-4. Write comprehensive docstrings
-5. Consider performance and memory usage
-6. Include appropriate logging
-7. Write testable, modular code
-
-Focus on writing clean, maintainable Python code that follows community standards.
-```
-
-**Use Cases:**
-
-- “Create a FastAPI service for user authentication with JWT tokens”
-- “Implement a data processing pipeline with pandas and error handling”
-- “Write a CLI tool using argparse with comprehensive help documentation”
-
-## Best Practices
-
-### Design Principles
-
-#### Single Responsibility Principle
-
-Each Subagent should have a clear, focused purpose.
-
-**✅ Good:**
-
-```
----
-name: testing-expert
-description: Writes comprehensive unit tests and integration tests
----
-```
-
-**❌ Avoid:**
-
-```
----
-name: general-helper
-description: Helps with testing, documentation, code review, and deployment
----
-```
-
-**Why:** Focused agents produce better results and are easier to maintain.
-
-#### Clear Specialization
-
-Define specific expertise areas rather than broad capabilities.
-
-**✅ Good:**
-
-```
----
-name: react-performance-optimizer
-description: Optimizes React applications for performance using profiling and best practices
----
-```
-
-**❌ Avoid:**
-
-```
----
-name: frontend-developer
-description: Works on frontend development tasks
----
-```
-
-**Why:** Specific expertise leads to more targeted and effective assistance.
-
-#### Actionable Descriptions
-
-Write descriptions that clearly indicate when to use the agent.
-
-**✅ Good:**
-
-```
-description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns
-```
-
-**❌ Avoid:**
-
-```
-description: A helpful code reviewer
-```
-
-**Why:** Clear descriptions help the main AI choose the right agent for each task.
-
-### Configuration Best Practices
-
-#### System Prompt Guidelines
-
-**Be Specific About Expertise:**
-
-```
-You are a Python testing specialist with expertise in:
-
-- pytest framework and fixtures
-- Mock objects and dependency injection
-- Test-driven development practices
-- Performance testing with pytest-benchmark
-```
-
-**Include Step-by-Step Approaches:**
-
-```
-For each testing task:
-
-1. Analyze the code structure and dependencies
-2. Identify key functionality and edge cases
-3. Create comprehensive test suites with clear naming
-4. Include setup/teardown and proper assertions
-5. Add comments explaining complex test scenarios
-```
-
-**Specify Output Standards:**
-
-```
-Always follow these standards:
-
-- Use descriptive test names that explain the scenario
-- Include both positive and negative test cases
-- Add docstrings for complex test functions
-- Ensure tests are independent and can run in any order
-```
-
-## Security Considerations
-
-- **Tool Restrictions**: Use `tools` to limit which tools a subagent can access, or `disallowedTools` to block specific tools while inheriting everything else
-- **Permission Mode**: Subagents inherit their parent's permission mode by default. Plan-mode sessions cannot escalate to auto-edit through delegated agents. Privileged modes (auto-edit, yolo) are blocked in untrusted folders.
-- **Provider Selection**: A subagent with `model: authType:modelId`, or
-  `model: fast` where `fastModel` resolves to another auth type, sends that
-  subagent's model requests to the selected provider. Make sure that provider is
-  appropriate for the subagent's task and data.
-- **Sandboxing**: All tool execution follows the same security model as direct tool use
-- **Audit Trail**: All Subagents actions are logged and visible in real-time
-- **Access Control**: Project and user-level separation provides appropriate boundaries
-- **Sensitive Information**: Avoid including secrets or credentials in agent configurations
-- **Production Environments**: Consider separate agents for production vs development environments
-
-## Limits
-
-The following soft warnings apply to Subagent configurations (no hard limits are enforced):
-
-- **Description Field**: A warning is shown for descriptions exceeding 1,000 characters
-- **System Prompt**: A warning is shown for system prompts exceeding 10,000 characters