@relipa/ai-flow-kit 0.2.0 → 0.2.1

package/custom/templates/spring-boot.md

@@ -1,224 +1,5 @@
-# Spring Boot AI System Prompt
-
-You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
-
-> **Code examples:** See `.rules/java/spring-boot-examples.md` — read it when generating code for a specific layer.
-
----
-
-## Project Stack
-
-- **Java:** 17+
-- **Spring Boot:** 3.x
-- **Build Tool:** Maven (prefer) or Gradle
-- **ORM:** Spring Data JPA + Hibernate
-- **Database:** MySQL / PostgreSQL
-- **Testing:** JUnit 5 + Mockito + AssertJ
-- **Utilities:** Lombok, MapStruct
-- **API Style:** RESTful JSON
-
----
-
-## Architecture
-
-Follow strict **Layered Architecture**:
-
-```
-Controller (HTTP layer)
-    ↓
-Service (Business logic)
-    ↓
-Repository (Data access - Spring Data JPA)
-    ↓
-Entity / Domain Model
-```
-
-### Package Structure
-
-```
-com.company.project/
-├── controller/         # \@RestController — HTTP endpoints only
-├── service/
-│   ├── impl/           # \@Service — business logic implementation
-│   └── [Interface].java
-├── repository/         # \@Repository — extends JpaRepository
-├── entity/             # \@Entity — JPA entities
-├── dto/
-│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
-│   └── response/       # Output DTOs (e.g. UserResponse)
-├── mapper/             # MapStruct mappers (Entity ↔ DTO)
-├── exception/
-│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
-│   └── [CustomException].java
-├── config/             # \@Configuration classes
-└── util/               # Pure utility helpers (stateless)
-```
-
----
-
-## Controller Rules
-
-- Annotate with `\@RestController` + `\@RequestMapping`
-- **Only** handle HTTP concerns: parse request, call service, return response
-- Never put business logic in Controller
-- Always use DTOs — never expose Entity directly
-- Use `ResponseEntity<T>` for explicit HTTP status control
-- Validate input with `\@Valid` + Bean Validation annotations
-
----
-
-## Service Rules
-
-- Always define an **interface**, implement in the `impl/` package
-- Annotate implementation with `\@Service`
-- All business logic lives here
-- Use `\@Transactional` at the method level (not class level)
-- Throw specific custom exceptions, not generic `RuntimeException`
-- Never return an Entity — always convert to DTO via Mapper
-
----
-
-## Repository Rules
-
-- Extend `JpaRepository<Entity, ID>`
-- Use **method name queries** for simple queries
-- Use `\@Query` (JPQL) for complex queries — avoid native SQL unless necessary
-- Never add business logic here
-- Use `\@EntityGraph` to solve N+1 problems
-
----
-
-## Entity Rules
-
-- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
-- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
-- Always use `\@Table(name = "snake_case_table_name")`
-- Use `\@Column(name = "snake_case_column_name")` explicitly
-- For soft delete: add `deleted` boolean + `deletedAt` timestamp
-- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
-
----
-
-## DTO Rules
-
-- Use separate DTOs for **Request** and **Response** — never share
-- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
-- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
-- Never expose internal fields (password hash, audit timestamps) in the Response DTO
-
----
-
-## MapStruct Mapper Rules
-
-- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
-- Define explicit mappings with `\@Mapping` when field names differ
-- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
-
----
-
-## Exception Handling
-
-- Create custom exceptions extending `RuntimeException`
-- Handle all exceptions in one `\@RestControllerAdvice` class
-- Return a consistent error response format
-- Never expose stack traces to the client
-
----
-
-## Testing Rules
-
-### Unit Tests (Service layer)
-- Test class: `[ServiceImpl]Test.java`
-- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
-- Test happy path + edge cases + exception scenarios
-- Use AssertJ: `assertThat(result).isEqualTo(expected)`
-
-### Integration Tests (Controller layer)
-- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
-- Test full HTTP flow with `MockMvc`
-- Use `\@Sql` or Testcontainers for database state
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Class | PascalCase | `UserService`, `OrderController` |
-| Method | camelCase | `findById`, `createOrder` |
-| Variable | camelCase | `userResponse`, `orderId` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| Package | lowercase | `com.company.project.service` |
-| DB Table | snake_case | `user_orders`, `product_items` |
-| DB Column | snake_case | `created_at`, `user_id` |
-| REST endpoint | kebab-case | `/api/v1/user-profiles` |
-| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
-| Response DTO | `[Resource]Response` | `OrderResponse` |
-
----
-
-## API Design
-
-- Version all APIs: `/api/v1/...`
-- Use plural nouns for resources: `/users`, `/orders`
-- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
-- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
-- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
-
-```
-GET    /api/v1/users              → 200 list
-POST   /api/v1/users              → 201 created
-GET    /api/v1/users/{id}         → 200 or 404
-PUT    /api/v1/users/{id}         → 200 or 404
-DELETE /api/v1/users/{id}         → 204 or 404
-GET    /api/v1/users/{id}/orders  → 200 nested resource
-```
-
----
-
-## Performance Rules
-
-- Always use pagination — never return unbounded lists
-- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
-- Add database indexes on frequently queried columns
-- Use `\@Transactional(readOnly = true)` on read-only service methods
-- For heavy read operations, consider projection interfaces
-
----
-
-## Security Rules
-
-- Never log passwords, tokens, or sensitive PII
-- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
-- Validate and sanitize all user inputs via Bean Validation
-- Use `\@PreAuthorize` for method-level security
-- Never return stack traces to API consumers
-- Store secrets in environment variables / Vault — never in code
-
----
-
-## Logging Rules
-
-- Use SLF4J with Lombok `\@Slf4j`
-- `log.info` — normal business events
-- `log.warn` — recoverable issues (not found, validation fail)
-- `log.error` — unexpected exceptions (always include `ex` as the second argument)
-- Never log sensitive data (password, credit card, token)
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
-- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
-- ❌ Returning `Entity` directly from Controller → always use DTO
-- ❌ `SELECT *` or unbounded `findAll()` → always paginate
-- ❌ Business logic in Controller → move to Service
-- ❌ Catching and swallowing exceptions → handle properly or rethrow
-- ❌ `new RuntimeException("something")` → create a specific custom exception
-- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
-- ❌ `\@Transactional` on Controller → only on Service methods
-
----
-
-When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.
+# Spring Boot AI System Prompt
+
+You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
+
+> **Rules & code examples:** Read `.rules/java/spring-boot-rules.md` (architecture, layer rules, naming, security, anti-patterns) and `.rules/java/spring-boot-examples.md` (code samples per layer) **in full** before writing or modifying any Java code in this project.

