@plaited/development-skills 0.6.5 → 0.8.0

package/README.md

@@ -42,11 +42,11 @@ LSP understands re-exports, aliases, and type relationships.
 ## Install for AI Agents
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/plaited/skills-installer/main/install.sh | bash -s -- --agents <agent-name> --project development-skills
+npx skills add plaited/development-skills
+# or
+bunx skills add plaited/development-skills
 ```
 
-**Agents:** `claude` · `cursor` · `copilot` · `codex` · `gemini` · `windsurf` · `opencode` · `amp` · `goose` · `factory`
-
 ## Commands
 
 | Command | What it does |

package/bin/cli.ts

@@ -20,7 +20,7 @@
  *   bunx @plaited/development-skills lsp-hover src/index.ts 10 5
  *   bunx @plaited/development-skills lsp-find parseConfig
  *   bunx @plaited/development-skills validate-skill .claude/skills/my-skill
- *   bunx @plaited/development-skills scaffold-rules --agent=claude --format=json
+ *   bunx @plaited/development-skills scaffold-rules
  */
 
 import { lspAnalyze } from '../src/lsp-analyze.ts'
@@ -64,7 +64,7 @@ Examples:
   bunx @plaited/development-skills lsp-symbols src/app.ts
   bunx @plaited/development-skills lsp-analyze src/app.ts
   bunx @plaited/development-skills validate-skill .claude/skills/my-skill
-  bunx @plaited/development-skills scaffold-rules --agent=claude --format=json
+  bunx @plaited/development-skills scaffold-rules
 
 Options:
   -h, --help    Show this help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaited/development-skills",
-  "version": "0.6.5",
+  "version": "0.8.0",
   "description": "Development skills for Claude Code - TypeScript LSP, code documentation, and validation tools",
   "license": "ISC",
   "engines": {
@@ -21,7 +21,8 @@
   "files": [
     "bin/",
     "src/",
-    ".plaited/"
+    "rules/",
+    "skills/"
   ],
   "publishConfig": {
     "access": "public"
@@ -48,7 +49,6 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.11",
-    "@modelcontextprotocol/sdk": "1.22.0",
     "@types/bun": "1.3.6",
     "format-package": "7.0.0",
     "lint-staged": "16.2.7",

package/{.plaited/rules → rules}/accuracy.md

@@ -28,4 +28,4 @@
 - Code review: Read files before commenting
 - Patterns: Confirm examples reflect actual usage
 
-See .plaited/rules/testing.md for verification in test contexts.
+See rules/testing.md for verification in test contexts.

package/{.plaited/rules → rules}/modules.md

@@ -9,11 +9,16 @@
 *Fix:* Add `.ts` extension
 
 **Re-export at boundaries** - Parent `feature.ts` re-exports from `feature/feature.ts`
-```
-src/
-├── acp/           # Feature module
-│   └── acp.ts     # Implementation
-└── acp.ts         # Re-exports public API
+
+```mermaid
+graph TD
+    A[src/] --> B[feature/]
+    A --> C[feature.ts]
+    B --> D[feature.ts]
+    B --> E[tests/]
+    E --> F[feature.spec.ts]
+    
+    C -.Re-exports.-> D
 ```
 
 **File organization within modules:**

package/rules/skill-activation.md

@@ -0,0 +1,26 @@
+# Skill Activation
+
+**Evaluate before implementing** - Check available skills for relevance before starting work
+
+**Activation sequence:**
+
+1. **Evaluate** - For each skill in `<available_skills>`, assess: `[skill-name] - YES/NO - [reason]`
+2. **Activate** - Call `Skill(skill-name)` for each relevant skill before proceeding
+3. **Implement** - Begin work only after activation is complete
+
+*Verify:* Did you check available skills before starting implementation?
+*Fix:* Pause, evaluate skills, activate relevant ones, then continue
+
+**Example:**
+```
+- code-patterns: NO - not writing code
+- git-workflow: YES - need commit conventions
+- documentation: YES - writing README
+
+> Skill(git-workflow)
+> Skill(documentation)
+```
+
+**Activation before implementation** - Evaluating skills without calling `Skill()` provides no benefit
+*Verify:* Check that `Skill()` was called for each YES evaluation
+*Fix:* Call `Skill(skill-name)` for skipped activations

