@stephen-lord/docs 1.0.0 → 1.0.1

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

@@ -0,0 +1,209 @@
+# Digital Brain
+
+> A personal operating system for founders, creators, and builders. Part of the [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) collection.
+
+## Overview
+
+Digital Brain is a structured knowledge management system designed for AI-assisted personal productivity. It provides a complete folder-based architecture for managing:
+
+- **Personal Brand** - Voice, positioning, values
+- **Content Creation** - Ideas, drafts, publishing pipeline
+- **Knowledge Base** - Bookmarks, research, learning
+- **Network** - Contacts, relationships, introductions
+- **Operations** - Goals, tasks, meetings, metrics
+
+The system follows context engineering principles: progressive disclosure, append-only data, and module separation to optimize for AI agent interactions.
+
+## Architecture
+
+```
+digital-brain/
+├── SKILL.md                 # Main skill definition (Claude Code compatible)
+├── SKILLS-MAPPING.md        # How context engineering skills apply
+│
+├── identity/                # Personal brand & voice
+│   ├── IDENTITY.md          # Module instructions
+│   ├── voice.md             # Tone, style, patterns
+│   ├── brand.md             # Positioning, audience
+│   ├── values.yaml          # Core principles
+│   ├── bio-variants.md      # Platform bios
+│   └── prompts/             # Generation templates
+│
+├── content/                 # Content creation hub
+│   ├── CONTENT.md           # Module instructions
+│   ├── ideas.jsonl          # Content ideas (append-only)
+│   ├── posts.jsonl          # Published content log
+│   ├── calendar.md          # Content schedule
+│   ├── engagement.jsonl     # Saved inspiration
+│   ├── drafts/              # Work in progress
+│   └── templates/           # Thread, newsletter, post templates
+│
+├── knowledge/               # Personal knowledge base
+│   ├── KNOWLEDGE.md         # Module instructions
+│   ├── bookmarks.jsonl      # Saved resources
+│   ├── learning.yaml        # Skills & goals
+│   ├── competitors.md       # Market landscape
+│   ├── research/            # Deep-dive notes
+│   └── notes/               # Quick captures
+│
+├── network/                 # Relationship management
+│   ├── NETWORK.md           # Module instructions
+│   ├── contacts.jsonl       # People database
+│   ├── interactions.jsonl   # Meeting log
+│   ├── circles.yaml         # Relationship tiers
+│   └── intros.md            # Introduction tracker
+│
+├── operations/              # Productivity system
+│   ├── OPERATIONS.md        # Module instructions
+│   ├── todos.md             # Task list (P0-P3)
+│   ├── goals.yaml           # OKRs
+│   ├── meetings.jsonl       # Meeting notes
+│   ├── metrics.jsonl        # Key metrics
+│   └── reviews/             # Weekly reviews
+│
+├── agents/                  # Automation
+│   ├── AGENTS.md            # Script documentation
+│   └── scripts/
+│       ├── weekly_review.py
+│       ├── content_ideas.py
+│       ├── stale_contacts.py
+│       └── idea_to_draft.py
+│
+├── references/              # Detailed documentation
+│   └── file-formats.md
+│
+└── examples/                # Usage workflows
+    ├── content-workflow.md
+    └── meeting-prep.md
+```
+
+## Skills Integration
+
+This example demonstrates these context engineering skills:
+
+| Skill | Application |
+|-------|-------------|
+| `context-fundamentals` | Progressive disclosure, attention budget |
+| `memory-systems` | JSONL append-only logs, structured recall |
+| `tool-design` | Self-contained automation scripts |
+| `context-optimization` | Module separation, just-in-time loading |
+
+See [SKILLS-MAPPING.md](./SKILLS-MAPPING.md) for detailed mapping of how each skill informs the design.
+
+## Installation
+
+### As a Claude Code Skill
+
+```bash
+# User-wide installation
+git clone https://github.com/muratcankoylan/digital-brain-skill.git \
+  ~/.claude/skills/digital-brain
+
+# Or project-specific
+git clone https://github.com/muratcankoylan/digital-brain-skill.git \
+  .claude/skills/digital-brain
+```
+
+### As a Standalone Template
+
+```bash
+git clone https://github.com/muratcankoylan/digital-brain-skill.git ~/digital-brain
+cd ~/digital-brain
+```
+
+## Quick Start
+
+1. **Define your voice** - Fill out `identity/voice.md` with your tone and style
+2. **Set your positioning** - Complete `identity/brand.md` with audience and pillars
+3. **Add contacts** - Populate `network/contacts.jsonl` with key relationships
+4. **Set goals** - Define OKRs in `operations/goals.yaml`
+5. **Start creating** - Ask AI to "write a post" and watch it use your voice
+
+## File Format Conventions
+
+| Format | Use Case | Why |
+|--------|----------|-----|
+| `.jsonl` | Append-only logs | Agent-friendly, preserves history |
+| `.yaml` | Structured config | Human-readable hierarchies |
+| `.md` | Narrative content | Editable, rich formatting |
+| `.xml` | Complex prompts | Clear structure for agents |
+
+## Usage Examples
+
+### Content Creation
+```
+User: "Help me write a X thread about AI agents"
+
+Agent Process:
+1. Reads identity/voice.md for tone patterns
+2. Checks identity/brand.md - confirms "ai_agents" is a pillar
+3. References content/posts.jsonl for successful formats
+4. Drafts thread matching voice attributes
+```
+
+### Meeting Preparation
+```
+User: "Prepare me for my call with Sarah"
+
+Agent Process:
+1. Searches network/contacts.jsonl for Sarah
+2. Gets history from network/interactions.jsonl
+3. Checks operations/todos.md for pending items
+4. Generates pre-meeting brief
+```
+
+### Weekly Review
+```
+User: "Run my weekly review"
+
+Agent Process:
+1. Executes agents/scripts/weekly_review.py
+2. Compiles metrics from operations/metrics.jsonl
+3. Runs agents/scripts/stale_contacts.py
+4. Presents summary with action items
+```
+
+## Automation Scripts
+
+| Script | Purpose | Run Frequency |
+|--------|---------|---------------|
+| `weekly_review.py` | Generate review from data | Weekly |
+| `content_ideas.py` | Suggest content from knowledge | On-demand |
+| `stale_contacts.py` | Find neglected relationships | Weekly |
+| `idea_to_draft.py` | Expand idea to draft scaffold | On-demand |
+
+```bash
+# Run directly
+python agents/scripts/weekly_review.py
+
+# Or with arguments
+python agents/scripts/content_ideas.py --pillar ai_agents --count 5
+```
+
+## Design Principles
+
+1. **Progressive Disclosure** - Load only what's needed for the current task
+2. **Append-Only Data** - Never delete, preserve history for pattern analysis
+3. **Module Separation** - Each domain is independent, no cross-contamination
+4. **Voice First** - Always read voice.md before any content generation
+5. **Platform Agnostic** - Works with Claude Code, Cursor, any AI assistant
+
+## Contributing
+
+This is part of the [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) collection.
+
+Contributions welcome:
+- New content templates
+- Additional automation scripts
+- Module enhancements
+- Documentation improvements
+
+## License
+
+MIT - Use freely, attribution appreciated.
+
+---
+
+**Author**: Muratcan Koylan
+**Version**: 1.0.0
+**Last Updated**: 2025-12-29

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

