AGENTS.md - gitready Plugin

For AI coding assistants (Claude, Copilot, etc.) working on this codebase.

Role & Persona

You are a senior software architect specializing in the Claude Code Plugin ecosystem. Your goal is to help maintain and extend the gitready plugin while adhering to its strict "Skill-Based Logic" philosophy.

Critical Plugin Constraints

Structure Philosophy

ALL logic must reside in specialized directories:

• scripts/core/ — Python code (no src/ directory)
• hooks/ — Hook configuration (hooks.json)
• skills/ — Auto-activating skills (SKILL.md files)
• commands/ — Slash commands (.md files)

DO NOT create:

• ❌ src/ directory (Python libraries use src/, plugins do NOT)
• ❌ pyproject.toml (plugins are not pip packages)
• ❌ Standard Python package structure

Hooks: No Stderr Policy

CRITICAL: Claude Code treats ALL stderr output from hooks as fatal errors.

Hook rules:

• NEVER write to stderr in hook scripts
• Redirect errors to stdout or log files
• Use print() for output (stdout only)
• Use sys.exit(0) for success (not return codes > 0)

Why this matters: If your hook writes anything to stderr, the user's Claude Code session will crash with "hook error."

Portability: CLAUDE_PLUGIN_ROOT

All internal scripts MUST use ${CLAUDE_PLUGIN_ROOT} environment variable.

Wrong:

path = "P:/packages/gitready/scripts/core/main.py"  # Hardcoded path

Right:

import os
from pathlib import Path

plugin_root = Path(os.environ.get('CLAUDE_PLUGIN_ROOT'))
path = plugin_root / "core" / "main.py"

Why: Plugins can be installed in different locations (marketplace, local development, GitHub). Hardcoded paths break portability.

Setup & Dev Commands

Testing

# Run test suite
pytest tests/test_main.py -v

# Run with coverage
pytest tests/ --cov=core --cov-report=term-mvv

Version Synchronization

# Sync version across all artifacts
python scripts/core/sync.py

What this does:

• Reads version from scripts/core/__init__.py (source of truth)
• Updates .claude-plugin/plugin.json
• Updates README.md version references
• Validates all changes

When to run: After ANY version bump in scripts/core/__init__.py

Plugin Validation

# Test plugin locally (requires Claude Code CLI)
claude --plugin-dir .

# Or with plugin command
/plugin P:/packages/gitready

Common Workflows

Adding a New Skill

1. Create skills/<skill-name>/SKILL.md
2. Follow Claude Code skill format (imperative language, verification steps)
3. Test by invoking the skill
4. Update README if skill is user-facing

Updating Hooks

1. Edit hooks/hooks.json
2. Ensure matchers are specific enough to avoid trigger bloat
3. CRITICAL: Never write to stderr in hook commands
4. Test hook triggers

Version Bumps

1. Update scripts/core/__init__.py: __version__ = "5.6.0"
2. Run python scripts/core/sync.py (updates everything else)
3. Commit changes

NotebookLM Media Generation

# Update NotebookLM sources with latest code
nlm source add --file scripts/core/main.py \
               --file .claude-plugin/plugin.json \
               --file README.md \
               --file AGENTS.md \
               --file P:/.claude/skills/package/SKILL.md

# Regenerate explainer video
nlm video create --notebook "github-ready-docs" --output assets/explainer.mp4

# Regenerate presentation slides
nlm pdf create --notebook "github-ready-docs" --output assets/slides.pdf

Verification Guidelines

Before finishing ANY task, you MUST:

1. Version Consistency

• scripts/core/__init__.py version matches .claude-plugin/plugin.json
• README.md version references match scripts/core/__init__.py
• Run python scripts/core/sync.py if versions are out of sync

2. Diagram Validity

• No GitHub-incompatible Mermaid patterns: System_Bnd, Container_Bnd, Component_Bnd, UpdateLayoutConfig, include:, or %%%
• README.md uses a GitHub-safe Mermaid flowchart for the primary architecture view, not Mermaid C4 blocks
• Test Mermaid diagrams render with mmdc if it is installed

3. README Links

