AGENTS.md git:20261016.b17a98eA

Immutable. This exact content never changes and is served at /api/v1/blob/e060273996b2621f.

# Agent Instructions

This repository contains public Agent Skills.

## Rules

- Follow the Agent Skills specification: https://agentskills.io/specification.
- Follow the Agent Plugins specification for repository-managed portable plugins: https://agent-plugins.org/specification.
- Keep client-native plugin packages that cannot share the portable root contract in separate generated adapter projections, as required by [ADR-0071](docs/adrs/0071-add-target-specific-openai-distribution-profiles.short.md) ([Long, canonical](docs/adrs/0071-add-target-specific-openai-distribution-profiles.long.md) · [Guide](docs/adrs/0071-add-target-specific-openai-distribution-profiles.guide.md)).
- Canonical SSH management sources belong to `stark-ai-de/ssh-manager`. Import only reviewed, revision- and digest-pinned artifacts under `vendor/ssh-manager/runtime`; generated local runtime and MCP membership are target-specific. Run `pnpm run validate:ssh` for the consumer contract.
- Do not commit `adapters/`. Generate OpenAI-native packages into disposable staging and archive them under `dist/openai/` with `pnpm run package:openai-plugin`; `pnpm run sync:openai-plugin` is a refuse-redirect.
- Follow [`docs/listing/openai/stark-ai-developer-first-publication.md`](docs/listing/openai/stark-ai-developer-first-publication.md) for OpenAI portal upload and first-publication observations.
- Bundled `agents/openai.yaml` is canonical skill-local metadata. Copy it unchanged into projections; do not adapter-overlay, rewrite, or generate it.
- Edit bundled skills only under `skills/<category>/<skill>/`. Do not edit `plugins/stark-ai-developer/` by hand, including copies under `plugins/stark-ai-developer/skills/`. After changing a bundled skill or `plugins/stark-ai-developer.source.json`, run `pnpm run sync:agent-plugin`. Confirm with `pnpm run validate:projections` when the portable contract changed.
- Every skill must have `SKILL.md` with valid `name` and `description`.
- Skill folder names must match frontmatter names.
- Do not include secrets, tokens, customer data, private repo paths, or internal hostnames.
- Keep `SKILL.md` files concise and operational.
- Move long examples, rubrics, and templates into `references/` or `assets/`.
- Prefer read-only scripts. Any script that modifies files must be clearly documented.
- Document repo-level decisions in `docs/adrs/`.
- Store every repository ADR as linked `.short.md`, `.long.md`, and `.guide.md` files. Long is canonical; Short is a faithful abstraction; Guide is non-normative.
- Keep one decision per ADR and do not impose numeric word, paragraph, or section limits.
- Keep accepted ADR IDs, filename stems, and decision text stable; change architecture through a reciprocal successor ADR, not an in-place decision rewrite.
- Treat Accepted repository ADRs as binding. If a user requests a conflicting change, name the conflict, warn visibly, and stop the affected implementation until an adaptation or successor decision is accepted.
- Stable public skills with multiple material workflows keep a complete finite inventory. For clear authorized intent, announce the selected route and proceed; show every option for bare, ambiguous, or explicit options requests. An options request alone authorizes no execution. Never infer mutation beyond the user's requested outcome and scope, as required by ADR-0060.
- The [2026-07-31 Architecture Compass setup receipt](skill-evals/architecture-compass/runs/2026-07-31-setup-complete.md) is preserved as historical, non-normative evidence. It is stale for current proof; [ADR-0041](docs/adrs/0041-select-validation-from-changed-contracts-and-owning-boundaries.short.md) ([Long, canonical](docs/adrs/0041-select-validation-from-changed-contracts-and-owning-boundaries.long.md) · [Guide](docs/adrs/0041-select-validation-from-changed-contracts-and-owning-boundaries.guide.md)) records the current AC-ADR-049 adaptation, and accepted local ADRs remain authoritative.
- Follow `docs/specs.md` for spec persistence, ADR linkage, filename examples, and repo-facing documentation update rules.
- Do not copy copyrighted skill text from other repositories. Use them only as inspiration.
- Do not vendor already-published third-party skills into `skills/`; install them project-locally with `npx skills`.
- Do not stage files with `git add` unless the user explicitly asks.
- Do not unstage files or otherwise change Git index state unless the user explicitly asks.
- Follow [ADR-0029](docs/adrs/0029-keep-linked-worktrees-inside-the-repository.short.md) ([Long, canonical](docs/adrs/0029-keep-linked-worktrees-inside-the-repository.long.md) · [Guide](docs/adrs/0029-keep-linked-worktrees-inside-the-repository.guide.md)) for agent worktrees: any agent writing repository state uses one assigned worktree under `<root>/.worktrees/<repo>-worktrees/` as its working directory and write scope; the canonical checkout and sibling worktrees are read-only to that writer by default.
- Worktree enforcement state: repository instructions define the invariant; no shared writable root is configured because granting `<root>/.worktrees/<repo>-worktrees/` to every worker would permit cross-worktree writes. Launch each writing agent in its assigned worktree and enforce that workspace as the only repository write scope where the host supports it. Re-check this state only when host capabilities or repository policy change.
- Select checks from changed contracts, owning boundaries, and explicit requirements. Reuse only exact, current evidence. Run the local `pnpm run validate` aggregate for release intent or when a mandatory repository, ADR, user, or approved risk-plan gate requires it; do not run it merely because work is being finalized. Honor an explicit user exclusion while reporting any resulting evidence gap, as required by [ADR-0041](docs/adrs/0041-select-validation-from-changed-contracts-and-owning-boundaries.short.md) ([Long, canonical](docs/adrs/0041-select-validation-from-changed-contracts-and-owning-boundaries.long.md) · [Guide](docs/adrs/0041-select-validation-from-changed-contracts-and-owning-boundaries.guide.md)).