@keber/qa-framework 1.11.3 → 1.13.0

package/scripts/check-forbidden-chars.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * check-forbidden-chars.js
+ *
+ * Enforces the BLOCKING character-safety rule declared in
+ * .github/copilot-instructions.md: generated content must never carry typographic
+ * characters that survive a copy-paste but break on the way to a terminal, a CSV,
+ * a PowerShell script or an Azure DevOps field.
+ *
+ * Forbidden: em-dash (U+2014), en-dash (U+2013), horizontal ellipsis (U+2026),
+ * smart quotes (U+201C, U+201D, U+2018, U+2019) and arrows (U+2190-U+21FF).
+ * Each has an ASCII equivalent that renders identically everywhere.
+ *
+ * Latin Extended (U+00C0-U+024F) is explicitly NOT flagged: Spanish accents,
+ * n with tilde and u/o with umlaut are required orthography, not decoration.
+ * Emoji are not flagged either - they are outside the forbidden set.
+ *
+ * Unlike check-spanish-accents.js this scans .js and .ts as well as .md, because
+ * the generators under scripts/ embed these characters in template literals and
+ * console output that propagate into every consuming project.
+ *
+ * Usage:
+ *   node scripts/check-forbidden-chars.js <file|dir> [...]   check paths
+ *   node scripts/check-forbidden-chars.js --staged           check staged files
+ *   node scripts/check-forbidden-chars.js --report <paths>   print findings, never fail
+ *
+ * Exit codes: 0 = clean, 1 = at least one forbidden character, 2 = usage error.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// '.example' covers .env.example, which ships to consuming projects like any other
+// template. A BOM or an em-dash there is not cosmetic: some .env parsers read the
+// first key as QA_BASE_URL and silently fail to find it.
+const EXTENSIONS = ['.md', '.js', '.ts', '.ps1', '.example'];
+
+// Code point -> { name, replacement }. Arrows are handled by range below.
+const FORBIDDEN = {
+  0x2014: { name: 'em dash', replacement: ' - ' },
+  0x2013: { name: 'en dash', replacement: ' - ' },
+  0x2026: { name: 'horizontal ellipsis', replacement: '...' },
+  0x201c: { name: 'left double quotation mark', replacement: '"' },
+  0x201d: { name: 'right double quotation mark', replacement: '"' },
+  0x2018: { name: 'left single quotation mark', replacement: "'" },
+  0x2019: { name: 'right single quotation mark', replacement: "'" },
+};
+
+const ARROW_START = 0x2190;
+const ARROW_END = 0x21ff;
+
+// The two arrows with an obvious ASCII spelling; every other arrow in the block
+// has no single equivalent, so the report asks for a rewrite instead of guessing.
+const ARROW_REPLACEMENTS = {
+  0x2190: '<-',
+  0x2192: '->',
+};
+
+function describe(codePoint) {
+  if (FORBIDDEN[codePoint]) return FORBIDDEN[codePoint];
+  if (codePoint >= ARROW_START && codePoint <= ARROW_END) {
+    return {
+      name: 'arrow',
+      replacement: ARROW_REPLACEMENTS[codePoint] || 'an ASCII arrow such as -> or <-',
+    };
+  }
+  return null;
+}
+
+function hex(codePoint) {
+  return 'U+' + codePoint.toString(16).toUpperCase().padStart(4, '0');
+}
+
+/**
+ * Scan one file's text. Returns an array of findings; column is 1-based and
+ * counted in code points, so an astral character earlier on the line does not
+ * shift the reported position.
+ */
+function scanText(text, file) {
+  const findings = [];
+  const lines = text.split(/\r?\n/);
+
+  lines.forEach((line, lineIndex) => {
+    let column = 0;
+    for (const char of line) {
+      column += 1;
+      const codePoint = char.codePointAt(0);
+      const match = describe(codePoint);
+      if (!match) continue;
+      findings.push({
+        file,
+        line: lineIndex + 1,
+        column,
+        char,
+        codePoint,
+        name: match.name,
+        replacement: match.replacement,
+        text: line.trim(),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function scanFile(file) {
+  return scanText(fs.readFileSync(file, 'utf8'), file);
+}
+
+// Archived copies of content this framework shipped in an earlier release. Their bytes
+// are the point: test/upgrade.test.js matches them against SHIPPED_SCAFFOLD_HASHES to
+// prove a real legacy installation is recognised as pristine. Rewriting a character in
+// one of them changes its hash and silently voids that proof, so they are read-only
+// history rather than authored content and the rule does not apply to them.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'legacy-v1.11.3']);
+
+function collect(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return EXTENSIONS.includes(path.extname(target)) ? [target] : [];
+  return fs.readdirSync(target).flatMap((entry) => {
+    if (SKIP_DIRS.has(entry)) return [];
+    return collect(path.join(target, entry));
+  });
+}
+
+function stagedFiles() {
+  const out = execFileSync(
+    'git',
+    ['diff', '--cached', '--name-only', '--diff-filter=ACM'],
+    { encoding: 'utf8' }
+  );
+  return out
+    .split('\n')
+    .map((s) => s.trim())
+    .filter((s) => s && EXTENSIONS.includes(path.extname(s)) && fs.existsSync(s));
+}
+
+function main(argv) {
+  const reportOnly = argv.includes('--report');
+  const args = argv.filter((a) => a !== '--report');
+
+  let files;
+  if (args.includes('--staged')) {
+    files = stagedFiles();
+  } else if (args.length) {
+    files = args.flatMap(collect);
+  } else {
+    console.error('usage: check-forbidden-chars.js <file|dir>... | --staged [--report]');
+    return 2;
+  }
+
+  const findings = files.flatMap(scanFile);
+
+  if (findings.length) {
+    const stream = reportOnly ? console.log : console.error;
+    stream(`\nForbidden characters (${findings.length} occurrence(s)):\n`);
+    for (const f of findings) {
+      stream(`  ${f.file}:${f.line}:${f.column}  "${f.char}" ${hex(f.codePoint)} ${f.name}`);
+      stream(`    use ${f.replacement}`);
+      stream(`    ${f.text}`);
+    }
+    if (!reportOnly) {
+      stream(
+        '\nThese characters break on the way to a terminal, a CSV export or an Azure' +
+        '\nDevOps field. Replace them with their ASCII equivalents rather than' +
+        '\nbypassing this check. Spanish accents are permitted and are never flagged.\n'
+      );
+      return 1;
+    }
+    return 0;
+  }
+
+  if (reportOnly) {
+    console.log(`check-forbidden-chars: ${files.length} file(s) checked, no findings.`);
+    return 0;
+  }
+
+  console.log(`check-forbidden-chars: ${files.length} file(s) checked, no violations.`);
+  return 0;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { scanText, scanFile, main, EXTENSIONS, FORBIDDEN, ARROW_START, ARROW_END };

package/scripts/check-spanish-accents.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * check-spanish-accents.js
+ *
+ * Fails when a Markdown file whose prose is Spanish carries no accented characters.
+ *
+ * Why this exists: a spec written as "Codigo" while the UI renders "Código" produces a
+ * page-object selector that never matches. In one project that cost 24 of 39 failing smoke
+ * tests and two wrong mitigations (raising a timeout, forcing HTTP/1.1) before the real
+ * cause was found, because the failure presents as a timeout, not as a text mismatch.
+ * Accent stripping is a defect, not a house style - and its measured incidence in
+ * agent-generated artifacts is high enough that honor-system compliance does not hold.
+ *
+ * The hard part is not detecting missing accents; it is deciding which files are Spanish.
+ * A naive "every .md must contain accents" rule fails every legitimately English artifact
+ * the framework ships. Counting Spanish marker words in raw text does not separate them
+ * either: an English document about a Spanish-language project quotes enough Spanish paths,
+ * identifiers and snippets to cross any absolute threshold that still catches short
+ * Spanish files.
+ *
+ * So this classifies on the density of Spanish function words in PROSE ONLY, after
+ * stripping fenced code, inline code, link targets, HTML tags and table pipes. English
+ * prose that merely cites Spanish identifiers scores low because those citations live in
+ * the stripped regions; real Spanish prose scores high because its function words are
+ * spread through the sentences themselves.
+ *
+ * Usage:
+ *   node scripts/check-spanish-accents.js <file|dir> [...]   check paths
+ *   node scripts/check-spanish-accents.js --staged           check staged .md files
+ *   node scripts/check-spanish-accents.js --report <paths>   print scores, never fail
+ *
+ * Exit codes: 0 = clean, 1 = at least one Spanish file has no accents, 2 = usage error.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Function words that are unavoidable in real Spanish prose and rare in English text.
+// Deliberately excludes "no", "a", "en", "es" and other tokens that collide with English
+// or with code, and excludes accented forms so a stripped file is not penalised twice.
+const MARKERS = [
+  'que', 'para', 'con', 'por', 'los', 'las', 'del', 'una', 'como', 'pero',
+  'este', 'esta', 'estos', 'estas', 'sin', 'sobre', 'desde', 'cuando', 'donde',
+  'cada', 'todo', 'todos', 'toda', 'todas', 'entre', 'hasta', 'porque', 'segun',
+  'debe', 'deben', 'ser', 'son', 'hay', 'muy', 'ya', 'si', 'lo', 'le', 'se',
+];
+
+const ACCENTED = /[áéíóúÁÉÍÓÚñÑüÜ]/;
+
+// A file is Spanish when at least this share of its prose words are Spanish markers.
+// Calibrated against this package's own corpus: Spanish agent templates land near 0.13,
+// English skill files and the FRAMEWORK-FIXES reports stay below 0.03.
+const DENSITY_THRESHOLD = 0.07;
+// Below this many prose words the density estimate is too noisy to act on.
+const MIN_PROSE_WORDS = 60;
+
+/** Remove every region where Spanish tokens are citations rather than prose. */
+function extractProse(markdown) {
+  return markdown
+    .replace(/^---\n[\s\S]*?\n---/, ' ')      // YAML frontmatter
+    .replace(/```[\s\S]*?```/g, ' ')          // fenced code
+    .replace(/~~~[\s\S]*?~~~/g, ' ')          // fenced code, alt syntax
+    .replace(/`[^`\n]*`/g, ' ')               // inline code
+    .replace(/\]\([^)]*\)/g, '] ')            // link targets, keep link text
+    .replace(/<[^>\n]*>/g, ' ')               // HTML tags and <placeholders>
+    .replace(/\{\{[^}]*\}\}/g, ' ')           // {{TEMPLATE_PLACEHOLDERS}}
+    .replace(/\|/g, ' ')                      // table pipes
+    .replace(/^\s{4,}\S.*$/gm, ' ')           // indented code blocks
+    .replace(/[A-Za-z0-9_.\-]+\/[A-Za-z0-9_./\-]+/g, ' ') // bare paths
+    .replace(/[#*_>[\]]/g, ' ');              // remaining markdown punctuation
+}
+
+function score(markdown) {
+  const prose = extractProse(markdown);
+  const words = prose.toLowerCase().match(/[a-zà-ÿ]+/g) || [];
+  const markers = words.filter((w) => MARKERS.includes(w)).length;
+  const density = words.length ? markers / words.length : 0;
+  return {
+    words: words.length,
+    markers,
+    density,
+    isSpanish: words.length >= MIN_PROSE_WORDS && density >= DENSITY_THRESHOLD,
+    hasAccents: ACCENTED.test(markdown),
+  };
+}
+
+function collect(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return target.endsWith('.md') ? [target] : [];
+  return fs.readdirSync(target).flatMap((entry) => {
+    if (entry === 'node_modules' || entry === '.git') return [];
+    return collect(path.join(target, entry));
+  });
+}
+
+function stagedMarkdown() {
+  const out = execFileSync(
+    'git',
+    ['diff', '--cached', '--name-only', '--diff-filter=ACM', '--', '*.md'],
+    { encoding: 'utf8' }
+  );
+  return out.split('\n').map((s) => s.trim()).filter((s) => s && fs.existsSync(s));
+}
+
+function main(argv) {
+  const reportOnly = argv.includes('--report');
+  const args = argv.filter((a) => a !== '--report');
+
+  let files;
+  if (args.includes('--staged')) {
+    files = stagedMarkdown();
+  } else if (args.length) {
+    files = args.flatMap(collect);
+  } else {
+    console.error('usage: check-spanish-accents.js <file|dir>... | --staged [--report]');
+    return 2;
+  }
+
+  const failures = [];
+  for (const file of files) {
+    const result = score(fs.readFileSync(file, 'utf8'));
+    if (reportOnly) {
+      console.log(
+        `${result.isSpanish ? 'ES' : 'en'}  density=${result.density.toFixed(3)}  ` +
+        `words=${String(result.words).padStart(5)}  accents=${result.hasAccents ? 'yes' : 'NO '}  ${file}`
+      );
+    }
+    if (result.isSpanish && !result.hasAccents) failures.push({ file, ...result });
+  }
+
+  if (reportOnly) return 0;
+
+  if (failures.length) {
+    console.error('\nSpanish Markdown without accented characters:\n');
+    for (const f of failures) {
+      console.error(`  ${f.file}`);
+      console.error(
+        `    ${f.markers} Spanish markers in ${f.words} prose words ` +
+        `(density ${f.density.toFixed(3)}), 0 accented characters.`
+      );
+    }
+    console.error(
+      '\nSpanish prose must carry its accents: a spec saying "Codigo" does not match a UI' +
+      '\nthat renders "Código", and the resulting selector failure looks like a timeout.' +
+      '\nFix the orthography rather than bypassing this check.\n'
+    );
+    return 1;
+  }
+
+  console.log(`check-spanish-accents: ${files.length} file(s) checked, no violations.`);
+  return 0;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { score, extractProse, MARKERS, DENSITY_THRESHOLD };

package/scripts/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/cli.js — keber/qa-framework CLI entry point
+ * scripts/cli.js - keber/qa-framework CLI entry point
  *
  * Usage:
  *   npx keber/qa-framework <command> [options]

package/scripts/generate.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/generate.js — Generate a qa artifact from a template
+ * scripts/generate.js - Generate a qa artifact from a template
  *
  * Usage:
  *   qa-framework generate <artifact> [options]
@@ -39,7 +39,7 @@ const outputDir     = getArg('--output')    ? path.resolve(process.cwd(), getArg
 const templateDir = path.resolve(__dirname, '..', 'templates');
 
 const ARTIFACTS = {
-  spec:             null,    // special — copies all 6 files
+  spec:             null,    // special - copies all 6 files
   'test-plan':      path.join(templateDir, 'test-plan.md'),
   'test-case':      path.join(templateDir, 'test-case.md'),
   'execution-report': path.join(templateDir, 'execution-report.md'),

package/scripts/init.js

@@ -15,6 +15,9 @@
 const fs   = require('fs');
 const path = require('path');
 
+const { buildCommandContent, discoverSkillNames, commandFileName } = require('./lib/claude-commands');
+const { AGENT_NAMES, isSprintCycleEnabled, renderAllAgents } = require('./lib/claude-agents');
+
 // --- Parse args ---
 const args            = process.argv.slice(2);
 const configFlag      = args.indexOf('--config');
@@ -126,7 +129,7 @@ if (fs.existsSync(qaReadmeTemplate)) {
 // --- qa/memory/INDEX.md ---
 const memoryDir = path.join(qaRoot, 'memory');
 writeIfMissing(path.join(memoryDir, 'INDEX.md'),
-`# Memory Index — ${config.project?.displayName ?? config.project?.name ?? 'Project'}
+`# Memory Index - ${config.project?.displayName ?? config.project?.name ?? 'Project'}
 
 > The agent reads this file first before loading any memory file.
 > Add a row here whenever you create or update a file in this directory.
@@ -146,7 +149,7 @@ for (const file of ['ci-pipeline-findings.md', 'e2e-stabilization-patterns.md',
 
 // --- 03-test-cases README (optional directory marker) ---
 writeIfMissing(path.join(qaRoot, '03-test-cases', 'README.md'),
-`# 03-test-cases/ — Optional Standalone Test Cases
+`# 03-test-cases/ - Optional Standalone Test Cases
 
 > **v1.7.0+:** The primary location for test cases (with detailed steps) is now
 > \`qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{project}-Sprint-{N}-{module}.md\`.
@@ -192,13 +195,26 @@ const SPEC_FILES = [
 
 const templateDir = path.resolve(__dirname, '..', 'templates', 'specification');
 
+// Spec folders carry the module-/submodule- prefix; automation folders and TC ids
+// use the bare key. See scripts/lib/module-keys.js for why the two differ.
+const {
+  moduleSpecDirName,
+  submoduleSpecDirName,
+  moduleBareName,
+  submoduleBareName,
+} = require('./lib/module-keys');
+
 for (const mod of modules) {
   const moduleKey = mod.key ?? mod.name.toLowerCase().replace(/\s+/g, '-');
+  const moduleDirName = moduleSpecDirName(moduleKey);
+  const moduleName = moduleBareName(moduleKey);
   const submodules = mod.submodules ?? [];
 
   for (const sub of submodules) {
     const subKey = sub.key ?? sub.name.toLowerCase().replace(/\s+/g, '-');
-    const subDir = path.join(qaRoot, moduleKey, subKey);
+    const subDirName = submoduleSpecDirName(subKey);
+    const subName = submoduleBareName(subKey);
+    const subDir = path.join(qaRoot, '01-specifications', moduleDirName, subDirName);
     fs.mkdirSync(subDir, { recursive: true });
 
     for (const specFile of SPEC_FILES) {
@@ -210,8 +226,8 @@ for (const mod of modules) {
           content = content
             .replace(/\{\{MODULE_NAME\}\}/g, mod.name)
             .replace(/\{\{SUBMODULE_NAME\}\}/g, sub.name)
-            .replace(/\{\{MODULE\}\}/g, moduleKey.toUpperCase())
-            .replace(/\{\{SUB\}\}/g, subKey.toUpperCase());
+            .replace(/\{\{MODULE\}\}/g, moduleName.toUpperCase())
+            .replace(/\{\{SUB\}\}/g, subName.toUpperCase());
           fs.writeFileSync(dest, content, 'utf8');
         } else {
           fs.writeFileSync(dest, `# ${specFile}\n\n> Auto-generated placeholder\n`, 'utf8');
@@ -223,11 +239,11 @@ for (const mod of modules) {
     }
 
     // Create automation spec stub in e2e/tests/{module}/
-    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', 'tests', moduleKey);
+    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', 'tests', moduleName);
     fs.mkdirSync(e2eDir, { recursive: true });
-    const specTs = path.join(e2eDir, `${subKey}.spec.ts`);
+    const specTs = path.join(e2eDir, `${subName}.spec.ts`);
     if (!fs.existsSync(specTs)) {
-      fs.writeFileSync(specTs, specScaffold(mod.name, sub.name, moduleKey, subKey), 'utf8');
+      fs.writeFileSync(specTs, specScaffold(mod.name, sub.name, moduleName, subName), 'utf8');
       console.log(`  [created] ${path.relative(cwd, specTs)}`);
     }
   }
@@ -245,6 +261,19 @@ for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', '
     console.log(`  [created] ${path.relative(cwd, dest)}`);
   }
 }
+// Lane scripts: the lane lock plus its config reader and global-setup guards. Plain
+// CommonJS so they run as a CLI and stay testable with `node --test` without pulling
+// in a TypeScript test runner.
+const laneScriptsDir = path.join(e2eScaffoldDir, 'scripts');
+fs.mkdirSync(laneScriptsDir, { recursive: true });
+for (const file of ['lane-config.js', 'lane-lock.js', 'global-setup-guards.js']) {
+  const dest = path.join(laneScriptsDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(scaffoldSrc, 'scripts', file), dest);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
+  }
+}
+
 const fixturesDir = path.join(e2eScaffoldDir, 'fixtures');
 fs.mkdirSync(fixturesDir, { recursive: true });
 for (const file of ['auth.ts', 'test-helpers.ts', 'base.ts']) {
@@ -283,7 +312,7 @@ const adoDir = path.join(qaRoot, '08-azure-integration');
 writeIfMissing(path.join(adoDir, 'README.md'), `# ADO Integration\n\nSee keber/qa-framework integrations/ado-powershell/ for setup instructions.\n`);
 writeIfMissing(path.join(adoDir, 'module-registry.json'), JSON.stringify({ modules: [] }, null, 2));
 
-// --- Skills → .github/skills/ ---
+// --- Skills -> .github/skills/ ---
 const skillsSrc = path.resolve(__dirname, '..', 'skills');
 const skillsDest = path.join(cwd, '.github', 'skills');
 fs.mkdirSync(skillsDest, { recursive: true });
@@ -298,7 +327,7 @@ if (fs.existsSync(skillsSrc)) {
   }
 }
 
-// --- QA structure guide → qa/QA-STRUCTURE-GUIDE.md ---
+// --- QA structure guide -> qa/QA-STRUCTURE-GUIDE.md ---
 const structureGuideSrc  = path.resolve(__dirname, '..', 'docs', 'folder-structure-guide.md');
 const structureGuideDest = path.join(qaRoot, 'QA-STRUCTURE-GUIDE.md');
 if (fs.existsSync(structureGuideSrc)) {
@@ -314,7 +343,40 @@ const copilotInstrContent = fs.readFileSync(instrTemplatePath, 'utf8')
   .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
-// --- AGENT-NEXT-STEPS.md — readable by the agent after install ---
+// --- .claude/commands/qa-*.md - thin wrappers pointing at .github/skills/ ---
+const claudeCommandsDest = path.join(cwd, '.claude', 'commands');
+fs.mkdirSync(claudeCommandsDest, { recursive: true });
+for (const skillName of discoverSkillNames(skillsSrc)) {
+  writeIfMissing(path.join(claudeCommandsDest, commandFileName(skillName)), buildCommandContent(skillName));
+}
+
+// --- .claude/rules/qa-framework.md - always-loaded rules (Claude Code equivalent of applyTo: '**') ---
+const claudeRulesPath  = path.join(cwd, '.claude', 'rules', 'qa-framework.md');
+const rulesTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.rules.md');
+const claudeRulesContent = fs.readFileSync(rulesTemplatePath, 'utf8')
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
+writeIfMissing(claudeRulesPath, claudeRulesContent);
+
+// --- .claude/agents/qa-*.md - optional ANALISIS/PLAN sprint-cycle mode (Claude Code only) ---
+// Gated by integrations.azureDevOps.sprintCycle.enabled. No .github/ equivalent: Claude
+// Code subagents with per-agent tools/model frontmatter have no Copilot counterpart.
+// Each agent is rendered independently: an invalid lane config fails qa-investigador
+// only, the other agents are still written, and init exits 1 at the end.
+const agentFailures = [];
+if (isSprintCycleEnabled(config)) {
+  const templatesDir = path.resolve(__dirname, '..', 'templates');
+  const claudeAgentsDest = path.join(cwd, '.claude', 'agents');
+  fs.mkdirSync(claudeAgentsDest, { recursive: true });
+  for (const agent of renderAllAgents(templatesDir, config)) {
+    if (agent.error) {
+      agentFailures.push(agent);
+      continue;
+    }
+    writeIfMissing(path.join(claudeAgentsDest, agent.fileName), agent.content);
+  }
+}
+
+// --- AGENT-NEXT-STEPS.md - readable by the agent after install ---
 const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 
 > This file was generated automatically by the postinstall script.
@@ -324,6 +386,7 @@ const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 
 - \`qa/\` folder structure with spec templates and agent instructions
 - \`.github/instructions/qa-framework.instructions.md\` with QA agent behavior rules (framework-owned, safe to upgrade)
+- \`.claude/rules/qa-framework.md\` and \`.claude/commands/qa-*.md\` - equivalent Claude Code artifacts (framework-owned, safe to upgrade)
 
 ## Required next steps
 
@@ -362,12 +425,21 @@ const adoQaInstalledFinal = fs.existsSync(path.join(cwd, 'node_modules', '@keber
 const azureReporterInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@alex_neo', 'playwright-azure-reporter'));
 
 console.log('');
-console.log('  @keber/qa-framework — scaffold complete');
+console.log('  @keber/qa-framework - scaffold complete');
 console.log('  ----------------------------------------');
 console.log('  Installed:');
 console.log('    qa/                    QA directory structure + spec templates');
 console.log('    .github/skills/        QA agent skills (8 stages)');
 console.log('    .github/instructions/  qa-framework.instructions.md');
+console.log('    .claude/commands/      qa-*.md (Claude Code slash commands)');
+console.log('    .claude/rules/         qa-framework.md (Claude Code always-loaded rules)');
+if (isSprintCycleEnabled(config)) {
+  const failedAgents = new Set(agentFailures.map((a) => a.agentName));
+  const generatedAgents = AGENT_NAMES.filter((name) => !failedAgents.has(name));
+  if (generatedAgents.length) {
+    console.log(`    .claude/agents/        ${generatedAgents.join('/')}.md (ANALISIS/PLAN mode)`);
+  }
+}
 console.log('');
 console.log('  Optional integrations:');
 if (playwrightInstalled) {
@@ -390,6 +462,23 @@ console.log('');
 console.log('  Next: edit qa/qa-framework.config.json, then read qa/AGENT-NEXT-STEPS.md');
 console.log('');
 
+if (agentFailures.length) {
+  if (skipIfExists) {
+    // Postinstall mode: a non-zero exit would make `npm install` of this package fail,
+    // which blocks the user from ever reaching the fix. Report loudly, exit 0.
+    for (const { agentName, fileName, error } of agentFailures) {
+      console.error(`[qa-framework/init] WARNING: agent ${agentName} (.claude/agents/${fileName}) was not generated. ${error.message}`);
+    }
+    console.error('[qa-framework/init] WARNING: fix qa-framework.config.json (run "npx qa-framework validate"), then run "npx qa-framework upgrade" to generate the missing agent.');
+  } else {
+    for (const { fileName, error } of agentFailures) {
+      console.error(`[qa-framework/init] ERROR: .claude/agents/${fileName} was not generated. ${error.message}`);
+    }
+    console.error('[qa-framework/init] Fix qa-framework.config.json (run "qa-framework validate") and run init or upgrade again.');
+    process.exitCode = 1;
+  }
+}
+
 // -----------------------------------------------------------------------
 // Helpers
 // -----------------------------------------------------------------------