clawforge-cli 1.6.3__tar.gz → 2.0.0__tar.gz

{clawforge_cli-1.6.3 → clawforge_cli-2.0.0}/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## v2.0.0 — Fleet Forge Pivot
+
+**ClawForge is now an agent fleet forge for OpenClaw.**
+
+### New: Fleet Management
+- `create` — Interactive agent creation wizard with archetype templates
+- `list` — Fleet overview with status indicators
+- `inspect` — Deep view of agent DNA (config + workspace + bindings)
+- `edit` — Open agent workspace files in $EDITOR
+- `bind`/`unbind` — Wire agents to Discord channels
+- `clone` — Duplicate an agent
+- `activate`/`deactivate` — Agent lifecycle management
+- `destroy` — Full agent removal with safety guards
+- `migrate` — Workspace isolation migration
+- `export`/`import` — Share agents as .clawforge archives
+- `template` — Manage agent archetypes (list/show/create/delete)
+- `compat` — Fleet-wide model/tool compatibility (via clwatch)
+- `upgrade-check` — Tool upgrade recommendations (via clwatch)
+- `doctor` expanded with Fleet Health and Tool Versions sections
+
+### New: Built-in Archetypes
+- 5 templates: generalist, coder, monitor, researcher, communicator
+- {{PLACEHOLDER}} substitution for name, role, emoji
+
+### New: clwatch Integration
+- Optional enrichment — works without clwatch, smarter with it
+- Model compatibility checks during agent creation
+- Fleet-wide deprecation monitoring
+- Tool version tracking in doctor
+
+### Changed
+- `sprint`, `review`, `swarm` now show deprecation notice
+- Use `clawforge coding sprint|review|swarm` for explicit routing
+- README rewritten fleet-first
+- SKILL.md updated for OpenClaw fleet integration
+
+### Unchanged
+- All v1 coding workflow commands still work
+- Installation methods unchanged (brew, npm, uv, bun, source)
+
+---
+
+## v1.7.0 — clwatch Integration
+
+### clwatch Integration (requires clwatch)
+- New `clawforge changelog` command for tracking tool changelogs via clwatch
+- `changelog check` — one-shot update check
+  - Auto-patch reference files when tool capabilities change
+  - `--auto` flag for hands-free patching
+  - `--notify` sends Discord notification on changes
+  - `--webhook URL` POSTs changes to custom webhook
+- `changelog watch` — polling daemon mode
+  - Configurable interval (default: 6h, min: 15m)
+  - Integrates with `clawforge watch --daemon --changelog`
+- `changelog status` — show known vs current versions
+- `changelog ack <tool>` — acknowledge version as reviewed
+- New `patch-references.sh` standalone patcher utility
+  - Accepts clwatch JSON payload and patches reference files
+  - `--auto` and `--dry-run` modes
+- Graceful degradation: works standalone without clwatch installed
+- Reference file auto-detection: `~/.clawforge/references/`, `cwd/references/`, or custom `--refs-dir`
+- Integrates with existing `watch --daemon` via `--changelog` flag
+  - Runs changelog check on configured interval (default 6h)
+  - Auto-patches if `changelog_auto_patch` config is enabled
+
+### Config Additions
+- `changelog_check_interval`: How often daemon checks for updates (default: "6h")
+- `changelog_auto_patch`: Auto-patch without confirmation (default: false)
+- `changelog_refs_dir`: Custom references directory path (default: auto-detect)
+- `changelog_tools`: Comma-separated list of tools to monitor (default: "claude-code,codex-cli,gemini-cli,opencode,openclaw")
+
 ## v1.6.3 — npm Binary Download on Install
 
 ### Fixed

clawforge_cli-2.0.0/Formula/clawforge.rb

