mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
fix(docs): doc-lifecycle sweep — delete byte-dup, duplicates gate, BC6 label, career-leak excision, hookless reconcile (age-gate-the-ungated-egwt.12)
This commit is contained in:
boshu
@@ -130,11 +130,11 @@ Located in `.claude/workflows/meta-observer/`
|
||||
- Quick start guides
|
||||
- All included artifacts
|
||||
|
||||
2. **`pattern-guide.md`**
|
||||
2. **`../meta-observer-pattern.md`**
|
||||
- Full pattern documentation
|
||||
- Architecture, principles, usage
|
||||
- Examples, troubleshooting
|
||||
- [View guide →](./pattern-guide.md)
|
||||
- [View guide →](../meta-observer-pattern.md)
|
||||
|
||||
3. **`example-today.md`**
|
||||
- Today's experiment (2025-11-09)
|
||||
@@ -394,9 +394,9 @@ This pattern validates and uses:
|
||||
│ ├── meta-observer.md # Observer agent protocol
|
||||
│ └── autonomous-worker.md # Worker template
|
||||
└── workflows/
|
||||
├── meta-observer-pattern.md # Full pattern documentation
|
||||
└── meta-observer/
|
||||
├── README.md # This file - overview
|
||||
├── pattern-guide.md # Full pattern documentation
|
||||
├── example-today.md # Real experiment example
|
||||
└── SHOWCASE.md # Public demonstration doc
|
||||
```
|
||||
@@ -464,7 +464,7 @@ This pattern validates and uses:
|
||||
## Support
|
||||
|
||||
**Questions?**
|
||||
- Read: `pattern-guide.md` (comprehensive)
|
||||
- Read: `../meta-observer-pattern.md` (comprehensive)
|
||||
- Example: `example-today.md` (real usage)
|
||||
- Showcase: `SHOWCASE.md` (for presentations)
|
||||
|
||||
|
||||
@@ -1,555 +0,0 @@
|
||||
# Meta-Observer Pattern: Autonomous Multi-Session Coordination
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Status:** Production-ready ✅
|
||||
**Discovered:** 2025-11-09
|
||||
**Pattern Type:** Multi-session coordination via stigmergy
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Meta-Observer Pattern** enables N autonomous workers to coordinate through shared memory (Memory MCP) without central orchestration.
|
||||
|
||||
**Key Innovation:** Emergent coordination > Central control
|
||||
|
||||
**Inspiration:** Ant colonies (pheromone trails/stigmergy), not military (command/control)
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
**Traditional multi-session coordination:**
|
||||
- ❌ Central orchestrator becomes bottleneck
|
||||
- ❌ Micromanagement slows workers
|
||||
- ❌ Orchestrator doesn't know domain context
|
||||
- ❌ Single point of failure
|
||||
- ❌ Doesn't scale (coordination overhead increases with N)
|
||||
|
||||
**Result:** Slower than serial work, despite parallelization
|
||||
|
||||
---
|
||||
|
||||
## Solution
|
||||
|
||||
**Autonomous workers + Shared memory + Minimal intervention observer**
|
||||
|
||||
```
|
||||
WORKERS (N sessions) MEMORY MCP META-OBSERVER
|
||||
─────────────────── ────────────── ──────────────
|
||||
Work independently ←→ Shared knowledge ←─ Monitor passively
|
||||
Update when complete ─→ Worker discoveries ─→ Synthesize findings
|
||||
Self-organize via MCP ←─ Cross-worker data ─→ Document learnings
|
||||
No coordination needed Persistent state Intervene if blocking
|
||||
```
|
||||
|
||||
**Result:** Parallel work + Emergent insights + No bottlenecks
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Worker Autonomy
|
||||
|
||||
**Workers are domain experts who self-organize.**
|
||||
|
||||
- Make independent decisions
|
||||
- No permission needed
|
||||
- Trust domain expertise
|
||||
- Work at own pace
|
||||
- Update Memory MCP when complete
|
||||
|
||||
### 2. Stigmergy Coordination
|
||||
|
||||
**Coordination through shared environment (Memory MCP), not commands.**
|
||||
|
||||
- Workers leave "pheromone trails" (observations in Memory MCP)
|
||||
- Other workers detect trails and adapt
|
||||
- Emergent patterns arise naturally
|
||||
- No central coordinator needed
|
||||
|
||||
### 3. Minimal Intervention
|
||||
|
||||
**Observer watches, synthesizes, documents - intervenes rarely.**
|
||||
|
||||
- Monitor worker activity passively (every 2-4h)
|
||||
- Synthesize N worker streams into coherent narrative
|
||||
- Intervene ONLY if blocking conflicts
|
||||
- Trust worker autonomy 99% of time
|
||||
|
||||
### 4. Emergent Intelligence
|
||||
|
||||
**Valuable insights emerge from worker combinations.**
|
||||
|
||||
- Cross-domain patterns
|
||||
- Unexpected synergies
|
||||
- Novel solutions
|
||||
- Distributed problem-solving
|
||||
|
||||
### 5. Natural Scaling
|
||||
|
||||
**Pattern scales to N workers without overhead.**
|
||||
|
||||
- Add workers: Just create new entity, no coordination changes
|
||||
- Remove workers: No impact on others
|
||||
- 10 workers = same overhead as 2 workers
|
||||
- Coordination cost: O(1), not O(N²)
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
**1. Autonomous Workers (N sessions)**
|
||||
- Domain: Specific repo, codebase, or task area
|
||||
- Goal: Domain-specific objectives
|
||||
- Entity: Unique Memory MCP entity (`Worker Session: {domain}`)
|
||||
- Behavior: Work independently, update Memory MCP when complete
|
||||
- Coordination: Minimal (only if blocking another worker)
|
||||
|
||||
**2. Memory MCP (Shared Knowledge Base)**
|
||||
- Function: Stigmergy (coordination through environment)
|
||||
- Data: Worker observations, discoveries, blockers, status
|
||||
- Persistence: Survives /clear, session restarts, IDE restarts
|
||||
- Access: All sessions read/write
|
||||
- Structure: Entities + Relations + Observations
|
||||
|
||||
**3. Meta-Observer (1 session)**
|
||||
- Role: Monitor, synthesize, document
|
||||
- Location: Workspace root (neutral territory)
|
||||
- Behavior: Passive observation, active synthesis
|
||||
- Intervention: Minimal (only blocking conflicts)
|
||||
- Output: Synthesis documents, pattern learnings
|
||||
|
||||
---
|
||||
|
||||
## Implementation
|
||||
|
||||
### Step 1: Launch Meta-Observer Pattern
|
||||
|
||||
```bash
|
||||
/launch-meta-observer
|
||||
```
|
||||
|
||||
**Agent prompts for:**
|
||||
- Number of workers
|
||||
- Domain for each worker
|
||||
- Overall goal
|
||||
- Observer location (default: workspace root)
|
||||
|
||||
**Creates:**
|
||||
- N worker entities in Memory MCP
|
||||
- N worker briefs (`.agents/briefs/worker-N-{domain}.md`)
|
||||
- 1 observer brief (`.agents/briefs/meta-observer-{timestamp}.md`)
|
||||
- Meta-Observer session initialized
|
||||
|
||||
### Step 2: Brief Workers
|
||||
|
||||
**Each worker receives custom brief with:**
|
||||
- Domain assignment
|
||||
- Autonomous work protocol
|
||||
- Memory MCP update instructions
|
||||
- Unique entity name
|
||||
- Context management guidelines
|
||||
|
||||
**Workers understand:**
|
||||
- ✅ Work autonomously (you're the expert)
|
||||
- ✅ Update Memory MCP after major progress
|
||||
- ✅ Check Memory MCP for other worker discoveries (optional)
|
||||
- ✅ Coordinate only if blocking
|
||||
- ✅ Manage context (sub-agents, bundling at 40%)
|
||||
|
||||
### Step 3: Observer Monitors
|
||||
|
||||
**Every 2-4 hours, observer:**
|
||||
1. Queries Memory MCP for worker updates
|
||||
2. Reads new discoveries
|
||||
3. Identifies cross-worker patterns
|
||||
4. Checks for blockers/conflicts
|
||||
5. Updates synthesis
|
||||
6. Intervenes if necessary (rare)
|
||||
7. Documents learnings
|
||||
|
||||
### Step 4: Workers Execute
|
||||
|
||||
**Workers autonomously:**
|
||||
1. Do domain work
|
||||
2. Use sub-agents for complex tasks
|
||||
3. Monitor context (stay <40%)
|
||||
4. Update Memory MCP after phases
|
||||
5. Check for blockers from others (optional)
|
||||
6. Continue until goal complete
|
||||
|
||||
### Step 5: End-of-Day Synthesis
|
||||
|
||||
**Observer creates comprehensive synthesis:**
|
||||
- What each worker completed
|
||||
- Emergent insights across workers
|
||||
- Patterns validated
|
||||
- Learnings captured
|
||||
- Overall progress toward goal
|
||||
|
||||
---
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Pattern 1: Repository Parallelization
|
||||
|
||||
**Use case:** Work spans multiple repos
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/launch-meta-observer --workers 3 \
|
||||
--domains "backend-api,frontend-ui,infrastructure" \
|
||||
--goal "Implement authentication feature"
|
||||
```
|
||||
|
||||
**Workers:**
|
||||
- Worker 1 (backend-api): Auth endpoints, JWT logic
|
||||
- Worker 2 (frontend-ui): Login UI, protected routes
|
||||
- Worker 3 (infrastructure): Database schema, secrets management
|
||||
|
||||
**Observer:** Synthesizes complete feature, ensures consistency
|
||||
|
||||
**Coordination:** Workers update Memory MCP when APIs ready, schemas deployed, etc.
|
||||
|
||||
### Pattern 2: Domain Specialization
|
||||
|
||||
**Use case:** Different expertise areas
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/launch-meta-observer --workers 4 \
|
||||
--domains "documentation,testing,deployment,monitoring" \
|
||||
--goal "Production-ready release"
|
||||
```
|
||||
|
||||
**Workers:**
|
||||
- Worker 1: API docs, user guides, tutorials
|
||||
- Worker 2: Unit tests, integration tests, E2E tests
|
||||
- Worker 3: CI/CD pipelines, deployment automation
|
||||
- Worker 4: Metrics, logging, alerting, dashboards
|
||||
|
||||
**Observer:** Synthesizes release readiness across all domains
|
||||
|
||||
### Pattern 3: Phase Parallelization
|
||||
|
||||
**Use case:** Independent phases of same project
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/launch-meta-observer --workers 3 \
|
||||
--domains "research,implementation,validation" \
|
||||
--goal "New feature development"
|
||||
```
|
||||
|
||||
**Workers:**
|
||||
- Worker 1: Research approaches, evaluate options, document findings
|
||||
- Worker 2: Implement solution based on research
|
||||
- Worker 3: Create validation suite, test implementation
|
||||
|
||||
**Coordination:** Worker 1 hands off to Worker 2 via Memory MCP
|
||||
|
||||
### Pattern 4: Launch Preparation (Today's Experiment)
|
||||
|
||||
**Use case:** Multi-domain launch readiness
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/launch-meta-observer --workers 3 \
|
||||
--domains "12-factor-agentops,agentops-showcase,launch-content" \
|
||||
--goal "Q1 2025 public launch"
|
||||
```
|
||||
|
||||
**Workers:**
|
||||
- Worker 1: Framework documentation, factor-mapping, compliance
|
||||
- Worker 2: VitePress website build, deployment, validation
|
||||
- Worker 3: SEO blog posts, launch strategy, social content
|
||||
|
||||
**Result:** All completed autonomously, emergent insights discovered
|
||||
|
||||
---
|
||||
|
||||
## Memory MCP Patterns
|
||||
|
||||
### Worker Update Pattern
|
||||
|
||||
```typescript
|
||||
// After completing major work
|
||||
mcp__memory__add_observations({
|
||||
observations: [{
|
||||
entityName: "Worker Session: {domain}",
|
||||
contents: [
|
||||
"Completed: {what}",
|
||||
"Discoveries: {insights}",
|
||||
"Impact: {contribution to goal}",
|
||||
"Blockers: {none or description}",
|
||||
"Context: {%}",
|
||||
"Next: {steps}",
|
||||
"Files: {modified}",
|
||||
"Commits: {if applicable}"
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
### Observer Query Pattern
|
||||
|
||||
```typescript
|
||||
// Check all worker updates
|
||||
mcp__memory__search_nodes({
|
||||
query: "Worker Session completed discoveries"
|
||||
})
|
||||
|
||||
// Get specific workers
|
||||
mcp__memory__open_nodes({
|
||||
names: [
|
||||
"Worker Session: domain-1",
|
||||
"Worker Session: domain-2"
|
||||
]
|
||||
})
|
||||
|
||||
// Check for blockers
|
||||
mcp__memory__search_nodes({
|
||||
query: "BLOCKER Worker Session"
|
||||
})
|
||||
```
|
||||
|
||||
### Handoff Pattern
|
||||
|
||||
```typescript
|
||||
// Worker 1 completes, hands off to Worker 2
|
||||
mcp__memory__add_observations({
|
||||
observations: [{
|
||||
entityName: "Worker Session: domain-1",
|
||||
contents: [
|
||||
"Work complete",
|
||||
"Handoff to Worker 2:",
|
||||
"- Artifacts: {files}",
|
||||
"- Context: {what they need to know}",
|
||||
"- Ready for: {next phase}",
|
||||
"Status: COMPLETE, HANDED OFF"
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
// Worker 2 picks up
|
||||
mcp__memory__search_nodes({ query: "Handoff to Worker 2" })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Pattern succeeds when:**
|
||||
- ✅ Workers complete work autonomously (no constant guidance)
|
||||
- ✅ Emergent insights arise (worker combinations create value)
|
||||
- ✅ Observer synthesis valuable (creates coherent narrative)
|
||||
- ✅ Intervention minimal (only blocking conflicts)
|
||||
- ✅ Faster than serial (parallelization actually helps)
|
||||
- ✅ No context collapse (all sessions <40%)
|
||||
- ✅ Scales naturally (adding workers doesn't slow down)
|
||||
|
||||
**Pattern needs adjustment when:**
|
||||
- ⚠️ Workers asking for constant guidance (be more autonomous)
|
||||
- ⚠️ No emergent insights (workers in silos, not sharing via MCP)
|
||||
- ⚠️ Observer intervening frequently (micromanaging)
|
||||
- ⚠️ Slower than serial (parallelization overhead too high)
|
||||
- ⚠️ Blocking conflicts undetected (observer not monitoring)
|
||||
- ⚠️ Context collapse (workers not using sub-agents/bundling)
|
||||
|
||||
---
|
||||
|
||||
## Advantages
|
||||
|
||||
**vs Central Orchestration:**
|
||||
- ✅ No bottleneck (workers don't wait for orchestrator)
|
||||
- ✅ Domain expertise (workers know their domain best)
|
||||
- ✅ Scales naturally (O(1) coordination, not O(N²))
|
||||
- ✅ Resilient (no single point of failure)
|
||||
- ✅ Emergent insights (patterns arise from combinations)
|
||||
|
||||
**vs No Coordination:**
|
||||
- ✅ Shared knowledge (Memory MCP provides context)
|
||||
- ✅ Conflict detection (observer watches for blockers)
|
||||
- ✅ Synthesis (coherent narrative from distributed work)
|
||||
- ✅ Learning capture (patterns documented)
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
**Not suitable for:**
|
||||
- ❌ Single-session work (overhead not worth it)
|
||||
- ❌ Tightly coupled tasks (constant sync needed)
|
||||
- ❌ Simple linear workflow (serial is simpler)
|
||||
- ❌ Real-time coordination required (async by design)
|
||||
|
||||
**Challenges:**
|
||||
- Workers must be disciplined about Memory MCP updates
|
||||
- Observer must resist urge to micromanage
|
||||
- Requires trust in worker autonomy
|
||||
- Emergent patterns may be unexpected (feature or bug?)
|
||||
|
||||
---
|
||||
|
||||
## Integration with 12-Factor AgentOps
|
||||
|
||||
**This pattern validates:**
|
||||
|
||||
**Factor II (JIT Context Loading):**
|
||||
- Workers bundle at 40%, stay lean
|
||||
- Observer stays <30% (just reading/synthesizing)
|
||||
- Sub-agents keep worker context low
|
||||
- Memory MCP eliminates need to load full context
|
||||
|
||||
**Factor VI (Session Continuity):**
|
||||
- Memory MCP persists across /clear
|
||||
- Workers can bundle and resume seamlessly
|
||||
- Observer synthesizes even after session restarts
|
||||
- Work continues despite interruptions
|
||||
|
||||
**Factor VII (Intelligent Routing):**
|
||||
- Observer synthesizes, doesn't command
|
||||
- Workers self-route based on domain expertise
|
||||
- Memory MCP routes information between workers
|
||||
- Emergent routing (not planned routing)
|
||||
|
||||
**Factor IX (Pattern Extraction):**
|
||||
- Observer captures emergent patterns
|
||||
- Workers document discoveries in Memory MCP
|
||||
- Learnings extracted automatically
|
||||
- Pattern library grows organically
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Nested Observers
|
||||
|
||||
**For very large N (10+ workers):**
|
||||
|
||||
```
|
||||
Meta-Meta-Observer
|
||||
├── Domain Observer 1 (watches 5 workers)
|
||||
├── Domain Observer 2 (watches 5 workers)
|
||||
└── Domain Observer 3 (watches 5 workers)
|
||||
```
|
||||
|
||||
**Use when:** 10+ workers, group into domains
|
||||
|
||||
### Dynamic Worker Addition
|
||||
|
||||
**Add worker mid-stream:**
|
||||
|
||||
```bash
|
||||
/worker-brief --domain "new-domain" --goal "additional work" --number 4
|
||||
```
|
||||
|
||||
**Observer automatically incorporates** new worker into monitoring.
|
||||
|
||||
### Worker Subtraction
|
||||
|
||||
**Worker completes and exits:**
|
||||
|
||||
```typescript
|
||||
mcp__memory__add_observations({
|
||||
observations: [{
|
||||
entityName: "Worker Session: domain-1",
|
||||
contents: [
|
||||
"Status: COMPLETE",
|
||||
"Exiting: Work done",
|
||||
"Handoff: None needed",
|
||||
"Final report: {summary}"
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Other workers and observer continue** unaffected.
|
||||
|
||||
---
|
||||
|
||||
## Experiment Results (2025-11-09)
|
||||
|
||||
**Hypothesis:** Central orchestration best for multi-session work
|
||||
|
||||
**Actual Discovery:** Autonomous coordination superior
|
||||
|
||||
**Evidence:**
|
||||
- 3 workers completed complex work independently
|
||||
- Zero active coordination needed
|
||||
- Emergent insights discovered (recursive validation)
|
||||
- Observer synthesis highly valuable
|
||||
- Pattern scales to N workers naturally
|
||||
- Faster than would have been with central control
|
||||
|
||||
**Conclusion:** Pattern validated ✅
|
||||
|
||||
**Status:** Production-ready for general use
|
||||
|
||||
---
|
||||
|
||||
## Files
|
||||
|
||||
**.claude/commands/**
|
||||
- `launch-meta-observer.md` - Initialize pattern
|
||||
- `worker-brief.md` - Generate worker instructions
|
||||
|
||||
**.claude/agents/**
|
||||
- `meta-observer.md` - Observer agent
|
||||
- `autonomous-worker.md` - Worker template
|
||||
|
||||
**.claude/workflows/**
|
||||
- `meta-observer-pattern.md` - This file (full pattern docs)
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
**Related Patterns:**
|
||||
- Context Bundling Protocol
|
||||
- Sub-Agent Delegation Pattern
|
||||
- Stigmergy Coordination (ant colonies)
|
||||
|
||||
**Related Factors:**
|
||||
- Factor II: Context Loading → The 40% Rule as Overload Prevention
|
||||
- Factor VI: Resume Work → Validation Continuity Across Sessions
|
||||
- Factor VII: Smart Routing → Directing Work to Appropriate Validation Paths
|
||||
- Factor IX: Mine Patterns → Learning What Passes Validation
|
||||
|
||||
**Inspiration:**
|
||||
- Ant colony optimization
|
||||
- Swarm intelligence
|
||||
- Distributed systems (eventual consistency)
|
||||
- Self-organizing systems
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize pattern
|
||||
/launch-meta-observer
|
||||
|
||||
# Follow prompts for:
|
||||
# - Number of workers
|
||||
# - Domain per worker
|
||||
# - Overall goal
|
||||
|
||||
# Workers work autonomously
|
||||
# Observer monitors and synthesizes
|
||||
# You get comprehensive synthesis at end
|
||||
|
||||
# That's it!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Pattern:** Meta-Observer
|
||||
**Principle:** Emergent coordination > Central control
|
||||
**Scales to:** N autonomous workers
|
||||
**Status:** Production-ready ✅
|
||||
**Discovered:** 2025-11-09 through experiment
|
||||
**Maintained by:** AgentOps Community
|
||||
Reference in New Issue
Block a user