davidl71/devwisdom-go

devwisdom-go

Wisdom Module Extraction (Go Proof of Concept)

A standalone Go MCP server providing wisdom quotes, trusted advisors, and inspirational guidance for developers. Extracted from the exarp project as a proof of concept for using compiled languages (Go) for exarp modules.

🎯 Project Status

Phase 1: ✅ Complete (Core Structure)
Phase 2: ✅ Complete (Wisdom Data Porting - 16/21 local sources)
Phase 3: ✅ Complete (Advisor System)
Phase 4: ✅ Complete (MCP Protocol Implementation)
Phase 4.5: ✅ Complete (SDK Migration - 2026-01-09)
Phase 6: ✅ Complete (Random Source Selector)
Current Phase: Phase 5 (Consultation Logging)
Language: Go 1.23+
MCP SDK: Official modelcontextprotocol/go-sdk v1.2.0
Type: MCP Server / Developer Tools

📋 Quick Start

# Clone the repository
git clone <repository-url>
cd devwisdom-go

# Build MCP server
make build

# Build CLI
make build-cli

# Run MCP server
make run

# Run CLI commands
./devwisdom-cli quote
./devwisdom-cli consult --metric security --score 75
./devwisdom-cli briefing --days 7

# Run with watchdog (crash monitoring + file watching)
make watchdog

# Test
make test

💻 CLI Usage

The devwisdom CLI provides easy access to wisdom quotes and advisor consultations. The CLI can run in two modes:

• CLI Mode: When run from a terminal (stdin is a TTY)
• MCP Server Mode: When run via stdio (for MCP integration)

Building the CLI

# Build CLI binary
make build-cli

# Build both server and CLI
make build-all

# Install CLI globally
make install-cli

Commands

# Get a random wisdom quote (date-seeded, consistent per day)
devwisdom quote

# Get quote from specific source
devwisdom quote --source stoic

# Get quote with score context (affects aeon level selection)
devwisdom quote --source art_of_war --score 85

# Get quote in JSON format
devwisdom quote --json

# Get quote text only (quiet mode)
devwisdom quote --quiet

# Consult an advisor for a metric
devwisdom consult --metric security --score 40

# Consult an advisor for a tool
devwisdom consult --tool project_scorecard --score 75

# Consult an advisor for a workflow stage
devwisdom consult --stage daily_checkin --score 60

# List all available wisdom sources
devwisdom sources

# List sources in JSON format
devwisdom sources --json

# List all available advisors
devwisdom advisors

# List advisors in JSON format
devwisdom advisors --json

# Get daily briefing (today's wisdom)
devwisdom briefing

# Get briefing for last 7 days
devwisdom briefing --days 7

# Get briefing in JSON format
devwisdom briefing --json

# Show version
devwisdom version

# Show help
devwisdom help

Examples

# Quick daily wisdom
devwisdom quote

# Security advice when score is low
devwisdom consult --metric security --score 25

# Planning stage advice
devwisdom consult --stage planning --score 60

# View all Stoic quotes available
devwisdom sources --json | jq '.[] | select(.name == "stoic")'

# Get quote for high-performing project
devwisdom quote --source pistis_sophia --score 90

# Get quiet quote for scripts
QUOTE=$(devwisdom quote --quiet)
echo "Today: $QUOTE"

Command Options

quote command:

• --source SOURCE: Wisdom source name (e.g., stoic, pistis_sophia, random)
• --score SCORE: Project health score (0-100), affects aeon level selection
• --json: Output in JSON format
• --quiet: Output only the quote text

consult command:

• --metric METRIC: Metric name (e.g., security, testing, documentation)
• --tool TOOL: Tool name (e.g., project_scorecard)
• --stage STAGE: Stage name (e.g., daily_checkin, sprint_planning)
• --score SCORE: Project health score (0-100), required for metric/tool consultations
• --json: Output in JSON format
• --quiet: Output only the quote text

briefing command:

• --days DAYS: Number of days to include (default: 1)
• --json: Output in JSON format

Use Cases

Daily Standup:

# Get today's wisdom for team standup
devwisdom quote

Project Health Monitoring:

# Get advice based on current project score
SCORE=$(calculate-project-score)
devwisdom consult --metric security --score $SCORE

CI/CD Integration:

# Add wisdom to build notifications
QUOTE=$(devwisdom quote --quiet)
echo "Build wisdom: $QUOTE" | send-notification

Documentation Generation:

# Generate markdown with quotes
devwisdom sources --json | jq -r '.[] | "## \(.name)\n\n\(.description)\n"'

