@plaited/development-skills 0.6.0 → 0.6.1

package/.plaited/rules/code-review.md

@@ -13,7 +13,7 @@ Before completing a code review, run these validation scripts:
 
 ### AgentSkills Validation
 
-When working with AgentSkills directories (`.claude/skills/`, `.cursor/skills/`, `.factory/skills/`, etc.):
+When working with AgentSkills directories (`.plaited/skills/`, `.claude/skills/`, `.cursor/skills/`, `.factory/skills/`, etc.):
 
 {{#if development-skills}}
 **Validate structure:**

package/.plaited/rules/documentation.md

@@ -0,0 +1,41 @@
+# Documentation Standards
+
+## TSDoc Requirements
+
+Public APIs require comprehensive TSDoc documentation following these conventions:
+
+- **No `@example` sections** - Tests serve as living examples
+- **Use `@internal` marker** - Mark non-public APIs explicitly
+- **Always use `type`** - Prefer type aliases over interfaces
+
+### TSDoc Template
+
+```typescript
+/**
+ * Brief description of what this does
+ *
+ * @remarks
+ * Additional context, usage notes, or implementation details.
+ *
+ * @param options - Description of the parameter
+ * @returns Description of return value
+ *
+ * @public
+ */
+```
+
+## Diagrams
+
+Use Mermaid diagrams only (not ASCII art):
+
+```markdown
+\```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+\```
+```
+
+**Avoid**: ASCII box-drawing characters (`┌`, `│`, `└`, `─`, etc.)
+
+**Rationale:** Token efficiency, clearer semantic meaning, easier maintenance.

package/.plaited/rules/git-workflow.md

@@ -1,8 +1,3 @@
-<!--
-RULE TEMPLATE - Distributed via scaffold-rules skill
-Variables: {{LINK:*}}
--->
-
 # Git Workflow
 
 ## Commit Message Format

package/.plaited/rules/github.md

@@ -58,7 +58,7 @@ gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '
 **Step 4: Address ALL feedback**
 Create a checklist and address each item:
 - [ ] Human reviewer comments
-- [ ] Claude Code review comments
+- [ ] Agentic Code review comments
 - [ ] GitHub Advanced Security alerts (ReDoS, injection, etc.)
 - [ ] GitHub Code Quality comments (dead code, useless assignments)
 - [ ] Inline review suggestions
@@ -68,7 +68,7 @@ Create a checklist and address each item:
 | Source | API/Location | Description |
 |--------|--------------|-------------|
 | Human reviewers | `gh pr view --json reviews` | Code owners, team members |
-| Claude Code | `gh pr view --json comments` | AI-generated review (login: `claude`) |
+| AI code review | `gh pr view --json comments` | AI-generated review |
 | GitHub Advanced Security | `gh api .../code-scanning/alerts` | Security vulnerabilities (ReDoS, injection) |
 | GitHub Code Quality | `gh api .../pulls/.../comments` | Code quality issues (login: `github-code-quality[bot]`) |
 | Inline suggestions | `gh api .../pulls/.../comments` | Line-specific review comments |
@@ -76,9 +76,9 @@ Create a checklist and address each item:
 ### Filtering by Author
 
 ```bash
-# Get all automated reviews from PR
+# Get all automated reviews from PR (adjust regex for your AI reviewer logins)
 gh pr view <number> --repo <owner>/<repo> --json reviews --jq '
-  .reviews[] | select(.author.login | test("github-|claude")) | {author: .author.login, state: .state}
+  .reviews[] | select(.author.login | test("github-|bot")) | {author: .author.login, state: .state}
 '
 
 # Get specific inline comment by ID

package/.plaited/rules/module-organization.md

@@ -1,8 +1,3 @@
-<!--
-RULE TEMPLATE - Distributed via scaffold-rules skill
-Variables: {{#if bun}}
--->
-
 # Module Organization
 
 ## No Index Files
@@ -43,9 +38,7 @@ Only use `main.ts` if the package truly has multiple co-equal entry points that
 
 ## Explicit Import Extensions
 
-{{#if bun}}
 Always include `.ts` extensions in imports. Bun runs TypeScript natively—no compilation required:
-{{/if}}
 
 ```typescript
 // ✅ Good

package/.plaited/rules/testing.md

@@ -1,8 +1,3 @@
-<!--
-RULE TEMPLATE - Distributed via scaffold-rules skill
-Variables: {{#if agent:claude}}
--->
-
 # Testing
 
 Use Bun's built-in test runner for unit and integration tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaited/development-skills",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Development skills for Claude Code - TypeScript LSP, code documentation, and validation tools",
   "license": "ISC",
   "engines": {

package/src/scaffold-rules.ts

@@ -6,8 +6,8 @@
  * and outputs JSON for agent consumption.
  *
  * All agents use `.plaited/rules/` as the unified default location.
- * The output includes marker-wrapped sections for both CLAUDE.md and AGENTS.md,
- * allowing programmatic updates without destroying user content.
+ * AGENTS.md serves as the single source of truth for rules content,
+ * while CLAUDE.md simply references it via @AGENTS.md syntax.
  *
  * Options:
  * - --rules-dir, -d: Custom rules directory path (overrides default .plaited/rules)
@@ -15,8 +15,8 @@
  * - --list, -l: List available rules without full output
  *
  * Output includes:
- * - claudeMdSection: Marker-wrapped section with @ syntax for CLAUDE.md
  * - agentsMdSection: Marker-wrapped section with markdown links for AGENTS.md
+ * - claudeMdReference: Short reference snippet pointing to @AGENTS.md
  * - templates: Processed rule content for each selected rule
  *
  * Template syntax:
@@ -95,10 +95,10 @@ export type ProcessedTemplate = {
  */
 export type ScaffoldOutput = {
   rulesPath: string
-  /** Marker-wrapped section with @ syntax for CLAUDE.md */
-  claudeMdSection: string
   /** Marker-wrapped section with markdown links for AGENTS.md */
   agentsMdSection: string
+  /** Short reference snippet for CLAUDE.md pointing to AGENTS.md */
+  claudeMdReference: string
   templates: Record<string, ProcessedTemplate>
 }
 
@@ -214,38 +214,34 @@ const processTemplate = (content: string, context: TemplateContext): string => {
 }
 
 /**
- * Generate marker-wrapped section for CLAUDE.md with @ syntax
+ * Generate marker-wrapped reference snippet for CLAUDE.md
  *
  * @remarks
- * Claude Code uses `@path/to/file.md` syntax to reference rule files.
+ * Claude Code uses `@file.md` syntax to include file contents.
+ * This generates a short reference pointing to AGENTS.md as the single source of truth.
  * The markers allow this section to be updated without affecting other content.
  */
-const generateClaudeMdSection = (templates: Record<string, ProcessedTemplate>, rulesPath: string): string => {
+const generateClaudeMdReference = (): string => {
   const lines = [
     MARKERS.start,
     '',
     '## Project Rules',
     '',
-    `This project uses modular development rules stored in \`${rulesPath}/\`.`,
-    'Each rule file covers a specific topic:',
+    'See @AGENTS.md for shared development rules.',
     '',
+    MARKERS.end,
   ]
 
-  for (const [_ruleId, template] of Object.entries(templates)) {
-    lines.push(`- @${rulesPath}/${template.filename} - ${template.description}`)
-  }
-
-  lines.push('')
-  lines.push(MARKERS.end)
-
   return lines.join('\n')
 }
 
 /**
- * Generate marker-wrapped section for AGENTS.md with markdown links
+ * Generate marker-wrapped section for AGENTS.md with dual format
  *
  * @remarks
- * AGENTS.md format uses standard markdown links to reference rule files.
+ * AGENTS.md uses both formats for maximum compatibility:
+ * - `@path` syntax for Claude Code to load file contents
+ * - `[name](path)` markdown links for other tools and GitHub rendering
  * The markers allow this section to be updated without affecting other content.
  */
 const generateAgentsMdSection = (templates: Record<string, ProcessedTemplate>, rulesPath: string): string => {
@@ -260,7 +256,8 @@ const generateAgentsMdSection = (templates: Record<string, ProcessedTemplate>, r
   ]
 
   for (const [ruleId, template] of Object.entries(templates)) {
-    lines.push(`- [${ruleId}](${rulesPath}/${template.filename}) - ${template.description}`)
+    // Dual format: @ syntax for Claude Code, markdown link for other tools
+    lines.push(`- @${rulesPath}/${template.filename} - [${ruleId}](${rulesPath}/${template.filename})`)
   }
 
   lines.push('')
@@ -358,15 +355,15 @@ export const scaffoldRules = async (args: string[]): Promise<void> => {
     }
   }
 
-  // Generate marker-wrapped sections for both CLAUDE.md and AGENTS.md
-  const claudeMdSection = generateClaudeMdSection(templates, rulesPath)
+  // Generate marker-wrapped section for AGENTS.md and reference for CLAUDE.md
   const agentsMdSection = generateAgentsMdSection(templates, rulesPath)
+  const claudeMdReference = generateClaudeMdReference()
 
   // Build output
   const output: ScaffoldOutput = {
     rulesPath,
-    claudeMdSection,
     agentsMdSection,
+    claudeMdReference,
     templates,
   }
 

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

@@ -10,8 +10,8 @@ type Template = {
 
 type ScaffoldOutput = {
   rulesPath: string
-  claudeMdSection: string
   agentsMdSection: string
+  claudeMdReference: string
   templates: Record<string, Template>
 }
 
@@ -121,42 +121,138 @@ describe('scaffold-rules', () => {
       expect(result.rulesPath).toBe('.plaited/rules')
     })
 
-    test('includes claudeMdSection with markers and @ syntax', async () => {
+    test('includes claudeMdReference with markers and @AGENTS.md', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      expect(result.claudeMdSection).toContain('<!-- PLAITED-RULES-START -->')
-      expect(result.claudeMdSection).toContain('<!-- PLAITED-RULES-END -->')
-      expect(result.claudeMdSection).toContain('@.plaited/rules/')
-      expect(result.claudeMdSection).toContain('## Project Rules')
+      expect(result.claudeMdReference).toContain('<!-- PLAITED-RULES-START -->')
+      expect(result.claudeMdReference).toContain('<!-- PLAITED-RULES-END -->')
+      expect(result.claudeMdReference).toContain('@AGENTS.md')
+      expect(result.claudeMdReference).toContain('## Project Rules')
     })
 
-    test('includes agentsMdSection with markers and markdown links', async () => {
+    test('includes agentsMdSection with markers and dual format', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
 
       expect(result.agentsMdSection).toContain('<!-- PLAITED-RULES-START -->')
       expect(result.agentsMdSection).toContain('<!-- PLAITED-RULES-END -->')
-      expect(result.agentsMdSection).toContain('[')
+      // Should have @ syntax for Claude Code
+      expect(result.agentsMdSection).toContain('@.plaited/rules/')
+      // Should have markdown links for other tools
       expect(result.agentsMdSection).toContain('](.plaited/rules/')
       expect(result.agentsMdSection).toContain('## Rules')
     })
 
-    test('claudeMdSection lists all selected rules', async () => {
+    test('claudeMdReference does not list individual rules', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
 
-      for (const template of Object.values(result.templates)) {
-        expect(result.claudeMdSection).toContain(`@.plaited/rules/${template.filename}`)
-      }
+      // claudeMdReference should be a simple reference to AGENTS.md, not a list of rules
+      expect(result.claudeMdReference).not.toContain('.plaited/rules/')
+      expect(result.claudeMdReference).toContain('@AGENTS.md')
     })
 
-    test('agentsMdSection lists all selected rules', async () => {
+    test('agentsMdSection lists all selected rules in dual format', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
 
       for (const [ruleId, template] of Object.entries(result.templates)) {
+        // Each rule should have both @ syntax and markdown link
+        expect(result.agentsMdSection).toContain(`@.plaited/rules/${template.filename}`)
         expect(result.agentsMdSection).toContain(`[${ruleId}](.plaited/rules/${template.filename})`)
       }
     })
   })
 
+  describe('claudeMdReference behavior', () => {
+    test('has exact expected content structure', async () => {
+      const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
+
+      // Verify the exact structure of claudeMdReference
+      const lines = result.claudeMdReference.split('\n')
+      expect(lines[0]).toBe('<!-- PLAITED-RULES-START -->')
+      expect(lines[1]).toBe('')
+      expect(lines[2]).toBe('## Project Rules')
+      expect(lines[3]).toBe('')
+      expect(lines[4]).toBe('See @AGENTS.md for shared development rules.')
+      expect(lines[5]).toBe('')
+      expect(lines[6]).toBe('<!-- PLAITED-RULES-END -->')
+    })
+
+    test('is constant regardless of rules selected', async () => {
+      const allRules: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
+      const oneRule: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules testing`.json()
+      const twoRules: ScaffoldOutput =
+        await $`bun ${binDir}/cli.ts scaffold-rules --rules testing --rules accuracy`.json()
+
+      // claudeMdReference should be identical in all cases
+      expect(oneRule.claudeMdReference).toBe(allRules.claudeMdReference)
+      expect(twoRules.claudeMdReference).toBe(allRules.claudeMdReference)
+    })
+
+    test('is constant regardless of rules-dir', async () => {
+      const defaultPath: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
+      const customPath: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules-dir=.cursor/rules`.json()
+      const anotherPath: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules-dir=custom/path`.json()
+
+      // claudeMdReference should be identical regardless of rules-dir
+      expect(customPath.claudeMdReference).toBe(defaultPath.claudeMdReference)
+      expect(anotherPath.claudeMdReference).toBe(defaultPath.claudeMdReference)
+    })
+
+    test('uses shared markers with agentsMdSection', async () => {
+      const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
+
+      // Both sections should use the same markers for consistency
+      const startMarker = '<!-- PLAITED-RULES-START -->'
+      const endMarker = '<!-- PLAITED-RULES-END -->'
+
+      expect(result.claudeMdReference).toContain(startMarker)
+      expect(result.claudeMdReference).toContain(endMarker)
+      expect(result.agentsMdSection).toContain(startMarker)
+      expect(result.agentsMdSection).toContain(endMarker)
+    })
+  })
+
+  describe('agentsMdSection with filtered rules', () => {
+    test('only includes selected rules in dual format', async () => {
+      const result: ScaffoldOutput =
+        await $`bun ${binDir}/cli.ts scaffold-rules --rules testing --rules bun-apis`.json()
+
+      // Should contain selected rules (both @ and markdown formats)
+      expect(result.agentsMdSection).toContain('@.plaited/rules/testing.md')
+      expect(result.agentsMdSection).toContain('[testing]')
+      expect(result.agentsMdSection).toContain('@.plaited/rules/bun-apis.md')
+      expect(result.agentsMdSection).toContain('[bun-apis]')
+
+      // Should NOT contain other rules
+      expect(result.agentsMdSection).not.toContain('@.plaited/rules/accuracy.md')
+      expect(result.agentsMdSection).not.toContain('[accuracy]')
+      expect(result.agentsMdSection).not.toContain('@.plaited/rules/git-workflow.md')
+    })
+
+    test('has valid structure with single rule in dual format', async () => {
+      const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules testing`.json()
+
+      expect(result.agentsMdSection).toContain('<!-- PLAITED-RULES-START -->')
+      expect(result.agentsMdSection).toContain('## Rules')
+      // Both formats present
+      expect(result.agentsMdSection).toContain('@.plaited/rules/testing.md')
+      expect(result.agentsMdSection).toContain('[testing](.plaited/rules/testing.md)')
+      expect(result.agentsMdSection).toContain('<!-- PLAITED-RULES-END -->')
+    })
+
+    test('has empty rules list when no rules match', async () => {
+      const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules nonexistent`.nothrow().json()
+
+      // Should still have valid structure with markers
+      expect(result.agentsMdSection).toContain('<!-- PLAITED-RULES-START -->')
+      expect(result.agentsMdSection).toContain('## Rules')
+      expect(result.agentsMdSection).toContain('<!-- PLAITED-RULES-END -->')
+
+      // But no rule references (neither @ nor markdown)
+      expect(result.agentsMdSection).not.toMatch(/@\.plaited\/rules\/.*\.md/)
+      expect(result.agentsMdSection).not.toMatch(/\[.*\]\(\.plaited\/rules\/.*\.md\)/)
+    })
+  })
+
   describe('template content', () => {
     test('git-workflow uses standard commit format', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules`.json()
@@ -194,17 +290,20 @@ describe('scaffold-rules', () => {
       expect(result.rulesPath).toBe('.cursor/rules')
     })
 
-    test('claudeMdSection uses custom path', async () => {
+    test('claudeMdReference is path-independent', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules-dir=.cursor/rules`.json()
 
-      expect(result.claudeMdSection).toContain('@.cursor/rules/')
-      expect(result.claudeMdSection).not.toContain('.plaited/rules/')
+      // claudeMdReference always references AGENTS.md regardless of rules path
+      expect(result.claudeMdReference).toContain('@AGENTS.md')
+      expect(result.claudeMdReference).not.toContain('.cursor/rules')
     })
 
-    test('agentsMdSection uses custom path', async () => {
+    test('agentsMdSection uses custom path in both formats', async () => {
       const result: ScaffoldOutput = await $`bun ${binDir}/cli.ts scaffold-rules --rules-dir=.cursor/rules`.json()
 
-      expect(result.agentsMdSection).toContain('.cursor/rules/')
+      // Both @ syntax and markdown links should use custom path
+      expect(result.agentsMdSection).toContain('@.cursor/rules/')
+      expect(result.agentsMdSection).toContain('](.cursor/rules/')
       expect(result.agentsMdSection).not.toContain('.plaited/rules/')
     })
 
@@ -278,8 +377,8 @@ describe('scaffold-rules', () => {
 
       // Should return valid output with empty templates
       expect(result.templates).toEqual({})
-      expect(result.claudeMdSection).toContain('<!-- PLAITED-RULES-START -->')
-      expect(result.claudeMdSection).toContain('<!-- PLAITED-RULES-END -->')
+      expect(result.claudeMdReference).toContain('<!-- PLAITED-RULES-START -->')
+      expect(result.claudeMdReference).toContain('<!-- PLAITED-RULES-END -->')
     })
 
     test('description extraction falls back for heading-only content', async () => {