coding-agent-skills 0.2.8

package/scripts/validate-project-adapters.mjs

@@ -0,0 +1,8 @@
+import { projectAdapterCliResult } from "./lib/project-adapter-installation.mjs";
+
+const outcome = projectAdapterCliResult(process.argv[2]);
+for (const line of outcome.lines) {
+  if (outcome.stream === "stdout") console.log(line);
+  else console.error(line);
+}
+process.exitCode = outcome.exitCode;

package/scripts/verify-evidence-bundle.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { evidenceBundleCliResult } from "./lib/evidence-bundle.mjs";
+
+const args = process.argv.slice(2);
+const bundleFile = args[0];
+const json = args.includes("--json");
+
+try {
+  const result = evidenceBundleCliResult(bundleFile, { json });
+  for (const line of result.lines) {
+    if (result.stream === "stderr") console.error(line);
+    else console.log(line);
+  }
+  process.exit(result.exitCode);
+} catch {
+  console.error("evidence bundle verification failed safely");
+  process.exit(2);
+}

package/skills/build-verify/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: build-verify
+description: Discover and run existing project-native lint, typecheck, test, build, and targeted-test commands as controlled local validation. Use after code changes, when reproducing CI failures, or before handoff; do not use to install dependencies, auto-fix files, deploy, migrate, or validate live runtime state.
+---
+
+# Build Verify
+
+Validate the changed scope with existing project commands and emit an evidence pack. This skill is action-capable only for approved local validation that the repository already defines.
+
+## Purpose And Use
+
+Use after code changes, for bounded CI reproduction, or before handoff. Do not use for dependency setup, auto-repair, deployment, migration, publication, or live-runtime health.
+
+## Inputs
+
+Require repository root and changed or requested scope. Optionally accept required checks, target tests, time budget, known pre-existing failures, and a project adapter.
+
+Do not assume scripts exist, dependencies are installed, a successful build proves tests pass, or a failure was caused by the current change.
+
+## Command Policy
+
+First inspect known manifests. Permit only discovered, non-mutating validation scripts for:
+
+- lint without auto-fix
+- typecheck
+- targeted tests
+- full tests
+- build or compile
+- repository-provided verification checks inspected before use
+
+Do not install, add, update, audit-fix, deploy, migrate, update snapshots, run watch mode, rewrite generated files, auto-fix, or invoke scripts whose behavior is unknown. Treat any script containing a restricted operation as rejected.
+
+The skill may execute only discovered local validation commands. It must record any files those tools change and cannot silently accept generated mutations.
+
+## Procedure
+
+1. Obtain repository identity and working-tree context, using `repo-map` evidence when available.
+2. Inspect package or build manifests and CI configuration to discover applicable commands.
+3. Classify each command as allowed, restricted, unknown, or not applicable.
+4. Run the narrowest relevant check first.
+5. Run required broad checks in the repository's established order.
+6. Record exit status, duration, concise output, and whether a failure is new, pre-existing, or unclassified.
+7. Rerun only checks affected by an approved repair; do not repair outside this skill.
+8. Emit the shared evidence pack.
+
+Use [checklist.md](checklist.md). Consult [failure-modes.md](failure-modes.md), [adapter-interface.md](adapter-interface.md), and [examples.md](examples.md). Format findings with [evidence-template.md](evidence-template.md).
+
+## Evidence, Recovery, And Dependencies
+
+Emit discovered scripts, required and skipped checks, command results, durations, failure classification, changed state, and the final verification matrix. Recover from missing tools, timeouts, flaky checks, or malformed scripts by recording the limitation and using only safer discovered checks; never install or mutate to recover.
+
+Depend on repository identity from `repo-map` or equivalent evidence and the evidence-pack contract. Adapters may define safe aliases, order, selectors, and timeouts but cannot permit restricted behavior. Safe usage runs existing lint, typecheck, test, and build checks; unsafe usage installs dependencies or invokes fix/deploy scripts.
+
+## Approval Boundary
+
+Normal local validation needs no additional approval after command discovery. Installation, file-changing fix modes, snapshot updates, migrations, deployments, network publication, and external-system mutation remain outside this skill even if a project script exposes them.
+
+## Completion
+
+Claim `complete` only when all required applicable checks passed and skipped checks do not weaken the requested conclusion. Report `partial`, `failed`, or `blocked` when dependencies, timeouts, missing scripts, or failures prevent full validation. Never claim a check passed when it was not run.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/build-verify/adapter-interface.md

