/create-command

Create Command

Creates a new star-command block in the SYNAPSE commands domain file.

---

Purpose

Add a new star-command definition to `.synapse/commands`, allowing users to define custom commands that the SYNAPSE engine's L7 layer will detect and process.

---

Prerequisites

• `.synapse/commands` file exists
• User provides a command name and at least one rule

---

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | `command-name` | Yes | Star-command name without `*` prefix (e.g., `review`) | | `rules` | Yes | One or more instruction rules for the command (at least 1) |

---

Steps

Step 1: Validate Command Name

• Command name must be lowercase kebab-case (e.g., `review`, `quick-fix`)
• Allowed characters: `a-z`, `0-9`, `-`
• Must NOT start or end with `-`
• Must NOT be empty

If invalid: `Error: Command name must be lowercase kebab-case (e.g., "review"). Got: "{name}"`

Step 2: Check for Duplicates

Read `.synapse/commands` and check if a block header `[*{command-name}]` already exists.

If it exists: `Error: Star-command "*{command-name}" already exists in .synapse/commands. Edit the file directly to modify it.`

Step 3: Derive Command Key

Convert the command name to uppercase for rule keys:

• `review` -> `CMD_REVIEW`
• `quick-fix` -> `CMD_QUICK_FIX`

Full key prefix: `COMMANDS_{CMD_KEY}`

Step 4: Append Command Block

Append the new command block to `.synapse/commands`:

[*{command-name}] COMMAND:
COMMANDS_{CMD_KEY}_0={first-rule}
COMMANDS_{CMD_KEY}_1={second-rule}

• Add a blank line before the block for readability
• Each rule is indexed starting from 0
• At least 1 rule is required

Step 5: Validate

• Verify at least 1 rule was provided
• Read back `.synapse/commands` and verify the block header exists
• Verify rule lines follow `COMMANDS_{CMD_KEY}_{N}=text` format

Step 6: Confirm

Created star-command "*{command-name}" with {count} rules.

The SYNAPSE engine's L7 layer will detect "*{command-name}" in user prompts
and inject the associated rules into the context.

---

Validation

• [ ] Command name is valid kebab-case
• [ ] No duplicate command in `.synapse/commands`
• [ ] At least 1 rule provided
• [ ] Block header follows `[*{name}] COMMAND:` format
• [ ] Rule keys follow `COMMANDS_{CMD_KEY}_{N}=text` format
• [ ] `.synapse/commands` remains parseable after addition

---

Error Handling

| Error | Message | |-------|---------| | Invalid name | `Error: Command name must be lowercase kebab-case (e.g., "review"). Got: "{name}"` | | Duplicate command | `Error: Star-command "*{name}" already exists in .synapse/commands.` | | No rules provided | `Error: At least one rule is required for a star-command.` | | Commands file missing | `Error: .synapse/commands not found. SYNAPSE must be initialized first (SYN-8).` |

---

*Create Command — SYNAPSE CRUD Command C6* *Source: SYNAPSE-HOOK-SKILL-COMMAND-ANALYSIS.md section 2.3, DESIGN-SYNAPSE-ENGINE.md section 15*