feat(docs): Create agent.md and docs folder (#1312)

Author: mkmeral

AGENTS.md

@@ -122,7 +122,7 @@ hatch fmt --linter
 
 If you're using an IDE like VS Code or PyCharm, consider configuring it to use these tools automatically.
 
-For additional details on styling, please see our dedicated [Style Guide](./STYLE_GUIDE.md).
+For additional details on styling, please see our dedicated [Style Guide](./docs/STYLE_GUIDE.md).
 
 
 ## Contributing via Pull Requests

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Hooks System
+
+The hooks system enables extensible agent functionality through strongly-typed event callbacks.
+
+## Terminology
+
+- **Paired events**: Events that denote the beginning and end of an operation
+- **Hook callback**: A function that receives a strongly-typed event argument
+- **Hook provider**: An object implementing `HookProvider` that registers callbacks via `register_hooks()`
+
+## Naming Conventions
+
+- All hook events have a suffix of `Event`
+- Paired events follow `Before{Action}Event` and `After{Action}Event`
+- Action words come after the lifecycle indicator (e.g., `BeforeToolCallEvent` not `BeforeToolEvent`)
+
+## Paired Events
+
+- For every `Before` event there is a corresponding `After` event, even if an exception occurs
+- `After` events invoke callbacks in reverse registration order (for proper cleanup)
+
+## Writable Properties
+
+Some events have writable properties that modify agent behavior. Values are re-read after callbacks complete. For example, `BeforeToolCallEvent.selected_tool` is writable - after invoking the callback, the modified `selected_tool` takes effect for the tool call.

docs/HOOKS.md

@@ -0,0 +1,15 @@
+# Developer Documentation
+
+This folder contains documentation for contributors and developers working on the Strands Agents SDK.
+
+## Contents
+
+- [STYLE_GUIDE.md](./STYLE_GUIDE.md) - Code style conventions and formatting guidelines
+- [HOOKS.md](./HOOKS.md) - Hooks system rules and usage guide
+- [MCP_CLIENT_ARCHITECTURE.md](./MCP_CLIENT_ARCHITECTURE.md) - MCP client threading architecture and design decisions
+
+## Related Documentation
+
+- [AGENTS.md](../AGENTS.md) - Guidance for AI agents and LLMs working with this codebase
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines for human contributors
+- [strandsagents.com](https://strandsagents.com/) - User-facing documentation