From 468a999b80f27a07f7f63a886b746dae55bb714a Mon Sep 17 00:00:00 2001 From: rob Date: Sat, 4 Apr 2026 17:49:59 -0300 Subject: [PATCH] Add Philosophy page and improve documentation - Add /philosophy page explaining the paradigm shift from libraries to capabilities - Visual diagrams comparing traditional vs CmdForge approach (bin of circuits vs organized workshop) - Composition flow diagram showing tools chaining together - Link from About page and homepage - Update CLAUDE.md with accurate field names (output_schema not structured_output) - Add Provider Install dialog to GUI dialogs list Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 26 +- src/cmdforge/web/routes.py | 5 + src/cmdforge/web/templates/pages/about.html | 7 + src/cmdforge/web/templates/pages/index.html | 7 +- .../web/templates/pages/philosophy.html | 418 ++++++++++++++++++ 5 files changed, 458 insertions(+), 5 deletions(-) create mode 100644 src/cmdforge/web/templates/pages/philosophy.html diff --git a/CLAUDE.md b/CLAUDE.md index a45959d..c9ba038 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -56,7 +56,7 @@ python -m cmdforge.cli # Alternative CLI invocation - **gui/**: PySide6 desktop GUI - **main_window.py**: Main application window with sidebar navigation - **pages/**: Welcome page, Tools page, Tool Builder, Registry browser, Collections page, Providers management, Profiles - - **dialogs/**: Step editors (prompt/code/tool), Argument editor, Provider dialog, Connect/Publish dialogs, Test Step dialog, Settings dialog, System Dep dialog, Help dialogs, Review/Issue dialogs + - **dialogs/**: Step editors (prompt/code/tool), Argument editor, Provider dialog, Provider Install dialog, Connect/Publish dialogs, Test Step dialog, Settings dialog, System Dep dialog, Help dialogs, Review/Issue dialogs - **widgets/**: Flow graph visualization (`flow_graph.py`), Icon utilities (`icons.py`) ### Key Paths @@ -73,7 +73,7 @@ python -m cmdforge.cli # Alternative CLI invocation Tools are YAML configs with: - `name`, `description`, `category` - `arguments`: Custom flags with defaults (e.g., `--max` → `{max}`) -- `steps`: Ordered list of `prompt` or `code` steps +- `steps`: Ordered list of `prompt`, `code`, or `tool` steps - `output`: Template for final output (e.g., `"{response}"`) ### Step Types @@ -81,9 +81,11 @@ Tools are YAML configs with: 1. **Prompt Step**: Calls AI provider with template, stores result in `output_var` - `profile`: AI persona (system prompt prefix) - `strip_fences`: Remove markdown code fences from output - - `structured_output`: JSON schema for validated structured responses + - `output_schema`: JSON schema for validated structured responses + - `max_tokens`: Max output tokens (provider-dependent, e.g., 4096 for haiku) + - `plain_text`: Bypass structured output enforcement 2. **Code Step**: Executes Python code via `exec()`, captures specified variables (comma-separated for multiple outputs) -3. **Tool Step**: Calls another tool (meta-tools), supports `args` dict and `provider` override. Dependencies resolved via `resolver.py` +3. **Tool Step**: Calls another tool (meta-tools), supports `input_template`, `args` dict, and `provider` override. Dependencies resolved via `resolver.py` ### Variable Flow @@ -104,12 +106,28 @@ Providers are CLI tools that accept prompts via stdin and output to stdout. Defi providers: - name: claude command: "claude -p" + description: "Anthropic Claude" + fallback: claude-haiku # Optional: try this provider if primary fails - name: mock command: "echo '[MOCK]'" ``` +Provider fields: +- `name`: Provider identifier used in tool configs +- `command`: Shell command to invoke (prompt sent via stdin) +- `description`: Optional human-readable description +- `fallback`: Optional provider to try if this one fails (prevents infinite loops) + The `mock` provider is built-in for testing without API calls. Use `--provider mock` or `--dry-run` flags when testing tools. +Provider CLI commands: +- `cmdforge providers list` - List all providers and their status +- `cmdforge providers add ` - Add/update a provider +- `cmdforge providers remove ` - Remove a provider +- `cmdforge providers test ` - Test a provider +- `cmdforge providers install` - Interactive guide to install AI providers +- `cmdforge providers for-tools [tools...]` - List providers used by tools (with `--warm` to pre-load local models) + ## Web UI & Registry CmdForge includes a web interface and tool registry: diff --git a/src/cmdforge/web/routes.py b/src/cmdforge/web/routes.py index 0b0d904..4225c8a 100644 --- a/src/cmdforge/web/routes.py +++ b/src/cmdforge/web/routes.py @@ -869,6 +869,11 @@ def about(): return render_template("pages/about.html") +@web_bp.route("/philosophy", endpoint="philosophy") +def philosophy(): + return render_template("pages/philosophy.html") + + @web_bp.route("/donate", endpoint="donate") def donate(): return render_template("pages/donate.html") diff --git a/src/cmdforge/web/templates/pages/about.html b/src/cmdforge/web/templates/pages/about.html index bb25775..8b59859 100644 --- a/src/cmdforge/web/templates/pages/about.html +++ b/src/cmdforge/web/templates/pages/about.html @@ -12,6 +12,13 @@

