Skip to content

Commit 8a2f323

Browse files
authored
Add GateFlow local CLI and agent creation (#11)
Add a command-first local CLI for GateFlow with status, shell, TUI launch, agent listing, and agent creation. - wire TUI shortcut `a` to create Claude-compatible agent markdown files - improve terminal color semantics for headings, status, selection, and footer - bump release metadata to v2.5.3 - cover CLI, agent creation, and color behavior with unit tests
1 parent 17c75fb commit 8a2f323

14 files changed

Lines changed: 770 additions & 43 deletions

File tree

.claude-plugin/marketplace.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
{
1111
"name": "gateflow",
1212
"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.",
13-
"version": "2.5.2",
13+
"version": "2.5.3",
1414
"author": {
1515
"name": "codejunkie99",
1616
"github": "https://github.com/codejunkie99"

README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,23 @@ Skills activate automatically based on context:
154154
| `/gf-tui` | Open the local GateFlow terminal console |
155155
| `/gf-release` | Validate plugin release readiness |
156156

157+
### Local CLI
158+
159+
GateFlow also ships with a command-first local CLI for plugin maintenance and
160+
agent creation:
161+
162+
```bash
163+
python3 tools/gateflow_cli.py status
164+
python3 tools/gateflow_cli.py agents list
165+
python3 tools/gateflow_cli.py agents create "CDC Reviewer" \
166+
--role "clock-domain crossing reviewer" \
167+
--description "Reviews synchronizers and CDC constraints"
168+
python3 tools/gateflow_cli.py shell
169+
python3 tools/gateflow_cli.py tui
170+
```
171+
172+
Inside the TUI, press `a` to create a new agent without leaving the dashboard.
173+
157174
### Example Session
158175

159176
```
@@ -590,6 +607,7 @@ For detailed release notes, see [`releases.md`](releases.md).
590607

591608
| Version | Date | What Changed |
592609
|---------|------|-------------|
610+
| **2.5.3** | 2026-05-21 | Command-first local CLI, interactive agent creation, and richer terminal colors |
593611
| **2.5.2** | 2026-05-21 | Responsive TUI layout for narrow terminal windows |
594612
| **2.5.1** | 2026-05-21 | TUI terminal compatibility fixes for cursor and colorless PTYs |
595613
| **2.5.0** | 2026-05-21 | OpenClaw-style CLI/TUI, release readiness workflow, deterministic validators, synced marketplace/docs/index/mirrors |

docs/gateflow.index

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ primary|CLAUDE.md|SV patterns, always_ff/comb, FSM, CDC, lint fixes, Spear/Tumbu
66
primary|README.md|Installation, usage, features, component inventory
77
primary|plugins/gateflow/README.md|Plugin-local overview and quick start
88
primary|releases.md|Release notes and version history
9+
tools|tools/gateflow_cli.py|Command-first local CLI with status, shell, TUI, and agent creation
10+
tools|tools/gateflow_tui.py|Keyboard dashboard with semantic color and interactive agent creation
11+
tools|tools/validate_gateflow.py|Release metadata and package wiring validator
912

1013
commands|commands/gf-audit.md|Audit plugin quality and optionally auto-fix issues
1114
commands|commands/gf-boards.md|List supported FPGA boards and query pinouts

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "gateflow",
3-
"version": "2.5.2",
3+
"version": "2.5.3",
44
"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.",
55
"author": {
66
"name": "codejunkie99",

plugins/gateflow/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,21 @@ claude plugin add codejunkie99/Gateflow-Plugin
107107
| `/gf-tui` | Local terminal console |
108108
| `/gf-release` | Release readiness validation |
109109

110+
### Local CLI
111+
112+
From the repository root:
113+
114+
```bash
115+
python3 tools/gateflow_cli.py status
116+
python3 tools/gateflow_cli.py agents list
117+
python3 tools/gateflow_cli.py agents create "CDC Reviewer" \
118+
--role "clock-domain crossing reviewer" \
119+
--description "Reviews synchronizers and CDC constraints"
120+
python3 tools/gateflow_cli.py shell
121+
```
122+
123+
Inside the keyboard dashboard, press `a` to create a new agent.
124+
110125
### 8 Verified IP Blocks
111126

112127
Every block ships with RTL + testbench + formal properties + docs.
@@ -205,6 +220,9 @@ claude plugin add codejunkie99/Gateflow-Plugin
205220

206221
# Open terminal console
207222
/gf-tui
223+
224+
# Use the local CLI
225+
python3 tools/gateflow_cli.py shell
208226
```
209227

210228
---

plugins/gateflow/commands/gf-tui.md

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ allowed-tools:
99

1010
# GateFlow TUI Command
1111

12-
Open the local GateFlow terminal console.
12+
Open the local GateFlow terminal console and local CLI.
1313

1414
## Usage
1515

@@ -21,12 +21,25 @@ Open the local GateFlow terminal console.
2121

2222
## Execution
2323

24-
Run from the repository root:
24+
Run the command-first CLI from the repository root:
25+
26+
```bash
27+
python3 tools/gateflow_cli.py status
28+
python3 tools/gateflow_cli.py agents list
29+
python3 tools/gateflow_cli.py agents create "CDC Reviewer" \
30+
--role "clock-domain crossing reviewer" \
31+
--description "Reviews synchronizers and CDC constraints"
32+
python3 tools/gateflow_cli.py shell
33+
```
34+
35+
Open the keyboard dashboard:
2536

2637
```bash
2738
python3 tools/gateflow_tui.py
2839
```
2940

41+
Inside the dashboard, press `a` to create a new agent.
42+
3043
Use snapshot mode when running in a non-interactive terminal:
3144

3245
```bash
@@ -39,5 +52,6 @@ python3 tools/gateflow_tui.py --snapshot --plain
3952
- component inventory
4053
- local hardware tool health
4154
- map/release readiness
55+
- interactive agent creation
4256
- quick actions for `/gf-doctor`, `/gf-map`, `/gf-viz`, `/gf-lint`, `/gf-sim`,
4357
`/gf-formal`, and `/gf-release`

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ Launch a local terminal console for GateFlow.
2424

2525
| Mode | Command | Use When |
2626
|---|---|---|
27+
| CLI | `python3 tools/gateflow_cli.py status` | You want a normal command surface |
28+
| Shell | `python3 tools/gateflow_cli.py shell` | You want a local `gateflow>` prompt |
29+
| Agent create | `python3 tools/gateflow_cli.py agents create "Name"` | You need a new custom agent |
2730
| Interactive | `python3 tools/gateflow_tui.py` | You are in a real TTY and want keyboard navigation |
2831
| Snapshot | `python3 tools/gateflow_tui.py --snapshot --plain` | Logs, CI, or non-interactive terminals |
2932
| JSON | `python3 tools/gateflow_tui.py --json` | Scripts need machine-readable state |
@@ -32,6 +35,8 @@ Launch a local terminal console for GateFlow.
3235

3336
- Local workspace mode by default; no gateway is required.
3437
- TTY-aware styling with plain and JSON fallbacks.
38+
- Command-first local CLI for status and agent management.
39+
- Press `a` in the dashboard to create a new agent interactively.
3540
- Health/status surfaces are visible before action.
3641
- Commands are shown as operator shortcuts rather than hidden docs.
3742
- Release and config repair loops stay inside the terminal workflow.
@@ -44,6 +49,7 @@ Launch a local terminal console for GateFlow.
4449
Yosys, and SymbiYosys availability.
4550
4. **Actions** — launch points for doctor, map, viz, lint, sim, formal, and
4651
release workflows.
52+
5. **Agent creation**`a` opens prompts for name, role, and description.
4753

4854
## Guardrails
4955

@@ -59,6 +65,8 @@ Run:
5965

6066
```bash
6167
python3 -m unittest tests/test_gateflow_tui.py
68+
python3 -m unittest tests/test_gateflow_cli.py
69+
python3 tools/gateflow_cli.py --plain status
6270
python3 tools/gateflow_tui.py --snapshot --plain
6371
python3 tools/gateflow_tui.py --json
6472
```

releases.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
# Releases
22

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

522
Patch release for narrow terminal windows.

tests/test_gateflow_cli.py

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
import importlib.util
2+
import json
3+
import subprocess
4+
import sys
5+
import tempfile
6+
import unittest
7+
from io import StringIO
8+
from pathlib import Path
9+
10+
11+
ROOT = Path(__file__).resolve().parents[1]
12+
CLI = ROOT / "tools" / "gateflow_cli.py"
13+
14+
15+
def load_cli():
16+
spec = importlib.util.spec_from_file_location("gateflow_cli", CLI)
17+
module = importlib.util.module_from_spec(spec)
18+
spec.loader.exec_module(module)
19+
return module
20+
21+
22+
class GateFlowCliTests(unittest.TestCase):
23+
def test_create_agent_writes_claude_agent_file(self):
24+
cli = load_cli()
25+
26+
with tempfile.TemporaryDirectory() as tmp:
27+
root = Path(tmp)
28+
result = cli.create_agent(
29+
root=root,
30+
name="Timing Closer",
31+
role="timing closure specialist",
32+
description="Closes timing on FPGA builds",
33+
color="cyan",
34+
tools=["Read", "Edit", "Bash"],
35+
force=False,
36+
)
37+
38+
self.assertEqual(root / "plugins/gateflow/agents/timing-closer.md", result.path)
39+
content = result.path.read_text(encoding="utf-8")
40+
self.assertIn("name: timing-closer", content)
41+
self.assertIn("color: cyan", content)
42+
self.assertIn(" - Bash", content)
43+
self.assertIn("timing closure specialist", content)
44+
self.assertIn("Closes timing on FPGA builds", content)
45+
46+
def test_cli_agents_create_outputs_created_path(self):
47+
with tempfile.TemporaryDirectory() as tmp:
48+
completed = subprocess.run(
49+
[
50+
sys.executable,
51+
str(CLI),
52+
"--root",
53+
tmp,
54+
"--plain",
55+
"agents",
56+
"create",
57+
"CDC Reviewer",
58+
"--role",
59+
"clock-domain crossing reviewer",
60+
"--description",
61+
"Reviews synchronizers and CDC constraints",
62+
"--tool",
63+
"Read",
64+
"--tool",
65+
"Grep",
66+
],
67+
text=True,
68+
capture_output=True,
69+
check=False,
70+
)
71+
72+
self.assertEqual("", completed.stderr)
73+
self.assertEqual(0, completed.returncode)
74+
self.assertIn("created", completed.stdout)
75+
self.assertIn("cdc-reviewer.md", completed.stdout)
76+
self.assertTrue((Path(tmp) / "plugins/gateflow/agents/cdc-reviewer.md").exists())
77+
78+
def test_cli_status_json_returns_plugin_payload(self):
79+
completed = subprocess.run(
80+
[sys.executable, str(CLI), "--root", str(ROOT), "status", "--json"],
81+
text=True,
82+
capture_output=True,
83+
check=False,
84+
)
85+
86+
self.assertEqual("", completed.stderr)
87+
self.assertEqual(0, completed.returncode)
88+
payload = json.loads(completed.stdout)
89+
self.assertEqual("gateflow", payload["plugin"]["name"])
90+
self.assertIn("actions", payload)
91+
92+
def test_shell_help_mentions_agent_creation(self):
93+
cli = load_cli()
94+
95+
help_text = cli.shell_help()
96+
97+
self.assertIn("create-agent", help_text)
98+
self.assertIn("agents create", help_text)
99+
100+
def test_agents_list_clips_long_descriptions(self):
101+
cli = load_cli()
102+
103+
with tempfile.TemporaryDirectory() as tmp:
104+
root = Path(tmp)
105+
cli.create_agent(
106+
root=root,
107+
name="Long Description Agent",
108+
role="agent list display test",
109+
description="Reviews " + "very " * 30 + "long agent descriptions",
110+
color="green",
111+
tools=["Read"],
112+
force=False,
113+
)
114+
output = StringIO()
115+
116+
result = cli._print_agents(root, as_json=False, plain=True, output=output)
117+
118+
lines = output.getvalue().splitlines()
119+
self.assertEqual(0, result)
120+
self.assertLessEqual(max(len(line) for line in lines), 100)
121+
self.assertIn("...", output.getvalue())
122+
123+
124+
if __name__ == "__main__":
125+
unittest.main()

0 commit comments

Comments
 (0)