docs: restructure agent instruction files

[kevinmessiaen]

Summary

• Rewrites CLAUDE.md and AGENTS.md to follow Boris Cherny's recommended CLAUDE.md structure (Workflow Orchestration → Task Management → Core Principles)
• CLAUDE.md targets Claude Code (interactive, human in the loop) with plan mode, subagent strategy, elegance, and verification rules
• AGENTS.md targets autonomous agents (no human in the loop) — lean, self-contained, setup+commands inside Workflow Orchestration
• Adds lessons.md for capturing corrected mistakes session by session
• Extends .cursor/rules/guidelines.mdc with two new rules: Root Causes No Temporary Fixes, Minimal Scope
• Adds Verification Gate section to the giskard-oss-pr-ready skill
• Replaces "Autonomous Execution" with Clarify Before Acting: agents must comment on the issue (not open a PR) when scope is unclear, propose alternatives before implementing them, and push back on PR comments they disagree with rather than applying changes blindly

Test plan

• Read CLAUDE.md — confirm 3 sections, ~50 lines, no operational content
• Read AGENTS.md — confirm 3 sections, ~60 lines, setup+commands inside Workflow Orchestration
• Read lessons.md — confirm terse format
• Read .cursor/rules/guidelines.mdc — confirm 5 rules total
• Read section 6 of AGENTS.md — confirm clarify-before-acting policy covers ambiguous issues, better suggestions, and PR comment disagreements

[gemini-code-assist]

Code Review

This pull request updates the repository's AI agent guidelines and documentation. It introduces new rules for root cause analysis and minimal scope in the Cursor rules, adds a verification gate requiring test evidence in the skill documentation, and completely restructures AGENTS.md and CLAUDE.md to provide clearer workflow orchestration for autonomous and interactive agents. A new lessons.md file is also created to track process improvements. The review feedback correctly identifies inconsistent file paths for the task management documentation and suggests including critical operational warnings about using uv run in the Claude-specific guide to ensure consistency and prevent execution failures.

[gemini-code-assist]

The path to the todo file is inconsistent with other references in this file (lines 12 and 33). It should be updated to tasks/todo.md to ensure clarity for automated agents.

Suggested change

	2. Verify Plan — review before starting; proceed if unambiguous
	5. Document Results — add review section to tasks/todo.md

[gemini-code-assist]

The header is missing the link to README.md and the critical warning about using uv run, which are present in AGENTS.md. Including these ensures consistency across agent documentation and prevents operational failures when the assistant attempts to run commands directly.

Suggested change

	giskard-oss — behavioral config for Claude Code (interactive assistant with a human in the loop).
	giskard-oss — behavioral config for Claude Code (interactive assistant with a human in the loop). Human-oriented docs: [README.md](README.md). Always invoke Python via uv run — bare python or pytest will fail.

[gemini-code-assist]

The path to the todo file is inconsistent with other references in this file (lines 9 and 37). It should be updated to tasks/todo.md for consistency.

Suggested change

	5. Document Results — add review section to todo.md
	5. Document Results — add review section to tasks/todo.md