Better Updated Promting

apps/cli/src/application/assistant/agent.ts

@@ -15,6 +15,6 @@ export const CopilotAgent: z.infer<typeof Agent> = {
     name: "rowboatx",
     description: "Rowboatx copilot",
     instructions: CopilotInstructions,
-    model: "gpt-4.1",
+    model: "gpt-5.1",
     tools,
 }

apps/cli/src/application/assistant/skills/builtin-tools/skill.ts

@@ -0,0 +1,179 @@
+export const skill = String.raw`
+# Builtin Tools Reference
+
+Load this skill when creating or modifying agents that need access to Rowboat's builtin tools (shell execution, file operations, etc.).
+
+## Available Builtin Tools
+
+Agents can use builtin tools by declaring them in the \`"tools"\` object with \`"type": "builtin"\` and the appropriate \`"name"\`.
+
+### executeCommand
+**The most powerful and versatile builtin tool** - Execute any bash/shell command and get the output.
+
+**Agent tool declaration:**
+\`\`\`json
+"tools": {
+  "bash": {
+    "type": "builtin",
+    "name": "executeCommand"
+  }
+}
+\`\`\`
+
+**What it can do:**
+- Run package managers (npm, pip, apt, brew, cargo, go get, etc.)
+- Git operations (clone, commit, push, pull, status, diff, log, etc.)
+- System operations (ps, top, df, du, find, grep, kill, etc.)
+- Build and compilation (make, cargo build, go build, npm run build, etc.)
+- Network operations (curl, wget, ping, ssh, netstat, etc.)
+- Text processing (awk, sed, grep, jq, yq, cut, sort, uniq, etc.)
+- Database operations (psql, mysql, mongo, redis-cli, etc.)
+- Container operations (docker, kubectl, podman, etc.)
+- Testing and debugging (pytest, jest, cargo test, etc.)
+- File operations (cat, head, tail, wc, diff, patch, etc.)
+- Any CLI tool or script execution
+
+**Agent instruction examples:**
+- "Use the bash tool to run git commands for version control operations"
+- "Execute curl commands using the bash tool to fetch data from APIs"
+- "Use bash to run 'npm install' and 'npm test' commands"
+- "Run Python scripts using the bash tool with 'python script.py'"
+- "Use bash to execute 'docker ps' and inspect container status"
+- "Run database queries using 'psql' or 'mysql' commands via bash"
+- "Use bash to execute system monitoring commands like 'top' or 'ps aux'"
+
+**Pro tips for agent instructions:**
+- Commands can be chained with && for sequential execution
+- Use pipes (|) to combine Unix tools (e.g., "cat file.txt | grep pattern | wc -l")
+- Redirect output with > or >> when needed
+- Full bash shell features are available (variables, loops, conditionals, etc.)
+- Tools like jq, yq, awk, sed can parse and transform data
+
+**Example agent with executeCommand:**
+\`\`\`json
+{
+  "name": "arxiv-feed-reader",
+  "description": "A feed reader for the arXiv",
+  "model": "gpt-4.1",
+  "instructions": "Extract latest papers from the arXiv feed and summarize them. Use curl to fetch the RSS feed, then parse it with yq and jq:\n\ncurl -s https://rss.arxiv.org/rss/cs.AI | yq -p=xml -o=json | jq -r '.rss.channel.item[] | select(.title | test(\"agent\"; \"i\")) | \"\\(.title)\\n\\(.link)\\n\\(.description)\\n\"'\n\nThis will give you papers containing 'agent' in the title.",
+  "tools": {
+    "bash": {
+      "type": "builtin",
+      "name": "executeCommand"
+    }
+  }
+}
+\`\`\`
+
+**Another example - System monitoring agent:**
+\`\`\`json
+{
+  "name": "system-monitor",
+  "description": "Monitor system resources and processes",
+  "model": "gpt-4.1",
+  "instructions": "Monitor system resources using bash commands. Use 'df -h' for disk usage, 'free -h' for memory, 'top -bn1' for processes, 'ps aux' for process list. Parse the output and report any issues.",
+  "tools": {
+    "bash": {
+      "type": "builtin",
+      "name": "executeCommand"
+    }
+  }
+}
+\`\`\`
+
+**Another example - Git automation agent:**
+\`\`\`json
+{
+  "name": "git-helper",
+  "description": "Automate git operations",
+  "model": "gpt-4.1",
+  "instructions": "Help with git operations. Use commands like 'git status', 'git log --oneline -10', 'git diff', 'git branch -a' to inspect the repository. Can also run 'git add', 'git commit', 'git push' when instructed.",
+  "tools": {
+    "bash": {
+      "type": "builtin",
+      "name": "executeCommand"
+    }
+  }
+}
+\`\`\`
+
+## Agent-to-Agent Calling
+
+Agents can call other agents as tools to create complex multi-step workflows. This is the core mechanism for building multi-agent systems in the CLI.
+
+**Tool declaration:**
+\`\`\`json
+"tools": {
+  "summariser": {
+    "type": "agent",
+    "name": "summariser_agent"
+  }
+}
+\`\`\`
+
+**When to use:**
+- Breaking complex tasks into specialized sub-agents
+- Creating reusable agent components
+- Orchestrating multi-step workflows
+- Delegating specialized tasks (e.g., summarization, data processing, audio generation)
+
+**How it works:**
+- The agent calls the tool like any other tool
+- The target agent receives the input and processes it
+- Results are returned as tool output
+- The calling agent can then continue processing or delegate further
+
+**Example - Agent that delegates to a summarizer:**
+\`\`\`json
+{
+  "name": "paper_analyzer",
+  "model": "gpt-4.1",
+  "instructions": "Pick 2 interesting papers and summarise each using the summariser tool. Pass the paper URL to the summariser. Don't ask for human input.",
+  "tools": {
+    "summariser": {
+      "type": "agent",
+      "name": "summariser_agent"
+    }
+  }
+}
+\`\`\`
+
+**Tips for agent chaining:**
+- Make instructions explicit about when to call other agents
+- Pass clear, structured data between agents
+- Add "Don't ask for human input" for autonomous workflows
+- Keep each agent focused on a single responsibility
+
+## Additional Builtin Tools
+
+While \`executeCommand\` is the most versatile, other builtin tools exist for specific Rowboat operations (file management, agent inspection, etc.). These are primarily used by the Rowboat copilot itself and are not typically needed in user agents. If you need file operations, consider using bash commands like \`cat\`, \`echo\`, \`tee\`, etc. through \`executeCommand\`.
+
+## Best Practices
+
+1. **Give agents clear examples** in their instructions showing exact bash commands to run
+2. **Explain output parsing** - show how to use jq, yq, grep, awk to extract data
+3. **Chain commands efficiently** - use && for sequences, | for pipes
+4. **Handle errors** - remind agents to check exit codes and stderr
+5. **Be specific** - provide example commands rather than generic descriptions
+6. **Security** - remind agents to validate inputs and avoid dangerous operations
+
+## When to Use Builtin Tools vs MCP Tools vs Agent Tools
+
+- **Use builtin executeCommand** when you need: CLI tools, system operations, data processing, git operations, any shell command
+- **Use MCP tools** when you need: Web scraping (firecrawl), text-to-speech (elevenlabs), specialized APIs, external service integrations
+- **Use agent tools (\`"type": "agent"\`)** when you need: Complex multi-step logic, task delegation, specialized processing that benefits from LLM reasoning
+
+Many tasks can be accomplished with just \`executeCommand\` and common Unix tools - it's incredibly powerful!
+
+## Key Insight: Multi-Agent Workflows
+
+In the CLI, multi-agent workflows are built by:
+1. Creating specialized agents for specific tasks (in \`agents/\` directory)
+2. Creating an orchestrator agent that has other agents in its \`tools\`
+3. Running the orchestrator with \`rowboatx --agent orchestrator_name\`
+
+There are no separate "workflow" files - everything is an agent!
+`;
+
+export default skill;
+