package/{.plaited/rules → rules}/testing.md

@@ -14,7 +14,7 @@
 
 **Use real dependencies** - Prefer installed packages over mocks when testing module resolution  
 *Verify:* Review test imports for fake paths  
-*Fix:* Use actual package like `@modelcontextprotocol/sdk/client`
+*Fix:* Use actual package like `typescript`
 
 **Organize with describe** - Group related tests in `describe('feature', () => {...})`  
 *Verify:* Check for flat test structure  

package/{.plaited/skills → skills}/scaffold-rules/SKILL.md

@@ -34,9 +34,8 @@ bunx @plaited/development-skills scaffold-rules
 ```
 
 This will:
-1. Copy rules to `.plaited/rules/` (canonical location)
-2. Create symlinks in `.claude/rules` and `.cursor/rules` (if those directories exist)
-3. Fallback: append links to `AGENTS.md` if no agent directories found
+1. Write rules into `AGENTS.md` (creates if missing, updates between markers if present)
+2. Add `@AGENTS.md` reference to `CLAUDE.md` if it exists without one
 
 ### Step 3: Report to User
 
@@ -51,25 +50,32 @@ Tell the user what was created based on the `actions` output.
 
 ## How It Works
 
+Rules are written directly into `AGENTS.md` between markers:
+
 ```
-.plaited/rules/          ← Canonical location (files copied here)
-    ├── testing.md
-    ├── bun.md
-    └── ...
+<!-- PLAITED-RULES-START -->
+
+## Rules
+
+(rule content inlined here)
 
