docs: align Homebrew workflow with automation and add CLAUDE.md

[paxcalpt]

Summary

This PR addresses documentation inconsistency and adds comprehensive AI assistant guidelines via CLAUDE.md. Aligns with ecosystem-wide improvements across HenriquesLab repositories.

Aligns with:

• rxiv-maker PR #280
• folder2md4llms PR #37

Changes Made

1. ✅ Update CONTRIBUTING.md - Homebrew Workflow

• Added just release taskrepo as the recommended method
• Restructured to show automated workflow first
• Kept manual workflow as alternative for contributors without just
• Changed VERSION=0.10.17 → VERSION=X.Y.Z (clear placeholder)
• Changed ~/GitHub/homebrew-formulas → ../homebrew-formulas (relative path)
• Added context about homebrew-formulas repository utilities

2. ✅ Create CLAUDE.md - AI Assistant Guidelines

New file with comprehensive documentation for AI assistants:

Contents:

• Project Overview: TaskRepo architecture and features
• Development Environment: Setup, dependencies, testing
• Release Process: Version bumping and PyPI workflow
• Homebrew Formula Updates: Full automation documentation
  • Automated just release workflow (recommended)
  • Manual workflow (alternative)
  • Utility commands reference
• Code Style: PEP 8, type hints, docstrings
• Testing Strategy: Unit and integration tests
• Security Considerations: Input validation, credentials

3. ✅ Update .gitignore

• Added !CLAUDE.md exception to allow tracking
• TaskRepo uses restrictive .md ignore pattern with explicit allowlist

Testing

• ✅ Documentation-only changes (no code modifications)
• ✅ Verified CLAUDE.md is now tracked by git
• ✅ Verified with git diff

Benefits

• Consistency: Aligns with rxiv-maker and folder2md4llms patterns
• Automation: Documents the preferred just-based workflow
• AI Assistant Support: CLAUDE.md enables better automated contributions
• Maintainability: Centralized automation documentation

Workflow Alignment

This PR ensures consistency between:

• CONTRIBUTING.md - Contributor-facing documentation
• CLAUDE.md - AI assistant and automation guidelines
• homebrew-formulas repository - Formula management automation

Both workflows (automated and manual) are now documented, with automation clearly marked as recommended.

[claude]

Pull Request Review - PR #12

Summary

This PR adds comprehensive documentation improvements with CLAUDE.md guidelines and aligns the Homebrew release workflow documentation. The changes are documentation-only with no code modifications.

---

✅ Strengths

1. Documentation Consistency

• Excellent alignment across CLAUDE.md, CONTRIBUTING.md, and external homebrew-formulas repository
• Clear distinction between automated (recommended) and manual workflows
• Consistent use of relative paths (../homebrew-formulas) instead of absolute paths

2. AI Assistant Guidelines (CLAUDE.md)

• Comprehensive coverage of project architecture, setup, and workflows
• Well-structured sections covering all key areas:
  • Development environment setup
  • Release process
  • Code style and testing strategy
  • Security considerations
• Appropriate use of the .gitignore exception to track this file

3. Workflow Documentation

• Strong improvement in CONTRIBUTING.md with clear prioritization of automated workflow
• Good use of placeholders (X.Y.Z instead of specific versions)
• Detailed step-by-step instructions for both automated and manual approaches

---

🔍 Observations & Suggestions

1. Documentation Completeness ✓

Status: All changes look complete and accurate

The documentation correctly references:

• UV package manager (aligned with project setup)
• Ruff for linting/formatting (matches pyproject.toml config)
• MyPy for type checking (matches development dependencies)
• PyTest for testing (matches test infrastructure)

2. .gitignore Pattern ✓

Status: Correct implementation

*.md
!README.md
!CHANGELOG.md
!CONTRIBUTING.md
!CLAUDE.md

This pattern is appropriate for TaskRepo since it stores tasks as markdown files in ~/.taskrepo/ directories, and the explicit allowlist approach prevents accidental commits of task files while preserving important documentation.

3. Consistency Check ✓

Status: Aligned across files

Verified consistency between:

• CLAUDE.md (lines 56-85): Documents the automated workflow with just release taskrepo
• CONTRIBUTING.md (lines 36-105): Mirrors the same workflow with identical command sequences
• Both correctly reference the external homebrew-formulas repository

4. Testing Strategy ✓

Status: Appropriate for documentation changes

The PR correctly identifies these as documentation-only changes requiring no code testing. The verification approach (git diff, tracked file check) is suitable.

---

🎯 Code Quality Assessment

Documentation Quality: ⭐⭐⭐⭐⭐

• Clear, concise, and well-organized
• Appropriate level of detail for target audiences
• Good use of code blocks and formatting

Best Practices: ⭐⭐⭐⭐⭐

• Follows project conventions (see CLAUDE.md adherence to PEP 8, Google-style docstrings)
• Proper git hygiene with .gitignore updates
• No security concerns (documentation only)

Maintainability: ⭐⭐⭐⭐⭐

• Centralized documentation reduces duplication
• Clear workflows reduce maintenance burden
• Version placeholders (X.Y.Z) prevent documentation drift

