Skip to content

Add AI coding agent instruction files and hook architecture#142

Merged
wscourge merged 8 commits intomainfrom
wiktor/ai-rules
Apr 17, 2026
Merged

Add AI coding agent instruction files and hook architecture#142
wscourge merged 8 commits intomainfrom
wiktor/ai-rules

Conversation

@wscourge
Copy link
Copy Markdown
Contributor

@wscourge wscourge commented Apr 15, 2026 •
edited
Loading

Summary

  • Adds AGENTS.md as single source of truth for AI coding assistant context (Cursor, Copilot, Windsurf, Codex, Cline all read it natively)
  • Adds CLAUDE.md as a thin @AGENTS.md import for Claude Code
  • Adds .claude/ with permissions and three hooks tuned for speed
  • Adds .gitignore rules for ephemeral AI tool data while keeping shared config tracked

Hooks

Hook Event Budget What it does
session-start-setup.sh SessionStart <1s Generates session-scoped tracker ID via CLAUDE_ENV_FILE. Reports git branch, dirty files, missing deps (import chartmogul). Local-only, no network.
post-edit-lint.sh PostToolUse (Edit/Write/MultiEdit) <50ms Records edited .py file path to a session-scoped tracker. Deduplicates inline with sort -u. Skips __pycache__/, *.egg-info/, dist/, build/, non-Python. No formatting.
post-stop-validate.sh Stop <1s Batch-lints tracked files with flake8, then runs unittest unconditionally (~0.13s). Reports failures as structured JSON context for the next prompt. Silent on clean runs.

Design decisions

  • Edit path is fast - no formatting or linting on individual edits; batched in Stop hook instead
  • Tests run unconditionally in Stop - suite runs in ~0.13s so the cost is negligible; catches regressions regardless of how code changed (Edit, Bash, file deletion)
  • Session-scoped tracker - tracker filename includes a session ID (via CLAUDE_ENV_FILE) so concurrent sessions on the same machine don't collide
  • No blocking hooks - failures inform the next prompt rather than forcing a retry loop
  • SessionStart is local-only - detects problems (missing package, uncommitted changes) but does not fix them; the agent acts on warnings
  • Aligned with Ruby SDK - same hook pipeline pattern (record-on-edit, batch-in-stop), same CLAUDE_ENV_FILE session ID mechanism, same structured jq output format

Test plan

  • Open the repo in Claude Code and verify CLAUDE.md resolves the @AGENTS.md import
  • Confirm .claude/settings.local.json is gitignored but .claude/settings.json is tracked
  • Edit a .py file and verify the edit completes instantly (no lint delay)
  • After the turn ends, verify the stop hook ran flake8 and unittest (check for structured output on failure)
  • Introduce a syntax error and confirm both lint offenses and test failure summaries appear in context
  • Run two sessions in parallel and confirm their trackers don't collide

wscourge added 2 commits April 15, 2026 17:21
@wscourge
Add AI coding agent instruction files
b2a6ed0 
- AGENTS.md as single source of truth for AI assistant context
- CLAUDE.md as thin @AGENTS.md import for Claude Code
- .claude/settings.json with shared permissions and hook wiring
- .claude/hooks/session-start.sh to install deps on session start
- .claude/hooks/post-edit-lint.sh for fast per-file linting
- .claude/hooks/post-stop-validate.sh for full lint, test, and build
@wscourge
Add .gitignore rules for AI tool ephemeral data
aadd82d 
Ignore plans, todos, local settings, and worktrees from Claude Code
and data directories from Cursor, Aider, Codeium, Copilot, Windsurf,
Cline, and Codex. Shared config (.claude/settings.json, hooks) remains
tracked.
@wscourge
Improve Claude Code hook architecture
f3587d1 
- SessionStart: detect repo state (branch, dirty files, missing deps)
  instead of running pip install. No network, <1s, idempotent.
- PostToolUse: record edited file path only (<50ms). No linting per
  edit - batched to Stop instead.
- Stop: batch-lint touched files with flake8, run test suite (~0.13s).
  Report lint issues and test failures as additionalContext so the
  next turn sees them. Silent on clean runs.
- Add MultiEdit to PostToolUse matcher in settings.json.
@wscourge wscourge changed the title Add AI coding agent instruction files Add AI coding agent instruction files and hook architecture Apr 16, 2026
@wscourge wscourge marked this pull request as draft April 16, 2026 07:10
@wscourge
Align hook architecture with Ruby SDK patterns
539cb3f 
- Add session-scoped file tracker via CLAUDE_ENV_FILE to prevent
  cross-session collisions (matches Ruby SDK approach)
- Rename session-start.sh to session-start-setup.sh for consistency
- Fix python -> python3 usage throughout all hooks
- Fix double git status call in session start
- Run tests unconditionally in Stop (0.13s cost, catches regressions
  even when only Bash commands were used)
- Extract structured lint offenses and test failure summaries instead
  of raw output
- Align .gitignore AI tool entries with Ruby SDK (add .claude/memory,
  scheduled-tasks, credentials.json, CLAUDE.local.md, .continue,
  .junie, granular .cursor paths)
@wscourge wscourge marked this pull request as ready for review April 16, 2026 08:56
loomchild
loomchild reviewed Apr 16, 2026
View reviewed changes
Copy link
Copy Markdown

@loomchild loomchild left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, just 2 random comments. But I am not really qualified to test since I am not using these tools much.

Comment thread .gitignore
Comment thread AGENTS.md Outdated
pkopac
pkopac reviewed Apr 16, 2026
View reviewed changes
Comment thread .claude/settings.json Outdated
wscourge added 2 commits April 16, 2026 14:35
@wscourge
Address PR review feedback
478a446 
- .gitignore: use .claude/* with negation for hooks/ and settings.json
  instead of listing individual subdirs. Use .cursor/ instead of
  individual subdirs. (loomchild)
- AGENTS.md: remove Python version and CI mention from testing section
  - tools can read version from setup.py/CI config (loomchild)
- settings.json: remove gh api from default allow list (pkopac)
@wscourge
Restore granular .cursor/ ignores instead of ignoring whole dir
42f32c2 
.cursor/rules/ can be committed for shared project rules, so only
ignore ephemeral subdirs (chat/, composer/) and local config (mcp.json).
@wscourge
Scope gh permissions to read-only operations
0689a71 
Replace broad Bash(gh pr:*) with granular read-only rules:
- gh pr view/list/diff/checks/status
- gh run view/list/watch
- gh issue view/list
- gh release view/list
- gh repo view
- gh search

Write operations (gh pr create/edit/merge, gh api POST) will now
prompt for confirmation instead of running automatically.
@wscourge wscourge requested review from pkopac and removed request for MariaBraganca, mynameispedro and pkopac April 16, 2026 13:04
@wscourge
Use built-in session_id and project-local tracker path
76840f3 
- session-start-setup.sh: read session_id from hook input JSON instead
  of generating a custom one
- Move file tracker from /tmp to .claude/tmp/ (already gitignored by
  .claude/* rule) so hooks don't write outside the project directory
@wscourge wscourge requested a review from pkopac April 16, 2026 13:18
@wscourge wscourge merged commit d32e6ba into main Apr 17, 2026
7 checks passed
@wscourge wscourge deleted the wiktor/ai-rules branch April 17, 2026 08:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@loomchild loomchild loomchild left review comments

@pkopac pkopac Awaiting requested review from pkopac

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@wscourge @loomchild @pkopac