UAT: Built-in tool names use hyphen-prefix format (`builtin/file-read`) but spec requires underscore format (`builtin/read_file`) — naming convention mismatch #4097

New issue

Open

opened 2026-04-06 10:20:57 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:20:57 +00:00

Owner

Metadata

Branch: fix/builtin-tool-naming-convention
Commit Message: fix(tool): align builtin tool names with spec naming convention
Milestone: (none — backlog)
Parent Epic: #392

Backlog note: This issue was discovered during UAT of the Built-in Tools feature area. It is placed in the backlog for human review and future milestone assignment.

Background and Context

The specification (docs/specification.md) consistently uses underscore-based naming for built-in tools, while the implementation uses a hyphen-with-prefix format. This creates a naming convention mismatch that will cause skill YAML files referencing spec-documented tool names to fail at runtime.

Current Behavior (Implementation)

The code in src/cleveragents/tool/builtins/ registers tools with these names:

File tools (file_tools.py):

builtin/file-read
builtin/file-write
builtin/file-edit
builtin/file-delete
builtin/file-list
builtin/file-search

Git tools (git_tools.py):

builtin/git-status
builtin/git-diff
builtin/git-log
builtin/git-blame

Expected Behavior (from spec)

The specification (docs/specification.md) consistently uses these names:

Skill YAML examples (lines 32797-32799):

tools:
  - name: builtin/read_file
  - name: builtin/list_directory
  - name: builtin/search_files

Git skill YAML examples (lines 32816-32819):

tools:
  - name: builtin/git_status
  - name: builtin/git_diff
  - name: builtin/git_log
  - name: builtin/git_blame

Skill tools table (lines 7240-7252):

read_file      builtin  local/file-ops  ✓  —  —
write_file     builtin  local/file-ops  —  ✓  file
edit_file      builtin  local/file-ops  —  ✓  file
delete_file    builtin  local/file-ops  —  ✓  file
list_directory builtin  local/file-ops  ✓  —  —
git_status     builtin  local/git-ops   ✓  —  —
git_diff       builtin  local/git-ops   ✓  —  —
git_log        builtin  local/git-ops   ✓  —  —
git_blame      builtin  local/git-ops   ✓  —  —

JSON output (lines 7329-7341):

{ "name": "read_file", "source": "builtin", ... }
{ "name": "write_file", "source": "builtin", ... }
{ "name": "git_status", "source": "builtin", ... }

The spec also references builtin/shell_execute (not builtin/shell-execute).

Impact

Any skill YAML file that references built-in tools using the spec-documented names (e.g., builtin/read_file) will fail to resolve because the registry contains builtin/file-read instead. This is a breaking discrepancy between documentation and implementation.

The test fixtures in features/steps/skill_cli_steps.py and robot/helper_skill_cli.py already use builtin/shell_execute (underscore format), confirming the spec's intent.

Code Locations

src/cleveragents/tool/builtins/file_tools.py — FILE_READ_SPEC.name = "builtin/file-read" (should be "builtin/read_file")
src/cleveragents/tool/builtins/file_tools.py — all 6 file tool names use hyphen format
src/cleveragents/tool/builtins/git_tools.py — all 4 git tool names use hyphen format
src/cleveragents/tool/builtins/__init__.py — exports use old names
features/builtin_adapter.feature — tests reference builtin/file-read, builtin/git-status (will need updating)
features/tool_builtins.feature — tests reference builtin/file-read etc. (will need updating)
features/git_tools.feature — tests reference builtin/git-status etc. (will need updating)
docs/specification.md lines 32797-32819 — spec uses underscore format

Subtasks

Rename all file tool specs in file_tools.py: builtin/file-read → builtin/read_file, builtin/file-write → builtin/write_file, builtin/file-edit → builtin/edit_file, builtin/file-delete → builtin/delete_file, builtin/file-list → builtin/list_directory, builtin/file-search → builtin/search_files
Rename all git tool specs in git_tools.py: builtin/git-status → builtin/git_status, builtin/git-diff → builtin/git_diff, builtin/git-log → builtin/git_log, builtin/git-blame → builtin/git_blame
Update src/cleveragents/tool/builtins/__init__.py exports to use new names
Update all Behave feature files that reference old tool names
Update features/builtin_adapter.feature expected tool names
Run nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e coverage_report

Definition of Done