@@ -0,0 +1,7 @@
+# Project Adapter Interface
+
+Validate adapters against `../../schemas/project-adapter.schema.json` and confirm manifest compatibility before applying them.
+
+An adapter may declare package manager, manifest paths, validation script aliases, safe test selectors, check order, timeouts, generated-output expectations, and checks required for specific scopes.
+
+It must not permit installation, auto-fix, snapshot updates, deployment, migration, privileged APIs, or suppression of failed/skipped checks. Shared safety and completion rules win.

package/skills/build-verify/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build Verify"
+  short_description: "Run project-native validation without installing or deploying"
+  default_prompt: "Discover and run approved local lint, typecheck, test, and build checks, then report evidence without installing dependencies or changing external systems."

package/skills/build-verify/checklist.md

@@ -0,0 +1,12 @@
+# Build Verification Checklist
+
+- [ ] Record repository, intent, changed scope, adapter, and time budget.
+- [ ] Inspect manifests and CI to discover existing validation commands.
+- [ ] Reject scripts with installs, fixes, deploys, migrations, watch mode, or unknown mutation.
+- [ ] Run the narrowest relevant tests first.
+- [ ] Run required lint, typecheck, test, and build checks.
+- [ ] Record command, duration, exit status, and concise failure evidence.
+- [ ] Separate pre-existing, new, and unclassified failures.
+- [ ] Record skipped checks and consequences.
+- [ ] Declare all observed state changes.
+- [ ] Emit an evidence pack without unsupported success claims.

package/skills/build-verify/evidence-template.md

@@ -0,0 +1,11 @@
+# Build Verification Evidence
+
+Include:
+
+- Repository identity and changed scope.
+- Discovered validation scripts and their source manifests.
+- Required, executed, skipped, and rejected checks.
+- Command results, durations, failure summaries, and reruns.
+- Classification of failures as new, pre-existing, or unclassified.
+- Changed-state declaration.
+- Final verification matrix and status.

package/skills/build-verify/examples.md

@@ -0,0 +1,16 @@
+# Examples
+
+## Safe
+
+- "Run the repository's existing typecheck, targeted tests, full tests, and build."
+- "Reproduce the failing CI test using scripts already defined in the project."
+- After inspection confirms them: `npm run lint`, `npm run typecheck`, `npm run test`, or `npm run build`.
+
+## Unsafe
+
+- "Install anything missing and keep trying until it passes."
+- "Run the fix script and update snapshots automatically."
+- "Deploy after the build succeeds."
+- "Run every package script without inspecting it."
+
+Reject unsafe operations and report the blocked verification consequence.

package/skills/build-verify/failure-modes.md

@@ -0,0 +1,14 @@
+# Failure Modes
+
+| Failure | Recovery |
+|---|---|
+| Script is absent | Record skipped check; do not invent an equivalent |
+| Dependency or executable missing | Report `blocked`; do not install |
+| Validation times out | Capture partial evidence and narrow only when justified |
+| Test is flaky | Rerun a bounded number of times and label instability |
+| Failure predates current changes | Preserve evidence and avoid claiming current work caused it |
+| Command mutates files | Stop, report the mutation, and downgrade status |
+| Script behavior is unclear | Inspect its definition; reject if still uncertain |
+| Broad check fails after targeted pass | Report failure; targeted success is not overall success |
+
+Recovery remains within discovered validation commands. Repairs are outside this skill.