apps/cli/src/application/assistant/skills/index.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import builtinToolsSkill from "./builtin-tools/skill.js";
 import deletionGuardrailsSkill from "./deletion-guardrails/skill.js";
 import mcpIntegrationSkill from "./mcp-integration/skill.js";
 import workflowAuthoringSkill from "./workflow-authoring/skill.js";
@@ -31,6 +32,13 @@ const definitions: SkillDefinition[] = [
     summary: "Creating or editing workflows/agents, validating schema rules, and keeping filenames aligned with JSON ids.",
     content: workflowAuthoringSkill,
   },
+  {
+    id: "builtin-tools",
+    title: "Builtin Tools Reference",
+    folder: "builtin-tools",
+    summary: "Understanding and using builtin tools (especially executeCommand for bash/shell) in agent definitions.",
+    content: builtinToolsSkill,
+  },
   {
     id: "mcp-integration",
     title: "MCP Integration Guidance",

apps/cli/src/application/assistant/skills/workflow-authoring/skill.ts

@@ -1,26 +1,26 @@
 export const skill = String.raw`
-# Workflow Authoring
+# Agent and Workflow Authoring
 
-Load this skill whenever a user wants to inspect, create, or update workflows or agents inside the Rowboat workspace.
+Load this skill whenever a user wants to inspect, create, or update agents inside the Rowboat workspace.
 
-## Workflow knowledge
-- Workflows (\`workflows/*.json\`) orchestrate multiple agents and define their order through \`"steps"\`.
-- Agents (\`agents/*.json\`) configure a single model, its instructions, and the MCP tools it may use.
-- Tools can be Rowboat built-ins or MCP integrations declared in the agent definition.
+## Core Concepts
 
-## Workflow format
-\`\`\`
-{
-  "name": "workflow_name",
-  "description": "Description of the workflow",
-  "steps": [
-    {"type": "agent", "id": "agent_name"}
-  ]
-}
-\`\`\`
+**IMPORTANT**: In the CLI, there are NO separate "workflow" files. Everything is an agent.
+
+- **All definitions live in \`agents/*.json\`** - there is no separate workflows folder
+- Agents configure a model, instructions, and the tools they can use
+- Tools can be: builtin (like \`executeCommand\`), MCP integrations, or **other agents**
+- **"Workflows" are just agents that orchestrate other agents** by having them as tools
+
+## How multi-agent workflows work
+
+1. **Create an orchestrator agent** that has other agents in its \`tools\`
+2. **Run the orchestrator**: \`rowboatx --agent orchestrator_name\`
+3. The orchestrator calls other agents as tools when needed
+4. Data flows through tool call parameters and responses
 
 ## Agent format
-\`\`\`
+\`\`\`json
 {
   "name": "agent_name",
   "description": "Description of the agent",
@@ -42,22 +42,127 @@ Load this skill whenever a user wants to inspect, create, or update workflows or
   }
 }
 \`\`\`
-- Tool keys should be descriptive (e.g., \`"search"\`, \`"fetch"\`, \`"analyze"\`) rather than the MCP tool name.
-- Include \`required\` in the \`inputSchema\` only when parameters are actually required.
+
+## Tool types
+
+### Builtin tools
+\`\`\`json
+"bash": {
+  "type": "builtin",
+  "name": "executeCommand"
+}
+\`\`\`
+
+### MCP tools
+\`\`\`json
+"search": {
+  "type": "mcp",
+  "name": "firecrawl_search",
+  "description": "Search the web",
+  "mcpServerName": "firecrawl",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": {"type": "string", "description": "Search query"}
+    },
+    "required": ["query"]
+  }
+}
+\`\`\`
+
+### Agent tools (for chaining agents)
+\`\`\`json
+"summariser": {
+  "type": "agent",
+  "name": "summariser_agent"
+}
+\`\`\`
+- Use \`"type": "agent"\` to call other agents as tools
+- The target agent will be invoked with the parameters you pass
+- Results are returned as tool output
+- This is how you build multi-agent workflows
+
+## Complete Multi-Agent Workflow Example
+
+**Podcast creation workflow** - This is all done through agents calling other agents:
+
+**1. Task-specific agent** (does one thing):
+\`\`\`json
+{
+  "name": "summariser_agent",
+  "description": "Summarises an arxiv paper",
+  "model": "gpt-4.1",
+  "instructions": "Download and summarise an arxiv paper. Use curl to fetch the PDF. Output just the GIST in two lines. Don't ask for human input.",
+  "tools": {
+    "bash": {"type": "builtin", "name": "executeCommand"}
+  }
+}
+\`\`\`
+
+**2. Agent that delegates to other agents**:
+\`\`\`json
+{
+  "name": "summarise-a-few",
+  "description": "Summarises multiple arxiv papers",
+  "model": "gpt-4.1",
+  "instructions": "Pick 2 interesting papers and summarise each using the summariser tool. Pass the paper URL to the tool. Don't ask for human input.",
+  "tools": {
+    "summariser": {
+      "type": "agent",
+      "name": "summariser_agent"
+    }
+  }
+}
+\`\`\`
+
+**3. Orchestrator agent** (coordinates the whole workflow):
+\`\`\`json
+{
+  "name": "podcast_workflow",
+  "description": "Create a podcast from arXiv papers",
+  "model": "gpt-4.1",
+  "instructions": "1. Fetch arXiv papers about agents using bash\n2. Pick papers and summarise them using summarise_papers\n3. Create a podcast transcript\n4. Generate audio using text_to_speech\n\nExecute these steps in sequence.",
+  "tools": {
+    "bash": {"type": "builtin", "name": "executeCommand"},
+    "summarise_papers": {
+      "type": "agent",
+      "name": "summarise-a-few"
+    },
+    "text_to_speech": {
+      "type": "mcp",
+      "name": "text_to_speech",
+      "mcpServerName": "elevenLabs",
+      "description": "Generate audio",
+      "inputSchema": { "type": "object", "properties": {...}}
+    }
+  }
+}
+\`\`\`
+
+**To run this workflow**: \`rowboatx --agent podcast_workflow\`
 
 ## Naming and organization rules
-- Agent filenames must match the \`"name"\` field and the workflow step \`"id"\`.
-- Workflow filenames must match the \`"name"\` field.
-- Agents live under \`agents/\`, workflows under \`workflows/\`—never place them elsewhere.
-- Always keep filenames, \`"name"\`, and referenced ids perfectly aligned.
-- Use relative paths (no \${BASE_DIR} prefixes) when calling tools from the CLI.
+- **All agents live in \`agents/*.json\`** - no other location
+- Agent filenames must match the \`"name"\` field exactly
+- When referencing an agent as a tool, use its \`"name"\` value
+- Always keep filenames and \`"name"\` fields perfectly aligned
+- Use relative paths (no \${BASE_DIR} prefixes) when giving examples to users
+
+## Best practices for multi-agent design
+1. **Single responsibility**: Each agent should do one specific thing well
+2. **Clear delegation**: Agent instructions should explicitly say when to call other agents
+3. **Autonomous operation**: Add "Don't ask for human input" for autonomous workflows
+4. **Data passing**: Make it clear what data to extract and pass between agents
+5. **Tool naming**: Use descriptive tool keys (e.g., "summariser", "fetch_data", "analyze")
+6. **Orchestration**: Create a top-level agent that coordinates the workflow
 
 ## Capabilities checklist
-1. Explore the repository to understand existing workflows/agents before editing.
-2. Update files carefully to maintain schema validity.
-3. Suggest improvements and ask clarifying questions.
-4. List and explore MCP servers/tools when users need new capabilities.
-5. Confirm work done and outline next steps once changes are complete.
+1. Explore \`agents/\` directory to understand existing agents before editing
+2. Update files carefully to maintain schema validity
+3. When creating multi-agent workflows, create an orchestrator agent
+4. Add other agents as tools with \`"type": "agent"\` for chaining
+5. List and explore MCP servers/tools when users need new capabilities
+6. Confirm work done and outline next steps once changes are complete
 `;
 
 export default skill;

apps/cli/src/application/assistant/skills/workflow-run-ops/skill.ts

@@ -1,19 +1,39 @@
 export const skill = String.raw`
-# Workflow Run Operations
+# Agent Run Operations
 
-Package of repeatable commands for inspecting workflow run history under ~/.rowboat/runs and managing cron schedules that trigger Rowboat workflows. Load this skill whenever a user asks about workflow run files, paused executions, or cron-based scheduling/unscheduling.
+Package of repeatable commands for running agents, inspecting agent run history under ~/.rowboat/runs, and managing cron schedules. Load this skill whenever a user asks about running agents, execution history, paused runs, or scheduling.
 
 ## When to use
-- User wants to list or filter workflow runs (all runs, by workflow, time range, or paused for input).
-- User wants to inspect cron jobs or change the workflow schedule.
-- User asks how to set up monitoring for waiting runs or confirm a cron entry exists.
+- User wants to run an agent (including multi-agent workflows)
+- User wants to list or filter agent runs (all runs, by agent, time range, or paused for input)
+- User wants to inspect cron jobs or change agent schedules
+- User asks how to set up monitoring for waiting runs
+
+## Running Agents
+
+**To run any agent**:
+\`\`\`bash
+rowboatx --agent <agent-name>
+\`\`\`
+
+**With input**:
+\`\`\`bash
+rowboatx --agent <agent-name> --input "your input here"
+\`\`\`
+
+**Non-interactive** (for automation/cron):
+\`\`\`bash
+rowboatx --agent <agent-name> --input "input" --no-interactive
+\`\`\`
+
+**Note**: Multi-agent workflows are just agents that have other agents in their tools. Run the orchestrator agent to trigger the whole workflow.
 
 ## Run monitoring examples
 Operate from ~/.rowboat (Rowboat tools already set this as the working directory). Use executeCommand with the sample Bash snippets below, modifying placeholders as needed.
 
 Each run file name starts with a timestamp like '2025-11-12T08-02-41Z'. You can use this to filter for date/time ranges.
 
-Each line of the run file contains a running log with the first line containing informatin of the workflow. E.g. '{"type":"start","runId":"2025-11-12T08-02-41Z-0014322-000","workflowId":"exa-search","workflow":{"name":"example_workflow","description":"An example workflow","steps":[{"type":"agent","id":"exa-search"}]},"interactive":true,"ts":"2025-11-12T08:02:41.168Z"}'
+Each line of the run file contains a running log with the first line containing information about the agent run. E.g. '{"type":"start","runId":"2025-11-12T08-02-41Z-0014322-000","agent":"agent_name","interactive":true,"ts":"2025-11-12T08:02:41.168Z"}'
 
 If a run is waiting for human input the last line will contain 'paused_for_human_input'. See examples below.
 
@@ -22,11 +42,11 @@ If a run is waiting for human input the last line will contain 'paused_for_human
    ls ~/.rowboat/runs
    
 
-2. **Filter by workflow**
+2. **Filter by agent**
    
-   grep -rl '"workflowId":"<workflow-id>"' ~/.rowboat/runs | xargs -n1 basename | sed 's/\.jsonl$//' | sort -r
+   grep -rl '"agent":"<agent-name>"' ~/.rowboat/runs | xargs -n1 basename | sed 's/\.jsonl$//' | sort -r
    
-   Replace <workflow-id> with the desired id.
+   Replace <agent-name> with the desired agent name.
 
 3. **Filter by time window**
    To the previous commands add the below through unix pipe
@@ -42,20 +62,34 @@ If a run is waiting for human input the last line will contain 'paused_for_human
    Prints the files whose last line equals 'pause-for-human-input'.
 
 ## Cron management examples
-1. **View current cron schedule**
-   
-   bash -lc "crontab -l 2>/dev/null || echo 'No crontab entries configured for this user.'"
-   
-2. **Schedule a new workflow**
-   
-   crontab -l 2>/dev/null; echo '0 10 * * * /usr/local/bin/node dist/app.js exa-search "what is the weather in tokyo" >> /Users/arjun/.rowboat/logs/exa_search.log 2>&1' ) | crontab -
-   
 
-3. **Unschedule/remove a workflow**
+For scheduling agents to run automatically at specific times.
+
+1. **View current cron schedule**
+   \`\`\`bash
+   crontab -l 2>/dev/null || echo 'No crontab entries configured.'
+   \`\`\`
+
+2. **Schedule an agent to run periodically**
+   \`\`\`bash
+   (crontab -l 2>/dev/null; echo '0 10 * * * cd /path/to/cli && rowboatx --agent <agent-name> --input "input" --no-interactive >> ~/.rowboat/logs/<agent-name>.log 2>&1') | crontab -
+   \`\`\`
    
-   crontab -l | grep -v 'exa-search' | crontab -
-   
-   Removes cron lines containing the workflow id.
+   Example (runs daily at 10 AM):
+   \`\`\`bash
+   (crontab -l 2>/dev/null; echo '0 10 * * * cd ~/rowboat-V2/apps/cli && rowboatx --agent podcast_workflow --no-interactive >> ~/.rowboat/logs/podcast.log 2>&1') | crontab -
+   \`\`\`
+
+3. **Unschedule/remove an agent**
+   \`\`\`bash
+   crontab -l | grep -v '<agent-name>' | crontab -
+   \`\`\`
+
+## Common cron schedule patterns
+- \`0 10 * * *\` - Daily at 10 AM
+- \`0 */6 * * *\` - Every 6 hours
+- \`0 9 * * 1\` - Every Monday at 9 AM
+- \`*/30 * * * *\` - Every 30 minutes
 `;
 
 export default skill;

apps/cli/src/application/lib/builtin-tools.ts

@@ -44,7 +44,7 @@ export const BuiltinTools: z.infer<typeof BuiltinToolsSchema> = {
     },
 
     exploreDirectory: {
-        description: 'Recursively explore directory structure to understand existing workflows, agents, and file organization',
+        description: 'Recursively explore directory structure to understand existing agents and file organization',
         inputSchema: z.object({
             subdirectory: z.string().optional().describe('Subdirectory to explore (optional, defaults to root)'),
             maxDepth: z.number().optional().describe('Maximum depth to traverse (default: 3)'),
@@ -260,27 +260,35 @@ export const BuiltinTools: z.infer<typeof BuiltinToolsSchema> = {
         },
     },
     
-    analyzeWorkflow: {
-        description: 'Read and analyze a workflow file to understand its structure, agents, and dependencies',
+    analyzeAgent: {
+        description: 'Read and analyze an agent file to understand its structure, tools, and configuration',
         inputSchema: z.object({
-            workflowName: z.string().describe('Name of the workflow file to analyze (with or without .json extension)'),
+            agentName: z.string().describe('Name of the agent file to analyze (with or without .json extension)'),
         }),
-        execute: async ({ workflowName }: { workflowName: string }) => {
+        execute: async ({ agentName }: { agentName: string }) => {
             try {
-                const filename = workflowName.endsWith('.json') ? workflowName : `${workflowName}.json`;
-                const filePath = path.join(BASE_DIR, 'workflows', filename);
+                const filename = agentName.endsWith('.json') ? agentName : `${agentName}.json`;
+                const filePath = path.join(BASE_DIR, 'agents', filename);
                 
                 const content = await fs.readFile(filePath, 'utf-8');
-                const workflow = JSON.parse(content);
+                const agent = JSON.parse(content);
                 
                 // Extract key information
+                const toolsList = agent.tools ? Object.keys(agent.tools) : [];
+                const agentTools = agent.tools ? Object.entries(agent.tools).map(([key, tool]: [string, any]) => ({
+                    key,
+                    type: tool.type,
+                    name: tool.name || key,
+                })) : [];
+                
                 const analysis = {
-                    name: workflow.name,
-                    description: workflow.description || 'No description',
-                    agentCount: workflow.agents ? workflow.agents.length : 0,
-                    agents: workflow.agents || [],
-                    tools: workflow.tools || {},
-                    structure: workflow,
+                    name: agent.name,
+                    description: agent.description || 'No description',
+                    model: agent.model || 'Not specified',
+                    toolCount: toolsList.length,
+                    tools: agentTools,
+                    hasOtherAgents: agentTools.some((t: any) => t.type === 'agent'),
+                    structure: agent,
                 };
                 
                 return {
@@ -291,7 +299,7 @@ export const BuiltinTools: z.infer<typeof BuiltinToolsSchema> = {
             } catch (error) {
                 return {
                     success: false,
-                    message: `Failed to analyze workflow: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Failed to analyze agent: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 };
             }
         },