forge-tool

# forge-tool

Create one or more CmdForge tools from a natural-language description. The
generated tools include configuration, documentation, typed arguments, and
contracts, with optional decomposition into reusable ToolStep components.

`forge-tool` is an official registry tool rather than CmdForge package source.
Install it with one command:

```bash
cmdforge registry install official/forge-tool
```

## Choose the ownership location

Use project-local storage for tools that belong to an application:

```bash
cd ~/PycharmProjects/my-project
echo "Classify bounded documentation excerpts and return cited JSON" \
  | forge-tool --name docs-classify --project
```

This writes `.cmdforge/docs-classify/config.yaml` and `README.md`. Commit those
files to the consuming project. Do not modify the CmdForge source repository to
add another project's tools.

Use global storage for personal tools available in every project:

```bash
echo "Extract email addresses from text" \
  | forge-tool --name extract-emails
```

Use an explicit root when another layout is required:

```bash
echo "Normalize imported records" \
  | forge-tool --name normalize-records --output-dir ./automation/tools
```

`--project` and `--output-dir` are mutually exclusive.

## Arguments

| Flag | Default | Description |
|---|---|---|
| `--name NAME` | required | Name of the primary generated tool |
| `--category CATEGORY` | `Other` | Tool category |
| `--default-provider PROVIDER` | `claude-sonnet` | Provider placed on generated prompt steps |
| `--force VALUE` | `false` | Permit replacement when a target tool directory exists |
| `--project` | false | Write under the current project's `.cmdforge/` root |
| `--output-dir PATH` | empty | Write under an explicit tool root |

Without `--force`, any existing target stops the entire generated batch before
files are written. Symlink targets are always rejected. Review existing tools
and version-control status before deliberately replacing them.

## Workflow

1. Validate the requested name and ownership root.
2. Ask the selected provider for a schema-valid tool design.
3. Validate every generated tool and ToolStep reference before writing.
4. Require the batch to contain the requested primary tool.
5. Write the tools and run CmdForge's built-in deterministic preflight checks.

Complex workflows are split only when a component is independently useful,
contractible, and testable. Tightly coupled steps remain together.

## Review a generated project tool

```bash
cmdforge inspect docs-classify
git status --short .cmdforge/docs-classify
sed -n '1,240p' .cmdforge/docs-classify/config.yaml
```

Generated output is still AI-authored code and configuration. Inspect it before
running or publishing it, especially code steps, MCP calls, filesystem access,
and provider/privacy policies.

## Dependencies

`forge-tool` has no other tool dependencies. A clean
`cmdforge registry install official/forge-tool` installation is ready to run.
Generated tools may declare their own dependencies when the requested workflow
requires them.

## Output

The command prints a summary containing created paths and built-in preflight
results. Global tools receive shell wrappers. Project-local tools remain scoped
to their containing project and run through `cmdforge run TOOL`.