user-commands

name	user-commands
layer	professional
description	Slash commands for agent management — gene monitoring, workspace ops, task tracking, and system info. Extensible command dispatch system.

User Commands Gene

This gene gives your agent a slash command system — a set of /commands that let the human (and the agent itself) quickly inspect status, manage goals, sync workspace, and monitor genes.

Architecture

Directory Structure (IMPORTANT)

Commands are stored as individual markdown files, one file per command:

skills/user-commands/
├── SKILL.md              ← this file (dispatch logic + /genes commands)
├── config.schema.json
└── commands/             ← one .md file per command
    ├── lscmd.md
    ├── sync.md
    ├── reload.md
    ├── clean.md
    ├── status.md
    ├── sysinfo.md
    ├── tasks.md
    ├── goals.md
    ├── cron.md
    ├── skills.md
    └── <your-custom>.md  ← add your own here

⚠️ Do NOT put all commands in a single file. Each command = its own .md file. This is how the dispatch system works — it reads one file per command invocation, keeping context minimal.

Dispatch Flow

1. Parse command — Extract the first token after / (e.g., /scrum board → scrum)
2. Load definition — Read skills/user-commands/commands/<command>.md
3. Execute — Follow the steps defined in the command file
4. Report — Output per the command's format rules

Adding Custom Commands

Create a new file skills/user-commands/commands/<name>.md:

# /<name>

**Purpose:** One-line description.

**Steps:**
1. Step one
2. Step two

**Output:** Format instructions.

The agent will auto-discover it via /lscmd. No registration needed.

Built-in Commands

Workspace & Git

Command	Description
/sync	Internalize session changes into files + git push
/reload	Broadcast reload signal to all active sessions
/clean	Clean zombie processes and expired resources

Monitoring

Command	Description
/status	Quick overview: running tasks, pending reviews, issues
/sysinfo	System resources (CPU/RAM/disk) + session token usage
/tasks	List all dispatched tasks grouped by status
/cron	List scheduled cron jobs with health status
/skills	List all installed agent skills

Planning

Command	Description
/goals	View/manage agent goals (add, complete, drop)
/duties	List long-term responsibilities with health status (🟢🟡🔴)

Gene Management

Command	Description
/genes status	Overview of installed genes with health indicators
/genes list	All available genes (installed + not installed) by layer
/genes check <name>	Deep check: config validation, dependencies
/genes install <name>	Guided gene installation
/genes update	Check for gene updates from upstream
/genes config	Pretty-print current .agent-config.json

Meta

Command	Description
/lscmd	List all available commands

Output Principles

• Compact first — Tables > lists > paragraphs. One line when possible.
• No data loss — Key info (times, statuses, links) always included.
• No filler — No "here are the results", no sign-offs.
• Highlight issues — Expand only when something needs attention.

Configuration

Variable	Type	Default	Description
COMMAND_PREFIX	string	/genes	Prefix for gene management commands
CUSTOM_COMMANDS_DIR	string	commands/	Directory for command definitions

/lscmd (Inline)

List all commands — scan commands/ directory, output table with name + purpose.

/genes Commands

/genes status

1. Read .agent-config.json for configured genes
2. Check which gene directories exist under skills/
3. Health check each: installed+configured = ✅, directory but no config = ⚠️, config but no files = ❌
4. Output by layer with health indicators

/genes list

1. Load the full gene catalog (from neogenome repo or memory)
2. Cross-reference with installed genes
3. Output all genes by layer, marking installed vs available

/genes check <name>

1. Look up gene by name
2. Check directory existence, config schema, current config values
3. Calculate config completeness %
4. Check gene dependencies
5. Output detailed health report

/genes install <name>

1. Verify gene exists in catalog and isn't already installed
2. Copy gene files from neogenome repo to skills/<name>/
3. Ask required config questions (from config.schema.json)
4. Update .agent-config.json
5. Read gene's SKILL.md to internalize
6. Confirm with capabilities gained

/genes update

1. Pull latest neogenome repo
2. Compare each installed gene with upstream version
3. Report which have updates available
4. Offer to update (preserving local customizations)

/genes config

1. Read .agent-config.json
2. Pretty-print with section annotations (agent identity, human info, gene configs)
3. Offer to edit if requested

Gene Catalog Reference

Gene	Layer	Description
memory	Core	Daily logs + long-term memory + distillation
evolution	Core	Passive learning from mistakes
workspace-sync	Core	Git-based persistence and bootstrap recovery
heartbeat-ops	Core	Proactive behavior during idle time
task-alignment	Core	Confirm understanding before acting
secret-vault	Core	Encrypted secret management
resource-efficiency	Core	Model routing & token conservation
doc-sync	Core	Documentation-code synchronization
gitflow-discipline	Core	Strict branching — all changes through PR
task-dispatch	Professional	Background task delegation with resumability
delivery	Professional	Structured work handoff, PR/MR creation
scout	Professional	Autonomous information gathering
scrum	Professional	Sprint planning, kanban, velocity tracking
ci-autonomy	Professional	Self-healing CI/CD
project-bootstrap	Professional	Day-zero project standards
user-commands	Professional	This gene — slash commands
coding	Domain	TDD, git discipline, code quality
product	Domain	PRDs, user stories, prioritization
finance	Domain	Financial analysis, reporting
design	Domain	Design review, accessibility
domain-first-design	Domain	ERD-first platform design

Integration with Other Genes

• All genes — /genes commands provide visibility into gene health
• Workspace Sync — /sync triggers git persistence
• Task Dispatch — /tasks shows dispatched work
• Heartbeat Ops — /clean overlaps with heartbeat zombie cleanup
• Scrum — Agents with scrum gene can add /scrum as a custom command