zhongwei/gh-netresearch-claude-code-marketplace-skills-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:43:17 +08:00
commit 8967d326a7
30 changed files with 5154 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "agents",
"description": "Generate and maintain AGENTS.md files following the public agents.md convention. Creates thin root files with precedence rules, scoped files for subsystems, auto-extracts commands from build tools, and supports Go, PHP, TypeScript, and Python projects with language-specific templates.",
"version": "1.1.0-20251125",
"author": {
"name": "Netresearch DTT GmbH",
"email": "info@netresearch.de"
},
"skills": [
"./"
]
}

19
.gitignore vendored Normal file
View File

@@ -0,0 +1,19 @@
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# OS
.DS_Store
Thumbs.db
# Temporary
*.tmp
*.bak
.cache/
# Test output
test-output/
*.test.md

18
LICENSE Normal file
View File

@@ -0,0 +1,18 @@
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 2025 Netresearch DTT GmbH
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# agents
Generate and maintain AGENTS.md files following the public agents.md convention. Creates thin root files with precedence rules, scoped files for subsystems, auto-extracts commands from build tools, and supports Go, PHP, TypeScript, and Python projects with language-specific templates.

390
SKILL.md Normal file
View File

@@ -0,0 +1,390 @@
---
name: agents
version: 1.1.0
description: Generate and maintain AGENTS.md files following the public agents.md convention. Use when creating documentation for AI agent workflows, onboarding guides, or when standardizing agent interaction patterns across projects.
license: Complete terms in LICENSE.txt
---
# AGENTS.md Generator Skill
Generate and maintain AGENTS.md files following the public agents.md convention.
## What This Skill Does
Creates hierarchical AGENTS.md documentation for software projects:
- **Thin root files** (~30 lines) with precedence rules and global defaults
- **Scoped files** for subsystems (backend/, frontend/, internal/, cmd/, etc.)
- **Auto-extracted commands** from Makefile, package.json, composer.json, go.mod
- **Managed headers** marking files as agent-maintained with timestamps
- **Language-specific templates** for Go, PHP, TypeScript, Python, and hybrid projects
- **Idempotent updates** that preserve existing structure
Based on analysis of 21 real AGENTS.md files across Netresearch projects.
## When to Use This Skill
- **New projects**: Establish baseline AGENTS.md structure
- **Existing projects**: Standardize agent documentation
- **Team onboarding**: Provide AI assistants with project context
- **Multi-repo consistency**: Apply same standards across repositories
- **Documentation updates**: Refresh after major changes
## Usage
### Generate for Current Project
```bash
# Basic generation (thin root + auto-detected scopes)
/tmp/agents-skill/scripts/generate-agents.sh .
# Dry-run to preview what will be created
/tmp/agents-skill/scripts/generate-agents.sh . --dry-run
# Verbose output with detection details
/tmp/agents-skill/scripts/generate-agents.sh . --verbose
```
### Template Styles
```bash
# Thin root (default, ~30 lines, simple-ldap-go style)
/tmp/agents-skill/scripts/generate-agents.sh . --style=thin
# Verbose root (~100-200 lines, ldap-selfservice style)
/tmp/agents-skill/scripts/generate-agents.sh . --style=verbose
```
### Update Existing Files
```bash
# Update timestamps and refresh auto-extracted content
/tmp/agents-skill/scripts/generate-agents.sh . --update
# Force regeneration (overwrites existing, keeps structure)
/tmp/agents-skill/scripts/generate-agents.sh . --force
```
### Validation
```bash
# Validate existing AGENTS.md structure
/tmp/agents-skill/scripts/validate-structure.sh .
# Check for missing scoped files
/tmp/agents-skill/scripts/detect-scopes.sh .
```
## Supported Project Types
### Languages & Frameworks
- **Go**: Libraries, web apps (Fiber/Echo/Gin), CLI tools (Cobra/urfave/cli)
- **PHP**: Composer packages, TYPO3 extensions, Laravel/Symfony apps
- **TypeScript/JavaScript**: React, Next.js, Vue, Node.js, Express
- **Python**: pip, poetry, pipenv, Django, Flask, FastAPI
- **Hybrid**: Multi-language projects (auto-creates scoped files per stack)
### Detection Signals
| Signal | Detection |
|--------|-----------|
| `go.mod` | Go project, extracts version |
| `composer.json` | PHP project, detects TYPO3/Laravel |
| `package.json` | Node.js project, detects framework |
| `pyproject.toml` | Python project, detects poetry/ruff |
| `Makefile` | Extracts targets with `##` comments |
| `.github/workflows/` | Extracts CI checks |
| `docker-compose.yml` | Docker-first setup |
## Output Structure
### Thin Root (Default)
**~30 lines** following `simple-ldap-go` pattern:
```markdown
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->
# 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 from build tools]
- Lint: [auto-detected from linters]
- Format: [auto-detected from formatters]
- Tests: [auto-detected from test runners]
## Index of scoped AGENTS.md
- `./backend/AGENTS.md` — Backend services
- `./frontend/AGENTS.md` — Frontend application
## When instructions conflict
Nearest AGENTS.md wins. User prompts override files.
```
### Scoped Files (9-Section Schema)
Each scoped file follows this structure:
1. **Overview**: Purpose of this subsystem
2. **Setup & environment**: Prerequisites, installation
3. **Build & tests**: File-scoped commands (preferred)
4. **Code style & conventions**: Language-specific standards
5. **Security & safety**: Security practices
6. **PR/commit checklist**: Pre-commit requirements
7. **Good vs. bad examples**: Concrete code samples
8. **When stuck**: Where to find help
9. **House Rules** (optional): Overrides of global rules
### Managed Header
All generated files include:
```html
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
```
This marks files as agent-maintained and provides update tracking.
## Auto-Detection Features
### Project Type Detection
```bash
$ /tmp/agents-skill/scripts/detect-project.sh .
{
"type": "go-web-app",
"language": "go",
"version": "1.24",
"build_tool": "make",
"has_docker": true,
"quality_tools": ["golangci-lint", "gofmt"],
"test_framework": "testing",
"ci": "github-actions"
}
```
### Scope Detection
Automatically creates scoped AGENTS.md for directories with ≥5 source files:
```bash
$ /tmp/agents-skill/scripts/detect-scopes.sh .
{
"scopes": [
{"path": "internal", "type": "backend-go", "files": 15},
{"path": "cmd", "type": "cli", "files": 3},
{"path": "examples", "type": "examples", "files": 8}
]
}
```
### Command Extraction
Extracts actual commands from build tools:
```bash
$ /tmp/agents-skill/scripts/extract-commands.sh .
{
"typecheck": "go build -v ./...",
"lint": "golangci-lint run ./...",
"format": "gofmt -w .",
"test": "go test -v -race -short ./...",
"build": "go build -o bin/app ./cmd/app"
}
```
## Examples
Real-world examples from Netresearch projects in `references/examples/`:
### Go Library (simple-ldap-go)
**Perfect thin root** (26 lines):
- Minimal global rules
- File-scoped commands
- Clear scope index
- No duplication
### Hybrid App (ldap-selfservice-password-changer)
**Go backend + TypeScript frontend**:
- Root with quick navigation
- Scoped: `internal/AGENTS.md` (Go)
- Scoped: `internal/web/AGENTS.md` (TypeScript + Tailwind)
### PHP TYPO3 Extension (t3x-rte_ckeditor_image)
**Composer-based with Make targets**:
- Root with emoji headers
- Scoped: `Classes/AGENTS.md` (PHP backend)
- Scoped: `Documentation/AGENTS.md` (RST docs)
- Scoped: `Tests/AGENTS.md` (PHPUnit tests)
### Python CLI (coding_agent_cli_toolset)
**Script-heavy toolset**:
- Root with precedence focus
- Scoped: `scripts/AGENTS.md`
## Customization
### Override Templates
Copy templates to project and modify:
```bash
cp /tmp/agents-skill/templates/root-thin.md ./.agents-templates/root.md
# Edit ./.agents-templates/root.md
/tmp/agents-skill/scripts/generate-agents.sh . --template-dir=./.agents-templates
```
### Add Custom Sections
Templates support placeholders:
- `{{PROJECT_NAME}}` - From package.json/composer.json/go.mod
- `{{PROJECT_TYPE}}` - Auto-detected type
- `{{LANGUAGE}}` - Primary language
- `{{BUILD_COMMANDS}}` - Extracted commands
- `{{QUALITY_TOOLS}}` - Detected linters/formatters
- `{{TIMESTAMP}}` - Current date (YYYY-MM-DD)
## Idempotent Updates
Safe to run multiple times:
1. Checks existing files
2. Preserves custom content in sections
3. Updates only auto-extracted parts (commands, versions)
4. Refreshes timestamps
5. Adds missing sections
6. No changes if nothing updated
## Validation
```bash
# Check structure compliance
/tmp/agents-skill/scripts/validate-structure.sh .
# Validates:
# ✅ Root is thin (≤50 lines or has index)
# ✅ All scoped files have 9 sections
# ✅ Managed headers present
# ✅ Precedence statement in root
# ✅ Links from root to scoped files work
# ✅ No duplicate content between root and scoped
```
## Integration with Claude Code
### As Marketplace Skill
Add to `claude-code-marketplace`:
```json
{
"name": "agents",
"description": "Generate AGENTS.md files following public convention",
"version": "1.0.0",
"source": "./skills/agents"
}
```
### Direct Usage
```bash
# Clone skill
git clone https://github.com/netresearch/agents-skill.git /tmp/agents-skill
# Generate for current project
/tmp/agents-skill/scripts/generate-agents.sh .
```
## Structure Standards Application
**When creating root AGENTS.md files**, keep them thin (~30 lines):
- Include clear precedence statement at top
- Define minimal global rules only (PR size, commit format, safety)
- List pre-commit checks (typecheck, lint, format, test)
- Provide scope index linking to scoped files
- Move detailed setup to scoped files (not in root)
- Move language-specific patterns to scoped files (not in root)
- Move extensive examples to scoped files (not in root)
**When determining scope boundaries**, create scoped files for:
- Different technology stacks: `backend/`, `frontend/`, `api/`
- Package visibility: `internal/`, `pkg/` (Go projects)
- CLI tools: `cmd/`, `cli/`
- Utility scripts: `scripts/`
- Documentation and examples: `docs/`, `examples/`
- Testing infrastructure: `tests/`, `testutil/`
**When extracting commands**, automate extraction from:
- Makefile targets with `##` comments
- package.json scripts section
- composer.json scripts section
- CI workflow files (.github/workflows/, .gitlab-ci.yml)
- Never manually duplicate commands that exist in build tools
## Troubleshooting
### No Commands Detected
```bash
# Check what was detected
/tmp/agents-skill/scripts/extract-commands.sh . --verbose
# Fallback: Specify commands manually
/tmp/agents-skill/scripts/generate-agents.sh . --commands='{"lint":"make lint","test":"make test"}'
```
### Wrong Project Type
```bash
# Override auto-detection
/tmp/agents-skill/scripts/generate-agents.sh . --type=go-library
# Supported types:
# go-library, go-web-app, go-cli
# php-library, php-typo3, php-laravel
# typescript-react, typescript-node
# python-library, python-cli
# hybrid
```
### Scoped File Not Created
```bash
# Check scope detection
/tmp/agents-skill/scripts/detect-scopes.sh .
# Manually specify scopes
/tmp/agents-skill/scripts/generate-agents.sh . --scopes=internal,cmd,examples
```
## Contributing
Improvements welcome! Common additions:
- New language templates
- Better command extraction
- Additional validation rules
- More real-world examples
## License
GPL-2.0-or-later (matching other Netresearch skills)
## References
- **Analysis**: `references/analysis.md` - Analysis of 21 real AGENTS.md files
- **Prompt**: `references/prompt.md` - Original generation prompt/rule
- **Examples**: `references/examples/` - Real-world AGENTS.md files
- **Best Practices**: `references/best-practices.md` - Writing guide

104
STATUS.md Normal file
View File

@@ -0,0 +1,104 @@
# agents-skill Creation Status
**Created**: 2025-10-18
**Status**: ✅ COMPLETE - Fully functional skill ready for use
## ✅ Completed
1. **Directory Structure**: Created all necessary directories
2. **SKILL.md**: Complete skill metadata and documentation
3. **`.gitignore**`: Standard ignores
4. **Analysis**: Complete analysis of 21 real AGENTS.md files
5. **Templates**: root-thin.md, root-verbose.md, and scoped templates (Go, PHP, TypeScript, CLI)
6. **Scripts**: All generator and detection scripts implemented
7. **Examples**: Real-world AGENTS.md files from 4 projects copied
8. **README.md**: Comprehensive usage guide
9. **LICENSE**: GPL-2.0-or-later
10. **Git Repository**: Initialized with initial commit
## 📦 Implementation Summary
### Templates (✅ Complete)
- ✅ `templates/root-thin.md` - Thin root template (simple-ldap-go style, ~30 lines)
- ✅ `templates/root-verbose.md` - Verbose root template (~100-200 lines)
- ✅ `templates/scoped/backend-go.md` - Go backend 9-section template
- ✅ `templates/scoped/backend-php.md` - PHP backend 9-section template
- ✅ `templates/scoped/frontend-typescript.md` - TypeScript frontend 9-section template
- ✅ `templates/scoped/cli.md` - CLI tools 9-section template
### Scripts (✅ Complete)
- ✅ `scripts/generate-agents.sh` - Main orchestrator with --dry-run, --update, --force, --style
- ✅ `scripts/detect-project.sh` - Auto-detect language, version, framework, tools
- ✅ `scripts/detect-scopes.sh` - Find directories needing scoped AGENTS.md
- ✅ `scripts/extract-commands.sh` - Parse Makefile, package.json, composer.json
- ✅ `scripts/validate-structure.sh` - Validate structure compliance
- ✅ `scripts/lib/template.sh` - Template rendering helper functions
### Examples (✅ Complete)
- ✅ `references/examples/simple-ldap-go/` - Perfect thin root (26 lines)
- ✅ `references/examples/ldap-selfservice/` - Hybrid Go + TypeScript
- ✅ `references/examples/t3x-rte-ckeditor-image/` - PHP TYPO3 extension
- ✅ `references/examples/coding-agent-cli/` - Python CLI toolset
- ✅ `references/analysis.md` - Comprehensive analysis of 21 files
### Documentation (✅ Complete)
- ✅ `README.md` - Comprehensive usage guide with examples
- ✅ `SKILL.md` - Complete skill metadata and documentation
- ✅ `LICENSE` - GPL-2.0-or-later
- ✅ `.gitignore` - Standard ignores
### Git Repository (✅ Complete)
- ✅ Initialized with all files
- ✅ Initial commit with descriptive message
- ✅ Ready for push to GitHub
## 🚀 Next Steps
1. ✅ **Push to GitHub**: Create repository at `https://github.com/netresearch/agents-skill`
2. ✅ **Add to marketplace**: Update sync configuration and workflow
3. ✅ **Test on real projects**: Validate with simple-ldap-go, t3x-rte_ckeditor_image, etc.
## 📝 Final Directory Structure
```
/tmp/agents-skill/
├── .git/ ✅ Git repository initialized
├── .gitignore ✅ Standard ignores
├── LICENSE ✅ GPL-2.0-or-later
├── README.md ✅ Comprehensive usage guide
├── SKILL.md ✅ Complete skill metadata
├── STATUS.md ✅ This file
├── templates/
│ ├── root-thin.md ✅ Thin root template
│ ├── root-verbose.md ✅ Verbose root template
│ ├── scoped/
│ │ ├── backend-go.md ✅ Go backend template
│ │ ├── backend-php.md ✅ PHP backend template
│ │ ├── cli.md ✅ CLI tools template
│ │ └── frontend-typescript.md ✅ TypeScript frontend template
│ └── sections/ (future: modular sections)
├── scripts/
│ ├── detect-project.sh ✅ Project type detection
│ ├── detect-scopes.sh ✅ Scope detection
│ ├── extract-commands.sh ✅ Build command extraction
│ ├── generate-agents.sh ✅ Main generator
│ ├── validate-structure.sh ✅ Structure validation
│ └── lib/
│ └── template.sh ✅ Template rendering helpers
└── references/
├── analysis.md ✅ Comprehensive analysis
└── examples/
├── simple-ldap-go/ ✅ Perfect thin root example
├── ldap-selfservice/ ✅ Hybrid Go + TypeScript
├── t3x-rte-ckeditor-image/ ✅ PHP TYPO3 extension
└── coding-agent-cli/ ✅ Python CLI toolset
```
## ✅ Skill is Complete and Ready for Use
The agents-skill is fully implemented and ready to generate AGENTS.md files for any supported project type (Go, PHP, TypeScript, Python, hybrid).
**Usage**:
```bash
/tmp/agents-skill/scripts/generate-agents.sh /path/to/project
```

45
claudedocs/refactoring-summary.md Normal file
View File

@@ -0,0 +1,45 @@
# SKILL.md Refactoring Summary
**Date:** 2025-11-14
**Version Change:** 1.0.0 → 1.1.0
**Skill:** agents
## Changes Applied
### Pattern 2: Converted "## Best Practices" to Imperative Form
- **Before:** "## Best Practices" with subsections containing mixed Do's/Don'ts
- **After:** "## Structure Standards Application" with imperative "When X" format
#### Keep Root Thin
- **Before:** "Good" and "Bloated" examples with checkmarks/X marks
- **After:** "When creating root AGENTS.md files" with action-oriented instructions
- Converted positive examples to directives
- Converted negative examples to avoidance instructions
#### Scope Appropriately
- **Before:** "Create scoped files for:" with bullet list
- **After:** "When determining scope boundaries" with action-oriented guidance
- Same content, imperative presentation
#### Auto-Extract Commands
- **Before:** "Don't manually write commands if they exist in:"
- **After:** "When extracting commands, automate extraction from:"
- Positive framing with clear directive
## Impact Analysis
**Readability:** Improved - clearer action-oriented instructions
**Consistency:** Aligned with skill-creator best practices
**Usability:** Enhanced - readers know when and how to apply each pattern
**Structure:** Maintained all examples while improving presentation
## Files Modified
- `/SKILL.md` (lines 1-400)
## Verification
- Version number updated in YAML frontmatter: ✓
- Best Practices converted to imperative form: ✓
- All guidance remains intact: ✓
- No broken internal references: ✓

21
composer.json Normal file
View File

@@ -0,0 +1,21 @@
{
"name": "netresearch/agents-skill",
"description": "Generate and maintain AGENTS.md files following the public agents.md convention",
"type": "ai-agent-skill",
"license": "GPL-2.0-or-later",
"authors": [
{
"name": "Netresearch DTT GmbH",
"email": "plugins@netresearch.de",
"homepage": "https://www.netresearch.de/",
"role": "Manufacturer"
}
],
"require": {
"netresearch/composer-agent-skill-plugin": "*"
},
"keywords": [
"ai-agent",
"skill"
]
}

