Skip to main content

CODITECT STANDARD: Commands

Version: 1.0.0 Status: Production Standard Last Updated: February 7, 2026 Authority: Based on Anthropic Agent SDK Official Documentation and existing CODITECT command patterns Scope: All command definitions in .coditect/commands/

1. Executive Summary​

This document defines the authoritative standard for CODITECT command files. Commands are user-invocable slash commands (/command-name) that provide CLI-style interfaces for framework operations. All commands MUST comply with this standard.

Compliance: Mandatory for all commands in coditect-core repository. Compliance Target: Grade B (80%) minimum within 30 days of publication.

2. Required File Format​

2.1 File Naming Convention​

Pattern: {command-name}.md

Rules:

  • Lowercase only
  • Hyphen-separated words (kebab-case)
  • No spaces, underscores, or special characters
  • Maximum 64 characters
  • Must match the command invocation name (e.g., orient.md for /orient)

Valid Examples:

  • orient.md
  • session-log.md
  • component-create.md

Invalid Examples:

  • SessionLog.md (uppercase)
  • session_log.md (underscore)
  • qa validate.md (space)

2.2 File Location​

Path: .coditect/commands/{command-name}.md

NOT allowed:

  • Subdirectories within commands/
  • Commands outside .coditect/commands/
  • Duplicate command names

3. YAML Frontmatter Structure​

3.1 Required Fields​

All commands MUST include YAML frontmatter at the start of the file:

---
name: command-name                    # Lowercase, hyphens, matches filename
description: Brief description        # 10-1024 chars, no XML tags
argument-hint: <argument-pattern>     # Pattern showing expected arguments
allowed-tools: Glob, Grep, Read      # Valid Anthropic tool names available to command
---

Field Requirements:

FieldTypeRequiredValidation
namestringYESLowercase kebab-case, matches filename, max 64 chars
descriptionstringYES10-1024 chars, no XML tags, describes purpose
argument-hintstringYESShows argument pattern (e.g., <path> [--options])
allowed-toolsstring/listYESComma-separated valid Anthropic tool names
---
# ... required fields ...
title: /command-name - Display Title  # Human-readable title
component_type: command               # Fixed value
version: 1.0.0                        # Semantic version
track: H                              # CODITECT track assignment
quality_score: 85                     # Current quality score (0-100)
invocation: /command-name             # Invocation syntax
audience: customer | contributor      # Target audience
status: active | deprecated          # Lifecycle status
tokens: ~1500                         # Approximate token cost
created: 'YYYY-MM-DD'                # Creation date
updated: 'YYYY-MM-DD'                # Last update date
last_reviewed: 'YYYY-MM-DD'          # Last human/AI review date (H.24)
command_name: /command-name           # Full invocation including slash
usage: /command-name [options]        # Usage syntax
requires_confirmation: false          # Whether command needs user confirmation
modifies_files: false                 # Whether command modifies filesystem
network_access: false                 # Whether command needs network
tags: [command, automation]           # Category tags
---

3.3 Valid Tool Names​

Commands may only reference these Anthropic-recognized tools:

Read, Write, Edit, Bash, Grep, Glob, LS, TodoWrite,
WebSearch, WebFetch, Task, Skill, NotebookEdit, ExitPlanMode

4. Body Structure​

4.1 Required Sections​

Commands MUST include these sections in the body:

# /command-name - Title

Brief description of what the command does.

## System Prompt

Execution directive and agent instructions.

## Usage

```bash
/command-name [arguments] [options]

Arguments​

ArgumentTypeRequiredDefaultDescription
arg1stringYes-Description

Examples​

# Example 1: Basic usage
/command-name value

# Example 2: With options
/command-name value --option
  • Agent: agent-name - Related agent
  • Skill: skill-name - Related skill
  • Script: script-name.py - Implementation script

### 4.2 Recommended Sections

```markdown
## When to Use

**Use this command when:**
- Condition 1
- Condition 2

**Don't use this command when:**
- Condition 1

## Success Output

When command completes successfully:

checkmark COMMAND COMPLETE: /command-name


## Completion Checklist

- [ ] Check 1
- [ ] Check 2

## Failure Indicators

- cross mark Failure condition 1
- cross mark Failure condition 2

## Anti-Patterns (Avoid)

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Pattern 1    | Issue   | Fix      |

## Principles

This command embodies:
- **#N Principle Name** - How it applies

5. Quality Criteria​

5.1 Compliance Checklist​

All commands must pass these checks:

File Format (Weight: 15%)

  • Filename matches pattern {command-name}.md
  • Located in .coditect/commands/
  • No duplicate command names

YAML Frontmatter (Weight: 35%)

  • All required fields present: name, description, argument-hint, allowed-tools
  • name matches filename (without .md)
  • description between 10-1024 characters, no XML tags
  • allowed-tools lists valid Anthropic tool names
  • component_type: command present

Specification Quality (Weight: 30%)

  • Usage section with invocation syntax and options
  • Arguments table with name, type, required, default, description columns
  • At least 1 usage example with code block
  • Workflow/execution steps described (System Prompt or dedicated section)

Documentation Standards (Weight: 20%)

  • Related Components section linking to agents/skills/scripts
  • Proper markdown headings (H1 + H2 minimum)
  • Code blocks with language tags (bash, yaml, etc.)
  • When to Use / When NOT to Use guidance

5.2 Grading Scale​

Grade A (90-100%): Production-ready, exemplary documentation Grade B (80-89%): Production-ready, minor improvements needed Grade C (70-79%): Functional, moderate improvements needed Grade D (60-69%): Requires significant improvements Grade F (<60%): Does not meet minimum standards, rework required

5.3 Automated Validation​

Commands can be validated using:

python3 .coditect/scripts/qa/grade-commands.py commands/{command-name}.md

Validation Output:

  • Compliance score (0-100%)
  • Failed checks with details
  • Recommendations for improvement
  • Grade assignment

6. Templates​

6.1 Minimal Command Template​

---
name: example-command
description: Brief description of what this command does
argument-hint: <target> [--options]
allowed-tools: Read, Grep, Glob
---
# /example-command - Command Title

Brief description of the command purpose.

## System Prompt

**EXECUTION DIRECTIVE:** When invoked, IMMEDIATELY execute without questions.

## Usage

```bash
/example-command <target> [--verbose]

Arguments​

ArgumentTypeRequiredDefaultDescription
targetpathYes-Target file or directory
--verboseflagNofalseShow detailed output

Examples​

# Basic usage
/example-command path/to/file.md

# With verbose output
/example-command path/to/file.md --verbose
  • Agent: related-agent - Description
  • Script: related-script.py - Implementation

### 6.2 Standard Command Template

Extends minimal with: When to Use, Success Output, Completion Checklist, Failure Indicators, Anti-Patterns, Principles sections.

---

## 7. Migration Guide

### For Existing Commands Without Frontmatter

1. Add YAML frontmatter with required fields
2. Ensure `name` matches filename
3. Add `argument-hint` showing expected arguments
4. Add `allowed-tools` listing valid tools
5. Run validation: `python3 scripts/qa/grade-commands.py commands/{name}.md`

---

## 8. References

- [CODITECT-STANDARD-AGENTS.md](coditect-standard-agents.md) - Agent file standard
- [CODITECT-STANDARD-SKILLS.md](coditect-standard-skills.md) - Skill file standard
- [CODITECT-STANDARD-AUTOMATION.md](coditect-standard-automation.md) - Automation principles

---

**Version:** 1.0.0
**Created:** February 7, 2026
**Author:** CODITECT Standards Team