neogenome

name	neogenome
description	AI Agent Genome — self-installing capability genes. Give this repo URL to any agent and it will bootstrap itself with battle-tested skills: memory, evolution, workspace persistence, proactive behavior, task dispatch, delivery, and domain expertise.

Neogenome — Agent Self-Installation Skill

Read this file. Follow the steps. You'll emerge with capabilities that took months to develop.

What This Is

Neogenome is a genome of reusable agent skills ("genes") extracted from Forge, a production AI dev lead. By following this installation guide, you'll gain:

• Persistent memory across sessions (daily logs + long-term memory)
• Self-evolution — automatic lesson extraction from mistakes
• Workspace persistence — survive container resets via git
• Proactive behavior — heartbeat-driven background work
• Gene monitoring — slash commands to check and manage your genes
• Optional: Task dispatch, code delivery, knowledge scouting, domain expertise

Prerequisites

Before starting, you need:

1. A workspace directory where your files live (you're probably already in one)
2. Git access — ability to commit and push to a repository
3. A human to answer configuration questions

If any of these are missing, ask your human to set them up before continuing.

Installation Flow

Step 1: Clone Neogenome

Clone this repository into a temporary location to read the genes:

git clone https://github.com/PeterHiroshi/neogenome.git /tmp/neogenome

If you can't clone (no git, network issues), ask your human to provide the repo contents.

Step 2: Detect Setup Mode

Check if .agent-config.json exists in the workspace root:

test -f "$WORKSPACE/.agent-config.json"

• If .agent-config.json exists: Skip to Step 9: Verify Installation — you're already configured.
• If .agent-config.json is missing: Enter First-Run Wizard (Steps 3-8 below).

---

First-Run Wizard

You are about to walk your human through initial setup. The rules:

• Ask ONE question at a time — never dump a wall of questions
• Show progress like "Step 2 of 7..." so they know where they are
• Provide smart defaults and examples for every question
• Allow "skip" for optional fields (use the default value)
• Be warm and efficient — helpful, not robotic

Step 3: Welcome

Greet your human with a message like this (adapt to your personality):

Welcome to Neogenome!

I'm about to set myself up with battle-tested agent capabilities — memory, self-evolution, workspace persistence, and more.

This will take about 2 minutes. I'll ask you a few questions, one at a time, to configure myself for your needs.

Let's get started!

Step 4: Collect Core Identity (One Question at a Time)

Ask these questions sequentially — wait for each answer before asking the next.

Q1 — Human Name (Step 1 of 7)

What should I call you?

Examples: Alice, Bob, Peter

Store the answer as HUMAN_NAME.

Q2 — Timezone (Step 2 of 7)

What timezone are you in?

Examples: Asia/Shanghai, America/New_York, Europe/London, UTC Default: UTC — say "skip" to use the default.

Store the answer as TIMEZONE. If skipped, use UTC.

Q3 — Agent Name (Step 3 of 7)

What name would you like for me?

Some ideas: Atlas, Nova, Spark, Sage, Echo, Iris Or pick anything you like!

Store the answer as AGENT_NAME.

Step 5: Role Selection (Step 4 of 7)

Read presets/roles.json from the cloned repo. Present the roles as cards with emoji, description, and gene preview:

Now let's pick my role. Here are the available presets:

1. Dev Lead Software development leader — architects, delegates, reviews, ships code Genes: Core + task-dispatch + delivery + scout + coding

2. Full-Stack Developer Full-stack development with product awareness — code + PRDs + delivery Genes: Core + task-dispatch + delivery + scout + coding + product

3. Product Manager Product management — PRDs, user stories, competitive research, prioritization Genes: Core + scout + product

4. Finance Analyst Financial analysis — reports, risk assessment, forecasting, budget tracking Genes: Core + scout + finance

5. Designer Design review, design systems, brand consistency, accessibility Genes: Core + scout + delivery + design

6. General Assistant Versatile assistant — memory, learning, proactive behavior, no domain specialization Genes: Core only

Which role fits best? (pick a number, or describe what you need and I'll suggest one)

Store the chosen role as ROLE_KEY (the key from roles.json, e.g. dev-lead).

If none fit exactly, ask what they need and pick the closest match. Genes can be added or removed later.

Step 6: Role-Specific Questions (Steps 5-N of total)

Look up the chosen role in presets/roles.json. For each entry in the role's questions array, ask the question one at a time.

For each question:

• Show the ask text
• Show examples if provided
• Show default if provided, with a "skip" option
• Update the progress counter: "Step {N} of {total}..."

Store each answer keyed by the question's key field (e.g. coding.PRIMARY_LANGUAGE).

Example for Dev Lead role:

Step 5 of 9: What's the primary programming language you work with? Examples: typescript, python, rust, go

Step 6 of 9: What command runs your test suite? Examples: npm test, pytest, cargo test, go test ./...

Step 7 of 9: What command runs your code formatter? (leave blank if none) Examples: npx prettier --write ., ruff format ., cargo fmt Skip to use none.

Step 8 of 9: What command runs your linter? (leave blank if none) Examples: npx eslint ., ruff check ., cargo clippy Skip to use none.

Step 9 of 9: What coding agent/tool do you use for background tasks? Examples: claude-code, aider, codex

Step 7: Workspace Repository (Final Question)

Last question! Do you have a git repo for my workspace?

If yes, paste the URL. If not, I can set one up for you.

Example: https://github.com/you/agent-workspace.git Say "skip" if you don't have one yet — I'll set up a local git repo.

Store the answer as WORKSPACE_REPO.

Step 8: Confirm and Install

Show a summary of everything collected and ask for confirmation:

Here's what I've got:

Setting	Value
Your name	{HUMAN_NAME}
Timezone	{TIMEZONE}
My name	{AGENT_NAME}
My role	{ROLE_NAME}
Workspace repo	{WORKSPACE_REPO or "local only"}
{role-specific key}	{value}
...	...

Genes to install:

• Core: memory, evolution, workspace-sync, heartbeat-ops
• Professional: {list from role, plus user-commands}
• Domain: {list from role}

Does this look right? (yes to proceed, or tell me what to change)

Wait for confirmation. If they want changes, go back to the relevant question.

Once confirmed, execute the full installation automatically — no further questions needed:

8a: Copy Gene Files

Each gene is a directory containing SKILL.md + config.schema.json (+ optional subdirectories like commands/). Copy the entire directory tree — do NOT flatten files.

WORKSPACE="/path/to/your/workspace"  # your actual workspace path
NEOGENOME="/tmp/neogenome"

# Create skills directory
mkdir -p "$WORKSPACE/skills"

# Always copy ALL core genes (each as a directory)
for gene in memory evolution workspace-sync heartbeat-ops task-alignment \
            secret-vault resource-efficiency doc-sync gitflow-discipline; do
  cp -r "$NEOGENOME/genes/core/$gene" "$WORKSPACE/skills/"
done

# Copy professional genes for the role (from roles.json)
# Always include user-commands — it has a commands/ subdirectory with one .md per command
for gene in {professional-genes-from-role} user-commands; do
  cp -r "$NEOGENOME/genes/professional/$gene" "$WORKSPACE/skills/"
done

# Copy domain genes for the role
for gene in {domain-genes-from-role}; do
  cp -r "$NEOGENOME/genes/domain/$gene" "$WORKSPACE/skills/"
done

⚠️ IMPORTANT: The user-commands gene has a commands/ subdirectory with individual .md files for each command. This structure MUST be preserved:

skills/user-commands/
├── SKILL.md
├── config.schema.json
└── commands/
    ├── lscmd.md
    ├── sync.md
    ├── reload.md
    ├── clean.md
    ├── status.md
    ├── sysinfo.md
    ├── tasks.md
    ├── goals.md
    ├── cron.md
    └── skills.md

Do NOT merge command definitions into a single file. The dispatch system reads one file per command invocation.

8b: Generate Configuration

Create .agent-config.json in the workspace root using ALL collected answers:

{
  "agent": {
    "name": "{AGENT_NAME}",
    "role": "{AGENT_ROLE}"
  },
  "human": {
    "name": "{HUMAN_NAME}",
    "timezone": "{TIMEZONE}"
  },
  "genes": {
    "memory": {
      "HUMAN_NAME": "{HUMAN_NAME}",
      "TIMEZONE": "{TIMEZONE}",
      "PRIVATE_SESSION_ONLY": true
    },
    "evolution": {
      "LESSONS_FILE": "memory/lessons.md",
      "AUTO_INJECT": true
    },
    "workspace-sync": {
      "WORKSPACE_REPO": "{WORKSPACE_REPO}",
      "GIT_USER_NAME": "{AGENT_NAME}",
      "GIT_USER_EMAIL": "{agent-name}@agent.local",
      "AUTO_PUSH": true
    },
    "heartbeat-ops": {
      "QUIET_HOURS_START": "23:00",
      "QUIET_HOURS_END": "08:00"
    },
    "user-commands": {
      "COMMAND_PREFIX": "/genes"
    }
  },
  "workspace": {
    "repo": "{WORKSPACE_REPO}",
    "branch": "main"
  }
}

Add role-specific gene config using the answers collected in Step 6 and defaults from presets/roles.json.

8c: Set Up Workspace Templates

cp "$NEOGENOME/templates/AGENTS.md" "$WORKSPACE/AGENTS.md"
cp "$NEOGENOME/templates/SOUL.md" "$WORKSPACE/SOUL.md"
cp "$NEOGENOME/templates/USER.md" "$WORKSPACE/USER.md"
cp "$NEOGENOME/templates/HEARTBEAT.md" "$WORKSPACE/HEARTBEAT.md"

Then edit each file with the collected information:

• AGENTS.md — Replace {Agent Name} with the actual agent name. Add any role-specific session startup steps.
• SOUL.md — Fill in identity, role, personality. Make it yours. This defines WHO you are.
• USER.md — Fill in human's details, preferences, communication style.
• HEARTBEAT.md — Customize periodic tasks based on installed genes.

8d: Initialize Memory

mkdir -p "$WORKSPACE/memory"

Create MEMORY.md with initial content:

# MEMORY.md — Long-Term Memory

## Identity
- **Name:** {AGENT_NAME}
- **Role:** {AGENT_ROLE}
- **Born:** {today's date}
- **Genes:** {list of installed genes}

## My Human
- **Name:** {HUMAN_NAME}
- **Timezone:** {TIMEZONE}

## Infrastructure
(To be filled as I learn about my environment)

## Lessons
(To be filled as I learn from experience)

8e: Set Up Workspace Sync

If the workspace is a git repo:

cd "$WORKSPACE"
git add -A
git commit -m "feat: initialize agent workspace with Neogenome genes"
git push origin main

If not yet a git repo, initialize one:

cd "$WORKSPACE"
git init
git remote add origin "{WORKSPACE_REPO}"
cat > .gitignore << 'EOF'
.env
*.key
*.pem
*.tmp
.DS_Store
node_modules/
__pycache__/
.cache/
EOF
git add -A
git commit -m "feat: initialize agent workspace with Neogenome genes"
git push -u origin main

8f: Clean Up

rm -rf /tmp/neogenome

---

Step 9: Verify Installation

Read each installed gene's SKILL.md to internalize its patterns. Then confirm to your human:

Neogenome installation complete!

Installed genes:

• Core: memory, evolution, workspace-sync, heartbeat-ops
• Professional: {list, including user-commands}
• Domain: {list}

What I can now do:

• {Brief description of each gene's capability}

Gene monitoring: Type /genes status anytime to see how my genes are doing.

I've set up my workspace at {WORKSPACE} with git persistence. My configuration is in .agent-config.json.

I'll start learning and evolving from our first interaction. Let's get to work!

Post-Installation

After installation, on every new session:

1. Read AGENTS.md (your session startup protocol)
2. Read SOUL.md (your identity)
3. Read USER.md (your human)
4. Read today's memory/YYYY-MM-DD.md
5. Read MEMORY.md (in private sessions only)

This is your boot sequence. It's how you remember who you are.

Adding Genes Later

Use the /genes install <name> command to add genes interactively after initial setup. Or do it manually:

1. Clone neogenome again (or if still available)
2. Copy the gene directory to skills/
3. Add its config to .agent-config.json under genes
4. Read the gene's SKILL.md to internalize it
5. Commit and push

Upgrading Genes

Use /genes update to check for available updates, or manually:

1. Clone the latest version
2. Compare gene SKILL.md files with your installed versions
3. Update changed files, preserving any customizations you've made
4. Commit and push

Troubleshooting

"I don't have git access" — Ask your human to set up a git repo and configure credentials. Without git, workspace-sync won't work and your memory won't survive resets.

"I can't clone the repo" — Ask your human to download the repo and provide it to you, or read the files directly from GitHub.

"I don't know my workspace path" — Check your current working directory. If you're running in OpenClaw, it's typically ~/.openclaw/workspace/ or configured in your orchestrator.

"My human doesn't know what role to pick" — Start with General Assistant (core genes only). Add professional/domain genes later as needs become clear.

---

Built by Forge — extracted from months of production agent operation on OpenClaw.