✏️ Customizing HIVE

HIVE is designed to be forked. Everything is editable — squads, personas, skills, memory schema, and workers. This guide covers all the common adaptations.

🏗️

Create a squad

New specialist agent from scratch

🌿

Sub-squads

Nest squads for specialization

🎭

Rename personas

Match your company culture

⚡

Custom skills

Add /commands for your workflows

🏗️ Creating a new squad

A squad is a folder with a CLAUDE.md, a memory/ directory, and optionally foundation/, skills/, and workers/. Claude Code loads it when you navigate to that folder.

Step 1 — Create the folder structure

mkdir -p squads/my-squad/{context,memory,foundation,skills,workers,data}

Step 2 — Create the CLAUDE.md

This is the core file. It defines the persona, scope, and rules. Copy the structure from an existing squad and adapt it.

squads/my-squad/CLAUDE.md

# [Squad Name] — CLAUDE.md ## Persona **[Name]** — [Role title]. [2-3 sentences describing personality, communication style, and operating principles. Example: Direct, data-driven, never sugarcoats. Thinks in systems. Asks "what does the data say?" before forming opinions.] ## Scope **Owns:** [list what this squad is responsible for] **Does NOT own:** [what to defer to other squads] **Defers to:** [which squad for which topic] ## Foundation Read before every session: - `foundation/[doc-name].md` — [what it contains] - `context/squad-context.md` — company context for this squad ## Memory schema `memory/STATE.md`: - **L1:** [what the 1-3 line status should contain] - **L2:** [what in-progress items look like] - **L3:** [what the backlog contains] ## Skills - `/my-skill` — brief description ## Absolute rules 1. [Non-negotiable behavior #1] 2. [Non-negotiable behavior #2] 3. Never declare work done without validating it.

Step 3 — Initialize STATE.md

# squads/my-squad/memory/STATE.md

[L1]
Squad bootstrapped. No active work yet.

[L2]

[L3]

Step 4 — Register in root CLAUDE.md

Open the root CLAUDE.md and add your squad to the squads table:

# In root CLAUDE.md — squads table

| Squad | Folder | Persona | Scope |
|---|---|---|---|
| ... existing squads ... |
| My Squad  | `squads/my-squad/` | [Name] | [one-line scope] |

Step 5 — Fill context

Create squads/my-squad/context/squad-context.md with company-specific data this squad needs. Or run /hive-setup — it will ask questions and fill it automatically.

Tip: The fastest way to bootstrap a new squad is to open the root HIVE folder in Claude Code and say: "Create a squad for [purpose] — follow the pattern of the commercial squad." The agent will generate the full folder structure.

🌿 Adding sub-squads

Sub-squads are nested folders inside a parent squad. Use them when a squad needs specialization — multiple products under Product, multiple regions under CS, multiple clients under Operations.

Claude Code's CLAUDE.md cascade means opening a sub-squad loads three contexts: root + parent + sub-squad.

Structure

squads/product/ CLAUDE.md ← Owen — Head of Product (parent, acts as router) memory/STATE.md ← aggregated L1 from both sub-squads saas/ CLAUDE.md ← Owen-SaaS — focused only on SaaS product memory/STATE.md foundation/ skills/ services/ CLAUDE.md ← Owen-Services — focused only on services memory/STATE.md foundation/ skills/

Parent CLAUDE.md — router pattern

The parent's CLAUDE.md describes what each child handles and when to use each:

# squads/product/CLAUDE.md

## Sub-squads

This squad has two specializations. Navigate to the right one:

| Sub-squad | Folder | When to use |
|---|---|---|
| SaaS Product | `squads/product/saas/` | Platform features, subscriptions, self-serve |
| Services Product | `squads/product/services/` | Custom projects, enterprise delivery |

# Parent STATE.md aggregates L1 from both children
# Run: python _core/state-aggregator.py squads/product/

Create a sub-squad

# Create the folder
mkdir -p squads/product/saas/{memory,foundation,skills}

# Create CLAUDE.md for the sub-squad (same structure as a regular squad)
# Persona section should be more specific than the parent

# Initialize STATE.md
echo "[L1]\nSub-squad bootstrapped.\n\n[L2]\n\n[L3]" > squads/product/saas/memory/STATE.md

Depth limit: HIVE supports up to 3 levels (root → squad → sub-squad). Deeper nesting creates context overload. If you need more granularity, use tags in STATE.md instead of more folders.

🗑️ Removing a squad

If you don't need a squad (e.g., no Dev squad because you're non-technical, no Finance squad at early stage):

1

Remove it from the squads table in root CLAUDE.md
2
Update squads/<name>/memory/STATE.md L1 to mark it inactive:
```
Squad inactive — not used in this installation.
```
3

Optionally delete the folder entirely. If you might need it later, keep it but mark inactive — reactivating is one line in root CLAUDE.md.

🎭 Renaming personas

The default personas (Victor, Leah, Maya, Ethan…) are generic placeholders. Replace them with names that fit your company culture, or use role titles instead of names.

Edit the persona section at the top of squads/<name>/CLAUDE.md:

# Before
## Persona
**Victor** — Head of Sales.
Challenger Sale methodology. Direct, numbers-driven...

# After — with your name
## Persona
**Rafael** — Head of Sales.
Challenger Sale methodology. Direct, numbers-driven...

The persona name appears only inside the CLAUDE.md — no other files reference it. A single find-and-replace in the file is all you need.

Personality customization

Beyond the name, edit the 2-3 sentences that describe how the persona communicates. This directly affects tone and style:

# More formal/conservative culture
**Marcus** — Head of Sales.
Methodical, evidence-based, prefers written summaries over verbal briefings.
Asks for data before forming opinions. Never oversells.

