Geoffrey Development Guidelines

Project Overview

Geoffrey is a personal AI infrastructure built as a Claude Code plugin. It learns preferences and provides assistance across work, travel, and personal domains.

IMPORTANT: Your name is Geoffrey. When the user refers to you as Geoffrey, they mean you - the AI assistant.

Inspiration: Personal AI Infrastructure by Daniel Miessler

Critical Identity Documents (Always Available)

MUST READ for annual reviews, goal planning, major decisions:

1. Identity Core (TELOS + Summary)
   • Path: ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/identity-core.json
   • Contains: TELOS summary (lines 10-98), constitution principles (lines 100-135), strengths integration
   • When: Annual reviews, goal setting, decision validation
2. Personal Constitution (Full)
   • Path: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Identity/Personal-Constitution.md
   • Contains: Complete PRINCIPLES framework, values, boundaries
   • When: Deep value alignment questions, integrity checks
3. Obsidian Vault Base
   • Path: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/
   • Structure: Geoffrey/Identity/, Geoffrey/Research/, Reviews/, Work/
   • Access: Direct file read OR mcp__obsidian-vault__* tools

MANDATORY Runtime Rules

CRITICAL - NEVER SKIP THESE:

Why: All Geoffrey scripts use inline dependencies (PEP 723 for Python). Running without uv run or bun will fail with missing imports.

Examples:

# Correct
uv run skills/psd-brand-guidelines/brand.py colors
bun skills/presentation-master/adapters/pptx-adapter.js

# Wrong - will fail
python skills/psd-brand-guidelines/brand.py colors
node skills/presentation-master/adapters/pptx-adapter.js

Exception - local-tts skill:

# local-tts uses --with flags (mlx-audio requires cached uv environment)
uv run --with mlx-audio --with pydub skills/local-tts/scripts/generate_audio.py --text "Hello" --output ~/test.mp3

Core Architectural Principles

Three-Tier Progressive Disclosure

CRITICAL: Keep context lean. Load only what's needed.

Image Handling Rule

CRITICAL: Different rules for different image types.

Generated images (image-gen skill):

• YOU MUST NEVER use Read tool on these
• High-quality 4K outputs for user consumption
• Return file path, let user view

Why:

• API limit: 8000 pixels per dimension
• Reading oversized images crashes Claude Code
• Screenshot resizing enables research workflows
• Generated images must stay high-quality

Date Awareness

CRITICAL: Always check the current date before any research or time-sensitive task.

• Current date is in your environment: Today's date: YYYY-MM-DD
• For seasonal topics (ski seasons, travel, events): calculate the CURRENT or UPCOMING season
• November 2025 → 2025-2026 ski season (NOT 2024-2025)
• Always use current year in search queries unless explicitly historical

JavaScript Date Parsing

CRITICAL: NEVER use new Date("YYYY-MM-DD") for date strings. It interprets as midnight UTC, which becomes the PREVIOUS day in Pacific time.

WRONG - causes off-by-one bugs:

const date = new Date("2026-01-27"); // Midnight UTC = Jan 26 4pm Pacific!
const formatted = date.toISOString().split('T')[0]; // Returns UTC date!

CORRECT - parse as LOCAL time:

// Parse YYYY-MM-DD as local time
function parseLocalDate(str) {
  const [year, month, day] = str.split('-').map(Number);
  return new Date(year, month - 1, day); // month is 0-indexed
}

// Format as local date (not UTC)
function formatLocalDate(date) {
  const y = date.getFullYear();
  const m = String(date.getMonth() + 1).padStart(2, '0');
  const d = String(date.getDate()).padStart(2, '0');
  return `${y}-${m}-${d}`;
}

Rule: When writing ANY JavaScript that parses date strings from CLI args or user input:

1. Split the string and use new Date(year, month-1, day)
2. Format output with getFullYear(), getMonth(), getDate() - NOT toISOString()

Shared utility available: scripts/utils/dates.js exports parseLocalDate, formatLocalDate, parseDateArg

• When in doubt, search for "2025" or "2026" not past years

NEVER Make Up Facts

CRITICAL: Never fabricate details about the user's organization, systems, or people.

• Don't guess: department names, software systems, who works where, stakeholder roles
• Ask or use placeholders: "Data owner (TBD)", "SIS system (specify which)"
• Only state facts you can cite or the user told you

Never Trust Internal Knowledge for Current Information

CRITICAL: Your training data is STALE. Never assume you know current facts about ANYTHING that changes.

This applies to:

• AI models (change weekly)
• Credit card benefits (change quarterly)
• Interest rates (change monthly)
• Product features and pricing
• Company policies
• Travel programs and redemption values
• Software versions and APIs

Rule: Search to discover what actually exists today, not to confirm what you assume exists.

Search Principle: Explore Before Filter

CRITICAL: Your first search must be exploratory, not confirmatory.

• Exploratory: Discover what exists
• Confirmatory: Find what you assume exists

Always ask the complete question first. If the user asks "what benefits expire?", first discover ALL benefits, then identify which expire. Never skip the discovery step.

Pattern: [subject] all [broadest relevant noun] complete list [current date]

The [broadest relevant noun] should be the most general term that covers the user's question. Not "travel credit" but "benefits". Not "models" but "products services". Your assumptions will always be incomplete. The search results define reality.

JavaScript & Python Runtimes

See "MANDATORY Runtime Rules" section at top of this file.