package/docs/common/CHANGELOG.md

@@ -7,17 +7,9 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [0.2.2] - 2026-08-06
-
-### Added
-
-- **`ak gate <n> skip --ticket <id> [--reason <text>]`** — a gate can now close as "skipped" (legitimately produced no deliverable) instead of only `start`/`approved`. First consumer: `ingest-data` Gate 3, when the AI decides the ingested content is reference-only and no task list is needed — it now runs `ak gate 3 skip` instead of leaving the gate untouched. `scripts/task.js`'s `updateTaskGateState()` gained a `skip` branch that records `skippedGates[gate] = {at, reason}` in `task-state.json` and advances `currentGate` exactly like `approved` does, so every existing "is this task done" check (which only ever inspects `currentGate`) keeps working with zero changes. Prompted by an impact assessment for the `ai-flow-ex` VS Code extension's dashboard, which was showing skipped-Gate-3 ingest-data tasks stuck as "ready to run Gate 3" forever — see `docs/superpowers/specs/2026-08-06-ingest-data-gate3-skipped-state-design.md` in `ai-flow-ex` for the paired UI-side change (reads `skippedGates` to render a distinct "⏭ Skipped" badge instead of the generic "✓ Approved").
-
-### Fixed
-
-- **`ak task next` treated `ingest-data` as a 2-gate flow** — a stale assumption left over from before Gate 3 (task creation & ticket generation) was added to `ingest-data` earlier in the same release cycle. `scripts/task.js` grouped it with `gen-doc`/`create-system-requirement` (`maxGate = 2`), so pausing via `ak task next` on Gate 2 would prematurely mark the task `status: 'done'` and `gateLabel(3, 'ingest-data')` returned `'Done'` instead of `'Sinh Task & Tạo Ticket'`. Split into its own 3-gate branch (`maxGate = 3`); `gen-doc`/`create-system-requirement` are unaffected.
+## [Unreleased]
 
-## [0.2.1] - 2026-08-05
+## [0.2.1] - 2026-08-17
 
 ### Added
 
@@ -30,6 +22,24 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - Approved tickets get their link written back into the originating `Meetings-Log`/`QnA-Log`/`Confirmations-Log` entry (`→ Tasks created: TICKET-101 (coding), ...`), keeping the traceability chain from PM Workflow §6 intact end-to-end.
   - **Still open, tracked in the PM Workflow doc's Vấn đề 5 implementation note:** no fixed feedback→task-type rule table (AI still judges per-context); new tickets don't auto-attach `functionId`/labels (Dev/BA/QA still assign on `ak use TICKET-XXX`); Backlog issueType/priority default to the project's first issueType and a "Normal"-named priority unless overridden explicitly in the task JSON.
 