package/skills/git-preflight/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: git-preflight
+description: Inspect Git repository and handoff readiness without changing Git state. Use before commits, reviews, handoffs, or publication to report branch, HEAD, staged, unstaged, untracked, file-scope, diff-stat, and whitespace evidence; never add, commit, push, pull, merge, rebase, reset, restore, clean, checkout, switch, or stash.
+---
+
+# Git Preflight
+
+Produce an evidence-backed description of Git state. Remain audit-only.
+
+## Purpose And Use
+
+Use before review, commit preparation, handoff, or publication decisions. Do not use to stage, repair, synchronize, rewrite, commit, or publish Git state.
+
+## Inputs
+
+Require repository path and handoff intent. Optionally accept expected branch, base branch, expected files, generated-file rules, and a project adapter.
+
+Do not assume the current directory is the root, a dirty tree belongs to the current task, staged changes are complete, or the current branch is safe to publish.
+
+## Command Policy
+
+Permit read-only Git inspection such as:
+
+- `git rev-parse`
+- `git remote -v`
+- `git branch --show-current`
+- bounded `git log`
+- `git status --short --branch`
+- `git diff --check`
+- `git diff --stat`
+- `git diff --name-only`
+- corresponding cached/staged diff inspection
+
+Do not add, commit, push, pull, fetch with side effects, merge, rebase, reset, restore, clean, checkout, switch, stash, tag, update-index, or alter configuration.
+
+This is audit-only behavior. Inspect full shell structure and reject wrappers or chains that conceal mutation.
+
+## Procedure
+
+1. Confirm the repository root and worktree.
+2. Record branch, HEAD, remote identity, and detached-head state.
+3. Inventory staged, unstaged, untracked, conflicted, and ignored-sensitive conditions.
+4. Inspect file names and diff statistics without exposing secret contents.
+5. Run whitespace/error checks.
+6. Compare observed files with declared task scope and identify unrelated changes.
+7. Report readiness; do not perform the handoff action.
+8. Emit the shared evidence pack.
+
+Use [checklist.md](checklist.md), [failure-modes.md](failure-modes.md), [adapter-interface.md](adapter-interface.md), [examples.md](examples.md), and [evidence-template.md](evidence-template.md).
+
+## Evidence, Recovery, And Dependencies
+
+Emit Git root, worktree, remote, branch, HEAD, staged/unstaged/untracked/conflicted state, diff summaries, whitespace result, scope mismatch, and readiness. Recover from detached HEAD, locks, conflicts, or nested worktrees only by reporting and narrowing inspection; never repair them.
+
+Depend on repository identity from `repo-map` or equivalent evidence and the evidence-pack contract. Adapters may add protected-branch and generated-file rules but cannot hide dirty state. Safe usage reports handoff readiness; unsafe usage stages, restores, rebases, commits, or pushes.
+
+## Approval Boundary
+
+No approval can turn this audit skill into a Git mutation workflow. Direct the user to a separately approved handoff skill for changes to Git state.
+
+## Completion
+
+Claim `complete` when repository identity and relevant Git state are fully described, scope mismatches are reported, and no mutation occurred. A repository conflict, unreadable index, ambiguous worktree, or missing required evidence yields `partial`, `failed`, or `blocked`.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/git-preflight/adapter-interface.md

@@ -0,0 +1,7 @@
+# Project Adapter Interface
+
+Validate adapters against `../../schemas/project-adapter.schema.json` and confirm manifest compatibility before applying them.
+
+An adapter may declare expected base and protected branches, generated-file patterns, required clean paths, allowed task-scope patterns, and repository-specific handoff checks.
+
+It cannot add Git mutation, hide dirty files or conflicts, suppress whitespace failures, or redefine readiness. Shared policy wins.

package/skills/git-preflight/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Git Preflight"
+  short_description: "Inspect Git handoff readiness without changing Git state"
+  default_prompt: "Inspect branch, HEAD, staged, unstaged, untracked, and whitespace state without modifying Git history or the working tree."

package/skills/git-preflight/checklist.md

@@ -0,0 +1,11 @@
+# Git Preflight Checklist
+
+- [ ] Confirm Git root and worktree.
+- [ ] Record remote, branch, HEAD, and detached state.
+- [ ] Record staged, unstaged, untracked, and conflicted files.
+- [ ] Inspect diff names and statistics.
+- [ ] Run `git diff --check`.
+- [ ] Compare files with declared task scope.
+- [ ] Flag unrelated, generated, secret-like, or unexpectedly staged files.
+- [ ] Confirm no Git state changed.
+- [ ] Emit handoff readiness evidence.

