@securityreviewai/securityreview-kit 0.1.43 → 0.1.45

package/README.md

@@ -27,11 +27,11 @@ npx @securityreviewai/securityreview-kit init --switch-project
 
 | Target | Flag | MCP Config | Workspace Rule |
 |---|---|---|---|
-| Cursor | `cursor` | `.cursor/mcp.json` | `.cursor/rules/srai-security-review.mdc`, `.cursor/rules/guardrails_rule.mdc`, `.cursor/commands/srai-profile.md`, `.cursor/commands/guardrails-init-profile.md`, `.cursor/skills/threat-modelling/SKILL.md`, `.cursor/hooks.json` |
-| Claude Code | `claude` | `.mcp.json` | `.claude/CLAUDE.md`, `.claude/settings.json`, `.claude/skills/threat-modelling/SKILL.md`, `.claude/skills/guardrails-profiler/SKILL.md`, `.claude/skills/guardrails-selection/SKILL.md`, `.claude/commands/guardrails-init-profile.md` |
-| VS Code Copilot | `vscode` | `.vscode/mcp.json` | `.github/copilot-instructions.md`, `.github/skills/threat-modelling/SKILL.md`, `.github/skills/guardrails-profiler/SKILL.md`, `.github/skills/guardrails-selection/SKILL.md`, `.github/hooks/srai-session-policy.json` |
+| Cursor | `cursor` | `.cursor/mcp.json` | `.cursor/rules/srai-security-review.mdc`, `.cursor/rules/guardrails_rule.mdc`, `.cursor/commands/srai-profile.md`, `.cursor/commands/guardrails-init-profile.md`, `.cursor/skills/threat-modelling/SKILL.md`, `.cursor/skills/vibereview-sync/SKILL.md`, `.cursor/hooks.json` |
+| Claude Code | `claude` | `.mcp.json` | `.claude/CLAUDE.md`, `.claude/settings.json`, `.claude/skills/threat-modelling/SKILL.md`, `.claude/skills/vibereview-sync/SKILL.md`, `.claude/skills/guardrails-profiler/SKILL.md`, `.claude/skills/guardrails-selection/SKILL.md`, `.claude/commands/guardrails-init-profile.md` |
+| VS Code Copilot | `vscode` | `.vscode/mcp.json` | `.github/copilot-instructions.md`, `.github/skills/threat-modelling/SKILL.md`, `.github/skills/vibereview-sync/SKILL.md`, `.github/skills/guardrails-profiler/SKILL.md`, `.github/skills/guardrails-selection/SKILL.md`, `.github/hooks/srai-session-policy.json` |
 | Windsurf | `windsurf` | `.windsurf/mcp_config.json` | `.windsurf/rules/srai-security-review.md` |
-| Codex | `codex` | `.codex/config.toml` | `.codex/AGENTS.md`, `.codex/skills/threat-modelling/SKILL.md`, `.codex/skills/guardrails-profiler/SKILL.md`, `.codex/skills/guardrails-selection/SKILL.md`, `.codex/hooks.json`, `.codex/commands/guardrails-init-profile.md` |
+| Codex | `codex` | `.codex/config.toml` | `.codex/AGENTS.md`, `.codex/skills/threat-modelling/SKILL.md`, `.codex/skills/vibereview-sync/SKILL.md`, `.codex/skills/guardrails-profiler/SKILL.md`, `.codex/skills/guardrails-selection/SKILL.md`, `.codex/hooks.json`, `.codex/commands/guardrails-init-profile.md` |
 | Gemini CLI | `gemini` | `.gemini/settings.json` | `GEMINI.md` |
 | Antigravity | `antigravity` | `.gemini/settings.json` | `.agents/rules/srai-security-review.md` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securityreviewai/securityreview-kit",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Bootstrap security-review-mcp for AI IDEs and CLI tools",
   "author": "Debarshi Das <debarshi.das@we45.com>",
   "license": "UNLICENSED",

package/src/generators/mcp/claude.js

@@ -10,7 +10,7 @@ function getClaudeSessionStartHooks() {
         '1. Fetch Vibe Guardrails first using .claude/skills/guardrails-selection/SKILL.md.',
         '2. Run PWNISMS threat modelling using .claude/skills/threat-modelling/SKILL.md.',
         '3. Implement secure code using the hydrated guardrails and threat findings.',
-        '4. Write a structured .md artifact under vibereview/, validate it, and call sync_ai_ide_markdown directly after implementation or threat-model updates.',
+        '4. Read .claude/skills/vibereview-sync/SKILL.md. Write a structured .md artifact under vibereview/, do not read sibling markdown files there just to infer format, validate it, and call sync_ai_ide_markdown directly after implementation or threat-model updates.',
         '',
         'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, VibeReview sync last.',
     ].join('\n');

package/src/generators/mcp/claude.test.js