+- **`ak gate <n> skip --ticket <id> [--reason <text>]`** — a gate can now close as "skipped" (legitimately produced no deliverable) instead of only `start`/`approved`. First consumer: `ingest-data` Gate 3, when the AI decides the ingested content is reference-only and no task list is needed — it now runs `ak gate 3 skip` instead of leaving the gate untouched. `scripts/task.js`'s `updateTaskGateState()` gained a `skip` branch that records `skippedGates[gate] = {at, reason}` in `task-state.json` and advances `currentGate` exactly like `approved` does, so every existing "is this task done" check (which only ever inspects `currentGate`) keeps working with zero changes. Prompted by an impact assessment for the `ai-flow-ex` VS Code extension's dashboard, which was showing skipped-Gate-3 ingest-data tasks stuck as "ready to run Gate 3" forever — see `docs/superpowers/specs/2026-08-06-ingest-data-gate3-skipped-state-design.md` in `ai-flow-ex` for the paired UI-side change (reads `skippedGates` to render a distinct "⏭ Skipped" badge instead of the generic "✓ Approved").
+
+### Changed
+
+- **Per-framework rule sections (Architecture, layer rules, naming, security, anti-patterns) moved out of `CLAUDE.md`/`AGENTS.md` into `.rules/<lang>/<framework>-rules.md`, alongside the existing `-examples.md`.** Extends the same on-demand `.rules/` pattern already used for code samples to the rules themselves: `custom/templates/<framework>.md` now holds only the title, a one-line intro, and a single "> **Rules & code examples:**" pointer to both files — everything else (Controller/Service/Repository/Entity/DTO/Mapper/Exception/Testing/Naming/API/Performance/Security/Logging/anti-patterns, per framework) lives in the new `-rules.md` file. Applied to all 9 templates that had this structure (`spring-boot`, `php`, `php-plain`, `reactjs`, `nestjs`, `nodejs-express`, `python`, `python-django`, `python-fastapi`, `python-ml`) — `nextjs`/`vue-nuxt`/`laravel` were already ~15 lines with no such structure and are untouched. Unlike the workflow-file pointer (read once at a clear Gate-start trigger), these rules apply continuously across every code edit in Gate 3, so `custom/templates/shared/gate-workflow.md` and `ml-gate-workflow.md` both gained an explicit bullet at the top of their Gate 3 (`Code Generation` / `Implement, Train & Iterate`) step: read the rules + examples files pointed to at the top of `CLAUDE.md`/`AGENTS.md` before the first line of code, and keep applying them to every subsequent edit, not just the first. Also fixed `generateSkillNameList()`'s "Codex indexes these automatically" wording, which became inaccurate once `claude` also uses the compact skill list (see previous entry) — reworded to name neither tool specifically. Measured on the kit's own dogfood skill set: solo `spring-boot`/`reactjs`/`php` 247/211/~205 → **41 lines each**; multi `spring-boot`+`php` 385 → **55 lines**.
+
+- **`CLAUDE.md` now uses the same compact skill list as `AGENTS.md`, and 2 techstack templates dropped a redundant "Project Stack" section.** `AI_TOOL_SKILL_LIST_STYLE` gained `'claude': 'compact'` — Claude Code auto-discovers each skill's name + description from `.claude/skills/*/SKILL.md` frontmatter on its own (same mechanism the original Codex-only rationale assumed only Codex had), so restating the full description table in `CLAUDE.md` was duplicating information the tool already surfaces natively. `custom/templates/spring-boot.md` and `reactjs.md` also dropped their "## Project Stack" bullet list (Java/Spring Boot/Maven version pins, React/TypeScript/Vite/Router/etc.) — for spring-boot every item was already restated in a more specific rule section further down (Testing Rules, Entity Rules, Mapper Rules...); for reactjs most items were too (State Management, Form, Styling, API Layer Rules), except **Router (React Router v6), the shadcn/ui pairing with Tailwind, and Vitest as the specific test runner**, which had no other home in the file and are now gone rather than relocated — worth restoring into an existing rule section later if that specificity is missed. Measured on the kit's own dogfood skill set (~46 skills): solo `spring-boot` 306 → 247 lines, solo `reactjs` ~264 → 211 lines, multi `spring-boot`+`php` 444 → 385 lines.
+
+- **`CLAUDE.md` now uses the pointer layout too, not just `AGENTS.md`.** `AI_TOOL_LAYOUT` in `scripts/init.js` gained `'claude': 'pointer'` alongside the existing `'codex': 'pointer'` — CLAUDE.md is loaded in full at the start of every session regardless of which gate (if any) is active, so inlining the ~115 KB DEV/TESTER/EXECUTE/gen-doc/ingest-data + BA + QA workflow set spent context on gates most sessions never touch. The workflow bodies now live in `.aiflow/instructions/` and CLAUDE.md just links to them, same as Codex. Unlike Codex's pointer layout, the skill registry keeps its full description table for `claude` (`resolveSkillListStyle()`/`resolveSkillsRoot()`) — Claude Code has no skill index of its own the way Codex does, so only the workflow bodies move out, not the registry.
+- **Techstack rule templates (`custom/templates/<framework>.md`) no longer inline full code samples for every layer.** Following the pattern already used for `spring-boot.md`/`custom/rules/java/spring-boot-examples.md`, the same split was applied to the other 9 templates that had grown a "✅ Good / ❌ Bad" code block per rule area: `reactjs`, `php`, `php-plain`, `python-ml`, `nestjs`, `nodejs-express`, `python`, `python-django`, `python-fastapi`. Each template keeps its bullet rules, naming table, and anti-pattern list, with a one-line pointer to a new `custom/rules/<lang>/<framework>-examples.md` file holding the actual code samples — read on demand when generating code for that specific layer instead of being inlined into every session's context. `FRAMEWORK_LANGUAGE` in `scripts/init.js` also gained entries for `nodejs-express`, `python`, `python-django`, `python-fastapi`, and `php-plain` (previously missing, so `.rules/<lang>/` was never copied into projects using those frameworks).
+- **Multi-framework projects no longer duplicate the tool header, skill registry, and workflow-files pointer once per framework.** A project with 2+ frameworks (e.g. a `spring-boot` backend + a `reactjs` frontend) calls `setupFramework()` once per framework with `multi: true`; each call used to emit a fully self-contained block (tool header + full skill registry + framework rules + "Installed workflow files" pointer note), so all three non-framework-specific sections got repeated verbatim per framework — the ~46-skill registry was the dominant cost in `CLAUDE.md` once the per-framework code samples above were split out. `setupFramework()` now builds all three via `buildSharedBlock()` once and writes it under its own fixed `<!-- aiflow-kit-start:shared -->` marker; per-framework blocks (`buildToolBlock(tool, ..., { includeShared: false })`) carry only the framework-specific rules and (for inline tools) the inlined gate-workflow body. The "Installed workflow files" note moved to the shared block because its 3 listed paths (`.aiflow/instructions/gate-workflow.md`, `create-spec-workflow.md`, `create-testcase-workflow.md`) are always the same 3 filenames regardless of framework — only their on-disk *content* varies per framework (e.g. ML vs standard gate workflow), not the pointer text itself. Re-running for an already-present framework upserts its block in place (new `upsertMarkerBlock()` helper) instead of appending another copy. Single-framework projects are unaffected (`includeShared` defaults to `true`, same single block as before). Measured on the kit's own dogfood project (spring-boot + php, ~46 real skills): 452 → 444 lines.
+
+- **QnA-Log table (`skill-ba-qna-template-v1.md`) gained 3 response-tracking columns — Người trả lời, Ngày trả lời, Nguồn.** `skill-ba-qna-v1.md`'s Bước 4 now spells out how each is filled: **Người trả lời** defaults to `git config user.email` (fallback `user.name`) of whoever is running the session, overridden only when the BA explicitly names a different responder (e.g. answering on the customer's behalf); **Ngày trả lời** is stamped automatically from the current system date (`dd/mm/yyyy`), never asked; **Nguồn** is always BA-entered manually (e.g. "Khách hàng", "Nội bộ team", "Team Marketing") with no default or inference. Questions still **Open** leave all three columns blank (`—`). Checklist gained a matching item to catch missing values on **Confirmed** rows.
+
+### Fixed
+
+- **`ak task next` treated `ingest-data` as a 2-gate flow** — a stale assumption left over from before Gate 3 (task creation & ticket generation) was added to `ingest-data` earlier in the same release cycle. `scripts/task.js` grouped it with `gen-doc`/`create-system-requirement` (`maxGate = 2`), so pausing via `ak task next` on Gate 2 would prematurely mark the task `status: 'done'` and `gateLabel(3, 'ingest-data')` returned `'Done'` instead of `'Sinh Task & Tạo Ticket'`. Split into its own 3-gate branch (`maxGate = 3`); `gen-doc`/`create-system-requirement` are unaffected.
+
 ## [0.2.0] - 2026-08-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

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;