Consolidate documentation and add SessionStart hook for AI assistants #400
Conversation
- Add SessionStart hook (.claude/hooks/SessionStart.sh) to auto-verify environment setup - Consolidate AGENTS.md content into docs/reference/contributing.md (single source of truth) - Enhance README.md with better examples, features, use cases, and community links - Update docs/index.md to include README content (eliminates duplication) - Remove .github/AGENTS.md (no longer needed) Benefits: - No duplication between files - easier maintenance - SessionStart hook ensures proper setup for Claude Code sessions - Contributing.md is now comprehensive guide for both humans and AI - README provides rich landing page while feeding docs homepage - Tool-agnostic approach works for all AI assistants
There was a problem hiding this comment.
Pull request overview
This PR consolidates documentation and adds a SessionStart hook for AI assistants to streamline the development environment setup. It eliminates documentation duplication by making docs/reference/contributing.md the single source of truth for developer guidance.
Changes:
- Added SessionStart hook to auto-verify environment setup for Claude Code sessions
- Consolidated agent instructions from
.github/AGENTS.mdintodocs/reference/contributing.md - Enhanced README.md with improved structure, features, use cases, and community links
- Updated
docs/index.mdto include README content via MyST directive
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
.claude/hooks/SessionStart.sh |
New script to validate development environment on session start |
README.md |
Enhanced with better structure, examples, features section, and community links |
docs/index.md |
Now includes README content to avoid duplication |
docs/reference/contributing.md |
Consolidated with agent instructions, added Quick Reference and comprehensive architecture overview |
.github/AGENTS.md |
Removed (content migrated to contributing.md) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| if uv sync --all-extras --locked 2>&1 | grep -q "Resolved"; then | ||
| echo "✅ Dependencies synced successfully" | ||
| else | ||
| echo "✅ Dependencies already up to date" |
There was a problem hiding this comment.
The grep logic for detecting successful dependency sync may not work reliably. The command checks if "Resolved" appears in the output, but uv sync --all-extras --locked with --locked flag will not resolve dependencies (it uses the lockfile). Consider checking the exit code instead or adjusting the conditional to better reflect what uv sync --locked actually outputs.
| if uv sync --all-extras --locked 2>&1 | grep -q "Resolved"; then | |
| echo "✅ Dependencies synced successfully" | |
| else | |
| echo "✅ Dependencies already up to date" | |
| if uv sync --all-extras --locked; then | |
| echo "✅ Dependencies are in sync" | |
| else | |
| echo "❌ Failed to sync dependencies" | |
| exit 1 |
| # Run ruff check (non-blocking) | ||
| echo " → Checking code style with ruff..." | ||
| if uv run ruff check . --quiet 2>&1; then | ||
| echo " ✅ Ruff checks passed" | ||
| else | ||
| echo " ⚠️ Ruff found some issues (run 'uv run ruff check --fix .' to auto-fix)" | ||
| fi | ||
|
|
||
| # Run quick type check (non-blocking) | ||
| echo " → Type checking with mypy..." | ||
| if make mypy 2>&1 | tail -n 1 | grep -q "Success"; then | ||
| echo " ✅ Type checks passed" | ||
| else | ||
| echo " ⚠️ Type check issues found (run 'make mypy' for details)" | ||
| fi |
There was a problem hiding this comment.
The error handling for ruff and mypy checks may not work as expected. Both commands redirect stderr to stdout with 2>&1, but if these commands fail, they won't cause the script to exit (due to the conditional if statement). However, since these are marked as non-blocking validation checks in the comment, the current behavior might be intentional. Consider making it clearer by removing set -e from affecting these commands or adding || true to make the intent explicit.
|
|
||
| Here's how to use egglog to prove that `2 * (x + 3)` is equivalent to `6 + 2 * x` through algebraic rewriting: | ||
|
|
||
| ```{code-cell} python |
There was a problem hiding this comment.
The code block uses MyST-NB directive {code-cell} python which is designed for Sphinx documentation with the MyST-NB extension. This won't render properly on GitHub or PyPI where the README is typically displayed. Consider using standard markdown code fences (```python) for the README, or ensure that the rendering context (e.g., on PyPI) supports MyST-NB directives.
| ```{code-cell} python | |
| ```python |
| ```{include} ../README.md | ||
| :start-after: # egglog Python | ||
| :end-before: ## License | ||
| ``` |
There was a problem hiding this comment.
The include directive skips the main h1 heading from README.md (using :start-after: # egglog Python), which means the docs homepage will have no h1 heading. This is problematic for document structure and SEO. Consider either removing the :start-after: directive to include the heading, or adding a dedicated h1 heading before the include directive in docs/index.md.
CodSpeed Performance ReportMerging this PR will not alter performanceComparing Summary
|
Benefits: