Configurador

Imported from HecAguilaV/SymbiOSis (Ecosistema/Configurador/AGENTS.md). Install upstream with npx skills add HecAguilaV/SymbiOSis --skill Configurador. Copyright stays with the author.

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)

Generic Skills (User Installation → ~/.claude/skills/)

These skills are copied to user's Claude/OpenCode config via the installer.

Auto-invoke Skills

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

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
└── ...

GentlemanClaude/skills/              # User-installable skills
├── react-19/SKILL.md                # Copied to ~/.claude/skills/
├── typescript/SKILL.md
└── ...

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

Adding a User Skill (for Claude/OpenCode users)

1. Create skill directory under GentlemanClaude/skills/
2. Add SKILL.md following the template
3. Register in this file under "Generic Skills"
4. The installer will copy it to user's config

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:

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:

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.