@@ -0,0 +1,203 @@
+---
+name: digital-brain
+description: This skill should be used when the user asks to "write a post", "check my voice", "look up contact", "prepare for meeting", "weekly review", "track goals", or mentions personal brand, content creation, network management, or voice consistency.
+version: 1.0.0
+---
+
+# Digital Brain
+
+A structured personal operating system for managing digital presence, knowledge, relationships, and goals with AI assistance. Designed for founders building in public, content creators growing their audience, and tech-savvy professionals seeking AI-assisted personal management.
+
+**Important**: This skill uses progressive disclosure. Module-specific instructions are in each subdirectory's `.md` file. Only load what's needed for the current task.
+
+## When to Activate
+
+Activate this skill when the user:
+
+- Requests content creation (posts, threads, newsletters) - load identity/voice.md first
+- Asks for help with personal brand or positioning
+- Needs to look up or manage contacts/relationships
+- Wants to capture or develop content ideas
+- Requests meeting preparation or follow-up
+- Asks for weekly reviews or goal tracking
+- Needs to save or retrieve bookmarked resources
+- Wants to organize research or learning materials
+
+**Trigger phrases**: "write a post", "my voice", "content ideas", "who is [name]", "prepare for meeting", "weekly review", "save this", "my goals"
+
+## Core Concepts
+
+### Progressive Disclosure Architecture
+
+The Digital Brain follows a three-level loading pattern:
+
+| Level | When Loaded | Content |
+|-------|-------------|---------|
+| **L1: Metadata** | Always | This SKILL.md overview |
+| **L2: Module Instructions** | On-demand | `[module]/[MODULE].md` files |
+| **L3: Data Files** | As-needed | `.jsonl`, `.yaml`, `.md` data |
+
+### File Format Strategy
+
+Formats chosen for optimal agent parsing:
+
+- **JSONL** (`.jsonl`): Append-only logs - ideas, posts, contacts, interactions
+- **YAML** (`.yaml`): Structured configs - goals, values, circles
+- **Markdown** (`.md`): Narrative content - voice, brand, calendar, todos
+- **XML** (`.xml`): Complex prompts - content generation templates
+
+### Append-Only Data Integrity
+
+JSONL files are **append-only**. Never delete entries:
+- Mark as `"status": "archived"` instead of deleting
+- Preserves history for pattern analysis
+- Enables "what worked" retrospectives
+
+## Detailed Topics
+
+### Module Overview
+
+```
+digital-brain/
+├── identity/     → Voice, brand, values (READ FIRST for content)
+├── content/      → Ideas, drafts, posts, calendar
+├── knowledge/    → Bookmarks, research, learning
+├── network/      → Contacts, interactions, intros
+├── operations/   → Todos, goals, meetings, metrics
+└── agents/       → Automation scripts
+```
+
+### Identity Module (Critical for Content)
+
+**Always read `identity/voice.md` before generating any content.**
+
+Contains:
+- `voice.md` - Tone, style, vocabulary, patterns
+- `brand.md` - Positioning, audience, content pillars
+- `values.yaml` - Core beliefs and principles
+- `bio-variants.md` - Platform-specific bios
+- `prompts/` - Reusable generation templates
+
+### Content Module
+
+Pipeline: `ideas.jsonl` → `drafts/` → `posts.jsonl`
+
+- Capture ideas immediately to `ideas.jsonl`
+- Develop in `drafts/` using `templates/`
+- Log published content to `posts.jsonl` with metrics
+- Plan in `calendar.md`
+
+### Network Module
+
+Personal CRM with relationship tiers:
+- `inner` - Weekly touchpoints
+- `active` - Bi-weekly touchpoints
+- `network` - Monthly touchpoints
+- `dormant` - Quarterly reactivation checks
+
+### Operations Module
+
+Productivity system with priority levels:
+- P0: Do today, blocking
+- P1: This week, important
+- P2: This month, valuable
+- P3: Backlog, nice to have
+
+## Practical Guidance
+
+### Content Creation Workflow
+
+```
+1. Read identity/voice.md (REQUIRED)
+2. Check identity/brand.md for topic alignment
+3. Reference content/posts.jsonl for successful patterns
+4. Use content/templates/ as starting structure
+5. Draft matching voice attributes
+6. Log to posts.jsonl after publishing
+```
+
+### Pre-Meeting Preparation
+
+```
+1. Look up contact: network/contacts.jsonl
+2. Get history: network/interactions.jsonl
+3. Check pending: operations/todos.md
+4. Generate brief with context
+```
+
+### Weekly Review Process
+
+```
+1. Run: python agents/scripts/weekly_review.py
+2. Review metrics in operations/metrics.jsonl
+3. Check stale contacts: agents/scripts/stale_contacts.py
+4. Update goals progress in operations/goals.yaml
+5. Plan next week in content/calendar.md
+```
+
+## Examples
+
+### Example: Writing an X Post
+
+**Input**: "Help me write a post about AI agents"
+
+**Process**:
+1. Read `identity/voice.md` → Extract voice attributes
+2. Check `identity/brand.md` → Confirm "ai_agents" is a content pillar
+3. Reference `content/posts.jsonl` → Find similar successful posts
+4. Draft post matching voice patterns
+5. Suggest adding to `content/ideas.jsonl` if not publishing immediately
+
+**Output**: Post draft in user's authentic voice with platform-appropriate format.
+
+### Example: Contact Lookup
+
+**Input**: "Prepare me for my call with Sarah Chen"
+
+**Process**:
+1. Search `network/contacts.jsonl` for "Sarah Chen"
+2. Get recent entries from `network/interactions.jsonl`
+3. Check `operations/todos.md` for pending items with Sarah
+4. Compile brief: role, context, last discussed, follow-ups
+
+**Output**: Pre-meeting brief with relationship context.
+
+## Guidelines
+
+1. **Voice First**: Always read `identity/voice.md` before any content generation
+2. **Append Only**: Never delete from JSONL files - archive instead
+3. **Update Timestamps**: Set `updated` field when modifying tracked data
+4. **Cross-Reference**: Knowledge informs content, network informs operations
+5. **Log Interactions**: Always log meetings/calls to `interactions.jsonl`
+6. **Preserve History**: Past content in `posts.jsonl` informs future performance
+
+## Integration
+
+This skill integrates context engineering principles:
+
+- **context-fundamentals** - Progressive disclosure, attention budget management
+- **memory-systems** - JSONL for persistent memory, structured recall
+- **tool-design** - Scripts in `agents/scripts/` follow tool design principles
+- **context-optimization** - Module separation prevents context bloat
+
+## References
+
+Internal references:
+- [Identity Module](./identity/IDENTITY.md) - Voice and brand details
+- [Content Module](./content/CONTENT.md) - Content pipeline docs
+- [Network Module](./network/NETWORK.md) - CRM documentation
+- [Operations Module](./operations/OPERATIONS.md) - Productivity system
+- [Agent Scripts](./agents/AGENTS.md) - Automation documentation
+
+External resources:
+- [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- [Anthropic Context Engineering Guide](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+
+---
+
+## Skill Metadata
+
+**Created**: 2024-12-29
+**Last Updated**: 2024-12-29
+**Author**: Murat Can Koylan
+**Version**: 1.0.0

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

@@ -0,0 +1,219 @@
+# Skills Mapping: Digital Brain
+
+This document maps how [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) principles are applied in the Digital Brain implementation.
+
+---
+
+## Context Engineering Principles Applied
+
+### 1. Context Fundamentals
+
+| Concept | Source Skill | Digital Brain Application |
+|---------|--------------|---------------------------|
+| **Attention Budget** | context-fundamentals | Module separation ensures only relevant content loads. Voice file (~200 lines) loads for content tasks; contacts file loads for network tasks. Never load everything. |
+| **Progressive Disclosure** | context-fundamentals | Three-level architecture: L1 (SKILL.md metadata), L2 (module instructions), L3 (data files). Each level loads only when needed. |
+| **High-Signal Tokens** | context-fundamentals | JSONL schemas include only essential fields. Voice profiles focus on patterns, not exhaustive rules. |
+
+**Design Decision**:
+> "Find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome."
+
+Applied by keeping `voice.md` focused on distinctive patterns (signature phrases, anti-patterns) rather than generic writing advice Claude already knows.
+
+---
+
+### 2. Memory Systems
+
+| Concept | Source Skill | Digital Brain Application |
+|---------|--------------|---------------------------|
+| **Append-Only Logs** | memory-systems | All `.jsonl` files are append-only. Status changes via `"status": "archived"`, never deletion. Preserves full history. |
+| **Structured Recall** | memory-systems | Consistent schemas across files enable pattern matching. `contact_id` links `contacts.jsonl` to `interactions.jsonl`. |
+| **Episodic Memory** | memory-systems | `interactions.jsonl` captures discrete events. `posts.jsonl` logs content with performance metrics for retrospective analysis. |
+| **Semantic Memory** | memory-systems | `knowledge/bookmarks.jsonl` with categories and tags enables topic-based retrieval. |
+
+**Design Decision**:
+> "Agents maintain persistent memory files to track progress across complex sequences."
+
+Applied in `operations/metrics.jsonl` where weekly snapshots accumulate, enabling trend analysis without recomputing from raw data.
+
+---
+
+### 3. Tool Design
+
+| Concept | Source Skill | Digital Brain Application |
+|---------|--------------|---------------------------|
+| **Self-Contained Tools** | tool-design | Scripts in `agents/scripts/` are standalone Python files. Each does one thing: `weekly_review.py` generates reviews, `stale_contacts.py` finds neglected relationships. |
+| **Clear Input/Output** | tool-design | Scripts read from known paths, output structured text to stdout. No side effects unless explicitly documented. |
+| **Token Efficiency** | tool-design | Scripts process data and return summaries. Agent receives results, not raw data processing logic. |
+
+**Design Decision**:
+> "Tools should be self-contained, unambiguous, and promote token efficiency."
+
+Applied by having `content_ideas.py` analyze bookmarks and past posts internally, returning only actionable suggestions rather than raw analysis.
+
+---
+
+### 4. Context Optimization
+
+| Concept | Source Skill | Digital Brain Application |
+|---------|--------------|---------------------------|
+| **Module Separation** | context-optimization | Six distinct modules (`identity/`, `content/`, `knowledge/`, `network/`, `operations/`, `agents/`) prevent cross-contamination. Content creation never needs to load network data. |
+| **Just-In-Time Loading** | context-optimization | Module instruction files (`IDENTITY.md`, `CONTENT.md`, etc.) load only when that module is relevant. |
+| **Reference Depth** | context-optimization | Main SKILL.md links to module docs which link to data files. Maximum two hops to any information. |
+
+**Design Decision**:
+> "Rather than pre-loading all data, maintain lightweight identifiers and dynamically load data at runtime."
+
+Applied in network module: agent first scans `contacts.jsonl` for matching name, then loads specific `interactions.jsonl` entries only for that contact.
+
+---
+
+### 5. Context Degradation (Mitigation)
+
+| Risk | Source Skill | Digital Brain Mitigation |
+|------|--------------|--------------------------|
+| **Context Rot** | context-degradation | Module separation caps any single load. Voice file stays under 300 lines. Data files stream via JSONL (read line by line). |
+| **Stale Context** | context-degradation | `last_contact` timestamps in contacts. `stale_contacts.py` proactively surfaces relationships needing attention. |
+| **Conflicting Instructions** | context-degradation | Single source of truth per domain. Voice only in `voice.md`. Goals only in `goals.yaml`. No duplication. |
+
+**Design Decision**:
+> "As context length increases, models experience diminishing returns in accuracy and recall."
+
+Applied by keeping SKILL.md under 200 lines, each module instruction file under 100 lines, and using external files for data rather than inline content.
+
+---
+
+## Architecture Decisions
+
+### Why JSONL for Logs?
+
+```
+✓ Append-only by design
+✓ Stream-friendly (no full file parse)
+✓ Schema per line (first line documents structure)
+✓ Agent-friendly (standard JSON parsing)
+✓ Grep-compatible for quick searches
+
+✗ Not human-editable (use YAML/MD for configs)
+✗ No transactions (acceptable for personal data)
+```
+
+### Why Markdown for Narrative?
+
+```
+✓ Human-readable and editable
+✓ Rich formatting (tables, lists, code)
+✓ Git-friendly diffs
+✓ Universal rendering
+
+Use for: voice, brand, calendar, todos, templates
+```
+
+### Why YAML for Config?
+
+```
+✓ Hierarchical structure
+✓ Human-readable
+✓ Comments supported
+✓ Clean syntax for nested data
+
+Use for: goals, values, circles, learning
+```
+
+### Why XML for Prompts?
+
+```
+✓ Clear structure for agents
+✓ Named sections (instructions, context, output)
+✓ Variable placeholders
+✓ Validation-friendly
+
+Use for: content-generation templates, complex prompts
+```
+
+---
+
+## Workflow Mappings
+
+### Content Creation → Skills Applied
+
+```
+User: "Write a post about building in public"
+
+Skills Chain:
+1. context-fundamentals → Load only identity module
+2. memory-systems → Retrieve voice patterns from voice.md
+3. context-optimization → Don't load network/operations
+4. tool-design → Use content templates as structured scaffolds
+
+Files Loaded:
+- SKILL.md (50 tokens) - Routing
+- identity/IDENTITY.md (80 tokens) - Module instructions
+- identity/voice.md (200 tokens) - Voice patterns
+- identity/brand.md (scan for pillars) - Topic validation
+
+Total: ~400 tokens vs loading entire brain (~5000 tokens)
+```
+
+### Relationship Management → Skills Applied
+
+```
+User: "Prepare me for my call with Alex"
+
+Skills Chain:
+1. context-fundamentals → Load only network module
+2. memory-systems → Query contacts, then interactions
+3. context-optimization → Just-in-time loading of specific contact
+4. tool-design → Structured output (brief format)
+
+Files Loaded:
+- SKILL.md (50 tokens) - Routing
+- network/NETWORK.md (60 tokens) - Module instructions
+- network/contacts.jsonl (scan for Alex) - Contact data
+- network/interactions.jsonl (filter by contact_id) - History
+
+Total: ~300 tokens for relevant context only
+```
+
+---
+
+## Trade-offs and Rationale
+
+| Decision | Trade-off | Rationale |
+|----------|-----------|-----------|
+| Separate modules | More files to navigate | Prevents context bloat; enables targeted loading |
+| JSONL for data | Less human-friendly | Optimized for agent parsing and append operations |
+| No database | No query language | Simplicity; works offline; no dependencies |
+| Python scripts | Requires Python runtime | Universal; readable; easy to extend |
+| Placeholders not examples | User must fill in | Avoids "AI slop"; forces personalization |
+
+---
+
+## Verification Checklist
+
+When extending Digital Brain, verify:
+
+- [ ] New files follow format conventions (JSONL/YAML/MD/XML)
+- [ ] Module instruction files stay under 100 lines
+- [ ] JSONL files include schema line as first entry
+- [ ] Cross-module references are minimal
+- [ ] Scripts are self-contained with clear I/O
+- [ ] No duplicate sources of truth
+
+---
+
+## Related Skills
+
+This implementation draws from these skills in the collection:
+
+| Skill | Primary Application |
+|-------|---------------------|
+| `context-fundamentals` | Overall architecture, progressive disclosure |
+| `context-degradation` | Mitigation strategies, file size limits |
+| `context-optimization` | Module separation, just-in-time loading |
+| `memory-systems` | JSONL design, append-only patterns |
+| `tool-design` | Agent scripts, I/O patterns |
+| `multi-agent-patterns` | Future: delegation to specialized sub-agents |
+
+---
+
+*This mapping demonstrates how theoretical context engineering principles translate to practical system design.*