---

🔒 Security Considerations

Status: ✅ No security concerns

• No code changes
• No credential or secret exposure
• Documentation correctly emphasizes security in CLAUDE.md:
  • Input sanitization (line 128)
  • Repository URL validation (line 129)
  • Secure git credential handling (line 130)

---

📊 Test Coverage

Status: ✅ N/A (Documentation only)

No test coverage changes required. The existing test suite remains intact with tests for:

• Unit tests (task management, GitHub integration, merge logic)
• Integration tests
• Coverage maintained via CI/CD pipeline

---

🎨 Style & Conventions

Alignment with CLAUDE.md: ✅ Perfect

The documentation itself follows the guidelines it establishes:

• Clear formatting with headers and code blocks
• Consistent terminology
• Appropriate use of examples
• Professional tone

---

💡 Minor Suggestions (Optional)

1. CLAUDE.md - Homebrew Formula Section

Consider adding a note about when the homebrew-formulas repository is available:

**Note:** The homebrew-formulas repository must be cloned as a sibling to TaskRepo for these commands to work.

2. CONTRIBUTING.md - Prerequisites

Consider mentioning that just installation is needed for the automated workflow:

# Install just (if not already installed)
# macOS: brew install just
# Linux: cargo install just
# Or see: https://github.com/casey/just#installation

However, these are very minor suggestions and not blockers. The PR is excellent as-is.

---

✅ Final Recommendation

APPROVE ✅

This PR is ready to merge. It provides:

• Clear, comprehensive documentation for AI assistants
• Improved workflow documentation for contributors
• No code changes means minimal risk
• Excellent alignment with project conventions
• Strong foundation for ecosystem-wide consistency

Merge Checklist

• ✅ Code quality: N/A (documentation only)
• ✅ Security: No concerns
• ✅ Testing: Appropriate for doc changes
• ✅ Style: Follows project conventions
• ✅ Completeness: All related docs updated

Great work on improving the documentation and establishing clear guidelines for AI-assisted contributions! This aligns well with modern development practices.

---

Reviewed by: Claude Sonnet 4.5
Review Date: 2026-02-02
PR: #12

[Copilot]

Pull request overview

This PR enhances TaskRepo's documentation by aligning Homebrew formula update workflows with the automated tools in the homebrew-formulas repository and adding comprehensive AI assistant guidelines. The changes are documentation-only and establish consistency across HenriquesLab repositories.

Changes:

• Updated CONTRIBUTING.md to prioritize automated just release workflow over manual steps, with clearer organization and improved placeholder values
• Added CLAUDE.md with comprehensive guidelines for AI assistants, covering development setup, release process, Homebrew automation, code style, and testing strategy
• Updated .gitignore to explicitly allow tracking of CLAUDE.md

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

File	Description
CONTRIBUTING.md	Restructured Homebrew update section to emphasize automated workflow; improved clarity with relative paths and generic version placeholders
CLAUDE.md	New comprehensive guide for AI assistants with project overview, development environment setup, release process, Homebrew automation, and code conventions
.gitignore	Added exception to allow tracking CLAUDE.md following existing markdown file allowlist pattern

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The version should be updated in src/taskrepo/__version__.py, not pyproject.toml. The pyproject.toml file uses dynamic = ["version"] and references the version from src/taskrepo/__version__.py via the hatch configuration at line 121.

Suggested change

	1. Update version in `pyproject.toml`
	1. Update version in `src/taskrepo/__version__.py` (version is read dynamically in `pyproject.toml`)

[Copilot]

The sentence is missing a period at the end. It should end with "...and just sha256." to match standard punctuation conventions.

Suggested change

	**Note:** The automated workflow using `just` is preferred for consistency and efficiency. See the [homebrew-formulas repository](https://github.com/HenriquesLab/homebrew-formulas) for additional utility commands like `just list`, `just check-updates`, and `just sha256`
	**Note:** The automated workflow using `just` is preferred for consistency and efficiency. See the [homebrew-formulas repository](https://github.com/HenriquesLab/homebrew-formulas) for additional utility commands like `just list`, `just check-updates`, and `just sha256`.

[Copilot]

The project uses prompt_toolkit for interactive prompts, not questionary. This can be verified in pyproject.toml line 29 which lists "prompt_toolkit>=3.0.0" as a dependency.

Suggested change

	- Interactive prompts using questionary
	- Interactive prompts using prompt_toolkit

[paxcalpt]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

This PR successfully:

• Aligns CONTRIBUTING.md with automated workflow pattern
  • Prioritizes just release taskrepo (recommended)
  • Fixes hardcoded version (0.10.17 → X.Y.Z)
  • Updates paths (~/GitHub → ../homebrew-formulas)
• Creates CLAUDE.md with comprehensive automation guidelines
  • Homebrew formula workflow documentation
  • Development environment setup
  • Release process and testing strategy
• Updates .gitignore to allow CLAUDE.md tracking

Changes align with rxiv-maker PR #280 and folder2md4llms PR #37 patterns. Adds TaskRepo-specific automation documentation for AI assistants.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}