📚 For detailed usage examples, see:

• - Comprehensive CLI command examples with output samples
• - MCP server integration examples
• - Go library usage examples
• - All example files and guides

Quick Reference

🐚 Zsh Plugin

Install the zsh plugin for convenient shell integration with tab completion and helper functions.

Installation

Automatic Installation (Recommended)

# From project root
cd zsh
./install.sh

The installation script will:

• Detect your zsh framework (oh-my-zsh or standard zsh)
• Copy plugin files to the appropriate location
• Configure your ~/.zshrc automatically
• Set up tab completion

Manual Installation

For oh-my-zsh users:

# Create plugin directory
mkdir -p ~/.oh-my-zsh/custom/plugins/devwisdom

# Copy plugin files
cp zsh/devwisdom.plugin.zsh ~/.oh-my-zsh/custom/plugins/devwisdom/
cp zsh/_devwisdom ~/.oh-my-zsh/custom/plugins/devwisdom/

# Make completion executable
chmod +x ~/.oh-my-zsh/custom/plugins/devwisdom/_devwisdom

# Add to ~/.zshrc
echo 'plugins=(... devwisdom)' >> ~/.zshrc

For standard zsh users:

# Create plugin directory
mkdir -p ~/.zsh/plugins/devwisdom

# Copy plugin files
cp zsh/devwisdom.plugin.zsh ~/.zsh/plugins/devwisdom/
cp zsh/_devwisdom ~/.zsh/plugins/devwisdom/

# Make completion executable
chmod +x ~/.zsh/plugins/devwisdom/_devwisdom

# Add to ~/.zshrc
cat >> ~/.zshrc << 'EOF'
# devwisdom plugin
source ~/.zsh/plugins/devwisdom/devwisdom.plugin.zsh
fpath=(~/.zsh/plugins/devwisdom $fpath)
autoload -Uz compinit && compinit
EOF

After installation:

# Reload your shell configuration
source ~/.zshrc

Plugin Commands

The zsh plugin provides convenient wrapper functions:

# Show daily wisdom (random source, date-seeded)
devwisdom-daily

# Show daily wisdom from specific source
devwisdom-daily stoic

# Quick quote with optional source and score
devwisdom-quote              # Random quote
devwisdom-quote stoic        # Quote from stoic source
devwisdom-quote stoic 75     # Quote from stoic with score 75

# Consult advisor (metric, tool, or stage)
devwisdom-consult security 40                    # Metric advisor
devwisdom-consult project_scorecard 75          # Tool advisor
devwisdom-consult daily_checkin 60               # Stage advisor

# List available sources
devwisdom-sources

# List available advisors
devwisdom-advisors

# Get daily briefing (default: 1 day)
devwisdom-briefing
devwisdom-briefing 7         # Last 7 days

Tab Completion

The plugin includes full tab completion support:

# Tab completion for commands
devwisdom <TAB>              # Shows: quote, consult, sources, advisors, briefing

# Tab completion for options
devwisdom quote --<TAB>       # Shows: --source, --score, --json, --quiet
devwisdom consult --<TAB>    # Shows: --metric, --tool, --stage, --score, --json, --quiet

Auto-Daily Wisdom

Enable automatic daily wisdom on shell startup:

# Add to ~/.zshrc
export DEVWISDOM_AUTO_DAILY=true

When enabled, you'll see a daily wisdom quote each time you open a new terminal session.

Use Cases

Daily Motivation:

# Add to ~/.zshrc for daily inspiration
devwisdom-daily

Project Health Check:

# Quick consultation when starting work
devwisdom-consult security $(get-project-score)

Script Integration:

#!/bin/zsh
# Get wisdom for automation scripts
QUOTE=$(devwisdom quote --json)
echo "Today's wisdom: $(echo $QUOTE | jq -r '.quote')"

Custom Aliases:

# Add to ~/.zshrc
alias wisdom='devwisdom quote'
alias advice='devwisdom consult'
alias daily='devwisdom-daily'

🔄 Watchdog Script

The project includes a watchdog script that monitors the server for crashes and can automatically reload on file changes.

Basic Usage

# Monitor for crashes only
./watchdog.sh

# Watch files and reload on changes
./watchdog.sh --watch-files

# Watch files and restart on changes
./watchdog.sh --watch-files --restart-on-change

# Log to file
./watchdog.sh --watch-files --log-file watchdog.log

Features

