From 1bc81fb38c20154f0dd77f7da9b9d95439d8d873 Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Wed, 18 Feb 2026 17:32:13 +0100 Subject: [PATCH] chore: update readme --- README.md | 157 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 89 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 362166d..48248db 100644 --- a/README.md +++ b/README.md @@ -11,33 +11,42 @@ This repository serves as a **personal AI operating system** - a collection of s - **Communications** - Email management, meeting scheduling, follow-up tracking - **AI Development** - Tools for creating new skills and agent configurations - **Memory & Context** - Persistent memory systems, conversation analysis +- **Document Processing** - PDF manipulation, spreadsheet handling, diagram generation - **Custom Workflows** - Domain-specific automation and specialized agents ## 📂 Repository Structure ``` . -├── agent/ # Agent definitions (agents.json) -├── prompts/ # Agent system prompts (chiron.txt, chiron-forge.txt) +├── agents/ # Agent definitions (agents.json) +├── prompts/ # Agent system prompts (chiron.txt, chiron-forge.txt, etc.) ├── context/ # User profiles and preferences │ └── profile.md # Work style, PARA areas, preferences -├── command/ # Custom command definitions +├── commands/ # Custom command definitions │ └── reflection.md -├── skill/ # Opencode Agent Skills (11+ skills) -│ ├── task-management/ # PARA-based productivity -│ ├── skill-creator/ # Meta-skill for creating skills -│ ├── reflection/ # Conversation analysis -│ ├── communications/ # Email & messaging -│ ├── calendar-scheduling/ # Time management -│ ├── mem0-memory/ # Persistent memory -│ ├── research/ # Investigation workflows -│ ├── knowledge-management/ # Note capture & organization +├── skills/ # Opencode Agent Skills (18 skills) +│ ├── agent-development/ # Agent creation and configuration │ ├── basecamp/ # Basecamp project management │ ├── brainstorming/ # Ideation & strategic thinking -│ └── plan-writing/ # Project planning templates +│ ├── doc-translator/ # Documentation translation +│ ├── excalidraw/ # Architecture diagrams +│ ├── frontend-design/ # UI/UX design patterns +│ ├── memory/ # Persistent memory system +│ ├── mem0-memory/ # DEPRECATED (use memory) +│ ├── msteams/ # Microsoft Teams integration +│ ├── obsidian/ # Obsidian vault management +│ ├── outline/ # Outline wiki integration +│ ├── outlook/ # Outlook email & calendar +│ ├── pdf/ # PDF manipulation toolkit +│ ├── prompt-engineering-patterns/ # Prompt patterns +│ ├── reflection/ # Conversation analysis +│ ├── skill-creator/ # Meta-skill for creating skills +│ ├── systematic-debugging/ # Debugging methodology +│ └── xlsx/ # Spreadsheet handling ├── scripts/ # Repository utility scripts │ └── test-skill.sh # Test skills without deploying -├── .beads/ # Issue tracking database +├── rules/ # Development rules and conventions +├── tools/ # Utility tools ├── AGENTS.md # Developer documentation └── README.md # This file ``` @@ -65,15 +74,15 @@ inputs.agents = { # In your home-manager module (e.g., opencode.nix) xdg.configFile = { - "opencode/skill".source = "${inputs.agents}/skill"; + "opencode/skills".source = "${inputs.agents}/skills"; "opencode/context".source = "${inputs.agents}/context"; - "opencode/command".source = "${inputs.agents}/command"; + "opencode/commands".source = "${inputs.agents}/commands"; "opencode/prompts".source = "${inputs.agents}/prompts"; }; # Agent config is embedded into config.json, not deployed as files programs.opencode.settings.agent = builtins.fromJSON - (builtins.readFile "${inputs.agents}/agent/agents.json"); + (builtins.readFile "${inputs.agents}/agents/agents.json"); ``` Rebuild your system: @@ -82,7 +91,7 @@ Rebuild your system: home-manager switch ``` -**Note**: The `agent/` directory is NOT deployed as files. Instead, `agents.json` is read at Nix evaluation time and embedded into the opencode `config.json`. +**Note**: The `agents/` directory is NOT deployed as files. Instead, `agents.json` is read at Nix evaluation time and embedded into the opencode `config.json`. #### Option 2: Manual Installation @@ -92,8 +101,11 @@ Clone and symlink: # Clone repository git clone https://github.com/yourusername/AGENTS.git ~/AGENTS -# Create symlink to Opencode config directory -ln -s ~/AGENTS ~/.config/opencode +# Create symlinks to Opencode config directory +ln -s ~/AGENTS/skills ~/.config/opencode/skills +ln -s ~/AGENTS/context ~/.config/opencode/context +ln -s ~/AGENTS/commands ~/.config/opencode/commands +ln -s ~/AGENTS/prompts ~/.config/opencode/prompts ``` ### Verify Installation @@ -101,8 +113,8 @@ ln -s ~/AGENTS ~/.config/opencode Check that Opencode can see your skills: ```bash -# Skills should be available at ~/.config/opencode/skill/ -ls ~/.config/opencode/skill/ +# Skills should be available at ~/.config/opencode/skills/ +ls ~/.config/opencode/skills/ ``` ## 🎨 Creating Your First Skill @@ -112,19 +124,19 @@ Skills are modular packages that extend Opencode with specialized knowledge and ### 1. Initialize a New Skill ```bash -python3 skill/skill-creator/scripts/init_skill.py my-skill-name --path skill/ +python3 skills/skill-creator/scripts/init_skill.py my-skill-name --path skills/ ``` This creates: -- `skill/my-skill-name/SKILL.md` - Main skill documentation -- `skill/my-skill-name/scripts/` - Executable code (optional) -- `skill/my-skill-name/references/` - Reference documentation (optional) -- `skill/my-skill-name/assets/` - Templates and files (optional) +- `skills/my-skill-name/SKILL.md` - Main skill documentation +- `skills/my-skill-name/scripts/` - Executable code (optional) +- `skills/my-skill-name/references/` - Reference documentation (optional) +- `skills/my-skill-name/assets/` - Templates and files (optional) ### 2. Edit the Skill -Open `skill/my-skill-name/SKILL.md` and customize: +Open `skills/my-skill-name/SKILL.md` and customize: ```yaml --- @@ -142,7 +154,7 @@ compatibility: opencode ### 3. Validate the Skill ```bash -python3 skill/skill-creator/scripts/quick_validate.py skill/my-skill-name +python3 skills/skill-creator/scripts/quick_validate.py skills/my-skill-name ``` ### 4. Test the Skill @@ -160,39 +172,46 @@ The test script creates a temporary config directory with symlinks to this repo' ## 📚 Available Skills -| Skill | Purpose | Status | -| ------------------------ | ------------------------------------------------------- | --------- | -| **task-management** | PARA-based productivity with Obsidian Tasks integration | ✅ Active | -| **skill-creator** | Guide for creating new Opencode skills | ✅ Active | -| **reflection** | Conversation analysis and skill improvement | ✅ Active | -| **communications** | Email drafts, follow-ups, message management | ✅ Active | -| **calendar-scheduling** | Time blocking, meeting management | ✅ Active | -| **mem0-memory** | Persistent memory storage and retrieval | ✅ Active | -| **research** | Investigation workflows, source management | ✅ Active | -| **knowledge-management** | Note capture, knowledge organization | ✅ Active | -| **basecamp** | Basecamp project & todo management via MCP | ✅ Active | -| **brainstorming** | General-purpose ideation with Obsidian save | ✅ Active | -| **plan-writing** | Project plans with templates (kickoff, tasks, risks) | ✅ Active | +| Skill | Purpose | Status | +| --------------------------- | -------------------------------------------------------------- | ------------ | +| **agent-development** | Create and configure Opencode agents | ✅ Active | +| **basecamp** | Basecamp project & todo management via MCP | ✅ Active | +| **brainstorming** | General-purpose ideation and strategic thinking | ✅ Active | +| **doc-translator** | Documentation translation to German/Czech with Outline publish | ✅ Active | +| **excalidraw** | Architecture diagrams from codebase analysis | ✅ Active | +| **frontend-design** | Production-grade UI/UX with high design quality | ✅ Active | +| **memory** | SQLite-based persistent memory with hybrid search | ✅ Active | +| **mem0-memory** | Legacy memory system (deprecated) | ⚠️ Deprecated | +| **msteams** | Microsoft Teams integration via Graph API | ✅ Active | +| **obsidian** | Obsidian vault management via Local REST API | ✅ Active | +| **outline** | Outline wiki integration for team documentation | ✅ Active | +| **outlook** | Outlook email, calendar, and contact management | ✅ Active | +| **pdf** | PDF manipulation, extraction, creation, and forms | ✅ Active | +| **prompt-engineering-patterns** | Advanced prompt engineering techniques | ✅ Active | +| **reflection** | Conversation analysis and skill improvement | ✅ Active | +| **skill-creator** | Guide for creating new Opencode skills | ✅ Active | +| **systematic-debugging** | Debugging methodology for bugs and test failures | ✅ Active | +| **xlsx** | Spreadsheet creation, editing, and analysis | ✅ Active | ## 🤖 AI Agents -### Chiron - Personal Assistant +### Primary Agents -**Configuration**: `agent/agents.json` + `prompts/chiron.txt` +| Agent | Mode | Purpose | +| ------------------- | ------- | ---------------------------------------------------- | +| **Chiron** | Plan | Read-only analysis, planning, and guidance | +| **Chiron Forge** | Build | Full execution and task completion with safety | -Chiron is a personal AI assistant focused on productivity and task management. Named after the wise centaur from Greek mythology, Chiron provides: +### Subagents (Specialists) -- Task and project management guidance -- Daily and weekly review workflows -- Skill routing based on user intent -- Integration with productivity tools (Obsidian, ntfy, n8n) +| Agent | Domain | Purpose | +| ------------------- | ---------------- | ------------------------------------------ | +| **Hermes** | Communication | Basecamp, Outlook, MS Teams | +| **Athena** | Research | Outline wiki, documentation, knowledge | +| **Apollo** | Private Knowledge| Obsidian vault, personal notes | +| **Calliope** | Writing | Documentation, reports, prose | -**Modes**: - -- **Chiron** (Plan Mode) - Read-only analysis and planning (`prompts/chiron.txt`) -- **Chiron-Forge** (Worker Mode) - Full write access with safety prompts (`prompts/chiron-forge.txt`) - -**Triggers**: Personal productivity requests, task management, reviews, planning +**Configuration**: `agents/agents.json` + `prompts/*.txt` ## 🛠️ Development Workflow @@ -200,7 +219,7 @@ Chiron is a personal AI assistant focused on productivity and task management. N Before committing: -1. **Validate skills**: `./scripts/test-skill.sh --validate` or `python3 skill/skill-creator/scripts/quick_validate.py skill/` +1. **Validate skills**: `./scripts/test-skill.sh --validate` or `python3 skills/skill-creator/scripts/quick_validate.py skills/` 2. **Test locally**: `./scripts/test-skill.sh --run` to launch opencode with dev skills 3. **Check formatting**: Ensure YAML frontmatter is valid 4. **Update docs**: Keep README and AGENTS.md in sync @@ -210,9 +229,9 @@ Before committing: ### Essential Documentation - **AGENTS.md** - Complete developer guide for AI agents -- **skill/skill-creator/SKILL.md** - Comprehensive skill creation guide -- **skill/skill-creator/references/workflows.md** - Workflow pattern library -- **skill/skill-creator/references/output-patterns.md** - Output formatting patterns +- **skills/skill-creator/SKILL.md** - Comprehensive skill creation guide +- **skills/skill-creator/references/workflows.md** - Workflow pattern library +- **skills/skill-creator/references/output-patterns.md** - Output formatting patterns ### Skill Design Principles @@ -223,22 +242,25 @@ Before committing: ### Example Skills to Study -- **task-management/** - Full implementation with Obsidian Tasks integration - **skill-creator/** - Meta-skill with bundled resources - **reflection/** - Conversation analysis with rating system - **basecamp/** - MCP server integration with multiple tool categories - **brainstorming/** - Framework-based ideation with Obsidian markdown save -- **plan-writing/** - Template-driven document generation +- **memory/** - SQLite-based hybrid search implementation ## 🔧 Customization ### Modify Agent Behavior -Edit `agent/agents.json` for agent definitions and `prompts/*.txt` for system prompts: +Edit `agents/agents.json` for agent definitions and `prompts/*.txt` for system prompts: -- `agent/agents.json` - Agent names, models, permissions +- `agents/agents.json` - Agent names, models, permissions - `prompts/chiron.txt` - Chiron (Plan Mode) system prompt -- `prompts/chiron-forge.txt` - Chiron-Forge (Worker Mode) system prompt +- `prompts/chiron-forge.txt` - Chiron Forge (Build Mode) system prompt +- `prompts/hermes.txt` - Hermes (Communication) system prompt +- `prompts/athena.txt` - Athena (Research) system prompt +- `prompts/apollo.txt` - Apollo (Private Knowledge) system prompt +- `prompts/calliope.txt` - Calliope (Writing) system prompt **Note**: Agent changes require `home-manager switch` to take effect (config is embedded, not symlinked). @@ -253,7 +275,7 @@ Edit `context/profile.md` to configure: ### Add Custom Commands -Create new command definitions in `command/` directory following the pattern in `command/reflection.md`. +Create new command definitions in `commands/` directory following the pattern in `commands/reflection.md`. ## 🌟 Use Cases @@ -309,15 +331,14 @@ This repository contains personal configurations and skills. Feel free to use th ## 🔗 Links - [Opencode](https://opencode.dev) - AI coding assistant -- [Beads](https://github.com/steveyegge/beads) - AI-native issue tracking - [PARA Method](https://fortelabs.com/blog/para/) - Productivity methodology - [Obsidian](https://obsidian.md) - Knowledge management platform ## 🙋 Questions? - Check `AGENTS.md` for detailed developer documentation -- Review existing skills in `skill/` for examples -- See `skill/skill-creator/SKILL.md` for skill creation guide +- Review existing skills in `skills/` for examples +- See `skills/skill-creator/SKILL.md` for skill creation guide ---