package/skills/git-preflight/evidence-template.md

@@ -0,0 +1,10 @@
+# Git Preflight Evidence
+
+Include:
+
+- Git root, remote, branch, HEAD, and worktree identity.
+- Staged, unstaged, untracked, conflicted, and ignored-risk summaries.
+- Diff names, statistics, and whitespace-check result.
+- Declared-scope comparison and unrelated changes.
+- Mutation declaration.
+- Handoff readiness: ready, partial, failed, or blocked.

package/skills/git-preflight/examples.md

@@ -0,0 +1,18 @@
+# Examples
+
+## Safe
+
+- "Tell me whether this working tree is ready for handoff."
+- `git status --short --branch`
+- `git diff --check`
+- `git diff --stat`
+- `git diff --cached --name-only`
+
+## Unsafe
+
+- "Stage the right files for me."
+- "Clean unrelated changes."
+- "Rebase onto main, commit, and push."
+- "Restore anything that does not belong."
+
+This skill reports those needs but performs none of them.

package/skills/git-preflight/failure-modes.md

@@ -0,0 +1,13 @@
+# Failure Modes
+
+| Failure | Recovery |
+|---|---|
+| Not a Git repository | Report `blocked` or defer to `repo-map` |
+| Detached HEAD | Report exact state and avoid publication readiness |
+| Conflicts present | Report `failed` for handoff readiness |
+| Index unreadable or locked | Record error; do not remove lock files |
+| Nested worktree ambiguity | Identify candidates and stop before choosing silently |
+| Secret-like filename appears | Report filename risk without reading content |
+| Unrelated changes cannot be attributed | Mark handoff `partial` |
+
+Never repair Git state within this skill.

package/skills/llm-drift-control/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: llm-drift-control
+description: Reconcile project claims and inherited context against authoritative documentation, source code, tests, Git evidence, and runtime evidence. Use for phase claims, long-running tasks, stale handoffs, contradictory docs, or completion reviews; classify claims without rewriting code or documentation and never treat prompts as proof.
+---
+
+# LLM Drift Control
+
+Build a claim-to-evidence matrix and classify project truth. Remain audit-only.
+
+## Purpose And Use
+
+Use for inherited context, phase claims, stale handoffs, contradictory documentation, or completion reviews. Do not use to rewrite documentation or code, repair discrepancies, or substitute prompt text for evidence.
+
+## Inputs
+
+Require the claims or context to verify and repository scope. Optionally accept declared source precedence, relevant phase, expected branch, runtime evidence, and project adapter.
+
+Do not assume user prose, assistant summaries, README text, generated documentation, passing tests, or deployed behavior is independently authoritative.
+
+## Classification
+
+Classify every material claim as:
+
+- `confirmed`
+- `partial`
+- `stale`
+- `contradicted`
+- `unverifiable`
+
+Attach sources and confidence to every classification.
+
+## Command Policy
+
+Permit bounded documentation and source reads, `rg` searches, read-only Git inspection, existing test-result inspection, and repository drift scripts only after reading and confirming they are non-mutating.
+
+Do not rewrite docs or code, regenerate documentation, install tools, run deployment or migration commands, load secrets, or modify runtime state.
+
+This is audit-only behavior. Existing drift scripts may run only after inspection proves they are non-mutating.
+
+## Procedure
+
+1. Normalize the claims into atomic statements.
+2. Assign expected source types and adapter-defined precedence.
+3. Gather bounded evidence from documentation, source, tests, Git, and existing runtime evidence.
+4. Record source age, branch, and scope where relevant.
+5. Classify each claim and explain contradictions.
+6. Distinguish absence of evidence from evidence of absence.
+7. Identify corrective work without performing it.
+8. Emit the shared evidence pack and claim matrix.
+
+Use [checklist.md](checklist.md), [failure-modes.md](failure-modes.md), [adapter-interface.md](adapter-interface.md), [examples.md](examples.md), and [evidence-template.md](evidence-template.md).
+
+## Evidence, Recovery, And Dependencies
+
+Emit the atomic claim matrix, classifications, source references, branch/time applicability, contradictions, confidence, unresolved questions, and suggested corrective work. Recover from broad claims, source disagreement, stale evidence, or unknown authority by splitting claims and lowering confidence; never invent a winner.
+
+Depend on `repo-map` evidence and the evidence-pack contract; Git or runtime evidence may be supplied by their audit skills. Adapters may define source precedence and phase markers but cannot declare prompts authoritative. Safe usage validates a phase claim; unsafe usage rewrites sources to make the claim true.
+
+## Approval Boundary
+
+This skill has no mutation path. Any documentation or code correction requires a separate approved workflow.
+
+## Completion
+
+Claim `complete` when every material claim has a classification, evidence trail, confidence reason, and unresolved conflict status. Missing authoritative evidence produces `partial` or `unverifiable`, never invented certainty.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/llm-drift-control/adapter-interface.md

