Add GateFlow local CLI and agent creation

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "gateflow",
       "description": "AI-powered hardware development platform \u2014 design, verify, synthesize, release, and deploy working RTL with natural language. 20 agents, 27 skills, 8 IP blocks.",
-      "version": "2.5.2",
+      "version": "2.5.3",
       "author": {
         "name": "codejunkie99",
         "github": "https://github.com/codejunkie99"

README.md

@@ -154,6 +154,23 @@ Skills activate automatically based on context:
 | `/gf-tui` | Open the local GateFlow terminal console |
 | `/gf-release` | Validate plugin release readiness |
 
+### Local CLI
+
+GateFlow also ships with a command-first local CLI for plugin maintenance and
+agent creation:
+
+```bash
+python3 tools/gateflow_cli.py status
+python3 tools/gateflow_cli.py agents list
+python3 tools/gateflow_cli.py agents create "CDC Reviewer" \
+  --role "clock-domain crossing reviewer" \
+  --description "Reviews synchronizers and CDC constraints"
+python3 tools/gateflow_cli.py shell
+python3 tools/gateflow_cli.py tui
+```
+
+Inside the TUI, press `a` to create a new agent without leaving the dashboard.
+
 ### Example Session
 
 ```
@@ -590,6 +607,7 @@ For detailed release notes, see [`releases.md`](releases.md).
 
 | Version | Date | What Changed |
 |---------|------|-------------|
+| **2.5.3** | 2026-05-21 | Command-first local CLI, interactive agent creation, and richer terminal colors |
 | **2.5.2** | 2026-05-21 | Responsive TUI layout for narrow terminal windows |
 | **2.5.1** | 2026-05-21 | TUI terminal compatibility fixes for cursor and colorless PTYs |
 | **2.5.0** | 2026-05-21 | OpenClaw-style CLI/TUI, release readiness workflow, deterministic validators, synced marketplace/docs/index/mirrors |

docs/gateflow.index

@@ -6,6 +6,9 @@ primary|CLAUDE.md|SV patterns, always_ff/comb, FSM, CDC, lint fixes, Spear/Tumbu
 primary|README.md|Installation, usage, features, component inventory
 primary|plugins/gateflow/README.md|Plugin-local overview and quick start
 primary|releases.md|Release notes and version history
+tools|tools/gateflow_cli.py|Command-first local CLI with status, shell, TUI, and agent creation
+tools|tools/gateflow_tui.py|Keyboard dashboard with semantic color and interactive agent creation
+tools|tools/validate_gateflow.py|Release metadata and package wiring validator
 
 commands|commands/gf-audit.md|Audit plugin quality and optionally auto-fix issues
 commands|commands/gf-boards.md|List supported FPGA boards and query pinouts

plugins/gateflow/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gateflow",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "description": "AI-powered hardware development platform \u2014 design, verify, synthesize, release, and deploy working RTL with natural language. 20 agents, 27 skills, 8 IP blocks.",
   "author": {
     "name": "codejunkie99",

plugins/gateflow/README.md

@@ -107,6 +107,21 @@ claude plugin add codejunkie99/Gateflow-Plugin
 | `/gf-tui` | Local terminal console |
 | `/gf-release` | Release readiness validation |
 
+### Local CLI
+
+From the repository root:
+
+```bash
+python3 tools/gateflow_cli.py status
+python3 tools/gateflow_cli.py agents list
+python3 tools/gateflow_cli.py agents create "CDC Reviewer" \
+  --role "clock-domain crossing reviewer" \
+  --description "Reviews synchronizers and CDC constraints"
+python3 tools/gateflow_cli.py shell
+```
+
+Inside the keyboard dashboard, press `a` to create a new agent.
+
 ### 8 Verified IP Blocks
 
 Every block ships with RTL + testbench + formal properties + docs.
@@ -205,6 +220,9 @@ claude plugin add codejunkie99/Gateflow-Plugin
 
 # Open terminal console
 /gf-tui
+
+# Use the local CLI
+python3 tools/gateflow_cli.py shell
 ```
 
 ---

plugins/gateflow/commands/gf-tui.md

@@ -9,7 +9,7 @@ allowed-tools:
 
 # GateFlow TUI Command
 
-Open the local GateFlow terminal console.
+Open the local GateFlow terminal console and local CLI.
 
 ## Usage
 
@@ -21,12 +21,25 @@ Open the local GateFlow terminal console.
 
 ## Execution
 
-Run from the repository root:
+Run the command-first CLI from the repository root:
+
+```bash
+python3 tools/gateflow_cli.py status
+python3 tools/gateflow_cli.py agents list
+python3 tools/gateflow_cli.py agents create "CDC Reviewer" \
+  --role "clock-domain crossing reviewer" \
+  --description "Reviews synchronizers and CDC constraints"
+python3 tools/gateflow_cli.py shell
+```
+
+Open the keyboard dashboard:
 
 ```bash
 python3 tools/gateflow_tui.py
 ```
 
+Inside the dashboard, press `a` to create a new agent.
+
 Use snapshot mode when running in a non-interactive terminal:
 
 ```bash
@@ -39,5 +52,6 @@ python3 tools/gateflow_tui.py --snapshot --plain
 - component inventory
 - local hardware tool health
 - map/release readiness
+- interactive agent creation
 - quick actions for `/gf-doctor`, `/gf-map`, `/gf-viz`, `/gf-lint`, `/gf-sim`,
   `/gf-formal`, and `/gf-release`

plugins/gateflow/skills/gf-tui/SKILL.md

@@ -24,6 +24,9 @@ Launch a local terminal console for GateFlow.
 
 | Mode | Command | Use When |
 |---|---|---|
+| CLI | `python3 tools/gateflow_cli.py status` | You want a normal command surface |
+| Shell | `python3 tools/gateflow_cli.py shell` | You want a local `gateflow>` prompt |
+| Agent create | `python3 tools/gateflow_cli.py agents create "Name"` | You need a new custom agent |
 | Interactive | `python3 tools/gateflow_tui.py` | You are in a real TTY and want keyboard navigation |
 | Snapshot | `python3 tools/gateflow_tui.py --snapshot --plain` | Logs, CI, or non-interactive terminals |
 | JSON | `python3 tools/gateflow_tui.py --json` | Scripts need machine-readable state |
@@ -32,6 +35,8 @@ Launch a local terminal console for GateFlow.
 
 - Local workspace mode by default; no gateway is required.
 - TTY-aware styling with plain and JSON fallbacks.
+- Command-first local CLI for status and agent management.
+- Press `a` in the dashboard to create a new agent interactively.
 - Health/status surfaces are visible before action.
 - Commands are shown as operator shortcuts rather than hidden docs.
 - Release and config repair loops stay inside the terminal workflow.
@@ -44,6 +49,7 @@ Launch a local terminal console for GateFlow.
    Yosys, and SymbiYosys availability.
 4. **Actions** — launch points for doctor, map, viz, lint, sim, formal, and
    release workflows.
+5. **Agent creation** — `a` opens prompts for name, role, and description.
 
 ## Guardrails
 
@@ -59,6 +65,8 @@ Run:
 
 ```bash
 python3 -m unittest tests/test_gateflow_tui.py
+python3 -m unittest tests/test_gateflow_cli.py
+python3 tools/gateflow_cli.py --plain status
 python3 tools/gateflow_tui.py --snapshot --plain
 python3 tools/gateflow_tui.py --json
 ```

releases.md

@@ -1,5 +1,22 @@
 # Releases
 
+## 2.5.3 (2026-05-21) — Command CLI + Agent Creation
+
+Patch release for making the local terminal surface behave like a real CLI.
+
+### New Features
+- Added `tools/gateflow_cli.py` with `status`, `tui`, `agents list`,
+  `agents create`, and `shell` subcommands.
+- Added local agent creation that writes Claude-compatible agent markdown under
+  `plugins/gateflow/agents/`.
+- Added `a` inside the TUI to create a new agent without leaving the dashboard.
+
+### Polish
+- Reworked terminal colors around semantic state: copper identity, cyan
+  headings/navigation, green ready states, amber warnings, and muted separators.
+- Added regression coverage for agent creation, CLI JSON status, shell help,
+  rich curses color-pair setup, and stacked health-row styles.
+
 ## 2.5.2 (2026-05-21) — Responsive TUI Layout
 
 Patch release for narrow terminal windows.

tests/test_gateflow_cli.py

@@ -0,0 +1,125 @@
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from io import StringIO
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+CLI = ROOT / "tools" / "gateflow_cli.py"
+
+
+def load_cli():
+    spec = importlib.util.spec_from_file_location("gateflow_cli", CLI)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class GateFlowCliTests(unittest.TestCase):
+    def test_create_agent_writes_claude_agent_file(self):
+        cli = load_cli()
+
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            result = cli.create_agent(
+                root=root,
+                name="Timing Closer",
+                role="timing closure specialist",
+                description="Closes timing on FPGA builds",
+                color="cyan",
+                tools=["Read", "Edit", "Bash"],
+                force=False,
+            )
+
+            self.assertEqual(root / "plugins/gateflow/agents/timing-closer.md", result.path)
+            content = result.path.read_text(encoding="utf-8")
+            self.assertIn("name: timing-closer", content)
+            self.assertIn("color: cyan", content)
+            self.assertIn("  - Bash", content)
+            self.assertIn("timing closure specialist", content)
+            self.assertIn("Closes timing on FPGA builds", content)
+
+    def test_cli_agents_create_outputs_created_path(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            completed = subprocess.run(
+                [
+                    sys.executable,
+                    str(CLI),
+                    "--root",
+                    tmp,
+                    "--plain",
+                    "agents",
+                    "create",
+                    "CDC Reviewer",
+                    "--role",
+                    "clock-domain crossing reviewer",
+                    "--description",
+                    "Reviews synchronizers and CDC constraints",
+                    "--tool",
+                    "Read",
+                    "--tool",
+                    "Grep",
+                ],
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+
+            self.assertEqual("", completed.stderr)
+            self.assertEqual(0, completed.returncode)
+            self.assertIn("created", completed.stdout)
+            self.assertIn("cdc-reviewer.md", completed.stdout)
+            self.assertTrue((Path(tmp) / "plugins/gateflow/agents/cdc-reviewer.md").exists())
+
+    def test_cli_status_json_returns_plugin_payload(self):
+        completed = subprocess.run(
+            [sys.executable, str(CLI), "--root", str(ROOT), "status", "--json"],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual("", completed.stderr)
+        self.assertEqual(0, completed.returncode)
+        payload = json.loads(completed.stdout)
+        self.assertEqual("gateflow", payload["plugin"]["name"])
+        self.assertIn("actions", payload)
+
+    def test_shell_help_mentions_agent_creation(self):
+        cli = load_cli()
+
+        help_text = cli.shell_help()
+
+        self.assertIn("create-agent", help_text)
+        self.assertIn("agents create", help_text)
+
+    def test_agents_list_clips_long_descriptions(self):
+        cli = load_cli()
+
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            cli.create_agent(
+                root=root,
+                name="Long Description Agent",
+                role="agent list display test",
+                description="Reviews " + "very " * 30 + "long agent descriptions",
+                color="green",
+                tools=["Read"],
+                force=False,
+            )
+            output = StringIO()
+
+            result = cli._print_agents(root, as_json=False, plain=True, output=output)
+
+            lines = output.getvalue().splitlines()
+            self.assertEqual(0, result)
+            self.assertLessEqual(max(len(line) for line in lines), 100)
+            self.assertIn("...", output.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()