@synapta/skills 0.1.1 → 0.2.0

package/skills/repo-bootstrap/assets/scoped/oro-project.md

@@ -0,0 +1,170 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{INSTALL_LINE}}
+{{PHP_VERSION_LINE}}
+{{ORO_VERSION_LINE}}
+{{DATABASE_LINE}}
+{{MESSAGE_QUEUE_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Directory structure
+```
+bin/
+  console              → Symfony console entry point
+config/
+  bundles.php          → Registered bundles
+  config.yml           → Main configuration
+  config_dev.yml       → Development overrides
+  config_prod.yml      → Production settings
+  parameters.yml       → Environment parameters
+  security.yml         → Security configuration
+  oro/
+    bundles.yml        → Oro bundle registration
+public/
+  index.php            → Web entry point
+  bundles/             → Bundle assets
+src/
+  Acme/                → Custom bundles
+    Bundle/
+      MyBundle/
+var/
+  cache/               → Cache files
+  logs/                → Log files
+  attachment/          → File attachments
+migrations/
+  Schema/              → Doctrine schema migrations
+  Data/                → Data migrations/fixtures
+```
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{COMMANDS_TABLE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- **PSR-12** coding standard
+- Strict types: `declare(strict_types=1);`
+- Symfony best practices + Oro conventions
+- Bundle-based architecture for all custom code
+- Use Oro's config-based approach (YAML over annotations)
+- Dependency injection via `services.yml`
+
+### Project structure rules
+| Type | Location | Purpose |
+|------|----------|---------|
+| Custom bundles | `src/Vendor/Bundle/` | All custom functionality |
+| Overrides | `config/` | Configuration overrides |
+| Migrations | `migrations/` | Application-level migrations |
+| Assets | `public/bundles/` | Compiled/copied assets |
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START oro-commands -->
+## Oro CLI commands
+```bash
+# Installation & setup
+bin/console oro:install                    # Full installation
+bin/console oro:platform:update           # Update after code changes
+
+# Cache management
+bin/console cache:clear                   # Clear cache
+bin/console oro:assets:install            # Install bundle assets
+bin/console oro:localization:dump         # Dump translations
+
+# Database & migrations
+bin/console doctrine:migrations:migrate   # Run migrations
+bin/console oro:migration:data:load       # Load data migrations
+
+# Message queue (required for Oro)
+bin/console oro:message-queue:consume     # Process queue
+bin/console oro:cron                      # Run cron jobs
+
+# Development
+bin/console debug:router                  # List routes
+bin/console debug:container               # Debug DI container
+```
+<!-- AGENTS-GENERATED:END oro-commands -->
+
+<!-- AGENTS-GENERATED:START message-queue -->
+## Message Queue
+Oro requires a running message queue consumer for:
+- Email sending
+- Search indexing
+- Workflow processing
+- Data import/export
+
+**Development:** Run `bin/console oro:message-queue:consume` in terminal
+**Production:** Use supervisor or systemd to keep consumer running
+<!-- AGENTS-GENERATED:END message-queue -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- **Parameters**: Use `parameters.yml` for sensitive values (not in git)
+- **OAuth2**: Configure for API authentication
+- **ACL**: Define permissions in bundle `acl.yml`
+- **HTTPS**: Enforce in production
+- **Secrets**: Use Symfony secrets for production credentials
+- **Session**: Configure secure session handling
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START deployment -->
+## Deployment
+```bash
+# Production deployment steps
+composer install --no-dev --optimize-autoloader
+bin/console cache:clear --env=prod
+bin/console oro:platform:update --env=prod --force
+bin/console oro:assets:install --env=prod
+bin/console assetic:dump --env=prod
+```
+- Always run `oro:platform:update` after code changes
+- Restart message queue consumer after deployment
+- Warm up cache before switching to new release
+<!-- AGENTS-GENERATED:END deployment -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+{{CACHE_CHECKLIST_LINE}}
+{{PHPSTAN_CHECKLIST_LINE}}
+{{UNIT_TEST_CHECKLIST_LINE}}
+- [ ] Bundle registered in `config/oro/bundles.yml`
+- [ ] Migrations reversible and tested
+- [ ] Assets installed: `bin/console oro:assets:install`
+- [ ] Message queue tested with consumer running
+- [ ] ACL permissions defined for new entities
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Oro Documentation: https://doc.oroinc.com
+- Installation: https://doc.oroinc.com/backend/setup/
+- Backend Architecture: https://doc.oroinc.com/backend/architecture/
+- CLI Commands: `bin/console list oro`
+- Check `vendor/oro/` bundles for reference implementations
+- Review root AGENTS.md for project-wide conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/python-modern.md

@@ -0,0 +1,170 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{PYTHON_VERSION_LINE}}
+{{PACKAGE_MANAGER_LINE}}
+{{VENV_LINE}}
+{{ENV_VARS_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Project configuration
+All tool config lives in `pyproject.toml` -- no `setup.cfg`, `setup.py`, `tox.ini`, or scattered config files.
+
+```toml
+[project]                    # PEP 621 metadata
+[build-system]               # Build backend (hatchling, setuptools, flit, pdm)
+[tool.ruff]                  # Linting + formatting (replaces black, isort, flake8, pylint)
+[tool.ruff.lint]             # Lint rule selection
+[tool.mypy]                  # Static type checking
+[tool.pytest.ini_options]    # Test configuration
+[tool.coverage]              # Coverage settings
+```
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+
+| Command | Purpose | ~Time |
+|---------|---------|-------|
+{{RUFF_CHECK_LINE}}
+{{RUFF_FORMAT_LINE}}
+{{MYPY_LINE}}
+{{PYTEST_LINE}}
+{{PYTEST_COV_LINE}}
+{{BUILD_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+
+### Ruff (linting + formatting)
+- Ruff replaces black, isort, flake8, pylint, pyflakes, pycodestyle in one tool
+- Format: `ruff format .` -- black-compatible, deterministic
+- Lint: `ruff check . --fix` -- auto-fix safe rules
+- Config in `pyproject.toml` under `[tool.ruff]`
+- Common rule sets: `E` (pycodestyle), `F` (pyflakes), `I` (isort), `UP` (pyupgrade), `B` (bugbear)
+
+### Type hints (mypy)
+- All functions must have type annotations (parameters + return)
+- Use `mypy --strict` or configure strictness in `pyproject.toml`
+- Modern syntax: `str | None` not `Optional[str]`, `list[int]` not `List[int]`
+- Use `typing.TypeAlias` for complex types
+- Use `Protocol` for structural subtyping (duck typing with types)
+
+### Naming conventions
+| Type | Convention | Example |
+|------|------------|---------|
+| Module | `snake_case` | `user_service.py` |
+| Class | `PascalCase` | `UserService` |
+| Function | `snake_case` | `get_user_by_id()` |
+| Constant | `UPPER_SNAKE_CASE` | `MAX_RETRIES` |
+| Type variable | `PascalCase` | `T = TypeVar("T")` |
+| Private | `_leading_underscore` | `_internal_helper()` |
+
+### Docstrings
+- Google style preferred (compatible with Sphinx napoleon)
+- Required for all public modules, classes, functions
+- Include `Args:`, `Returns:`, `Raises:` sections
+
+### Imports
+- Ruff handles import sorting (`I` rules) -- no separate isort needed
+- Group: stdlib, third-party, local (Ruff enforces this)
+- Prefer absolute imports; relative only within package internals
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START testing -->
+## Testing (pytest)
+- Test files: `tests/` directory, files named `test_*.py`
+- Test functions: `test_<description>()` -- no class needed for simple tests
+- Fixtures: prefer `conftest.py` for shared fixtures
+- Parametrize: use `@pytest.mark.parametrize` for data-driven tests
+- Markers: `@pytest.mark.slow`, `@pytest.mark.integration` for selective runs
+- Coverage: `pytest --cov=src --cov-report=term-missing`
+- Assert style: plain `assert` (pytest rewrites for detailed output)
+<!-- AGENTS-GENERATED:END testing -->
+
+<!-- AGENTS-GENERATED:START dependency-management -->
+## Dependency management
+
+### uv (recommended)
+```bash
+uv sync                     # Install deps from uv.lock
+uv add <package>            # Add dependency
+uv add --dev <package>      # Add dev dependency
+uv run pytest               # Run in managed venv
+```
+
+### poetry
+```bash
+poetry install              # Install deps from poetry.lock
+poetry add <package>        # Add dependency
+poetry add --group dev <p>  # Add dev dependency
+poetry run pytest           # Run in managed venv
+```
+
+### pip (fallback)
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"     # Install with dev extras
+```
+<!-- AGENTS-GENERATED:END dependency-management -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate and sanitize all user inputs
+- Use parameterized queries for database access (SQLAlchemy, asyncpg)
+- Never use dynamic code evaluation functions with untrusted data
+- Sensitive data: never log or expose in errors
+- File paths: validate and use `pathlib.Path` for all path operations
+- Subprocess: use list args, never `shell=True` with user input
+- Dependencies: pin versions in lockfile, audit with `pip-audit` or `safety`
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] `ruff check .` passes (no lint errors)
+- [ ] `ruff format --check .` passes (formatting clean)
+- [ ] `mypy .` passes (no type errors)
+- [ ] `pytest` passes (all tests green)
+- [ ] New public functions have type hints and docstrings
+- [ ] No `# type: ignore` without explanation comment
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Python docs: https://docs.python.org
+- Ruff rules reference: https://docs.astral.sh/ruff/rules/
+- mypy cheat sheet: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
+- pytest docs: https://docs.pytest.org
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/resources.md

@@ -0,0 +1,96 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Resources are typically consumed by other parts of the application
+- Some resources may need preprocessing or compilation
+- Check build scripts for resource handling
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START types -->
+## Resource types
+- **Templates**: HTML, email, or text templates
+- **Static assets**: Images, fonts, icons, stylesheets
+- **Configuration**: Default configs, schema files, fixtures
+- **Localization**: Translation files, locale data
+- **Data files**: JSON, YAML, CSV for static data
+<!-- AGENTS-GENERATED:END types -->
+
+<!-- AGENTS-GENERATED:START organization -->
+## Organization conventions
+- Group resources by type: `templates/`, `images/`, `locales/`
+- Use consistent naming: lowercase, hyphens for spaces
+- Keep related resources together
+- Version large binary assets carefully (consider Git LFS)
+<!-- AGENTS-GENERATED:END organization -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Use descriptive file names: `user-profile-template.html` not `template1.html`
+- Keep templates simple - logic belongs in code, not templates
+- Use consistent indentation in structured files (JSON, YAML, XML)
+- Document template variables and their expected values
+- Optimize images before committing (compress, resize)
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START templates -->
+## Template best practices
+- Use clear placeholder syntax: `{{variable}}` or `${variable}`
+- Document all required variables in comments or README
+- Keep templates focused - one purpose per template
+- Use partials/includes for reusable components
+<!-- AGENTS-GENERATED:END templates -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Never store secrets in resource files
+- Validate all resource files that accept user input
+- Sanitize template variables to prevent injection
+- Review images/assets for embedded metadata (EXIF, etc.)
+- Use CSP-safe inline styles when applicable
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] File names are descriptive and consistent
+- [ ] Images are optimized (compressed, correct size)
+- [ ] Templates have documented variables
+- [ ] No sensitive data in resources
+- [ ] Structured files are valid (JSON, YAML syntax)
+- [ ] Changes tested with consuming code
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check how resources are consumed in the codebase
+- Look for build/preprocessing scripts
+- Review existing resources for patterns
+- Check root AGENTS.md for project conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/skill-repo.md

@@ -0,0 +1,139 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- **Plugin manifest**: `.claude-plugin/plugin.json` (name, version, skills array, author URL)
+- **Skills**: `skills/<name>/SKILL.md` — one per domain
+- **Licensing**: Split MIT (code) + CC-BY-SA-4.0 (content) — entity: `Netresearch DTT GmbH`
+- **CI**: Reusable workflows from `netresearch/skill-repo-skill` (`validate.yml`, `auto-merge-deps.yml`)
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Directory structure
+```
+.claude-plugin/
+  plugin.json            → Plugin manifest (name, version, skills, author)
+skills/
+  <skill-name>/
+    SKILL.md             → Skill definition (max 500 words)
+    assets/              → Templates, scoped AGENTS.md templates
+    scripts/             → Shell scripts (bash 4.3+, ShellCheck clean)
+    references/          → Extended docs, golden samples, examples
+    checkpoints/         → Checkpoint definitions (YAML)
+LICENSE-MIT              → MIT license for code
+LICENSE-CC-BY-SA-4.0     → CC-BY-SA-4.0 for content
+.github/
+  workflows/
+    lint.yml             → Calls skill-repo-skill validate.yml@main
+    auto-merge-deps.yml  → Calls skill-repo-skill auto-merge-deps.yml@main
+```
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{LINT_LINE}}
+{{VALIDATE_LINE}}
+{{SHELLCHECK_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+
+### SKILL.md rules
+- Max **500 words** — keep it focused and actionable
+- Use `references/` for extended documentation (no word limit)
+- Front matter: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
+- Instructions are FOR AGENTS, not humans — be prescriptive, not descriptive
+
+### plugin.json rules
+- `version`: semver, bump on release
+- `author.url`: must be a valid URL
+- `skills[].name` must match directory name under `skills/`
+
+### Shell scripts
+- Shebang: `#!/usr/bin/env bash`
+- `set -euo pipefail` at top
+- ShellCheck clean (no suppressions without justification)
+- Use `"$var"` quoting everywhere
+
+### Templates
+- Use `{{PLACEHOLDER}}` syntax — whole-line placeholders only
+- Wrap auto-generated sections in `<!-- AGENTS-GENERATED:START name -->` / `<!-- AGENTS-GENERATED:END name -->`
+
+### Licensing
+- Entity name: **Netresearch DTT GmbH** (never "Netresearch GmbH & Co. KG")
+- Code files (`.sh`, `.py`, `.json`): MIT
+- Content files (`.md`, `.yaml`): CC-BY-SA-4.0
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START checkpoints -->
+## Checkpoints (verification)
+- `checkpoints.yaml` defines verifiable steps agents can run
+- Each checkpoint: `name`, `command`, `expected` (exit code or output pattern)
+- Agents run checkpoints after completing tasks to verify correctness
+- Keep checkpoints fast (<10s each)
+<!-- AGENTS-GENERATED:END checkpoints -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Never include secrets or credentials in skills
+- Validate all user inputs in scripts
+- Use placeholder values in examples: `your-api-key`, `example.com`
+- Review generated content for sensitive information
+- Shell scripts: quote all variables, avoid `eval` with user input
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START ci -->
+## CI/CD
+- **Validate workflow**: Runs on PR — markdown lint, YAML lint, ShellCheck, plugin.json schema
+- **Auto-merge deps**: Merges Renovate/Dependabot PRs after CI passes
+- Config files (`.markdownlint-cli2.jsonc`, `.yamllint.yml`) are per-repo; validate.yml provides defaults if missing
+- **Releasing**: bump `plugin.json` version, create signed tag, push — release workflow handles the rest
+<!-- AGENTS-GENERATED:END ci -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] SKILL.md is under 500 words
+- [ ] `plugin.json` version bumped if releasing
+- [ ] Shell scripts pass ShellCheck
+- [ ] Templates use whole-line `{{PLACEHOLDER}}` syntax
+- [ ] Golden samples exist for key patterns
+- [ ] Checkpoints are verifiable (fast, deterministic)
+- [ ] Entity name is "Netresearch DTT GmbH" in all license files
+- [ ] No trailing blank lines in YAML files
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check existing skill repos for patterns (e.g., `agent-rules-skill`, `go-development-skill`)
+- Review `skill-repo-skill` for CI workflow definitions
+- Test skills locally with `claude --skill <name>`
+- Check root AGENTS.md for project conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}