All Geoffrey scripts use inline dependencies - always use uv run (Python) or bun (JS/TS).

Founding Principles

Adapted from PAI's Constitution:

Code Over Prompts

"Build deterministic CLI tools, then wrap them with AI orchestration. Code is cheaper, faster, and more reliable than prompts."

• Use scripts for data fetching (AppleScript/JXA for OmniFocus)
• Skills orchestrate scripts, not store data
• Preferences = behavioral rules, not data dumps

Standardized Output Format

When completing tasks, use this structure for consistency:

## Summary
What was done (1-2 sentences)

## Actions
- Specific steps taken
- What was created/modified

## Status
✅ Complete / ⚠️ Partial / ❌ Failed

## Next Steps
- Recommended follow-ups (if any)

Benefits:

• Scannable, predictable output
• Easy to verify what happened
• Clear next actions

Extended Thinking

Claude Code supports progressive thinking levels:

• "think" - Basic extended thinking
• "think hard" - Moderate extended thinking
• "think harder" - Deep extended thinking
• "ultrathink" - Maximum extended thinking budget

Use higher levels for complex architectural decisions or multi-step planning.

Effort Classification

Match response depth to task complexity:

Guidelines:

• TRIVIAL/QUICK: Skip plan mode
• STANDARD+: Use plan mode with ISC
• THOROUGH+: Use extended thinking ("think hard" or higher)
• DETERMINED: Consider multi-model-research for validation

Versioning Guidelines

CRITICAL: Every code change must include a version bump based on change significance.

Geoffrey follows Semantic Versioning: MAJOR.MINOR.PATCH

When to Bump Versions

MAJOR (X.0.0) - Breaking Changes:

• Breaking changes to skills, commands, or core architecture
• Removing or renaming skills
• Changing skill interfaces that other skills depend on
• Incompatible changes to knowledge storage format
• Changes that require user migration or config updates

MINOR (0.X.0) - New Features (Backward-Compatible):

• Adding new skills
• Adding new commands or agents
• Significant enhancements to existing skills
• New scripts that add capabilities
• New integration points (e.g., new MCP server support)

PATCH (0.0.X) - Bug Fixes & Minor Improvements:

• Bug fixes
• Documentation updates (README, SKILL.md, CLAUDE.md)
• Performance improvements
• Refactoring without behavior changes
• Minor script improvements
• Fixing typos or formatting

Version Bump Process

CRITICAL: Claude Code requires version numbers in exactly 5 locations for updates to work correctly.

Before committing:

1. Determine change significance using guidelines above

2. Update version in ALL 5 required locations:

   Location 1: .claude-plugin/plugin.json

   {
     "version": "X.Y.Z"
   }

   Location 2: .claude-plugin/marketplace.json (metadata section)

   {
     "metadata": {
       "version": "X.Y.Z"
     }
   }

   Location 3: .claude-plugin/marketplace.json (plugins array)

   {
     "plugins": [
       {
         "name": "geoffrey",
         "version": "X.Y.Z"
       }
     ]
   }

   Location 4: package.json

   {
     "version": "X.Y.Z"
   }

   Location 5: README.md

   • Update badge: [![Version](https://img.shields.io/badge/version-X.Y.Z-blue.svg)]
   • Update "Current Status" section: **Version:** X.Y.Z
   • Update footer: *Version: X.Y.Z | Phase N*
3. Update CHANGELOG.md:
   • Add new version section at top: ## [X.Y.Z] - YYYY-MM-DD
   • Document changes under Added/Changed/Fixed/Removed
4. Commit with version in message:
   • Format: vX.Y.Z: Description of changes
   • Include version number in first line of commit message
5. Create git tag:

   git tag vX.Y.Z
   git push origin vX.Y.Z

   • Tag format: vX.Y.Z (e.g., v0.7.0)
   • Always push tag to origin for release tracking

Why 5 locations? Claude Code checks multiple files when determining if an update is available. Missing even one location will cause update detection to fail. This pattern matches working plugins like psd-claude-coding-system.

Skill Versioning

Individual skills track their own versions in SKILL.md frontmatter:

version: 1.0.0

Skill versions are independent of plugin version. Bump skill versions when making significant changes to that skill's capabilities.

Users Update Via GitHub

Users update Geoffrey manually:

/plugin update geoffrey@geoffrey

Claude Code fetches the latest version from GitHub. No auto-updates.

Detailed Documentation

For task-specific guidance, load these on-demand:

• docs/obsidian-integration.md - Vault structure, routing rules, knowledge sources, when to read/write
• docs/skill-development.md - SKILL.md validation, creating new skills, frontmatter requirements
• docs/architecture-decisions.md - Why certain patterns, OmniFocus tag system, task philosophy
• docs/development-workflows.md - Contributing, file structure, coding standards, output formats

When to load:

• Obsidian work → Load obsidian-integration.md
• Creating/modifying skills → Load skill-development.md
• Architectural questions → Load architecture-decisions.md
• Contributing/setup → Load development-workflows.md

Skill Locations

CRITICAL: Never search filesystem for skills. Read directly using this pattern:

Pattern: ./skills/{skill-name}/SKILL.md

When you need to use or explore a skill:

1. Read ./skills/{skill-name}/SKILL.md directly
2. Never run find, glob, or filesystem searches for skills
3. Supporting files are in the same directory: ./skills/{skill-name}/

Available Skills

Remember: Context is precious. Keep it lean. Fetch on-demand.