@@ -0,0 +1,7 @@
+# Project Adapter Interface
+
+Validate adapters against `../../schemas/project-adapter.schema.json` and confirm manifest compatibility before applying them.
+
+An adapter may define authoritative-document precedence, phase markers, generated-document relationships, canonical source directories, test-to-capability mappings, and safe drift-check scripts.
+
+It cannot declare prompts authoritative, suppress contradictions, rewrite sources, run mutating scripts, or redefine the five claim classifications.

package/skills/llm-drift-control/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LLM Drift Control"
+  short_description: "Reconcile project claims against repository evidence"
+  default_prompt: "Classify project claims against documentation, source, tests, Git, and runtime evidence without rewriting code or documentation."

package/skills/llm-drift-control/checklist.md

@@ -0,0 +1,11 @@
+# Drift Control Checklist
+
+- [ ] Break context into atomic material claims.
+- [ ] Record repository, branch, scope, and source-precedence policy.
+- [ ] Gather bounded documentation, source, test, Git, and runtime evidence.
+- [ ] Record source path, age, and applicability.
+- [ ] Classify every claim.
+- [ ] Explain contradictions and partial support.
+- [ ] Distinguish absence of evidence from evidence of absence.
+- [ ] Record corrective work without performing it.
+- [ ] Emit the claim matrix and evidence pack.

package/skills/llm-drift-control/evidence-template.md

@@ -0,0 +1,13 @@
+# Drift Control Evidence
+
+Include a claim matrix with:
+
+- Atomic claim.
+- Classification: confirmed, partial, stale, contradicted, or unverifiable.
+- Evidence references and source type.
+- Branch, timestamp, or applicability notes.
+- Confidence and reason.
+- Contradictions and unresolved questions.
+- Suggested corrective work without execution.
+
+Also include the shared changed-state declaration and handoff.

package/skills/llm-drift-control/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Safe
+
+- "Verify whether the claimed phase is actually implemented."
+- "Compare the README, tests, and source before trusting this handoff."
+- "Classify each current-truth statement as confirmed, stale, or unverifiable."
+
+## Unsafe
+
+- "Rewrite the docs so they agree with the prompt."
+- "Assume the phase list is true and fill in missing code."
+- "Deploy the latest branch to see which claim wins."
+
+The skill identifies corrective work but does not perform it.

package/skills/llm-drift-control/failure-modes.md

@@ -0,0 +1,13 @@
+# Failure Modes
+
+| Failure | Recovery |
+|---|---|
+| Claim is too broad | Split it into atomic statements |
+| Sources disagree | Preserve both and classify contradiction |
+| Authoritative source is unknown | Use adapter precedence or report unverifiable |
+| Evidence is from another branch | Mark scope mismatch |
+| Documentation is generated | Trace to its source when available |
+| Tests exist but were not run | Treat them as implementation evidence, not passing evidence |
+| Runtime evidence is stale | Lower confidence and record timestamp |
+
+Never resolve uncertainty by inventing a preferred truth.

