From de7bde514f96f877889a68d3917788b1717dd9b2 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Wed, 6 May 2026 12:49:41 +0200 Subject: [PATCH 1/2] docs: cite contribution-guidelines and directory-coverage; remove stale analysis Cite ai-contribution-guidelines.md (3 Cs framework) and directory-coverage.md (scoped AGENTS.md coverage rationale). Remove references/analysis.md - dated cross-project survey, no longer load-bearing. Signed-off-by: Sebastian Mendel --- skills/agent-rules/SKILL.md | 2 + skills/agent-rules/references/analysis.md | 322 ---------------------- 2 files changed, 2 insertions(+), 322 deletions(-) delete mode 100644 skills/agent-rules/references/analysis.md diff --git a/skills/agent-rules/SKILL.md b/skills/agent-rules/SKILL.md index ad1ba1c..0c22631 100644 --- a/skills/agent-rules/SKILL.md +++ b/skills/agent-rules/SKILL.md @@ -66,6 +66,8 @@ Use `--update` to preserve human-curated content outside `` ma | [`output-structure.md`](references/output-structure.md) | Root/scoped sections | | [`git-hooks-setup.md`](references/git-hooks-setup.md) | Hook framework detection and setup | | [`examples/`](references/examples/) | Complete examples | +| [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" framework for AI contributions (Comprehensible, Consistent, Correct) | +| [`directory-coverage.md`](references/directory-coverage.md) | Full coverage rationale for scoped AGENTS.md files | ## Templates diff --git a/skills/agent-rules/references/analysis.md b/skills/agent-rules/references/analysis.md deleted file mode 100644 index 4e7e4d8..0000000 --- a/skills/agent-rules/references/analysis.md +++ /dev/null @@ -1,322 +0,0 @@ -# AGENTS.md Analysis Across 6 Netresearch Projects - -> **Reference:** This analysis aligns with the [official agents.md specification](https://agents.md/) and [GitHub best practices from 2,500+ repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/). - -## Executive Summary - -**Total AGENTS.md Files Found**: 21 files across 6 projects - -**Patterns Observed**: -1. **Root files are thin** (26-348 lines) with precedence rules and global defaults -2. **Scoped files are focused** on specific subsystems (backend, frontend, CLI, etc.) -3. **Managed header** present in newer files: `` -4. **Consistent structure** following the 9-section schema from your prompt - -## File Distribution - -| Project | Root | Scoped Files | Total Lines (root) | -|---------|------|--------------|-------------------| -| t3x-rte_ckeditor_image | ✅ | Classes/, Documentation/, Resources/, Tests/ | 348 | -| coding_agent_cli_toolset | ✅ | scripts/ | 308 | -| ldap-selfservice-password-changer | ✅ | internal/, internal/web/ | 282 | -| ldap-manager | ✅ | cmd/, internal/, internal/web/, scripts/ | 228 | -| raybeam | ✅ | cmd/, internal/ | 209 | -| simple-ldap-go | ✅ | docs/, examples/, testutil/ | 26 ⭐ **Perfect thin root** | - -## Key Findings - -### 1. **simple-ldap-go** is the Best Example ⭐ - -**Root file** (26 lines): -- Minimal global rules -- Clear precedence statement -- Index of scoped files -- No duplication with scoped content - -```markdown -## Global rules -- Keep diffs small; add tests for new code paths -- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites - -## Minimal pre-commit checks -- Typecheck (all packages): `go build -v ./...` -- Lint/format (file scope): `gofmt -w ` -- Unit tests (fast): `go test -v -race -short -timeout=10s ./...` - -## Index of scoped AGENTS.md -- `./examples/AGENTS.md` — Example applications -- `./testutil/AGENTS.md` — Testing utilities -- `./docs/AGENTS.md` — Documentation -``` - -### 2. Scoped Files Follow 9-Section Schema - -**Example: simple-ldap-go/examples/AGENTS.md**: -1. ✅ Overview -2. ✅ Setup & environment -3. ✅ Build & tests (file-scoped) -4. ✅ Code style & conventions -5. ✅ Security & safety -6. ✅ PR/commit checklist -7. ✅ Good vs. bad examples -8. ✅ When stuck -9. ⚠️ House Rules (rarely used, only when overriding) - -### 3. Managed Header Usage - -**Present in** (newer projects): -- simple-ldap-go (all files) -- ldap-selfservice-password-changer (all files) -- raybeam (some files) - -**Missing in** (older projects): -- t3x-rte_ckeditor_image -- coding_agent_cli_toolset - -**Format**: -```html - -``` - -### 4. Precedence Rules - Consistent Pattern - -All root files establish precedence clearly: - -**Pattern 1** (verbose): -> "This file explains repo-wide conventions and where to find scoped rules. **Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only." - -**Pattern 2** (concise): -> "**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults." - -**Pattern 3** (index-focused): -> "## Precedence & Scoped Files -> Nearest AGENTS.md wins. Use this root for defaults only." - -### 5. Docker-First vs Native-First - -**Docker-first projects** (ldap-selfservice-password-changer, ldap-manager): -```markdown -### Setup -**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev) - -# Docker (recommended) -docker compose --profile dev up - -# Native development -pnpm install -``` - -**Native-first projects** (simple-ldap-go, t3x-rte_ckeditor_image): -```markdown -### Setup -**Prerequisites**: Go 1.24, golangci-lint - -# Install -go mod download -``` - -### 6. Language-Specific Patterns - -**Go Projects** (simple-ldap-go, ldap-manager, raybeam): -- Minimal pre-commit: `go build -v ./...`, `gofmt -w`, `go test -short` -- Go version in global rules (1.24, 1.25) -- golangci-lint for comprehensive checks - -**PHP Project** (t3x-rte_ckeditor_image): -- Composer scripts for CI pipeline -- PHPStan + PHP-CS-Fixer + Rector -- Make targets preferred over composer commands - -**Hybrid Projects** (ldap-selfservice-password-changer): -- Separate sections for Go backend vs TypeScript frontend -- Scoped AGENTS.md for `internal/` (Go) and `internal/web/` (TS) -- pnpm for package management (strict version) - -### 7. Quick Start Patterns - -**Best practice** (ldap-selfservice-password-changer): -```markdown -## Quick Navigation -- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services -- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend -``` - -**Alternative** (simple-ldap-go): -```markdown -## Index of scoped AGENTS.md -- `./examples/AGENTS.md` — Example applications and usage patterns -- `./testutil/AGENTS.md` — Testing utilities and container management -``` - -### 8. House Rules Implementation - -**Global defaults** typically include: -- Commits: Conventional Commits, small PRs (~≤300 LOC) -- Type-safety: Strict types when supported -- SOLID, KISS, DRY, YAGNI principles -- SemVer for versioning -- No secrets in VCS -- Structured logging -- WCAG AA for UI projects - -**Scoped overrides** (rare): -- Different test coverage targets per module -- Module-specific commit conventions -- Technology-specific style guides - -### 9. Common Gaps Across Projects - -❌ **Missing .envrc** in most projects (your prompt requires it) -❌ **Missing .editorconfig** in some projects -❌ **Husky + commitlint** not universally adopted -❌ **lint-staged** not implemented in older projects -❌ **CI parity section** often missing (should reference GitHub Actions) - -## Recommendations for Your Skill - -### Essential Features - -1. **Template Selection**: - - Thin root (simple-ldap-go style) ⭐ - - Verbose root (ldap-selfservice-password-changer style) - - Auto-detect based on project size - -2. **Project Type Detection**: - - Go: Look for `go.mod`, detect version from `go.mod` directive - - PHP: Look for `composer.json`, detect TYPO3 from dependencies - - TypeScript: Look for `tsconfig.json`, detect strict mode - - Hybrid: Detect multiple languages, recommend scoped files - -3. **Scoped File Generation**: - - **Required scopes**: backend/, frontend/, internal/ - - **Optional scopes**: cmd/, scripts/, examples/, docs/, testutil/ - - **Auto-create** if directory exists and has ≥5 files - -4. **Content Extraction**: - - **Makefile**: Extract targets with `##` comments → Build & Test Commands - - **package.json scripts**: Extract npm/pnpm commands - - **go.mod**: Extract Go version → Prerequisites - - **composer.json scripts**: Extract PHP quality commands - - **GitHub Actions**: Extract CI checks → PR/commit checklist - -5. **Managed Header**: - - Always add to new files - - Preserve in existing files - - Update timestamp on regeneration - -6. **Precedence Rules**: - - Auto-add "Nearest AGENTS.md wins" statement - - Generate index of scoped files in root - - Link from root to scoped files - -### Skill Structure Recommendation - -``` -agents-skill/ -├── SKILL.md -├── README.md -├── templates/ -│ ├── root-thin.md # simple-ldap-go style (recommended) -│ ├── root-verbose.md # ldap-selfservice style -│ ├── scoped-backend.md # Go/PHP backend -│ ├── scoped-frontend.md # TypeScript/JS frontend -│ ├── scoped-cli.md # CLI tools -│ ├── scoped-docs.md # Documentation -│ ├── scoped-tests.md # Testing utilities -│ └── sections/ # Modular sections -│ ├── header.md # Managed header template -│ ├── precedence.md # Precedence statement -│ ├── setup.md # Setup section -│ ├── build-commands.md # Build & test commands -│ ├── code-style.md # Code style guidelines -│ ├── security.md # Security practices -│ ├── pr-checklist.md # PR/commit checklist -│ ├── examples.md # Good vs bad examples -│ └── when-stuck.md # When stuck guidance -├── scripts/ -│ ├── generate-agents.sh # Main generator -│ ├── detect-project.sh # Auto-detect project type -│ ├── extract-commands.sh # Extract from Makefile/package.json -│ └── validate-structure.sh # Validate generated files -└── references/ - ├── examples/ # Real-world examples - │ ├── go-library.md # simple-ldap-go - │ ├── go-web-app.md # ldap-manager - │ ├── php-typo3.md # t3x-rte_ckeditor_image - │ └── hybrid-app.md # ldap-selfservice-password-changer - └── best-practices.md # AGENTS.md writing guide -``` - -### Key Differentiators - -✅ **Thin root by default** (not verbose like some projects) -✅ **Auto-scope detection** (create scoped files when needed) -✅ **Command extraction** (don't make user write commands manually) -✅ **Managed header** (mark files as agent-maintained) -✅ **Language-agnostic** (works with Go, PHP, TypeScript, Python, etc.) -✅ **Idempotent** (can be re-run without breaking existing structure) - -## Sample Output Comparison - -### Your Prompt's Expected Output - -**Root AGENTS.md** (following simple-ldap-go pattern): -```markdown - - -# AGENTS.md (root) - -**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only. - -## Global rules -- Keep PRs small (~≤300 net LOC) -- Conventional Commits: type(scope): subject -- Ask before: heavy deps, full e2e, repo rewrites -- Never commit secrets or PII - -## Minimal pre-commit checks -- Typecheck: [auto-detected command] -- Lint: [auto-detected command] -- Format: [auto-detected command] -- Tests: [auto-detected command] - -## Index of scoped AGENTS.md -- `./internal/AGENTS.md` — Go backend services -- `./internal/web/AGENTS.md` — TypeScript frontend - -## When instructions conflict -Nearest AGENTS.md wins. User prompts override files. -``` - -**Scoped AGENTS.md** (e.g., internal/AGENTS.md): -```markdown - - -# AGENTS.md — Backend Services - -## Overview -[Auto-generated description of internal/ directory purpose] - -## Setup & environment -[Auto-detected from go.mod, .env.example] - -## Build & tests (prefer file-scoped) -[Auto-extracted from Makefile, go commands] - -## Code style & conventions -[Auto-detected from golangci-lint config, gofmt] - -## Security & safety -[Standard Go security practices + project-specific] - -## PR/commit checklist -[Auto-extracted from GitHub Actions, Makefile] - -## Good vs. bad examples -[Template with placeholders to fill] - -## When stuck -- Check root AGENTS.md for global rules -- Review sibling modules for patterns -``` - From fd9329552938f3b0634b597d51a5901790732187 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Wed, 6 May 2026 13:15:44 +0200 Subject: [PATCH 2/2] fix: correct 3 Cs framework labels to match reference Signed-off-by: Sebastian Mendel --- skills/agent-rules/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/agent-rules/SKILL.md b/skills/agent-rules/SKILL.md index 0c22631..34e0056 100644 --- a/skills/agent-rules/SKILL.md +++ b/skills/agent-rules/SKILL.md @@ -66,7 +66,7 @@ Use `--update` to preserve human-curated content outside `` ma | [`output-structure.md`](references/output-structure.md) | Root/scoped sections | | [`git-hooks-setup.md`](references/git-hooks-setup.md) | Hook framework detection and setup | | [`examples/`](references/examples/) | Complete examples | -| [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" framework for AI contributions (Comprehensible, Consistent, Correct) | +| [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" framework for AI contributions (Comprehension, Context, Continuity) | | [`directory-coverage.md`](references/directory-coverage.md) | Full coverage rationale for scoped AGENTS.md files | ## Templates