@3lineas/grooveskills 1.4.0 → 1.6.0

package/dist/{chunk-FN4OEDVV.js → chunk-HUG3MG3P.js}

@@ -70,7 +70,8 @@ var SKILL_CATALOG = [
     name: "GrooveSkills Harness",
     description: "Lightweight project harness, context memory, and ODD 3-lane task execution (Answer, Task, Spec) for AI coding agents",
     dependencies: [],
-    directoryName: "groove-harness"
+    directoryName: "groove-harness",
+    isCoreHarness: true
   },
   {
     id: "odd-ai",
@@ -135,6 +136,55 @@ var SKILL_CATALOG = [
     dependencies: [],
     directoryName: "clean-architecture-ddd"
   },
+  {
+    id: "external-service-adapters",
+    name: "External Service Adapters & Wrappers",
+    description: "Standardized adapter and wrapper architecture for external services (payment gateways, emails, SMS, cloud storage)",
+    dependencies: [],
+    directoryName: "external-service-adapters"
+  },
+  {
+    id: "storage-file-adapters",
+    name: "Storage & File Adapters (S3, R2, Supabase)",
+    description: "Standardized wrapper & adapter architecture for object storage, uploads, presigned URLs, and streaming without repositories",
+    dependencies: [],
+    directoryName: "storage-file-adapters"
+  },
+  {
+    id: "auth-rbac-policies",
+    name: "Auth Adapters & RBAC/ABAC Policies",
+    description: "Authentication adapter architecture and pure domain authorization policies (RBAC/ABAC) with AuthenticatedActor contract",
+    dependencies: [],
+    directoryName: "auth-rbac-policies"
+  },
+  {
+    id: "controller-orchestration-queues",
+    name: "Controller Orchestration & Queue Adapters",
+    description: "Strict orchestration rules for Controllers, atomic Actions, DB Transactions, and background Queue Adapters (Cloudflare, BullMQ, SQS)",
+    dependencies: [],
+    directoryName: "controller-orchestration-queues"
+  },
+  {
+    id: "webhook-idempotency",
+    name: "Webhook Verifiers & Idempotency Guards",
+    description: "Incoming webhook HMAC verification adapters and atomic idempotency guards guaranteeing at-most-once processing",
+    dependencies: [],
+    directoryName: "webhook-idempotency"
+  },
+  {
+    id: "caching-rate-limiting",
+    name: "Cache-Aside & Rate Limiting Adapters",
+    description: "Cache-aside remember wrapper and interchangeable sliding-window rate limiter adapters (Redis, Cloudflare KV, In-Memory)",
+    dependencies: [],
+    directoryName: "caching-rate-limiting"
+  },
+  {
+    id: "env-feature-flags",
+    name: "Fail-Fast Env & Feature Flags Adapters",
+    description: "Fail-fast environment schema validation with Valibot and decoupled feature flags adapters (PostHog, LaunchDarkly, Unleash)",
+    dependencies: [],
+    directoryName: "env-feature-flags"
+  },
   {
     id: "testing-vitest",
     name: "Vitest Testing Standards",
@@ -194,7 +244,14 @@ function detectProjectContext(targetPath) {
     "best-practices",
     "ux-writing",
     "error-handling-logging",
-    "clean-architecture-ddd"
+    "clean-architecture-ddd",
+    "external-service-adapters",
+    "storage-file-adapters",
+    "auth-rbac-policies",
+    "controller-orchestration-queues",
+    "webhook-idempotency",
+    "caching-rate-limiting",
+    "env-feature-flags"
   ];
   for (const skill of SKILL_CATALOG) {
     if (skill.dependencies.length === 0) {
@@ -220,7 +277,7 @@ function detectProjectContext(targetPath) {
 
 // src/domains/ui/ui-orchestrator.ts
 import * as p5 from "@clack/prompts";
-import pc2 from "picocolors";
+import pc3 from "picocolors";
 
 // src/domains/ui/banners.ts
 import pc from "picocolors";
@@ -235,7 +292,8 @@ function renderBanner() {
 // src/domains/ui/prompt-skills.ts
 import * as p from "@clack/prompts";
 async function promptSkills(suggestedSkillIds) {
-  const options = SKILL_CATALOG.map((skill) => {
+  const selectableSkills = SKILL_CATALOG.filter((skill) => !skill.isCoreHarness);
+  const options = selectableSkills.map((skill) => {
     const isSuggested = suggestedSkillIds.includes(skill.id);
     return {
       value: skill.id,
@@ -321,7 +379,7 @@ function verifySkillExists(targetPath, skillDirectoryName, agents) {
 }
 
 // src/domains/installer/install-orchestrator.ts
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 
 // src/domains/adapters/skill-reference-builder.ts
 import { existsSync as existsSync3, lstatSync as lstatSync2, mkdirSync, readFileSync as readFileSync3, rmSync, unlinkSync, writeFileSync } from "fs";
@@ -547,8 +605,8 @@ function syncProjectStore(targetPath, selectedSkillIds, _selectedAgents) {
 }
 
 // src/domains/harness/install-harness.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join10 } from "path";
 
 // src/domains/harness/harness-languages.ts
 var SUPPORTED_LANGUAGES = {
@@ -556,58 +614,98 @@ var SUPPORTED_LANGUAGES = {
     code: "es",
     name: "Spanish",
     nativeName: "Espa\xF1ol",
-    instruction: "Todos los mensajes, validaciones, errores, CTAs y comunicaciones con el usuario deben redactarse estrictamente en Espa\xF1ol. El tono debe ser emp\xE1tico, amable, persuasivo y profesional."
+    instruction: "Todos los mensajes, validaciones, errores, CTAs y comunicaciones con el usuario deben redactarse estrictamente en Espa\xF1ol. El tono debe ser emp\xE1tico, amable, persuasivo y profesional.",
+    onboardingPromptTitle: "Prompt de inicializaci\xF3n para tu Agente IA (Copia y pega en el chat):",
+    onboardingPrompt: "Hola. Acabo de configurar GrooveSkills Harness en este proyecto. Por favor lee `.grooveskills/memory/tasks/00-onboarding.md`, `.grooveskills/memory/context.md` y las skills instaladas en `.agents/skills/`. Hazme preguntas interactivas paso a paso para detectar vac\xEDos de arquitectura, aclarar objetivos y adaptar el proyecto a mis necesidades antes de continuar."
   },
   en: {
     code: "en",
     name: "English",
     nativeName: "English",
-    instruction: "All user-facing messages, form validations, errors, CTAs, and notifications must be written strictly in English. Tone must be empathetic, friendly, persuasive, and professional."
+    instruction: "All user-facing messages, form validations, errors, CTAs, and notifications must be written strictly in English. Tone must be empathetic, friendly, persuasive, and professional.",
+    onboardingPromptTitle: "Initialization prompt for your AI Agent (Copy and paste into your chat):",
+    onboardingPrompt: "Hello. I just configured GrooveSkills Harness in this project. Please review `.grooveskills/memory/tasks/00-onboarding.md`, `.grooveskills/memory/context.md`, and the skills installed in `.agents/skills/`. Ask me step-by-step interactive questions to identify architectural gaps, clarify priorities, and adapt the project to my needs before continuing."
   },
   pt: {
     code: "pt",
     name: "Portuguese",
     nativeName: "Portugu\xEAs",
-    instruction: "Todas as mensagens, valida\xE7\xF5es, erros, CTAs e comunica\xE7\xF5es voltadas para o usu\xE1rio devem ser redigidas estritamente em Portugu\xEAs. O tom deve ser emp\xE1tico, amig\xE1vel, persuasivo e profissional."
+    instruction: "Todas as mensagens, valida\xE7\xF5es, erros, CTAs e comunica\xE7\xF5es voltadas para o usu\xE1rio devem ser redigidas estritamente em Portugu\xEAs. O tom deve ser emp\xE1tico, amig\xE1vel, persuasivo e profissional.",
+    onboardingPromptTitle: "Prompt de inicializa\xE7\xE3o para o seu Agente de IA (Copie e cole no chat):",
+    onboardingPrompt: "Ol\xE1. Acabei de configurar o GrooveSkills Harness neste projeto. Por favor leia `.grooveskills/memory/tasks/00-onboarding.md`, `.grooveskills/memory/context.md` e as skills instaladas em `.agents/skills/`. Fa\xE7a-me perguntas interativas passo a passo para mapear lacunas de arquitetura, alinhar prioridades e adaptar o projeto \xE0s minhas necessidades antes de prosseguir."
   },
   it: {
     code: "it",
     name: "Italian",
     nativeName: "Italiano",
-    instruction: "Tutti i messaggi, le convalide, gli errori, i pulsanti/CTA e le comunicazioni rivolte all'utente devono essere scritti rigorosamente in Italiano. Il tono deve essere empatico, cordiale, persuasivo e professionale."
+    instruction: "Tutti i messaggi, le convalide, gli errori, i pulsanti/CTA e le comunicazioni rivolte all'utente devono essere scritti rigorosamente in Italiano. Il tono deve essere empatico, cordiale, persuasivo e professionale.",
+    onboardingPromptTitle: "Prompt di inizializzazione per il tuo Agente AI (Copia e incolla nella chat):",
+    onboardingPrompt: "Ciao. Ho appena configurato GrooveSkills Harness in questo progetto. Ti prego di leggere `.grooveskills/memory/tasks/00-onboarding.md`, `.grooveskills/memory/context.md` e le skills installate in `.agents/skills/`. Fammi domande interattive passo dopo passo per identificare lacune architetturali, allineare le priorit\xE0 e adattare il progetto alle mie esigenze prima di continuare."
   },
   fr: {
     code: "fr",
     name: "French",
     nativeName: "Fran\xE7ais",
-    instruction: "Tous les messages, validations, erreurs, boutons d'appel \xE0 l'action (CTA) et notifications destin\xE9s \xE0 l'utilisateur doivent \xEAtre r\xE9dig\xE9s strictement en Fran\xE7ais. Le ton doit \xEAtre empathique, courtois, persuasif et professionnel."
+    instruction: "Tous les messages, validations, erreurs, boutons d'appel \xE0 l'action (CTA) et notifications destin\xE9s \xE0 l'utilisateur doivent \xEAtre r\xE9dig\xE9s strictement en Fran\xE7ais. Le ton doit \xEAtre empathique, courtois, persuasif et professionnel.",
+    onboardingPromptTitle: "Prompt d'initialisation pour votre Agent IA (Copiez et collez dans le chat) :",
+    onboardingPrompt: "Bonjour. Je viens de configurer GrooveSkills Harness sur ce projet. Veuillez consulter `.grooveskills/memory/tasks/00-onboarding.md`, `.grooveskills/memory/context.md` et les skills install\xE9es dans `.agents/skills/`. Posez-moi des questions interactives \xE9tape par \xE9tape pour identifier les lacunes d'architecture, pr\xE9ciser les priorit\xE9s et adapter le projet \xE0 mes besoins avant de continuer."
   }
 };
 
 // src/domains/harness/harness-templates.ts
-function buildContextTemplate(detectedDependencies, language = "es") {
+function buildContextTemplate(detectedDependencies, language = "es", profile) {
   const depsFormatted = detectedDependencies.length > 0 ? detectedDependencies.map((d) => `- \`${d}\``).join("\n") : "- (No external dependencies detected)";
   const langConfig = SUPPORTED_LANGUAGES[language];
-  return `# Project Context & Architecture
+  const projectName = profile?.projectName ?? "Project";
+  const pkgManager = profile?.packageManager ?? "npm";
+  const commandLines = [];
+  if (profile?.commands) {
+    for (const [key, cmd] of Object.entries(profile.commands)) {
+      commandLines.push(`- **${key}**: \`${cmd}\``);
+    }
+  }
+  const commandsSection = commandLines.length > 0 ? commandLines.join("\n") : `- Build: Refer to \`package.json\` scripts.
+- Typecheck: Refer to TypeScript configuration.
+- Tests: Refer to test runner configuration.`;
+  const aliasLines = [];
+  if (profile?.pathAliases) {
+    for (const [alias, target] of Object.entries(profile.pathAliases)) {
+      aliasLines.push(`- \`${alias}\` -> \`${target}\``);
+    }
+  }
+  const aliasesSection = aliasLines.length > 0 ? `
+### Path Aliases
+${aliasLines.join("\n")}
+` : "";
+  const dirLines = [];
+  if (profile?.sourceDirectories && profile.sourceDirectories.length > 0) {
+    for (const dir of profile.sourceDirectories) {
+      dirLines.push(`- \`${dir}/\``);
+    }
+  }
+  const dirsSection = dirLines.length > 0 ? `
+### Source Modules
+${dirLines.join("\n")}
+` : "";
+  return `# Project Context & Architecture: ${projectName}
 
 This file provides AI agents with instant architectural orientation for this project.
 
 ## 1. Stack & Dependencies
+- **Package Manager**: \`${pkgManager}\`
 ${depsFormatted}
 
 ## 2. Directory Structure Conventions
 - Follow single-responsibility per file (<200 lines).
 - Maintain direct imports with path aliases; avoid barrel files.
 - Keep domain boundaries explicit and clean.
-
+${aliasesSection}${dirsSection}
 ## 3. Communication & User Copy Language
 - **Configured Language**: ${langConfig.nativeName} (\`${language}\`).
 - **Policy**: ${langConfig.instruction}
 
 ## 4. Essential Commands
-- Build: Refer to \`package.json\` scripts.
-- Typecheck: Refer to TypeScript configuration.
-- Tests: Refer to test runner configuration.
+${commandsSection}
 `;
 }
 function buildDecisionsTemplate(language = "es") {
@@ -622,6 +720,38 @@ An append-only log of significant technical and architectural choices.
 | ${now} | Adopt GrooveSkills Harness | Initialized \`.grooveskills/\` control plane with ODD | Clean, encapsulated agent memory, 3-lane ODD flow, and ${langConfig.nativeName} copy standard |
 `;
 }
+function buildOnboardingTaskTemplate(projectName = "Project") {
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  return `---
+status: pending
+createdAt: ${now}
+---
+
+# 00 \u2014 Initial Project Onboarding & Architecture Exploration: ${projectName}
+
+## Outcome Hypothesis
+By scanning dependencies, entry points, configuration manifests, and module layout, the AI agent will gain a verified architectural understanding of \`${projectName}\`, proven by filling out \`.grooveskills/memory/context.md\`, formulating interactive alignment questions with the user, and validating the essential build/typecheck commands.
+
+## Scope
+- In scope: Inspect project manifests, entry points, directory conventions, ask interactive alignment questions, and verify script execution.
+- Out of scope: Refactoring business logic or modifying functional code before alignment.
+
+## Checklist
+- [ ] Verify package manager and essential scripts (\`build\`, \`test\`, \`typecheck\`).
+- [ ] Map high-level module architecture and data flow in \`.grooveskills/memory/context.md\`.
+- [ ] Ask the user step-by-step interactive questions to clarify goals, domain scope, and adapt project conventions.
+- [ ] Document agreed technical decisions in \`.grooveskills/memory/decisions.md\`.
+- [ ] Verify test runner or static checks pass cleanly.
+- [ ] Switch status to \`completed\` once project context is fully verified.
+
+## Evidence
+- Observed command runs and outputs during the initial onboarding pass.
+- User answers to alignment questions captured in memory.
+
+## Next
+- Once onboarding is marked completed, proceed with domain tasks following the 3-lane ODD protocol.
+`;
+}
 function buildTaskTemplate() {
   return `---
 status: in-progress
@@ -657,6 +787,7 @@ function buildAgentHarnessBlock(language = "es") {
 This project uses the **GrooveSkills Harness** located in \`.grooveskills/\`.
 
 ## 1. Three-Lane ODD Protocol
+- **Onboarding Check**: If \`.grooveskills/memory/tasks/00-onboarding.md\` has \`status: pending\`, complete its checklist to enrich \`context.md\` and set its status to \`completed\`.
 - **Authorize & Explore**: Follow the 7-step ODD protocol (Authorize, Explore, Resolve, Classify, Track & Hypothesize, Execute, Verify).
 - **Lane 1 (Answer)**: Explanations, audits, or questions. Read-only; write zero code.
 - **Lane 2 (Task)**: Direct implementation. Declare Outcome Hypothesis and checklist in \`.grooveskills/memory/tasks/<slug>.md\`. Only check off tasks with observed evidence under \`Evidence\`.
@@ -673,19 +804,162 @@ This project uses the **GrooveSkills Harness** located in \`.grooveskills/\`.
 <!-- grooveskills:harness:end -->`;
 }
 
+// src/domains/harness/scan-project-onboarding.ts
+import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
+import { basename, join as join8 } from "path";
+function detectProjectName(targetPath) {
+  const packageJsonPath = join8(targetPath, "package.json");
+  if (existsSync6(packageJsonPath)) {
+    try {
+      const raw = readFileSync4(packageJsonPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (typeof parsed.name === "string" && parsed.name.trim().length > 0) {
+        return parsed.name.trim();
+      }
+    } catch {
+    }
+  }
+  const cargoPath = join8(targetPath, "Cargo.toml");
+  if (existsSync6(cargoPath)) {
+    try {
+      const cargoRaw = readFileSync4(cargoPath, "utf-8");
+      const nameMatch = cargoRaw.match(/name\s*=\s*"([^"]+)"/);
+      if (nameMatch?.[1]) {
+        return nameMatch[1];
+      }
+    } catch {
+    }
+  }
+  const pyprojectPath = join8(targetPath, "pyproject.toml");
+  if (existsSync6(pyprojectPath)) {
+    try {
+      const pyRaw = readFileSync4(pyprojectPath, "utf-8");
+      const pyMatch = pyRaw.match(/name\s*=\s*"([^"]+)"/);
+      if (pyMatch?.[1]) {
+        return pyMatch[1];
+      }
+    } catch {
+    }
+  }
+  return basename(targetPath) || "project";
+}
+function detectPackageManager(targetPath) {
+  if (existsSync6(join8(targetPath, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (existsSync6(join8(targetPath, "bun.lockb")) || existsSync6(join8(targetPath, "bun.lock"))) {
+    return "bun";
+  }
+  if (existsSync6(join8(targetPath, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (existsSync6(join8(targetPath, "package-lock.json"))) {
+    return "npm";
+  }
+  if (existsSync6(join8(targetPath, "Cargo.lock")) || existsSync6(join8(targetPath, "Cargo.toml"))) {
+    return "cargo";
+  }
+  if (existsSync6(join8(targetPath, "uv.lock"))) {
+    return "uv";
+  }
+  if (existsSync6(join8(targetPath, "poetry.lock"))) {
+    return "poetry";
+  }
+  return "npm";
+}
+function detectCommands(targetPath, pkgManager) {
+  const packageJsonPath = join8(targetPath, "package.json");
+  if (!existsSync6(packageJsonPath)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync4(packageJsonPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const scripts = parsed.scripts ?? {};
+    const commands = {};
+    const runner = pkgManager === "npm" ? "npm run" : pkgManager;
+    if (scripts.build) {
+      commands.build = `${runner} build`;
+    }
+    if (scripts["check-types"]) {
+      commands.typecheck = `${runner} check-types`;
+    } else if (scripts.typecheck) {
+      commands.typecheck = `${runner} typecheck`;
+    } else if (scripts.tsc) {
+      commands.typecheck = `${runner} tsc`;
+    }
+    if (scripts.test) {
+      commands.test = `${runner} test`;
+    }
+    if (scripts.lint) {
+      commands.lint = `${runner} lint`;
+    }
+    if (scripts.dev) {
+      commands.dev = `${runner} dev`;
+    }
+    return commands;
+  } catch {
+    return {};
+  }
+}
+function detectPathAliases(targetPath) {
+  const tsconfigPath = join8(targetPath, "tsconfig.json");
+  if (!existsSync6(tsconfigPath)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync4(tsconfigPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const paths = parsed.compilerOptions?.paths ?? {};
+    const aliases = {};
+    for (const [key, targets] of Object.entries(paths)) {
+      if (Array.isArray(targets) && typeof targets[0] === "string") {
+        aliases[key] = targets[0];
+      }
+    }
+    return aliases;
+  } catch {
+    return {};
+  }
+}
+function detectSourceDirectories(targetPath) {
+  const srcPath = join8(targetPath, "src");
+  const scanTarget = existsSync6(srcPath) ? srcPath : targetPath;
+  try {
+    const entries = readdirSync2(scanTarget, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => !name.startsWith(".") && name !== "node_modules" && name !== "dist");
+  } catch {
+    return [];
+  }
+}
+function scanProjectOnboarding(targetPath) {
+  const projectName = detectProjectName(targetPath);
+  const packageManager = detectPackageManager(targetPath);
+  const commands = detectCommands(targetPath, packageManager);
+  const pathAliases = detectPathAliases(targetPath);
+  const sourceDirectories = detectSourceDirectories(targetPath);
+  return {
+    projectName,
+    packageManager,
+    commands,
+    pathAliases,
+    sourceDirectories
+  };
+}
+
 // src/domains/harness/upsert-agent-instructions.ts
-import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { join as join9 } from "path";
 var START_MARKER = "<!-- grooveskills:harness:start -->";
 var END_MARKER = "<!-- grooveskills:harness:end -->";
 function applyHarnessBlock(filePath, language = "es") {
   const block = buildAgentHarnessBlock(language);
-  if (!existsSync6(filePath)) {
+  if (!existsSync7(filePath)) {
     writeFileSync2(filePath, `${block}
 `, "utf-8");
     return;
   }
-  const existingContent = readFileSync4(filePath, "utf-8");
+  const existingContent = readFileSync5(filePath, "utf-8");
   if (existingContent.includes(START_MARKER) && existingContent.includes(END_MARKER)) {
     const regex = new RegExp(`${START_MARKER}[\\s\\S]*?${END_MARKER}`, "g");
     const updated = existingContent.replace(regex, block);
@@ -698,11 +972,11 @@ function applyHarnessBlock(filePath, language = "es") {
 }
 function upsertAgentInstructions(targetPath, selectedAgents, language = "es") {
   const updatedFiles = [];
-  const agentsMdPath = join8(targetPath, "AGENTS.md");
+  const agentsMdPath = join9(targetPath, "AGENTS.md");
   applyHarnessBlock(agentsMdPath, language);
   updatedFiles.push(agentsMdPath);
   if (selectedAgents.includes("claude")) {
-    const claudeMdPath = join8(targetPath, "CLAUDE.md");
+    const claudeMdPath = join9(targetPath, "CLAUDE.md");
     applyHarnessBlock(claudeMdPath, language);
     updatedFiles.push(claudeMdPath);
   }
@@ -714,43 +988,65 @@ function installHarness(options) {
   const memoryDir = getProjectMemoryDir(options.targetPath);
   const tasksDir = getProjectTasksDir(options.targetPath);
   const language = options.language ?? "es";
-  if (!existsSync7(tasksDir)) {
+  const forceOnboarding = Boolean(options.forceOnboarding);
+  if (!existsSync8(tasksDir)) {
     mkdirSync3(tasksDir, { recursive: true });
   }
   const createdFiles = [];
-  const contextPath = join9(memoryDir, "context.md");
-  if (!existsSync7(contextPath)) {
-    writeFileSync3(contextPath, buildContextTemplate(options.detectedDependencies, language), "utf-8");
+  const contextPath = join10(memoryDir, "context.md");
+  const shouldWriteContext = !existsSync8(contextPath) || forceOnboarding;
+  if (shouldWriteContext) {
+    const profile = scanProjectOnboarding(options.targetPath);
+    const contextContent = buildContextTemplate(
+      options.detectedDependencies,
+      language,
+      profile
+    );
+    writeFileSync3(contextPath, contextContent, "utf-8");
     createdFiles.push(contextPath);
+    const onboardingTaskPath = join10(tasksDir, "00-onboarding.md");
+    writeFileSync3(
+      onboardingTaskPath,
+      buildOnboardingTaskTemplate(profile.projectName),
+      "utf-8"
+    );
+    createdFiles.push(onboardingTaskPath);
   }
-  const decisionsPath = join9(memoryDir, "decisions.md");
-  if (!existsSync7(decisionsPath)) {
+  const decisionsPath = join10(memoryDir, "decisions.md");
+  if (!existsSync8(decisionsPath)) {
     writeFileSync3(decisionsPath, buildDecisionsTemplate(language), "utf-8");
     createdFiles.push(decisionsPath);
   }
-  const templateTaskPath = join9(tasksDir, "_template.md");
-  if (!existsSync7(templateTaskPath)) {
+  const templateTaskPath = join10(tasksDir, "_template.md");
+  if (!existsSync8(templateTaskPath)) {
     writeFileSync3(templateTaskPath, buildTaskTemplate(), "utf-8");
     createdFiles.push(templateTaskPath);
   }
-  const instructions = upsertAgentInstructions(options.targetPath, options.selectedAgents, language);
+  const instructions = upsertAgentInstructions(
+    options.targetPath,
+    options.selectedAgents,
+    language
+  );
   createdFiles.push(...instructions);
-  return createdFiles;
+  return {
+    createdFiles,
+    onboardingInitialized: shouldWriteContext
+  };
 }
 
 // src/domains/harness/write-project-config.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
 function readExistingConfig(configPath) {
   const fallback = {
     skills: [],
     agents: [],
     harness: false
   };
-  if (!existsSync8(configPath)) {
+  if (!existsSync9(configPath)) {
     return fallback;
   }
   try {
-    const raw = readFileSync5(configPath, "utf-8");
+    const raw = readFileSync6(configPath, "utf-8");
     const parsed = JSON.parse(raw);
     return {
       skills: Array.isArray(parsed.skills) ? parsed.skills : [],
@@ -805,7 +1101,7 @@ async function installSkills(options) {
     if (!skill) {
       continue;
     }
-    const skillSourceDir = join10(projectSkillsDir, skill.directoryName);
+    const skillSourceDir = join11(projectSkillsDir, skill.directoryName);
     for (const agentId of options.selectedAgents) {
       const adapter = ADAPTER_REGISTRY[agentId];
       if (!adapter) {
@@ -815,14 +1111,15 @@ async function installSkills(options) {
       createdFiles.push(...files);
     }
   }
-  const harnessFiles = installHarness({
+  const harnessResult = installHarness({
     targetPath: options.targetPath,
     selectedAgents: options.selectedAgents,
     selectedSkillIds: skillsToInstall,
     detectedDependencies: options.detectedDependencies || [],
-    language: options.language
+    language: options.language,
+    forceOnboarding: options.forceOnboarding
   });
-  createdFiles.push(...harnessFiles);
+  createdFiles.push(...harnessResult.createdFiles);
   const configPath = writeProjectConfig(
     options.targetPath,
     skillsToInstall,
@@ -835,14 +1132,35 @@ async function installSkills(options) {
     installedSkills: skillsToInstall,
     configuredAgents: options.selectedAgents,
     createdFiles,
-    harnessInitialized: true,
+    harnessInitialized: harnessResult.onboardingInitialized,
     language: options.language
   };
 }
 
+// src/domains/ui/render-onboarding-prompt.ts
+import pc2 from "picocolors";
+function formatOnboardingPrompt(language = "es") {
+  const langConfig = SUPPORTED_LANGUAGES[language] ?? SUPPORTED_LANGUAGES.es;
+  const title = langConfig.onboardingPromptTitle;
+  const prompt = langConfig.onboardingPrompt;
+  const separator = pc2.cyan("\u2500".repeat(60));
+  const formattedOutput = [
+    separator,
+    pc2.bold(pc2.yellow(title)),
+    "",
+    pc2.green(prompt),
+    separator
+  ].join("\n");
+  return {
+    title,
+    prompt,
+    formattedOutput
+  };
+}
+
 // src/domains/ui/ui-orchestrator.ts
-async function resolveLanguageSelection(harnessExists, configuredLanguage) {
-  if (harnessExists) {
+async function resolveLanguageSelection(harnessExists, configuredLanguage, forceOnboarding) {
+  if (harnessExists && !forceOnboarding) {
     return configuredLanguage ?? "es";
   }
   const langChoice = await promptLanguage(configuredLanguage ?? "es");
@@ -867,14 +1185,14 @@ async function resolveOverwriteConfirmation(targetPath, selectedSkills, selected
   }
   return Boolean(confirm2);
 }
-async function runInteractiveUi(context) {
+async function runInteractiveUi(context, forceOnboarding = false) {
   console.log(renderBanner());
-  p5.intro(pc2.magenta("Welcome to GrooveSkills! Let's tailor your AI agents with clean architectural standards."));
+  p5.intro(pc3.magenta("Welcome to GrooveSkills! Let's tailor your AI agents with clean architectural standards."));
   if (context.detectedDependencies.length > 0) {
-    const harnessInfo = context.harnessExists ? pc2.green(`Active (.grooveskills/memory, lang: ${context.configuredLanguage ?? "es"})`) : pc2.cyan("Will be initialized");
+    const harnessInfo = context.harnessExists && !forceOnboarding ? pc3.green(`Active (.grooveskills/memory, lang: ${context.configuredLanguage ?? "es"})`) : pc3.cyan("Will be initialized");
     p5.note(
-      `Detected dependencies: ${context.detectedDependencies.map((d) => pc2.bold(d)).join(", ")}
-Active AI folders: ${context.detectedAgents.map((a) => pc2.green(a)).join(", ") || "None (will be created)"}
+      `Detected dependencies: ${context.detectedDependencies.map((d) => pc3.bold(d)).join(", ")}
+Active AI folders: ${context.detectedAgents.map((a) => pc3.green(a)).join(", ") || "None (will be created)"}
 GrooveSkills Harness: ${harnessInfo}`,
       "Project Environment"
     );
@@ -891,7 +1209,8 @@ GrooveSkills Harness: ${harnessInfo}`,
   }
   const selectedLanguage = await resolveLanguageSelection(
     context.harnessExists,
-    context.configuredLanguage
+    context.configuredLanguage,
+    forceOnboarding
   );
   const forceOverwrite = await resolveOverwriteConfirmation(
     context.targetPath,
@@ -907,17 +1226,25 @@ GrooveSkills Harness: ${harnessInfo}`,
     forceOverwrite,
     enableHarness: true,
     detectedDependencies: context.detectedDependencies,
-    language: selectedLanguage
+    language: selectedLanguage,
+    forceOnboarding
   });
-  s.stop(pc2.green("All skills and harness have been successfully configured!"));
-  const harnessStatus = result.harnessInitialized ? pc2.green(`Initialized in .grooveskills/ (Language: ${selectedLanguage})`) : pc2.cyan(`Preserved in .grooveskills/ (Language: ${selectedLanguage})`);
+  s.stop(pc3.green("All skills and harness have been successfully configured!"));
+  const harnessStatus = result.harnessInitialized ? pc3.green(`Initialized in .grooveskills/ (Language: ${selectedLanguage})`) : pc3.cyan(`Preserved in .grooveskills/ (Language: ${selectedLanguage})`);
   p5.note(
-    `Configured skills: ${result.installedSkills.map((s2) => pc2.bold(s2)).join(", ")}
-Target agents: ${result.configuredAgents.map((a) => pc2.cyan(a)).join(", ")}
+    `Configured skills: ${result.installedSkills.map((s2) => pc3.bold(s2)).join(", ")}
+Target agents: ${result.configuredAgents.map((a) => pc3.cyan(a)).join(", ")}
 GrooveSkills Harness: ${harnessStatus}`,
     "Installation Summary"
   );
-  p5.outro(pc2.green("Your AI programming pair is now empowered with your team's architectural habits! \u{1F680}"));
+  if (result.harnessInitialized) {
+    const promptRender = formatOnboardingPrompt(selectedLanguage);
+    p5.note(
+      pc3.green(promptRender.prompt),
+      promptRender.title
+    );
+  }
+  p5.outro(pc3.green("Your AI programming pair is now empowered with your team's architectural habits! \u{1F680}"));
 }
 
 // src/main.ts
@@ -927,23 +1254,31 @@ async function runGrooveSkills(options = {}) {
   const hasSkills = options.skills && options.skills.length > 0;
   const hasAgents = options.agents && options.agents.length > 0;
   const isDirectHarness = Boolean(options.harness) && hasAgents;
-  if (hasSkills && hasAgents || isDirectHarness) {
+  const isDirectInit = Boolean(options.forceOnboarding) && hasAgents;
+  if (hasSkills && hasAgents || isDirectHarness || isDirectInit) {
     const language = options.language ?? context.configuredLanguage ?? "es";
-    await installSkills({
+    const result = await installSkills({
       targetPath,
       selectedSkillIds: options.skills || [],
       selectedAgents: options.agents || [],
       forceOverwrite: Boolean(options.yes),
       enableHarness: true,
       detectedDependencies: context.detectedDependencies,
-      language
+      language,
+      forceOnboarding: options.forceOnboarding
     });
+    if (result.harnessInitialized) {
+      const promptRender = formatOnboardingPrompt(language);
+      console.log(`
+${promptRender.formattedOutput}
+`);
+    }
     return;
   }
-  await runInteractiveUi(context);
+  await runInteractiveUi(context, Boolean(options.forceOnboarding));
 }
 
 export {
   runGrooveSkills
 };
-//# sourceMappingURL=chunk-FN4OEDVV.js.map
+//# sourceMappingURL=chunk-HUG3MG3P.js.map