✨ Overview

AI coding assistants perform at their highest potential when they share your team's context, architectural habits, and empirical quality standards across every session.

GrooveSkills (@3lineas/grooveskills) equips any repository with a unified AI engineering control plane through two complementary layers:

🎯 How It Works

1. Automatic Project Onboarding & Persistent Memory (.grooveskills/memory/)

The GrooveSkills Harness is installed automatically as the foundation of your project—never an optional checkbox:

• First-Time Setup (Automatic Onboarding): Scans your repository (package manager, real package.json scripts, tsconfig.json path aliases, and src/ modules), asks for your preferred communication language, and populates .grooveskills/memory/context.md, decisions.md, tasks/00-onboarding.md, AGENTS.md, and CLAUDE.md.
• Subsequent Runs (Smart Skill Updates): Detects your existing harness, preserves your memory and language settings untouched, and only updates the skills you select.
• Re-Onboarding on Demand (init): Run npx @3lineas/grooveskills init anytime to re-scan your project stack and refresh the onboarding context.

2. Smart Stack Detection & Lightweight Agent References

GrooveSkills inspects your project manifests (package.json, Cargo.toml, pyproject.toml) to pre-select recommended skills. All canonical skill files live in .grooveskills/skills/<skill>/, while agent folders receive lightweight reference files (~13 lines) that preserve trigger metadata without duplicating trees in your IDE:

• Antigravity: .agents/skills/<skill>/SKILL.md
• Claude Code: .claude/skills/<skill>/SKILL.md
• Gemini Code Assist: .gemini/skills/<skill>/SKILL.md
• Cursor IDE: .cursor/rules/<skill>.mdc

3. Organic & Outcome-Driven Development (ODD) & 3-Lane Workflow

Through the built-in odd-ai and groove-harness skills, GrooveSkills guides your AI assistant with a hybrid Organic & Outcome-Driven Development (ODD) methodology:

• Organic Adaptability: Exploration, documentation, and planning scale proportionally to the complexity of each request—keeping minor tweaks nimble while giving major features solid structure.
• Outcome Accountability: Instead of stopping as soon as code is generated (Output-Driven), the assistant defines a testable Outcome Hypothesis and verifies it with empirical proof (Outcome-Driven).

The 7-Step ODD Lifecycle

1. Authorize (Permission Gate): Evaluates whether your prompt authorizes code modifications. Questions, audits, and reviews remain strictly read-only.
2. Explore Proportionately: Consults .grooveskills/memory/context.md and inspects only the files relevant to the active domain, preserving your token budget and context window.
3. Resolve Uncertainty Early: Answers technical unknowns by reading the codebase and asks concise, thoughtful questions only when product or design decisions are open.
4. Classify Semantic Scope: Routes the request into one of three execution lanes based on architectural impact and reversibility rather than line counts.
5. Track Before First Write & Outcome Hypothesis: Before editing source files on non-trivial tasks, records the plan and a formal hypothesis in .grooveskills/memory/tasks/<slug>.md:

   "By delivering [Output / Technical Change], [Outcome / Verifiable Behavior] will occur, proven by [Evidence / Test / Build Command]."

6. Execute Proportionate Clean Code: Writes clean, modular code following strict typing (zero any), guard clauses (zero nested ifs), direct imports, and <200 lines per file.
7. Verify Against Outcomes (Empirical Receipt): Runs deterministic checks (typecheck, test suite, linter, or build), logs the real output under ## Evidence, and updates ## Next for effortless session continuity.

4. Multilingual, Empathetic UX Communication

Select your preferred language (Español, English, Português, Italiano, or Français) during onboarding so every validation message, toast, and agent interaction remains warm, persuasive, and professional.

🚀 Quick Start

Interactive Wizard (Install or Update Skills)

npx @3lineas/grooveskills

Force Full Project Re-Onboarding (init)

npx @3lineas/grooveskills init

Non-Interactive Mode (CI & Scripting)

# Install skills and initialize harness in Spanish for Claude and Antigravity
npx @3lineas/grooveskills --skills odd-ai best-practices hono --agents antigravity claude -l es -y

# Re-run full project onboarding non-interactively across all AI assistants
npx @3lineas/grooveskills init --agents antigravity claude cursor gemini -l es -y

CLI Options Reference

📂 Project Structure

my-project/
├── .grooveskills/
│   ├── config.json                  # Manifest of active skills, agents, language & harness state
│   ├── skills/                      # Canonical single source of truth for installed skills
│   └── memory/                      # Persistent project memory (Core Harness control plane)
│       ├── context.md               # Auto-scanned stack, scripts, aliases & architecture map
│       ├── decisions.md             # Architecture Decision Records (ADR)
│       └── tasks/                   # 00-onboarding.md & tasks with Outcome Hypotheses
├── .agents/skills/<skill>/SKILL.md  # Lightweight reference pointer -> .grooveskills/skills/<skill>/SKILL.md
├── .claude/skills/<skill>/SKILL.md  # Lightweight reference pointer -> .grooveskills/skills/<skill>/SKILL.md
├── .gemini/skills/<skill>/SKILL.md  # Lightweight reference pointer -> .grooveskills/skills/<skill>/SKILL.md
├── .cursor/rules/<skill>.mdc        # Lightweight reference rule -> .grooveskills/skills/<skill>/SKILL.md
└── AGENTS.md / CLAUDE.md            # Concise harness pointer <!-- grooveskills:harness -->

📦 Skills Catalog

📄 License

Released under the MIT License © 3-Lineas