craft: Instructions file for Codex

AGENTS.md - Development Guidelines for Craft Plugin

This document provides development guidelines for agentic coding assistants working on the Craft plugin repository. It covers build/lint/test commands, code style conventions, and project-specific practices.

Build/Lint/Test Commands

Primary Test Commands

# Run all unit tests (581+ tests, ~90% coverage)
python3 tests/test_craft_plugin.py

# Run all tests with pytest (includes integration tests)
python3 -m pytest tests/ -v

# Run specific test file
python3 tests/test_craft_plugin.py::TestClass::test_method

# Run integration tests only
python3 tests/test_integration_*.py

# Run dependency system tests
bash tests/test_dependency_management.sh

# Run specific integration test
python3 tests/test_integration_dependency_system.py

Linting and Validation

# Validate command/skill/agent counts match documentation
./scripts/validate-counts.sh

# Markdown linting (24 rules enforced)
npx markdownlint-cli2 "**/*.md" --config .markdownlint.json

# Build documentation site
mkdocs build

# Check broken links (with ignore rules)
python3 tests/test_craft_plugin.py -k "broken_links"

Development Workflow

# Quick validation (lint + test counts)
./scripts/validate-counts.sh && python3 tests/test_craft_plugin.py

# Full CI validation
python3 -m pytest tests/ -v && npx markdownlint-cli2 "**/*.md"

# Documentation validation
mkdocs build && python3 tests/test_craft_plugin.py -k "broken_links"

Code Style Guidelines

Python Conventions

Imports

# Standard library imports first
import json
import os
import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Dict, List, Optional, Tuple

# Third-party imports (none in this project)

# Local imports (alphabetized)
from .complexity_scorer import calculate_complexity_score
from .validators import validate_command_structure

Type Hints

• Always use type hints for function parameters and return values
• Use Optional[T] for nullable types, not Union[T, None]
• Use List[T], Dict[K, V] instead of bare list, dict
• Use dataclasses with field() for complex defaults