feat: Add lifecycle hooks (beforeStep/afterStep)

README.md

@@ -24,6 +24,7 @@
 * **Builder Pattern**: Easily create our automation with an intuitive DSL.
 * **Reduce Complexity**: Design advanced scenarios with a single expression in minutes.
 * **Type-safety**: Benefit from type-safety and autocompletion for a robut development experience.
+* **Lifecycle Hooks**: Extend scenarios with beforeStep and afterStep hooks for logging, monitoring, validation, and more.
 * **Discover**: Find inspirations with a curated list of Trotsky implementations.
 
 ## Quickstart
@@ -57,6 +58,37 @@ async function main() {
 main()
 ```
 
+## Lifecycle Hooks
+
+Extend your scenarios with `beforeStep` and `afterStep` hooks for logging, monitoring, validation, and more:
+
+```ts
+import { Trotsky } from "trotsky"
+
+const trotsky = new Trotsky(agent)
+
+// Log when steps start
+trotsky.beforeStep((step, context) => {
+  console.log(`Starting: ${step.constructor.name}`)
+})
+
+// Track performance after each step
+trotsky.afterStep((step, context, result) => {
+  console.log(`Completed: ${step.constructor.name} (${result.executionTime}ms)`)
+
+  if (result.executionTime > 1000) {
+    console.warn('Slow step detected!')
+  }
+})
+
+await trotsky
+  .actor('alice.bsky.social')
+  .createPost('Hello world!')
+  .run()
+```
+
+See the [Hooks Documentation](https://trotsky.pirhoo.com/guide/hooks.html) for comprehensive guides and examples.
+
 ## Next Steps
 
 Find out more about how to use Trotsky with advanced scenario on the official [documentation](https://trotsky.pirhoo.com).

docs/.vitepress/config.mts

@@ -48,6 +48,7 @@ export default defineConfig({
           { text: 'Getting started', link: '/guide/getting-started' },
           { text: 'Why Trotsky', link: '/guide/why' },
           { text: 'Features', link: '/guide/features' },
+          { text: 'Lifecycle Hooks', link: '/guide/hooks' },
           { text: 'Code of Conduct', link: '/guide/code-of-conduct' },
           { text: 'Architecture', link: '/guide/architecture' },
           { text: 'FAQ', link: '/guide/faq' },

docs/guide/architecture.md

@@ -365,41 +365,6 @@ describe('StepActor', () => {
 })
 ```
 
-## Future Architecture Plans
-
-### 1. Plugin System
-
-Support for custom plugins:
-
-```typescript
-Trotsky.init(agent)
-  .use(new AnalyticsPlugin())
-  .use(new CachePlugin())
-```
-
-### 2. Middleware
-
-Request/response interceptors:
-
-```typescript
-Trotsky.init(agent)
-  .beforeStep((step) => console.log(`Executing: ${step.name}`))
-  .afterStep((step) => console.log(`Completed: ${step.name}`))
-```
-
-### 3. Advanced Caching
-
-Built-in caching layer for frequently accessed data:
-
-```typescript
-Trotsky.init(agent, {
-  cache: {
-    enabled: true,
-    ttl: 60000
-  }
-})
-```
-
 ## Best Practices
 
 1. **Use Type Inference**: Let TypeScript infer types instead of explicit annotations