dependency-management · diff
git:20260427.a7c1e49 to git:20260628.ca833f9
59 added, 19 removed. Audit A to A.
---
name: dependency-management
plugin: dependency-management
description: >
Python dependency and environment management for multi-service or monorepo python backends.
Use when: (1) adding, upgrading, or removing a Python package, (2) responding to Dependabot
or security vulnerability alerts (GHSA/CVE), (3) creating a new service that needs its
own requirements files, (4) debugging pip install failures or Docker build issues related
to dependencies, (5) reviewing or auditing the dependency tree, (6) running pip-compile.
Enforces the pip-compile locked-file workflow and tiered dependency hierarchy.
allowed-tools: Bash, Read, Write
---
## Dependencies
This skill requires **Python 3.8+** and standard library only. No external packages needed.
**To install this skill's dependencies:**
```bash
pip-compile ./requirements.in
pip install -r ./requirements.txt
```
See `./requirements.txt` for the dependency lockfile (currently empty — standard library only).
---
# Dependency Management
3. **One runtime per service.** Each isolated service owns its own `./requirements.txt` lockfile.
- ## Plugin & Skill Script Architecture (Hub-and-Spoke)
+ ## Script Architecture & Packaging
- 1. **DRY in source - Hub-and-Spoke.** One canonical script file lives at `plugins/<plugin-name>/scripts/`. Skills that need it use a file-level symlink in their own `scripts/` directory pointing back to the root (`ln -s ../../../scripts/foo.py`).
- 2. **File-level symlinks only.** Never symlink entire directories. The Bridge Installer (`plugin_installer.py`) only resolves individual file-level symlinks. Directory-level symlinks are silently dropped by binary packaging tools.
- 3. **Self-contained at install.** The installer (`plugin_installer.py`) resolves all symlinks to physical copies when deploying to `.agents/`. This ensures every skill is independently runnable regardless of the source mono-repo's presence.
- 4. **Windows Compatibility.** The `plugin_installer.py` uses a 3-tier strategy for Windows:
- - **Symlink** (if Developer Mode is on)
- - **Junction** (fallback for directory-level logic, though file-level is preferred)
- - **Full Copy** (ultimate fallback)
- This resolution ensures the Hub-and-Spoke pattern works cross-platform.
- 5. **No Cross-Plugin Script Execution.** A skill should never execute `python ../../other-plugin/scripts/foo.py`. If a cross-plugin capability is needed, use **Agent Skill Delegation**: instruct the Agent to invoke the target skill via the conversation layer. In the mono-repo source, cross-plugin file-level symlinks are acceptable for shared logic that the installer will then resolve.
+ For plugin packaging, DRY script distribution, and Windows symlink/junction compatibility rules, see the authoritative shared plugin packaging guidelines.
## Repository Layout (Example)
```
src/
├── requirements-core.in # Tier 1: shared baseline (fastapi, pydantic…)
├── requirements-core.txt # Lockfile for core
├── services/
│ ├── auth_service/
│ │ ├── requirements.in # Tier 2: inherits core + auth deps
- │ │ └── ./requirements.txt
+ │ │ └── requirements.txt
│ ├── payments_service/
│ │ ├── requirements.in
- │ │ └── ./requirements.txt
+ │ │ └── requirements.txt
│ └── database_service/
│ ├── requirements.in
- │ └── ./requirements.txt
+ │ └── requirements.txt
```
## Tiered Hierarchy
| Tier | Scope | File | Examples |
|------|-------|------|----------|
| **1 – Core** | Shared by >80% of services | `requirements-core.in` | `fastapi`, `pydantic`, `httpx` |
| **2 – Specialized** | Service-specific heavyweights | `<service>/requirements.in` | `stripe`, `redis`, `asyncpg` |
| **3 – Dev tools** | Never in production containers | `requirements-dev.in` | `pytest`, `black`, `ruff` |
Each service `.in` file usually begins with `-r ../../requirements-core.in` to inherit the core dependencies.
## Workflow: Adding or Upgrading a Package
1. **Declare** — Add or update the version constraint in the correct `.in` file.
- If the package is needed by most services → `requirements-core.in`
- If only one service → that service's `.in`
- Security floor pins use `>=` syntax: `cryptography>=46.0.5`
2. **Lock** — Compile the lockfile:
```bash
# Core
pip-compile src/requirements-core.in \
--output-file src/requirements-core.txt
# Individual service (example: auth)
pip-compile src/services/auth_service/requirements.in \
- --output-file src/services/auth_service/./requirements.txt
+ --output-file src/services/auth_service/requirements.txt
```
Because services inherit core via `-r`, recompiling a service also picks up core changes.
3. **Sync** — Install locally to verify:
+ Preferred (if available):
```bash
- pip install -r src/services/<service>/./requirements.txt
+ pip-sync src/services/<service>/requirements.txt
```
+ Fallback:
+ ```bash
+ pip install -r src/services/<service>/requirements.txt
+ ```
+
4. **Verify** — Rebuild the affected Docker/Podman container to confirm stable builds.
5. **Commit** — Stage and commit **both** `.in` and `.txt` files together.
## Workflow: Responding to Dependabot / Security Alerts
1. **Identify the affected package and fixed version** from the advisory (GHSA/CVE).
2. **Determine tier placement:**
- Check if the package is a **direct** dependency (appears in an `.in` file).
- If it only appears in `.txt` files, it's **transitive** — pinned by something upstream.
3. **For direct dependencies:** Bump the version floor in the relevant `.in` file.
```
# SECURITY PATCHES (Mon YYYY)
package-name>=X.Y.Z
```
4. **For transitive dependencies:** Add a version floor pin in the appropriate `.in` file
to force the resolver to pull the patched version, even though it's not a direct dependency.
5. **Recompile all affected lockfiles.** Since services inherit core, a core change means
recompiling every service lockfile. Use this compilation order:
```bash
# 1. Core first
pip-compile src/requirements-core.in \
--output-file src/requirements-core.txt
# 2. Then each service
for svc in auth_service payments_service database_service; do
pip-compile "src/services/${svc}/requirements.in" \
- --output-file "src/services/${svc}/./requirements.txt"
+ --output-file "src/services/${svc}/requirements.txt"
done
```
6. **Verify the patched version appears** in all affected `.txt` files:
```bash
grep -i "package-name" src/requirements-core.txt \
- src/services/*/./requirements.txt
+ src/services/*/requirements.txt
```
7. **If no newer version exists** (e.g., inherent design risk like pickle deserialization),
document the advisory acknowledgement as a comment in the `.in` file and note mitigations.
## Container / Dockerfile Constraints
- - Dockerfiles **only** use `COPY ./requirements.txt` + `RUN pip install -r ./requirements.txt`.
+ - Dockerfiles **only** use `COPY requirements.txt` + `RUN pip install -r requirements.txt`.
- No `RUN pip install <pkg>` commands. No manual installs.
- - Copy `./requirements.txt` **before** source code to preserve Docker layer caching.
+ - Copy `requirements.txt` **before** source code to preserve Docker layer caching.
+ ## Non-Negotiable Execution Rules
+
+ The agent MUST NOT:
+ - Run `pip install <pkg>` directly to resolve dependency issues.
+ - Modify `.txt` lockfiles manually.
+ - Bypass `pip-compile` failures.
+ - Ignore missing tools (e.g., `pip-compile` not installed).
+ - Continue after dependency conflicts without resolution.
+
+ If any of the above occurs:
+ 1. **HALT** execution immediately.
+ 2. Classify using the self-evolution profile.
+ 3. Either:
+ - Fix within allowed directories, OR
+ - Log to `map-debt.md`.
+ 4. Report explicitly to the user.
+
+ Workarounds are considered Tier 0 Friction and must be logged.
+
+
+ ## Self-Evolution Requirements
+
+ When this skill encounters friction, failure, ambiguity, or a workaround:
+ 1. Do not silently bypass the issue.
+ 2. Classify the issue using `references/self-evolution-profile.md`.
+ 3. If fixed within allowed directories, update the relevant skill/reference file.
+ 4. Add an entry to `references/evolution-log.md`.
+ 5. If not fixed, add an entry to `references/map-debt.md` with severity, repeat risk, and recommended fix.
+
+
+ ## When to Record Map Debt
+
+ Log to `map-debt.md` when:
+ - Tooling is missing (e.g. `pip-compile` is absent).
+ - Conflicts require human resolution.
+ - The dependency graph is ambiguous.
+ - Instructions in this plugin are unclear or contradictory.
+
+ Do not silently proceed.
+
+
## Common Pitfalls
- **Forgetting to recompile downstream services** after a core `.in` change.
- **Pinning `==` instead of `>=`** for security floors — use `>=` so `pip-compile` can resolve freely.
- **Adding dev tools to production `.in` files** — keep `pytest`, `ruff`, etc. in `requirements-dev.in`.
- **Committing `.txt` without `.in`** — always commit them as a pair.
+