-.claude/rules -> ../.plaited/rules   ← Symlink (if .claude/ exists)
-.cursor/rules -> ../.plaited/rules   ← Symlink (if .cursor/ exists)
+<!-- PLAITED-RULES-END -->
 ```
 
-| Project has... | Copy | Symlinks | AGENTS.md |
-|----------------|------|----------|-----------|
-| `.plaited/` only | ✓ | None | No |
-| `.claude/` only | ✓ | `.claude/rules` | No |
-| `.cursor/` only | ✓ | `.cursor/rules` | No |
-| `.plaited/` + `.claude/` | ✓ | `.claude/rules` | No |
-| `.plaited/` + `.cursor/` | ✓ | `.cursor/rules` | No |
-| `.plaited/` + `.claude/` + `.cursor/` | ✓ | Both | No |
-| None of the above | ✓ | None | ✓ Append links |
+- **No AGENTS.md**: Creates one with rules section
+- **AGENTS.md without markers**: Appends rules section with markers
+- **AGENTS.md with markers**: Replaces content between markers (preserves user content outside)
+- **CLAUDE.md exists**: Adds `@AGENTS.md` reference if not already present
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Rules duplicated in AGENTS.md | Markers were manually deleted | Remove duplicate section, re-run `scaffold-rules` |
+| Update didn't apply | Only one marker present (start or end) | Ensure both `<!-- PLAITED-RULES-START -->` and `<!-- PLAITED-RULES-END -->` exist, or delete both to get a fresh append |
+| `@AGENTS.md` not added to CLAUDE.md | CLAUDE.md doesn't exist | Create CLAUDE.md first, then re-run |
+
+**Do not** manually edit content between the `PLAITED-RULES-START` and `PLAITED-RULES-END` markers — it will be overwritten on next run.
 
 ## Related Skills
 

package/src/scaffold-rules.ts

@@ -1,46 +1,20 @@
 #!/usr/bin/env bun
 /**
- * Scaffold development rules - Copy bundled rules and create symlinks
+ * Scaffold development rules into AGENTS.md
  *
- * Copies rules from the package to `.plaited/rules/` (canonical location),
- * creates symlinks for `.claude/` and `.cursor/` agent directories,
- * and falls back to appending links in `AGENTS.md` if no agent dirs exist.
+ * Writes rules into AGENTS.md (creates if missing, uses markers for updates).
+ * Adds `@AGENTS.md` reference to CLAUDE.md if it exists without one.
  *
  * @throws When source rules directory cannot be read
- * @throws When target directory cannot be created (permissions)
- * @throws When symlink creation fails (existing file, not directory)
  */
 
-import { mkdir, readdir, readlink, stat, symlink } from 'node:fs/promises'
+import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseArgs } from 'node:util'
 
-/** Agents that get symlinks to .plaited/rules (not .plaited itself) */
-const SYMLINK_AGENTS = ['.claude', '.cursor'] as const
-
-/** All supported agent directories (including .plaited which gets direct copy) */
-const ALL_AGENTS = ['.plaited', ...SYMLINK_AGENTS] as const
-
-/** Canonical rules location */
-const TARGET_RULES = '.plaited/rules' as const
-
-/**
- * NOTE: This tool only scaffolds RULES, not skills.
- * Skills symlinks (.claude/skills -> ../.plaited/skills) are managed separately
- * via the skills-installer or manual setup.
- */
-
-/**
- * Check if path is a directory
- */
-const isDirectory = async (path: string): Promise<boolean> => {
-  try {
-    const s = await stat(path)
-    return s.isDirectory()
-  } catch {
-    return false
-  }
-}
+/** Markers for the rules section in AGENTS.md */
+const RULES_START = '<!-- PLAITED-RULES-START -->'
+const RULES_END = '<!-- PLAITED-RULES-END -->'
 
 /**
  * Main scaffold-rules function
@@ -59,7 +33,7 @@ export const scaffoldRules = async (args: string[]): Promise<void> => {
   const dryRun = values['dry-run'] as boolean | undefined
   const listOnly = values.list as boolean | undefined
 
-  const sourceRules = join(import.meta.dir, '../.plaited/rules')
+  const sourceRules = join(import.meta.dir, '../rules')
   const cwd = process.cwd()
 
   // Get available rules
@@ -74,77 +48,60 @@ export const scaffoldRules = async (args: string[]): Promise<void> => {
 
   const actions: string[] = []
 
-  // Check for agent directories BEFORE copying (since copy creates .plaited/)
-  // This determines whether to fall back to AGENTS.md append
-  let hadAgentDirBeforeScaffold = false
-  for (const agent of ALL_AGENTS) {
-    if (await isDirectory(join(cwd, agent))) {
-      hadAgentDirBeforeScaffold = true
-      break
-    }
-  }
-
-  // 1. Copy rules to .plaited/rules/ (canonical location, serves .plaited agent)
-  const targetDir = join(cwd, TARGET_RULES)
-  if (!dryRun) {
-    await mkdir(targetDir, { recursive: true })
-  }
+  // 1. Write rules into AGENTS.md
+  const agentsMdPath = join(cwd, 'AGENTS.md')
+  const agentsMd = Bun.file(agentsMdPath)
 
+  const ruleEntries: string[] = []
   for (const file of rules) {
-    const src = join(sourceRules, file)
-    const dest = join(targetDir, file)
-    if (!dryRun) {
-      await Bun.write(dest, await Bun.file(src).text())
-    }
-    actions.push(`copy: ${TARGET_RULES}/${file}`)
+    const content = await Bun.file(join(sourceRules, file)).text()
+    ruleEntries.push(content)
   }
+  const rulesContent = ruleEntries.join('\n\n')
+  const rulesSection = `${RULES_START}\n\n## Rules\n\n${rulesContent}\n\n${RULES_END}`
 