• Crash Detection: Automatically restarts server if it crashes
• File Watching: Monitors sources.json, config files, and Go source files
• Hot Reload: Reloads sources without full restart (if supported)
• Auto Rebuild: Rebuilds binary when Go source files change
• Restart Limits: Configurable maximum restart attempts
• Graceful Shutdown: Handles SIGTERM for clean shutdowns

Watchdog Options

• --watch-files: Enable file watching (uses fswatch on macOS, falls back to polling)
• --restart-on-change: Restart server on file changes (default: reload)
• --log-file PATH: Log output to file
• --pid-file PATH: Custom PID file location
• --max-restarts N: Maximum restart attempts (default: 10)
• --restart-delay SEC: Delay between restarts (default: 2)

Makefile Targets

make watchdog          # Run with file watching and reload
make watchdog-restart  # Run with file watching and restart on change
make watchdog-monitor  # Run with crash monitoring only

Cross-Compilation

Build binaries for multiple platforms:

# Build for specific platform
make build-windows     # Windows (amd64)
make build-linux       # Linux (amd64, arm64)
make build-darwin      # macOS (amd64, arm64)

# Build for all platforms
make build-all-platforms

# Build and package release archives
make build-release     # Creates zip/tar.gz archives in dist/release/

Release Archives:

• Windows: devwisdom-{version}-windows-amd64.zip
• Linux: devwisdom-{version}-linux-{arch}.tar.gz
• macOS: devwisdom-{version}-darwin-{arch}.tar.gz

Build Artifacts:

• Binaries are placed in dist/{platform}-{arch}/
• Release archives are placed in dist/release/
• Use make clean-dist to remove all build artifacts

🔄 CI/CD

Continuous Integration

The project uses GitHub Actions for CI/CD:

• CI Workflow (.github/workflows/ci.yml):

  • Runs on push and pull requests
  • Tests on Go 1.21 and 1.22
  • Runs linting with golangci-lint
  • Builds binaries to verify compilation
  • Uploads test coverage reports

• Release Workflow (.github/workflows/release.yml):

  • Triggers on version tags (e.g., v1.0.0)
  • Builds binaries for all platforms:
    • Windows (amd64)
    • Linux (amd64, arm64)
    • macOS (amd64, arm64)
  • Creates GitHub release with all artifacts
  • Generates release notes automatically

Creating a Release

# Create and push a version tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

The release workflow will automatically:

1. Build binaries for all platforms
2. Package them into release archives
3. Create a GitHub release
4. Attach all artifacts to the release

CI/CD Status

View workflow status and logs:

• CI Workflow
• Release Workflow

🏗️ Project Structure

devwisdom-go/
├── cmd/server/          # MCP server entry point
├── internal/
│   ├── wisdom/         # Wisdom engine (quotes, sources, advisors)
│   ├── mcp/            # MCP protocol handler
│   └── config/         # Configuration management
├── docs/               # Documentation
├── Makefile           # Build commands
└── go.mod             # Go dependencies

📊 Planning & Status

Tasks are tracked in exarp-go (Todo2 SQLite). See PROJECT_GOALS.md for phase breakdown and PRD.md for full requirements.

🚀 Phases

1. ✅ Phase 1: Core Structure (Complete)
2. ✅ Phase 2: Wisdom Data Porting (16/21 local sources complete)
3. ⏳ Phase 3: Advisor System
4. ⏳ Phase 4: MCP Protocol Implementation
5. ⏳ Phase 5: Consultation Logging
6. ✅ Phase 6: Daily Random Source Selection (Complete)
7. ⏳ Phase 7: Optional Features (Sefaria API)
8. ⏳ Phase 8: Testing
9. ⏳ Phase 9: Documentation
10. ⏳ Phase 10: Polish & Deployment

📚 Documentation

Core Documentation

• PROJECT_GOALS.md - Strategic phases and goals
• PRD.md - Product Requirements Document (129 user stories)
• TODO.md - Task breakdown by phase

Reference Documentation

• - Complete documentation index
• docs/WATCHDOG.md - Watchdog script documentation
• docs/PERFORMANCE.md - Performance analysis and benchmarks
• docs/MCP_SERVERS.md - MCP server configuration guide
• docs/CURSOR_EXTENSION.md - Cursor extension architecture (⚠️ Future goal - not currently implemented)

See for complete documentation index.

🔗 Related

• Source: Python wisdom module in exarp project
• MCP Spec: https://modelcontextprotocol.io/
• Go Docs: https://go.dev/doc/effective_go

📝 License

[Add your license here]

👤 Author

Extracted from exarp project as compiled language PoC.