AutoSkillit CLAUDE.md

AutoSkillit: Development Guidelines

Mandatory instructions for AI-assisted development in this repository.

1. Core Project Goal

A Claude Code plugin that orchestrates automated skill-driven workflows using headless sessions. It provides MCP tools (gated behind open_kitchen/close_kitchen via FastMCP v3 tag-based visibility) and bundled skills registered as /autoskillit:* slash commands.

2. General Principles

• Follow the Task Description: The issue or ticket is your primary source of truth.
• Adhere to Task Scope: Do not work on unassigned features or unrelated refactoring.
• Implement Faithfully: Produce functionally correct implementations. Do not add unrequested features.
• Adhere to Project Standards: Write clean, maintainable Python following established conventions.

3. Critical Rules - DO NOT VIOLATE

3.0. Skill Invocations Are Orders

• When a message includes a /skill-name, execute it via the Skill tool BEFORE any other action. No exceptions.
• Never skip or substitute a skill invocation based on your own judgment.

3.1. Code and Implementation

• Do Not Oversimplify: Implement logic with required complexity. No shortcuts that compromise correctness.
• Respect the Existing Architecture: Build on established patterns. Understand existing code before modifying.
• Address the Root Cause: Debug to find and fix root causes. No hardcoded workarounds.
• No Backward Compatibility Hacks: No comments about dead code. Remove dead code entirely.
• Avoid Redundancy: Do not duplicate logic or utilities.
• Use Current Package Versions: Web search for current stable versions when adding dependencies.
• Version Bumps: When bumping the package version, update pyproject.toml and run task sync-versions && uv lock; then search tests for hardcoded version strings (e.g. AUTOSKILLIT_INSTALLED_VERSION monkeypatches) and update them.
• Run pre-commit before committing: Always run pre-commit run --all-files before committing. Do not skip this step even when code appears clean — hooks auto-fix formatting and abort the commit, requiring re-stage and retry.
• Hook Renames: Renaming a hook script under src/autoskillit/hooks/ must update HOOK_REGISTRY in hook_registry.py AND add the old basename to RETIRED_SCRIPT_BASENAMES in the same commit. test_no_retired_name_has_a_live_file will fail otherwise.
• Skill Renames: Renaming a skill under src/autoskillit/skills_extended/ (or src/autoskillit/skills/) must update the skill's SKILL.md name: field AND add the old directory name to RETIRED_SKILL_NAMES in src/autoskillit/core/types/_type_constants.py in the SAME commit. test_no_retired_skill_name_has_a_live_directory will fail otherwise.
• Grep tool uses ripgrep (ERE) syntax: Use | for OR-alternation in Grep tool pattern arguments. \| is Bash grep BRE syntax — ripgrep treats it as a literal backslash-pipe and returns 0 results. Example: Grep(pattern="foo|bar") not Grep(pattern="foo\|bar"). In production, grep_pattern_lint_guard.py (hooks/guards/) blocks \| calls with a correction hint. The silent zero-results failure described above only occurs in hook-inactive contexts (e.g., raw CLI usage without the plugin installed).
• Worktree Init Prohibition: Never run autoskillit init from within a git worktree. sync_hooks_to_settings() will raise RuntimeError if pkg_root() resolves to a worktree. Use task install-worktree for worktree setup — it does NOT call init.
• Naming convention — *Def vs *Spec suffixes:
  • *Def — static definition of a registered entity (e.g., HookDef, PackDef, FeatureDef, RuleDef). Typically a NamedTuple or @dataclass(frozen=True), used as elements in a registry or lookup table. Typically lives in core/; stdlib-only types importable from hook scripts may live at the package root (e.g., HookDef in hook_registry.py).
  • *Spec — behavioral specification or validation rule (e.g., ExperimentTypeSpec, WriteBehaviorSpec). Typically a @dataclass or TypedDict configuring a pipeline or validation stage. Typically lives in recipe/ or domain layers; *Spec types used by IL-0 core protocols live in core/ (e.g., WriteBehaviorSpec in core/types/_type_results.py).