What Is the Commands Component in the AI Job Search Framework?

The Commands component serves as the single source of truth for all user-facing operations in the AI Job Search Framework, storing declarative workflow specifications as markdown files in .claude/commands/ that runtime agents execute without requiring changes to the core Python codebase.

The MadsLorentzen/ai-job-search repository organizes its interactive functionality through a unique declarative architecture. Rather than embedding command logic directly into Python scripts, the framework extracts high-level operations into self-contained markdown specifications. This design pattern separates workflow definition from execution, enabling rapid iteration and safe experimentation.

Declarative Architecture and Design Philosophy

The .claude/commands/ directory functions as a lightweight command registry. Each markdown file within this directory represents exactly one user-facing operation, acting as both documentation and executable specification.

Self-Contained Workflow Definitions

Every command file encodes a complete step-by-step workflow. The document outlines argument parsing rules, user prompt sequences, and required confirmations. For example, /.claude/commands/setup.md details the full onboarding flow, while /.claude/commands/reset.md specifies the sequence for clearing profile data safely.

Runtime Execution Model

Runtime agents—whether Claude, Gemini, or other LLM implementations—read these markdown files dynamically. The core Python codebase provides a thin run_command() wrapper that locates the appropriate markdown specification and delegates execution to the agent. This pointer-based architecture eliminates duplicated logic across the framework.

Key Command Files and Responsibilities

The Commands component currently defines seven primary operations:

Command File	Purpose	User Invocation
.claude/commands/setup.md	Provisions initial candidate profile and environment configuration	/setup
.claude/commands/reset.md	Clears stored profile or document data with confirmation guards	/reset [profile|documents]
.claude/commands/rank.md	Evaluates and scores job postings against candidate preferences	/rank <path-to-postings>
.claude/commands/outcome.md	Tracks post-application responses and interview outcomes	/outcome
.claude/commands/gmail-sync.md	Synchronizes Gmail contacts and communications	/gmail-sync
.claude/commands/html-report.md	Generates visual HTML summaries of search progress	/html-report
.claude/commands/add-portal.md	Registers new job portal integrations	/add-portal

Safety Mechanisms and Extensibility Features

The Commands component enforces strict safety protocols while maintaining radical extensibility.

Built-in Safety Guards

Destructive operations in .claude/commands/reset.md and similar files include explicit confirmation prompts. Each specification lists exactly which files will be read or written before execution, preventing accidental data loss. The declarative format makes safety checks visible and auditable.

Zero-Code Extension Model

Adding functionality requires no Python changes. Create a new markdown file in .claude/commands/ with the desired workflow steps, and the framework automatically discovers and exposes the command. This pattern supports rapid prototyping and A/B testing of new job search workflows.

Practical Implementation Examples

The run_command() helper executes any command defined in the Commands component by reading its markdown specification:

# Initialize the candidate profile using the setup workflow

from agents import run_command
run_command("/setup")

# Reset only the profile data (requires confirmation per reset.md)

run_command("/reset profile")

# Rank job postings using the logic defined in rank.md

run_command("/rank ./data/job-postings.json")

These invocations demonstrate that no additional Python code is required to support new commands—the framework dynamically loads the workflow from the corresponding markdown file.

Summary

• The Commands component stores all user-facing operation specifications in .claude/commands/ as markdown files.
• Each file serves as both documentation and executable workflow for runtime agents.
• Safety-critical operations include mandatory confirmation prompts and explicit file access declarations.
• New functionality requires only adding a markdown file—no Python code changes necessary.
• The architecture separates command description from execution logic, maintaining a clean, maintainable codebase.

Frequently Asked Questions

How does the framework discover new commands?

The framework scans the .claude/commands/ directory at runtime and exposes any markdown file as an invocable command. When a user types /<command-name>, the system loads the corresponding .claude/commands/<command-name>.md file and executes the workflow described within.

What safety measures protect user data during destructive operations?

Commands that modify or delete data—such as /.claude/commands/reset.md—must specify confirmation prompts in their markdown specification. The runtime agent parses these requirements and presents explicit warnings before executing file deletions, ensuring users confirm exactly which data stores will be cleared.

Can I modify existing commands without changing Python code?

Yes. Since the Commands component stores logic in markdown rather than Python, editing .claude/commands/rank.md or .claude/commands/setup.md immediately changes the workflow behavior. This decoupling allows non-developers to adjust prompts, add validation steps, or modify output formats by editing text files.

How do agents interpret the markdown command files?

Runtime agents parse the markdown as structured text containing step-by-step instructions, argument schemas, and conditional logic. The agent executes the described workflow using its native capabilities while the core framework handles file system access and state management, creating a clean separation between orchestration and implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}