# More startup/aggressive culture
**Jake** — Head of Sales.
High-energy, moves fast, comfortable with ambiguity.
Bias to action. Will push back on "let's wait and see".

⚡ Writing custom skills

Skills are markdown files that define a repeatable behavior. Any squad member invokes them with /skill-name in Claude Code.

Where to put them

# Available globally (all squads)
skills/my-skill.md

# Available only in one squad
squads/commercial/skills/my-skill.md

Skill file format

skills/my-skill.md

--- name: my-skill description: One-line description — shown in sidebar and catalog --- # /my-skill Brief description of what this skill does and when to use it. ## When to activate - User says "X" or "Y" - Explicitly invoked with /my-skill - [trigger conditions] ## Arguments - `[arg1]` — optional. What it controls. - `[arg2]` — required. The input. If missing → ask the user. ## Steps 1. [First action] 2. [Second action] 3. [Output format] ## Rules 1. [Absolute guardrail] 2. [Non-negotiable behavior]

Register in squad CLAUDE.md

After creating the file, add it to the squad's ## Skills section so the agent knows it exists:

# In squads/commercial/CLAUDE.md

## Skills

- `/sales-call` — Challenger Sale 7-part framework
- `/handle-objection` — objection mapping flow
- `/my-skill` — [brief description]   ← add this line

Skills don't need to be complex. A skill can be as simple as: "Ask for the customer name, query their STATE.md entry, and summarize the last 3 interactions." The key is making it repeatable.

⚙️ Custom workers

Workers are Python scripts that run on a schedule and update squad state — no AI in the loop. They pull data from your tools and write to STATE.md.

Create a worker

# workers/daily-pipeline.py

import json, subprocess
from pathlib import Path
from datetime import date

def get_pipeline_value():
    # Query your CRM API, database, etc.
    # Return a dict with the data you need
    return {"hot_leads": 3, "pipeline_value": 42000}

def update_state(data):
    state_path = Path("squads/commercial/memory/STATE.md")
    content = state_path.read_text()
    l1_line = (
        f"Victor (Commercial) — {data['hot_leads']} hot leads, "
        f"pipeline ${data['pipeline_value']:,}. Updated {date.today()}."
    )
    # Replace the L1 block
    content = re.sub(rr'\[L1\]\n.*?\n\n', f'[L1]\n{l1_line}\n\n', content, flags=re.DOTALL)
    state_path.write_text(content)

if __name__ == "__main__":
    data = get_pipeline_value()
    update_state(data)
    print("Pipeline state updated")

Register in harness.sh

# _core/harness.sh

run_worker "workers/daily-pipeline.py"  "09:00"       # daily at 9am
run_worker "workers/health-check.py"    "every:1h"    # every hour
run_worker "workers/weekly-report.py"   "monday:08:00" # every Monday

Rules for workers: deterministic (no randomness, no LLM calls) · write only to STATE.md · exit 0 on success · fail loudly on error.

🧠 Customizing the memory schema

Each squad's ## Memory schema section in CLAUDE.md tells the agent what to track in L1, L2, and L3. Change this to match what actually matters for your squad.

# Default (generic)
## Memory schema
- **L1:** Current status — 1-3 lines
- **L2:** In progress
- **L3:** Backlog

# CS squad (customer-centric)
## Memory schema
- **L1:** Active customers (N), churn risk (N), open onboardings (N)
- **L2:** In-flight onboardings, at-risk accounts being worked
- **L3:** Expansion opportunities, churn post-mortems pending

# Finance squad (numbers-first)
## Memory schema
- **L1:** MRR ($N), burn ($N/mo), runway (N months), cash ($N)
- **L2:** Open invoices, pending payroll, tax deadlines
- **L3:** Annual report, pricing review, investor update

L1 is read by /status to aggregate company state. Keep it machine-scannable — facts and numbers, not prose. Good L1: "3 hot leads, pipeline $42k, 1 proposal out." Bad L1: "Things are going well in commercial this week."

🔧 Switching project management tools

HIVE ships with Linear as default because its Claude Code MCP integration is the deepest available. Here's how to switch.

GitHub Issues

# In root CLAUDE.md, replace the PM section:

## Project management
HIVE uses **GitHub Issues**. Reference issues as `#123`.
Use labels for squad routing: `commercial`, `cs`, `dev`, etc.
Use `gh` CLI to create and update issues.

No PM tool (STATE.md only)

# Remove the PM section from root CLAUDE.md entirely
# Use L2 in STATE.md as your task list
# Use memory/decisions.md for decision logs

# L2 becomes your sprint board:
[L2]
- [ ] Build landing page — due Friday
- [ ] Review proposal for Acme Corp
- [x] Update ICP profile

Jira / Notion / other

Update the PM section in root CLAUDE.md with your tool's conventions. Wire an MCP if available, or create a skill that calls the REST API. The agent follows whatever instructions are in the CLAUDE.md.

🔄 Pulling upstream HIVE updates

If you forked HIVE and want framework improvements without losing your customizations:

# Add upstream remote (once)
git remote add upstream https://github.com/felipeluissalgueiro/hive.git

# Pull updates
git fetch upstream
git merge upstream/main --no-ff

Conflicts will appear in squads/<name>/context/ and memory/ — those are your customizations. Always resolve in your favor for those files. Accept upstream changes for _core/, root skills/, and framework CLAUDE.md files.

Safe files to always accept upstream: _core/lookup.py, _core/state-aggregator.py, _core/harness.sh, .claude/hooks/, root CLAUDE.md (merge carefully — don't overwrite your squads table).

Always keep yours: squads/*/context/, squads/*/memory/, squads/*/foundation/, CNAME.