153
plugin.lock.json Normal file
View File

@@ -0,0 +1,153 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:netresearch/claude-code-marketplace:skills/agents",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "67fb566c43c2efc08d5c3df47b44f56d2f3e6477",
"treeHash": "3caa289a90b8282766f02e812cd98175c73ad5a46a126850b6214ab053cb28e6",
"generatedAt": "2025-11-28T10:27:20.284373Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "agents",
"description": "Generate and maintain AGENTS.md files following the public agents.md convention. Creates thin root files with precedence rules, scoped files for subsystems, auto-extracts commands from build tools, and supports Go, PHP, TypeScript, and Python projects with language-specific templates.",
"version": "1.1.0-20251125"
},
"content": {
"files": [
{
"path": "LICENSE",
"sha256": "b4aa20b52533f8ab363e465f07d9e26ad92dac6e250b650c8947c99d6ee466e0"
},
{
"path": "STATUS.md",
"sha256": "a656b07890efb13577aa36e08becaded05e86e72e4fe09cc147d2edff921b71d"
},
{
"path": "README.md",
"sha256": "78949a278b3d0162e0665bfb5ecf5894f4052b0fabc76a62c0183782997d426a"
},
{
"path": ".gitignore",
"sha256": "03d5d046fa175e5d6ea564d562ffbd2a555e964b0a91d3ce04af8bc54f3a54ab"
},
{
"path": "SKILL.md",
"sha256": "ee7db7e9bdc267a2ae2e45fae3996af707eee3be49b9a9387e1286c449d642a2"
},
{
"path": "composer.json",
"sha256": "0c5d90b317084fbadf5b68d7c82f384ea38fb7077ad2f53a3eccd1e923c0b85d"
},
{
"path": "references/analysis.md",
"sha256": "2a24ab56d49577acfd6818a7243fd3ef1dc518d55196a379deacace140a9012c"
},
{
"path": "references/examples/coding-agent-cli/scripts-AGENTS.md",
"sha256": "fb68e9b8fdd0a38887edb23adf8a80270635b6d66c6063b5e5c9049217193aca"
},
{
"path": "references/examples/coding-agent-cli/AGENTS.md",
"sha256": "0012cbc25474d641e1f43714e4728082a2f8106323880fe91959f4b785eeb7ef"
},
{
"path": "references/examples/ldap-selfservice/internal-AGENTS.md",
"sha256": "587e67c42b0b273c3a1a7291c1cd481380aeac33693e0314c48908344efa3c5f"
},
{
"path": "references/examples/ldap-selfservice/internal-web-AGENTS.md",
"sha256": "fe8aaf9130a6f35e4a93dd91fd477088fe0e6fc8d9b046473b02c7491ef7774e"
},
{
"path": "references/examples/ldap-selfservice/AGENTS.md",
"sha256": "12e0d8102ff9a8d9afe58a6c62f5f80dfbab6a852a812d9d14ffbc2cf6167f7e"
},
{
"path": "references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.md",
"sha256": "18c70510d702bdb19f0635cf56b7fd1d43f33b261195c08a076bda7cdb6e47ef"
},
{
"path": "references/examples/t3x-rte-ckeditor-image/AGENTS.md",
"sha256": "07b74ea78fa432057a660207cf0359a9fccab3823329a47a506c77f2b2e71d7a"
},
{
"path": "references/examples/simple-ldap-go/examples-AGENTS.md",
"sha256": "883911058ad0c8c48da8486897c90f029a19658986f017bf1bde5ddc54eeffc7"
},
{
"path": "references/examples/simple-ldap-go/AGENTS.md",
"sha256": "b7f17e8beca30c42f40a7285d6c0043a67807181de5703aff2bce9e9c73ab072"
},
{
"path": "claudedocs/refactoring-summary.md",
"sha256": "eddf1114e3997c29e57d31133cf5a98e5cac0eabdefb06897328851f7b67cedd"
},
{
"path": "scripts/validate-structure.sh",
"sha256": "60789bd917958d125638f94479e6501e51d2d0f5d5373a4e33970f5f7710c848"
},
{
"path": "scripts/detect-scopes.sh",
"sha256": "a02b0147487009e754b658f84d48c47b4a45e46a0345616686a2aaf72bbe7967"
},
{
"path": "scripts/extract-commands.sh",
"sha256": "0ee80d781d8b031a0c626da4206321c747084b675c70fb8cc3e1303b2c1b4fc5"
},
{
"path": "scripts/generate-agents.sh",
"sha256": "3d50161327537782bde5d322e9e5fb6c83cd059e2d487212bcee0c72dd2dfe7a"
},
{
"path": "scripts/detect-project.sh",
"sha256": "403b1324a978ec99c0c99c70314de1b97136cc3dd23eb131e2e72389d7a5980c"
},
{
"path": "scripts/lib/template.sh",
"sha256": "4b30b4d85a30eea9ff5f9a36085b34a757396fde3058c734c869c640b18d9e17"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "4d106bd89bda56ab9f230ac02e05da20e3c3d302ae78b149fa0a3aa40081499b"
},
{
"path": "templates/root-verbose.md",
"sha256": "de9d263062471fc8f1fc154729a9a521acef48fda771ffee15f8a1803fd86e2c"
},
{
"path": "templates/root-thin.md",
"sha256": "686a97e5d5dd69ecbf567059167b35dde87a0691d6c5f69eac0759039b0bf71d"
},
{
"path": "templates/scoped/backend-go.md",
"sha256": "f1aad3498ac26177fdbbe69d07196b17b129fde9538e3d600754df686f26ee9d"
},
{
"path": "templates/scoped/cli.md",
"sha256": "c54098b6a5547639c7abc2403994495b96e61072b4e94d3bcb1bec749a611201"
},
{
"path": "templates/scoped/frontend-typescript.md",
"sha256": "c8024e783a228ad367679b2f961760fd3bf79bfb3b290c9c9d70c197626867a1"
},
{
"path": "templates/scoped/backend-php.md",
"sha256": "8956f7006f8a8fc13da61e9be3abde9711c7fd94fe533dd8fdfa8b3a966a6c80"
}
],
"dirSha256": "3caa289a90b8282766f02e812cd98175c73ad5a46a126850b6214ab053cb28e6"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

320
references/analysis.md Normal file
View File

@@ -0,0 +1,320 @@
# AGENTS.md Analysis Across 6 Netresearch Projects
## 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: `<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->`
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 <file.go>`
- 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
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
```
### 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
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
# 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
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
# 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
```

308
references/examples/coding-agent-cli/AGENTS.md Normal file
View File

@@ -0,0 +1,308 @@
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
# AI CLI Preparation - Agent Guide (Root)
**Thin root file**: See scoped AGENTS.md files for specific areas.
## Precedence & Scoped Files
This root AGENTS.md provides global defaults. **Nearest AGENTS.md wins** for specific rules.
**Scoped files:**
- [scripts/AGENTS.md](scripts/AGENTS.md) - Shell installation scripts
## Overview
AI CLI Preparation is an environment audit tool ensuring AI coding agents (like Claude Code) have access to necessary developer tools. It detects 50+ tools, reports versions, and provides installation guidance.
**Architecture:**
- **Phase 1 (Complete)**: Tool detection, version auditing, offline-first caching
- **Phase 2 (Planned)**: Context-aware installation/upgrade management (see [docs/PRD.md](docs/PRD.md))
**Tech Stack:**
- Python 3.10+ (standard library only, no external deps for core)
- Make for task automation
- Shell scripts (Bash) for installation
- JSON for caching (latest_versions.json, tools_snapshot.json)
**Key Files:**
- `cli_audit.py` (2,375 lines): Main audit engine, 50+ tool definitions
- `smart_column.py`: ANSI/emoji-aware table formatting
- `scripts/`: 13+ installation scripts (install/update/uninstall/reconcile)
- `docs/`: Comprehensive technical documentation (12 files, 189KB)
## Setup
**Requirements:**
- Python 3.10+ (Python 3.14.0rc2 tested)
- Standard library only (no pip install needed for core)
- Optional: pyflakes for linting
**First-time setup:**
```bash
# Allow direnv (if using)
direnv allow
# Show available commands
make help
# Update snapshot (requires network)
make update
# Run audit from snapshot (fast, offline-capable)
make audit
```
**Environment variables:**
```bash
# See .env.default for all options
CLI_AUDIT_COLLECT=1 # Collect-only mode (write snapshot)
CLI_AUDIT_RENDER=1 # Render-only mode (read snapshot)
CLI_AUDIT_OFFLINE=1 # Offline mode (manual cache only)
CLI_AUDIT_DEBUG=1 # Debug output
CLI_AUDIT_JSON=1 # JSON output
```
## Build & Tests
**Primary commands:**
```bash
make audit # Render from snapshot (no network, <100ms)
make update # Collect fresh data, write snapshot (~10s)
make audit-offline # Offline audit with hints
make lint # Run pyflakes (if installed)
make upgrade # Interactive upgrade guide
```
**Single tool audit:**
```bash
make audit-ripgrep # Audit specific tool
make audit-offline-python-core # Role-based preset
```
**Installation scripts:**
```bash
make install-python # Install Python toolchain (uv)
make install-node # Install Node.js (nvm)
make install-core # Install core tools (fd, fzf, ripgrep, jq, etc.)
```
**Testing:**
```bash
# Smoke test (verifies table output and JSON format)
./scripts/test_smoke.sh
# Test single tool detection
CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only ripgrep
# Validate snapshot
jq '.__meta__' tools_snapshot.json
```
**No formal test suite yet** - README acknowledges: "currently ships without tests"
- Smoke tests exist (test_smoke.sh)
- Manual validation workflows documented
## Code Style
**Python:**
- PEP 8 style (4-space indent, snake_case)
- Type hints used (`from __future__ import annotations`)
- Frozen dataclasses for immutability (`@dataclass(frozen=True)`)
- Docstrings minimal (focus on inline comments)
**Formatting:**
- EditorConfig enforced: LF, UTF-8, 4 spaces, trim trailing whitespace
- No auto-formatter configured (manual formatting)
- Lint via pyflakes: `make lint`
**Shell scripts:**
- Bash with `set -euo pipefail`
- Shellcheck-compliant (best effort)
- Consistent error handling (see scripts/lib/)
**Conventions:**
- File paths: Absolute paths, no auto-commit
- Functions: Snake_case, descriptive names
- Constants: UPPER_CASE (e.g., MANUAL_LOCK, HINTS_LOCK)
- Lock ordering: MANUAL_LOCK → HINTS_LOCK (enforced for safety)
## Security
**Secrets:**
- No secrets in VCS
- GITHUB_TOKEN optional (for GitHub API rate limit increase)
- Set via environment: `export GITHUB_TOKEN=ghp_...`
**Network:**
- HTTPS-only for upstream queries
- Retry logic with exponential backoff
- Per-origin rate limits (GitHub: 5/min, PyPI: 10/min, crates.io: 5/min)
- Timeout enforcement (default: 3s, configurable)
**Input validation:**
- Tool names validated against TOOLS registry
- Version strings sanitized (extract_version_number)
- Subprocess calls use lists, not shell=True (where possible)
**Caching:**
- Atomic file writes prevent corruption
- Offline-first design (committed latest_versions.json)
- No arbitrary code execution (package manager commands only)
## PR/Commit Checklist
**Before commit:**
- [ ] Run `make lint` (pyflakes clean)
- [ ] Run `make audit` (verify snapshot renders)
- [ ] Test affected tool: `make audit-<tool>`
- [ ] Update docs if behavior changed (README.md, docs/, scripts/README.md)
- [ ] Add/update smoke test if new output format
**Commit messages:**
- Conventional Commits format: `type(scope): description`
- Examples:
- `feat(audit): add snapshot-based collect/render modes`
- `fix(locks): enforce MANUAL_LOCK→HINTS_LOCK ordering`
- `docs(prd): add Phase 2 specifications and ADRs`
- `chore(cache): update latest_versions.json`
**Pull requests:**
- Keep PRs small (~≤300 net LOC changed)
- Link to issue/ticket if exists
- Update CHANGELOG section in PR description
- Ensure CI passes (when added)
## Good vs Bad Examples
**Good: Atomic dataclass with type safety**
```python
@dataclass(frozen=True)
class Tool:
name: str
candidates: tuple[str, ...]
source_kind: str # gh|pypi|crates|npm|gnu|skip
source_args: tuple[str, ...]
```
**Bad: Mutable dict with unclear types**
```python
# Don't do this
tool = {
'name': 'ripgrep',
'candidates': ['rg'], # List instead of tuple
'source': 'github', # Unclear allowed values
}
```
**Good: Lock ordering enforcement**
```python
def update_manual_cache(tool: str, version: str) -> None:
with MANUAL_LOCK: # Acquire first
with HINTS_LOCK: # Then hints
# Safe: consistent ordering prevents deadlock
```
**Bad: Lock ordering violation**
```python
def update_cache(tool: str) -> None:
with HINTS_LOCK: # Wrong order!
with MANUAL_LOCK:
# Deadlock risk
```
**Good: Parallel execution with isolation**
```python
with ThreadPoolExecutor(max_workers=16) as executor:
futures = [executor.submit(audit_tool, tool) for tool in TOOLS]
for future in as_completed(futures):
result = future.result() # Failures isolated
```
**Bad: Sequential execution**
```python
results = []
for tool in TOOLS: # Slow: 50 tools * 3s = 150s
results.append(audit_tool(tool))
```
## When Stuck
**Tool detection failing:**
1. Check PATH: `echo $PATH | tr ':' '\n'`
2. Debug single tool: `CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only <tool>`
3. Check version flag: `<tool> --version` or `<tool> -v`
4. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#version-detection-failures)
**Network issues:**
1. Increase timeout: `CLI_AUDIT_TIMEOUT_SECONDS=10 make update`
2. More retries: `CLI_AUDIT_HTTP_RETRIES=5 make update`
3. Use offline mode: `make audit-offline`
4. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#network-timeout-issues)
**Cache corruption:**
1. Remove caches: `rm latest_versions.json tools_snapshot.json`
2. Regenerate: `make update`
**Installation script fails:**
1. Check permissions: `make scripts-perms`
2. Debug script: `bash -x ./scripts/install_<tool>.sh`
3. See [scripts/README.md](scripts/README.md) for per-script troubleshooting
**Documentation:**
- Start with [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) for one-liners
- See [docs/INDEX.md](docs/INDEX.md) for navigation by role/task
- Architecture details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- API reference: [docs/API_REFERENCE.md](docs/API_REFERENCE.md)
## House Rules
**Defaults** (override in scoped AGENTS.md if needed):
**Commits:**
- Atomic commits (single logical change)
- Conventional Commits: `type(scope): description`
- Keep PRs small (~≤300 net LOC changed)
- Ticket IDs in commits/PRs if exists
**Type-safety:**
- Use type hints (`from __future__ import annotations`)
- Frozen dataclasses for immutability
- No `Any` unless truly dynamic
**Design principles:**
- SOLID, KISS, DRY, YAGNI
- Composition > Inheritance
- Law of Demeter (minimal coupling)
**Dependencies:**
- Standard library preferred (no external Python deps for core)
- Latest stable versions when external deps needed
- Document why in Decision Log (ADRs for Phase 2)
**Security:**
- No secrets in VCS
- HTTPS-only for network calls
- No arbitrary code execution
- Input validation on external data
**Documentation currency:**
- Update docs in same PR as behavior changes
- No drift between code and docs
- Document non-obvious decisions in ADRs (see docs/adr/)
**Testing:**
- Aim for ≥80% coverage on changed code (when test suite added)
- Bugfixes use TDD: failing test first, then fix
- New code paths need tests (future requirement)
**Current status:**
- Phase 1: Production-ready detection/audit
- Phase 2: Planned installation/upgrade (see [docs/PRD.md](docs/PRD.md))
- No unit tests yet (acknowledged in README)
---
**Quick Start:** New to the project? Start with [README.md](README.md) → [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) → [docs/INDEX.md](docs/INDEX.md)
**Contributing:** See [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) for detailed contribution guide

389
references/examples/coding-agent-cli/scripts-AGENTS.md Normal file
View File

@@ -0,0 +1,389 @@
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
# Installation Scripts - Agent Guide
**Scope:** Shell scripts for tool installation, update, uninstall, reconcile
## Overview
13+ Bash scripts for installing developer tools with multiple actions:
- **install**: Fresh installation (default action)
- **update**: Upgrade to latest version
- **uninstall**: Remove installation
- **reconcile**: Switch to preferred installation method (e.g., system → user)
**Key scripts:**
- `install_core.sh`: Core tools (fd, fzf, ripgrep, jq, yq, bat, delta, just)
- `install_python.sh`: Python toolchain via uv
- `install_node.sh`: Node.js via nvm
- `install_rust.sh`: Rust via rustup
- `install_go.sh`, `install_aws.sh`, `install_kubectl.sh`, etc.
- `guide.sh`: Interactive upgrade guide
- `test_smoke.sh`: Smoke test for audit output
**Shared utilities:** `lib/` directory (colors, logging, common functions)
## Setup
**Requirements:**
- Bash 4.0+
- `curl` or `wget` for downloads
- Internet access for fresh installs
- Appropriate permissions (user for `~/.local/bin`, sudo for system)
**Environment variables:**
```bash
INSTALL_PREFIX=${INSTALL_PREFIX:-~/.local} # Default: user-level
FORCE_INSTALL=1 # Skip confirmation prompts
DEBUG=1 # Verbose output
```
**Permissions:**
```bash
make scripts-perms # Ensure all scripts are executable
```
## Build & Tests
**Run individual script:**
```bash
# Install action (default)
./scripts/install_python.sh
# Update action
./scripts/install_python.sh update
# Uninstall action
./scripts/install_python.sh uninstall
# Reconcile action (switch installation method)
./scripts/install_node.sh reconcile
```
**Via Make:**
```bash
make install-python # Install Python toolchain
make update-python # Update Python toolchain
make uninstall-python # Uninstall Python toolchain
make reconcile-node # Switch Node.js to nvm-managed
```
**Smoke test:**
```bash
./scripts/test_smoke.sh # Verify audit output format
```
**Debug mode:**
```bash
DEBUG=1 ./scripts/install_python.sh
bash -x ./scripts/install_python.sh # Trace execution
```
## Code Style
**Shell standards:**
- Bash 4.0+ features allowed
- Shebang: `#!/usr/bin/env bash` or `#!/bin/bash`
- Set strict mode: `set -euo pipefail`
- `-e`: Exit on error
- `-u`: Error on undefined variables
- `-o pipefail`: Fail on pipe errors
**Formatting:**
- 4-space indentation (matches EditorConfig)
- Function names: lowercase_with_underscores
- Constants: UPPER_CASE
- Local variables: lowercase
**Structure:**
```bash
#!/usr/bin/env bash
set -euo pipefail
# Source shared utilities
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/lib/colors.sh" || true
source "${SCRIPT_DIR}/lib/common.sh" || true
# Main function per action
install_tool() {
echo_info "Installing <tool>..."
# Implementation
}
update_tool() {
echo_info "Updating <tool>..."
# Implementation
}
uninstall_tool() {
echo_info "Uninstalling <tool>..."
# Implementation
}
reconcile_tool() {
echo_info "Reconciling <tool>..."
# Implementation
}
# Action dispatcher
ACTION="${1:-install}"
case "$ACTION" in
install) install_tool ;;
update) update_tool ;;
uninstall) uninstall_tool ;;
reconcile) reconcile_tool ;;
*) echo "Usage: $0 {install|update|uninstall|reconcile}"; exit 1 ;;
esac
```
**Error handling:**
```bash
# Good: Check command exists before using
if ! command -v curl >/dev/null 2>&1; then
echo_error "curl not found. Install it first."
exit 1
fi
# Good: Check return codes
if ! download_file "$URL" "$DEST"; then
echo_error "Download failed"
exit 1
fi
# Good: Cleanup on error
trap 'rm -rf "$TMPDIR"' EXIT ERR
```
**Confirmation prompts:**
```bash
# Good: Skip prompt if FORCE_INSTALL=1
if [[ "${FORCE_INSTALL:-0}" != "1" ]]; then
read -p "Install <tool>? [y/N] " -n 1 -r
echo
[[ ! $REPLY =~ ^[Yy]$ ]] && exit 0
fi
```
## Security
**Download verification:**
```bash
# Always use HTTPS
URL="https://github.com/owner/repo/releases/download/..."
# Verify checksums when available
EXPECTED_SHA256="abc123..."
ACTUAL_SHA256=$(sha256sum "$FILE" | awk '{print $1}')
if [[ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]]; then
echo_error "Checksum mismatch!"
exit 1
fi
```
**Path safety:**
```bash
# Good: Quote variables, use absolute paths
INSTALL_DIR="${HOME}/.local/bin"
mkdir -p "$INSTALL_DIR"
mv "$TMPFILE" "$INSTALL_DIR/tool"
# Bad: Unquoted, relative paths
mkdir -p $INSTALL_DIR
mv tool bin/
```
**Sudo usage:**
```bash
# Good: Prompt for sudo only when needed
if [[ "$INSTALL_PREFIX" == "/usr/local" ]]; then
if ! sudo -v; then
echo_error "Sudo required for system installation"
exit 1
fi
sudo mv "$FILE" "$INSTALL_PREFIX/bin/"
else
# User-level, no sudo
mv "$FILE" "$INSTALL_PREFIX/bin/"
fi
```
**No secrets in scripts:**
- No API keys, tokens, passwords in scripts
- Use environment variables: `${GITHUB_TOKEN:-}`
- Document required env vars in script comments
## PR/Commit Checklist
**Before commit:**
- [ ] Run `shellcheck <script>` (if available)
- [ ] Test install action: `./scripts/install_<tool>.sh`
- [ ] Test update action: `./scripts/install_<tool>.sh update`
- [ ] Test uninstall action: `./scripts/install_<tool>.sh uninstall`
- [ ] Update `scripts/README.md` if new script or behavior change
- [ ] Verify script permissions: `make scripts-perms`
**Script checklist:**
- [ ] Shebang: `#!/usr/bin/env bash`
- [ ] Strict mode: `set -euo pipefail`
- [ ] Source shared lib: `source "${SCRIPT_DIR}/lib/colors.sh"`
- [ ] Action dispatcher (install/update/uninstall/reconcile)
- [ ] Error handling (check return codes, trap on exit)
- [ ] Confirmation prompts (respect FORCE_INSTALL)
- [ ] PATH updates (add to ~/.bashrc or ~/.zshrc if needed)
**Commit messages:**
- `feat(scripts): add install_terraform.sh`
- `fix(install-python): handle uv bootstrap failure`
- `docs(scripts): update README with reconcile action`
## Good vs Bad Examples
**Good: Robust download with fallback**
```bash
download_file() {
local url="$1"
local dest="$2"
if command -v curl >/dev/null 2>&1; then
curl -fsSL "$url" -o "$dest"
elif command -v wget >/dev/null 2>&1; then
wget -q "$url" -O "$dest"
else
echo_error "Neither curl nor wget found"
return 1
fi
}
```
**Bad: Assumes curl exists**
```bash
download_file() {
curl -fsSL "$1" -o "$2" # Fails if curl not installed
}
```
**Good: Version comparison**
```bash
version_gt() {
test "$(printf '%s\n' "$@" | sort -V | head -n 1)" != "$1"
}
CURRENT_VERSION="1.2.3"
LATEST_VERSION="1.3.0"
if version_gt "$LATEST_VERSION" "$CURRENT_VERSION"; then
echo "Upgrade available"
fi
```
**Bad: String comparison for versions**
```bash
if [[ "$LATEST_VERSION" > "$CURRENT_VERSION" ]]; then
# Wrong: "1.10.0" < "1.9.0" (string comparison)
echo "Upgrade available"
fi
```
**Good: Cleanup on exit**
```bash
TMPDIR=$(mktemp -d)
trap 'rm -rf "$TMPDIR"' EXIT ERR
# Download to temp
download_file "$URL" "$TMPDIR/file"
# ... process ...
# Cleanup happens automatically via trap
```
**Bad: Manual cleanup (error-prone)**
```bash
TMPDIR=$(mktemp -d)
download_file "$URL" "$TMPDIR/file"
# ... process ...
rm -rf "$TMPDIR" # Skipped if earlier command fails
```
**Good: Action-specific logic**
```bash
install_rust() {
if command -v rustup >/dev/null 2>&1; then
echo_warn "rustup already installed"
return 0
fi
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
}
update_rust() {
if ! command -v rustup >/dev/null 2>&1; then
echo_error "rustup not installed. Run install first."
return 1
fi
rustup update
}
```
## When Stuck
**Script fails silently:**
1. Add debug: `bash -x ./scripts/install_<tool>.sh`
2. Check logs: `./scripts/install_<tool>.sh 2>&1 | tee install.log`
3. Verify permissions: `ls -la scripts/`
**Download fails:**
1. Check network: `curl -I https://github.com`
2. Check URL: `echo "$URL"` (verify it's correct)
3. Try manual download: `curl -fsSL "$URL"`
**Installation fails:**
1. Check prerequisites (e.g., Python for uv, curl for rustup)
2. Check disk space: `df -h`
3. Check permissions: `ls -ld "$INSTALL_PREFIX"`
**PATH not updated:**
1. Source shell config: `source ~/.bashrc` or `source ~/.zshrc`
2. Check PATH: `echo $PATH | tr ':' '\n' | grep local`
3. Verify binary location: `ls -la ~/.local/bin/<tool>`
**Reconcile fails:**
1. Check current installation: `which <tool>`
2. Check installation method: `cli_audit.py --only <tool>`
3. Manually remove old version first: `apt remove <tool>` or `cargo uninstall <tool>`
**Documentation:**
- Script-specific docs: [README.md](README.md) (this directory)
- Troubleshooting: [../docs/TROUBLESHOOTING.md](../docs/TROUBLESHOOTING.md)
- Architecture: [../docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md#installation-scripts)
## House Rules
**Installation preferences** (Phase 2 planning):
- User-level preferred: `~/.local/bin` (workstations)
- System-level for servers: `/usr/local/bin`
- Vendor tools first: rustup, nvm, uv over system packages
- See [../docs/adr/ADR-002-package-manager-hierarchy.md](../docs/adr/ADR-002-package-manager-hierarchy.md)
**Reconciliation strategy:**
- Parallel approach: Keep both installations, prefer user via PATH
- No automatic removal (user chooses)
- See [../docs/adr/ADR-003-parallel-installation-approach.md](../docs/adr/ADR-003-parallel-installation-approach.md)
**Version policy:**
- Always latest by default
- Warn on major version upgrades
- See [../docs/adr/ADR-004-always-latest-version-policy.md](../docs/adr/ADR-004-always-latest-version-policy.md)
**Script structure:**
- Multi-action support: install, update, uninstall, reconcile
- Shared utilities in `lib/`
- Consistent error handling and logging
- Make integration via `make install-<tool>`
---
**Quick Start:** Run `make install-core` to install essential tools, then `make audit` to verify.
**Troubleshooting:** See [README.md](README.md) for per-script troubleshooting and [../docs/TROUBLESHOOTING.md](../docs/TROUBLESHOOTING.md) for general issues.

282
references/examples/ldap-selfservice/AGENTS.md Normal file
View File

@@ -0,0 +1,282 @@
# Agent Guidelines
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults.
**Project**: LDAP Selfservice Password Changer — hybrid Go + TypeScript web application with WCAG 2.2 AAA accessibility compliance.
## Quick Navigation
- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services
- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend & Tailwind CSS
## Global Defaults
### Project Overview
Self-service password change/reset web app for LDAP/ActiveDirectory with email-based password reset, rate limiting, and strict accessibility standards. Single binary deployment with embedded assets.
**Stack**: Go 1.25 + Fiber, TypeScript (ultra-strict), Tailwind CSS 4, Docker multi-stage builds, pnpm 10.18
**Key characteristics**:
- Docker-first: All dev/CI must work via Docker
- Accessibility: WCAG 2.2 AAA compliance (7:1 contrast, keyboard nav, screen readers)
- Type-safe: Go with testcontainers, TypeScript with all strict flags
- Security-focused: LDAPS, rate limiting, token-based reset, no password storage
### Setup
**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev)
```bash
# Clone and setup environment
git clone <repo>
cd ldap-selfservice-password-changer
cp .env.local.example .env.local # Edit with your LDAP config
# Docker (recommended)
docker compose --profile dev up
# Native development
pnpm install
go mod download
pnpm dev # Runs concurrent TS watch, CSS watch, and Go with hot-reload
```
See [docs/development-guide.md](docs/development-guide.md) for comprehensive setup.
### Build & Test Commands
**Package manager**: pnpm (specified in package.json: `pnpm@10.18.1`)
```bash
# Build everything
pnpm build # Build frontend assets + Go binary
# Frontend only
pnpm build:assets # TypeScript + Tailwind CSS
pnpm js:build # TypeScript compile + minify
pnpm css:build # Tailwind CSS + PostCSS
# Development (watch mode)
pnpm dev # Concurrent: TS watch, CSS watch, Go hot-reload
pnpm js:dev # TypeScript watch
pnpm css:dev # CSS watch
pnpm go:dev # Go with nodemon hot-reload
# Tests
go test -v ./... # All Go tests with verbose output
go test ./internal/... # Specific package tests
# Formatting
pnpm prettier --write . # Format TS, Go templates, config files
pnpm prettier --check . # Check formatting (CI)
# Type checking
pnpm js:build # TypeScript strict compilation (no emit in dev)
go build -v ./... # Go compilation + type checking
```
**CI commands** (from `.github/workflows/check.yml`):
- Type check: `pnpm js:build` and `go build -v ./...`
- Format check: `pnpm prettier --check .`
- Tests: `go test -v ./...`
### Code Style
**TypeScript**:
- Ultra-strict tsconfig: `strict: true`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noPropertyAccessFromIndexSignature`
- Prettier formatting: 120 char width, semicolons, double quotes, 2-space tabs
- No `any` types - use proper type definitions
- Follow existing patterns in `internal/web/static/`
**Go**:
- Standard Go formatting (`go fmt`)
- Prettier with `prettier-plugin-go-template` for HTML templates
- Follow Go project layout: `internal/` for private packages, `main.go` at root
- Use testcontainers for integration tests (see `*_test.go` files)
- Error wrapping with context
**General**:
- Composition over inheritance
- SOLID, KISS, DRY, YAGNI principles
- Law of Demeter: minimize coupling
- No secrets in VCS (use .env.local, excluded from git)
### Security
- **No secrets in git**: Use `.env.local` (gitignored), never commit LDAP credentials
- **LDAPS required**: Production must use encrypted LDAP connections
- **Rate limiting**: 3 requests/hour per IP (configurable via `RATE_LIMIT_*` env vars)
- **Token security**: Cryptographic random tokens with configurable expiry
- **Input validation**: Strict validation on all user inputs (see `internal/validators/`)
- **Dependency scanning**: Renovate enabled, review changelogs for major updates
- **No PII logging**: Redact sensitive data in logs
- **Run as non-root**: Dockerfile uses UID 65534 (nobody)
### PR/Commit Checklist
✅ **Before commit**:
- [ ] Run `pnpm prettier --write .` (format all)
- [ ] Run `pnpm js:build` (TypeScript strict check)
- [ ] Run `go test ./...` (all tests pass)
- [ ] Run `go build` (compilation check)
- [ ] No secrets in changed files
- [ ] Update docs if behavior changed
- [ ] WCAG 2.2 AAA compliance maintained (if UI changed)
✅ **Commit format**: Conventional Commits
```
type(scope): description
Examples:
feat(auth): add password reset via email
fix(validators): correct password policy regex
docs(api): update JSON-RPC examples
chore(deps): update pnpm to v10.18.1
```
**No Claude attribution** in commit messages.
✅ **PR requirements**:
- [ ] All CI checks pass (types, formatting, tests)
- [ ] Keep PRs small (~≤300 net LOC if possible)
- [ ] Include ticket ID if applicable: `fix(rate-limit): ISSUE-123: fix memory leak`
- [ ] Update relevant docs in same PR (README, AGENTS.md, docs/)
### Good vs Bad Examples
**✅ Good - TypeScript strict types**:
```typescript
interface PasswordPolicy {
minLength: number;
requireNumbers: boolean;
}
function validatePassword(password: string, policy: PasswordPolicy): boolean {
const hasNumber = /\d/.test(password);
return password.length >= policy.minLength && (!policy.requireNumbers || hasNumber);
}
```
**❌ Bad - Using any or unsafe access**:
```typescript
function validatePassword(password: any, policy: any) {
// ❌ any types
return password.length >= policy.minLength; // ❌ unsafe access
}
```
**✅ Good - Go error handling**:
```go
func connectLDAP(config LDAPConfig) (*ldap.Conn, error) {
conn, err := ldap.DialURL(config.URL)
if err != nil {
return nil, fmt.Errorf("failed to connect to LDAP at %s: %w", config.URL, err)
}
return conn, nil
}
```
**❌ Bad - Ignoring errors**:
```go
func connectLDAP(config LDAPConfig) *ldap.Conn {
conn, _ := ldap.DialURL(config.URL) // ❌ ignoring error
return conn // ❌ may return nil
}
```
**✅ Good - Accessible UI**:
```html
<button type="submit" aria-label="Submit password change" class="bg-blue-600 hover:bg-blue-700 focus:ring-4">
Change Password
</button>
```
**❌ Bad - Inaccessible UI**:
```html
<div onclick="submit()">Submit</div>
❌ not keyboard accessible, wrong semantics
```
### When Stuck
1. **Check existing docs**: [docs/](docs/) has comprehensive guides
2. **Review similar code**: Look for patterns in `internal/` packages
3. **Run tests**: `go test -v ./...` often reveals issues
4. **Check CI logs**: GitHub Actions shows exact failure points
5. **Verify environment**: Ensure `.env.local` is properly configured
6. **Docker issues**: `docker compose down -v && docker compose --profile dev up --build`
7. **Type errors**: Review `tsconfig.json` strict flags, use proper types
8. **Accessibility**: See [docs/accessibility.md](docs/accessibility.md) for WCAG 2.2 AAA guidelines
### House Rules
**Docker-First Philosophy**:
- All dev and CI must work via Docker Compose
- Native setup is optional convenience, not requirement
- Use profiles in compose.yml: `--profile dev` or `--profile test`
**Documentation Currency**:
- Update docs in same PR as code changes
- No drift between code and documentation
- Keep README, AGENTS.md, and docs/ synchronized
**Testing Standards**:
- Aim for ≥80% coverage on changed code
- Use testcontainers for integration tests (see existing `*_test.go`)
- For bugfixes: write failing test first (TDD)
- Tests must pass before PR approval
**Scope Discipline**:
- Build only what's requested
- No speculative features
- MVP first, iterate based on feedback
- YAGNI: You Aren't Gonna Need It
**Accessibility Non-Negotiable**:
- WCAG 2.2 AAA compliance required
- 7:1 contrast ratios for text
- Full keyboard navigation support
- Screen reader tested (VoiceOver/NVDA)
- See [docs/accessibility.md](docs/accessibility.md)
**Commit Practices**:
- Atomic commits: one logical change per commit
- Conventional Commits format enforced
- Never commit secrets or `.env.local`
- Keep PRs focused and reviewable
**Type Safety**:
- TypeScript: No `any`, all strict flags enabled
- Go: Leverage type system, avoid `interface{}`
- Validate inputs at boundaries
**Dependency Management**:
- Renovate auto-updates enabled
- Major version updates require changelog review
- Use Context7 MCP or official docs for migrations
- Keep pnpm-lock.yaml and go.sum committed

371
references/examples/ldap-selfservice/internal-AGENTS.md Normal file
View File

@@ -0,0 +1,371 @@
# Go Backend Services
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
**Scope**: Go backend packages in `internal/` directory
**See also**: [../AGENTS.md](../AGENTS.md) for global standards, [web/AGENTS.md](web/AGENTS.md) for frontend
## Overview
Backend services for LDAP selfservice password change/reset functionality. Organized as internal Go packages:
- **email/**: SMTP email service for password reset tokens
- **options/**: Configuration management from environment variables
- **ratelimit/**: IP-based rate limiting (3 req/hour default)
- **resettoken/**: Cryptographic token generation and validation
- **rpc/**: JSON-RPC 2.0 API handlers (password change/reset)
- **validators/**: Password policy validation logic
- **web/**: HTTP server setup, static assets, routing (see [web/AGENTS.md](web/AGENTS.md))
## Setup/Environment
**Required environment variables** (configure in `.env.local`):
```bash
# LDAP connection
LDAP_URL=ldaps://ldap.example.com:636
LDAP_USER_BASE_DN=ou=users,dc=example,dc=com
LDAP_BIND_DN=cn=admin,dc=example,dc=com
LDAP_BIND_PASSWORD=secret
# Email for password reset
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASSWORD=secret
SMTP_FROM=noreply@example.com
APP_BASE_URL=https://passwd.example.com
# Rate limiting (optional)
RATE_LIMIT_REQUESTS=3
RATE_LIMIT_WINDOW=1h
# Token expiry (optional)
TOKEN_EXPIRY_DURATION=1h
```
**Go toolchain**: Requires Go 1.25+ (specified in `go.mod`)
**Key dependencies**:
- `github.com/gofiber/fiber/v2` - HTTP server
- `github.com/netresearch/simple-ldap-go` - LDAP client
- `github.com/testcontainers/testcontainers-go` - Integration testing
- `github.com/joho/godotenv` - Environment loading
## Build & Tests
```bash
# Development
go run . # Start server with hot-reload (via pnpm go:dev)
go build -v ./... # Compile all packages
go test -v ./... # Run all tests with verbose output
# Specific package testing
go test ./internal/validators/... # Test password validators
go test ./internal/ratelimit/... # Test rate limiter
go test ./internal/resettoken/... # Test token generation
go test -run TestSpecificFunction # Run specific test
# Integration tests (uses testcontainers)
go test -v ./internal/email/... # Requires Docker for MailHog container
# Coverage
go test -cover ./... # Coverage summary
go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
# Build optimized binary
CGO_ENABLED=0 go build -ldflags="-w -s" -o ldap-passwd
```
**CI validation** (from `.github/workflows/check.yml`):
```bash
go mod download
go build -v ./...
go test -v ./...
```
## Code Style
**Go Standards**:
- Use `go fmt` (automatic via Prettier with go-template plugin)
- Follow [Effective Go](https://go.dev/doc/effective_go)
- Package-level documentation comments required
- Exported functions must have doc comments
**Project Conventions**:
- Internal packages only: No public API outside this project
- Error wrapping with context: `fmt.Errorf("context: %w", err)`
- Use structured logging (consider adding in future)
- Prefer explicit over implicit
- Use interfaces for testability (see `email/service.go`)
**Naming**:
- `internal/package/file.go` - implementation
- `internal/package/file_test.go` - tests
- Descriptive variable names (not `x`, `y`, `tmp`)
- No stuttering: `email.Service`, not `email.EmailService`
**Error Handling**:
```go
// ✅ Good: wrap with context
if err != nil {
return fmt.Errorf("failed to connect LDAP at %s: %w", config.URL, err)
}
// ❌ Bad: lose context
if err != nil {
return err
}
// ❌ Worse: ignore
conn, _ := ldap.Dial(url)
```
**Testing**:
- Table-driven tests preferred
- Use testcontainers for external dependencies (LDAP, SMTP)
- Test files colocated with code: `validators/validate_test.go`
- Descriptive test names: `TestPasswordValidation_RequiresMinimumLength`
## Security
**LDAP Security**:
- Always use LDAPS in production (`ldaps://` URLs)
- Bind credentials in environment, never hardcoded
- Validate user input before LDAP queries (prevent injection)
- Use `simple-ldap-go` helpers to avoid raw LDAP filter construction
**Password Security**:
- Never log passwords (plain or hashed)
- No password storage - passwords go directly to LDAP
- Passwords only in memory during request lifetime
- HTTPS required for transport security
**Token Security**:
- Cryptographic random tokens (see `resettoken/token.go`)
- Configurable expiry (default 1h)
- Single-use tokens (invalidated after use)
- No token storage in logs or metrics
**Rate Limiting**:
- IP-based limits: 3 requests/hour default
- Configurable via `RATE_LIMIT_*` env vars
- In-memory store (consider Redis for multi-instance)
- Apply to both change and reset endpoints
**Input Validation**:
- Strict validation on all user inputs (see `validators/`)
- Reject malformed requests early
- Validate email format, username format, password policies
- No HTML/script injection vectors
## PR/Commit Checklist
**Before committing Go code**:
- [ ] Run `go fmt ./...` (or `pnpm prettier --write .`)
- [ ] Run `go vet ./...` (static analysis)
- [ ] Run `go test ./...` (all tests pass)
- [ ] Run `go build` (compilation check)
- [ ] Update package doc comments if API changed
- [ ] Add/update tests for new functionality
- [ ] Check for sensitive data in logs
- [ ] Verify error messages provide useful context
**Testing requirements**:
- New features must have tests
- Bug fixes must have regression tests
- Aim for ≥80% coverage on changed packages
- Integration tests for external dependencies
**Documentation**:
- Update package doc comments (godoc)
- Update [docs/api-reference.md](../docs/api-reference.md) for RPC changes
- Update [docs/development-guide.md](../docs/development-guide.md) for new setup steps
- Update environment variable examples in `.env` and docs
## Good vs Bad Examples
**✅ Good: Type-safe configuration**
```go
type Config struct {
LDAPURL string `env:"LDAP_URL" validate:"required,url"`
BindDN string `env:"LDAP_BIND_DN" validate:"required"`
BindPassword string `env:"LDAP_BIND_PASSWORD" validate:"required"`
}
func LoadConfig() (*Config, error) {
var cfg Config
if err := env.Parse(&cfg); err != nil {
return nil, fmt.Errorf("parse config: %w", err)
}
return &cfg, nil
}
```
**❌ Bad: Unsafe configuration**
```go
func LoadConfig() *Config {
return &Config{
LDAPURL: os.Getenv("LDAP_URL"), // ❌ no validation, may be empty
}
}
```
**✅ Good: Table-driven tests**
```go
func TestPasswordValidation(t *testing.T) {
tests := []struct {
name string
password string
policy PasswordPolicy
wantErr bool
}{
{"valid password", "Test123!", PasswordPolicy{MinLength: 8}, false},
{"too short", "Ab1!", PasswordPolicy{MinLength: 8}, true},
{"no numbers", "TestTest", PasswordPolicy{RequireNumbers: true}, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := ValidatePassword(tt.password, tt.policy)
if (err != nil) != tt.wantErr {
t.Errorf("got error %v, wantErr %v", err, tt.wantErr)
}
})
}
}
```
**❌ Bad: Non-descriptive tests**
```go
func TestPassword(t *testing.T) {
err := ValidatePassword("test") // ❌ what policy? what's expected?
if err == nil {
t.Fail()
}
}
```
**✅ Good: Interface for testability**
```go
type EmailService interface {
SendResetToken(ctx context.Context, to, token string) error
}
type SMTPService struct {
host string
port int
}
func (s *SMTPService) SendResetToken(ctx context.Context, to, token string) error {
// real implementation
}
// In tests, use mock implementation
type MockEmailService struct {
SendFunc func(ctx context.Context, to, token string) error
}
```
**❌ Bad: Hard-to-test concrete dependency**
```go
func ResetPassword(username string) error {
service := NewSMTPService() // ❌ hardcoded, can't mock
return service.SendEmail(...)
}
```
## When Stuck
**Go-specific issues**:
1. **Module issues**: `go mod tidy` to clean dependencies
2. **Import errors**: Check `go.mod` requires correct versions
3. **Test failures**: `go test -v ./... -run FailingTest` for verbose output
4. **LDAP connection**: Verify `LDAP_URL` format and network access
5. **Email testing**: Ensure Docker running for testcontainers (MailHog)
6. **Rate limit testing**: Tests may fail if system time incorrect
**Debugging**:
```bash
# Verbose test output
go test -v ./internal/package/...
# Run specific test
go test -run TestName ./internal/package/
# Race detector (for concurrency issues)
go test -race ./...
# Build with debug info
go build -gcflags="all=-N -l"
```
**Common pitfalls**:
- **Nil pointer dereference**: Check error returns before using values
- **Context cancellation**: Always respect `context.Context` in long operations
- **Resource leaks**: Defer `Close()` calls immediately after acquiring resources
- **Goroutine leaks**: Ensure all goroutines can exit
- **Time zones**: Use `time.UTC` for consistency
## Package-Specific Notes
### email/
- Uses testcontainers for integration tests
- MailHog container spins up automatically in tests
- Mock `EmailService` interface for unit tests in other packages
### options/
- Configuration loaded from environment via `godotenv`
- Validation happens at startup (fail-fast)
- See `.env.local.example` for required variables
### ratelimit/
- In-memory store (map with mutex)
- Consider Redis for multi-instance deployments
- Tests use fixed time.Now for deterministic results
### resettoken/
- Crypto/rand for token generation (never math/rand)
- Base64 URL encoding (safe for URLs)
- Store tokens server-side with expiry
### rpc/
- JSON-RPC 2.0 specification compliance
- Error codes defined in [docs/api-reference.md](../docs/api-reference.md)
- Request validation before processing
### validators/
- Pure functions (no side effects)
- Configurable policies from environment
- Clear error messages for user feedback

448
references/examples/ldap-selfservice/internal-web-AGENTS.md Normal file
View File

@@ -0,0 +1,448 @@
# Frontend - TypeScript & Tailwind CSS
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
**Scope**: Frontend assets in `internal/web/` directory - TypeScript, Tailwind CSS, HTML templates
**See also**: [../../AGENTS.md](../../AGENTS.md) for global standards, [../AGENTS.md](../AGENTS.md) for Go backend
## Overview
Frontend implementation for LDAP selfservice password changer with strict accessibility compliance:
- **static/**: Client-side TypeScript, compiled CSS, static assets
- **js/**: TypeScript source files (compiled to ES modules)
- **styles.css**: Tailwind CSS output
- Icons, logos, favicons, manifest
- **templates/**: Go HTML templates (\*.gohtml)
- **handlers.go**: HTTP route handlers
- **middleware.go**: Security headers, CORS, etc.
- **server.go**: Fiber server setup
**Key characteristics**:
- **WCAG 2.2 AAA**: 7:1 contrast, keyboard navigation, screen reader support, adaptive density
- **Ultra-strict TypeScript**: All strict flags enabled, no `any` types
- **Tailwind CSS 4**: Utility-first, dark mode, responsive, accessible patterns
- **Progressive enhancement**: Works without JavaScript (forms submit via HTTP)
- **Password manager friendly**: Proper autocomplete attributes
## Setup/Environment
**Prerequisites**: Node.js 24+, pnpm 10.18+ (from root `package.json`)
```bash
# From project root
pnpm install # Install dependencies
# Development (watch mode)
pnpm css:dev # Tailwind CSS watch
pnpm js:dev # TypeScript watch
# OR
pnpm dev # Concurrent: CSS + TS + Go hot-reload
```
**No .env needed for frontend** - all config comes from Go backend
**Browser targets**: Modern browsers with ES module support (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
## Build & Tests
```bash
# Build frontend assets
pnpm build:assets # TypeScript + CSS (production builds)
# TypeScript
pnpm js:build # Compile TS → ES modules + minify
pnpm js:dev # Watch mode with preserveWatchOutput
tsc --noEmit # Type check only (no output)
# CSS
pnpm css:build # Tailwind + PostCSS → styles.css
pnpm css:dev # Watch mode
# Formatting
pnpm prettier --write internal/web/ # Format TS, CSS, HTML templates
pnpm prettier --check internal/web/ # Check formatting (CI)
```
**No unit tests yet** - TypeScript strict mode catches most errors, integration via Go tests
**CI validation** (from `.github/workflows/check.yml`):
```bash
pnpm install
pnpm js:build # TypeScript strict compilation
pnpm prettier --check .
```
**Accessibility testing**:
- Keyboard navigation: Tab through all interactive elements
- Screen reader: Test with VoiceOver (macOS/iOS) or NVDA (Windows)
- Contrast: Verify 7:1 ratios with browser dev tools
- See [../../docs/accessibility.md](../../docs/accessibility.md) for comprehensive guide
## Code Style
**TypeScript Ultra-Strict** (from `tsconfig.json`):
```json
{
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noPropertyAccessFromIndexSignature": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"noUnusedLocals": true,
"noUnusedParameters": true
}
```
**No `any` types allowed**:
```typescript
// ✅ Good: explicit types
function validatePassword(password: string, minLength: number): boolean {
return password.length >= minLength;
}
// ❌ Bad: any type
function validatePassword(password: any): boolean {
return password.length >= 8; // ❌ unsafe
}
```
**Prettier formatting**:
- 120 char width
- 2-space indentation
- Semicolons required
- Double quotes (not single)
- Trailing comma: none
**File organization**:
- TypeScript source: `static/js/*.ts`
- Output: `static/js/*.js` (minified ES modules)
- CSS input: `tailwind.css` (Tailwind directives)
- CSS output: `static/styles.css` (PostCSS processed)
## Accessibility Standards (WCAG 2.2 AAA)
**Required compliance** - not optional:
### Keyboard Navigation
- All interactive elements focusable with Tab
- Visual focus indicators (4px outline, 7:1 contrast)
- Logical tab order (top to bottom, left to right)
- No keyboard traps
- Skip links where needed
### Screen Readers
- Semantic HTML: `<button>`, `<input>`, `<label>`, not `<div onclick>`
- ARIA labels on icon-only buttons: `aria-label="Submit"`
- Error messages: `aria-describedby` linking to error text
- Live regions for dynamic content: `aria-live="polite"`
- Form field associations: `<label for="id">` + `<input id="id">`
### Color & Contrast
- Text: 7:1 contrast ratio (AAA)
- Large text (18pt+): 4.5:1 minimum
- Focus indicators: 3:1 against adjacent colors
- Dark mode: same contrast requirements
- Never rely on color alone (use icons, text, patterns)
### Responsive & Adaptive
- Responsive: layout adapts to viewport size
- Text zoom: 200% without horizontal scroll
- Adaptive density: spacing adjusts for user preferences
- Touch targets: 44×44 CSS pixels minimum (mobile)
### Examples
**✅ Good: Accessible button**
```html
<button type="submit" class="btn-primary focus:ring-4 focus:ring-blue-300" aria-label="Submit password change">
<svg aria-hidden="true">...</svg>
Change Password
</button>
```
**❌ Bad: Inaccessible div-button**
```html
<div onclick="submit()" class="button">❌ not keyboard accessible Submit</div>
```
**✅ Good: Form with error handling**
```html
<form>
<label for="password">New Password</label>
<input
id="password"
type="password"
aria-describedby="password-error"
aria-invalid="true"
autocomplete="new-password"
/>
<div id="password-error" role="alert">Password must be at least 8 characters</div>
</form>
```
**❌ Bad: Form without associations**
```html
<form>
<div>Password</div>
❌ not a label, no association <input type="password" /> ❌ no autocomplete, no error linkage
<div style="color: red">Error</div>
❌ no role="alert", only color
</form>
```
## Tailwind CSS Patterns
**Use utility classes**, not custom CSS:
**✅ Good: Utility classes**
```html
<button
class="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white hover:bg-blue-700 focus:ring-4 focus:ring-blue-300"
>
Submit
</button>
```
**❌ Bad: Custom CSS**
```html
<button class="custom-button">Submit</button>
<style>
.custom-button {
background: blue;
} /* ❌ Use Tailwind utilities */
</style>
```
**Dark mode support**:
```html
<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">Content</div>
```
**Responsive design**:
```html
<div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
<!-- Responsive grid: 1 col mobile, 2 tablet, 3 desktop -->
</div>
```
**Focus states (required)**:
```html
<button class="focus:ring-4 focus:ring-blue-300 focus:outline-none">
<!-- 4px focus ring, 7:1 contrast -->
</button>
```
## TypeScript Patterns
**Strict null checking**:
```typescript
// ✅ Good: handle nulls explicitly
function getElement(id: string): HTMLElement | null {
return document.getElementById(id);
}
const el = getElement("password");
if (el) {
// ✅ null check
el.textContent = "Hello";
}
// ❌ Bad: assume non-null
const el = getElement("password");
el.textContent = "Hello"; // ❌ may crash if null
```
**Type guards**:
```typescript
// ✅ Good: type guard for forms
function isHTMLFormElement(element: Element): element is HTMLFormElement {
return element instanceof HTMLFormElement;
}
const form = document.querySelector("form");
if (form && isHTMLFormElement(form)) {
form.addEventListener("submit", handleSubmit);
}
```
**No unsafe array access**:
```typescript
// ✅ Good: check array bounds
const items = ["a", "b", "c"];
const first = items[0]; // string | undefined (noUncheckedIndexedAccess)
if (first) {
console.log(first.toUpperCase());
}
// ❌ Bad: unsafe access
console.log(items[0].toUpperCase()); // ❌ may crash if empty array
```
## PR/Commit Checklist
**Before committing frontend code**:
- [ ] Run `pnpm js:build` (TypeScript strict check)
- [ ] Run `pnpm prettier --write internal/web/`
- [ ] Verify keyboard navigation works
- [ ] Test with screen reader (VoiceOver/NVDA)
- [ ] Check contrast ratios (7:1 for text)
- [ ] Test dark mode
- [ ] Verify password manager autofill works
- [ ] No console errors in browser
- [ ] Test on mobile viewport (responsive)
**Accessibility checklist**:
- [ ] All interactive elements keyboard accessible
- [ ] Focus indicators visible (4px outline, 7:1 contrast)
- [ ] ARIA labels on icon-only buttons
- [ ] Form fields properly labeled
- [ ] Error messages linked with aria-describedby
- [ ] No color-only information conveyance
- [ ] Touch targets ≥44×44 CSS pixels (mobile)
**Performance checklist**:
- [ ] Minified JS (via `pnpm js:minify`)
- [ ] CSS optimized (cssnano via PostCSS)
- [ ] No unused Tailwind classes (purged automatically)
- [ ] No console.log in production code
## Good vs Bad Examples
**✅ Good: Type-safe DOM access**
```typescript
function setupPasswordToggle(): void {
const toggle = document.getElementById("toggle-password");
const input = document.getElementById("password");
if (!toggle || !(input instanceof HTMLInputElement)) {
return; // Guard against missing elements
}
toggle.addEventListener("click", () => {
input.type = input.type === "password" ? "text" : "password";
});
}
```
**❌ Bad: Unsafe DOM access**
```typescript
function setupPasswordToggle() {
const toggle = document.getElementById("toggle-password")!; // ❌ non-null assertion
const input = document.getElementById("password") as any; // ❌ any type
toggle.addEventListener("click", () => {
input.type = input.type === "password" ? "text" : "password"; // ❌ may crash
});
}
```
**✅ Good: Accessible form validation**
```typescript
function showError(input: HTMLInputElement, message: string): void {
const errorId = `${input.id}-error`;
let errorEl = document.getElementById(errorId);
if (!errorEl) {
errorEl = document.createElement("div");
errorEl.id = errorId;
errorEl.setAttribute("role", "alert");
errorEl.className = "text-red-600 dark:text-red-400 text-sm mt-1";
input.parentElement?.appendChild(errorEl);
}
errorEl.textContent = message;
input.setAttribute("aria-invalid", "true");
input.setAttribute("aria-describedby", errorId);
}
```
**❌ Bad: Inaccessible validation**
```typescript
function showError(input: any, message: string) {
// ❌ any type
input.style.borderColor = "red"; // ❌ color only, no text
alert(message); // ❌ blocks UI, not persistent
}
```
## When Stuck
**TypeScript issues**:
1. **Type errors**: Check `tsconfig.json` flags, use proper types (no `any`)
2. **Null errors**: Add null checks or type guards
3. **Module errors**: Ensure ES module syntax (`import`/`export`)
4. **Build errors**: `pnpm install` to refresh dependencies
**CSS issues**:
1. **Styles not applying**: Check Tailwind purge config, rebuild with `pnpm css:build`
2. **Dark mode broken**: Use `dark:` prefix on utilities
3. **Responsive broken**: Use `md:`, `lg:` breakpoint prefixes
4. **Custom classes**: Don't - use Tailwind utilities instead
**Accessibility issues**:
1. **Keyboard nav broken**: Check tab order, focus indicators
2. **Screen reader confusion**: Verify ARIA labels, semantic HTML
3. **Contrast failure**: Use darker colors, test with dev tools
4. **See**: [../../docs/accessibility.md](../../docs/accessibility.md)
**Browser dev tools**:
- Accessibility tab: Check ARIA, contrast, structure
- Lighthouse: Run accessibility audit (aim for 100 score)
- Console: No errors in production code
## Testing Workflow
**Manual testing required** (no automated frontend tests yet):
1. **Visual testing**: Check all pages in light/dark mode
2. **Keyboard testing**: Tab through all interactive elements
3. **Screen reader testing**: Use VoiceOver (Cmd+F5) or NVDA
4. **Responsive testing**: Test mobile, tablet, desktop viewports
5. **Browser testing**: Chrome, Firefox, Safari, Edge
6. **Password manager**: Test autofill with 1Password, LastPass, etc.
**Accessibility testing tools**:
- Browser dev tools Lighthouse
- axe DevTools extension
- WAVE browser extension
- Manual keyboard/screen reader testing (required)
**Integration testing**: Go backend tests exercise full request/response flow including frontend templates

27
references/examples/simple-ldap-go/AGENTS.md Normal file
View File

@@ -0,0 +1,27 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2025-09-29 -->
# AGENTS.md (root)
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.
## 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
- Never commit secrets or sensitive data to the repository
- Follow Go 1.24 conventions and idioms
- Maintain minimum test coverage of 40%
## Minimal pre-commit checks
- Typecheck (all packages): `go build -v ./...`
- Lint/format (file scope): `gofmt -w <file.go>` and `~/go/bin/golangci-lint run ./...`
- Unit tests (fast): `go test -v -race -short -timeout=10s ./...`
## Index of scoped AGENTS.md
- `./examples/AGENTS.md` — Example applications and usage patterns
- `./testutil/AGENTS.md` — Testing utilities and container management
- `./docs/AGENTS.md` — Documentation and guides
## When instructions conflict
- The nearest `AGENTS.md` wins. Explicit user prompts override files.
- For Go-specific patterns, defer to language idioms and standard library conventions

45
references/examples/simple-ldap-go/examples-AGENTS.md Normal file
View File

@@ -0,0 +1,45 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2025-09-29 -->
# AGENTS.md — Examples
## Overview
Example applications demonstrating library usage patterns for authentication, user management, performance optimization, context handling, and error patterns. Entry points are the main.go files in each subdirectory.
## Setup & environment
- Install: `go mod download`
- Run example: `go run examples/<name>/main.go`
- Env: Examples use environment variables from `.env` files when present
## Build & tests (prefer file-scoped)
- Typecheck a file: `go build -v examples/<name>/main.go`
- Format a file: `gofmt -w examples/<name>/main.go`
- Run example: `go run examples/<name>/main.go`
## Code style & conventions
- Examples should be self-contained and runnable
- Use clear variable names that explain the concept
- Include comments explaining non-obvious patterns
- Error handling should demonstrate best practices
- Keep examples focused on a single concept
## Security & safety
- Never include real credentials in examples
- Use placeholder values like "ldap.example.com"
- Document required permissions clearly
- Examples should fail gracefully without real LDAP server
## PR/commit checklist
- Examples must compile without errors
- Include README.md explaining the example's purpose
- Test example with both real and mock LDAP servers if possible
- Ensure examples follow library best practices
## Good vs. bad examples
- Good: `authentication/main.go` (clear flow, error handling)
- Good: `context-usage/main.go` (proper context propagation)
- Pattern to follow: Simple, focused, well-commented demonstrations
## When stuck
- Check the main library documentation in ../docs/
- Review similar examples in sibling directories
- Ensure you have the latest library version

348
references/examples/t3x-rte-ckeditor-image/AGENTS.md Normal file
View File

@@ -0,0 +1,348 @@
# AI Agent Development Guide
**Project:** rte_ckeditor_image - TYPO3 CKEditor 5 Image Extension
**Type:** TYPO3 CMS Extension (PHP 8.2+ + JavaScript/ES6)
**License:** GPL-2.0-or-later
## 📋 Documentation Structure
This project uses a three-tier documentation system:
- **[claudedocs/](claudedocs/)** - AI session context (Markdown, gitignored, temporary)
- **[Documentation/](Documentation/)** - Official TYPO3 docs (RST, published, permanent)
- **Root** - Project essentials (README, CONTRIBUTING, SECURITY, LICENSE)
See **[claudedocs/INDEX.md](claudedocs/INDEX.md)** for AI context navigation and **[Documentation/AGENTS.md](Documentation/AGENTS.md)** for TYPO3 documentation system guide.
## 🎯 Quick Start
```bash
# First time setup
composer install
make help # See all available targets
# Development workflow
make lint # Run all linters
make format # Fix code style
make test # Run tests
make ci # Full CI check (pre-commit)
# Composer shortcuts (if make unavailable)
composer ci:test:php:lint # PHP syntax check
composer ci:test:php:phpstan # Static analysis
composer ci:test:php:cgl # Code style check
composer ci:cgl # Fix code style
```
## 🏗️ Setup
### Prerequisites
- **PHP:** 8.2-8.9 with extensions: dom, libxml
- **Composer:** Latest stable
- **TYPO3:** 13.4+ (cms-core, cms-backend, cms-frontend, cms-rte-ckeditor)
- **direnv:** Optional but recommended
### Installation
```bash
# Clone and install
git clone https://github.com/netresearch/t3x-rte_ckeditor_image.git
cd t3x-rte_ckeditor_image
composer install
# Enable direnv (optional)
direnv allow
```
## 🔧 Build & Test Commands
### Fast Quality Checks (Pre-commit)
```bash
make lint # PHP lint + PHPStan + style check
make format # Auto-fix code style
make typecheck # PHPStan static analysis
```
### Full CI Suite
```bash
make ci # Complete CI pipeline
make test # All tests (when available)
```
### Individual Commands
```bash
# PHP Linting
composer ci:test:php:lint
# Static Analysis
composer ci:test:php:phpstan
# Code Style Check
composer ci:test:php:cgl
# Code Style Fix
composer ci:cgl
# Rector (PHP Modernization)
composer ci:test:php:rector
composer ci:rector # Apply changes
```
## 📝 Code Style
### PHP Standards
- **Base:** PSR-12 + PER-CS 2.0
- **Strict types:** Required in all files (`declare(strict_types=1);`)
- **Header comments:** Auto-managed by PHP-CS-Fixer
- **Config:** `Build/.php-cs-fixer.dist.php`
### Key Rules
```php
<?php
declare(strict_types=1);
/**
* This file is part of the package netresearch/rte-ckeditor-image.
*
* For the full copyright and license information, please read the
* LICENSE file that was distributed with this source code.
*/
namespace Netresearch\RteCKEditorImage\Controller;
// Imports: Classes, constants, functions
use TYPO3\CMS\Core\Utility\GeneralUtility;
// Alignment on = and =>
$config = [
'short' => 'value',
'longer' => 'another',
];
```
### JavaScript Standards
- **ES6 modules:** CKEditor 5 plugin format
- **No npm tooling:** TYPO3-managed assets
- **Style:** Follow CKEditor 5 conventions
- **Location:** `Resources/Public/JavaScript/`
## 🔒 Security
- **No secrets in VCS:** Use TYPO3's environment configuration
- **Dependency scanning:** Renovate enabled (see `renovate.json`)
- **Static analysis:** PHPStan with strict rules
- **TYPO3 security:** Follow TYPO3 Security Guidelines
- **File uploads:** Use FAL (File Abstraction Layer)
- **XSS prevention:** All output escaped via Fluid templates
## ✅ PR/Commit Checklist
Before committing:
1. ✅ **Lint passed:** `make lint` or `composer ci:test:php:lint`
2. ✅ **Style fixed:** `make format` or `composer ci:cgl`
3. ✅ **Static analysis:** `composer ci:test:php:phpstan` (no new errors)
4. ✅ **Rector check:** `composer ci:test:php:rector` (no suggestions)
5. ✅ **Docs updated:** Update relevant docs/ files if API changed
6. ✅ **CHANGELOG:** Add entry if user-facing change
7. ✅ **Conventional Commits:** Use format: `type(scope): message`
8. ✅ **Small PRs:** Keep ≤300 net LOC changed
### Commit Format
```
<type>(<scope>): <subject>
[optional body]
[optional footer]
```
**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
**Scopes:** `backend`, `frontend`, `config`, `docs`, `build`
**Examples:**
```
feat(backend): add image processing hook for WebP
fix(frontend): resolve style drop-down disabled for typo3image
docs(api): update DataHandling API reference
```
## 🎓 Good vs Bad Examples
### ✅ Good: TYPO3 Pattern
```php
<?php
declare(strict_types=1);
namespace Netresearch\RteCKEditorImage\Controller;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Resource\ResourceFactory;
final class SelectImageController
{
public function __construct(
private readonly ResourceFactory $resourceFactory
) {
}
public function infoAction(ServerRequestInterface $request): ResponseInterface
{
$fileUid = (int)($request->getQueryParams()['fileId'] ?? 0);
// Implementation...
}
}
```
### ❌ Bad: Missing strict types, no DI
```php
<?php
namespace Netresearch\RteCKEditorImage\Controller;
class SelectImageController
{
public function infoAction($request)
{
$fileUid = $_GET['fileId']; // Direct superglobal access
$factory = new ResourceFactory(); // No DI
}
}
```
### ✅ Good: CKEditor 5 Plugin
```javascript
export default class Typo3Image extends Core.Plugin {
static get requires() {
return ['StyleUtils', 'GeneralHtmlSupport'];
}
init() {
const editor = this.editor;
this.listenTo(styleUtils, 'isStyleEnabledForBlock', (event, [style]) => {
// Event handling...
});
}
}
```
### ❌ Bad: Missing dependencies
```javascript
class Typo3Image extends Core.Plugin {
// Missing requires() - breaks style integration
init() {
// Implementation...
}
}
```
## 🆘 When Stuck
1. **AI Context:** Start with [claudedocs/INDEX.md](claudedocs/INDEX.md) for project navigation
2. **Architecture:** Review [claudedocs/ARCHITECTURE.md](claudedocs/ARCHITECTURE.md)
3. **Security:** Check [claudedocs/SECURITY.md](claudedocs/SECURITY.md)
4. **API Reference:** See [claudedocs/API_REFERENCE.md](claudedocs/API_REFERENCE.md)
5. **Development Guide:** Follow [claudedocs/DEVELOPMENT_GUIDE.md](claudedocs/DEVELOPMENT_GUIDE.md)
6. **TYPO3 Docs Guide:** Read [Documentation/AGENTS.md](Documentation/AGENTS.md)
7. **Published Manual:** https://docs.typo3.org/p/netresearch/rte-ckeditor-image/main/en-us/
8. **TYPO3 Core Docs:** https://docs.typo3.org/
9. **Issues:** https://github.com/netresearch/t3x-rte_ckeditor_image/issues
### Common Issues
- **Style drop-down disabled:** Missing `GeneralHtmlSupport` dependency (v13.0.0+)
- **Images not in frontend:** Missing static template include
- **PHPStan errors:** Run `composer ci:test:php:phpstan:baseline` to update baseline
- **Code style fails:** Run `composer ci:cgl` to auto-fix
## 📐 House Rules
### Commits & PRs
- **Atomic commits:** One logical change per commit
- **Conventional Commits:** Required format (see checklist)
- **Small PRs:** Target ≤300 net LOC changed
- **Branch naming:** `feature/short-description`, `fix/issue-123`
### Design Principles
- **SOLID:** Single responsibility, Open/closed, Liskov, Interface segregation, Dependency inversion
- **KISS:** Keep it simple, stupid
- **DRY:** Don't repeat yourself
- **YAGNI:** You aren't gonna need it
- **Composition > Inheritance:** Prefer composition
- **Law of Demeter:** Minimize coupling
### Dependencies
- **Latest stable:** Use current TYPO3 13.4+ versions
- **Renovate:** Auto-updates enabled
- **Major updates:** Require changelog review + migration notes
- **Composer:** Lock file committed
### API & Versioning
- **SemVer:** Semantic versioning (MAJOR.MINOR.PATCH)
- **TYPO3 compatibility:** Follow TYPO3 versioning
- **Breaking changes:** Increment major version
- **Deprecations:** Add `@deprecated` tag + removal plan
### Testing
- **TYPO3 Testing Framework:** Use `typo3/testing-framework`
- **Functional tests:** For database/integration scenarios
- **Unit tests:** For isolated logic
- **Test location:** `Tests/Functional/`, `Tests/Unit/`
### Licensing
- **License:** AGPL-3.0-or-later
- **SPDX:** Use SPDX identifiers
- **Headers:** Auto-managed by PHP-CS-Fixer
- **Third-party:** Document in CHANGELOG
## 🔗 Related Files
**Root Documentation:**
- **[README.md](README.md)** - Project overview and quick links
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
- **[SECURITY.md](SECURITY.md)** - Security policy
- **[LICENSE](LICENSE)** - GPL-2.0-or-later license
**AI Session Context (gitignored):**
- **[claudedocs/INDEX.md](claudedocs/INDEX.md)** - Navigation hub
- **[claudedocs/PROJECT_OVERVIEW.md](claudedocs/PROJECT_OVERVIEW.md)** - Project summary
- **[claudedocs/ARCHITECTURE.md](claudedocs/ARCHITECTURE.md)** - System design
- **[claudedocs/DEVELOPMENT_GUIDE.md](claudedocs/DEVELOPMENT_GUIDE.md)** - Development workflow
- **[claudedocs/API_REFERENCE.md](claudedocs/API_REFERENCE.md)** - PHP API docs
- **[claudedocs/SECURITY.md](claudedocs/SECURITY.md)** - Security analysis
**Official TYPO3 Documentation:**
- **[Documentation/](Documentation/)** - RST documentation (published)
- **[Documentation/AGENTS.md](Documentation/AGENTS.md)** - TYPO3 docs system guide
**Configuration:**
- **[composer.json](composer.json)** - Dependencies & scripts
- **[Build/](Build/)** - Development tools configuration
## 📚 Additional Resources
- **Repository:** https://github.com/netresearch/t3x-rte_ckeditor_image
- **Packagist:** https://packagist.org/packages/netresearch/rte-ckeditor-image
- **TYPO3 Ext:** https://extensions.typo3.org/extension/rte_ckeditor_image
- **TYPO3 Docs:** https://docs.typo3.org/
- **CKEditor 5:** https://ckeditor.com/docs/ckeditor5/

392
references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.md Normal file
View File

@@ -0,0 +1,392 @@
# Classes/AGENTS.md
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-15 -->
**Scope:** PHP backend components (Controllers, EventListeners, DataHandling, Utils)
**Parent:** [../AGENTS.md](../AGENTS.md)
## 📋 Overview
PHP backend implementation for TYPO3 CKEditor Image extension. Components:
### Controllers
- **SelectImageController** - Image browser wizard, file selection, image info API
- **ImageRenderingController** - Image rendering and processing for frontend
- **ImageLinkRenderingController** - Link-wrapped image rendering
### EventListeners
- **RteConfigurationListener** - PSR-14 event for RTE configuration injection
### DataHandling
- **RteImagesDbHook** - Database hooks for image magic reference handling
- **RteImageSoftReferenceParser** - Soft reference parsing for RTE images
### Backend Components
- **RteImagePreviewRenderer** - Backend preview rendering
### Utilities
- **ProcessedFilesHandler** - File processing and manipulation utilities
## 🏗️ Architecture Patterns
### TYPO3 Patterns
- **FAL (File Abstraction Layer):** All file operations via ResourceFactory
- **PSR-7 Request/Response:** HTTP message interfaces for controllers
- **PSR-14 Events:** Event-driven configuration and hooks
- **Dependency Injection:** Constructor-based DI (TYPO3 v13+)
- **Service Configuration:** `Configuration/Services.yaml` for DI registration
### File Structure
```
Classes/
├── Backend/
│ └── Preview/
│ └── RteImagePreviewRenderer.php
├── Controller/
│ ├── ImageLinkRenderingController.php
│ ├── ImageRenderingController.php
│ └── SelectImageController.php
├── DataHandling/
│ └── SoftReference/
│ └── RteImageSoftReferenceParser.php
├── Database/
│ └── RteImagesDbHook.php
├── EventListener/
│ └── RteConfigurationListener.php
└── Utils/
└── ProcessedFilesHandler.php
```
## 🔧 Build & Tests
```bash
# PHP-specific quality checks
make lint # All linters (syntax + PHPStan + Rector + style)
composer ci:test:php:lint # PHP syntax check
composer ci:test:php:phpstan # Static analysis
composer ci:test:php:rector # Rector modernization check
composer ci:test:php:cgl # Code style check
# Fixes
make format # Auto-fix code style
composer ci:cgl # Alternative: fix style
composer ci:rector # Apply Rector changes
# Full CI
make ci # Complete pipeline
```
## 📝 Code Style
### Required Patterns
**1. Strict Types (Always First)**
```php
<?php
declare(strict_types=1);
```
**2. File Header (Auto-managed by PHP-CS-Fixer)**
```php
/**
* This file is part of the package netresearch/rte-ckeditor-image.
*
* For the full copyright and license information, please read the
* LICENSE file that was distributed with this source code.
*/
```
**3. Import Order**
- Classes first
- Functions second
- Constants third
- One blank line before namespace
**4. Type Hints**
- All parameters must have type hints
- All return types must be declared
- Use nullable types `?Type` when appropriate
- Use union types `Type1|Type2` for PHP 8+
**5. Property Types**
```php
private ResourceFactory $resourceFactory; // Required type declaration
private readonly ResourceFactory $factory; // Readonly for immutability
```
**6. Alignment**
```php
$config = [
'short' => 'value', // Align on =>
'longer' => 'another',
];
```
## 🔒 Security
### FAL (File Abstraction Layer)
- **Always use FAL:** Never direct file system access
- **ResourceFactory:** For retrieving files by UID
- **File validation:** Check isDeleted(), isMissing()
- **ProcessedFile:** Use process() for image manipulation
```php
// ✅ Good: FAL usage
$file = $this->resourceFactory->getFileObject($id);
if ($file->isDeleted() || $file->isMissing()) {
throw new \Exception('File not found');
}
// ❌ Bad: Direct file access
$file = file_get_contents('/var/www/uploads/' . $filename);
```
### Input Validation
- **Type cast superglobals:** `(int)($request->getQueryParams()['id'] ?? 0)`
- **Validate before use:** Check ranges, formats, existence
- **Exit on error:** Use HTTP status codes with `HttpUtility::HTTP_STATUS_*`
### XSS Prevention
- **Fluid templates:** Auto-escaping enabled by default
- **JSON responses:** Use `JsonResponse` class
- **Localization:** Via `LocalizationUtility::translate()`
## ✅ PR/Commit Checklist
### PHP-Specific Checks
1. ✅ **Strict types:** `declare(strict_types=1);` in all files
2. ✅ **Type hints:** All parameters and return types declared
3. ✅ **PHPStan:** Zero errors (`composer ci:test:php:phpstan`)
4. ✅ **Code style:** PSR-12/PER-CS2.0 compliant (`make format`)
5. ✅ **Rector:** No modernization suggestions (`composer ci:test:php:rector`)
6. ✅ **FAL usage:** No direct file system access
7. ✅ **DI pattern:** Constructor injection, no `new ClassName()`
8. ✅ **PSR-7:** Request/Response for controllers
9. ✅ **Documentation:** PHPDoc for public methods
## 🎓 Good vs Bad Examples
### ✅ Good: Controller Pattern
```php
<?php
declare(strict_types=1);
namespace Netresearch\RteCKEditorImage\Controller;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Http\JsonResponse;
use TYPO3\CMS\Core\Resource\ResourceFactory;
final class SelectImageController
{
public function __construct(
private readonly ResourceFactory $resourceFactory
) {
}
public function infoAction(ServerRequestInterface $request): ResponseInterface
{
$fileUid = (int)($request->getQueryParams()['fileId'] ?? 0);
if ($fileUid <= 0) {
return new JsonResponse(['error' => 'Invalid file ID'], 400);
}
$file = $this->resourceFactory->getFileObject($fileUid);
return new JsonResponse([
'uid' => $file->getUid(),
'width' => $file->getProperty('width'),
'height' => $file->getProperty('height'),
]);
}
}
```
### ❌ Bad: Anti-patterns
```php
<?php
// ❌ Missing strict types
namespace Netresearch\RteCKEditorImage\Controller;
// ❌ Missing PSR-7 types
class SelectImageController
{
// ❌ No constructor DI
public function infoAction($request)
{
// ❌ Direct superglobal access
$fileUid = $_GET['fileId'];
// ❌ No DI - manual instantiation
$factory = new ResourceFactory();
// ❌ No type safety, no validation
$file = $factory->getFileObject($fileUid);
// ❌ Manual JSON encoding
header('Content-Type: application/json');
echo json_encode(['uid' => $file->getUid()]);
exit;
}
}
```
### ✅ Good: EventListener Pattern
```php
<?php
declare(strict_types=1);
namespace Netresearch\RteCKEditorImage\EventListener;
use TYPO3\CMS\Backend\Routing\UriBuilder;
use TYPO3\CMS\RteCKEditor\Form\Element\Event\AfterPrepareConfigurationForEditorEvent;
final class RteConfigurationListener
{
public function __construct(
private readonly UriBuilder $uriBuilder
) {
}
public function __invoke(AfterPrepareConfigurationForEditorEvent $event): void
{
$configuration = $event->getConfiguration();
$configuration['style']['typo3image'] = [
'routeUrl' => (string)$this->uriBuilder->buildUriFromRoute('rteckeditorimage_wizard_select_image'),
];
$event->setConfiguration($configuration);
}
}
```
### ❌ Bad: EventListener Anti-pattern
```php
<?php
namespace Netresearch\RteCKEditorImage\EventListener;
class RteConfigurationListener
{
// ❌ Wrong signature - not invokable
public function handle($event)
{
// ❌ Manual instantiation instead of DI
$uriBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(UriBuilder::class);
// ❌ Array access without type safety
$config = $event->getConfiguration();
$config['style']['typo3image']['routeUrl'] = $uriBuilder->buildUriFromRoute('rteckeditorimage_wizard_select_image');
$event->setConfiguration($config);
}
}
```
### ✅ Good: FAL Usage
```php
protected function getImage(int $id): File
{
try {
$file = $this->resourceFactory->getFileObject($id);
if ($file->isDeleted() || $file->isMissing()) {
throw new FileNotFoundException('File not found or deleted', 1234567890);
}
} catch (\Exception $e) {
throw new FileNotFoundException('Could not load file', 1234567891, $e);
}
return $file;
}
```
### ❌ Bad: Direct File Access
```php
// ❌ Multiple issues
protected function getImage($id) // Missing return type, no type hint
{
// ❌ Direct file system access, bypassing FAL
$path = '/var/www/html/fileadmin/' . $id;
// ❌ No validation, no error handling
if (file_exists($path)) {
return file_get_contents($path);
}
return null; // ❌ Should throw exception or return typed null
}
```
## 🆘 When Stuck
### Documentation
- **API Reference:** [docs/API/Controllers.md](../docs/API/Controllers.md) - Controller APIs
- **Event Listeners:** [docs/API/EventListeners.md](../docs/API/EventListeners.md) - PSR-14 events
- **Data Handling:** [docs/API/DataHandling.md](../docs/API/DataHandling.md) - Database hooks
- **Architecture:** [docs/Architecture/Overview.md](../docs/Architecture/Overview.md) - System design
### TYPO3 Resources
- **FAL Documentation:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Fal/Index.html
- **PSR-14 Events:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Events/Index.html
- **Dependency Injection:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/DependencyInjection/Index.html
- **Controllers:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Backend/Controllers/Index.html
### Common Issues
- **ResourceFactory errors:** Check file exists, not deleted, proper UID
- **DI not working:** Verify `Configuration/Services.yaml` registration
- **PHPStan errors:** Update baseline: `composer ci:test:php:phpstan:baseline`
- **Type errors:** Enable strict_types, add all type hints
## 📐 House Rules
### Controllers
- **Extend framework controllers:** ElementBrowserController for browsers
- **Final by default:** Use `final class` unless inheritance required
- **PSR-7 types:** ServerRequestInterface → ResponseInterface
- **JSON responses:** Use `JsonResponse` class
- **Validation first:** Validate all input parameters at method start
### EventListeners
- **Invokable:** Use `__invoke()` method signature
- **Event type hints:** Type-hint specific event classes
- **Immutability aware:** Get, modify, set configuration/state
- **Final classes:** Event listeners should be final
### DataHandling
- **Soft references:** Implement soft reference parsing for data integrity
- **Database hooks:** Use for maintaining referential integrity
- **Transaction safety:** Consider rollback scenarios
### Dependencies
- **Constructor injection:** All dependencies via constructor
- **Readonly properties:** Use `readonly` for immutable dependencies
- **Interface over implementation:** Depend on interfaces when available
- **GeneralUtility::makeInstance:** Only for factories or when DI unavailable
### Error Handling
- **Type-specific exceptions:** Use TYPO3 exception hierarchy
- **HTTP status codes:** Via HttpUtility constants
- **Meaningful messages:** Include context in exception messages
- **Log important errors:** Use TYPO3 logging framework
### Testing
- **Functional tests:** For controllers, database operations
- **Unit tests:** For utilities, isolated logic
- **Mock FAL:** Use TYPO3 testing framework FAL mocks
- **Test location:** `Tests/Functional/` and `Tests/Unit/`
## 🔗 Related
- **[Resources/AGENTS.md](../Resources/AGENTS.md)** - JavaScript/CKEditor integration
- **[Tests/AGENTS.md](../Tests/AGENTS.md)** - Testing patterns
- **[Configuration/Services.yaml](../Configuration/Services.yaml)** - DI container configuration
- **[docs/API/](../docs/API/)** - Complete API documentation

199
scripts/detect-project.sh Executable file
View File

@@ -0,0 +1,199 @@
#!/usr/bin/env bash
# Detect project type, language, version, and build tools
set -euo pipefail
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"
# Initialize variables
LANGUAGE="unknown"
VERSION="unknown"
BUILD_TOOL="unknown"
FRAMEWORK="none"
PROJECT_TYPE="unknown"
QUALITY_TOOLS=()
TEST_FRAMEWORK="unknown"
HAS_DOCKER=false
CI="none"
# Detect language and version
detect_language() {
if [ -f "go.mod" ]; then
LANGUAGE="go"
VERSION=$(grep '^go ' go.mod | awk '{print $2}' || echo "unknown")
BUILD_TOOL="go"
TEST_FRAMEWORK="testing"
# Detect Go project type
if [ -d "cmd" ]; then
PROJECT_TYPE="go-cli"
elif grep -q "github.com/gofiber/fiber" go.mod 2>/dev/null; then
PROJECT_TYPE="go-web-app"
FRAMEWORK="fiber"
elif grep -q "github.com/labstack/echo" go.mod 2>/dev/null; then
PROJECT_TYPE="go-web-app"
FRAMEWORK="echo"
elif grep -q "github.com/gin-gonic/gin" go.mod 2>/dev/null; then
PROJECT_TYPE="go-web-app"
FRAMEWORK="gin"
else
PROJECT_TYPE="go-library"
fi
# Detect Go quality tools
[ -f ".golangci.yml" ] || [ -f ".golangci.yaml" ] && QUALITY_TOOLS+=("golangci-lint")
command -v gofmt &>/dev/null && QUALITY_TOOLS+=("gofmt")
elif [ -f "composer.json" ]; then
LANGUAGE="php"
VERSION=$(jq -r '.require.php // "unknown"' composer.json 2>/dev/null || echo "unknown")
BUILD_TOOL="composer"
# Detect PHP framework
if jq -e '.require."typo3/cms-core"' composer.json &>/dev/null; then
PROJECT_TYPE="php-typo3"
FRAMEWORK="typo3"
TYPO3_VERSION=$(jq -r '.require."typo3/cms-core"' composer.json 2>/dev/null || echo "unknown")
elif jq -e '.require."laravel/framework"' composer.json &>/dev/null; then
PROJECT_TYPE="php-laravel"
FRAMEWORK="laravel"
elif jq -e '.require."symfony/symfony"' composer.json &>/dev/null; then
PROJECT_TYPE="php-symfony"
FRAMEWORK="symfony"
else
PROJECT_TYPE="php-library"
fi
# Detect PHP quality tools
jq -e '.require."phpstan/phpstan"' composer.json &>/dev/null && QUALITY_TOOLS+=("phpstan")
jq -e '.require."friendsofphp/php-cs-fixer"' composer.json &>/dev/null && QUALITY_TOOLS+=("php-cs-fixer")
[ -f "phpunit.xml" ] || [ -f "phpunit.xml.dist" ] && TEST_FRAMEWORK="phpunit"
elif [ -f "package.json" ]; then
LANGUAGE="typescript"
VERSION=$(jq -r '.engines.node // "unknown"' package.json 2>/dev/null || echo "unknown")
# Detect JS/TS framework
if jq -e '.dependencies."next"' package.json &>/dev/null; then
PROJECT_TYPE="typescript-nextjs"
FRAMEWORK="next.js"
BUILD_TOOL="npm"
elif jq -e '.dependencies."react"' package.json &>/dev/null; then
PROJECT_TYPE="typescript-react"
FRAMEWORK="react"
BUILD_TOOL="npm"
elif jq -e '.dependencies."vue"' package.json &>/dev/null; then
PROJECT_TYPE="typescript-vue"
FRAMEWORK="vue"
BUILD_TOOL="npm"
elif jq -e '.dependencies."express"' package.json &>/dev/null; then
PROJECT_TYPE="typescript-node"
FRAMEWORK="express"
BUILD_TOOL="npm"
else
PROJECT_TYPE="typescript-library"
BUILD_TOOL="npm"
fi
# Check for yarn/pnpm
[ -f "yarn.lock" ] && BUILD_TOOL="yarn"
[ -f "pnpm-lock.yaml" ] && BUILD_TOOL="pnpm"
# Detect quality tools
jq -e '.devDependencies."eslint"' package.json &>/dev/null && QUALITY_TOOLS+=("eslint")
jq -e '.devDependencies."prettier"' package.json &>/dev/null && QUALITY_TOOLS+=("prettier")
jq -e '.devDependencies."typescript"' package.json &>/dev/null && QUALITY_TOOLS+=("tsc")
# Detect test framework
if jq -e '.devDependencies."jest"' package.json &>/dev/null; then
TEST_FRAMEWORK="jest"
elif jq -e '.devDependencies."vitest"' package.json &>/dev/null; then
TEST_FRAMEWORK="vitest"
fi
elif [ -f "pyproject.toml" ]; then
LANGUAGE="python"
VERSION=$(grep 'requires-python' pyproject.toml | cut -d'"' -f2 2>/dev/null || echo "unknown")
# Detect Python build tool
if grep -q '\[tool.poetry\]' pyproject.toml 2>/dev/null; then
BUILD_TOOL="poetry"
elif grep -q '\[tool.hatch\]' pyproject.toml 2>/dev/null; then
BUILD_TOOL="hatch"
else
BUILD_TOOL="pip"
fi
# Detect framework
if grep -q 'django' pyproject.toml 2>/dev/null; then
PROJECT_TYPE="python-django"
FRAMEWORK="django"
elif grep -q 'flask' pyproject.toml 2>/dev/null; then
PROJECT_TYPE="python-flask"
FRAMEWORK="flask"
elif grep -q 'fastapi' pyproject.toml 2>/dev/null; then
PROJECT_TYPE="python-fastapi"
FRAMEWORK="fastapi"
elif [ -d "scripts" ] && [ "$(find scripts -name '*.py' | wc -l)" -gt 3 ]; then
PROJECT_TYPE="python-cli"
else
PROJECT_TYPE="python-library"
fi
# Detect quality tools
grep -q 'ruff' pyproject.toml 2>/dev/null && QUALITY_TOOLS+=("ruff")
grep -q 'black' pyproject.toml 2>/dev/null && QUALITY_TOOLS+=("black")
grep -q 'mypy' pyproject.toml 2>/dev/null && QUALITY_TOOLS+=("mypy")
grep -q 'pytest' pyproject.toml 2>/dev/null && TEST_FRAMEWORK="pytest"
fi
}
# Detect if Makefile exists
if [ -f "Makefile" ]; then
BUILD_TOOL="make"
fi
# Detect Docker
[ -f "Dockerfile" ] || [ -f "docker-compose.yml" ] && HAS_DOCKER=true
# Detect CI
if [ -d ".github/workflows" ]; then
CI="github-actions"
elif [ -f ".gitlab-ci.yml" ]; then
CI="gitlab-ci"
elif [ -f ".circleci/config.yml" ]; then
CI="circleci"
fi
# Run detection
detect_language
# Output JSON
# Handle empty quality_tools array
if [ ${#QUALITY_TOOLS[@]} -eq 0 ]; then
TOOLS_JSON="[]"
else
TOOLS_JSON="$(printf '%s\n' "${QUALITY_TOOLS[@]}" | jq -R . | jq -s .)"
fi
jq -n \
--arg type "$PROJECT_TYPE" \
--arg lang "$LANGUAGE" \
--arg ver "$VERSION" \
--arg build "$BUILD_TOOL" \
--arg framework "$FRAMEWORK" \
--argjson docker "$HAS_DOCKER" \
--argjson tools "$TOOLS_JSON" \
--arg test "$TEST_FRAMEWORK" \
--arg ci "$CI" \
'{
type: $type,
language: $lang,
version: $ver,
build_tool: $build,
framework: $framework,
has_docker: $docker,
quality_tools: $tools,
test_framework: $test,
ci: $ci
}'

178
scripts/detect-scopes.sh Executable file
View File

@@ -0,0 +1,178 @@
#!/usr/bin/env bash
# Detect directories that should have scoped AGENTS.md files
set -euo pipefail
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"
MIN_FILES=5 # Minimum files to warrant scoped AGENTS.md
# Get project info
PROJECT_INFO=$(bash "$(dirname "$0")/detect-project.sh" "$PROJECT_DIR")
LANGUAGE=$(echo "$PROJECT_INFO" | jq -r '.language')
scopes=()
# Function to count source files in a directory
count_source_files() {
local dir="$1"
local pattern="$2"
find "$dir" -maxdepth 3 -type f -name "$pattern" 2>/dev/null | wc -l
}
# Function to add scope
add_scope() {
local path="$1"
local type="$2"
local count="$3"
scopes+=("{\"path\": \"$path\", \"type\": \"$type\", \"files\": $count}")
}
# Language-specific scope detection
case "$LANGUAGE" in
"go")
# Check common Go directories
[ -d "internal" ] && {
count=$(count_source_files "internal" "*.go")
[ "$count" -ge "$MIN_FILES" ] && add_scope "internal" "backend-go" "$count"
}
[ -d "pkg" ] && {
count=$(count_source_files "pkg" "*.go")
[ "$count" -ge "$MIN_FILES" ] && add_scope "pkg" "backend-go" "$count"
}
[ -d "cmd" ] && {
count=$(count_source_files "cmd" "*.go")
[ "$count" -ge 3 ] && add_scope "cmd" "cli" "$count"
}
[ -d "examples" ] && {
count=$(count_source_files "examples" "*.go")
[ "$count" -ge 3 ] && add_scope "examples" "examples" "$count"
}
[ -d "testutil" ] && {
count=$(count_source_files "testutil" "*.go")
[ "$count" -ge 3 ] && add_scope "testutil" "testing" "$count"
}
[ -d "docs" ] && {
count=$(find docs -type f \( -name "*.md" -o -name "*.rst" \) | wc -l)
[ "$count" -ge 3 ] && add_scope "docs" "documentation" "$count"
}
;;
"php")
# Check common PHP directories
[ -d "Classes" ] && {
count=$(count_source_files "Classes" "*.php")
[ "$count" -ge "$MIN_FILES" ] && add_scope "Classes" "backend-php" "$count"
}
[ -d "src" ] && {
count=$(count_source_files "src" "*.php")
[ "$count" -ge "$MIN_FILES" ] && add_scope "src" "backend-php" "$count"
}
[ -d "Tests" ] && {
count=$(count_source_files "Tests" "*.php")
[ "$count" -ge 3 ] && add_scope "Tests" "testing" "$count"
}
[ -d "tests" ] && {
count=$(count_source_files "tests" "*.php")
[ "$count" -ge 3 ] && add_scope "tests" "testing" "$count"
}
[ -d "Documentation" ] && {
count=$(find Documentation -type f \( -name "*.rst" -o -name "*.md" \) | wc -l)
[ "$count" -ge 3 ] && add_scope "Documentation" "documentation" "$count"
}
[ -d "Resources" ] && {
count=$(find Resources -type f | wc -l)
[ "$count" -ge 5 ] && add_scope "Resources" "resources" "$count"
}
;;
"typescript")
# Check common TypeScript/JavaScript directories
[ -d "src" ] && {
count=$(count_source_files "src" "*.ts")
ts_count=$count
count=$(count_source_files "src" "*.tsx")
tsx_count=$count
if [ "$tsx_count" -ge "$MIN_FILES" ]; then
add_scope "src" "frontend-typescript" "$tsx_count"
elif [ "$ts_count" -ge "$MIN_FILES" ]; then
add_scope "src" "backend-typescript" "$ts_count"
fi
}
[ -d "components" ] && {
count=$(count_source_files "components" "*.tsx")
[ "$count" -ge "$MIN_FILES" ] && add_scope "components" "frontend-typescript" "$count"
}
[ -d "pages" ] && {
count=$(count_source_files "pages" "*.tsx")
[ "$count" -ge 3 ] && add_scope "pages" "frontend-typescript" "$count"
}
[ -d "app" ] && {
count=$(count_source_files "app" "*.tsx")
[ "$count" -ge 3 ] && add_scope "app" "frontend-typescript" "$count"
}
[ -d "server" ] || [ -d "backend" ] && {
dir=$([ -d "server" ] && echo "server" || echo "backend")
count=$(count_source_files "$dir" "*.ts")
[ "$count" -ge "$MIN_FILES" ] && add_scope "$dir" "backend-typescript" "$count"
}
[ -d "__tests__" ] || [ -d "tests" ] && {
dir=$([ -d "__tests__" ] && echo "__tests__" || echo "tests")
count=$(count_source_files "$dir" "*.test.ts")
[ "$count" -ge 3 ] && add_scope "$dir" "testing" "$count"
}
;;
"python")
# Check common Python directories
[ -d "src" ] && {
count=$(count_source_files "src" "*.py")
[ "$count" -ge "$MIN_FILES" ] && add_scope "src" "backend-python" "$count"
}
[ -d "tests" ] && {
count=$(count_source_files "tests" "*.py")
[ "$count" -ge 3 ] && add_scope "tests" "testing" "$count"
}
[ -d "scripts" ] && {
count=$(count_source_files "scripts" "*.py")
[ "$count" -ge 3 ] && add_scope "scripts" "cli" "$count"
}
[ -d "docs" ] && {
count=$(find docs -type f \( -name "*.md" -o -name "*.rst" \) | wc -l)
[ "$count" -ge 3 ] && add_scope "docs" "documentation" "$count"
}
;;
esac
# Check for web subdirectories (cross-language)
if [ -d "internal/web" ]; then
count=$(find internal/web -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) | wc -l)
[ "$count" -ge "$MIN_FILES" ] && add_scope "internal/web" "frontend-typescript" "$count"
fi
# Output JSON
if [ ${#scopes[@]} -eq 0 ]; then
echo '{"scopes": []}'
else
echo "{\"scopes\": [$(IFS=,; echo "${scopes[*]}")]}"
fi

183
scripts/extract-commands.sh Executable file
View File

@@ -0,0 +1,183 @@
#!/usr/bin/env bash
# Extract build commands from various build tool files
set -euo pipefail
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"
# Get project info
PROJECT_INFO=$(bash "$(dirname "$0")/detect-project.sh" "$PROJECT_DIR")
LANGUAGE=$(echo "$PROJECT_INFO" | jq -r '.language')
BUILD_TOOL=$(echo "$PROJECT_INFO" | jq -r '.build_tool')
# Initialize command variables
TYPECHECK_CMD=""
LINT_CMD=""
FORMAT_CMD=""
TEST_CMD=""
BUILD_CMD=""
DEV_CMD=""
# Extract from Makefile
extract_from_makefile() {
[ ! -f "Makefile" ] && return
# Extract targets with ## comments
while IFS= read -r line; do
if [[ $line =~ ^([a-zA-Z_-]+):.*\#\#(.*)$ ]]; then
target="${BASH_REMATCH[1]}"
description="${BASH_REMATCH[2]}"
case "$target" in
lint|check) LINT_CMD="make $target" ;;
format|fmt) FORMAT_CMD="make $target" ;;
test|tests) TEST_CMD="make $target" ;;
build) BUILD_CMD="make $target" ;;
typecheck|types) TYPECHECK_CMD="make $target" ;;
dev|serve) DEV_CMD="make $target" ;;
esac
fi
done < Makefile
}
# Extract from package.json
extract_from_package_json() {
[ ! -f "package.json" ] && return
TYPECHECK_CMD=$(jq -r '.scripts.typecheck // .scripts["type-check"] // empty' package.json 2>/dev/null)
[ -n "$TYPECHECK_CMD" ] && TYPECHECK_CMD="npm run typecheck" || TYPECHECK_CMD="npx tsc --noEmit"
LINT_CMD=$(jq -r '.scripts.lint // empty' package.json 2>/dev/null)
[ -n "$LINT_CMD" ] && LINT_CMD="npm run lint" || LINT_CMD="npx eslint ."
FORMAT_CMD=$(jq -r '.scripts.format // empty' package.json 2>/dev/null)
[ -n "$FORMAT_CMD" ] && FORMAT_CMD="npm run format" || FORMAT_CMD="npx prettier --write ."
TEST_CMD=$(jq -r '.scripts.test // empty' package.json 2>/dev/null)
[ -n "$TEST_CMD" ] && TEST_CMD="npm test"
BUILD_CMD=$(jq -r '.scripts.build // empty' package.json 2>/dev/null)
[ -n "$BUILD_CMD" ] && BUILD_CMD="npm run build"
DEV_CMD=$(jq -r '.scripts.dev // .scripts.start // empty' package.json 2>/dev/null)
[ -n "$DEV_CMD" ] && DEV_CMD="npm run dev"
}
# Extract from composer.json
extract_from_composer_json() {
[ ! -f "composer.json" ] && return
LINT_CMD=$(jq -r '.scripts.lint // .scripts["cs:check"] // empty' composer.json 2>/dev/null)
[ -n "$LINT_CMD" ] && LINT_CMD="composer run lint"
FORMAT_CMD=$(jq -r '.scripts.format // .scripts["cs:fix"] // empty' composer.json 2>/dev/null)
[ -n "$FORMAT_CMD" ] && FORMAT_CMD="composer run format"
TEST_CMD=$(jq -r '.scripts.test // empty' composer.json 2>/dev/null)
[ -n "$TEST_CMD" ] && TEST_CMD="composer run test" || TEST_CMD="vendor/bin/phpunit"
TYPECHECK_CMD=$(jq -r '.scripts.phpstan // .scripts["stan"] // empty' composer.json 2>/dev/null)
[ -n "$TYPECHECK_CMD" ] && TYPECHECK_CMD="composer run phpstan" || {
if [ -f "phpstan.neon" ] || [ -f "Build/phpstan.neon" ]; then
TYPECHECK_CMD="vendor/bin/phpstan analyze"
fi
}
}
# Extract from pyproject.toml
extract_from_pyproject() {
[ ! -f "pyproject.toml" ] && return
# Check for ruff
if grep -q '\[tool.ruff\]' pyproject.toml; then
LINT_CMD="ruff check ."
FORMAT_CMD="ruff format ."
fi
# Check for black
if grep -q 'black' pyproject.toml; then
FORMAT_CMD="black ."
fi
# Check for mypy
if grep -q 'mypy' pyproject.toml; then
TYPECHECK_CMD="mypy ."
fi
# Check for pytest
if grep -q 'pytest' pyproject.toml; then
TEST_CMD="pytest"
fi
}
# Language-specific defaults
set_language_defaults() {
case "$LANGUAGE" in
"go")
[ -z "$TYPECHECK_CMD" ] && TYPECHECK_CMD="go build -v ./..."
[ -z "$LINT_CMD" ] && {
if [ -f ".golangci.yml" ] || [ -f ".golangci.yaml" ]; then
LINT_CMD="golangci-lint run ./..."
fi
}
[ -z "$FORMAT_CMD" ] && FORMAT_CMD="gofmt -w ."
[ -z "$TEST_CMD" ] && TEST_CMD="go test -v -race -short ./..."
[ -z "$BUILD_CMD" ] && BUILD_CMD="go build -v ./..."
;;
"php")
[ -z "$TYPECHECK_CMD" ] && {
if [ -f "phpstan.neon" ] || [ -f "Build/phpstan.neon" ]; then
TYPECHECK_CMD="vendor/bin/phpstan analyze"
fi
}
[ -z "$LINT_CMD" ] && LINT_CMD="vendor/bin/php-cs-fixer fix --dry-run"
[ -z "$FORMAT_CMD" ] && FORMAT_CMD="vendor/bin/php-cs-fixer fix"
[ -z "$TEST_CMD" ] && TEST_CMD="vendor/bin/phpunit"
;;
"typescript")
[ -z "$TYPECHECK_CMD" ] && TYPECHECK_CMD="npx tsc --noEmit"
[ -z "$LINT_CMD" ] && LINT_CMD="npx eslint ."
[ -z "$FORMAT_CMD" ] && FORMAT_CMD="npx prettier --write ."
[ -z "$TEST_CMD" ] && {
if [ -f "jest.config.js" ] || [ -f "jest.config.ts" ]; then
TEST_CMD="npm test"
elif grep -q 'vitest' package.json 2>/dev/null; then
TEST_CMD="npx vitest"
fi
}
;;
"python")
[ -z "$LINT_CMD" ] && LINT_CMD="ruff check ."
[ -z "$FORMAT_CMD" ] && FORMAT_CMD="ruff format ."
[ -z "$TYPECHECK_CMD" ] && TYPECHECK_CMD="mypy ."
[ -z "$TEST_CMD" ] && TEST_CMD="pytest"
;;
esac
}
# Run extraction
extract_from_makefile
extract_from_package_json
extract_from_composer_json
extract_from_pyproject
set_language_defaults
# Output JSON
jq -n \
--arg typecheck "$TYPECHECK_CMD" \
--arg lint "$LINT_CMD" \
--arg format "$FORMAT_CMD" \
--arg test "$TEST_CMD" \
--arg build "$BUILD_CMD" \
--arg dev "$DEV_CMD" \
'{
typecheck: $typecheck,
lint: $lint,
format: $format,
test: $test,
build: $build,
dev: $dev
}'

292
scripts/generate-agents.sh Executable file
View File

@@ -0,0 +1,292 @@
#!/usr/bin/env bash
# Main AGENTS.md generator script
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_DIR/templates"
# Source helper library
source "$SCRIPT_DIR/lib/template.sh"
# Default options
PROJECT_DIR="${1:-.}"
STYLE="${STYLE:-thin}"
DRY_RUN=false
UPDATE_ONLY=false
FORCE=false
VERBOSE=false
# Parse flags
while [[ $# -gt 0 ]]; do
case $1 in
--style=*)
STYLE="${1#*=}"
shift
;;
--dry-run)
DRY_RUN=true
shift
;;
--update)
UPDATE_ONLY=true
shift
;;
--force)
FORCE=true
shift
;;
--verbose|-v)
VERBOSE=true
shift
;;
--help|-h)
cat <<EOF
Usage: generate-agents.sh [PROJECT_DIR] [OPTIONS]
Generate AGENTS.md files for a project following the public agents.md convention.
Options:
--style=thin|verbose Template style (default: thin)
--dry-run Preview what will be created
--update Update existing files only
--force Force regeneration of existing files
--verbose, -v Verbose output
--help, -h Show this help message
Examples:
generate-agents.sh . # Generate thin root + scoped files
generate-agents.sh . --dry-run # Preview changes
generate-agents.sh . --style=verbose # Use verbose root template
generate-agents.sh . --update # Update existing files
EOF
exit 0
;;
*)
PROJECT_DIR="$1"
shift
;;
esac
done
cd "$PROJECT_DIR"
log() {
[ "$VERBOSE" = true ] && echo "[INFO] $*" >&2
}
error() {
echo "[ERROR] $*" >&2
exit 1
}
# Detect project
log "Detecting project type..."
PROJECT_INFO=$("$SCRIPT_DIR/detect-project.sh" "$PROJECT_DIR")
[ "$VERBOSE" = true ] && echo "$PROJECT_INFO" | jq . >&2
LANGUAGE=$(echo "$PROJECT_INFO" | jq -r '.language')
VERSION=$(echo "$PROJECT_INFO" | jq -r '.version')
PROJECT_TYPE=$(echo "$PROJECT_INFO" | jq -r '.type')
[ "$LANGUAGE" = "unknown" ] && error "Could not detect project language"
# Detect scopes
log "Detecting scopes..."
SCOPES_INFO=$("$SCRIPT_DIR/detect-scopes.sh" "$PROJECT_DIR")
[ "$VERBOSE" = true ] && echo "$SCOPES_INFO" | jq . >&2
# Extract commands
log "Extracting build commands..."
COMMANDS=$("$SCRIPT_DIR/extract-commands.sh" "$PROJECT_DIR")
[ "$VERBOSE" = true ] && echo "$COMMANDS" | jq . >&2
# Generate root AGENTS.md
ROOT_FILE="$PROJECT_DIR/AGENTS.md"
if [ -f "$ROOT_FILE" ] && [ "$FORCE" = false ] && [ "$UPDATE_ONLY" = false ]; then
log "Root AGENTS.md already exists, skipping (use --force to regenerate)"
elif [ "$DRY_RUN" = true ]; then
echo "[DRY-RUN] Would create/update: $ROOT_FILE"
else
log "Generating root AGENTS.md..."
# Select template
if [ "$STYLE" = "verbose" ]; then
TEMPLATE="$TEMPLATE_DIR/root-verbose.md"
else
TEMPLATE="$TEMPLATE_DIR/root-thin.md"
fi
# Prepare template variables
declare -A vars
vars[TIMESTAMP]=$(get_timestamp)
vars[LANGUAGE_CONVENTIONS]=$(get_language_conventions "$LANGUAGE" "$VERSION")
vars[TYPECHECK_CMD]=$(echo "$COMMANDS" | jq -r '.typecheck')
vars[LINT_CMD]=$(echo "$COMMANDS" | jq -r '.lint')
vars[FORMAT_CMD]=$(echo "$COMMANDS" | jq -r '.format' | sed 's/^/ (file scope): /')
vars[TEST_CMD]=$(echo "$COMMANDS" | jq -r '.test')
vars[SCOPE_INDEX]=$(build_scope_index "$SCOPES_INFO")
# Verbose template additional vars
if [ "$STYLE" = "verbose" ]; then
vars[PROJECT_DESCRIPTION]="TODO: Add project description"
vars[VERSION]="$VERSION"
vars[BUILD_TOOL]=$(echo "$PROJECT_INFO" | jq -r '.build_tool')
vars[FRAMEWORK]=$(echo "$PROJECT_INFO" | jq -r '.framework')
vars[PROJECT_TYPE]="$PROJECT_TYPE"
vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
vars[QUALITY_STANDARDS]="TODO: Add quality standards"
vars[SECURITY_SPECIFIC]="TODO: Add security-specific guidelines"
vars[TEST_COVERAGE]="40"
vars[TEST_FAST_CMD]=$(echo "$COMMANDS" | jq -r '.test')
vars[TEST_FULL_CMD]=$(echo "$COMMANDS" | jq -r '.test')
vars[ARCHITECTURE_DOC]="./docs/architecture.md"
vars[API_DOC]="./docs/api.md"
vars[CONTRIBUTING_DOC]="./CONTRIBUTING.md"
fi
# Language-specific conflict resolution
case "$LANGUAGE" in
"go")
vars[LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION]="- For Go-specific patterns, defer to language idioms and standard library conventions"
;;
*)
vars[LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION]=""
;;
esac
# Render template
render_template "$TEMPLATE" "$ROOT_FILE" vars
echo "✅ Created: $ROOT_FILE"
fi
# Generate scoped AGENTS.md files
SCOPE_COUNT=$(echo "$SCOPES_INFO" | jq '.scopes | length')
if [ "$SCOPE_COUNT" -eq 0 ]; then
log "No scopes detected (directories with <$MIN_FILES source files)"
else
log "Generating $SCOPE_COUNT scoped AGENTS.md files..."
while read -r scope; do
SCOPE_PATH=$(echo "$scope" | jq -r '.path')
SCOPE_TYPE=$(echo "$scope" | jq -r '.type')
SCOPE_FILE="$PROJECT_DIR/$SCOPE_PATH/AGENTS.md"
if [ -f "$SCOPE_FILE" ] && [ "$FORCE" = false ] && [ "$UPDATE_ONLY" = false ]; then
log "Scoped AGENTS.md already exists: $SCOPE_PATH, skipping"
continue
fi
if [ "$DRY_RUN" = true ]; then
echo "[DRY-RUN] Would create/update: $SCOPE_FILE"
continue
fi
# Select template based on scope type
SCOPE_TEMPLATE="$TEMPLATE_DIR/scoped/$SCOPE_TYPE.md"
if [ ! -f "$SCOPE_TEMPLATE" ]; then
log "No template for scope type: $SCOPE_TYPE, skipping $SCOPE_PATH"
continue
fi
# Prepare scoped template variables
declare -A scope_vars
scope_vars[TIMESTAMP]=$(get_timestamp)
scope_vars[SCOPE_NAME]=$(basename "$SCOPE_PATH")
scope_vars[SCOPE_DESCRIPTION]=$(get_scope_description "$SCOPE_TYPE")
scope_vars[FILE_PATH]="<file>"
scope_vars[HOUSE_RULES]=""
# Language-specific variables
case "$SCOPE_TYPE" in
"backend-go")
scope_vars[GO_VERSION]="$VERSION"
scope_vars[GO_MINOR_VERSION]=$(echo "$VERSION" | cut -d. -f2)
scope_vars[GO_TOOLS]="golangci-lint, gofmt"
scope_vars[ENV_VARS]="See .env.example"
scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
;;
"backend-php")
scope_vars[PHP_VERSION]="$VERSION"
FRAMEWORK=$(echo "$PROJECT_INFO" | jq -r '.framework')
scope_vars[FRAMEWORK]="$FRAMEWORK"
scope_vars[PHP_EXTENSIONS]="json, mbstring, xml"
scope_vars[ENV_VARS]="See .env.example"
scope_vars[PHPSTAN_LEVEL]="10"
scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
if [ "$FRAMEWORK" = "typo3" ]; then
scope_vars[FRAMEWORK_CONVENTIONS]="- TYPO3-specific: Use dependency injection, follow TYPO3 CGL"
scope_vars[FRAMEWORK_DOCS]="- TYPO3 documentation: https://docs.typo3.org"
else
scope_vars[FRAMEWORK_CONVENTIONS]=""
scope_vars[FRAMEWORK_DOCS]=""
fi
;;
"frontend-typescript")
scope_vars[NODE_VERSION]="$VERSION"
FRAMEWORK=$(echo "$PROJECT_INFO" | jq -r '.framework')
scope_vars[FRAMEWORK]="$FRAMEWORK"
scope_vars[PACKAGE_MANAGER]=$(echo "$PROJECT_INFO" | jq -r '.build_tool')
scope_vars[ENV_VARS]="See .env.example"
scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
scope_vars[DEV_CMD]=$(echo "$COMMANDS" | jq -r '.dev')
scope_vars[CSS_APPROACH]="CSS Modules"
case "$FRAMEWORK" in
"react")
scope_vars[FRAMEWORK_CONVENTIONS]="- Use functional components with hooks\n- Avoid class components"
scope_vars[FRAMEWORK_DOCS]="https://react.dev"
;;
"next.js")
scope_vars[FRAMEWORK_CONVENTIONS]="- Use App Router (app/)\n- Server Components by default"
scope_vars[FRAMEWORK_DOCS]="https://nextjs.org/docs"
;;
"vue")
scope_vars[FRAMEWORK_CONVENTIONS]="- Use Composition API\n- Avoid Options API for new code"
scope_vars[FRAMEWORK_DOCS]="https://vuejs.org/guide"
;;
*)
scope_vars[FRAMEWORK_CONVENTIONS]=""
scope_vars[FRAMEWORK_DOCS]=""
;;
esac
;;
"cli")
scope_vars[LANGUAGE]="$LANGUAGE"
CLI_FRAMEWORK="standard"
[ -f "go.mod" ] && grep -q "github.com/spf13/cobra" go.mod 2>/dev/null && CLI_FRAMEWORK="cobra"
[ -f "go.mod" ] && grep -q "github.com/urfave/cli" go.mod 2>/dev/null && CLI_FRAMEWORK="urfave/cli"
scope_vars[CLI_FRAMEWORK]="$CLI_FRAMEWORK"
scope_vars[BUILD_OUTPUT_PATH]="./bin/"
scope_vars[SETUP_INSTRUCTIONS]="- Build: $(echo "$COMMANDS" | jq -r '.build')"
scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
scope_vars[RUN_CMD]="./bin/$(basename "$PROJECT_DIR")"
scope_vars[TEST_CMD]=$(echo "$COMMANDS" | jq -r '.test')
scope_vars[LINT_CMD]=$(echo "$COMMANDS" | jq -r '.lint')
;;
esac
# Render template
render_template "$SCOPE_TEMPLATE" "$SCOPE_FILE" scope_vars
echo "✅ Created: $SCOPE_FILE"
done < <(echo "$SCOPES_INFO" | jq -c '.scopes[]')
fi
if [ "$DRY_RUN" = true ]; then
echo ""
echo "[DRY-RUN] No files were modified. Remove --dry-run to apply changes."
fi
echo ""
echo "✅ AGENTS.md generation complete!"
[ "$SCOPE_COUNT" -gt 0 ] && echo " Generated: 1 root + $SCOPE_COUNT scoped files"

178
scripts/validate-structure.sh Executable file
View File

@@ -0,0 +1,178 @@
#!/usr/bin/env bash
# Validate AGENTS.md structure compliance
set -euo pipefail
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"
ERRORS=0
WARNINGS=0
error() {
echo "❌ ERROR: $*"
((ERRORS++))
}
warning() {
echo "⚠️ WARNING: $*"
((WARNINGS++))
}
success() {
echo "✅ $*"
}
# Check if file has managed header
check_managed_header() {
local file="$1"
if grep -q "^<!-- Managed by agent:" "$file"; then
success "Managed header present: $file"
return 0
else
warning "Missing managed header: $file"
return 1
fi
}
# Check if root is thin (≤50 lines or has scope index)
check_root_is_thin() {
local file="$1"
local line_count=$(wc -l < "$file")
if [ "$line_count" -le 50 ]; then
success "Root is thin: $line_count lines"
return 0
elif grep -q "## Index of scoped AGENTS.md" "$file"; then
success "Root has scope index (verbose style acceptable)"
return 0
else
error "Root is bloated: $line_count lines and no scope index"
return 1
fi
}
# Check if root has precedence statement
check_precedence_statement() {
local file="$1"
if grep -qi "precedence" "$file" && grep -qi "closest.*AGENTS.md.*wins" "$file"; then
success "Precedence statement present"
return 0
else
error "Missing precedence statement in root"
return 1
fi
}
# Check if scoped file has all 9 sections
check_scoped_sections() {
local file="$1"
local required_sections=(
"## Overview"
"## Setup & environment"
"## Build & tests"
"## Code style & conventions"
"## Security & safety"
"## PR/commit checklist"
"## Good vs. bad examples"
"## When stuck"
)
local missing=()
for section in "${required_sections[@]}"; do
if ! grep -q "^$section" "$file"; then
missing+=("$section")
fi
done
if [ ${#missing[@]} -eq 0 ]; then
success "All required sections present: $file"
return 0
else
error "Missing sections in $file: ${missing[*]}"
return 1
fi
}
# Check if scope index links work
check_scope_links() {
local root_file="$1"
if ! grep -q "## Index of scoped AGENTS.md" "$root_file"; then
return 0 # No index, skip check
fi
# Extract links from scope index
local links=$(sed -n '/## Index of scoped AGENTS.md/,/^##/p' "$root_file" | grep -o '\./[^)]*AGENTS.md' || true)
if [ -z "$links" ]; then
warning "Scope index present but no links found"
return 1
fi
local broken=()
while read -r link; do
# Remove leading ./
local clean_link="${link#./}"
local full_path="$PROJECT_DIR/$clean_link"
if [ ! -f "$full_path" ]; then
broken+=("$link")
fi
done <<< "$links"
if [ ${#broken[@]} -eq 0 ]; then
success "All scope index links work"
return 0
else
error "Broken scope index links: ${broken[*]}"
return 1
fi
}
# Main validation
echo "Validating AGENTS.md structure in: $PROJECT_DIR"
echo ""
# Check root AGENTS.md
ROOT_FILE="$PROJECT_DIR/AGENTS.md"
if [ ! -f "$ROOT_FILE" ]; then
error "Root AGENTS.md not found"
else
echo "=== Root AGENTS.md ==="
check_managed_header "$ROOT_FILE"
check_root_is_thin "$ROOT_FILE"
check_precedence_statement "$ROOT_FILE"
check_scope_links "$ROOT_FILE"
echo ""
fi
# Check scoped AGENTS.md files
SCOPED_FILES=$(find "$PROJECT_DIR" -name "AGENTS.md" -not -path "$ROOT_FILE" 2>/dev/null || true)
if [ -n "$SCOPED_FILES" ]; then
echo "=== Scoped AGENTS.md Files ==="
while read -r file; do
rel_path="${file#$PROJECT_DIR/}"
echo "Checking: $rel_path"
check_managed_header "$file"
check_scoped_sections "$file"
echo ""
done <<< "$SCOPED_FILES"
fi
# Summary
echo "=== Validation Summary ==="
if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
echo "✅ All checks passed!"
exit 0
elif [ $ERRORS -eq 0 ]; then
echo "⚠️ Validation passed with $WARNINGS warning(s)"
exit 0
else
echo "❌ Validation failed with $ERRORS error(s) and $WARNINGS warning(s)"
exit 1
fi

24
templates/root-thin.md Normal file
View File

@@ -0,0 +1,24 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
# AGENTS.md (root)
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.
## 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
- Never commit secrets or sensitive data to the repository
{{LANGUAGE_CONVENTIONS}}
## Minimal pre-commit checks
- Typecheck: {{TYPECHECK_CMD}}
- Lint/format: {{LINT_CMD}}{{FORMAT_CMD}}
- Tests: {{TEST_CMD}}
## Index of scoped AGENTS.md
{{SCOPE_INDEX}}
## When instructions conflict
- The nearest `AGENTS.md` wins. Explicit user prompts override files.
{{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}

63
templates/root-verbose.md Normal file
View File

@@ -0,0 +1,63 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
# AGENTS.md (root)
**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
## Project Overview
{{PROJECT_DESCRIPTION}}
**Tech Stack**: {{LANGUAGE}} {{VERSION}}, {{BUILD_TOOL}}, {{FRAMEWORK}}
**Type**: {{PROJECT_TYPE}}
## 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
{{LANGUAGE_CONVENTIONS}}
## Development Workflow
1. Create feature branch: `git checkout -b feature/description`
2. Make changes with tests
3. Run pre-commit checks (see below)
4. Commit with conventional format
5. Push and create PR
6. Address review feedback
7. Merge when approved
## Pre-commit Checks
**Always run before committing:**
- Typecheck: {{TYPECHECK_CMD}}
- Lint: {{LINT_CMD}}
- Format: {{FORMAT_CMD}}
- Tests: {{TEST_CMD}}
- Build: {{BUILD_CMD}}
## Code Quality Standards
{{QUALITY_STANDARDS}}
## Security & Safety
- Never commit secrets, credentials, or PII
- Validate all user inputs
- Use parameterized queries for database access
- Keep dependencies updated
{{SECURITY_SPECIFIC}}
## Testing Requirements
- Write tests for new features
- Maintain {{TEST_COVERAGE}}% minimum coverage
- Run fast tests locally: {{TEST_FAST_CMD}}
- Run full suite in CI: {{TEST_FULL_CMD}}
## Index of Scoped AGENTS.md
{{SCOPE_INDEX}}
## When Instructions Conflict
Nearest AGENTS.md wins. User prompts override files.
{{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}
## Documentation
- Architecture: {{ARCHITECTURE_DOC}}
- API docs: {{API_DOC}}
- Contributing: {{CONTRIBUTING_DOC}}

77
templates/scoped/backend-go.md Normal file
View File

@@ -0,0 +1,77 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
# AGENTS.md — {{SCOPE_NAME}}
## Overview
{{SCOPE_DESCRIPTION}}
## Setup & environment
- Install: `go mod download`
- Go version: {{GO_VERSION}}
- Required tools: {{GO_TOOLS}}
- Environment variables: {{ENV_VARS}}
## Build & tests (prefer file-scoped)
- Typecheck a file: `go build -v {{FILE_PATH}}`
- Format a file: `gofmt -w {{FILE_PATH}}`
- Lint a file: `golangci-lint run {{FILE_PATH}}`
- Test a file: `go test -v -race -short {{FILE_PATH}}`
- Build: {{BUILD_CMD}}
## Code style & conventions
- Follow Go 1.{{GO_MINOR_VERSION}} idioms
- Use standard library over external deps when possible
- Errors: wrap with `fmt.Errorf("context: %w", err)`
- Naming: `camelCase` for private, `PascalCase` for exported
- Struct tags: use canonical form (json, yaml, etc.)
- Comments: complete sentences ending with period
- Package docs: first sentence summarizes purpose
## Security & safety
- Validate all inputs from external sources
- Use `context.Context` for cancellation and timeouts
- Avoid goroutine leaks: always ensure termination paths
- Sensitive data: never log or include in errors
- SQL: use parameterized queries only
- File paths: validate and sanitize user-provided paths
## PR/commit checklist
- [ ] Tests pass: `go test -v -race ./...`
- [ ] Lint clean: `golangci-lint run ./...`
- [ ] Formatted: `gofmt -w .`
- [ ] No goroutine leaks
- [ ] Error messages are descriptive
- [ ] Public APIs have godoc comments
## Good vs. bad examples
**Good**: Descriptive error wrapping
```go
if err := db.Query(); err != nil {
return fmt.Errorf("failed to query users table: %w", err)
}
```
**Bad**: Generic error messages
```go
if err := db.Query(); err != nil {
return fmt.Errorf("error: %w", err)
}
```
**Good**: Proper context usage
```go
func (s *Service) FetchData(ctx context.Context, id string) error {
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
return s.client.Get(ctx, id)
}
```
## When stuck
- Check Go documentation: https://pkg.go.dev
- Review existing patterns in this codebase
- Check root AGENTS.md for project-wide conventions
- Run `go doc <package>` for standard library help
## House Rules (optional)
{{HOUSE_RULES}}

85
templates/scoped/backend-php.md Normal file
View File

@@ -0,0 +1,85 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
# AGENTS.md — {{SCOPE_NAME}}
## Overview
{{SCOPE_DESCRIPTION}}
## Setup & environment
- Install: `composer install`
- PHP version: {{PHP_VERSION}}
- Framework: {{FRAMEWORK}}
- Required extensions: {{PHP_EXTENSIONS}}
- Environment variables: {{ENV_VARS}}
## Build & tests (prefer file-scoped)
- Typecheck a file: `vendor/bin/phpstan analyze {{FILE_PATH}} --level={{PHPSTAN_LEVEL}}`
- Format a file: `vendor/bin/php-cs-fixer fix {{FILE_PATH}}`
- Lint a file: `php -l {{FILE_PATH}}`
- Test a file: `vendor/bin/phpunit {{FILE_PATH}}`
- Build: {{BUILD_CMD}}
## Code style & conventions
- Follow PSR-12 coding standard
- Use strict types: `declare(strict_types=1);`
- Type hints: always use for parameters and return types
- Naming: `camelCase` for methods, `PascalCase` for classes
- Visibility: always declare (public, protected, private)
- PHPDoc: required for public APIs, include `@param` and `@return`
{{FRAMEWORK_CONVENTIONS}}
## Security & safety
- Validate and sanitize all user inputs
- Use prepared statements for database queries
- Escape output in templates
- Never use `eval()` or dynamic code execution
- Sensitive data: never log or expose in errors
- CSRF protection: enable for all forms
- XSS protection: escape all user-generated content
## PR/commit checklist
- [ ] Tests pass: `vendor/bin/phpunit`
- [ ] PHPStan Level {{PHPSTAN_LEVEL}} clean: `vendor/bin/phpstan analyze`
- [ ] PSR-12 compliant: `vendor/bin/php-cs-fixer fix --dry-run`
- [ ] No deprecated functions used
- [ ] Public methods have PHPDoc
- [ ] Security: inputs validated, outputs escaped
## Good vs. bad examples
**Good**: Proper type hints and strict types
```php
declare(strict_types=1);
public function calculateTotal(int $quantity, float $price): float
{
return $quantity * $price;
}
```
**Bad**: Missing type hints
```php
public function calculateTotal($quantity, $price)
{
return $quantity * $price;
}
```
**Good**: Prepared statements
```php
$stmt = $db->prepare('SELECT * FROM users WHERE id = :id');
$stmt->execute(['id' => $userId]);
```
**Bad**: String concatenation
```php
$result = $db->query("SELECT * FROM users WHERE id = " . $userId);
```
## When stuck
- Check PHP documentation: https://www.php.net
- {{FRAMEWORK_DOCS}}
- Review existing patterns in this codebase
- Check root AGENTS.md for project-wide conventions
## House Rules (optional)
{{HOUSE_RULES}}

84
templates/scoped/cli.md Normal file
View File

@@ -0,0 +1,84 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
# AGENTS.md — {{SCOPE_NAME}}
## Overview
{{SCOPE_DESCRIPTION}}
Command-line interface tools and entry points.
## Setup & environment
{{SETUP_INSTRUCTIONS}}
- CLI framework: {{CLI_FRAMEWORK}}
- Build output: {{BUILD_OUTPUT_PATH}}
## Build & tests (prefer file-scoped)
- Build CLI: {{BUILD_CMD}}
- Run CLI: {{RUN_CMD}}
- Test: {{TEST_CMD}}
- Lint: {{LINT_CMD}}
## Code style & conventions
- Use flag parsing library consistently ({{CLI_FRAMEWORK}})
- Provide `--help` for all commands and subcommands
- Use `--version` to display version information
- Exit codes: 0 = success, 1 = general error, 2 = usage error
- Output: structured (JSON) for scripts, human-readable for interactive
- Errors: write to stderr, not stdout
- Progress: show for long-running operations
- Interactive prompts: support non-interactive mode with flags
## Security & safety
- Validate all file paths and prevent directory traversal
- Never execute user-provided code without explicit confirmation
- Sensitive data: never log or display in plain text
- Config files: validate schema and permissions
- Network operations: timeout and retry with backoff
## PR/commit checklist
- [ ] `--help` text is clear and accurate
- [ ] `--version` displays correct version
- [ ] Exit codes are correct
- [ ] Errors go to stderr
- [ ] Long operations show progress
- [ ] Works in non-interactive mode
- [ ] Tests cover main workflows
## Good vs. bad examples
**Good**: Proper error handling
```{{LANGUAGE}}
if err := runCommand(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
```
**Bad**: Errors to stdout
```{{LANGUAGE}}
if err := runCommand(); err != nil {
fmt.Println("Error:", err)
}
```
**Good**: Clear help text
```
Usage: myapp <command> [options]
Commands:
init Initialize a new project
build Build the project
deploy Deploy to production
Options:
--config string Config file path (default: config.yaml)
--verbose Enable verbose output
```
## When stuck
- Review {{CLI_FRAMEWORK}} documentation
- Check existing commands for patterns
- Test with `--help` to ensure clarity
- Check root AGENTS.md for project conventions
## House Rules (optional)
{{HOUSE_RULES}}

96
templates/scoped/frontend-typescript.md Normal file
View File

@@ -0,0 +1,96 @@
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
# AGENTS.md — {{SCOPE_NAME}}
## Overview
{{SCOPE_DESCRIPTION}}
## Setup & environment
- Install: `npm install` or `yarn install`
- Node version: {{NODE_VERSION}}
- Framework: {{FRAMEWORK}}
- Package manager: {{PACKAGE_MANAGER}}
- Environment variables: {{ENV_VARS}}
## Build & tests (prefer file-scoped)
- Typecheck a file: `npx tsc --noEmit {{FILE_PATH}}`
- Lint a file: `npx eslint {{FILE_PATH}}`
- Format a file: `npx prettier --write {{FILE_PATH}}`
- Test a file: `npm test {{FILE_PATH}}`
- Build: {{BUILD_CMD}}
- Dev server: {{DEV_CMD}}
## Code style & conventions
- TypeScript strict mode enabled
- Use functional components with hooks (React)
- Naming: `camelCase` for variables/functions, `PascalCase` for components
- File naming: `ComponentName.tsx`, `utilityName.ts`
- Imports: group and sort (external, internal, types)
- CSS: {{CSS_APPROACH}} (CSS Modules, Tailwind, styled-components, etc.)
{{FRAMEWORK_CONVENTIONS}}
## Security & safety
- Sanitize user inputs before rendering
- Use `dangerouslySetInnerHTML` only with sanitized content
- Validate environment variables at build time
- Never expose secrets in client-side code
- Use HTTPS for all API calls
- Implement CSP headers
- WCAG 2.2 AA accessibility compliance
## PR/commit checklist
- [ ] Tests pass: `npm test`
- [ ] TypeScript compiles: `npx tsc --noEmit`
- [ ] Lint clean: `npm run lint`
- [ ] Formatted: `npm run format`
- [ ] Accessibility: keyboard navigation works, ARIA labels present
- [ ] Responsive: tested on mobile, tablet, desktop
- [ ] Performance: no unnecessary re-renders
## Good vs. bad examples
**Good**: Proper TypeScript typing
```typescript
interface User {
id: string;
name: string;
email: string;
}
function UserCard({ user }: { user: User }): JSX.Element {
return <div>{user.name}</div>;
}
```
**Bad**: Using `any`
```typescript
function UserCard({ user }: { user: any }) {
return <div>{user.name}</div>;
}
```
**Good**: Accessible button
```tsx
<button
onClick={handleClick}
aria-label="Close dialog"
type="button"
>
<CloseIcon />
</button>
```
**Bad**: Non-semantic click handler
```tsx
<div onClick={handleClick}>
<CloseIcon />
</div>
```
## When stuck
- Check {{FRAMEWORK}} documentation: {{FRAMEWORK_DOCS}}
- Review TypeScript handbook: https://www.typescriptlang.org/docs/
- Check root AGENTS.md for project-wide conventions
- Review existing components for patterns
## House Rules (optional)
{{HOUSE_RULES}}