@@ -0,0 +1,37 @@
+class Clawforge < Formula
+  desc "Forge and manage fleets of OpenClaw agents"
+  homepage "https://github.com/cyperx84/clawforge"
+  url "https://github.com/cyperx84/clawforge/archive/refs/tags/v2.0.0.tar.gz"
+  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
+  license "MIT"
+  head "https://github.com/cyperx84/clawforge.git", branch: "main"
+
+  depends_on "jq"
+  depends_on "tmux"
+  depends_on "gh"
+
+  def install
+    # Install shell scripts
+    libexec.install Dir["bin/*"]
+    libexec.install Dir["lib"]
+    libexec.install Dir["tui"]
+    libexec.install Dir["config"]
+    libexec.install "VERSION"
+    libexec.install "registry"
+
+    # Create wrapper that sets CLAWFORGE_DIR
+    (bin/"clawforge").write <<~EOS
+      #!/bin/bash
+      export CLAWFORGE_DIR="#{libexec}"
+      exec "#{libexec}/clawforge" "$@"
+    EOS
+
+    # Dashboard binary
+    bin.install libexec/"clawforge-dashboard"
+  end
+
+  test do
+    assert_match "clawforge v", shell_output("#{bin}/clawforge version")
+    assert_match "Usage:", shell_output("#{bin}/clawforge help")
+  end
+end

