AGENTS/.sisyphus/notepads/chiron-agent-framework/learnings.md

Learnings - Chiron Agent Framework

Task: Update agents/agents.json with 6 Chiron agents

Agent Configuration Pattern

• JSON structure: { "agent-name": { "description": "...", "mode": "...", "model": "...", "prompt": "{file:./prompts/...}", "permission": { "question": "..." } } }
• Two primary agents: chiron (plan mode) and chiron-forge (build mode)
• Four subagents: hermes (work comm), athena (work knowledge), apollo (private knowledge), calliope (writing)
• All agents use zai-coding-plan/glm-4.7 model
• Prompts are file references: {file:./prompts/agent-name.txt}
• Permissions use simple allow: { "question": "allow" }

Verification

• JSON validation: python3 -c "import json; json.load(open('agents/agents.json'))"
• No MCP configuration needed for agent definitions
• Mode values: "primary" or "subagent"

Files Modified

• agents/agents.json - Expanded from 1 to 6 agents (8 lines → 57 lines)

Successful Approaches

• Follow existing JSON structure pattern
• Maintain consistent indentation and formatting
• Use file references for prompts (not inline)

Task: Create prompts/chiron-forge.txt

Chiron-Forge Prompt Pattern

• Purpose: Execution/build mode counterpart to Chiron's planning mode
• Identity: Worker-mode AI assistant with full write access
• Core distinction: Chiron = planning/analysis, Chiron-Forge = building/executing
• Second-person addressing: "You are..." format

Key Components

• Identity: "execution and build mode counterpart to Chiron"
• Capabilities: Full write access, read files, create/modify files, execute bash commands
• Workflow: Receive → Understand → Plan Action → Execute → Confirm (destructive) → Report
• Safety: Question tool for destructive operations (rm *, git push), sudo denied
• Delegation: Still delegates to subagents for specialized domains
• Scope boundaries: NOT planning/analysis agent, NOT evaluation of alternatives

Verification

• File size: 3185 chars (target >500)
• Keywords present: execution, build, worker, write
• Lines: 67

Files Created

• prompts/chiron-forge.txt - Chiron-Forge build mode system prompt

Task: Create prompts/calliope.txt

Calliope Prompt Pattern

• Purpose: Writing specialist for documentation, reports, meeting notes, and professional prose
• Identity: Greek muse of epic poetry and eloquence
• Core distinction: Focuses on eloquence and structure, not technical implementation
• Second-person addressing: "You are..." format

Key Components

• Identity: "Greek muse of epic poetry and eloquence, specializing in writing assistance"
• Capabilities: Draft documentation, create reports, transform notes to summaries, professional writing
• Workflow: Understand → Clarify (Question tool) → Gather → Draft → Refine → Review
• Quality Standards: Clarity, logical structure, consistent terminology, accurate representation
• Output Format: Clear hierarchy, bullet/numbered lists, tables, executive summaries, action items

Scope Boundaries

