@ai-content-space/loopx 0.2.8 → 0.2.10

package/skills/sql-style/references/window-functions.md

@@ -0,0 +1,328 @@
+# Window Functions
+
+## Ranking Functions
+
+```sql
+-- ROW_NUMBER: Sequential numbering within partition
+SELECT
+    customer_id,
+    order_date,
+    total,
+    ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY order_date DESC) as row_num
+FROM orders;
+
+-- Get most recent order per customer
+SELECT *
+FROM (
+    SELECT
+        customer_id,
+        order_id,
+        order_date,
+        total,
+        ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY order_date DESC) as rn
+    FROM orders
+) ranked
+WHERE rn = 1;
+
+-- RANK: Same values get same rank, gaps in sequence
+SELECT
+    student_id,
+    score,
+    RANK() OVER (ORDER BY score DESC) as rank,
+    DENSE_RANK() OVER (ORDER BY score DESC) as dense_rank,
+    ROW_NUMBER() OVER (ORDER BY score DESC) as row_num
+FROM exam_results;
+/*
+score=100: rank=1, dense_rank=1, row_num=1
+score=100: rank=1, dense_rank=1, row_num=2
+score=95:  rank=3, dense_rank=2, row_num=3
+*/
+
+-- NTILE: Divide into N buckets
+SELECT
+    customer_id,
+    total_spent,
+    NTILE(4) OVER (ORDER BY total_spent DESC) as quartile
+FROM customer_lifetime_value;
+```
+
+## Aggregate Window Functions
+
+```sql
+-- Running totals and cumulative sums
+SELECT
+    order_date,
+    daily_revenue,
+    SUM(daily_revenue) OVER (ORDER BY order_date) as cumulative_revenue,
+    AVG(daily_revenue) OVER (
+        ORDER BY order_date
+        ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
+    ) as rolling_7day_avg
+FROM daily_sales;
+
+-- Moving average with RANGE
+SELECT
+    sale_date,
+    amount,
+    AVG(amount) OVER (
+        ORDER BY sale_date
+        RANGE BETWEEN INTERVAL '7 days' PRECEDING AND CURRENT ROW
+    ) as avg_last_7_days
+FROM sales;
+
+-- Partition-specific aggregates
+SELECT
+    product_id,
+    sale_date,
+    quantity,
+    SUM(quantity) OVER (PARTITION BY product_id ORDER BY sale_date) as cumulative_qty,
+    AVG(quantity) OVER (PARTITION BY product_id) as avg_qty_for_product,
+    quantity::FLOAT / SUM(quantity) OVER (PARTITION BY product_id) as pct_of_total
+FROM product_sales;
+```
+
+## LAG and LEAD Functions
+
+```sql
+-- Compare with previous/next row
+SELECT
+    order_date,
+    total,
+    LAG(total) OVER (ORDER BY order_date) as previous_day_total,
+    LEAD(total) OVER (ORDER BY order_date) as next_day_total,
+    total - LAG(total) OVER (ORDER BY order_date) as day_over_day_change
+FROM daily_orders;
+
+-- Find gaps in time series
+SELECT
+    event_date,
+    LAG(event_date) OVER (ORDER BY event_date) as prev_date,
+    event_date - LAG(event_date) OVER (ORDER BY event_date) as days_since_last
+FROM events
+WHERE event_date - LAG(event_date) OVER (ORDER BY event_date) > 7;
+
+-- Session analysis with time gaps
+SELECT
+    user_id,
+    action_time,
+    LAG(action_time) OVER (PARTITION BY user_id ORDER BY action_time) as prev_action,
+    EXTRACT(EPOCH FROM (
+        action_time - LAG(action_time) OVER (PARTITION BY user_id ORDER BY action_time)
+    )) / 60 as minutes_since_last_action,
+    CASE
+        WHEN EXTRACT(EPOCH FROM (
+            action_time - LAG(action_time) OVER (PARTITION BY user_id ORDER BY action_time)
+        )) / 60 > 30 THEN 1
+        ELSE 0
+    END as new_session
+FROM user_actions;
+```
+
+## FIRST_VALUE and LAST_VALUE
+
+```sql
+-- Compare each row to first/last in partition
+SELECT
+    product_id,
+    price_date,
+    price,
+    FIRST_VALUE(price) OVER (
+        PARTITION BY product_id
+        ORDER BY price_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as initial_price,
+    LAST_VALUE(price) OVER (
+        PARTITION BY product_id
+        ORDER BY price_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as current_price,
+    price - FIRST_VALUE(price) OVER (
+        PARTITION BY product_id
+        ORDER BY price_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as price_change_from_start
+FROM product_price_history;
+
+-- NTH_VALUE: Get specific positioned value
+SELECT
+    sale_date,
+    amount,
+    NTH_VALUE(amount, 2) OVER (
+        ORDER BY sale_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as second_day_amount
+FROM daily_sales;
+```
+
+## Frame Specifications
+
+```sql
+-- ROWS vs RANGE difference
+SELECT
+    order_date,
+    amount,
+    -- ROWS: Physical row offset
+    SUM(amount) OVER (
+        ORDER BY order_date
+        ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING
+    ) as sum_5_rows,
+    -- RANGE: Logical value range
+    SUM(amount) OVER (
+        ORDER BY order_date
+        RANGE BETWEEN INTERVAL '2 days' PRECEDING AND INTERVAL '2 days' FOLLOWING
+    ) as sum_5_day_range
+FROM orders;
+
+-- Common frame patterns
+SELECT
+    sale_date,
+    revenue,
+    -- All preceding rows
+    SUM(revenue) OVER (
+        ORDER BY sale_date
+        ROWS UNBOUNDED PRECEDING
+    ) as running_total,
+    -- Last 3 rows including current
+    AVG(revenue) OVER (
+        ORDER BY sale_date
+        ROWS BETWEEN 2 PRECEDING AND CURRENT ROW
+    ) as ma_3,
+    -- Entire partition
+    SUM(revenue) OVER (
+        PARTITION BY EXTRACT(YEAR FROM sale_date)
+    ) as yearly_total,
+    -- Centered window
+    AVG(revenue) OVER (
+        ORDER BY sale_date
+        ROWS BETWEEN 3 PRECEDING AND 3 FOLLOWING
+    ) as centered_ma_7
+FROM sales;
+```
+
+## Advanced Analytics
+
+```sql
+-- Percentile calculations
+SELECT
+    employee_id,
+    salary,
+    PERCENT_RANK() OVER (ORDER BY salary) as pct_rank,
+    CUME_DIST() OVER (ORDER BY salary) as cumulative_dist,
+    PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY salary) OVER () as median_salary,
+    PERCENTILE_DISC(0.9) WITHIN GROUP (ORDER BY salary) OVER () as p90_salary
+FROM employees;
+
+-- Cohort retention analysis
+WITH user_cohorts AS (
+    SELECT
+        user_id,
+        DATE_TRUNC('month', signup_date) as cohort_month,
+        DATE_TRUNC('month', activity_date) as activity_month
+    FROM user_activity
+),
+cohort_sizes AS (
+    SELECT
+        cohort_month,
+        COUNT(DISTINCT user_id) as cohort_size
+    FROM user_cohorts
+    GROUP BY cohort_month
+)
+SELECT
+    uc.cohort_month,
+    uc.activity_month,
+    EXTRACT(MONTH FROM AGE(uc.activity_month, uc.cohort_month)) as months_since_signup,
+    COUNT(DISTINCT uc.user_id) as active_users,
+    cs.cohort_size,
+    ROUND(100.0 * COUNT(DISTINCT uc.user_id) / cs.cohort_size, 2) as retention_pct
+FROM user_cohorts uc
+JOIN cohort_sizes cs ON uc.cohort_month = cs.cohort_month
+GROUP BY uc.cohort_month, uc.activity_month, cs.cohort_size
+ORDER BY uc.cohort_month, months_since_signup;
+
+-- Time-series gap filling
+SELECT
+    date_series.date,
+    COALESCE(s.revenue, 0) as revenue,
+    AVG(s.revenue) OVER (
+        ORDER BY date_series.date
+        ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
+    ) as ma_7day
+FROM generate_series(
+    '2024-01-01'::DATE,
+    '2024-12-31'::DATE,
+    '1 day'::INTERVAL
+) AS date_series(date)
+LEFT JOIN sales s ON date_series.date = s.sale_date;
+```
+
+## Conditional Aggregation with Windows
+
+```sql
+-- Filter within window function
+SELECT
+    product_id,
+    sale_date,
+    quantity,
+    SUM(quantity) FILTER (WHERE quantity > 10) OVER (
+        PARTITION BY product_id
+        ORDER BY sale_date
+    ) as cumulative_large_orders,
+    COUNT(*) FILTER (WHERE quantity > 100) OVER (
+        PARTITION BY product_id
+    ) as total_bulk_orders
+FROM sales;
+
+-- Multiple conditions
+SELECT
+    customer_id,
+    order_date,
+    total,
+    COUNT(*) FILTER (WHERE total > 1000) OVER (
+        PARTITION BY customer_id
+    ) as high_value_order_count,
+    AVG(total) FILTER (WHERE total < 100) OVER (
+        PARTITION BY customer_id
+    ) as avg_small_order_value
+FROM orders;
+```
+
+## Performance Considerations
+
+```sql
+-- Avoid multiple window passes - combine into one
+-- Bad: Multiple scans
+SELECT
+    product_id,
+    (SELECT AVG(price) FROM products) as avg_price,
+    (SELECT MAX(price) FROM products) as max_price
+FROM products;
+
+-- Good: Single window pass
+SELECT DISTINCT
+    AVG(price) OVER () as avg_price,
+    MAX(price) OVER () as max_price
+FROM products;
+
+-- Materialize expensive windows
+CREATE MATERIALIZED VIEW product_rankings AS
+SELECT
+    product_id,
+    category,
+    sales_count,
+    RANK() OVER (PARTITION BY category ORDER BY sales_count DESC) as category_rank,
+    PERCENT_RANK() OVER (ORDER BY sales_count DESC) as overall_percentile
+FROM product_sales_summary;
+
+CREATE INDEX idx_product_rankings_category ON product_rankings(category, category_rank);
+```
+
+## Common Patterns
+
+1. **Top N per Group**: Use ROW_NUMBER() with WHERE rn <= N
+2. **Running Totals**: SUM() OVER (ORDER BY date)
+3. **Moving Averages**: AVG() with ROWS BETWEEN N PRECEDING
+4. **Session Analysis**: LAG() to detect time gaps
+5. **Deduplication**: ROW_NUMBER() OVER (PARTITION BY key ORDER BY priority) WHERE rn = 1
+6. **Percentiles**: PERCENT_RANK() or PERCENTILE_CONT()
+7. **Year-over-Year**: LAG(value, 12) OVER (ORDER BY month)
+8. **Cohort Analysis**: PARTITION BY cohort_date, aggregate over activity periods