package/skills/repo-map/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: repo-map
+description: Audit and map an unfamiliar or ambiguous source repository without modifying project, Git, dependency, runtime, or remote state. Use when Codex must locate the canonical repository, understand structure and tooling, identify entry points, tests, documentation, CI, or migrations, or establish evidence before planning code changes.
+---
+
+# Repository Map
+
+Produce an evidence-backed repository map. Remain audit-only and fail closed when repository identity or command safety is uncertain.
+
+## Purpose And Use
+
+Use this skill to establish canonical repository identity, structure, tooling, entry points, tests, CI, documentation, migrations, and boundaries before implementation. Do not use it for route-level tracing, builds, runtime validation, secret auditing, or any mutation.
+
+## Inputs
+
+Require a starting path and the user intent or subsystem to understand. Optionally accept an expected canonical remote, maximum traversal depth, project adapter identifier, or explicit approval for one normally excluded file.
+
+Do not assume the starting path is the repository root, the README is current, one package manifest describes the whole repository, or a familiar directory is authoritative.
+
+## Safety Boundary
+
+Run only bounded inspection commands:
+
+- `pwd`
+- bounded `ls`
+- `rg --files` with exclusions
+- bounded `find` under the candidate repository
+- `git rev-parse`
+- `git remote -v`
+- `git status --short --branch`
+- bounded reads with `sed` or `head`
+- structured parsers used only to read known manifest files
+
+Do not write files, install packages, deploy, migrate, call privileged APIs, change processes or services, read secret files, scan an unrestricted home directory, or mutate Git. Reject shell chains containing a restricted operation even when another segment is allowed.
+
+Treat `.env`, credential stores, private keys, token files, browser profiles, cloud configuration, and similarly named files as secret-bearing. Do not read them without explicit approval.
+
+This is audit-only behavior. It may collect evidence but must not change the inspected project or external state.
+
+## Procedure
+
+1. Record user intent, starting path, declared scope, and adapter.
+2. Confirm the path exists without searching outside the declared scope.
+3. Locate candidate repository roots with bounded inspection.
+4. Establish identity with Git root, remote, branch, HEAD, and working-tree state when Git exists.
+5. Stop and report ambiguity if multiple candidates remain plausible.
+6. Inventory top-level files and directories with bounded depth and explicit exclusions.
+7. Inspect known manifests and workspace configuration without loading secret values.
+8. Identify application entry points, packages, tests, CI, documentation, migrations, and generated-code boundaries.
+9. Compare documentation claims with visible code structure; label discrepancies rather than resolving them by assumption.
+10. Produce the shared evidence pack before claiming completion.
+
+Use [checklist.md](checklist.md) while executing. Consult [failure-modes.md](failure-modes.md) when a check fails, [adapter-interface.md](adapter-interface.md) when an adapter is present, and [examples.md](examples.md) for safe and unsafe cases. Format results with [evidence-template.md](evidence-template.md).
+
+## Evidence, Recovery, And Dependencies
+
+Emit repository identity, working-tree state, structural map, inspected manifests, boundaries, skipped checks, risks, and unresolved questions through the shared evidence-pack contract. Recover from missing paths, ambiguity, permissions, or malformed manifests only through narrower read-only inspection; never install, alter permissions, or mutate files.
+
+This skill depends only on the evidence-pack contract. Adapters may add safe markers, paths, and evidence requirements but cannot weaken policy. Safe usage maps a named repository before editing; unsafe usage scans an entire home directory or reads secrets.
+
+## Approval Boundary
+
+Explicit approval may permit reading one named normally excluded file when necessary. Approval does not permit writes, installation, Git mutation, runtime mutation, deployment, migration, or privileged API access; those operations are outside this skill.
+
+## Completion
+
+Claim `complete` only when repository identity is established or explicitly non-Git, required structural areas were inspected, every required check is executed or recorded as skipped with consequence, no mutation occurred, uncertainties are reported, and the evidence pack is complete.
+
+Otherwise report `partial`, `failed`, or `blocked`. Never equate command execution with successful mapping.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/repo-map/adapter-interface.md

