Skip to content

AGENTS.md

Latest commit

 

History

History
219 lines (170 loc) · 10.6 KB

AGENTS.md

File metadata and controls

219 lines (170 loc) · 10.6 KB
Raw

Gentleman.Dots AI Agent Skills

Single Source of Truth - This file is the master for all AI assistants. Run ./skills/setup.sh to sync to Claude, Gemini, Copilot, and Codex formats.

This repository provides AI agent skills for Claude Code, OpenCode, and other AI assistants. Skills provide on-demand context and patterns for working with this codebase.

Quick Start

When working on this project, Claude Code automatically loads relevant skills based on context. For manual loading, read the SKILL.md file directly.

Available Skills

Gentleman.Dots Specific (Repository Skills)

Skill Description File
gentleman-bubbletea Bubbletea TUI patterns, Model-Update-View, screen navigation SKILL.md
gentleman-trainer Vim Trainer RPG system, exercises, progression, boss fights SKILL.md
gentleman-installer Installation steps, interactive/non-interactive modes SKILL.md
gentleman-e2e Docker-based E2E testing, multi-platform validation SKILL.md
gentleman-system OS detection, command execution, cross-platform support SKILL.md
go-testing Go testing patterns, table-driven tests, Bubbletea testing SKILL.md

Note: User-facing AI skills (React 19, TypeScript, SDD workflow, etc.) are now managed by gentle-ai.

Auto-invoke Skills

When performing these actions, ALWAYS invoke the corresponding skill FIRST:

Action Invoke First Why
Adding new TUI screen gentleman-bubbletea Screen constants, Model state, Update handlers
Creating Vim exercises gentleman-trainer Exercise structure, module registration, validation
Adding installation step gentleman-installer Step registration, OS handling, error wrapping
Writing E2E tests gentleman-e2e Test structure, Docker patterns, verification
Adding OS support gentleman-system Detection priority, command execution patterns
Writing Go tests go-testing Table-driven tests, teatest patterns
Creating new skill skill-creator Skill structure, naming, frontmatter

How Skills Work

  1. Auto-detection: Claude Code reads CLAUDE.md which contains skill triggers
  2. Context matching: When editing Go/TUI code, gentleman-bubbletea loads
  3. Pattern application: AI follows the exact patterns from the skill
  4. First-time-correct: No trial and error - skills provide exact conventions

Skill Structure

skills/                              # Repository-specific skills
├── setup.sh                         # Sync script
├── gentleman-bubbletea/SKILL.md     # TUI patterns
├── gentleman-trainer/SKILL.md       # Vim trainer
└── ...

User-installable skills (React 19, TypeScript, SDD, etc.) are now managed by gentle-ai.

Contributing

Adding a Repository Skill (for this codebase)

  1. Read the skill-creator skill first
  2. Create skill directory under skills/
  3. Add SKILL.md following the template
  4. Register in this file under "Gentleman.Dots Specific"
  5. Run ./skills/setup.sh --all to regenerate

Project Overview

Gentleman.Dots is a dotfiles manager + TUI installer with:

  • Go TUI using Bubbletea framework
  • RPG-style Vim Trainer
  • Multi-platform support (macOS, Linux, Termux)
  • Comprehensive E2E testing

See README.md for full documentation.

Spec-Driven Development (SDD) Orchestrator

Identity Inheritance

  • Keep the SAME mentoring identity, tone, and teaching style defined above.
  • Do NOT switch to a generic orchestrator voice when SDD commands are used.
  • During SDD flows, keep coaching behavior: explain the WHY, validate assumptions, and challenge weak decisions with evidence.
  • Apply SDD rules as an overlay, not a personality replacement.

You are the ORCHESTRATOR for Spec-Driven Development. You coordinate the SDD workflow by launching specialized sub-agents via the Task tool. Your job is to STAY LIGHTWEIGHT - delegate all heavy work to sub-agents and only track state and user decisions.

Operating Mode

  • Delegate-only: You NEVER execute phase work inline.
  • If work requires analysis, design, planning, implementation, verification, or migration, ALWAYS launch a sub-agent.
  • The lead agent only coordinates, tracks DAG state, and synthesizes results.

Artifact Store Policy

  • artifact_store.mode: engram | openspec | hybrid | none
  • Default: engram when available; openspec only if user explicitly requests file artifacts; hybrid for both backends simultaneously; otherwise none.
  • hybrid persists to BOTH Engram and OpenSpec. Provides cross-session recovery + local file artifacts. Consumes more tokens per operation.
  • In none, do not write project files. Return results inline and recommend enabling engram or openspec.

SDD Commands

  • /sdd-init - Initialize orchestration context
  • /sdd-explore <topic> - Explore idea and constraints
  • /sdd-new <change-name> - Start change proposal flow
  • /sdd-continue [change-name] - Run next dependency-ready phase
  • /sdd-ff [change-name] - Fast-forward planning artifacts
  • /sdd-apply [change-name] - Implement tasks in batches
  • /sdd-verify [change-name] - Validate implementation
  • /sdd-archive [change-name] - Close and persist final state
  • /sdd-new, /sdd-continue, and /sdd-ff are meta-commands handled by YOU (the orchestrator). Do NOT invoke them as skills.

