repository·main·Indexed 26 days ago
https://github.com/gentleman-programming/gentle-aiAn ecosystem configurator that enhances AI coding agents (such as Claude Code, Cursor, Windsurf, and OpenCode) with persistent memory via Engram, Spec-Driven Development (SDD), curated skills, MCP servers, and model routing. It transforms chatbots into teaching-oriented development partners by providing a structured AI development layer, including tools for review-driven development (RDD) and project context registration.
Gentle-AI is an ecosystem configurator for AI coding agents. It does not install agents itself; instead, it equips existing agents (like Claude Code, Cursor, or Windsurf) with:
The gentle-ai ecosystem consists of several core components that enhance AI agent capabilities:
engram): Persistent cross-session memory via MCP (auto-detects project name, full-text search, git sync).sdd): Spec-Driven Development workflow (10 phases).skills): A curated library of coding skills.context7): MCP server for live framework/library documentation.persona): Managed Gentleman/neutral persona injection.permissions): Security guardrails for Claude Code and OpenCode. Default sensitive-paths deny list includes: ~/.ssh/*, **/*.pem, **/*.key, **/.env*, ~/.credentials/*, ~/.aws/credentials, ~/.config/gh/hosts.yml, ~/Library/Keychains/*, **/secrets/*, **/*.p12, **/*.pfx.gga): Gentleman Guardian Angel (AI provider switcher).theme): Gentleman Kanagawa theme overlay.Gentle-AI provides three primary interaction interfaces:
Note: This repository does not currently expose a local HTTP API.
The Gentleman AI Installer is an ecosystem configurator designed to supercharge AI coding agents (such as Claude Code, OpenCode, Cursor, VSCode, Gemini CLI, etc.). Instead of just installing the agents, it injects the 'Gentleman stack' into your existing tools to provide a professional-grade development environment.
Key features injected into your agents include:
The review-findings-ledger capability has been modified to provide more robust error handling and lifecycle management. Key improvements include:
authority_corrupted or operation_outcome_unknown, the system now uses typed sentinels to surface the actual cause of failures.validateCompactRecoveryEdge.git common-dir with ENOTSUP fallbacks for unsupported platforms.The _shared directory serves as a support package containing shared SDD (Software Development Documentation) reference documents. These documents (e.g., sdd-phase-common.md, persistence-contract.md) are intended to be consumed by actual SDD skills to provide consistent context and contracts.
Important: The _shared package is not an invokable skill. It cannot be called directly by a user or an agent; it exists solely to provide reference material for other installed skills.
The system implements specific safety and authority mechanisms:
off-only override.Doctor.Pre-upgrade and pre-sync snapshots only cover agents listed in ~/.gentle-ai/state.json (state.InstalledAgents). Configuration directories for agents installed outside of gentle-ai are not included in the snapshot.
existed=false, they are removed during restore to revert the state.Rollbacks only handle configuration files. They do not uninstall system packages. If you need to undo a package installation, use your platform's package manager:
brew uninstall <package>sudo apt-get remove <package>sudo pacman -R <package>The Agent Builder is a sub-system within Gentle AI designed to create custom sub-agents. It consists of four main layers:
Builder orchestrator, PromptComposer, OutputParser, and a Custom Agent Registry.GenerationEngine interface to wrap various CLI tools (e.g., Claude Code, OpenCode, Gemini, Codex) to generate skill content.SKILL.md files into agent directories, updates the custom-agents.json registry, and manages SDD (Software Design Document) integration by modifying system prompts.The Organic Agent Routing Projection defines provider-neutral instructions that map Gentle AI's canonical implementation-routing facts into supported adapters. It helps an orchestrator select the most efficient implementation topology (e.g., direct_inline, delegated_direct, or sdd).
Key distinction: The projection provides guidance for choosing a topology but does not own runtime route admission, verification, review, delivery, or lifecycle transitions.
Hermes (Nous Research) is supported as a TierFull agent. Unlike other agents that may use workspace-first routing, Hermes configuration is global only, residing in ~/.hermes/.
Key integration details:
~/.hermes/config.yaml. MCP servers are defined under the mcp_servers: key.~/.hermes/SOUL.md, which acts as 'slot #1' of the Hermes system prompt.StrategyMergeIntoYAML to idempotently inject context7 and engram MCP servers into the global config without destroying user comments or content.generic/persona-gentleman.md and generic/persona-neutral.md, with skill-loading blocks rewritten to match Hermes's native skill model (loading from ~/.hermes/skills/).The Gentle AI architecture is organized into nine mutually exclusive contexts. Each context has specific responsibilities, sources of truth, and prohibited actions. Use this taxonomy to identify which domain package should handle a specific task (e.g., filesystem changes belong to MMI, while host/process observation belongs to HCR).
| Code | Canonical context | Depends on |
|---|---|---|
HCR | host-install-command-runtime | — |
PAD | product-admission-and-delivery | — |
MMI | managed-mutation-integrity | HCR |
ACI | agent-capability-and-instruction-projection | HCR |
RAR | review-authority-and-receipts | HCR |
MCA | model-catalog-and-assignment | ACI |
EPD | evidence-policy-and-diagnostics | RAR, HCR |
DSR | desired-state-resource-reconciliation | MMI, ACI, HCR |
SDD | sdd-lifecycle-and-artifacts | RAR, EPD, MMI, ACI |