agentic-brownfield-coding

Claude Code Bashless Setup

Your goal is to amend an existing Claude Code project setup so that the agent no longer uses the built-in Bash tool. Instead, all essential CLI capabilities are exposed as structured MCP tools via a local MCP stdio server. This forces the agent to use purpose-built tools with explicit parameters rather than being attracted to unstructured shell access.

Additional user arguments: $ARGUMENTS

Language hint: Always create all generated script content and comments in English, while continuing to speak to the user in the language of their choice.

Platform hint: Instructions and templates assume a Linux host with GNU coreutils. Adapt to the detected user OS.

• macOS — Substitute BSD equivalents for GNU-only utilities.
• Windows — Still use .sh files (skip irrelevant chmod +x), assuming Git Bash is available at runtime.

Highlight this requirement in the Debriefing. Set "shell": "bash" on new command hooks in settings.json. Launch the MCP server via bash rather than putting the .sh path directly in command.

Workflow

1. Begin execution by creating a formal task list for progress tracking using the TaskCreate tool.

Create a task for each of the following phases (##) and sub-phases (###). Do not duplicate the contents in the description, only reference this skill (abc-init:bashless) and the workflow item.

1. Create a dependency chain between all tasks using TaskUpdate, setting addBlockedBy to the predecessor task.
2. Work through the TaskList using TaskUpdate to mark tasks as in_progress and completed as you go.

Phase 1: Reconnaissance

Catalogue shell commands and MCP tools the agent will require during autonomous code development for this project. Assume the project has already been initialized with artifacts for Claude Code and existing technology is documented.

1a — Shell Commands

Spawn an Agent to scan the following locations for explicit and implicit references to CLI commands:

1. The project's CLAUDE.md and any sub-directory CLAUDE.md files
2. The project's .claude directory, particularly sub-directories commands/, rules/ and agents/
3. Top-level documentation files (e.g. README.md, CONTRIBUTING.md, docs/)

Pay special attention to the following aspects:

• Execution wrappers — How commands are executed in general: directly, via Docker, NPX, Makefile, etc.
• Test runners — How are automated tests executed (e.g. pytest, jest, siesta, phpunit, go test)
• Linters/formatters — How is code quality ensured (e.g. eslint, ruff, phpcs)
• Build tools — Are builds executed manually and if so how (e.g. make, npm run build, cargo build)
• Framework CLIs — Project-specific console commands (e.g. artisan, manage.py, nx, laravel/symfony)

Use TaskCreate and TaskUpdate to add additional blocking tasks for files that need to be updated in Phase 3c below.

1b — MCP Tools

Spawn an Agent to summarize available MCP tools:

1. Read .mcp.json at the project root (if it exists) to identify existing project-registered servers.
2. Use the ToolSearch tool to query: "+mcp__" with high max_results to fetch schemas for all available MCP tools.
3. Return a full tool list, grouped by server (name pattern "mcp__<server>__"), with very short description per tool.
4. Highlight tools suitable for codebase exploration (e.g. IDE search tools, Code Index, symbol/semantic search).
5. Highlight tools that can read or edit files and could make the agent ignore the native Read/Write/Edit tools.

Phase 2: User Interview

Use AskUserQuestion during the following interview process to keep the conversation structured. Offer pre-defined choice options where possible based on reconnaissance findings.

2a — Git Write Permissions

Ask the user to which degree the agent should be able to participate in Git code submission:

• Read-only — The user reviews all code changes in the IDE and makes commits manually.

The agent only receives tools to explore and modify the current working tree (git_status, git_diff, git_rm, git_mv).

• Commit — The user reviews and amends finished commits by the agent and pushes them manually.

The agent receives read tools plus git_commit.

• Full — The agent can interact with git fully autonomously.

All of the above plus git_branch, git_checkout and git_push. If chosen, ask the user a follow-up question whether push to certain branches should be prohibited.

2b — CLI Tool Selection

Present the proposed list of project CLI tools to the user. For each tool, show:

• CLI application name
• Example command
• Proposed MCP tool name (e.g. git_log, npm_test) and parameters

Detect or ask the user whether a sandboxed execution wrapper is available on the system (e.g. bubblewrap on Linux, sandbox-exec on macOS).

• If sandboxing is available, suggest adding available read-only filesystem utilities (diff, jq).
• If sandboxing is unavailable but the user has explicitly requested such tools,

warn against the resulting security risks and offer to help with the installation of a respective sandboxing tool. If the user explicitly insists on proceeding with an unsandboxed setup, note this for Phase 3a and the debriefing.

Ask the user to:

1. Confirm, remove, or add tools
2. Suggest additional project-specific commands not detected automatically

2c — Codebase Exploration Tools

Determine whether you have access to MCP tools for codebase exploration (from reconnaissance phase 1b).

• If such tools exist: Ask the user whether they also wish to disable the native Glob and Grep

built-in tools, since the MCP alternatives may be superior in efficiency and speed.

• If no such tools exist: Inform the user that Glob and Grep will remain enabled as they are

essential for codebase navigation without Bash.

2d — MCP Tool Pruning

Explain to the user that many MCP servers expose a large number of tools indiscriminately, so disabling undesired and unnecessary tools helps the agent make better tool call decisions.

For each MCP server identified during reconnaissance phase 1b with more than ~5 tools:

1. Present a table of available tools with their short descriptions, grouped by server.
2. Ask the user to identify the tools they actively want to keep — or alternatively, tools they want to remove.

Recommendations:

• Advise to keep search/find tools (especially indexed/semantic/structural/symbolic search).
• Advise against redundant tools (overlapping functions) that make tool-choice less obvious.
• Warn about tools that can execute external actions such as IDE run configurations.

Important: Always recommend deactivation of tools that can read or edit/refactor files! These tools can tempt the agent to ignore native Read/Write/Edit tools which are important for the enforcement of rules, hooks and permission checks.

2e — Sandbox Configuration

Check whether the current .claude/settings.json contains a sandbox configuration block.

• If it does: Explain that the sandbox only restricts the Bash tool and has no effect when Bash is disabled.

Ask the user whether the sandbox block should be removed to reduce configuration noise.

• If it does not: Skip this question.

Phase 3: Generate Artifacts

3a — CLI MCP Server

1. Copy the [template](./templates/bash-commands-mcp.sh) to <project-dir>/.claude/mcp/bash-commands.sh and make it executable (chmod +x).
2. Adjust the command execution wrappers to match the project's execution environment.
3. Uncomment and adapt the run_local_sandboxed wrapper based on the target operating system,

independent of whether a sandboxing tool is actually installed, ensuring the function is available.

• Use run_local_sandboxed for all tools that locally execute arbitrary code or filesystem operations.
• Only fall back to run_local (unsandboxed