@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/digital-brain-skill/agents/AGENTS.md

@@ -0,0 +1,82 @@
+---
+name: agents-module
+description: Automation scripts and agent helpers for the Digital Brain. Use these scripts for recurring tasks, summaries, and maintenance.
+---
+
+# Agent Automation
+
+Scripts and workflows that help maintain and leverage your Digital Brain.
+
+## Available Scripts
+
+| Script | Purpose | Frequency |
+|--------|---------|-----------|
+| `weekly_review.py` | Generate weekly review from data | Weekly |
+| `content_ideas.py` | Generate content ideas from knowledge | On-demand |
+| `stale_contacts.py` | Find contacts needing outreach | Weekly |
+| `metrics_snapshot.py` | Compile metrics for tracking | Weekly |
+| `idea_to_draft.py` | Expand an idea into a draft | On-demand |
+
+## How to Use
+
+Scripts are in `agents/scripts/`. They work with your Digital Brain data and can be run by the agent when needed.
+
+### Running Scripts
+```bash
+# Agent can execute scripts directly
+python agents/scripts/weekly_review.py
+
+# Or with arguments
+python agents/scripts/content_ideas.py --pillar "ai_agents" --count 5
+```
+
+### Script Outputs
+Scripts output to stdout in a format the agent can process. They may also write to files when appropriate (e.g., generating a review document).
+
+## Agent Instructions
+
+<instructions>
+When using automation scripts:
+
+1. **Weekly review**: Run every Sunday, outputs review template with data filled in
+2. **Content ideas**: Use when user asks for ideas, leverages knowledge base
+3. **Stale contacts**: Run weekly, surfaces relationships needing attention
+4. **Metrics snapshot**: Run weekly to append to metrics.jsonl
+5. **Idea to draft**: Use when user wants to develop a specific idea
+
+Scripts read from Digital Brain files and output actionable results.
+</instructions>
+
+## Workflow Automations
+
+### Sunday Weekly Review
+```
+1. Run metrics_snapshot.py to update metrics.jsonl
+2. Run stale_contacts.py to identify outreach needs
+3. Run weekly_review.py to generate review document
+4. Present summary to user
+```
+
+### Content Ideation Session
+```
+1. Read recent entries from knowledge/bookmarks.jsonl
+2. Check content/ideas.jsonl for undeveloped ideas
+3. Run content_ideas.py for fresh suggestions
+4. Cross-reference with content calendar
+```
+
+### Pre-Meeting Prep
+```
+1. Look up contact in network/contacts.jsonl
+2. Pull recent interactions from network/interactions.jsonl
+3. Check any pending todos involving them
+4. Generate brief with context
+```
+
+## Custom Script Development
+
+To add new scripts:
+1. Create Python file in `agents/scripts/`
+2. Follow existing patterns (read JSONL, output structured data)
+3. Document in this file
+4. Test with sample data

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/digital-brain-skill/agents/scripts/content_ideas.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Content Ideas Generator
+Generates content ideas based on knowledge base and past successful content.
+"""
+
+import json
+import argparse
+from datetime import datetime
+from pathlib import Path
+
+BRAIN_ROOT = Path(__file__).parent.parent.parent
+
+def load_jsonl(filepath):
+    """Load JSONL file, skipping schema lines."""
+    items = []
+    if not filepath.exists():
+        return items
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                if '_schema' not in data:
+                    items.append(data)
+            except json.JSONDecodeError:
+                continue
+    return items
+
+def get_top_performing_content():
+    """Get posts with highest engagement."""
+    posts = load_jsonl(BRAIN_ROOT / 'content' / 'posts.jsonl')
+
+    # Sort by engagement metrics if available
+    def engagement_score(post):
+        metrics = post.get('metrics', {})
+        return (
+            metrics.get('likes', 0) +
+            metrics.get('comments', 0) * 2 +
+            metrics.get('reposts', 0) * 3
+        )
+
+    sorted_posts = sorted(posts, key=engagement_score, reverse=True)
+    return sorted_posts[:5]
+
+def get_recent_bookmarks(category=None):
+    """Get recent bookmarks, optionally filtered by category."""
+    bookmarks = load_jsonl(BRAIN_ROOT / 'knowledge' / 'bookmarks.jsonl')
+
+    if category:
+        bookmarks = [b for b in bookmarks if b.get('category') == category]
+
+    # Sort by date, most recent first
+    bookmarks.sort(key=lambda x: x.get('saved_at', ''), reverse=True)
+    return bookmarks[:10]
+
+def get_undeveloped_ideas():
+    """Get ideas that haven't been developed yet."""
+    ideas = load_jsonl(BRAIN_ROOT / 'content' / 'ideas.jsonl')
+
+    raw_ideas = [i for i in ideas if i.get('status') == 'raw']
+    return raw_ideas
+
+def generate_suggestions(pillar=None, count=5):
+    """Generate content suggestions."""
+
+    output = f"""
+# Content Ideas Generator
+Generated: {datetime.now().isoformat()}
+Filter: {pillar or 'All pillars'}
+
+## Based on Top Performing Content
+"""
+
+    top_posts = get_top_performing_content()
+    if top_posts:
+        output += "\nYour best performing content themes:\n"
+        for post in top_posts[:3]:
+            output += f"- {post.get('pillar', 'Unknown')}: {post.get('type', 'post')}\n"
+        output += "\n**Suggestion**: Create more content in these high-performing areas.\n"
+    else:
+        output += "\nNo post history yet. Start creating!\n"
+
+    output += """
+## From Your Knowledge Base
+"""
+
+    bookmarks = get_recent_bookmarks(pillar)
+    if bookmarks:
+        output += "\nRecent topics you've been researching:\n"
+        for bm in bookmarks[:5]:
+            output += f"- {bm.get('title', 'Untitled')} ({bm.get('category', 'uncategorized')})\n"
+            if bm.get('key_insights'):
+                output += f"  Key insight: {bm['key_insights'][0]}\n"
+        output += "\n**Suggestion**: Turn these research topics into educational content.\n"
+    else:
+        output += "\nNo bookmarks yet. Save interesting content to fuel ideas.\n"
+
+    output += """
+## Undeveloped Ideas
+"""
+
+    ideas = get_undeveloped_ideas()
+    if ideas:
+        output += f"\nYou have {len(ideas)} undeveloped ideas:\n"
+        for idea in ideas[:count]:
+            output += f"- [{idea.get('priority', 'medium')}] {idea.get('idea', 'No content')}\n"
+        output += "\n**Suggestion**: Pick one high-priority idea and develop it today.\n"
+    else:
+        output += "\nNo undeveloped ideas in the queue.\n"
+
+    output += """
+## Quick Prompts
+
+1. "What's one thing I learned this week that others would find valuable?"
+2. "What's a common mistake I see in my industry?"
+3. "What question do I get asked most often?"
+4. "What worked for me that's counterintuitive?"
+5. "What do I wish I knew when I started?"
+"""
+
+    return output
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='Generate content ideas')
+    parser.add_argument('--pillar', '-p', help='Filter by content pillar')
+    parser.add_argument('--count', '-c', type=int, default=5, help='Number of ideas to show')
+
+    args = parser.parse_args()
+    print(generate_suggestions(args.pillar, args.count))

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/digital-brain-skill/agents/scripts/idea_to_draft.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""
+Idea to Draft Expander
+Takes an idea ID and creates a draft scaffold with relevant context.
+"""
+
+import json
+import argparse
+from datetime import datetime
+from pathlib import Path
+
+BRAIN_ROOT = Path(__file__).parent.parent.parent
+
+def load_jsonl(filepath):
+    """Load JSONL file, skipping schema lines."""
+    items = []
+    if not filepath.exists():
+        return items
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                if '_schema' not in data:
+                    items.append(data)
+            except json.JSONDecodeError:
+                continue
+    return items
+
+def find_idea(idea_id):
+    """Find an idea by ID or partial match."""
+    ideas = load_jsonl(BRAIN_ROOT / 'content' / 'ideas.jsonl')
+
+    for idea in ideas:
+        if idea.get('id') == idea_id:
+            return idea
+        # Partial match
+        if idea_id.lower() in idea.get('id', '').lower():
+            return idea
+        if idea_id.lower() in idea.get('idea', '').lower():
+            return idea
+
+    return None
+
+def find_related_bookmarks(tags, pillar):
+    """Find bookmarks related to the idea."""
+    bookmarks = load_jsonl(BRAIN_ROOT / 'knowledge' / 'bookmarks.jsonl')
+
+    related = []
+    for bm in bookmarks:
+        bm_tags = set(bm.get('tags', []))
+        bm_category = bm.get('category', '')
+
+        if tags and bm_tags.intersection(set(tags)):
+            related.append(bm)
+        elif pillar and bm_category == pillar:
+            related.append(bm)
+
+    return related[:5]
+
+def find_similar_posts(pillar):
+    """Find past posts in same pillar for reference."""
+    posts = load_jsonl(BRAIN_ROOT / 'content' / 'posts.jsonl')
+
+    similar = [p for p in posts if p.get('pillar') == pillar]
+    return similar[:3]
+
+def generate_draft_scaffold(idea_id):
+    """Generate a draft scaffold from an idea."""
+
+    idea = find_idea(idea_id)
+
+    if not idea:
+        return f"Error: Could not find idea matching '{idea_id}'"
+
+    pillar = idea.get('pillar', 'general')
+    tags = idea.get('tags', [])
+
+    related_bookmarks = find_related_bookmarks(tags, pillar)
+    similar_posts = find_similar_posts(pillar)
+
+    output = f"""
+# Draft: {idea.get('idea', 'Untitled')}
+
+## Metadata
+```yaml
+source_idea: {idea.get('id', 'unknown')}
+pillar: {pillar}
+created: {datetime.now().isoformat()}
+status: draft
+tags: {tags}
+```
+
+## Original Idea
+```
+{idea.get('idea', 'No content')}
+```
+
+Source: {idea.get('source', 'Unknown')}
+Notes: {idea.get('notes', 'None')}
+
+---
+
+## Hook Options
+<!-- Write 2-3 hook options -->
+
+1. [Hook option 1]
+2. [Hook option 2]
+3. [Hook option 3]
+
+---
+
+## Main Points
+
+### Point 1
+[Expand here]
+
+### Point 2
+[Expand here]
+
+### Point 3
+[Expand here]
+
+---
+
+## Supporting Evidence
+"""
+
+    if related_bookmarks:
+        output += "\n### From Your Research\n"
+        for bm in related_bookmarks:
+            output += f"- [{bm.get('title', 'Untitled')}]({bm.get('url', '#')})\n"
+            if bm.get('key_insights'):
+                output += f"  Insight: {bm['key_insights'][0]}\n"
+    else:
+        output += "\nNo related bookmarks found. Consider researching this topic.\n"
+
+    output += """
+---
+
+## Reference: Similar Past Content
+"""
+
+    if similar_posts:
+        for post in similar_posts:
+            output += f"- {post.get('type', 'post')}: {post.get('url', 'No URL')}\n"
+    else:
+        output += "\nNo similar past content found.\n"
+
+    output += """
+---
+
+## Call to Action
+
+[What should the reader do?]
+
+---
+
+## Pre-publish Checklist
+
+- [ ] Hook is compelling
+- [ ] Main points are clear and valuable
+- [ ] Voice matches brand (check identity/voice.md)
+- [ ] CTA is clear
+- [ ] Proofread
+
+---
+
+*Remember: Check identity/voice.md before finalizing!*
+"""
+
+    return output
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='Expand an idea into a draft')
+    parser.add_argument('idea_id', help='ID or partial match of the idea to expand')
+
+    args = parser.parse_args()
+    print(generate_draft_scaffold(args.idea_id))

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/digital-brain-skill/agents/scripts/stale_contacts.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Stale Contacts Finder
+Identifies contacts that haven't been reached out to recently.
+"""
+
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+
+BRAIN_ROOT = Path(__file__).parent.parent.parent
+
+# Thresholds by circle (in days)
+THRESHOLDS = {
+    'inner': 14,      # 2 weeks
+    'active': 30,     # 1 month
+    'network': 60,    # 2 months
+    'dormant': 180    # 6 months (for potential reactivation)
+}
+
+def load_jsonl(filepath):
+    """Load JSONL file, skipping schema lines."""
+    items = []
+    if not filepath.exists():
+        return items
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                if '_schema' not in data:
+                    items.append(data)
+            except json.JSONDecodeError:
+                continue
+    return items
+
+def days_since(date_str):
+    """Calculate days since a date string."""
+    if not date_str:
+        return 999  # Very stale if no date
+    try:
+        date = datetime.fromisoformat(date_str.replace('Z', '+00:00'))
+        return (datetime.now(date.tzinfo) - date).days
+    except (ValueError, TypeError):
+        return 999
+
+def find_stale_contacts():
+    """Find contacts needing outreach."""
+    contacts = load_jsonl(BRAIN_ROOT / 'network' / 'contacts.jsonl')
+
+    stale = {
+        'urgent': [],      # Way overdue
+        'due': [],         # Due for contact
+        'coming_up': []    # Getting close
+    }
+
+    for contact in contacts:
+        circle = contact.get('circle', 'network')
+        threshold = THRESHOLDS.get(circle, 60)
+        days = days_since(contact.get('last_contact'))
+
+        contact_info = {
+            'name': contact.get('name', 'Unknown'),
+            'circle': circle,
+            'days_since': days,
+            'threshold': threshold,
+            'handle': contact.get('handle', ''),
+            'notes': contact.get('notes', '')[:100]
+        }
+
+        if days > threshold * 1.5:
+            stale['urgent'].append(contact_info)
+        elif days > threshold:
+            stale['due'].append(contact_info)
+        elif days > threshold * 0.75:
+            stale['coming_up'].append(contact_info)
+
+    return stale
+
+def generate_report():
+    """Generate stale contacts report."""
+    stale = find_stale_contacts()
+
+    output = f"""
+# Stale Contacts Report
+Generated: {datetime.now().isoformat()}
+
+## Urgently Overdue ({len(stale['urgent'])})
+"""
+
+    if stale['urgent']:
+        for c in sorted(stale['urgent'], key=lambda x: -x['days_since']):
+            output += f"- **{c['name']}** ({c['circle']}) - {c['days_since']} days since contact\n"
+            if c['handle']:
+                output += f"  {c['handle']}\n"
+    else:
+        output += "None! You're on top of things.\n"
+
+    output += f"""
+## Due for Contact ({len(stale['due'])})
+"""
+
+    if stale['due']:
+        for c in sorted(stale['due'], key=lambda x: -x['days_since']):
+            output += f"- {c['name']} ({c['circle']}) - {c['days_since']} days\n"
+    else:
+        output += "None due right now.\n"
+
+    output += f"""
+## Coming Up ({len(stale['coming_up'])})
+"""
+
+    if stale['coming_up']:
+        for c in sorted(stale['coming_up'], key=lambda x: -x['days_since']):
+            output += f"- {c['name']} ({c['circle']}) - {c['days_since']} days (threshold: {c['threshold']})\n"
+    else:
+        output += "No contacts approaching threshold.\n"
+
+    output += """
+## Suggested Actions
+
+1. Send a quick "thinking of you" message to urgent contacts
+2. Schedule calls with due inner-circle contacts
+3. Engage with content from coming-up contacts
+
+## Thresholds
+
+- Inner circle: Every 2 weeks
+- Active: Every month
+- Network: Every 2 months
+- Dormant: Quarterly check for reactivation
+"""
+
+    return output
+
+if __name__ == '__main__':
+    print(generate_report())

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/digital-brain-skill/agents/scripts/weekly_review.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Weekly Review Generator
+Compiles data from Digital Brain into a weekly review document.
+"""
+
+import json
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# Get the digital brain root (parent of agents/)
+BRAIN_ROOT = Path(__file__).parent.parent.parent
+
+def load_jsonl(filepath):
+    """Load JSONL file, skipping schema lines."""
+    items = []
+    if not filepath.exists():
+        return items
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                # Skip schema definition lines
+                if '_schema' not in data:
+                    items.append(data)
+            except json.JSONDecodeError:
+                continue
+    return items
+
+def get_week_range():
+    """Get the start and end of the current week."""
+    today = datetime.now()
+    start = today - timedelta(days=today.weekday())
+    end = start + timedelta(days=6)
+    return start.strftime('%Y-%m-%d'), end.strftime('%Y-%m-%d')
+
+def analyze_content(week_start):
+    """Analyze content published this week."""
+    posts = load_jsonl(BRAIN_ROOT / 'content' / 'posts.jsonl')
+    ideas = load_jsonl(BRAIN_ROOT / 'content' / 'ideas.jsonl')
+
+    week_posts = [p for p in posts if p.get('published', '') >= week_start]
+    new_ideas = [i for i in ideas if i.get('created', '') >= week_start]
+
+    return {
+        'posts_published': len(week_posts),
+        'new_ideas': len(new_ideas),
+        'posts': week_posts
+    }
+
+def analyze_network(week_start):
+    """Analyze network activity this week."""
+    interactions = load_jsonl(BRAIN_ROOT / 'network' / 'interactions.jsonl')
+
+    week_interactions = [i for i in interactions if i.get('date', '') >= week_start]
+
+    return {
+        'interactions': len(week_interactions),
+        'details': week_interactions
+    }
+
+def analyze_metrics():
+    """Get latest metrics if available."""
+    metrics = load_jsonl(BRAIN_ROOT / 'operations' / 'metrics.jsonl')
+    if metrics:
+        return metrics[-1]  # Most recent
+    return {}
+
+def generate_review():
+    """Generate the weekly review output."""
+    week_start, week_end = get_week_range()
+
+    content = analyze_content(week_start)
+    network = analyze_network(week_start)
+    metrics = analyze_metrics()
+
+    review = f"""
+# Weekly Review: {week_start} to {week_end}
+Generated: {datetime.now().isoformat()}
+
+## Summary
+
+### Content
+- Posts published: {content['posts_published']}
+- New ideas captured: {content['new_ideas']}
+
+### Network
+- Interactions logged: {network['interactions']}
+
+### Latest Metrics
+"""
+
+    if metrics:
+        audience = metrics.get('audience', {})
+        for key, value in audience.items():
+            review += f"- {key}: {value}\n"
+    else:
+        review += "- No metrics recorded yet\n"
+
+    review += """
+## Action Items
+
+1. [ ] Review content performance
+2. [ ] Plan next week's content
+3. [ ] Follow up on pending introductions
+4. [ ] Update goals progress
+5. [ ] Schedule key meetings
+
+## Notes
+
+[Add your reflections here]
+"""
+
+    return review
+
+if __name__ == '__main__':
+    print(generate_review())