commit 8967d326a706b5343258f1b3bda7d230c6470cdb Author: Zhongwei Li Date: Sun Nov 30 08:43:17 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e090f5d --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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": [ + "./" + ] +} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..02d663a --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.bak +.cache/ + +# Test output +test-output/ +*.test.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9f322a4 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ddd0be3 --- /dev/null +++ b/README.md @@ -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. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..8cf975c --- /dev/null +++ b/SKILL.md @@ -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 + + +# 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 + +``` + +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 diff --git a/STATUS.md b/STATUS.md new file mode 100644 index 0000000..85211e0 --- /dev/null +++ b/STATUS.md @@ -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 +``` diff --git a/claudedocs/refactoring-summary.md b/claudedocs/refactoring-summary.md new file mode 100644 index 0000000..1a7ff4a --- /dev/null +++ b/claudedocs/refactoring-summary.md @@ -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: ✓ diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..ec0d7ac --- /dev/null +++ b/composer.json @@ -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" + ] +} \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7e8f513 --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file diff --git a/references/analysis.md b/references/analysis.md new file mode 100644 index 0000000..d1aeee5 --- /dev/null +++ b/references/analysis.md @@ -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: `` +4. **Consistent structure** following the 9-section schema from your prompt + +## File Distribution + +| Project | Root | Scoped Files | Total Lines (root) | +|---------|------|--------------|-------------------| +| t3x-rte_ckeditor_image | ✅ | Classes/, Documentation/, Resources/, Tests/ | 348 | +| coding_agent_cli_toolset | ✅ | scripts/ | 308 | +| ldap-selfservice-password-changer | ✅ | internal/, internal/web/ | 282 | +| ldap-manager | ✅ | cmd/, internal/, internal/web/, scripts/ | 228 | +| raybeam | ✅ | cmd/, internal/ | 209 | +| simple-ldap-go | ✅ | docs/, examples/, testutil/ | 26 ⭐ **Perfect thin root** | + +## Key Findings + +### 1. **simple-ldap-go** is the Best Example ⭐ + +**Root file** (26 lines): +- Minimal global rules +- Clear precedence statement +- Index of scoped files +- No duplication with scoped content + +```markdown +## Global rules +- Keep diffs small; add tests for new code paths +- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites + +## Minimal pre-commit checks +- Typecheck (all packages): `go build -v ./...` +- Lint/format (file scope): `gofmt -w ` +- Unit tests (fast): `go test -v -race -short -timeout=10s ./...` + +## Index of scoped AGENTS.md +- `./examples/AGENTS.md` — Example applications +- `./testutil/AGENTS.md` — Testing utilities +- `./docs/AGENTS.md` — Documentation +``` + +### 2. Scoped Files Follow 9-Section Schema + +**Example: simple-ldap-go/examples/AGENTS.md**: +1. ✅ Overview +2. ✅ Setup & environment +3. ✅ Build & tests (file-scoped) +4. ✅ Code style & conventions +5. ✅ Security & safety +6. ✅ PR/commit checklist +7. ✅ Good vs. bad examples +8. ✅ When stuck +9. ⚠️ House Rules (rarely used, only when overriding) + +### 3. Managed Header Usage + +**Present in** (newer projects): +- simple-ldap-go (all files) +- ldap-selfservice-password-changer (all files) +- raybeam (some files) + +**Missing in** (older projects): +- t3x-rte_ckeditor_image +- coding_agent_cli_toolset + +**Format**: +```html + +``` + +### 4. Precedence Rules - Consistent Pattern + +All root files establish precedence clearly: + +**Pattern 1** (verbose): +> "This file explains repo-wide conventions and where to find scoped rules. **Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only." + +**Pattern 2** (concise): +> "**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults." + +**Pattern 3** (index-focused): +> "## Precedence & Scoped Files +> Nearest AGENTS.md wins. Use this root for defaults only." + +### 5. Docker-First vs Native-First + +**Docker-first projects** (ldap-selfservice-password-changer, ldap-manager): +```markdown +### Setup +**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev) + +# Docker (recommended) +docker compose --profile dev up + +# Native development +pnpm install +``` + +**Native-first projects** (simple-ldap-go, t3x-rte_ckeditor_image): +```markdown +### Setup +**Prerequisites**: Go 1.24, golangci-lint + +# Install +go mod download +``` + +### 6. Language-Specific Patterns + +**Go Projects** (simple-ldap-go, ldap-manager, raybeam): +- Minimal pre-commit: `go build -v ./...`, `gofmt -w`, `go test -short` +- Go version in global rules (1.24, 1.25) +- golangci-lint for comprehensive checks + +**PHP Project** (t3x-rte_ckeditor_image): +- Composer scripts for CI pipeline +- PHPStan + PHP-CS-Fixer + Rector +- Make targets preferred over composer commands + +**Hybrid Projects** (ldap-selfservice-password-changer): +- Separate sections for Go backend vs TypeScript frontend +- Scoped AGENTS.md for `internal/` (Go) and `internal/web/` (TS) +- pnpm for package management (strict version) + +### 7. Quick Start Patterns + +**Best practice** (ldap-selfservice-password-changer): +```markdown +## Quick Navigation +- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services +- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend +``` + +**Alternative** (simple-ldap-go): +```markdown +## Index of scoped AGENTS.md +- `./examples/AGENTS.md` — Example applications and usage patterns +- `./testutil/AGENTS.md` — Testing utilities and container management +``` + +### 8. House Rules Implementation + +**Global defaults** typically include: +- Commits: Conventional Commits, small PRs (~≤300 LOC) +- Type-safety: Strict types when supported +- SOLID, KISS, DRY, YAGNI principles +- SemVer for versioning +- No secrets in VCS +- Structured logging +- WCAG AA for UI projects + +**Scoped overrides** (rare): +- Different test coverage targets per module +- Module-specific commit conventions +- Technology-specific style guides + +### 9. Common Gaps Across Projects + +❌ **Missing .envrc** in most projects (your prompt requires it) +❌ **Missing .editorconfig** in some projects +❌ **Husky + commitlint** not universally adopted +❌ **lint-staged** not implemented in older projects +❌ **CI parity section** often missing (should reference GitHub Actions) + +## Recommendations for Your Skill + +### Essential Features + +1. **Template Selection**: + - Thin root (simple-ldap-go style) ⭐ + - Verbose root (ldap-selfservice-password-changer style) + - Auto-detect based on project size + +2. **Project Type Detection**: + - Go: Look for `go.mod`, detect version from `go.mod` directive + - PHP: Look for `composer.json`, detect TYPO3 from dependencies + - TypeScript: Look for `tsconfig.json`, detect strict mode + - Hybrid: Detect multiple languages, recommend scoped files + +3. **Scoped File Generation**: + - **Required scopes**: backend/, frontend/, internal/ + - **Optional scopes**: cmd/, scripts/, examples/, docs/, testutil/ + - **Auto-create** if directory exists and has ≥5 files + +4. **Content Extraction**: + - **Makefile**: Extract targets with `##` comments → Build & Test Commands + - **package.json scripts**: Extract npm/pnpm commands + - **go.mod**: Extract Go version → Prerequisites + - **composer.json scripts**: Extract PHP quality commands + - **GitHub Actions**: Extract CI checks → PR/commit checklist + +5. **Managed Header**: + - Always add to new files + - Preserve in existing files + - Update timestamp on regeneration + +6. **Precedence Rules**: + - Auto-add "Nearest AGENTS.md wins" statement + - Generate index of scoped files in root + - Link from root to scoped files + +### Skill Structure Recommendation + +``` +agents-skill/ +├── SKILL.md +├── README.md +├── templates/ +│ ├── root-thin.md # simple-ldap-go style (recommended) +│ ├── root-verbose.md # ldap-selfservice style +│ ├── scoped-backend.md # Go/PHP backend +│ ├── scoped-frontend.md # TypeScript/JS frontend +│ ├── scoped-cli.md # CLI tools +│ ├── scoped-docs.md # Documentation +│ ├── scoped-tests.md # Testing utilities +│ └── sections/ # Modular sections +│ ├── header.md # Managed header template +│ ├── precedence.md # Precedence statement +│ ├── setup.md # Setup section +│ ├── build-commands.md # Build & test commands +│ ├── code-style.md # Code style guidelines +│ ├── security.md # Security practices +│ ├── pr-checklist.md # PR/commit checklist +│ ├── examples.md # Good vs bad examples +│ └── when-stuck.md # When stuck guidance +├── scripts/ +│ ├── generate-agents.sh # Main generator +│ ├── detect-project.sh # Auto-detect project type +│ ├── extract-commands.sh # Extract from Makefile/package.json +│ └── validate-structure.sh # Validate generated files +└── references/ + ├── examples/ # Real-world examples + │ ├── go-library.md # simple-ldap-go + │ ├── go-web-app.md # ldap-manager + │ ├── php-typo3.md # t3x-rte_ckeditor_image + │ └── hybrid-app.md # ldap-selfservice-password-changer + └── best-practices.md # AGENTS.md writing guide +``` + +### Key Differentiators + +✅ **Thin root by default** (not verbose like some projects) +✅ **Auto-scope detection** (create scoped files when needed) +✅ **Command extraction** (don't make user write commands manually) +✅ **Managed header** (mark files as agent-maintained) +✅ **Language-agnostic** (works with Go, PHP, TypeScript, Python, etc.) +✅ **Idempotent** (can be re-run without breaking existing structure) + +## Sample Output Comparison + +### Your Prompt's Expected Output + +**Root AGENTS.md** (following simple-ldap-go pattern): +```markdown + + +# AGENTS.md (root) + +**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only. + +## Global rules +- Keep PRs small (~≤300 net LOC) +- Conventional Commits: type(scope): subject +- Ask before: heavy deps, full e2e, repo rewrites +- Never commit secrets or PII + +## Minimal pre-commit checks +- Typecheck: [auto-detected command] +- Lint: [auto-detected command] +- Format: [auto-detected command] +- Tests: [auto-detected command] + +## Index of scoped AGENTS.md +- `./internal/AGENTS.md` — Go backend services +- `./internal/web/AGENTS.md` — TypeScript frontend + +## When instructions conflict +Nearest AGENTS.md wins. User prompts override files. +``` + +**Scoped AGENTS.md** (e.g., internal/AGENTS.md): +```markdown + + +# AGENTS.md — Backend Services + +## Overview +[Auto-generated description of internal/ directory purpose] + +## Setup & environment +[Auto-detected from go.mod, .env.example] + +## Build & tests (prefer file-scoped) +[Auto-extracted from Makefile, go commands] + +## Code style & conventions +[Auto-detected from golangci-lint config, gofmt] + +## Security & safety +[Standard Go security practices + project-specific] + +## PR/commit checklist +[Auto-extracted from GitHub Actions, Makefile] + +## Good vs. bad examples +[Template with placeholders to fill] + +## When stuck +- Check root AGENTS.md for global rules +- Review sibling modules for patterns +``` + diff --git a/references/examples/coding-agent-cli/AGENTS.md b/references/examples/coding-agent-cli/AGENTS.md new file mode 100644 index 0000000..7ffd33e --- /dev/null +++ b/references/examples/coding-agent-cli/AGENTS.md @@ -0,0 +1,308 @@ + + +# 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-` +- [ ] 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 ` +3. Check version flag: ` --version` or ` -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_.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 diff --git a/references/examples/coding-agent-cli/scripts-AGENTS.md b/references/examples/coding-agent-cli/scripts-AGENTS.md new file mode 100644 index 0000000..8223df2 --- /dev/null +++ b/references/examples/coding-agent-cli/scripts-AGENTS.md @@ -0,0 +1,389 @@ + + +# 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 ..." + # Implementation +} + +update_tool() { + echo_info "Updating ..." + # Implementation +} + +uninstall_tool() { + echo_info "Uninstalling ..." + # Implementation +} + +reconcile_tool() { + echo_info "Reconciling ..." + # 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 ? [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