clawforge_cli-2.0.0/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.4
+Name: clawforge-cli
+Version: 2.0.0
+Summary: Forge and manage fleets of OpenClaw agents
+Project-URL: Homepage, https://github.com/cyperx84/clawforge
+Project-URL: Repository, https://github.com/cyperx84/clawforge
+Author: cyperx84
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,fleet,openclaw,orchestration
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ClawForge
+
+```text
+   ________                ______
+  / ____/ /___ __      __ / ____/___  _________ ____
+ / /   / / __ `/ | /| / // /_  / __ \/ ___/ __ `/ _ \
+/ /___/ / /_/ /| |/ |/ // __/ / /_/ / /  / /_/ /  __/
+\____/_/\__,_/ |__/|__//_/    \____/_/   \__, /\___/
+                                         /____/
+```
+
+**Forge and manage fleets of OpenClaw agents.**
+
+Build agents, shape their identity, wire them to channels, deploy fleets — then run coding workflows or anything else.
+
+## Inspired By
+
+This project was inspired by [Elvis's "OpenClaw + Codex/Claude Code Agent Swarm" workflow](https://x.com/elvissun/article/2025920521871716562) — a battle-tested system for managing a fleet of AI coding agents.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Create an agent from a template
+clawforge create scout --from monitor --name Scout --role "External monitoring"
+
+# 2. Bind it to a Discord channel
+clawforge bind scout "#scout"
+
+# 3. Activate — adds to config and restarts gateway
+clawforge activate scout
+
+# Check your fleet
+clawforge list
+```
+
+---
+
+## Fleet Commands
+
+The primary interface. Everything starts here.
+
+| Command | Description |
+|---------|-------------|
+| `clawforge create <id>` | Interactive agent creation wizard |
+| `clawforge create <id> --from <archetype>` | Create from template (non-interactive) |
+| `clawforge list` | Fleet overview — all agents with status |
+| `clawforge inspect <id>` | Deep view: config, workspace, bindings |
+| `clawforge edit <id> --soul\|--agents\|--tools\|--heartbeat` | Edit workspace files |
+| `clawforge bind <id> <channel>` | Wire agent to Discord/Telegram/etc |
+| `clawforge unbind <id>` | Remove channel binding |
+| `clawforge clone <source> <new-id>` | Duplicate an agent |
+| `clawforge activate <id>` | Add to config + restart gateway |
+| `clawforge deactivate <id>` | Remove from config (keep files) |
+| `clawforge destroy <id>` | Full removal (requires `--yes`) |
+| `clawforge export <id>` | Package as shareable `.clawforge` archive |
+| `clawforge import <path\|url>` | Import from archive |
+| `clawforge migrate` | Workspace isolation migration |
+| `clawforge apply` | Alias for activate |
+| `clawforge doctor` | Fleet + system health check |
+| `clawforge compat` | Fleet-wide model/tool compatibility (via clwatch) |
+| `clawforge upgrade-check` | Tool update recommendations (via clwatch) |
+
+### `clawforge list` — Fleet Overview
+
+```
+🔨 ClawForge Fleet — 4 agents
+
+ ID          Name        Model              Channel      Status
+ ────────────────────────────────────────────────────────────────
+ main        Claw        gpt-5.4            #claw        ● active
+ builder     Builder     gpt-5.4            #builder     ● active
+ researcher  Researcher  gpt-5.4            #researcher  ● active
+ scout       Scout       gpt-5.4            —            ○ created
+
+ ● = active   ○ = created (not yet bound/activated)   ◌ = config-only
+```
+
+### `clawforge inspect <id>` — Agent DNA
+
+```
+🔧 Builder
+
+ Config
+ ──────────────────────────────────
+ ID:          builder
+ Model:       openai-codex/gpt-5.4
+ Workspace:   ~/.openclaw/agents/builder/
+ Channel:     discord #builder
+
+ Workspace Files
+ ──────────────────────────────────
+ SOUL.md          3.7 KB  ✓  Coding specialist, direct and practical
+ AGENTS.md        3.5 KB  ✓  Boot sequence with dispatch patterns
+ HEARTBEAT.md     168 B   ○  Empty
+```
+
+---
+
+## Templates & Archetypes
+
+ClawForge ships five built-in archetypes. Use them as starting points:
+
+| Archetype | Best For |
+|-----------|----------|
+| `generalist` | All-purpose, can orchestrate other agents |
+| `coder` | Code-focused, knows Claude Code / Codex dispatch patterns |
+| `monitor` | System/external monitoring with periodic health checks |
+| `researcher` | Deep research, synthesis, source citation |
+| `communicator` | Multi-channel messaging, notification routing |
+
+```bash
+# Create from built-in archetype
+clawforge create ops --from generalist
+
+# Preview an archetype
+clawforge template show coder
+
+# Save an existing agent as a reusable template
+clawforge template create my-coder-v2 --from builder
+
+# List all templates (built-in + yours)
+clawforge template list
+
+# Delete a user template
+clawforge template delete my-coder-v2
+```
+
+User templates live at `~/.clawforge/templates/`.  
+Built-in archetypes live at `config/archetypes/` in the ClawForge install dir.
+
+---
+
+## Export & Import (Agent Sharing)
+
+Share agents with your team or across machines.
+
+```bash
+# Package an agent (skips memory and USER.md by default)
+clawforge export builder
+# → builder.clawforge in current directory
+
+# Include memory files
+clawforge export builder --with-memory
+
+# Skip USER.md (private info)
+clawforge export builder --no-user
+
+# Custom output path
+clawforge export builder --output ~/share/builder-v2.clawforge
+
+# Import from file
+clawforge import builder.clawforge
+
+# Import from URL
+clawforge import https://example.com/releases/coder.clawforge
+
+# Non-interactive import
+clawforge import coder.clawforge --id my-coder --model anthropic/claude-sonnet-4-6
+```
+
+### What's in an archive
+
+```
+builder.clawforge (tar.gz)
+├── manifest.json   # agent id, name, model, archetype, dates, clawforge version
+├── SOUL.md
+├── AGENTS.md
+├── TOOLS.md
+├── IDENTITY.md
+├── HEARTBEAT.md
+└── references/     # optional context docs
+```
+
+Import creates workspace at `~/.openclaw/agents/<id>/`, prompts for ID and model, then shows next steps.
+
+---
+
+## clwatch Integration
+
+When [clwatch](https://github.com/cyperx84/clwatch) is installed, ClawForge gets richer:
+
+```bash
+# Fleet-wide model/tool compatibility check
+clawforge compat
+
+# Check for tool updates + fleet impact
+clawforge upgrade-check
+
+# Expanded doctor with tool version info
+clawforge doctor
+
+# Auto-patch agent reference files when tools update
+clawforge changelog check --auto
+clawforge changelog watch             # daemon: polls every 6h
+```
+
+```
+Fleet Compatibility Report
+────────────────────────────────────
+ Agent       Model        Harness Compat    Deprecations
+ main        gpt-5.4      codex ✓           none
+ builder     gpt-5.4      codex ✓ claude ✓  none
+```
+
+ClawForge works fully without clwatch. Install it to add compatibility checking, deprecation warnings, and auto-patching.
+
+```bash
+brew install cyperx84/tap/clwatch
+```
+
+---
+
+## Legacy Coding Workflows
+
+The original ClawForge sprint/review/swarm workflows are still available, now under the `coding` namespace.
+
+```bash
+# Preferred (v2.0+)
+clawforge coding sprint "Add JWT authentication"
+clawforge coding review --pr 42
+clawforge coding swarm "Migrate tests from jest to vitest"
+
+# Bare forms still work — deprecated, removed in v3.0
+clawforge sprint "Add JWT authentication"
+clawforge review --pr 42
+clawforge swarm "Migrate tests"
+```
+
+### Coding commands quick reference
+
+| Command | Description | Key Flags |
+|---------|-------------|-----------|
+| `coding sprint` | Single agent, full dev cycle | `--quick`, `--branch`, `--agent`, `--auto-merge` |
+| `coding review` | Quality gate on PR (analysis only) | `--pr`, `--fix`, `--reviewers` |
+| `coding swarm` | Parallel multi-agent orchestration | `--max-agents`, `--repos`, `--auto-merge` |
+| `coding steer` | Course-correct a running agent | (task ID, message) |
+| `coding attach` | Attach to agent's tmux session | (task ID) |
+| `coding stop` | Stop a running agent | `--yes`, `--clean` |
+
+Full docs: [`docs/workflow-modes.md`](./docs/workflow-modes.md)
+
+---
+
+## Installation
+
+| Method | Command | Best For |
+|--------|---------|----------|
+| Homebrew | `brew install cyperx84/tap/clawforge` | macOS users (recommended) |
+| npm | `npm install -g @cyperx84/clawforge` | Node.js users |
+| uv | `uv tool install clawforge` | Python users |
+| bun | `bun install -g @cyperx84/clawforge` | Bun users |
+| Source | See below | Development |
+
+### Homebrew (recommended for macOS)
+
+```bash
+brew tap cyperx84/tap
+brew install cyperx84/tap/clawforge
+```
+
+Upgrade later:
+
+```bash
+brew update && brew upgrade clawforge
+```
+
+### npm / bun
+
+```bash
+npm install -g @cyperx84/clawforge
+# or
+bun install -g @cyperx84/clawforge
+```
+
+### uv (Python)
+
+```bash
+uv tool install clawforge
+uv tool upgrade clawforge   # upgrade
+```
+
+### Source install
+
+```bash
+git clone https://github.com/cyperx84/clawforge.git
+cd clawforge
+./install.sh --openclaw
+```
+
+That command will:
+- symlink `clawforge` into `~/.local/bin`
+- wire up `SKILL.md` for OpenClaw
+- create missing directories if needed
+
+### Manual install
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf "$(pwd)/bin/clawforge" ~/.local/bin/clawforge
+
+# Optional OpenClaw skill wiring
+mkdir -p ~/.openclaw/skills/clawforge/scripts
+ln -sf "$(pwd)/SKILL.md" ~/.openclaw/skills/clawforge/SKILL.md
+ln -sf "$(pwd)/bin/clawforge" ~/.openclaw/skills/clawforge/scripts/clawforge
+```
+
+### Prerequisites
+
+- `bash` 4+, `jq`, `git`, `tmux`
+- `gh` (GitHub CLI, authenticated) — for coding workflow commands
+- `claude` and/or `codex` CLI — for coding workflow commands
+
+---
+
+## Configuration
+
+`config/defaults.json`:
+
+```json
+{
+  "fleet": {
+    "workspace_root": "~/.openclaw/agents",
+    "template_dir": "~/.clawforge/templates",
+    "default_model": "openai-codex/gpt-5.4",
+    "default_archetype": "generalist"
+  },
+  "clwatch": {
+    "auto_check": true,
+    "warn_on_deprecations": true,
+    "compat_check_on_create": true
+  },
+  "default_agent": "claude",
+  "default_model_claude": "claude-sonnet-4-5",
+  "default_model_codex": "gpt-5.3-codex",
+  "ci_retry_limit": 2
+}
+```
+
+---
+
+## Documentation
+
+Full docs in [`docs/`](./docs/README.md):
+
+- [Fleet Management](./docs/fleet-management.md)
+- [Archetypes Reference](./docs/archetypes.md)
+- [clwatch Integration](./docs/clwatch-integration.md)
+- [Coding Workflows](./docs/workflow-modes.md)
+- [Migration Guide](./docs/migration-guide.md)
+- [Command Reference](./docs/command-reference.md)
+- [Dashboard (Go TUI)](./docs/dashboard.md)
+- [Architecture](./docs/architecture.md)
+- [Configuration](./docs/configuration.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Changelog](./CHANGELOG.md)
+
+---
+
+## Testing
+
+```bash
+./tests/run-all-tests.sh
+
+# Phase 3 specific
+./tests/test-fleet-phase3.sh
+```