@relipa/ai-flow-kit 0.2.0 → 0.2.2-beta.0

package/scripts/init.js

@@ -25,14 +25,19 @@ function commandExists(cmd) {
 
 // Map framework → language family for picking the right rules
 const FRAMEWORK_LANGUAGE = {
-    'laravel':      'php',
-    'php':          'php',
-    'spring-boot':  'java',
-    'reactjs':      'javascript',
-    'nextjs':       'javascript',
-    'vue-nuxt':     'javascript',
-    'nestjs':       'javascript',
-    'python-ml':    'python',
+    'laravel':          'php',
+    'php':              'php',
+    'php-plain':        'php',
+    'spring-boot':      'java',
+    'reactjs':          'javascript',
+    'nextjs':           'javascript',
+    'vue-nuxt':         'javascript',
+    'nestjs':           'javascript',
+    'nodejs-express':   'javascript',
+    'python-ml':        'python',
+    'python':           'python',
+    'python-django':    'python',
+    'python-fastapi':   'python',
 };
 
 // Frameworks that use the ML-specific gate workflow instead of the default one
@@ -69,8 +74,16 @@ const AI_TOOL_FILES = {
 // Codex is 'pointer' because it caps the combined AGENTS.md chain at
 // project_doc_max_bytes (32 KiB default) and silently drops whatever exceeds it.
 // The assembled workflow set is ~115 KB, so inlining would truncate it mid-gate.
+//
+// Claude is 'pointer' for a softer reason: no hard byte cap, but CLAUDE.md is
+// loaded in full at the start of every session regardless of which gate (or none)
+// is actually active, so inlining ~115 KB of DEV/TESTER/EXECUTE/gen-doc/ingest-data
+// + BA + QA workflow text spends context on gates most sessions never touch.
+// Claude Code already reads files on demand via Read/Skill, so a short pointer
+// works the same way a Skill reference does.
 const AI_TOOL_LAYOUT = {
     'codex': 'pointer',
+    'claude': 'pointer',
 };
 
 /** Return 'inline' or 'pointer' for a tool key. */
@@ -78,6 +91,39 @@ function resolveToolLayout(tool) {
     return AI_TOOL_LAYOUT[tool] || 'inline';
 }
 
+// Skill-list rendering per tool.
+//   'full'    — verbose markdown table with description per skill (default, for
+//               tools with no native skill index — cursor/gemini/copilot/generic).
+//   'compact' — bare skill-name list.
+//
+// Both Codex (.codex/skills/) and Claude Code (.claude/skills/) auto-discover
+// name + description from each SKILL.md's frontmatter on their own, so restating
+// the full table in the generated instruction file just burns context on every
+// turn for information the tool already surfaces natively. The compact list still
+// tells the AI which skill names exist and where to `Read` the full SKILL.md when
+// a workflow step names one — it just stops duplicating the description.
+const AI_TOOL_SKILL_LIST_STYLE = {
+    'codex': 'compact',
+    'claude': 'compact',
+};
+
+/** Return 'full' or 'compact' skill-list style for a tool key. */
+function resolveSkillListStyle(tool) {
+    return AI_TOOL_SKILL_LIST_STYLE[tool] || 'full';
+}
+
+// Where each tool actually reads its skills from, for re-rooting paths in the
+// generated registry/name-list. Only Codex mirrors skills into its own directory
+// (.codex/skills/); every other tool reads the canonical .claude/skills/ directly.
+const AI_TOOL_SKILLS_ROOT = {
+    'codex': '.codex/skills',
+};
+
+/** Return the skills-root path to embed in a tool's generated instruction file. */
+function resolveSkillsRoot(tool) {
+    return AI_TOOL_SKILLS_ROOT[tool] || '.claude/skills';
+}
+
 // Shared workflow templates copied to .aiflow/instructions/ for pointer-layout tools.
 // Keys are the destination basenames; gate workflow resolves per framework.
 const WORKFLOW_INSTRUCTION_FILES = [
@@ -612,7 +658,8 @@ async function generateSkillNameList(projectDir, skillsRoot = '.codex/skills') {
     if (!names.length) return '';
 
     let out = `## Available skills\n\n`;
-    out += `Codex indexes these automatically from \`${skillsRoot}/\`. When a workflow step says `;
+    out += `These skills are indexed automatically from \`${skillsRoot}/\` (name + description come from `;
+    out += `each SKILL.md's frontmatter). When a workflow step says `;
     out += `**INVOKE:** \`<name>\`, read \`${skillsRoot}/<name>/SKILL.md\` in full and follow it:\n\n`;
     out += names.sort().map(n => `\`${n}\``).join(' · ') + '\n';
     return out;
@@ -653,6 +700,29 @@ async function generateSkillRegistry(projectDir, skillsRoot = '.claude/skills')
     return registry;
 }
 
+/**
+ * Write `finalContent` into `targetPath` under its own marker pair: replace the
+ * existing block in place if the markers are already present, append (separated
+ * by `sep`) if the file exists without them, or create the file fresh otherwise.
+ * Used for multi-framework projects, where several independent markers
+ * (one per framework, plus the shared tool/registry block) share one file.
+ */
+async function upsertMarkerBlock(targetPath, markerStart, markerEnd, finalContent, sep) {
+    const exists = await fs.pathExists(targetPath);
+    if (!exists) {
+        await fs.writeFile(targetPath, finalContent);
+        return;
+    }
+    const existingContent = await fs.readFile(targetPath, 'utf-8');
+    const hasBlock = existingContent.includes(markerStart) && existingContent.includes(markerEnd);
+    if (hasBlock) {
+        const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`, 'g');
+        await fs.writeFile(targetPath, existingContent.replace(regex, finalContent));
+    } else {
+        await fs.appendFile(targetPath, sep + finalContent);
+    }
+}
+
 async function setupFramework(projectDir, framework, multi = false, selectedTools = Object.keys(AI_TOOL_FILES), options = {}) {
     if (!framework) return;
     const frameworkTemplatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
@@ -683,12 +753,19 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
     const workflowContent = [gateWorkflowContent, createSpecContent, createTestcaseContent].filter(Boolean).join('\n\n---\n\n');
 
     const separator = `\n\n---\n\n`;
-    const skillRegistry  = await generateSkillRegistry(projectDir);
-    const codexSkillList = await generateSkillNameList(projectDir, '.codex/skills');
 
     const markerStart = '<!-- aiflow-kit-start -->';
     const markerEnd   = '<!-- aiflow-kit-end -->';
 
+    // Multi-framework projects get exactly one shared block per tool (tool header +
+    // skill registry) instead of one copy per framework block — neither depends on
+    // which framework triggered this call, so repeating them per framework was pure
+    // duplication (e.g. spring-boot + php in the same project doubled the ~44-skill
+    // registry). Re-running for a second framework upserts this block in place via
+    // its fixed markers rather than appending another copy.
+    const sharedMarkerStart = '<!-- aiflow-kit-start:shared -->';
+    const sharedMarkerEnd   = '<!-- aiflow-kit-end:shared -->';
+
     // Pointer-layout tools need the workflows on disk instead of inlined.
     const needsPointer = selectedTools.some(t => resolveToolLayout(t) === 'pointer');
     const instructionPaths = needsPointer
@@ -696,12 +773,13 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
         : [];
 
     /**
-     * Assemble the marker block for one tool.
-     * 'inline' tools get the whole workflow set embedded; 'pointer' tools get a
-     * short "installed workflow files" list and read the workflows from disk.
+     * Tool header + skill registry + (for pointer tools) the "installed workflow
+     * files" pointer note — none of this depends on which framework is active:
+     * the 3 instruction-file paths are always the same 3 filenames regardless of
+     * framework (only their on-disk *content* varies), so this used to be
+     * duplicated per framework block for no reason.
      */
-    async function buildToolBlock(tool, blockMarkerStart, blockMarkerEnd) {
-        const pointer = resolveToolLayout(tool) === 'pointer';
+    async function buildSharedBlock(tool) {
         let body = '';
 
         const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
@@ -709,19 +787,46 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
             body += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
         }
 
-        if (frameworkContent) body += frameworkContent + '\n\n';
-
-        const registry = pointer ? codexSkillList : skillRegistry;
+        const skillsRoot = resolveSkillsRoot(tool);
+        const registry = resolveSkillListStyle(tool) === 'compact'
+            ? await generateSkillNameList(projectDir, skillsRoot)
+            : await generateSkillRegistry(projectDir, skillsRoot);
         if (registry) body += registry + '\n\n';
 
-        if (pointer) {
-            if (instructionPaths.length) {
-                body += `## Installed workflow files\n\n`;
-                body += `Generated for framework \`${framework}\` by ai-flow-kit v${PKG_VERSION}. `;
-                body += `Read the relevant file in full before starting a gate:\n\n`;
-                body += instructionPaths.map(p => `- \`${p}\``).join('\n') + '\n\n';
-            }
-        } else if (workflowContent) {
+        const pointer = resolveToolLayout(tool) === 'pointer';
+        if (pointer && instructionPaths.length) {
+            body += `## Installed workflow files\n\n`;
+            body += `Generated by ai-flow-kit v${PKG_VERSION}. `;
+            body += `These are the full DEV/TESTER/EXECUTE (+ gen-doc/ingest-data), BA spec, and QA `;
+            body += `testcase gate workflows — too large to inline here. Read the relevant file `;
+            body += `**in full** before starting a gate; do not work from a summary and do not skip, `;
+            body += `shorten, or merge gates:\n\n`;
+            body += instructionPaths.map(p => `- \`${p}\``).join('\n');
+        }
+
+        return body.trim();
+    }
+
+    /**
+     * Assemble the marker block for one tool.
+     * 'inline' tools get the framework's gate workflow embedded inline; 'pointer'
+     * tools already got their "read from disk" note via buildSharedBlock() above.
+     * Pass includeShared: false for multi-framework projects — the tool header,
+     * skill registry, and workflow-files note are written once via
+     * buildSharedBlock() instead.
+     */
+    async function buildToolBlock(tool, blockMarkerStart, blockMarkerEnd, { includeShared = true } = {}) {
+        const pointer = resolveToolLayout(tool) === 'pointer';
+        let body = '';
+
+        if (includeShared) {
+            const shared = await buildSharedBlock(tool);
+            if (shared) body += shared + '\n\n';
+        }
+
+        if (frameworkContent) body += frameworkContent + '\n\n';
+
+        if (!pointer && workflowContent) {
             body += workflowContent + '\n\n';
         }
 
@@ -802,7 +907,7 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
         const blockMarkerStart = multi ? `<!-- aiflow-kit-start:${framework} -->` : markerStart;
         const blockMarkerEnd   = multi ? `<!-- aiflow-kit-end:${framework} -->`   : markerEnd;
 
-        const finalContent = await buildToolBlock(tool, blockMarkerStart, blockMarkerEnd);
+        const finalContent = await buildToolBlock(tool, blockMarkerStart, blockMarkerEnd, { includeShared: !multi });
 
         const fileExists = await fs.pathExists(targetPath);
 
@@ -861,19 +966,15 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
                 }
             }
         } else {
-            if (fileExists) {
-                const existingContent = await fs.readFile(targetPath, 'utf-8');
-                const hasBlock = existingContent.includes(blockMarkerStart) && existingContent.includes(blockMarkerEnd);
-                if (hasBlock) {
-                    const regex = new RegExp(`${blockMarkerStart}[\\s\\S]*?${blockMarkerEnd}`, 'g');
-                    const updatedContent = existingContent.replace(regex, finalContent);
-                    await fs.writeFile(targetPath, updatedContent);
-                } else {
-                    await fs.appendFile(targetPath, separator + finalContent);
-                }
-            } else {
-                await fs.writeFile(targetPath, finalContent);
+            // Upsert the shared block (tool header + skill registry) once per tool —
+            // fixed markers mean a second framework's call replaces it in place
+            // instead of appending another copy.
+            const sharedBody = await buildSharedBlock(tool);
+            if (sharedBody) {
+                const sharedFinal = `${sharedMarkerStart}\n${sharedBody}\n${sharedMarkerEnd}`;
+                await upsertMarkerBlock(targetPath, sharedMarkerStart, sharedMarkerEnd, sharedFinal, separator);
             }
+            await upsertMarkerBlock(targetPath, blockMarkerStart, blockMarkerEnd, finalContent, separator);
             written.push(AI_TOOL_FILES[tool]);
         }
     }
@@ -1523,6 +1624,8 @@ module.exports = init;
 module.exports.AI_TOOL_FILES = AI_TOOL_FILES;
 module.exports.AI_TOOL_LAYOUT = AI_TOOL_LAYOUT;
 module.exports.resolveToolLayout = resolveToolLayout;
+module.exports.resolveSkillListStyle = resolveSkillListStyle;
+module.exports.resolveSkillsRoot = resolveSkillsRoot;
 module.exports.writeWorkflowInstructions = writeWorkflowInstructions;
 module.exports.setupCodex = setupCodex;
 module.exports.setupCodexSkills = setupCodexSkills;

package/scripts/prompt.js

@@ -386,16 +386,16 @@ Follow gates IN ORDER. Do NOT skip or merge gates.
 
 ### GATE 1 — Pre-flight & Work Plan (auto-start)
 **INVOKE:** \`execute-flow\` skill
-Check: MCP Playwright configured, TC file is parseable, \`ak-test/{repo}/\` scaffold exists, \`BASE_URL\` set, Playwright config exists. Display the work plan (TC file, repo, screen, BASE_URL) → wait for **APPROVED**.
+Check: MCP Playwright configured, TC file is parseable, \`AK-Docs/03.Testing/\` subfolders exist (\`04.Evidence/\`, \`05.Scripts/\`, \`02.Reports/\`, \`06.Bugs/\`), \`BASE_URL\` set, \`AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts\` exists (auto-scaffold if missing), \`.gitignore\` covers \`03.Testing/04.Evidence/\` and \`05.Scripts/**/node_modules\`. Display the work plan (TC file, repo, screen, BASE_URL) → wait for **APPROVED**.
 
 ### GATE 2 — Script Sync
 Only runs after Gate 1 APPROVED.
 **INVOKE:** \`script-sync\` skill
-Hash-based TC↔script sync: new TC → generate Playwright test via MCP snapshot/locator (never fabricate selectors); changed TC → update; unchanged → skip; manual/blocked → mark Untest/Pending. Display new/updated/skipped/manual counts → wait for **APPROVED**.
+Hash-based TC↔script sync: new TC → generate Playwright test via MCP snapshot/locator (never fabricate selectors, never use a locator matching more than one element); changed TC → update; unchanged → skip; manual/blocked → mark Untest/Pending. Every step calls \`captureStepEvidence()\` from \`Shared/evidence-helper.ts\`. Display new/updated/skipped/manual counts → wait for **APPROVED**.
 
 ### GATE 3 — Execute & Evidence
 Only runs after Gate 2 APPROVED.
-Run \`BASE_URL=<url> npx playwright test scripts/{screenId}/{ScreenID}.spec.ts\`, organize evidence (screenshots/trace/result.md) into \`ak-test/{repo}/results/{screenId}/run-{N}/\`, auto-draft bug reports for failures, update R1/R2 columns in the TC file. Supports \`RETEST: [TC_ID]\` and \`PR: [url]\`. Display pass/fail/untest/pending counts → wait for **APPROVED** (all Critical/High bugs resolved).
+Run from \`AK-Docs/03.Testing/05.Scripts/\` with \`EVIDENCE_DIR\` pointed at \`AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/\` (gitignored), organize evidence (screenshots/trace) there and text output (\`result.md\`, \`testreport.md\`) into \`AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/\`, auto-draft bug reports into \`AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/\`, update R1/R2 columns in the TC file. Cross-check assertions against the TC's actual Expected Result before recording PASS/FAIL — don't trust Playwright's exit code alone. Supports \`RETEST: [TC_ID]\` and \`PR: [url]\`. Display pass/fail/untest/pending counts → wait for **APPROVED** (all Critical/High bugs resolved).
 
 ### GATE 4 — Report & Bug Logging (wait for APPROVED)
 Only runs after Gate 3 APPROVED.

package/scripts/scaffold-playwright.js

@@ -18,7 +18,9 @@ const HARNESS_FILES = [
 
 const GITIGNORE_LINES = [
   '# Playwright',
+  'node_modules/',
   'playwright-report/',
+  'blob-report/',
   'test-results/',
   'tests/e2e/.auth/',
   '.env',