From d464c79002992eb0dec94a0a37f386d9a6d68c54 Mon Sep 17 00:00:00 2001 From: rob Date: Tue, 21 Jul 2026 12:58:20 -0300 Subject: [PATCH] Document agent-first tool workflows --- src/cmdforge/web/docs_content.py | 49 ++++++++++++++++++++++++++++---- tests/test_web_docs_content.py | 26 +++++++++++++++++ 2 files changed, 69 insertions(+), 6 deletions(-) create mode 100644 tests/test_web_docs_content.py diff --git a/src/cmdforge/web/docs_content.py b/src/cmdforge/web/docs_content.py index 822547f..51890fd 100644 --- a/src/cmdforge/web/docs_content.py +++ b/src/cmdforge/web/docs_content.py @@ -34,6 +34,13 @@ cmdforge create # CLI wizard # Or install a tool from the registry cmdforge registry install official/summarize +# Discover tools from scripts or an AI coding assistant +cmdforge list --json --filter "summarize" --limit 10 +cmdforge registry search "summarize text" --json --limit 5 + +# Run a one-off prompt without creating a tool +cat article.txt | cmdforge run-once "Summarize this:\n\n{input}" + # Use it! cat article.txt | summarize @@ -46,6 +53,26 @@ cf cmdforge create uses a command-line wizard. Both create the same YAML config files.

+

Using CmdForge with Coding Agents

+

CmdForge can expose installed tools to supported coding hosts over MCP. Preview the +configuration first; CmdForge updates only its marked policy block and does not expose +tools that you have not explicitly allowed.

+
cmdforge mcp configure codex --dry-run
+cmdforge mcp configure codex
+
+# Claude Code is supported too
+cmdforge mcp configure claude-code --dry-run
+

For a reusable workflow owned by an application, create it inside that application's +.cmdforge/ directory. Do not modify the CmdForge source repository merely to +add a tool for another project.

+
cd your-project
+cmdforge create classify-docs --project
+
+# Or use the official AI-assisted creator
+cmdforge registry install official/forge-tool
+echo "Create a bounded document classifier" \
+  | forge-tool --name classify-docs --project
+

How It Works

Each tool is a YAML file that defines:

    @@ -96,6 +123,7 @@ output: "{summary}" "headings": [ ("what-is-cmdforge", "What is CmdForge?"), ("quick-start", "Quick Start"), + ("coding-agents", "Using CmdForge with Coding Agents"), ("how-it-works", "How It Works"), ("next-steps", "Next Steps"), ("get-help", "Get Help"), @@ -160,8 +188,13 @@ pip install -e ".[dev]"

    Let's create a simple tool that explains code. You'll learn the basics of tool configuration.

    Create the Tool

    -

    Run the interactive creator:

    -
    cmdforge create
    +

    Run the interactive creator. Use --project when the tool belongs to the +current application and should be versioned with it:

    +
    # Personal tool in ~/.cmdforge/
+cmdforge create explain
+
+# Project-owned tool in ./.cmdforge/
+cmdforge create explain --project

    Or create the file manually at ~/.cmdforge/explain/config.yaml:

    name: explain
@@ -4004,12 +4037,12 @@ cat file.txt | summarize --provider mock
    Launch the Visual Builder (desktop GUI) - cmdforge list - List all installed tools + cmdforge list [--json] [--filter QUERY] + List or machine-search installed tools - cmdforge create - Create a new tool (interactive wizard) + cmdforge create NAME [--project] + Create a personal or project-owned tool cmdforge edit <tool> @@ -4027,6 +4060,10 @@ cat file.txt | summarize --provider mock cmdforge run <tool> Run a tool directly (without wrapper) + + cmdforge run-once "Instruction {input}" + Run an ad-hoc prompt without creating a tool + cmdforge refresh Regenerate all wrapper scripts diff --git a/tests/test_web_docs_content.py b/tests/test_web_docs_content.py new file mode 100644 index 0000000..05d119b --- /dev/null +++ b/tests/test_web_docs_content.py @@ -0,0 +1,26 @@ +"""Regression tests for user-facing documentation embedded in the web app.""" + +from cmdforge.web.docs_content import get_doc + + +def test_getting_started_documents_agent_first_workflow(): + content = get_doc("getting-started")["content"] + + expected_commands = ( + "cmdforge list --json --filter", + "cmdforge registry search", + "cmdforge run-once", + "cmdforge create classify-docs --project", + "forge-tool --name classify-docs --project", + "cmdforge mcp configure codex --dry-run", + "cmdforge mcp configure claude-code --dry-run", + ) + for command in expected_commands: + assert command in content + + +def test_first_tool_explains_project_ownership(): + content = get_doc("first-tool")["content"] + + assert "cmdforge create explain --project" in content + assert "./.cmdforge/" in content