@@ -21,6 +21,7 @@ test('Claude MCP generator writes .mcp.json, enables the project MCP server, and
     assert.match(settings.SessionStart[0].hooks[0].prompt, /MANDATORY SECURITY GATE/);
     assert.match(settings.SessionStart[0].hooks[0].prompt, /vibereview\//);
     assert.match(settings.SessionStart[0].hooks[0].prompt, /sync_ai_ide_markdown/);
+    assert.match(settings.SessionStart[0].hooks[0].prompt, /vibereview-sync\/SKILL\.md/);
 });
 
 test('Claude MCP generator preserves existing SessionStart hooks', () => {

package/src/generators/rules/claude.js

@@ -6,12 +6,14 @@ import {
     SENTINEL_END,
     SENTINEL_START,
     THREAT_MODELLING_SKILL_REL_DIR,
+    VIBEREVIEW_SYNC_SKILL_REL_DIR,
 } from '../../utils/constants.js';
 import { readText, upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
 import {
     getGuardrailsInitProfileContent,
     getRuleContent,
     getThreatModellingSkillContent,
+    getVibeReviewSyncSkillContent,
 } from './content.js';
 
 function writeGeneratedText(filePath, content) {
@@ -28,6 +30,7 @@ export function generate(cwd, options = {}) {
         ...options,
         guardrailsSelectionSkillDir: GUARDRAILS_SELECTION_SKILL_REL_DIR.claude,
         threatModellingSkillDir: THREAT_MODELLING_SKILL_REL_DIR.claude,
+        vibereviewSyncSkillDir: VIBEREVIEW_SYNC_SKILL_REL_DIR.claude,
     };
     const legacyRootPath = join(cwd, 'CLAUDE.md');
     const filePath = join(cwd, '.claude', 'CLAUDE.md');
@@ -54,6 +57,12 @@ export function generate(cwd, options = {}) {
         getThreatModellingSkillContent(optionsWithSkillDirs),
     );
 
+    const vibereviewSyncSkillPath = join(cwd, VIBEREVIEW_SYNC_SKILL_REL_DIR.claude, 'SKILL.md');
+    const vibereviewSyncSkill = writeGeneratedText(
+        vibereviewSyncSkillPath,
+        getVibeReviewSyncSkillContent(optionsWithSkillDirs),
+    );
+
     const deletedLegacyAgentPath = join(cwd, '.claude', 'agents', 'ctm_sync.md');
     const deletedLegacyAgent = existsSync(deletedLegacyAgentPath)
         ? (unlinkSync(deletedLegacyAgentPath), { filePath: deletedLegacyAgentPath, action: 'deleted' })
@@ -71,6 +80,7 @@ export function generate(cwd, options = {}) {
     return [
         { filePath, action, kind: 'rule' },
         { ...threatSkill, kind: 'skill' },
+        { ...vibereviewSyncSkill, kind: 'skill' },
         { ...guardrailsInit, kind: 'command' },
         ...(deletedLegacyAgent ? [{ ...deletedLegacyAgent, kind: 'cleanup' }] : []),
     ];

package/src/generators/rules/claude.test.js

@@ -13,6 +13,7 @@ test('Claude generator writes .claude/CLAUDE.md, threat skill, and profiling com
     const expectedPaths = [
         '.claude/CLAUDE.md',
         '.claude/skills/threat-modelling/SKILL.md',
+        '.claude/skills/vibereview-sync/SKILL.md',
         '.claude/commands/guardrails-init-profile.md',
     ];
 
@@ -20,11 +21,12 @@ test('Claude generator writes .claude/CLAUDE.md, threat skill, and profiling com
         assert.equal(existsSync(join(cwd, relPath)), true, `${relPath} should exist`);
     }
 
-    assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'command']);
+    assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'skill', 'command']);
 
     const instructions = readFileSync(join(cwd, '.claude/CLAUDE.md'), 'utf8');
     assert.match(instructions, /\.claude\/skills\/guardrails-selection\/SKILL\.md/);
     assert.match(instructions, /\.claude\/skills\/threat-modelling\/SKILL\.md/);
+    assert.match(instructions, /\.claude\/skills\/vibereview-sync\/SKILL\.md/);
     assert.match(instructions, /sync_ai_ide_markdown/);
     assert.match(instructions, /vibereview\//);
 
@@ -32,6 +34,13 @@ test('Claude generator writes .claude/CLAUDE.md, threat skill, and profiling com
     assert.match(threatSkill, /sync_ai_ide_markdown/);
     assert.match(threatSkill, /vibereview\//);
     assert.doesNotMatch(threatSkill, /get_project_profile_description/);
+
+    const vibereviewSkill = readFileSync(join(cwd, '.claude/skills/vibereview-sync/SKILL.md'), 'utf8');
+    assert.match(vibereviewSkill, /Do not read other/i);
+    assert.match(vibereviewSkill, /sync_ai_ide_markdown/);
+    assert.match(vibereviewSkill, /Event Identity/);
+    assert.match(vibereviewSkill, /Practice 1/);
+    assert.match(vibereviewSkill, /practice_name:/);
 });
 
 test('Claude generator migrates the kit-managed root CLAUDE.md block into .claude/CLAUDE.md', () => {

package/src/generators/rules/codex.js

@@ -4,12 +4,14 @@ import {
     GUARDRAILS_PROFILER_SKILL_REL_DIR,
     GUARDRAILS_SELECTION_SKILL_REL_DIR,
     THREAT_MODELLING_SKILL_REL_DIR,
+    VIBEREVIEW_SYNC_SKILL_REL_DIR,
 } from '../../utils/constants.js';
 import { upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
 import {
     getGuardrailsInitProfileContent,
     getRuleContent,
     getThreatModellingSkillContent,
+    getVibeReviewSyncSkillContent,
 } from './content.js';
 
 function writeGeneratedText(filePath, content) {
@@ -35,7 +37,7 @@ function getCodexSessionHookContent() {
         '1. Fetch Vibe Guardrails first using .codex/skills/guardrails-selection/SKILL.md. Resolve the project, call get_guardrails, shortlist relevant guardrails, then call get_guardrail_by_id for the shortlist.',
         '2. Run PWNISMS threat modelling using .codex/skills/threat-modelling/SKILL.md. Explicitly walk Product, Workload, Network, IAM, Secrets, Monitoring, and Supply Chain.',
         '3. Implement secure code using both the hydrated guardrails and PWNISMS findings.',
-        '4. Write a structured .md artifact under vibereview/, validate it, and call sync_ai_ide_markdown directly after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during the final sync.',
+        '4. Read .codex/skills/vibereview-sync/SKILL.md. Write a structured .md artifact under vibereview/, do not read sibling markdown files there just to infer format, validate it, and call sync_ai_ide_markdown directly after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during the final sync.',
         '',
         'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, VibeReview sync last.',
     ].join('\n');
@@ -96,6 +98,7 @@ export function generate(cwd, options = {}) {
         ...options,
         guardrailsSelectionSkillDir: GUARDRAILS_SELECTION_SKILL_REL_DIR.codex,
         threatModellingSkillDir: THREAT_MODELLING_SKILL_REL_DIR.codex,
+        vibereviewSyncSkillDir: VIBEREVIEW_SYNC_SKILL_REL_DIR.codex,
     };
     const filePath = join(cwd, '.codex', 'AGENTS.md');
     const content = getRuleContent(optionsWithSkillDirs);
@@ -107,6 +110,12 @@ export function generate(cwd, options = {}) {
         getThreatModellingSkillContent(optionsWithSkillDirs),
     );
 
+    const vibereviewSyncSkillPath = join(cwd, VIBEREVIEW_SYNC_SKILL_REL_DIR.codex, 'SKILL.md');
+    const vibereviewSyncSkill = writeGeneratedText(
+        vibereviewSyncSkillPath,
+        getVibeReviewSyncSkillContent(optionsWithSkillDirs),
+    );
+
     const deletedLegacyAgent = removeGeneratedText(join(cwd, '.codex', 'agents', 'ctm_sync.toml'));
 
     const hooksPath = join(cwd, '.codex', 'hooks.json');
@@ -124,6 +133,7 @@ export function generate(cwd, options = {}) {
     return [
         { filePath, action, kind: 'rule' },
         { ...threatSkill, kind: 'skill' },
+        { ...vibereviewSyncSkill, kind: 'skill' },
         { ...hooks, kind: 'hooks' },
         { ...guardrailsInit, kind: 'command' },
         ...(deletedLegacyAgent ? [{ ...deletedLegacyAgent, kind: 'cleanup' }] : []),

package/src/generators/rules/codex.test.js

@@ -13,6 +13,7 @@ test('Codex generator writes AGENTS, skills, hooks, and profiling command', () =
     const expectedPaths = [
         '.codex/AGENTS.md',
         '.codex/skills/threat-modelling/SKILL.md',
+        '.codex/skills/vibereview-sync/SKILL.md',
         '.codex/hooks.json',
         '.codex/commands/guardrails-init-profile.md',
     ];
@@ -21,11 +22,12 @@ test('Codex generator writes AGENTS, skills, hooks, and profiling command', () =
         assert.equal(existsSync(join(cwd, relPath)), true, `${relPath} should exist`);
     }
 
-    assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'hooks', 'command']);
+    assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'skill', 'hooks', 'command']);
 
     const instructions = readFileSync(join(cwd, '.codex/AGENTS.md'), 'utf8');
     assert.match(instructions, /\.codex\/skills\/guardrails-selection\/SKILL\.md/);
     assert.match(instructions, /\.codex\/skills\/threat-modelling\/SKILL\.md/);
+    assert.match(instructions, /\.codex\/skills\/vibereview-sync\/SKILL\.md/);
     assert.match(instructions, /sync_ai_ide_markdown/);
     assert.match(instructions, /vibereview\//);
     assert.doesNotMatch(instructions, /\.cursor/);
@@ -39,10 +41,19 @@ test('Codex generator writes AGENTS, skills, hooks, and profiling command', () =
     assert.match(threatSkill, /vibereview\//);
     assert.doesNotMatch(threatSkill, /get_project_profile_description/);
 
+    const vibereviewSkill = readFileSync(join(cwd, '.codex/skills/vibereview-sync/SKILL.md'), 'utf8');
+    assert.match(vibereviewSkill, /do not read other `?\.md`? files in `?vibereview\/`?/i);
+    assert.match(vibereviewSkill, /sync_ai_ide_markdown/);
+    assert.match(vibereviewSkill, /Event Identity/);
+    assert.match(vibereviewSkill, /OWASP Top 10 2025 Mappings/);
+    assert.match(vibereviewSkill, /Practice 1/);
+    assert.match(vibereviewSkill, /practice_name:/);
+
     const hooks = JSON.parse(readFileSync(join(cwd, '.codex/hooks.json'), 'utf8'));
     assert.equal(hooks.hooks.SessionStart[0].hooks[0].type, 'command');
     assert.equal(hooks.hooks.UserPromptSubmit[0].hooks[0].type, 'command');
     assert.match(hooks.hooks.UserPromptSubmit[0].hooks[0].command, /"hookEventName":"UserPromptSubmit"/);
     assert.match(hooks.hooks.UserPromptSubmit[0].hooks[0].command, /vibereview/);
     assert.match(hooks.hooks.UserPromptSubmit[0].hooks[0].command, /sync_ai_ide_markdown/);
+    assert.match(hooks.hooks.UserPromptSubmit[0].hooks[0].command, /vibereview-sync\/SKILL\.md/);
 });

package/src/generators/rules/content.js

@@ -50,6 +50,12 @@ function readTemplate(templateFileName, options = {}) {
         '.cursor/skills/threat-modelling',
         options.threatModellingSkillDir,
     );
+    out = injectPathPlaceholder(
+        out,
+        '{{VIBEREVIEW_SYNC_SKILL_DIR}}',
+        '.cursor/skills/vibereview-sync',
+        options.vibereviewSyncSkillDir,
+    );
 
     return out;
 }
@@ -75,6 +81,13 @@ export function getThreatModellingSkillContent(options = {}) {
     return readTemplate('skill.md', options);
 }
 
+/**
+ * Returns the VibeReview sync skill markdown.
+ */
+export function getVibeReviewSyncSkillContent(options = {}) {
+    return readTemplate(join('vibereview-sync', 'SKILL.md'), options);
+}
+
 /**
  * Returns the vibe guardrails always-applied rule markdown.
  */

package/src/generators/rules/content.md

@@ -27,13 +27,11 @@ For any task that touches auth, authorization, input handling, secrets, network,
    - If PWNISMS reveals a recurring security rule that is not covered by existing guardrails, create and apply an `ide_generated` guardrail in context.
 
 4. **Write and sync the VibeReview markdown last.**
+   - Read and follow `{{VIBEREVIEW_SYNC_SKILL_DIR}}/SKILL.md`.
    - After threat modelling is created or updated, or after guardrails are enforced during implementation, the main agent must write or update a structured `.md` artifact under `vibereview/`.
    - Do not delegate markdown authoring to a subagent. The same agent that performed the work should author the artifact so the context stays intact.
-   - Use a stable path such as `vibereview/<chat_session_id>-<slugified-title-or-event-name>.md`.
-   - Required frontmatter: `chat_session_id`, `summary`, and either `title` or `event_name`. Optional frontmatter: `workflow_name`, `workflow_description`.
-   - Required sections: `Best Practices Achieved`, `Threats Mitigated`, `Secure Code Snippets`, `Guardrails Applied`, and `OWASP Top 10 2025 Mappings`.
+   - Use the skill's structure and validation checklist rather than improvising the markdown format.
    - Reuse the exact existing guardrails shortlisted earlier, include any `ide_generated` guardrails, and only include grounded code snippets from actual code.
-   - Validate the markdown before sync: do not leave out `chat_session_id`, `summary`, threat metadata, guardrail satisfaction, or exact OWASP IDs/names.
    - Call `sync_ai_ide_markdown` directly with the finished markdown artifact before finalizing the task.
    - If sync fails, keep the file in `vibereview/`, report the failure, and do not pretend synchronization succeeded.
 

package/src/generators/rules/cursor.js

@@ -5,12 +5,14 @@ import {
     GUARDRAILS_SELECTION_SKILL_REL_DIR,
     MCP_SERVER_NAME,
     THREAT_MODELLING_SKILL_REL_DIR,
+    VIBEREVIEW_SYNC_SKILL_REL_DIR,
 } from '../../utils/constants.js';
 import { readJson, writeJson, writeText } from '../../utils/fs-helpers.js';
 import {
     getRuleContent,
     getProfileCommandContent,
     getThreatModellingSkillContent,
+    getVibeReviewSyncSkillContent,
     getGuardrailsRuleContent,
     getGuardrailsInitProfileContent,
     getHooksContent,
@@ -81,6 +83,7 @@ export function generate(cwd, options = {}) {
         ...options,
         guardrailsSelectionSkillDir: GUARDRAILS_SELECTION_SKILL_REL_DIR.cursor,
         threatModellingSkillDir: THREAT_MODELLING_SKILL_REL_DIR.cursor,
+        vibereviewSyncSkillDir: VIBEREVIEW_SYNC_SKILL_REL_DIR.cursor,
     };
     const baseRulePath = join(cwd, '.cursor', 'rules', 'srai-security-review.mdc');
     const guardrailsRulePath = join(cwd, '.cursor', 'rules', 'guardrails_rule.mdc');
@@ -97,6 +100,7 @@ export function generate(cwd, options = {}) {
         guardrailsSkillDir: GUARDRAILS_PROFILER_SKILL_REL_DIR.cursor,
     });
     const skillContent = getThreatModellingSkillContent(optionsWithSkillDirs);
+    const vibereviewSyncSkillContent = getVibeReviewSyncSkillContent(optionsWithSkillDirs);
 
     const baseRule = writeCursorRule(
         baseRulePath,
@@ -123,6 +127,9 @@ export function generate(cwd, options = {}) {
     );
     const skillAction = existsSync(skillPath) ? 'updated' : 'created';
     writeText(skillPath, skillContent);
+    const vibereviewSyncSkillPath = join(cwd, VIBEREVIEW_SYNC_SKILL_REL_DIR.cursor, 'SKILL.md');
+    const vibereviewSyncSkillAction = existsSync(vibereviewSyncSkillPath) ? 'updated' : 'created';
+    writeText(vibereviewSyncSkillPath, vibereviewSyncSkillContent);
 
     const hooksContent = getHooksContent();
     const hooksAction = existsSync(hooksPath) ? 'updated' : 'created';
@@ -136,6 +143,7 @@ export function generate(cwd, options = {}) {
         { ...profileCommand, kind: 'command' },
         { ...guardrailsInitProfileCommand, kind: 'command' },
         { filePath: skillPath, action: skillAction, kind: 'skill' },
+        { filePath: vibereviewSyncSkillPath, action: vibereviewSyncSkillAction, kind: 'skill' },
         { filePath: hooksPath, action: hooksAction, kind: 'hooks' },
         { ...cliPermissions, kind: 'config' },
         ...(deletedLegacyRule ? [{ ...deletedLegacyRule, kind: 'cleanup' }] : []),

package/src/generators/rules/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "printf '%s\\n' '{\"additional_context\":\"## MANDATORY SECURITY GATE (Session Policy)\\n\\nFor ANY user request that has security impact (auth, crypto, input handling, secrets, network, data storage, dependencies, new APIs/endpoints, or any code handling untrusted data):\\n\\n**Plan order:**\\n1. **Fetch Vibe Guardrails (first)** - Use .cursor/skills/guardrails-selection/SKILL.md. Analyze the task, call get_guardrails from security-review-mcp to load the broad catalog, shortlist the relevant guardrails, then call get_guardrail_by_id for the shortlist. These exact shortlisted guardrails are the hard constraints on generated code.\\n2. **PWNISMS threat modeling (second)** - Run threat modeling as a guide before writing code. Use .cursor/skills/threat-modelling/SKILL.md. Cross-reference guardrails with PWNISMS findings to identify gaps. Document findings to inform secure implementation.\\n3. **Implement secure code (third)** - Use the threat model findings AND shortlisted guardrails as guides to create secure code. Every must guardrail must be satisfied; no must_not guardrail may be violated.\\n4. **VibeReview sync (last)** - The main agent must write a structured `.md` artifact under `vibereview/`, validate that all required metadata and sections are present, and call `sync_ai_ide_markdown` directly after implementation is done. Include the exact shortlisted guardrails from earlier plus any IDE-generated guardrails in the markdown; do not query guardrails again during sync.\\n\\nNo blocking. No deferral. Guardrails enforce secure code; threat modeling guides the design; the main agent owns the final markdown sync to SRAI. Both sync and guardrail compliance are mandatory and should be part of your to-do.\"}'",
+        "command": "printf '%s\\n' '{\"additional_context\":\"## MANDATORY SECURITY GATE (Session Policy)\\n\\nFor ANY user request that has security impact (auth, crypto, input handling, secrets, network, data storage, dependencies, new APIs/endpoints, or any code handling untrusted data):\\n\\n**Plan order:**\\n1. **Fetch Vibe Guardrails (first)** - Use .cursor/skills/guardrails-selection/SKILL.md. Analyze the task, call get_guardrails from security-review-mcp to load the broad catalog, shortlist the relevant guardrails, then call get_guardrail_by_id for the shortlist. These exact shortlisted guardrails are the hard constraints on generated code.\\n2. **PWNISMS threat modeling (second)** - Run threat modeling as a guide before writing code. Use .cursor/skills/threat-modelling/SKILL.md. Cross-reference guardrails with PWNISMS findings to identify gaps. Document findings to inform secure implementation.\\n3. **Implement secure code (third)** - Use the threat model findings AND shortlisted guardrails as guides to create secure code. Every must guardrail must be satisfied; no must_not guardrail may be violated.\\n4. **VibeReview sync (last)** - Read .cursor/skills/vibereview-sync/SKILL.md. The main agent must write a structured `.md` artifact under `vibereview/`, must not read sibling markdown files there just to infer format, must validate that all required metadata and sections are present, and must call `sync_ai_ide_markdown` directly after implementation is done. Include the exact shortlisted guardrails from earlier plus any IDE-generated guardrails in the markdown; do not query guardrails again during sync.\\n\\nNo blocking. No deferral. Guardrails enforce secure code; threat modeling guides the design; the main agent owns the final markdown sync to SRAI. Both sync and guardrail compliance are mandatory and should be part of your to-do.\"}'",
         "timeout": 5
       }
     ]

package/src/generators/rules/skill.md

@@ -212,28 +212,31 @@ When discussing designs before code exists:
 The main agent writes a structured `.md` artifact under `vibereview/` and uploads it through `sync_ai_ide_markdown`. That markdown should contain:
 
 - **Threat model findings**: threats mitigated, PWNISMS categories, severities, mitigations applied
-- **Best practices achieved**: security patterns followed during implementation
+- **Best practices achieved**: structured practice entries with `practice_name`, `description`, and `category`
 - **Secure code snippets**: security-relevant code with explanations
 - **Guardrails applied**: all guardrails enforced during this session — both existing ones shortlisted earlier via `get_guardrails` + `get_guardrail_by_id` (`source: "existing"`) and new ones the IDE agent created on the fly (`source: "ide_generated"`), each with satisfaction status
 - **Workflow metadata**: `chat_session_id`, `event_name` or `title`, required `summary`, and optional `workflow_name` / `workflow_description`
 
 ### How to sync
 
-1. Write or update a file under `vibereview/`, ideally `vibereview/<chat_session_id>-<slugified-title-or-event-name>.md`.
-2. Put `chat_session_id`, `summary`, and either `title` or `event_name` in frontmatter.
-3. Include the required sections:
+1. Read and follow `{{VIBEREVIEW_SYNC_SKILL_DIR}}/SKILL.md`.
+2. Write or update a file under `vibereview/`, ideally `vibereview/<chat_session_id>-<slugified-title-or-event-name>.md`.
+3. Put `chat_session_id`, `summary`, and either `title` or `event_name` in frontmatter.
+4. Include the required sections:
    - `Best Practices Achieved`
    - `Threats Mitigated`
    - `Secure Code Snippets`
    - `Guardrails Applied`
    - `OWASP Top 10 2025 Mappings`
-4. Validate that:
-   - every threat entry includes `threat_name`, `pwnisms_category`, `severity`, and `mitigation_applied`
+5. Validate that:
+    - every threat entry includes `threat_name`, `pwnisms_category`, `severity`, and `mitigation_applied`
+   - every best-practice entry includes `practice_name`, `description`, and `category`
    - every guardrail includes `title`, `rule_type`, `source`, and `satisfied`
    - OWASP mappings use exact IDs and names
    - snippets are grounded in actual code, not invented text
-5. Call `sync_ai_ide_markdown` directly with the finished markdown artifact.
-6. If sync fails, leave the artifact in `vibereview/` and report the failure clearly.
+   - no sibling `.md` files in `vibereview/` were read just to infer format or content
+6. Call `sync_ai_ide_markdown` directly with the finished markdown artifact.
+7. If sync fails, leave the artifact in `vibereview/` and report the failure clearly.
 
 ---
 

package/src/generators/rules/vibereview-sync/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: vibereview-sync
+description: Write and synchronize a structured VibeReview markdown artifact under vibereview/ for the current security-relevant session. Use after threat modelling or guardrail-enforced implementation.
+---
+
+# VibeReview Markdown Sync
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+Use this skill whenever threat modelling output exists or security guardrail compliance must be synchronized to SRAI.
+
+This skill exists to make the markdown deterministic, grounded, and parseable without depending on a separate subagent. The same agent that performed the work should author the markdown and call `sync_ai_ide_markdown` directly.
+
+## Core Rules
+
+1. Write the artifact under `vibereview/`.
+2. Author the markdown from the current task context only.
+3. Do not read other `.md` files in `vibereview/` to infer structure, copy content, or merge state.
+4. If the current session file path is already known, update that one file directly.
+5. If the current session file does not exist yet, create a new file using a stable name such as:
+
+```text
+vibereview/<chat_session_id>-<slugified-title-or-event-name>.md
+```
+
+6. Validate the markdown before calling `sync_ai_ide_markdown`.
+7. If sync fails, leave the file on disk and report the failure clearly.
+
+## Why You Must Not Read Sibling Files
+
+Other markdown files in `vibereview/` may belong to different sessions, different workflows, or partially complete work. Reading them introduces drift and causes downstream extraction failures.
+
+Treat each VibeReview artifact as self-contained. The current artifact must be fully authorable from:
+
+- the current user request
+- the current session context
+- the threat model produced in this task
+- the exact guardrail shortlist preserved in context
+- the real code snippets touched in this task
+
+## Required Authoring Workflow
+
+### Step 1: Collect the required inputs
+
+Before writing the markdown, confirm you have:
+
+- a stable `chat_session_id`
+- a concise `summary`
+- either `title` or `event_name`
+- the exact existing guardrails shortlisted earlier
+- any `ide_generated` guardrails created during this task
+- grounded threat entries
+- grounded code snippets from actual files
+- exact OWASP Top 10 2025 mappings when applicable
+
+If any required field is missing, resolve it from current context before writing. Do not invent data.
+
+### Step 2: Write YAML frontmatter
+
+The frontmatter should use this shape:
+
+```yaml
+---
+chat_session_id: "cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201"
+workflow_name: "User Auth Hardening"
+workflow_description: "Security improvements for auth flow handling in the current IDE session"
+event_name: "Hardened AI IDE sync ingestion and workflow reuse"
+summary: "This change moved AI IDE sync handling to the server so workflow resolution and event creation happen deterministically after markdown upload. We enforced stable session identity, validated required event fields, and added structured extraction for threats, guardrails, secure code snippets, and OWASP mappings. The endpoint now accepts markdown, returns immediately, and continues processing in the background."
+external_id: "ai-ide-sync-2026-04-21-001"
+---
+```
+
+### Frontmatter rules
+
+- `chat_session_id` is required.
+- `summary` is required.
+- At least one of `event_name` or `title` is required.
+- `workflow_name` is optional.
+- `workflow_description` is optional.
+- `external_id` is optional.
+- If `workflow_name` is omitted, the server may derive it from the title.
+- Do not rely on `developer_name` or `developer_email` in markdown. The server ignores them when authenticated API identity exists.
+
+## Required Markdown Structure
+
+Use this top-level shape:
+
+```md
+# AI IDE Sync Event
+
+## Event Identity
+...
+
+## Summary
+...
+
+# Threats Mitigated
+...
+
+# Best Practices Achieved
+...
+
+# Secure Code Snippets
+...
+
+# Guardrails Applied
+...
+
+# OWASP Top 10 2025 Mappings
+...
+```
+
+The exact heading levels may vary slightly, but the section names should stay stable and obvious.
+
+## Event Identity Section
+
+Preferred structure:
+
+```md
+## Event Identity
+
+- chat_session_id: `cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201`
+- workflow_name: `User Auth Hardening`
+- event_name: `Hardened AI IDE sync ingestion and workflow reuse`
+- external_id: `ai-ide-sync-2026-04-21-001`
+```
+
+## Summary Section
+
+Repeat the summary in prose under `## Summary`.
+
+## Threats Mitigated Section
+
+Each threat entry must include:
+
+- `threat_name`
+- `pwnisms_category`
+- `severity`
+- `mitigation_applied`
+
+When code exists, include a `### Code Snippet` subsection with:
+
+- `file_path`
+- `language`
+- `explanation`
+- a fenced code block containing real code
+
+Preferred example:
+
+````md
+# Threats Mitigated
+
+## Threat 1
+
+- threat_name: Missing session identity can attach events to the wrong workflow
+- pwnisms_category: IAM
+- severity: High
+- mitigation_applied: The server now requires a stable `chat_session_id` and uses it to resolve or create the workflow before persisting the event.
+
+### Code Snippet
+
+- file_path: `app/api/external_ai_ide.py`
+- language: `python`
+- explanation: This prevents ambiguous workflow association and ensures repeated syncs from the same IDE chat session map to the same workflow.
+
+```python
+chat_session_id = str(
+    frontmatter.get("chat_session_id")
+    or extracted.chat_session_id
+    or ""
+).strip()
+
+if not chat_session_id:
+    raise ValueError("chat_session_id could not be resolved from markdown content")
+```
+````
+
+### Threat authoring rules
+
+- Keep each threat clearly separated.
+- Do not collapse multiple threats into one malformed block.
+- Always close fenced code blocks.
+- Never let prose spill into the next threat entry.
+- PWNISMS categories must be one of:
+  - `Product`
+  - `Workload`
+  - `Network`
+  - `IAM`
+  - `Secrets`
+  - `Monitoring`
+  - `Supply Chain`
+- Severity should be one of:
+  - `Critical`
+  - `High`
+  - `Medium`
+  - `Low`
+
+## Best Practices Achieved Section
+
+Use structured practice entries, not plain bullet-only lists.
+
+````md
+# Best Practices Achieved
+
+## Practice 1
+- practice_name: Stable workflow correlation
+- description: Used a stable chat session identifier to ensure repeated syncs map to the same workflow.
+- category: identity
+
+## Practice 2
+- practice_name: Server-side workflow orchestration
+- description: Kept workflow and event creation on the server instead of relying on IDE-side orchestration.
+- category: design
+
+## Practice 3
+- practice_name: Required field validation
+- description: Validated required event identity fields before persisting security review data.
+- category: validation
+````
+
+### Best practice rules
+
+- Each entry should be introduced with a stable heading such as `## Practice 1`, `## Practice 2`, and so on.
+- Each entry must include:
+  - `practice_name`
+  - `description`
+  - `category`
+- Keep the values concise and grounded in the actual work completed.
+- Do not turn this section into freeform paragraphs.
+- Do not reduce this section to plain bullet statements without field names.
+
+## Secure Code Snippets Section
+
+Each snippet entry should include:
+
+- `file_path`
+- `language`
+- `explanation`
+- a fenced code block with real code
+
+Preferred example:
+
+````md
+# Secure Code Snippets
+
+## Snippet 1
+
+- file_path: `app/api/external_ai_ide.py`
+- language: `python`
+- explanation: This is security-relevant because it isolates background processing from the request lifecycle and ensures the authenticated developer identity is propagated server-side.
+
+```python
+async def _process_ai_ide_markdown_ingestion(
+    *,
+    project_id: int,
+    ingestion_id: str,
+    filename: str,
+    markdown_text: str,
+    developer_name: str,
+    developer_email: str,
+) -> None:
+    logger.info(
+        "Starting AI IDE markdown ingestion %s for project %s",
+        ingestion_id,
+        project_id,
+    )
+```
+````
+
+### Secure snippet rules
+
+- Snippets must be real code, not invented examples.
+- Prefer snippets already cited in threat mitigations when they are strongly relevant.
+- Use fenced code blocks.
+- Keep snippets focused and bounded.
+
+## Guardrails Applied Section
+
+Each guardrail entry must include:
+
+- `title`
+- `rule_type`
+- `category`
+- `instruction`
+- `source`
+- `satisfied`
+- `notes`
+
+Preferred example:
+
+```md
+# Guardrails Applied
+
+## Guardrail 1
+
+- title: Require stable AI IDE session identity
+- rule_type: must
+- category: Identity
+- instruction: Every AI IDE sync markdown must include a stable chat_session_id so workflow association is deterministic.
+- source: existing
+- satisfied: true
+- notes: Enforced during markdown ingestion before workflow lookup or workflow creation.
+```
+
+### Guardrail rules
+
+- `rule_type` must be `must` or `must_not`.
+- `source` must be `existing` or `ide_generated`.
+- `satisfied` must be `true` or `false`.
+- Do not drop shortlisted existing guardrails even when unsatisfied.
+- If a guardrail was not fully satisfied, keep it and explain why in `notes`.
+
+## OWASP Top 10 2025 Mappings Section
+
+Use exact IDs and names. Preferred structures:
+
+```md
+# OWASP Top 10 2025 Mappings
+
+- A07: Authentication Failures
+- A06: Insecure Design
+- A10: Mishandling of Exceptional Conditions
+```
+
+or
+
+```md
+# OWASP Top 10 2025 Mappings
+
+- category_id: A07
+  category_name: Authentication Failures
+- category_id: A06
+  category_name: Insecure Design
+```
+
+Allowed values:
+
+- `A01` Broken Access Control
+- `A02` Security Misconfiguration
+- `A03` Software Supply Chain Failures
+- `A04` Cryptographic Failures
+- `A05` Injection
+- `A06` Insecure Design
+- `A07` Authentication Failures
+- `A08` Software or Data Integrity Failures
+- `A09` Security Logging and Alerting Failures
+- `A10` Mishandling of Exceptional Conditions
+
+## Validation Checklist Before Sync
+
+Before calling `sync_ai_ide_markdown`, verify all of the following:
+
+- The file is under `vibereview/`.
+- You did not read sibling markdown files in `vibereview/`.
+- `chat_session_id` exists in frontmatter.
+- `summary` exists in frontmatter.
+- `event_name` or `title` exists in frontmatter.
+- The `Event Identity` section exists.
+- The `Summary` section exists.
+- The `Threats Mitigated` section exists.
+- The `Best Practices Achieved` section exists.
+- The `Secure Code Snippets` section exists.
+- The `Guardrails Applied` section exists.
+- The `OWASP Top 10 2025 Mappings` section exists.
+- Every threat entry is structurally complete.
+- Every code fence is closed.
+- Every snippet is grounded in real code.
+- Every guardrail entry is structurally complete.
+- OWASP IDs and names are exact.
+
+## Final Step
+
+After validation:
+
+1. Save the markdown artifact under `vibereview/`.
+2. Call `sync_ai_ide_markdown` directly with that file's contents or path, depending on the tool interface exposed by the host.
+3. If sync succeeds, report success briefly.
+4. If sync fails, report failure clearly and leave the markdown artifact intact for retry.

package/src/generators/rules/vscode.js

@@ -3,9 +3,10 @@ import { join } from 'node:path';
 import {
     GUARDRAILS_SELECTION_SKILL_REL_DIR,
     THREAT_MODELLING_SKILL_REL_DIR,
+    VIBEREVIEW_SYNC_SKILL_REL_DIR,
 } from '../../utils/constants.js';
 import { upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
-import { getRuleContent, getThreatModellingSkillContent } from './content.js';
+import { getRuleContent, getThreatModellingSkillContent, getVibeReviewSyncSkillContent } from './content.js';
 
 function writeGeneratedText(filePath, content) {
     const action = existsSync(filePath) ? 'updated' : 'created';
@@ -30,7 +31,7 @@ function getCopilotSessionHookContent() {
         '1. Fetch Vibe Guardrails first using .github/skills/guardrails-selection/SKILL.md. Resolve the project, call get_guardrails, shortlist relevant guardrails, then call get_guardrail_by_id for the shortlist.',
         '2. Run PWNISMS threat modelling using .github/skills/threat-modelling/SKILL.md. Explicitly walk Product, Workload, Network, IAM, Secrets, Monitoring, and Supply Chain.',
         '3. Implement secure code using both the hydrated guardrails and PWNISMS findings.',
-        '4. Write a structured .md artifact under vibereview/, validate it, and call sync_ai_ide_markdown directly after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during the final sync.',
+        '4. Read .github/skills/vibereview-sync/SKILL.md. Write a structured .md artifact under vibereview/, do not read sibling markdown files there just to infer format, validate it, and call sync_ai_ide_markdown directly after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during the final sync.',
         '',
         'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, VibeReview sync last.',
     ].join('\n');
@@ -67,6 +68,7 @@ export function generate(cwd, options = {}) {
         ...options,
         guardrailsSelectionSkillDir: GUARDRAILS_SELECTION_SKILL_REL_DIR.vscode,
         threatModellingSkillDir: THREAT_MODELLING_SKILL_REL_DIR.vscode,
+        vibereviewSyncSkillDir: VIBEREVIEW_SYNC_SKILL_REL_DIR.vscode,
     };
     const filePath = join(cwd, '.github', 'copilot-instructions.md');
     const content = getRuleContent(optionsWithSkillDirs);
@@ -78,6 +80,12 @@ export function generate(cwd, options = {}) {
         getThreatModellingSkillContent(optionsWithSkillDirs),
     );
 
+    const vibereviewSyncSkillPath = join(cwd, VIBEREVIEW_SYNC_SKILL_REL_DIR.vscode, 'SKILL.md');
+    const vibereviewSyncSkill = writeGeneratedText(
+        vibereviewSyncSkillPath,
+        getVibeReviewSyncSkillContent(optionsWithSkillDirs),
+    );
+
     const deletedLegacyAgent = removeGeneratedText(join(cwd, '.github', 'agents', 'ctm_sync.agent.md'));
 
     const hooksPath = join(cwd, '.github', 'hooks', 'srai-session-policy.json');
@@ -86,6 +94,7 @@ export function generate(cwd, options = {}) {
     return [
         { filePath, action, kind: 'rule' },
         { ...threatSkill, kind: 'skill' },
+        { ...vibereviewSyncSkill, kind: 'skill' },
         { ...hooks, kind: 'hooks' },
         ...(deletedLegacyAgent ? [{ ...deletedLegacyAgent, kind: 'cleanup' }] : []),
     ];

package/src/generators/rules/vscode.test.js

@@ -13,6 +13,7 @@ test('VS Code Copilot generator writes instructions, skills, and hooks', () => {
     const expectedPaths = [
         '.github/copilot-instructions.md',
         '.github/skills/threat-modelling/SKILL.md',
+        '.github/skills/vibereview-sync/SKILL.md',
         '.github/hooks/srai-session-policy.json',
     ];
 
@@ -20,11 +21,12 @@ test('VS Code Copilot generator writes instructions, skills, and hooks', () => {
         assert.equal(existsSync(join(cwd, relPath)), true, `${relPath} should exist`);
     }
 
-    assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'hooks']);
+    assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'skill', 'hooks']);
 
     const instructions = readFileSync(join(cwd, '.github/copilot-instructions.md'), 'utf8');
     assert.match(instructions, /\.github\/skills\/guardrails-selection\/SKILL\.md/);
     assert.match(instructions, /\.github\/skills\/threat-modelling\/SKILL\.md/);
+    assert.match(instructions, /\.github\/skills\/vibereview-sync\/SKILL\.md/);
     assert.match(instructions, /sync_ai_ide_markdown/);
     assert.match(instructions, /vibereview\//);
     assert.doesNotMatch(instructions, /\.cursor/);
@@ -37,8 +39,16 @@ test('VS Code Copilot generator writes instructions, skills, and hooks', () => {
     assert.match(threatSkill, /vibereview\//);
     assert.doesNotMatch(threatSkill, /get_project_profile_description/);
 
+    const vibereviewSkill = readFileSync(join(cwd, '.github/skills/vibereview-sync/SKILL.md'), 'utf8');
+    assert.match(vibereviewSkill, /Do not read other/i);
+    assert.match(vibereviewSkill, /sync_ai_ide_markdown/);
+    assert.match(vibereviewSkill, /Guardrails Applied/);
+    assert.match(vibereviewSkill, /Practice 1/);
+    assert.match(vibereviewSkill, /practice_name:/);
+
     const hooks = JSON.parse(readFileSync(join(cwd, '.github/hooks/srai-session-policy.json'), 'utf8'));
     assert.equal(hooks.hooks.SessionStart[0].type, 'command');
     assert.match(hooks.hooks.SessionStart[0].command, /vibereview/);
     assert.match(hooks.hooks.SessionStart[0].command, /sync_ai_ide_markdown/);
+    assert.match(hooks.hooks.SessionStart[0].command, /vibereview-sync\/SKILL\.md/);
 });

package/src/utils/constants.js

@@ -83,5 +83,13 @@ export const THREAT_MODELLING_SKILL_REL_DIR = {
     codex: '.codex/skills/threat-modelling',
 };
 
+/** Relative workspace dirs for the VibeReview markdown sync skill (per IDE / CLI). */
+export const VIBEREVIEW_SYNC_SKILL_REL_DIR = {
+    cursor: '.cursor/skills/vibereview-sync',
+    claude: '.claude/skills/vibereview-sync',
+    vscode: '.github/skills/vibereview-sync',
+    codex: '.codex/skills/vibereview-sync',
+};
+
 export const SENTINEL_START = '<!-- securityreview-kit:start -->';
 export const SENTINEL_END = '<!-- securityreview-kit:end -->';