package/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Subagent Exec

package/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Test-Driven Development (TDD)

package/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Verification Before Completion

package/src/cli.mjs

@@ -30,7 +30,7 @@ function usage() {
     '  loopx status [slug] [--json]',
     '  loopx next <slug> [--json]',
     '  loopx setup-context',
-    '  loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes] [--dry-run] [--json]',
+    '  loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--add-agent-guidance] [--yes] [--dry-run] [--json]',
     '  loopx doctor [--json]',
     '  loopx migrate',
     '  loopx repair-install',
@@ -60,6 +60,7 @@ async function promptInstallOptions() {
     const targetAnswer = (await rl.question('Install targets (codex, claude, all) [all]: ')).trim().toLowerCase();
     const projectAnswer = (await rl.question('Install Claude project skills instead of user skills? [y/N]: ')).trim().toLowerCase();
     const modeAnswer = (await rl.question('Install mode (copy, symlink) [copy]: ')).trim().toLowerCase();
+    const guidanceAnswer = (await rl.question('Add loopx guidance to Codex AGENTS.md / Claude CLAUDE.md? [y/N]: ')).trim().toLowerCase();
     const proceedAnswer = (await rl.question('Proceed? [y/N]: ')).trim().toLowerCase();
     if (proceedAnswer !== 'y' && proceedAnswer !== 'yes') {
       return null;
@@ -69,6 +70,7 @@ async function promptInstallOptions() {
       targets: target === 'all' ? ['codex', 'claude'] : [target],
       project: projectAnswer === 'y' || projectAnswer === 'yes',
       installMethod: modeAnswer === 'symlink' ? 'symlink' : 'copy',
+      agentGuidance: guidanceAnswer === 'y' || guidanceAnswer === 'yes',
     };
   } finally {
     rl.close();
@@ -83,6 +85,7 @@ function installOptionsFromArgs(options) {
     project: Boolean(options.get('--project')),
     installMethod: options.get('--mode') === 'symlink' ? 'symlink' : 'copy',
     dir: options.get('--dir'),
+    agentGuidance: Boolean(options.get('--add-agent-guidance') || options.get('--add-codex-agents-guidance')),
   };
 }
 

package/src/context-manifest.mjs

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 
+import { discoverLoopxContextArtifacts } from './loopx-context-artifacts.mjs';
 import { inspectWorkspaceContext, resolveWorkspaceContextPaths } from './workspace-context.mjs';
 
 export const CONTEXT_MANIFEST_SCHEMA_VERSION = 1;
@@ -64,6 +65,53 @@ function stableRows(rows) {
     .slice(0, MAX_MANIFEST_ROWS);
 }
 
+async function loopxRepoContextRows(cwd, stage, priorityStart) {
+  const artifacts = await discoverLoopxContextArtifacts(cwd);
+  const rows = [];
+  let priority = priorityStart;
+  if (artifacts.specsRoot) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'repo-specs',
+      path: artifacts.specsRoot,
+      reason: 'long_lived_loopx_specs_directory',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  for (const spec of artifacts.specFiles) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'repo-spec',
+      path: spec.path,
+      reason: 'long_lived_loopx_spec',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  if (artifacts.memorySummary) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'memory-summary',
+      path: artifacts.memorySummary.path,
+      reason: 'curated_loopx_project_memory',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  if (artifacts.memoryIndex) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'memory-index',
+      path: artifacts.memoryIndex.path,
+      reason: 'curated_loopx_memory_retrieval_index',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  return rows;
+}
+
 export async function writeContextManifest(path, rows) {
   const text = stableRows(rows).map((item) => JSON.stringify(item)).join('\n');
   await mkdir(dirname(path), { recursive: true });
@@ -141,6 +189,7 @@ export async function generateBuildContextManifest({ cwd, root, state, slug }) {
     row(cwd, { stage: 'build', kind: 'domain-context', path: contextPaths.domainGlossary, reason: 'domain_vocabulary', priority: 34, required: contextSetup.status !== 'missing' }),
     row(cwd, { stage: 'build', kind: 'agent-domain', path: contextPaths.agentDomain, reason: 'agent_context_rules', priority: 35, required: false }),
     row(cwd, { stage: 'build', kind: 'workspace-config', path: join(cwd, '.loopx', 'config.json'), reason: 'project_rules_spec_sources_and_verification_commands', priority: 36, required: false }),
+    ...await loopxRepoContextRows(cwd, 'build', 37),
   ];
   const manifestPath = buildContextManifestPath(root);
   await writeContextManifest(manifestPath, rows);
@@ -163,7 +212,8 @@ export async function generateReviewContextManifest({ cwd, root, state, slug })
     row(cwd, { stage: 'review', kind: 'build-support', path: join(root, 'build-support'), reason: 'build_gate_evidence', priority: 30, required: false }),
     row(cwd, { stage: 'review', kind: 'agent-domain', path: contextPaths.agentDomain, reason: 'agent_context_rules', priority: 31, required: false }),
     row(cwd, { stage: 'review', kind: 'workspace-config', path: join(cwd, '.loopx', 'config.json'), reason: 'project_rules_spec_sources_and_verification_commands', priority: 32, required: false }),
-    row(cwd, { stage: 'review', kind: 'state', path: join(root, 'state.json'), reason: 'workflow_state', priority: 40 }),
+    ...await loopxRepoContextRows(cwd, 'review', 33),
+    row(cwd, { stage: 'review', kind: 'state', path: join(root, 'state.json'), reason: 'workflow_state', priority: 60 }),
   ];
   const manifestPath = reviewContextManifestPath(root);
   await writeContextManifest(manifestPath, rows);

package/src/install-discovery.mjs

@@ -29,8 +29,13 @@ const LOOPX_SKILLS = [
   'tdd',
   'verify',
   'doc-readability',
+  'requirement-analyzer',
   'go-style',
   'kratos',
+  'api-designer',
+  'architecture-designer',
+  'sql-style',
+  'cli-developer',
 ];
 const LOOPX_INSTALLATION_IDENTITY = 'loopx';
 const LOOPX_MANAGED_SCRIPT_ITEMS = [
@@ -49,6 +54,18 @@ const LOOPX_MANAGED_SCRIPT_ITEMS = [
     targetRelativePath: '.claude/hooks/loopx-workflow-hook.mjs',
   },
 ];
+const LOOPX_AGENT_GUIDANCE_BLOCK_ID = 'specs-and-memory-context';
+const LOOPX_AGENT_GUIDANCE_HEADING = '## loopx Specs And Memory';
+const LOOPX_AGENT_GUIDANCE_CONTENT = [
+  LOOPX_AGENT_GUIDANCE_HEADING,
+  '',
+  'When working in a repository that uses loopx:',
+  '',
+  '- If `docs/loopx/specs/` exists, inspect relevant specs before clarify, spec, plan, implementation, or review. Use `docs/loopx/specs/index.md` as a map when present, but do not require it.',
+  '- If `.loopx/memory/MEMORY.md` exists, read it as curated project memory.',
+  '- If `.loopx/memory/index.jsonl` exists, use it only to find relevant active memory cards.',
+  '- Treat current user instructions and named source documents as highest priority, repo specs as binding long-lived rules, and memory as advisory context.',
+].join('\n');
 const LOOPX_GOVERNED_SOURCE_ITEMS = [
   {
     name: 'loopx-plugin-manifest',
@@ -128,6 +145,19 @@ export function getClaudeSettingsPath(env = process.env) {
   return resolve(env.LOOPX_CLAUDE_SETTINGS_PATH || join(home, '.claude', 'settings.json'));
 }
 
+export function getCodexAgentsPath(env = process.env) {
+  const home = resolve(env.LOOPX_HOME || env.HOME || process.cwd());
+  return resolve(env.LOOPX_CODEX_AGENTS_PATH || join(home, '.codex', 'AGENTS.md'));
+}
+
+export function getClaudeAgentsPath(env = process.env, options = {}) {
+  if (options.project === true) {
+    return resolve(env.LOOPX_INSTALL_CWD || process.cwd(), 'CLAUDE.md');
+  }
+  const home = resolve(env.LOOPX_HOME || env.HOME || process.cwd());
+  return resolve(env.LOOPX_CLAUDE_AGENTS_PATH || join(home, '.claude', 'CLAUDE.md'));
+}
+
 export function getSkillLockPath(env = process.env) {
   return resolve(env.LOOPX_SKILL_LOCK_PATH || join(getAgentsRoot(env), '.skill-lock.json'));
 }
@@ -454,6 +484,85 @@ async function removeInstalledFile(path) {
   await rm(path, { force: true });
 }
 
+function managedBlockMarkers(id) {
+  return {
+    start: `<!-- loopx:managed:block ${id} -->`,
+    end: `<!-- /loopx:managed:block ${id} -->`,
+  };
+}
+
+function renderManagedBlock(id, content) {
+  const markers = managedBlockMarkers(id);
+  return `${markers.start}\n${content.trim()}\n${markers.end}`;
+}
+
+function managedBlockPattern(id) {
+  const escaped = String(id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`<!--\\s*loopx:managed:block\\s+${escaped}\\s*-->[\\s\\S]*?<!--\\s*\\/loopx:managed:block\\s+${escaped}\\s*-->`);
+}
+
+function upsertManagedBlock(existing, id, content) {
+  const nextBlock = renderManagedBlock(id, content);
+  const pattern = managedBlockPattern(id);
+  if (pattern.test(existing)) {
+    const nextContent = existing.replace(pattern, nextBlock);
+    return {
+      content: nextContent,
+      changed: nextContent !== existing,
+      existed: true,
+    };
+  }
+  const trimmed = existing.trimEnd();
+  const contentWithBlock = trimmed
+    ? `${trimmed}\n\n${nextBlock}\n`
+    : `${nextBlock}\n`;
+  return {
+    content: contentWithBlock,
+    changed: true,
+    existed: false,
+  };
+}
+
+export async function installAgentGuidanceFile(path, options = {}) {
+  const content = options.content || LOOPX_AGENT_GUIDANCE_CONTENT;
+  const id = options.id || LOOPX_AGENT_GUIDANCE_BLOCK_ID;
+  const existing = existsSync(path) ? await readFile(path, 'utf8') : '';
+  const existed = existsSync(path);
+  const next = upsertManagedBlock(existing, id, content);
+  if (!next.changed) {
+    return { status: 'already-current', path };
+  }
+  await ensureDir(dirname(path));
+  await writeFile(path, `${next.content.replace(/\s+$/, '')}\n`);
+  return {
+    status: next.existed ? 'updated' : (existed ? 'installed' : 'created'),
+    path,
+  };
+}
+
+function agentGuidanceEnabled(options = {}) {
+  return Boolean(options.agentGuidance || options.codexAgentsGuidance);
+}
+
+export async function installAgentGuidance(env = process.env, options = {}) {
+  const target = options.target || env.LOOPX_INSTALL_TARGET || 'codex';
+  const enabled = agentGuidanceEnabled(options);
+  const result = {};
+  if (target === 'codex' || target === 'all') {
+    const path = getCodexAgentsPath(env);
+    result.codex = enabled
+      ? await installAgentGuidanceFile(path)
+      : { status: 'recommended', path };
+  }
+  if (target === 'claude' || target === 'all') {
+    const path = getClaudeAgentsPath(env, options);
+    result.claude = enabled
+      ? await installAgentGuidanceFile(path)
+      : { status: 'recommended', path };
+  }
+  return result;
+}
+
 async function canonicalTargetOwnership(skillName, env = process.env, options = {}) {
   const targetDir = installedSkillDir(skillName, env);
   const sourceDir = skillSourceDir(skillName, env, options.skillSourceRoot);
@@ -736,11 +845,16 @@ export async function installBundledSkills(env = process.env, options = {}) {
     items: nextTemplateItems,
   });
   const templateGovernance = await inspectTemplateGovernance(baselinePath);
+  const agentGuidance = await installAgentGuidance(env, {
+    ...options,
+    target: options.target || env.LOOPX_INSTALL_TARGET || 'codex',
+  });
   return {
     ok: conflicts.length === 0,
     installed,
     conflicts,
     skipped,
+    agentGuidance,
     templateGovernance,
     inspection: await inspectInstallState(env),
   };