Skip to content

CODEBASE-GUIDE.md

Latest commit

 

History

History
77 lines (62 loc) · 3.51 KB

CODEBASE-GUIDE.md

File metadata and controls

77 lines (62 loc) · 3.51 KB
Raw

Gentle-AI Codebase Guide

This guide helps maintainers find the right code path before changing Gentle-AI. It is an index, not a full API reference.

Who this is for

Reader Use this guide to
New maintainer Build the project mental model before touching files.
Contributor Find the package that owns a behavior.
Reviewer Check whether a PR changes the right layer.
Release helper Verify sync, install, update, and docs boundaries.

90-second mental model

Gentle-AI is a Go CLI/TUI that configures AI coding agents. It installs and syncs managed assets such as SDD prompts, skills, MCP entries, permissions, personas, GGA support, Engram wiring, skill registries, and community tool/plugin helpers.

User
  |
  v
gentle-ai CLI / Bubbletea TUI
  |
  +--> detection + flag normalization
  +--> planner resolves components and dependencies
  +--> pipeline applies adapter/component steps with backups
  +--> verification reports readiness
  |
  v
Agent config roots (~/.claude, ~/.config/opencode, ~/.cursor, ...)
  |
  v
External tools and agents: Engram, Context7, GGA, supported AI CLIs/IDEs

Golden rule: agent-specific paths belong in adapters; reusable behavior belongs in components or shared orchestration packages.

Guide pages

Page Job
Mental model Understand what the project is, is not, and must preserve.
Repository map Find package ownership and placement rules.
Memory core Understand the Engram boundary and what this repo wires vs owns.
Interfaces Compare CLI, MCP, local HTTP API boundary, and TUI surfaces.
Sync and cloud Separate Gentle-AI config sync from Engram memory/cloud sync.
Dashboard Know what dashboard code is absent from this repo and how to avoid inventing it.
Integrations Change agent adapters, plugins, and setup boundaries safely.
Maintainer playbook Use checklists by change type and PR review guardrails.
Reference map Trace docs and source files to responsibilities.

Recommended reading path

  1. Start with Mental model.
  2. Use Repository map before editing code.
  3. Read Interfaces for user-facing changes.
  4. Read the specialized page for your area: memory, sync, dashboard, or integrations.
  5. Finish with Maintainer playbook before opening or reviewing a PR.

Existing references

Page Job
Architecture & Development Short codebase layout and test commands.
Usage User-facing CLI/TUI behavior.
Components Component, preset, and managed asset overview.
Engram Commands Engram user commands and MCP tool overview.
OpenCode SDD Profiles Profile sync details.
Skill Registry Skill indexing and refresh behavior.
Agents Supported agent matrix and config paths.
Rollback Backup, restore, and uninstall safety model.
Platforms Platform support and path notes.
Intended Usage Product scope and expected workflow boundaries.

Next step

Read Mental model next.