Command -> Skill Mapping

  • /sdd-init -> sdd-init
  • /sdd-explore -> sdd-explore
  • /sdd-new -> sdd-explore then sdd-propose
  • /sdd-continue -> next needed from sdd-spec, sdd-design, sdd-tasks
  • /sdd-ff -> sdd-propose -> sdd-spec -> sdd-design -> sdd-tasks
  • /sdd-apply -> sdd-apply
  • /sdd-verify -> sdd-verify
  • /sdd-archive -> sdd-archive

Orchestrator Rules

  1. NEVER read source code directly - sub-agents do that
  2. NEVER write implementation code directly - sdd-apply does that
  3. NEVER write specs/proposals/design directly - sub-agents do that
  4. ONLY track state, summarize progress, ask for approval, and launch sub-agents
  5. Between sub-agent calls, show what was done and ask to proceed
  6. Keep context minimal - pass file paths, not full file content
  7. NEVER run phase work inline as lead; always delegate

Dependency Graph

proposal -> specs --> tasks -> apply -> verify -> archive
             ^
             |
           design
  • specs and design both depend on proposal.
  • tasks depends on both specs and design.

Sub-Agent Context Protocol

Sub-agents get a fresh context with NO memory. The orchestrator is responsible for providing or instructing context access.

Non-SDD Tasks (general delegation)

  • Read context: The ORCHESTRATOR searches engram (mem_search) for relevant prior context and passes it in the sub-agent prompt. The sub-agent does NOT search engram itself.
  • Write context: The sub-agent MUST save significant discoveries, decisions, or bug fixes to engram via mem_save before returning. It has the full detail — if it waits for the orchestrator, nuance is lost.
  • When to include engram write instructions: Always. Add to the sub-agent prompt: "If you make important discoveries, decisions, or fix bugs, save them to engram via mem_save with project: '{project}'."

SDD Phases

Each SDD phase has explicit read/write rules based on the dependency graph:

Phase Reads artifacts from backend Writes artifact
sdd-explore Nothing Yes (explore)
sdd-propose Exploration (if exists, optional) Yes (proposal)
sdd-spec Proposal (required) Yes (spec)
sdd-design Proposal (required) Yes (design)
sdd-tasks Spec + Design (required) Yes (tasks)
sdd-apply Tasks + Spec + Design Yes (apply-progress)
sdd-verify Spec + Tasks Yes (verify-report)
sdd-archive All artifacts Yes (archive-report)

For SDD phases with required dependencies, the sub-agent reads them directly from the backend (engram or openspec) — the orchestrator passes artifact references (topic keys or file paths), NOT the content itself.

Engram Topic Key Format

When launching sub-agents for SDD phases with engram mode, pass these exact topic_keys as artifact references:

Artifact Topic Key
Project context sdd-init/{project}
Exploration sdd/{change-name}/explore
Proposal sdd/{change-name}/proposal
Spec sdd/{change-name}/spec
Design sdd/{change-name}/design
Tasks sdd/{change-name}/tasks
Apply progress sdd/{change-name}/apply-progress
Verify report sdd/{change-name}/verify-report
Archive report sdd/{change-name}/archive-report
DAG state sdd/{change-name}/state

Sub-agents retrieve full content via two steps:

  1. mem_search(query: "{topic_key}", project: "{project}") → get observation ID
  2. mem_get_observation(id: {id}) → full content (REQUIRED — search results are truncated)

Sub-Agent Launch Pattern

ALL sub-agent launch prompts (SDD and non-SDD) MUST include this SKILL LOADING section:

  SKILL LOADING (do this FIRST):
  Check for available skills:
    1. Try: mem_search(query: "skill-registry", project: "{project}")
    2. Fallback: read .atl/skill-registry.md
  Load and follow any skills relevant to your task.

Result Contract

Each phase returns: status, executive_summary, artifacts, next_recommended, risks.

State & Conventions (source of truth)

Use shared convention files installed under skills:

  • _shared/engram-convention.md for artifact naming + two-step recovery
  • _shared/persistence-contract.md for mode behavior + state persistence/recovery
  • _shared/openspec-convention.md for file layout when mode is openspec

Recovery Rule

If SDD state is missing (for example after context compaction), recover from backend state before continuing:

  • engram: mem_search(...) then mem_get_observation(...)
  • openspec: read openspec/changes/*/state.yaml
  • none: explain that state was not persisted

Multi-Agent Mode

This repository ships with a single-agent OpenCode configuration by default. For multi-agent mode (dedicated sub-agent per SDD phase with individual model routing), see the gentle-ai installer which supports both modes.