diff --git a/core/README.md b/core/README.md index fee25ca2..38cdfa92 100644 --- a/core/README.md +++ b/core/README.md @@ -145,7 +145,7 @@ uv run python -m framework test-debug uv run python -m framework test-list ``` -For detailed testing workflows, see the [hive-test skill](../.claude/skills/hive-test/SKILL.md). +For detailed testing workflows, see [developer-guide.md](../docs/developer-guide.md). ### Analyzing Agent Behavior with Builder diff --git a/core/framework/runtime/RUNTIME_LOGGING.md b/core/framework/runtime/RUNTIME_LOGGING.md index 945dcbc7..e021740c 100644 --- a/core/framework/runtime/RUNTIME_LOGGING.md +++ b/core/framework/runtime/RUNTIME_LOGGING.md @@ -561,7 +561,7 @@ The runtime logger automatically flags issues based on execution metrics: ### Attention Categories -Used by `/hive-debugger` skill for issue categorization: +Used for runtime issue categorization: 1. **Missing Outputs**: Node didn't set required output keys 2. **Tool Errors**: Tool calls failed (API errors, timeouts) @@ -690,7 +690,7 @@ rm -rf session_2025* **Documentation:** - `EXECUTION_STORAGE_REDESIGN.md` - Unified session storage design -- `/.claude/skills/hive-debugger/SKILL.md` - Interactive debugging skill +- `docs/developer-guide.md` - Debugging and troubleshooting workflows **Related:** - `core/framework/schemas/session_state.py` - Session state schema diff --git a/docs/antigravity-setup.md b/docs/antigravity-setup.md index e99e27cf..e3dfa556 100644 --- a/docs/antigravity-setup.md +++ b/docs/antigravity-setup.md @@ -25,7 +25,7 @@ Done. For details, prerequisites, and troubleshooting, read on. - **agent-builder** – Create and manage agents (goals, nodes, edges). - **tools** – File operations, web search, and other agent tools. -- **Skills** – Guided docs for building and testing agents (in `.agent/skills/` or `.claude/skills/`). +- **Documentation** – Guided docs for building and testing agents. --- @@ -80,18 +80,9 @@ That writes `~/.claude/mcp.json` as well. **Prefer to do it manually?** See [Manual MCP config](#manual-mcp-config-template) below. You’ll create `~/.gemini/mcp.json` (or `~/.claude/mcp.json`) with absolute paths to your repo’s `core` and `tools` folders. -### Step 3: Use skills +### Step 3: Use MCP tools + docs -Skills are guides (workflow, building, testing) in `.agent/skills/` (they point to `.claude/skills/`). If Antigravity doesn’t show a “skills” UI, open those folders in the project and use the files as reference while you use the MCP tools. - -| Skill | What it's for | -|-------|----------------| -| **hive** | End-to-end workflow for building and testing agents | -| **hive-concepts** | Core ideas for goal-driven agents | -| **hive-create** | Step-by-step agent construction | -| **hive-patterns** | Patterns and best practices | -| **hive-test** | Goal-based evaluation and testing | -| **hive-credentials** | Set up and manage agent credentials | +Use the `agent-builder` and `tools` MCP servers in Antigravity, and use docs in `docs/` for workflow guidance. --- @@ -100,7 +91,6 @@ Skills are guides (workflow, building, testing) in `.agent/skills/` (they point ``` .agent/ ├── mcp_config.json # Template for MCP servers (agent-builder, tools) -└── skills/ # Symlinks to .claude/skills/ ``` The **setup script** writes your **user** config (`~/.gemini/antigravity/mcp_config.json`) using paths from **this repo**. The file in `.agent/` is the template; Antigravity itself uses the file in your home directory. @@ -123,24 +113,24 @@ The **setup script** writes your **user** config (`~/.gemini/antigravity/mcp_con - Open the **repo root** as the project in the IDE (the folder that has `core/` and `tools/`). - If you edited `~/.gemini/antigravity/mcp_config.json` by hand, make sure `--directory` paths are **absolute** (e.g. `/Users/you/hive/core` and `/Users/you/hive/tools`). -**Skills don’t show up in the UI** +**MCP tools don’t show up in the UI** -- Antigravity may not have a dedicated “skills” panel. Use the files in `.claude/skills/` or `.agent/skills/` as docs; the MCP tools (agent-builder, tools) still work. +- Antigravity may need a restart. Use the files in `docs/` as documentation; the MCP tools (`agent-builder`, `tools`) are the required integration point. --- ## Verification prompt (optional) -Paste this into Antigravity to check that MCP and skills are set up. It doesn’t use your machine’s paths; anyone can use it. +Paste this into Antigravity to check that MCP is set up. It doesn’t use your machine’s paths; anyone can use it. ``` Check the Hive + Antigravity integration: 1. MCP: List available MCP servers/tools. Confirm that "agent-builder" and "tools" (or equivalent) are connected. If not, tell the user to run ./scripts/setup-antigravity-mcp.sh from the hive repo root, then restart Antigravity (see docs/antigravity-setup.md). -2. Skills: Confirm that the project has .agent/skills/ (or .claude/skills/) with: hive, hive-concepts, hive-create, hive-patterns, hive-test, hive-credentials. +2. Docs: Confirm that the project has `docs/` with setup/developer guides for the workflow. -3. Result: Reply with PASS (MCP + skills OK), PARTIAL (only skills or only MCP), or FAIL (neither), and one line on what to fix if not PASS. +3. Result: Reply with PASS (MCP OK), PARTIAL (some MCP tools missing), or FAIL (MCP unavailable), and one line on what to fix if not PASS. ``` If you get **PARTIAL** (e.g. MCP not connected), run `./scripts/setup-antigravity-mcp.sh` from the repo root and restart Antigravity. @@ -178,13 +168,10 @@ Make sure `uv` is installed and available in your PATH. Note: Use `--directory` From the **repo root**: -**Check that config and skills exist** +**Check that config exists** ```bash test -f .agent/mcp_config.json && echo "OK: mcp_config.json" || echo "MISSING" -for s in hive hive-concepts hive-create hive-patterns hive-test hive-credentials; do - test -L .agent/skills/$s && test -d .agent/skills/$s && echo "OK: $s" || echo "BROKEN: $s" -done ``` **Check that the config is valid JSON** diff --git a/docs/cleanup-plan.md b/docs/cleanup-plan.md index 8ded231f..d63a2104 100644 --- a/docs/cleanup-plan.md +++ b/docs/cleanup-plan.md @@ -38,7 +38,7 @@ | File | Action | |---|---| -| `.claude/skills/hive-create/SKILL.md` | Remove `"function"` from node type table (~L495, L856) | +| `docs/developer-guide.md` | Remove `"function"` from node type table (~L495, L856) | | `docs/developer-guide.md` | Remove `"function"` node type reference (~L613) | | `core/MCP_SERVER_GUIDE.md` | Audit for `"function"` references | | `docs/why-conditional-edge-priority.md` | Remove or repurpose (entire doc framed around function nodes) | diff --git a/docs/contributing-lint-setup.md b/docs/contributing-lint-setup.md index 92a72ca1..020496ab 100644 --- a/docs/contributing-lint-setup.md +++ b/docs/contributing-lint-setup.md @@ -104,11 +104,11 @@ The `.cursorrules` file at the repo root tells Cursor's AI the project's style r ### Antigravity IDE -Antigravity IDE (Google's AI-powered IDE) is supported via `.antigravity/mcp_config.json` and `.antigravity/skills/` (symlinks to `.claude/skills/`). See [antigravity-setup.md](antigravity-setup.md) for setup and troubleshooting. +Antigravity IDE (Google's AI-powered IDE) is supported via `.antigravity/mcp_config.json`. See [antigravity-setup.md](antigravity-setup.md) for setup and troubleshooting. ### Codex CLI -Codex CLI (OpenAI, v0.101.0+) is supported via `.codex/config.toml` (MCP server config) and `.agents/skills/` (symlinks to `.claude/skills/`). These files are tracked in git. Run `codex` in the repo root and type `use hive` to start. See the [Codex CLI section in the README](../README.md#codex-cli) for details. +Codex CLI (OpenAI, v0.101.0+) is supported via `.codex/config.toml` (MCP server config). This file is tracked in git. Run `codex` in the repo root to use the configured MCP tools. See the [Codex CLI section in the README](../README.md#codex-cli) for details. --- diff --git a/docs/developer-guide.md b/docs/developer-guide.md index 4c60187d..84646a20 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -101,22 +101,16 @@ Get API keys: ./quickstart.sh ``` -This installs agent-related Claude Code skills: - -- `/hive` - Complete workflow for building agents -- `/hive-create` - Step-by-step agent building -- `/hive-concepts` - Fundamental agent concepts -- `/hive-patterns` - Best practices and design patterns -- `/hive-test` - Test and validate agents +This sets up agent-builder and tools MCP workflows. ### Cursor IDE Support -Skills are also available in Cursor. To enable: +MCP tools are also available in Cursor. To enable: 1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) 2. Run `MCP: Enable` to enable MCP servers 3. Restart Cursor to load the MCP servers from `.cursor/mcp.json` -4. Type `/` in Agent chat and search for skills (e.g., `/hive-create`) +4. Open Agent chat and verify MCP tools are available ### Codex CLI Support @@ -124,15 +118,14 @@ Hive supports [OpenAI Codex CLI](https://github.com/openai/codex) (v0.101.0+). Configuration files are tracked in git: - `.codex/config.toml` — MCP server config (`agent-builder`) -- `.agents/skills/` — Symlinks to Hive skills To use Codex with Hive: 1. Run `codex` in the repo root -2. Type `use hive` to start the agent workflow +2. Start the configured MCP-assisted workflow Example: ``` -codex> use hive +Start Codex in the repo root and use the configured MCP tools ``` @@ -153,7 +146,7 @@ uv run python -c "import framework; print('✓ framework OK')" uv run python -c "import aden_tools; print('✓ aden_tools OK')" uv run python -c "import litellm; print('✓ litellm OK')" -# Run an agent (after building one via /hive-create) +# Run an agent (after building one with agent-builder) PYTHONPATH=exports uv run python -m your_agent_name validate ``` @@ -176,17 +169,8 @@ hive/ # Repository root │ ├── PULL_REQUEST_TEMPLATE.md # PR description template │ └── CODEOWNERS # Auto-assign reviewers │ -├── .claude/ # Claude Code Skills -│ └── skills/ # Skills for building -│ ├── hive/ # Complete workflow -│ ├── hive-create/ # Step-by-step build guide -│ ├── hive-concepts/ # Fundamental concepts -│ ├── hive-patterns/ # Best practices -│ └── hive-test/ # Test and validate agents ├── .codex/ # Codex CLI project config │ └── config.toml # Codex MCP server definitions -├── .agents/ # Shared skill mountpoint -│ └── skills/ # Symlinks to Hive skills │ ├── core/ # CORE FRAMEWORK PACKAGE │ ├── framework/ # Main package code @@ -222,7 +206,7 @@ hive/ # Repository root │ └── README.md # Tools documentation │ ├── exports/ # AGENT PACKAGES (user-created, gitignored) -│ └── your_agent_name/ # Created via /hive-create +│ └── your_agent_name/ # Created via agent-builder workflow │ ├── examples/ # Example agents │ └── templates/ # Pre-built template agents @@ -251,19 +235,16 @@ hive/ # Repository root ## Building Agents -### Using Claude Code Skills +### Using Agent Builder Workflow -The fastest way to build agents is using the Claude Code skills: +The fastest way to build agents is with the configured MCP workflow: ```bash -# Install skills (one-time) +# Install dependencies (one-time) ./quickstart.sh # Build a new agent -claude> /hive - -# Test the agent -claude> /hive-test +Use the agent-builder MCP tools from your IDE agent chat ``` ### Agent Development Workflow @@ -271,19 +252,19 @@ claude> /hive-test 1. **Define Your Goal** ``` - claude> /hive + Use the agent-builder workflow Enter goal: "Build an agent that processes customer support tickets" ``` 2. **Design the Workflow** - - The skill guides you through defining nodes + - The workflow guides you through defining nodes - Each node is a unit of work (LLM call with event_loop) - Edges define how execution flows 3. **Generate the Agent** - - The skill generates a complete Python package in `exports/` + - The workflow generates a complete Python package in `exports/` - Includes: `agent.json`, `tools.py`, `README.md` 4. **Validate the Agent** @@ -293,8 +274,9 @@ claude> /hive-test ``` 5. **Test the Agent** - ``` - claude> /hive-test + Run tests with: + ```bash + PYTHONPATH=exports uv run python -m your_agent_name test ``` ### Manual Agent Development @@ -351,11 +333,11 @@ hive run exports/my_agent --tui ## Testing Agents -### Using the Testing Agent Skill +### Using Built-in Test Commands ```bash # Run tests for an agent -claude> /hive-test +PYTHONPATH=exports uv run python -m agent_name test ``` This generates and runs: @@ -573,7 +555,7 @@ uv add ```bash # Option 1: Use Claude Code skill (recommended) -claude> /hive +Use the agent-builder workflow # Option 2: Create manually # Note: exports/ is initially empty (gitignored). Create your agent directory: diff --git a/docs/environment-setup.md b/docs/environment-setup.md index 11aec14c..0b316975 100644 --- a/docs/environment-setup.md +++ b/docs/environment-setup.md @@ -112,7 +112,7 @@ uv run python -c "import litellm; print('✓ litellm OK')" ### API Keys -We recommend using quickstart.sh for LLM API credential setup and /hive-credentials for the tools credentials +We recommend using `quickstart.sh` for LLM API credential setup and the credentials UI/tooling for tool credentials. ## Running Agents @@ -165,33 +165,27 @@ Build and run an agent using Claude Code CLI with the agent building skills: ./quickstart.sh ``` -This verifies agent-related Claude Code skills are available: - -- `/hive` - Complete workflow for building agents -- `/hive-create` - Step-by-step build guide -- `/hive-concepts` - Fundamental concepts -- `/hive-patterns` - Best practices -- `/hive-test` - Test and validate agents +This sets up agent-builder and tools MCP workflows. ### Cursor IDE Support -Skills are also available in Cursor. To enable: +MCP tools are also available in Cursor. To enable: 1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) 2. Run `MCP: Enable` to enable MCP servers 3. Restart Cursor to load the MCP servers from `.cursor/mcp.json` -4. Type `/` in Agent chat and search for skills (e.g., `/hive-create`) +4. Open Agent chat and verify MCP tools are available ### 2. Build an Agent **Claude Code:** ``` -claude> /hive +Use the agent-builder workflow ``` **Codex CLI:** ``` -codex> use hive +Start Codex in the repo root and use the configured MCP tools ``` Follow the prompts to: @@ -206,7 +200,7 @@ This step creates the initial agent structure required for further development. ### 3. Define Agent Logic ``` -claude> /hive-concepts +claude> architecture guidance ``` Follow the prompts to: @@ -221,7 +215,7 @@ This step establishes the core concepts and rules needed before building an agen ### 4. Apply Agent Patterns ``` -claude> /hive-patterns +claude> pattern guidance ``` Follow the prompts to: @@ -236,7 +230,7 @@ This step helps optimize agent design before final testing. ### 5. Test Your Agent ``` -claude> /hive-test +claude> test workflow ``` Follow the prompts to: @@ -367,7 +361,7 @@ hive/ │ └── pyproject.toml │ ├── exports/ # Agent packages (user-created, gitignored) -│ └── your_agent_name/ # Created via /hive-create +│ └── your_agent_name/ # Created via agent-builder workflow │ └── examples/ └── templates/ # Pre-built template agents @@ -459,7 +453,7 @@ This design allows agents in `exports/` to be: ### 2. Build Agent (Claude Code) ``` -claude> /hive +Use the agent-builder workflow Enter goal: "Build an agent that processes customer support tickets" ``` @@ -472,7 +466,7 @@ PYTHONPATH=exports uv run python -m your_agent_name validate ### 4. Test Agent ``` -claude> /hive-test +claude> test workflow ``` ### 5. Run Agent @@ -545,18 +539,17 @@ Run the quickstart script in the root directory: [OpenAI Codex CLI](https://github.com/openai/codex) (v0.101.0+) is supported with project-level config: - `.codex/config.toml` — MCP server configuration (`agent-builder`) -- `.agents/skills/` — Symlinks to Hive skills These files are tracked in git and available on clone. To use Codex with Hive: 1. Run `codex` in the repo root -2. Type `use hive` to start the agent workflow +2. Start the configured MCP-assisted workflow Quick verification: ```bash test -f .codex/config.toml && echo "OK: Codex config" || echo "MISSING: .codex/config.toml" -test -d .agents/skills/hive && echo "OK: Skills" || echo "MISSING: .agents/skills/" +echo "OK: .codex/config.toml and MCP tools configured" ``` ## Additional Resources @@ -564,8 +557,8 @@ test -d .agents/skills/hive && echo "OK: Skills" || echo "MISSING: .agents/skill - **Framework Documentation:** [core/README.md](../core/README.md) - **Tools Documentation:** [tools/README.md](../tools/README.md) - **Example Agents:** [examples/](../examples/) -- **Agent Building Guide:** [.claude/skills/hive-create/SKILL.md](../.claude/skills/hive-create/SKILL.md) -- **Testing Guide:** [.claude/skills/hive-test/SKILL.md](../.claude/skills/hive-test/SKILL.md) +- **Agent Building Guide:** [docs/developer-guide.md](./developer-guide.md) +- **Testing Guide:** [core/README.md](../core/README.md) ## Contributing @@ -574,7 +567,7 @@ When contributing agent packages: 1. Place agents in `exports/agent_name/` 2. Follow the standard agent structure (see existing agents) 3. Include README.md with usage instructions -4. Add tests if using `/hive-test` +4. Add tests if using `test workflow` 5. Document required environment variables ## Support diff --git a/docs/getting-started.md b/docs/getting-started.md index 88fb46f0..d3424605 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -47,7 +47,7 @@ This is the recommended way to create your first agent. # Setup already done via quickstart.sh above # Start Claude Code and build an agent -claude> /hive +Use the agent-builder workflow ``` Follow the interactive prompts to: @@ -115,19 +115,11 @@ hive/ │ └── file_system_toolkits/ │ ├── exports/ # Agent Packages (user-generated, not in repo) -│ └── your_agent/ # Your agents created via /hive +│ └── your_agent/ # Your agents created via agent-builder workflow │ ├── examples/ │ └── templates/ # Pre-built template agents │ -├── .claude/ # Claude Code Skills -│ └── skills/ -│ ├── hive/ -│ ├── hive-create/ -│ ├── hive-concepts/ -│ ├── hive-patterns/ -│ └── hive-test/ -│ └── docs/ # Documentation ``` @@ -165,10 +157,7 @@ Get your API keys: ## Testing Your Agent ```bash -# Using Claude Code -claude> /hive-test - -# Or manually +# Run tests PYTHONPATH=exports uv run python -m my_agent test # Run with specific test type @@ -181,7 +170,7 @@ PYTHONPATH=exports uv run python -m my_agent test --type success 1. **TUI Dashboard**: Run `hive tui` to explore agents interactively 2. **Detailed Setup**: See [environment-setup.md](./environment-setup.md) 3. **Developer Guide**: See [developer-guide.md](./developer-guide.md) -4. **Build Agents**: Use `/hive` skill in Claude Code +4. **Build Agents**: Use agent-builder workflow in Claude Code 5. **Custom Tools**: Learn to integrate MCP servers 6. **Join Community**: [Discord](https://discord.com/invite/MXE49hrKDk) @@ -224,4 +213,4 @@ pip uninstall -y framework tools - **Documentation**: Check the `/docs` folder - **Issues**: [github.com/adenhq/hive/issues](https://github.com/adenhq/hive/issues) - **Discord**: [discord.com/invite/MXE49hrKDk](https://discord.com/invite/MXE49hrKDk) -- **Build Agents**: Use `/hive` skill to create agents +- **Build Agents**: Use agent-builder workflow to create agents diff --git a/examples/templates/README.md b/examples/templates/README.md index f2899465..00139d64 100644 --- a/examples/templates/README.md +++ b/examples/templates/README.md @@ -22,7 +22,7 @@ template_name/ ### Option 1: Build from template (recommended) -Use the `/hive-create` skill and select "From a template" to interactively pick a template, customize the goal/nodes/graph, and export a new agent. +Use the agent-builder workflow and select "From a template" to interactively pick a template, customize the goal/nodes/graph, and export a new agent. ### Option 2: Manual copy diff --git a/quickstart.sh b/quickstart.sh index f54ce772..cdae5088 100755 --- a/quickstart.sh +++ b/quickstart.sh @@ -1204,14 +1204,6 @@ else echo -e "${YELLOW}--${NC}" fi -echo -n " ⬡ skills... " -if [ -d "$SCRIPT_DIR/.claude/skills" ]; then - SKILL_COUNT=$(ls -1d "$SCRIPT_DIR/.claude/skills"/*/ 2>/dev/null | wc -l) - echo -e "${GREEN}${SKILL_COUNT} found${NC}" -else - echo -e "${YELLOW}--${NC}" -fi - echo -n " ⬡ codex CLI... " if command -v codex > /dev/null 2>&1; then CODEX_VERSION=$(codex --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "0.0.0")