• DO NOT execute code or run commands (delegate to technical agents)
• DO NOT handle short communication (Hermes's domain)
• DO NOT manage wiki knowledge bases (Athena's domain)
• DO NOT make factual assertions without verification
• DO NOT write specialized domain content without input

Verification

• File size: 3390 chars (well above 500 minimum)
• Keywords present: writing, document, report, summaries
• Lines: 48
• Follows standard prompt structure from agent-development skill

Files Created

• prompts/calliope.txt - Calliope writing specialist system prompt (48 lines)

Task: Create skills/msteams/SKILL.md

MS Teams Skill Pattern

• Description format: Clear trigger conditions with numbered use cases
• Structure: Quick start → Core API capabilities → Common workflows → API endpoint reference → Best practices → Integration examples
• Scope: Channels, messages, meetings, chat operations
• Excluded: Authentication flows (handled externally), Outlook email functionality

Verification

• YAML frontmatter validation: python3 -c "import yaml; yaml.safe_load()"
• Required fields: name, description, compatibility
• Body content: >7400 chars, comprehensive coverage

Files Created

• skills/msteams/SKILL.md - Complete Teams Graph API integration documentation

Task: Create skills/obsidian/SKILL.md

Obsidian Skill Pattern

• Purpose: Document Obsidian Local REST API integration
• API base URL: http://localhost:27124
• Core capabilities: vault operations, note CRUD, search, daily notes

SKILL.md Requirements

• YAML frontmatter with quoted description when using special characters
• Required fields: name, description, compatibility: opencode
• Description must include "Use when:" triggers and "Triggers:" examples
• Body follows markdown structure with ATX headers (#, ##, ###)

Key Sections

1. Quick Start - API overview and base URL
2. Core Workflows - Step-by-step API operations
3. Note Structure Patterns - Frontmatter and WikiLink formats
4. Search Patterns - Tag-based, path-based, combined searches
5. Integration with Other Skills - Handoff triggers to other skills
6. Error Handling - HTTP status codes
7. Best Practices - Usage guidelines
8. Example Workflows - Practical curl examples

YAML Frontmatter Gotchas

• Must quote description if it contains colons, parentheses, or other special YAML characters
• Example: description: "Text with (parentheses) and colons: like this"
• Without quotes: causes YAML parsing errors

Obsidian Local REST API Endpoints

• GET /vault/ - List all files
• GET /active/ - Get active note
• POST /notes/ - Create note
• GET /notes/{path} - Read note
• PUT /notes/{path} - Update note
• DELETE /notes/{path} - Delete note
• GET /search/simple - Search content
• POST /search/ - Advanced search
• POST /daily/note - Create daily note
• GET /daily/note - Get daily note

Frontmatter Pattern

---
date: YYYY-MM-DD
created: ISO8601_timestamp
type: note_type
status: draft|final|archived
tags: #tag1 #tag2
---

WikiLink Format

• Link - Basic link
• Link - Link with alias
• #Section - Section link
• Note#Section - Section in other note

Search Query Patterns

• tag:#tagname - Tag search
• path:directory/ - Path restriction
• Combined with contextLength parameter

Files Created

• skills/obsidian/SKILL.md (250 lines, 6443 bytes)

Task: Create skills/outlook/SKILL.md

Outlook Skill Pattern

• Purpose: Document Outlook Graph API integration via MCP
• Core capabilities: Mail CRUD, folder management, calendar events, contacts, search
• Excluded: Graph API authentication (handled externally), Teams functionality

SKILL.md Structure for API Skills

• YAML frontmatter with clear "Use when:" triggers and "Triggers:" examples
• Description follows pattern: "API integration via MCP. Use when: (1) ..., (2) ... Triggers: '...', '...', '...'"
• Body sections: Core Operations → Common Workflows → IDs and Discovery → Important Notes

API Documentation Pattern

• Group operations by domain (Mail Access, Mail CRUD, Folder Management, Calendar Events, Contacts, Search)
• Each operation format: Function name: function_name(params) - Brief description
• Include parameter defaults: param=value in function signatures
• Document common workflows with step-by-step examples

Verification

• YAML frontmatter validation: python3 skills/skill-creator/scripts/quick_validate.py skills/outlook/
• Required fields: name, description, compatibility: opencode
• File size: 7572 chars (comprehensive but not excessive)

Files Created

• skills/outlook/SKILL.md (160 lines, 7572 bytes)

Task: Create scripts/validate-agents.sh

Validation Script Pattern

• Bash script follows existing test-skill.sh conventions
• Shebang: #!/usr/bin/env bash
• Strict mode: set -euo pipefail
• Color output: RED, GREEN, YELLOW, NC (no color)
• Helper functions for specific checks
• Main case statement for option handling

Script Structure

# Setup
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(dirname "$SCRIPT_DIR")"

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

# Functions
check_json_valid() - Validates JSON syntax
check_required_fields() - Validates agent structure
check_prompt_file() - Verifies prompt file exists and non-empty

# Main case statement handles --help, default validation

Agent Validation Checks

1. JSON validity: python3 -m json.tool
2. Required fields: description, mode, model, prompt, permission
3. Prompt file extraction: Regex from {file:./prompts/filename} format
4. File existence: Check prompt file exists in prompts/ directory
5. Non-empty check: Use -s test operator

Regex Pattern for Prompt References

[[ $prompt_ref =~ \{file:./prompts/([^}]+)\} ]]
# BASH_REMATCH[1] contains the filename

Python Integration in Bash Scripts

• Validate JSON: python3 -m json.tool file
• Parse JSON: python3 -c "import json; json.load(open('file'))"
• Extract data: python3 -c "import json; data = json.load(open('file')); print('\n'.join(data.keys()))"
• Check fields: python3 -c "import sys, json; data = json.load(sys.stdin); exit(0 if 'field' in data else 1)"

Comment Discipline

• Keep file header documentation (usage, purpose, checks)
• Remove inline comments for self-explanatory code (function names, clear operations)
• Keep comments for complex/regex patterns
• Follow existing repository conventions (e.g., "# Main" section marker)

Files Created

• scripts/validate-agents.sh - Bash validation script (130 lines)

Verification

• Script executable: chmod +x
• Runs successfully: Validates all 6 agents
• Error handling: Detects missing files, invalid JSON, missing fields
• Help documentation: --help flag