-  // 2. Symlink for other agents (.claude, .cursor)
-  for (const agent of SYMLINK_AGENTS) {
-    const agentDir = join(cwd, agent)
-    if (await isDirectory(agentDir)) {
-      const rulesLink = join(agentDir, 'rules')
-
-      // Check if symlink already exists and points to right place
-      try {
-        const existing = await readlink(rulesLink)
-        if (existing === '../.plaited/rules') {
-          actions.push(`skip: ${agent}/rules (symlink exists)`)
-          continue
-        }
-      } catch {
-        // Doesn't exist or not a symlink - proceed to create
-      }
+  if (await agentsMd.exists()) {
+    const content = await agentsMd.text()
+    const startIdx = content.indexOf(RULES_START)
+    const endIdx = content.indexOf(RULES_END)
 
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+      const before = content.slice(0, startIdx)
+      const after = content.slice(endIdx + RULES_END.length)
       if (!dryRun) {
-        await symlink('../.plaited/rules', rulesLink)
+        await Bun.write(agentsMdPath, `${before}${rulesSection}${after}`)
       }
-      actions.push(`symlink: ${agent}/rules -> ../.plaited/rules`)
+      actions.push('update: AGENTS.md (rules section)')
+    } else {
+      if (!dryRun) {
+        await Bun.write(agentsMdPath, `${content}\n${rulesSection}\n`)
+      }
+      actions.push('append: AGENTS.md (rules section)')
+    }
+  } else {
+    if (!dryRun) {
+      await Bun.write(agentsMdPath, `# AGENTS\n\n${rulesSection}\n`)
     }
+    actions.push('create: AGENTS.md (rules section)')
   }
 
-  // 3. Fallback: append to AGENTS.md only if NO agent directories existed before copy
-  if (!hadAgentDirBeforeScaffold) {
-    const agentsMdPath = join(cwd, 'AGENTS.md')
-    const agentsMd = Bun.file(agentsMdPath)
-
-    if (await agentsMd.exists()) {
-      const content = await agentsMd.text()
-      if (content.includes('.plaited/rules')) {
-        actions.push('skip: AGENTS.md (already has rules)')
-      } else {
-        const links = rules.map((f) => `- [${f.replace('.md', '')}](${TARGET_RULES}/${f})`).join('\n')
-        const section = `\n## Rules\n\n${links}\n`
-
-        if (!dryRun) {
-          await Bun.write(agentsMdPath, content + section)
-        }
-        actions.push('append: AGENTS.md (rules section)')
+  // 2. Add @AGENTS.md reference to CLAUDE.md if it exists without one
+  const claudeMdPath = join(cwd, 'CLAUDE.md')
+  const claudeMd = Bun.file(claudeMdPath)
+
+  if (await claudeMd.exists()) {
+    const content = await claudeMd.text()
+    if (/^@AGENTS\.md/m.test(content)) {
+      actions.push('skip: CLAUDE.md (already references @AGENTS.md)')
+    } else {
+      if (!dryRun) {
+        await Bun.write(claudeMdPath, `@AGENTS.md\n\n${content}`)
       }
+      actions.push('update: CLAUDE.md (added @AGENTS.md reference)')
     }
   }
 
-  console.log(JSON.stringify({ dryRun: !!dryRun, targetRules: TARGET_RULES, actions }, null, 2))
+  console.log(JSON.stringify({ dryRun: !!dryRun, actions }, null, 2))
 }
 
 // CLI entry point

package/src/tests/resolve-file-path.spec.ts

@@ -75,27 +75,6 @@ describe('resolveFilePath', () => {
   })
 
   describe('scoped package specifiers', () => {
-    test('resolves scoped package subpath export', () => {
-      // @modelcontextprotocol/sdk/client is a defined export
-      const result = resolveFilePath('@modelcontextprotocol/sdk/client')
-      expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
-      expect(result).toContain('client')
-    })
-
-    test('resolves scoped package server subpath', () => {
-      const result = resolveFilePath('@modelcontextprotocol/sdk/server')
-      expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
-      expect(result).toContain('server')
-    })
-
-    test('resolves scoped package deep subpath with extension', () => {
-      // Deep subpath with .js extension via wildcard export "./*"
-      const path = '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js'
-      const result = resolveFilePath(path)
-      expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
-      expect(result).toContain('bearerAuth')
-    })
-
     test('falls back to cwd for non-existent scoped package', () => {
       const scopedPkg = '@nonexistent/pkg/src/file.ts'
       const result = resolveFilePath(scopedPkg)

package/src/tests/scaffold-rules.spec.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { mkdir, readlink, rm } from 'node:fs/promises'
+import { mkdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { $ } from 'bun'
 
@@ -9,7 +9,6 @@ type ListOutput = {
 
 type ScaffoldOutput = {
   dryRun: boolean
-  targetRules: string
   actions: string[]
 }
 
@@ -19,13 +18,11 @@ describe('scaffold-rules', () => {
   let testDir: string
 
   beforeEach(async () => {
-    // Create a temp directory for each test
     testDir = join(import.meta.dir, `test-scaffold-${Date.now()}`)
     await mkdir(testDir, { recursive: true })
   })
 
   afterEach(async () => {
-    // Clean up temp directory
     await rm(testDir, { recursive: true, force: true })
   })
 
@@ -63,26 +60,14 @@ describe('scaffold-rules', () => {
       const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules --dry-run`.json()
 
       expect(result.dryRun).toBe(true)
-      expect(result.targetRules).toBe('.plaited/rules')
       expect(result.actions).toBeArray()
-    })
-
-    test('shows copy actions for each rule', async () => {
-      const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules --dry-run`.json()
-
-      const copyActions = result.actions.filter((a) => a.startsWith('copy:'))
-      expect(copyActions.length).toBeGreaterThan(0)
-
-      // Should include our compressed rules
-      expect(copyActions.some((a) => a.includes('core.md'))).toBe(true)
-      expect(copyActions.some((a) => a.includes('testing.md'))).toBe(true)
+      expect(result.actions).toContain('create: AGENTS.md (rules section)')
     })
 
     test('does not create files in dry-run mode', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules --dry-run`.json()
 
-      const rulesDir = Bun.file(join(testDir, '.plaited/rules'))
-      expect(await rulesDir.exists()).toBe(false)
+      expect(await Bun.file(join(testDir, 'AGENTS.md')).exists()).toBe(false)
     })
 
     test('short flag -n works', async () => {
@@ -92,109 +77,114 @@ describe('scaffold-rules', () => {
     })
   })
 
-  describe('copy behavior', () => {
-    test('copies rules to .plaited/rules/', async () => {
+  describe('AGENTS.md behavior', () => {
+    test('creates AGENTS.md if it does not exist', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const coreRule = Bun.file(join(testDir, '.plaited/rules/core.md'))
-      expect(await coreRule.exists()).toBe(true)
-
-      const content = await coreRule.text()
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
+      expect(content).toContain('# AGENTS')
+      expect(content).toContain('## Rules')
+      expect(content).toContain('<!-- PLAITED-RULES-START -->')
+      expect(content).toContain('<!-- PLAITED-RULES-END -->')
       expect(content).toContain('# Core Conventions')
     })
 
-    test('copies all compressed rules', async () => {
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
-
-      const expectedRules = ['accuracy', 'bun', 'core', 'documentation', 'modules', 'testing', 'workflow']
-
-      for (const rule of expectedRules) {
-        const ruleFile = Bun.file(join(testDir, `.plaited/rules/${rule}.md`))
-        expect(await ruleFile.exists()).toBe(true)
-      }
-    })
+    test('appends rules with markers to existing AGENTS.md', async () => {
+      await Bun.write(join(testDir, 'AGENTS.md'), '# My Project\n\nCustom content\n')
 
-    test('creates .plaited/rules directory if missing', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const rulesDir = await Bun.file(join(testDir, '.plaited/rules/core.md')).exists()
-      expect(rulesDir).toBe(true)
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
+      expect(content).toStartWith('# My Project\n\nCustom content\n')
+      expect(content).toContain('<!-- PLAITED-RULES-START -->')
+      expect(content).toContain('## Rules')
+      expect(content).toContain('<!-- PLAITED-RULES-END -->')
     })
-  })
 
-  describe('symlink behavior', () => {
-    test('creates symlink for .claude/rules when .claude exists', async () => {
-      // Create .claude directory
-      await mkdir(join(testDir, '.claude'), { recursive: true })
+    test('updates existing markers without overwriting user content', async () => {
+      const initial =
+        '# Project\n\nUser notes\n\n<!-- PLAITED-RULES-START -->\n\n## Rules\n\n- old rule\n\n<!-- PLAITED-RULES-END -->\n\nMore user content\n'
+      await Bun.write(join(testDir, 'AGENTS.md'), initial)
 
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
+      const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      // Check symlink exists and points to right place
-      const linkTarget = await readlink(join(testDir, '.claude/rules'))
-      expect(linkTarget).toBe('../.plaited/rules')
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
+      expect(content).toContain('User notes')
+      expect(content).toContain('More user content')
+      expect(content).not.toContain('old rule')
+      expect(content).toContain('# Core Conventions')
+      expect(result.actions).toContain('update: AGENTS.md (rules section)')
     })
 
-    test('creates symlink for .cursor/rules when .cursor exists', async () => {
-      // Create .cursor directory
-      await mkdir(join(testDir, '.cursor'), { recursive: true })
+    test('appends when only start marker exists (no end marker)', async () => {
+      const malformed = '# Project\n\n<!-- PLAITED-RULES-START -->\n\nOrphan content\n'
+      await Bun.write(join(testDir, 'AGENTS.md'), malformed)
 
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
+      const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      const linkTarget = await readlink(join(testDir, '.cursor/rules'))
-      expect(linkTarget).toBe('../.plaited/rules')
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
+      expect(content).toContain('# Core Conventions')
+      expect(result.actions).toContain('append: AGENTS.md (rules section)')
     })
 
-    test('skips symlink if already exists with correct target', async () => {
-      await mkdir(join(testDir, '.claude'), { recursive: true })
+    test('appends when markers are reversed (end before start)', async () => {
+      const reversed =
+        '# Project\n\n<!-- PLAITED-RULES-END -->\n\nMiddle\n\n<!-- PLAITED-RULES-START -->\n\nOld rules\n'
+      await Bun.write(join(testDir, 'AGENTS.md'), reversed)
 
-      // Run twice
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
       const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      // Second run should skip the symlink
-      const skipAction = result.actions.find((a) => a.includes('.claude/rules') && a.includes('skip'))
-      expect(skipAction).toBeDefined()
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
+      expect(content).toContain('# Core Conventions')
+      expect(result.actions).toContain('append: AGENTS.md (rules section)')
     })
 
-    test('does not create symlink if agent dir does not exist', async () => {
+    test('appends when only end marker exists (no start marker)', async () => {
+      const malformed = '# Project\n\nSome content\n\n<!-- PLAITED-RULES-END -->\n'
+      await Bun.write(join(testDir, 'AGENTS.md'), malformed)
+
       const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      // Should not have any symlink actions
-      const symlinkActions = result.actions.filter((a) => a.startsWith('symlink:'))
-      expect(symlinkActions.length).toBe(0)
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
+      expect(content).toContain('# Core Conventions')
+      expect(result.actions).toContain('append: AGENTS.md (rules section)')
     })
   })
 
-  describe('AGENTS.md fallback', () => {
-    test('appends rules to AGENTS.md when no agent dirs exist', async () => {
-      // Create AGENTS.md without any agent directories
-      await Bun.write(join(testDir, 'AGENTS.md'), '# AGENTS\n\nSome content\n')
+  describe('CLAUDE.md behavior', () => {
+    test('adds @AGENTS.md reference to existing CLAUDE.md', async () => {
+      await Bun.write(join(testDir, 'CLAUDE.md'), '# Claude Config\n\nSome settings\n')
 
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
-      expect(content).toContain('## Rules')
-      expect(content).toContain('.plaited/rules/')
+      const content = await Bun.file(join(testDir, 'CLAUDE.md')).text()
+      expect(content).toStartWith('@AGENTS.md\n\n')
+      expect(content).toContain('# Claude Config')
     })
 
-    test('does not append if agent dir exists', async () => {
-      await Bun.write(join(testDir, 'AGENTS.md'), '# AGENTS\n\nSome content\n')
-      await mkdir(join(testDir, '.plaited'), { recursive: true })
+    test('skips CLAUDE.md if @AGENTS.md reference already exists', async () => {
+      await Bun.write(join(testDir, 'CLAUDE.md'), '@AGENTS.md\n\n# Claude Config\n')
 
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
+      const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
-      // Should not have appended rules section (since .plaited exists)
-      expect(content).not.toContain('## Rules')
+      const skipAction = result.actions.find((a) => a.includes('CLAUDE.md') && a.includes('skip'))
+      expect(skipAction).toBeDefined()
     })
 
-    test('skips if AGENTS.md already has rules', async () => {
-      await Bun.write(join(testDir, 'AGENTS.md'), '# AGENTS\n\nSee .plaited/rules/ for rules\n')
+    test('adds reference when @AGENTS.md only appears inline (not at start of line)', async () => {
+      await Bun.write(join(testDir, 'CLAUDE.md'), '# Config\n\nSee `@AGENTS.md` for details\n')
 
       const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      const skipAction = result.actions.find((a) => a.includes('AGENTS.md') && a.includes('skip'))
-      expect(skipAction).toBeDefined()
+      const content = await Bun.file(join(testDir, 'CLAUDE.md')).text()
+      expect(content).toStartWith('@AGENTS.md\n\n')
+      expect(result.actions).toContain('update: CLAUDE.md (added @AGENTS.md reference)')
+    })
+
+    test('does not create CLAUDE.md if it does not exist', async () => {
+      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
+
+      expect(await Bun.file(join(testDir, 'CLAUDE.md')).exists()).toBe(false)
     })
   })
 
@@ -203,60 +193,25 @@ describe('scaffold-rules', () => {
       const result: ScaffoldOutput = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.json()
 
       expect(result).toHaveProperty('dryRun')
-      expect(result).toHaveProperty('targetRules')
       expect(result).toHaveProperty('actions')
-
       expect(result.dryRun).toBe(false)
-      expect(result.targetRules).toBe('.plaited/rules')
       expect(result.actions).toBeArray()
     })
   })
 
-  describe('symlink readability', () => {
-    test('rules are readable through .claude symlink', async () => {
-      await mkdir(join(testDir, '.claude'), { recursive: true })
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
-
-      // Read through symlink path
-      const content = await Bun.file(join(testDir, '.claude/rules/core.md')).text()
-      expect(content).toContain('# Core Conventions')
-    })
-
-    test('rules are readable through .cursor symlink', async () => {
-      await mkdir(join(testDir, '.cursor'), { recursive: true })
-      await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
-
-      // Read through symlink path
-      const content = await Bun.file(join(testDir, '.cursor/rules/core.md')).text()
-      expect(content).toContain('# Core Conventions')
-    })
-  })
-
-  describe('error handling', () => {
-    test('fails when existing file blocks symlink creation', async () => {
-      await mkdir(join(testDir, '.claude'), { recursive: true })
-      // Create a file where symlink should go
-      await Bun.write(join(testDir, '.claude/rules'), 'not a directory')
-
-      // Should fail when trying to create symlink over existing file
-      const result = await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules 2>&1`.nothrow().text()
-      expect(result).toContain('EEXIST')
-    })
-  })
-
   describe('rule content', () => {
-    test('core.md contains TypeScript conventions', async () => {
+    test('AGENTS.md contains TypeScript conventions', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const content = await Bun.file(join(testDir, '.plaited/rules/core.md')).text()
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
       expect(content).toContain('Type over interface')
       expect(content).toContain('Arrow functions')
     })
 
-    test('testing.md contains test conventions', async () => {
+    test('AGENTS.md contains test conventions', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const content = await Bun.file(join(testDir, '.plaited/rules/testing.md')).text()
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
       expect(content).toContain('test not it')
       expect(content).toContain('No conditional assertions')
     })
@@ -264,7 +219,7 @@ describe('scaffold-rules', () => {
     test('rules include verification patterns', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const content = await Bun.file(join(testDir, '.plaited/rules/core.md')).text()
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
       expect(content).toContain('*Verify:*')
       expect(content).toContain('*Fix:*')
     })
@@ -272,9 +227,7 @@ describe('scaffold-rules', () => {
     test('rules are compressed (no verbose examples)', async () => {
       await $`cd ${testDir} && bun ${binDir}/cli.ts scaffold-rules`.quiet()
 
-      const content = await Bun.file(join(testDir, '.plaited/rules/core.md')).text()
-
-      // Should not have verbose code blocks with Good/Avoid patterns
+      const content = await Bun.file(join(testDir, 'AGENTS.md')).text()
       expect(content).not.toContain('// ✅ Good')
       expect(content).not.toContain('// ❌ Avoid')
     })