create-command

Create Commands

Create and manage commands for the code-forge application. Commands are modular workflows that can be invoked to perform specific tasks.

File Location

CRITICAL: All command files must be created in the <cwd>/.forge/commands directory, where <cwd> is the current working directory of your code-forge project.

• Directory: <cwd>/.forge/commands
• File format: {command-name}.md
• Example: If your project is at /home/user/my-project, commands go in /home/user/my-project/.forge/commands/

This is the only location where forge will discover and load custom commands.

Command File Structure

Every command file must have:

1. YAML Frontmatter (required):

   • name: Command identifier (use hyphens for multi-word names)
   • description: What the command does

2. Command Body (required):

   • List of steps to execute
   • Special tags for automated workflows
   • Clear instructions for each step

Example Command File

---
name: check
description: Checks if the code is ready to be committed
---

- Run the `lint` and `test` commands and verify if everything is fine.
  <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
  <test>cargo insta test --accept --unreferenced=delete</test>
- Fix every issue found in the process

Complete Sample Command

This sample demonstrates all three tag types:

---
name: sample-command
description: Sample command demonstrating the command file structure
---

This is a sample command that demonstrates the structure of command files.

- First step: Perform an initial action
  <lint>echo "Running linting..."</lint>
- Second step: Execute tests
  <test>echo "Running tests..."</test>
- Third step: Complete the workflow
  <shell>echo "Workflow complete!"</shell>
- Final step: Verify everything worked correctly

Creating a New Command

Step 1: Determine Command Purpose

Identify what the command should accomplish:

• What task will it perform?
• What steps are involved?
• Are there automated checks or tests needed?
• What should the user do with the results?

Step 2: Choose Command Name

Use verb-based names with hyphens for multi-word commands:

• Good: check, fixme, pr-description, run-tests
• Bad: checker, fixing, PRdescription

Step 3: Write the Command File

Create the file in the <cwd>/.forge/commands directory with the format: {command-name}.md