All built-in tool names match the spec's underscore format
Skill YAML referencing builtin/read_file, builtin/git_status, etc. resolves correctly
All Behave tests updated to use new names
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/builtin-tool-naming-convention` - **Commit Message**: `fix(tool): align builtin tool names with spec naming convention` - **Milestone**: *(none — backlog)* - **Parent Epic**: #392 > **Backlog note:** This issue was discovered during UAT of the Built-in Tools feature area. It is placed in the backlog for human review and future milestone assignment. ## Background and Context The specification (`docs/specification.md`) consistently uses **underscore-based naming** for built-in tools, while the implementation uses a **hyphen-with-prefix format**. This creates a naming convention mismatch that will cause skill YAML files referencing spec-documented tool names to fail at runtime. ## Current Behavior (Implementation) The code in `src/cleveragents/tool/builtins/` registers tools with these names: **File tools** (`file_tools.py`): - `builtin/file-read` - `builtin/file-write` - `builtin/file-edit` - `builtin/file-delete` - `builtin/file-list` - `builtin/file-search` **Git tools** (`git_tools.py`): - `builtin/git-status` - `builtin/git-diff` - `builtin/git-log` - `builtin/git-blame` ## Expected Behavior (from spec) The specification (`docs/specification.md`) consistently uses these names: **Skill YAML examples** (lines 32797-32799): ```yaml tools: - name: builtin/read_file - name: builtin/list_directory - name: builtin/search_files ``` **Git skill YAML examples** (lines 32816-32819): ```yaml tools: - name: builtin/git_status - name: builtin/git_diff - name: builtin/git_log - name: builtin/git_blame ``` **Skill tools table** (lines 7240-7252): ``` read_file builtin local/file-ops ✓ — — write_file builtin local/file-ops — ✓ file edit_file builtin local/file-ops — ✓ file delete_file builtin local/file-ops — ✓ file list_directory builtin local/file-ops ✓ — — git_status builtin local/git-ops ✓ — — git_diff builtin local/git-ops ✓ — — git_log builtin local/git-ops ✓ — — git_blame builtin local/git-ops ✓ — — ``` **JSON output** (lines 7329-7341): ```json { "name": "read_file", "source": "builtin", ... } { "name": "write_file", "source": "builtin", ... } { "name": "git_status", "source": "builtin", ... } ``` The spec also references `builtin/shell_execute` (not `builtin/shell-execute`). ## Impact Any skill YAML file that references built-in tools using the spec-documented names (e.g., `builtin/read_file`) will fail to resolve because the registry contains `builtin/file-read` instead. This is a breaking discrepancy between documentation and implementation. The test fixtures in `features/steps/skill_cli_steps.py` and `robot/helper_skill_cli.py` already use `builtin/shell_execute` (underscore format), confirming the spec's intent. ## Code Locations - `src/cleveragents/tool/builtins/file_tools.py` — `FILE_READ_SPEC.name = "builtin/file-read"` (should be `"builtin/read_file"`) - `src/cleveragents/tool/builtins/file_tools.py` — all 6 file tool names use hyphen format - `src/cleveragents/tool/builtins/git_tools.py` — all 4 git tool names use hyphen format - `src/cleveragents/tool/builtins/__init__.py` — exports use old names - `features/builtin_adapter.feature` — tests reference `builtin/file-read`, `builtin/git-status` (will need updating) - `features/tool_builtins.feature` — tests reference `builtin/file-read` etc. (will need updating) - `features/git_tools.feature` — tests reference `builtin/git-status` etc. (will need updating) - `docs/specification.md` lines 32797-32819 — spec uses underscore format ## Subtasks - [ ] Rename all file tool specs in `file_tools.py`: `builtin/file-read` → `builtin/read_file`, `builtin/file-write` → `builtin/write_file`, `builtin/file-edit` → `builtin/edit_file`, `builtin/file-delete` → `builtin/delete_file`, `builtin/file-list` → `builtin/list_directory`, `builtin/file-search` → `builtin/search_files` - [ ] Rename all git tool specs in `git_tools.py`: `builtin/git-status` → `builtin/git_status`, `builtin/git-diff` → `builtin/git_diff`, `builtin/git-log` → `builtin/git_log`, `builtin/git-blame` → `builtin/git_blame` - [ ] Update `src/cleveragents/tool/builtins/__init__.py` exports to use new names - [ ] Update all Behave feature files that reference old tool names - [ ] Update `features/builtin_adapter.feature` expected tool names - [ ] Run `nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report` ## Definition of Done - [ ] All built-in tool names match the spec's underscore format - [ ] Skill YAML referencing `builtin/read_file`, `builtin/git_status`, etc. resolves correctly - [ ] All Behave tests updated to use new names - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:21:48 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-06 10:22:15 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:22:43 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label