AGENTS.md

Project

This repository authors and distributes the coding collection of portable Agent Skills. The Skills are semantic guidance usable by any compatible agent environment; this repository does not provide or require a workflow engine.

Truth And Installation

• skills/<public-id>/ is the single authored and installable Skill tree. Edit its instructions, resources, scripts, and provider metadata directly.
• contracts/skills.toml owns public IDs, activation, roles, permissions, and optional semantic dependencies; each ID resolves to its directory under skills/.
• The installed routing references own the scope contract between neighboring Skills (clusters and handoffs in routing.toml) and the session selection rules in routing.md, including direct-match bypass and one-primary-response composition; they define no runtime mode or lifecycle.
• tests/fixtures/selection-probes.toml holds uninstalled paired selection probes for discovery audits; checks validate its identifiers, not model behavior.
• docs/architecture/ contains stable architecture truth.
• Shared boundaries, all new designs/plans and retained evaluations belong to $AGENT_ARCHITECTURE_DIR/docs/; historical commands belong to its archived/agent-skills/commands/ tree. Do not create product-local evolution records.
• Resolve the three source roots and TMPDIR from this repository's mise configuration; retained runtime and temporary artifacts belong under $TMPDIR/skills/, and cross-repository maintenance must not guess checkout layout. Standalone product checks and runtime never require the architecture checkout.
• Use the project environment and supported entrypoints described in README.md#project-environment; mise.toml owns ordinary development context, while the standalone check remains usable without mise or personal global configuration. Re-establish target context when crossing projects and preserve caller-owned run isolation; do not duplicate environment values in this file.
• Global discovery uses an independent installed copy, directly or through host links to that copy. Source edits, Git updates, and checks must not update installed Skills; an explicitly authorized install/update owns that mutation.
• Provider plugin manifests are optional packaging surfaces. Their installed content follows the same source/installation separation and grants no workflow authority.

Instruction Scope

• Harness-global instructions own persistent user preferences and thin compaction/recovery reminders. Do not rely only on a task-loaded Skill to retain those preferences, and do not put task-specific permissions or lifecycle procedures in global instructions.
• Project AGENTS.md owns repository policy. The project's current design, plan, or approval summary records the task's effective objective, delivery endpoint, authorized actions and targets, exclusions, and unresolved decisions; those records document explicit approval rather than grant it.
• Skills own portable workflow and domain methods, including how to maintain and reconcile those project records. Session summaries are recall, not another approval source or a parallel live plan.
• Keep this ownership split when changing guidance here. A Skill edit does not authorize editing harness-global files; update those files only within separately approved scope. Keep superseded task restrictions in history rather than as contradictory current gates.

Skill Composition

• Directly matched Skills do not require the optional skills-routing entry. Its method references may be read independently for a relevant unresolved choice.
• The active coding agent owns request interpretation, Skill selection, sequencing, evidence judgment, optional review, finding adjudication, and the final response.
• Review is conditional on an explicit request, an applicable repository or approved-scope rule, or an evidence-backed risk or uncertainty judgment. A standalone review-change starts from the supplied bounded target and does not synthesize upstream work.
• Review evaluators are read-only. The calling design, planning, or implementing agent adjudicates findings and authorizes accepted repairs; bounded implementation, verification execution, diagnosis, and repair labor may be delegated when the host and applicable policy permit it. Final acceptance and continuation decisions remain with the calling agent.
• Skills preserve user and repository authorization boundaries. They never imply commit, push, publication, deployment, destructive history changes, or external mutation.

Working Rules

• Keep Skills provider-neutral and self-contained under the standard Agent Skills directory shape.
• Keep frontmatter descriptions precise enough for native discovery. For a change to a description, admission boundary, or neighboring handoff, apply skills/skill-authoring/ and update the scope contract before the summaries that restate it.
• Store only real semantic dependencies in semantic_requires; do not add executable workflow contracts, artifact validators, task graph compilers, mutable ledgers, replay logic, provider adapters, or prompt-space lifecycle gates.
• Keep the public inventory in contracts/skills.toml; change IDs only as part of an authorized rename, consolidation, or retirement, updating discovery, the scope contract, probes, and references together, and report installed copies or host global entries that still name the old ID. Maintain portable resource closure within each Skill directory.
• Use an existing installation manager, preferably npx skills, for cross-platform installation and explicit refresh. Preserve unrelated installed Skills, verify ownership before replacing existing paths, and remove retired owned IDs explicitly; never mirror-delete the shared discovery root.
• Use apply_patch for source edits and preserve unrelated working-tree changes.

Validation

Choose checks for the changed surface after a cohesive group of edits:

• Skill instructions, references, or inventory: mise exec -- python3 scripts/check-contracts.py and mise exec -- python3 scripts/check-install-surface.py cover discovery, contracts, and resource closure. Use applicable prose/link checks for changed documentation.
• Executable scripts or validators: run their focused tests and relevant syntax, lint, or type checks. Keep unchanged evidence after a repair unless its inputs or behavior were affected.
• Diagram sources or rendering: regenerate affected projections with their owned renderer and check those outputs; ordinary prose changes do not require diagram generation.
• mise run check is the full product check for relevant broad impact or explicit delivery acceptance. The main agent coordinates it and any standalone check at integration or delivery; workers normally return their relevant local results.

For optional Codex plugin metadata changes, also run the repository-independent plugin validator. No install, version bump, commit, push, publication, or consumer-state mutation is implied by validation.