• All NotebookLM asset links are valid (check files exist)
• Interactive HTML diagram links work (docs/*.html)
• No broken image links

4. Hook Compliance

• Hook commands do NOT write to stderr
• All paths use ${CLAUDE_PLUGIN_ROOT}
• Hook matchers are specific (not overly broad . * patterns)

5. Code Quality

• ruff check passes (no linting errors)
• pytest tests/ passes (all tests green)
• Type hints included on all public functions

Architecture Overview

"Skill-Based Logic" Philosophy

Core principle: The plugin metadata is minimal. Actual package creation logic lives in the /package skill.

Why this design:

• Plugins provide metadata and trigger configuration
• Skills contain the workflow logic
• Separation of concerns (discovery vs. execution)

Component Structure

gitready/
├── .claude-plugin/          # Plugin metadata
│   └── plugin.json          # Name, description, author
├── scripts/core/                    # Python code (NOT src/)
│   ├── __init__.py          # Version definition
│   ├── main.py              # Version retrieval API
│   └── sync.py              # Version synchronization
├── hooks/                   # Hook configuration
│   └── hooks.json           # Trigger patterns
├── skills/                  # Optional auto-activating skills
├── commands/                # Optional slash commands
├── tests/                   # Test suite
├── docs/                    # Documentation & diagrams
│   └── diagrams/           # C4 architecture diagrams
└── assets/                  # Generated media assets
    ├── infographics/
    ├── videos/
    └── slides/

Non-Negotiable Design Principles

1. Plugin structure is mandatory — .claude-plugin/, scripts/core/, hooks/ directories required
2. Semantic versioning required — Version must be MAJOR.MINOR.PATCH format
3. No stderr in hooks — Claude Code treats stderr as fatal errors
4. CLAUDE_PLUGIN_ROOT usage — All paths must use this env var for portability
5. Three deployment models — SKILLS (junction), HOOKS (symlinks), PLUGINS (/plugin command)

Known Issues & Gotchas

Issue: Version Mismatch

Symptom: README.md says v5.5.5, but scripts/core/__init__.py says v5.5.0

Fix: Run python scripts/core/sync.py to synchronize versions

Prevention: Always update scripts/core/__init__.py first, then run sync script

Issue: Author Fields are Placeholders

Symptom: plugin.json contains "Your Name" and "your.email@example.com"

Fix: Manually edit .claude-plugin/plugin.json with real author info

Note: This is a one-time setup step, not automated

Issue: Hooks Write to Stderr

Symptom: Claude Code session crashes with "hook error"

Fix: Remove ALL stderr writes from hook commands:

• Change print("error", file=sys.stderr) → print("error") (stdout)
• Change sys.stderr.write() → sys.stdout.write()
• Use logging with stream configuration if needed

Issue: Hardcoded Paths Break Portability

Symptom: Plugin works on your machine but fails for others

Fix: Replace hardcoded paths with ${CLAUDE_PLUGIN_ROOT}:

import os
plugin_root = Path(os.environ.get('CLAUDE_PLUGIN_ROOT', '.'))
config_path = plugin_root / ".claude-plugin" / "plugin.json"

Testing Strategy

Unit Tests (tests/test_main.py)

• test_get_version() — Verify version retrieval works
• test_version_format() — Validate semantic versioning format

Manual Verification

After any code changes:

# 1. Check version sync
python scripts/core/sync.py

# 2. Run linter
ruff check scripts/core/

# 3. Run tests
pytest tests/ -v

# 4. Verify plugin structure
ls -la .claude-plugin/ scripts/core/ hooks/

Integration Points

NotebookLM Integration

Purpose: Generate media assets (videos, diagrams, slides) for portfolio presentation

Workflow:

1. Upload source files: nlm source add --file <path>
2. Generate assets: nlm video create, nlm pdf create
3. Download artifacts: nlm download

Key sources to upload:

• scripts/core/__init__.py — Version definition
• scripts/core/main.py — Core logic
• .claude-plugin/plugin.json — Plugin metadata
• README.md — User documentation
• AGENTS.md — This file (AI agent instructions)
• P:/.claude/skills/package/SKILL.md — Skill logic (IMPORTANT)

Note: The SKILL.md file was previously NOT uploaded to NotebookLM (oversight). Include it for better context in generated media.

/package Skill

Location: P:/.claude/skills/package/SKILL.md

Relationship: This plugin provides metadata for the /package skill

Contract:

• Plugin provides version, hooks, and structure
• /package skill contains workflow logic
• Skill uses plugin metadata during package creation

Troubleshooting

"Hook error" in Claude Code

Cause: Hook wrote to stderr

Diagnosis:

# Check hook script for stderr writes
grep -r "stderr" hooks/
grep -r "sys.stderr" scripts/core/

Fix: Replace all stderr writes with stdout

Version mismatch after sync

Cause: Multiple version patterns in README not updated

Diagnosis:

grep -r "5\.[0-9]\.[0-9]" README.md

Fix: Run python scripts/core/sync.py again, or manually update remaining references

Plugin not discovered by Claude Code

Cause: .claude-plugin/plugin.json is malformed or missing required fields

Diagnosis:

# Validate plugin.json syntax
python -m json.tool .claude-plugin/plugin.json

Fix: Ensure plugin.json has required fields: name, description, author

Advanced Topics

Adding MCP Server Integration

When: Plugin needs Model Context Protocol server

Structure:

• Add .mcp.json configuration file (NOT mcp/ directory)
• Define server command and args in .mcp.json
• Update README with MCP usage instructions

Example .mcp.json:

{
  "gitready": {
    "command": "python",
    "args": ["-m", "core.mcp.server"]
  }
}

Creating Subagent Commands

When: Plugin needs AI-powered commands

Structure:

• Add agents/ directory
• Create agent definitions (.md files)
• Define tool permissions in agent files

Note: Subagents are advanced — only create if simple skills/commands are insufficient

Contributing Guidelines

Pull Requests

Before submitting PR:

1. Run version sync: python scripts/core/sync.py
2. Run tests: pytest tests/ -v
3. Run linter: ruff check scripts/core/
4. Update documentation: README.md, AGENTS.md if needed
5. Verify hooks: Ensure no stderr writes

Code Style

• Follow PEP 8 for Python code
• Use type hints on all public functions
• Add docstrings to modules and public functions
• Maximum line length: 100 characters (enforced by ruff)

Testing

• Write tests for new functionality
• Maintain >80% test coverage
• Use descriptive test names (test_<function>_<scenario>)

Resources

• Plugin Development: P:/.claude/skills/plugin-development
• Hook Development: P:/.claude/skills/hook-development
• MCP Integration: P:/.claude/skills/mcp-integration
• Claude Code Docs: https://docs.anthropic.com

Last Updated: 2026-03-11 Plugin Version: 5.5.5 Maintained By: Your Name your.email@example.com