An open-source platform for building and sharing AI-powered command-line tools.

+ + Read our philosophy: From Libraries to Capabilities + + + + diff --git a/src/cmdforge/web/templates/pages/index.html b/src/cmdforge/web/templates/pages/index.html index 48de8eb..14d9ecc 100644 --- a/src/cmdforge/web/templates/pages/index.html +++ b/src/cmdforge/web/templates/pages/index.html @@ -49,9 +49,14 @@
-

+

Why CmdForge?

+

+ + Read our philosophy → + +

diff --git a/src/cmdforge/web/templates/pages/philosophy.html b/src/cmdforge/web/templates/pages/philosophy.html new file mode 100644 index 0000000..2767afb --- /dev/null +++ b/src/cmdforge/web/templates/pages/philosophy.html @@ -0,0 +1,418 @@ +{% extends "base.html" %} + +{% block title %}Philosophy - CmdForge{% endblock %} + +{% block meta_description %}The philosophy behind CmdForge: from fragmented libraries to composable capabilities. Learn why we're building a new way to create software.{% endblock %} + +{% block content %} +
+ +
+
+

+ From Libraries to Capabilities +

+

+ Software development is changing. CmdForge is our attempt to make it simpler, + more composable, and accessible to everyone. +

+
+
+ + +
+
+

The Journey

+
+

+ I first learned to code on a Commodore VIC-20, writing BASIC before DOS existed. + I've watched computing evolve through every major shift: from single programs to + functions, from functions to libraries, from libraries to frameworks, from + frameworks to microservices. +

+

+ Each evolution promised to make things easier. And in many ways, they did. But + something else happened too: fragmentation. +

+

+ Open source gave us everything we could ever want. Thousands of contributors + building solutions to every problem imaginable. But finding the right solution + became the problem itself. +

+
+
+
+ + +
+
+

The Problem

+ +
+ +
+
+
+ + + +
+

Traditional Development

+
+ + +
+ + + + + + + + + + + + + + +
+ +

+ "Like digging through a giant bin of tangled circuits..." +

+ +
    +
  • + + + + Thousands of libraries to evaluate +
    • +
  • + + + + Different philosophies and coding styles +
    • +
  • + + + + Version conflicts and dependency hell +
    • +
  • + + + + Reinventing the same solutions +
    • +
+
+ + +
+
+
+ + + +
+

The CmdForge Way

+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Text + Developer + +
+ +

+ "Like an organized workshop with a knowledgeable shopkeeper..." +

+ +
    +
  • + + + + Every tool has a clear purpose +
    • +
  • + + + + AI helps you find what you need +
    • +
  • + + + + Tools combine instantly +
    • +
  • + + + + Shared globally, improved together +
    • +
+
+
+
+
+ + +
+
+

The Insight

+
+

+ What if we stopped thinking about libraries and started thinking + about capabilities? +

+

+ A library is code you integrate. A capability is something you ask for. +

+

+ Instead of searching through npm, pip, or crates.io for the right package, + what if you could just describe what you need? +

+
+ "I need something that extracts key points from meeting transcripts." +
+

+ And the system either finds an existing tool that does exactly that, or + creates one for you—and shares it back so the next person doesn't have to ask. +

+
+
+
+ + +
+
+

How It Works

+ + +
+

Tools Compose Into Systems

+
+ +
+
Input
+
meeting.txt
+
+ + + + + + +
+
Tool
+
extract-topics
+
+ + + + + + +
+
Tool
+
summarize
+
+ + + + + + +
+
Tool
+
format-email
+
+ + + + + + +
+
Output
+
summary.md
+
+
+ +

+ Each tool does one thing well. Combined, they create complex workflows. +

+
+ + +
+
+
+ + + +
+

Ask, Don't Search

+

+ Describe what you need in natural language. AI finds or creates it. +

+ + cmdforge registry describe "analyze sentiment" + +
+ +
+
+ + + +
+

Compose, Don't Integrate

+

+ Tools chain together with Unix pipes. No dependency management. +

+ + cat data.csv | analyze | report + +
+ +
+
+ + + +
+

Share, Don't Hoard

+

+ Every tool you create can benefit others. Build on each other's work. +

+ + cmdforge registry publish + +
+
+
+
+ + +
+
+

The Belief

+
+ "If something has been built once, it should be + reusable forever.

+ Not as a library. Not as a framework.
+ But as a capability anyone can call." +
+
+
+ + +
+
+

What This Means

+ +
+
+

CmdForge is NOT:

+
    +
  • + ✗ + A package manager (like npm or pip) +
    • +
  • + ✗ + A framework to learn +
    • +
  • + ✗ + Just AI code generation +
    • +
  • + ✗ + A replacement for shell scripting +
    • +
+
+ +
+

CmdForge IS:

+
    +
  • + ✓ + A capability registry +
    • +
  • + ✓ + A tool composition engine +
    • +
  • + ✓ + An AI-assisted discovery layer +
    • +
  • + ✓ + A shared execution ecosystem +
    • +
+
+
+
+
+ + +
+
+

Ready to Try It?

+

+ Start building composable tools in minutes. +

+
+ + Get Started + + + Browse Tools + +
+
+
+
+{% endblock %}