How Workflow Specifications Are Centralized in the AI Job Search Framework

The AI Job Search Framework uses a thin-pointer, single-source-of-truth design where all workflow specifications live in the .claude/ directory, ensuring every agent runtime reads from identical markdown files without duplication.

The MadsLorentzen/ai-job-search repository implements a strict thin-pointer architecture that eliminates configuration drift across multiple AI agent runtimes. Instead of embedding workflow logic inside agent-specific code, the framework centralizes every operational step—from scraping and ranking to applying and interview preparation—within markdown files in the .claude/ directory. This approach ensures that whether you are using Claude Code, Google Antigravity, Codex, Cursor, or Gemini CLI, all agents execute identical workflow specifications.

The .claude/ Directory as the Single Source of Truth

All workflow specifications reside under the .claude/ directory at the repository root. This location serves as the immutable reference point for every automation stage in the job search process.

Canonical Definitions in .claude/skills/

The .claude/skills/ subdirectory contains step-by-step skill files that define specific workflow stages. Each skill is documented in markdown format with exact instructions, triggers, and allowed tools. For example, the job scraper workflow is fully specified in .claude/skills/job-scraper/SKILL.md, which acts as the canonical definition for that operational step. These files contain the complete step-by-step instructions that agents must follow, ensuring consistent execution across all platforms.

CLI Commands in .claude/commands/

The .claude/commands/ directory houses CLI-style command definitions that trigger specific workflow actions such as setup.md for initialization procedures. These markdown files contain the precise triggers and tool permissions required to execute commands, ensuring consistent invocation patterns across all supported agent platforms. When an agent needs to execute a setup routine, it loads .claude/commands/setup.md directly rather than referencing hard-coded instructions.

Architectural Contract in AGENTS.md

The AGENTS.md file explicitly mandates the centralized architecture, declaring that all agent runtimes must load canonical specifications exclusively from the .claude/ directory. According to lines 9-17 of AGENTS.md: "All agent runtimes should load the canonical specifications … from the .claude/ directory."

This file establishes three foundational pillars of the framework design:

• Personal candidate profile — Defined in CLAUDE.md at the repository root
• Workflow specifications — The centralized markdown files under .claude/ that define all operational steps
• Portal-search skills — Specialized search capabilities that complement the core workflows

By formalizing these pillars, AGENTS.md ensures that workflow files remain the single source of truth, preventing any agent from maintaining independent or outdated copies of the process definitions.

Runtime Implementation Patterns

Every agent implementation follows the same thin-pointer pattern: read the markdown specification directly from disk rather than embedding logic in code.

Loading Specifications in Node.js

The following pattern demonstrates how Node.js runtimes resolve and read the canonical workflow specifications:

import fs from 'fs';
import path from 'path';

// Resolve the location of the canonical workflow spec
const specPath = path.resolve(
  __dirname,
  '..',
  '.claude',
  'skills',
  'job-scraper',
  'SKILL.md'
);

// Read the markdown spec (the file is the single source of truth)
const spec = fs.readFileSync(specPath, 'utf-8');
console.log('Job-scraper workflow spec:\n', spec);

Accessing Commands in Python

Python-based agents use identical path resolution strategies to access the centralized command definitions:

from pathlib import Path

# Central command definition for "setup"

setup_cmd_path = Path(__file__).parent.parent / '.claude' / 'commands' / 'setup.md'

with open(setup_cmd_path, 'r', encoding='utf-8') as f:
    setup_md = f.read()

print('Setup command description:\n', setup_md)

These implementations demonstrate that every runtime simply reads the markdown files under .claude/ with no hard-coded logic elsewhere, guaranteeing consistency across Claude Code, Codex, Cursor, and other supported agents.

Benefits of Centralized Workflow Specifications

This architecture delivers specific operational advantages:

• Zero configuration drift — Modifying .claude/skills/job-scraper/SKILL.md instantly updates behavior across all agent platforms without code changes in individual runtimes.
• Automatic propagation — Adding a new workflow step in the .claude/ directory makes it immediately available to Google Antigravity, Gemini CLI, and other agents.
• Simplified maintenance — Developers edit markdown files rather than hunting through agent-specific source code to update business logic.

Summary

• Workflow specifications in the AI Job Search Framework are centralized in the .claude/ directory, creating a single source of truth for all operational steps.
• The AGENTS.md file mandates that all agents—including Claude Code, Codex, and Cursor—load definitions exclusively from .claude/skills/ and .claude/commands/.
• Skill files define step-by-step workflows while command files specify CLI triggers and tool permissions, both stored as markdown documentation.
• Runtime implementations use thin-pointer patterns to read these files directly, eliminating hard-coded logic and ensuring automatic synchronization across all agent platforms.

Frequently Asked Questions

What is the single source of truth for workflow specifications in the AI Job Search Framework?

The single source of truth is the .claude/ directory at the repository root. Specifically, .claude/skills/*/*.md contains canonical skill definitions and .claude/commands/*.md houses command specifications. As declared in AGENTS.md, no agent runtime maintains independent copies of these workflows.

How do different AI agents access the centralized workflow specifications?

Every agent runtime—including Claude Code, Google Antigravity, Codex, Cursor, and Gemini CLI—reads the markdown files directly from the .claude/ directory using standard file system operations. The AGENTS.md file explicitly requires this behavior to ensure all platforms execute identical process definitions.

What are the three pillars of the framework architecture mentioned in AGENTS.md?

According to AGENTS.md, the three pillars are: (1) the personal candidate profile stored in CLAUDE.md, (2) the centralized workflow specifications under .claude/skills/ and .claude/commands/, and (3) the portal-search skills. These pillars establish that workflow files serve as the authoritative reference for all operational steps.

Can I modify a workflow without changing the agent implementation code?

Yes. Because agents use a thin-pointer pattern to read markdown specifications at runtime, you only need to edit the relevant file in .claude/skills/ or .claude/commands/. Changes propagate automatically to all agents without modifying JavaScript, Python, or other runtime source code, eliminating configuration drift entirely.

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