@@ -0,0 +1,18 @@
+# Project Adapter Interface
+
+Validate adapters against `../../schemas/project-adapter.schema.json` and confirm manifest compatibility before applying them.
+
+An adapter may provide:
+
+- Adapter identifier and version.
+- Repository-root markers.
+- Additional safe manifest filenames.
+- Bounded ignored-path patterns.
+- Documentation precedence.
+- Known application, package, test, CI, migration, and generated-code locations.
+- Safe structured-parser choices.
+- Extra required evidence fields.
+
+An adapter must not add mutation commands, remove restricted categories, permit secret reads, expand traversal beyond scope, suppress failures or dirty-state evidence, or redefine `complete`.
+
+Shared policy always wins. Reject an adapter whose rule cannot be reconciled safely.

package/skills/repo-map/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Repository Map"
+  short_description: "Map an unfamiliar repository without changing it"
+  default_prompt: "Inspect this repository and produce an evidence-backed map without modifying project or runtime state."

package/skills/repo-map/checklist.md

@@ -0,0 +1,15 @@
+# Repository Map Checklist
+
+- [ ] Record user intent, scope, starting path, and adapter.
+- [ ] Confirm the starting path exists.
+- [ ] Locate candidate repository roots within bounded scope.
+- [ ] Establish Git root or record that the project is non-Git.
+- [ ] Record remote, branch, HEAD, and working-tree state when available.
+- [ ] Stop if canonical identity remains ambiguous.
+- [ ] Inventory top-level structure with exclusions.
+- [ ] Inspect package, workspace, language, and build manifests.
+- [ ] Locate application and library entry points.
+- [ ] Locate tests, CI, documentation, migrations, and generated-code boundaries.
+- [ ] Record every skipped check and consequence.
+- [ ] Confirm no intentional state mutation occurred.
+- [ ] Emit a complete evidence pack.

package/skills/repo-map/evidence-template.md

@@ -0,0 +1,29 @@
+# Repository Map Evidence
+
+Use the shared evidence-pack schema and include:
+
+## Identity
+
+- Candidate and canonical roots
+- Git/non-Git status
+- Remote identity
+- Branch and HEAD
+- Working-tree state
+
+## Structure
+
+- Package/workspace model
+- Applications and libraries
+- Entry points
+- Tests and CI
+- Documentation hierarchy
+- Migrations
+- Generated-code boundaries
+
+## Confidence And Safety
+
+Explain confidence, declare whether state changed, and list excluded secret-bearing or out-of-scope locations without exposing content.
+
+## Handoff
+
+State what is mapped, what remains unknown, and which focused analysis should happen next.

package/skills/repo-map/examples.md

@@ -0,0 +1,19 @@
+# Examples
+
+## Safe Requests
+
+- "Map this repository before implementing the authentication change."
+- "Identify the monorepo packages, entry points, tests, and governing documentation."
+- "Confirm whether this directory is the canonical Git repository."
+
+Safe inspection includes bounded file listings, manifest reads, and read-only Git identity and status commands.
+
+## Unsafe Requests
+
+- "Search every directory in my home folder until you find something relevant."
+- "Read every `.env` file so you can understand configuration."
+- "Install missing tools while mapping the repository."
+- "Clean the working tree before reporting its structure."
+- "Restart the service to confirm the entry point."
+
+Decline the unsafe operation or explain that another separately approved workflow is required.

package/skills/repo-map/failure-modes.md

@@ -0,0 +1,16 @@
+# Failure Modes
+
+| Failure | Response |
+|---|---|
+| Starting path does not exist | Report `blocked`; request a valid path |
+| Multiple plausible repositories | Report `partial` or `blocked`; show candidates without choosing silently |
+| Not a Git repository | Continue structural mapping and record `not-git` |
+| Git command fails | Preserve the error summary and continue only where identity remains reliable |
+| Traversal is too large | Reduce depth, add exclusions, and report omitted areas |
+| Manifest is malformed | Record the parse failure; use bounded text inspection if safe |
+| Permission denied | Do not escalate automatically; record the inaccessible area and consequence |
+| Secret-like file encountered | Do not read it; record exclusion unless approval names the file |
+| Adapter conflicts with policy | Ignore the weakening rule and report the conflict |
+| Required evidence missing | Do not claim `complete` |
+
+Recovery must remain read-only. Do not install tools, alter permissions, or mutate the repository to make inspection easier.