Skip to content

Make the repository easy to use for AI coding agents - #8

Merged
PavlosIsaris merged 3 commits into
mainfrom
agent-friendly-docs
Oct 1, 2026
Merged

PavlosIsaris merged 3 commits into
mainfrom
agent-friendly-docs

Conversation

@PavlosIsaris

Copy link
Copy Markdown
Contributor

Agents

  • AGENTS.md with two parts. Part 1 is for agents that add the shared workflows to another repository: which workflows to call, the current tag, how to read files at the tag, and the rules that cause failures. Part 2 is for agents that change this repository: the layout, 12 design rules, local checks, release and commit conventions.
  • CLAUDE.md imports AGENTS.md, so Claude Code and other agents read the same file.
  • Pointers to AGENTS.md in the README and on the organisation profile.

A fresh Claude Code session (Haiku, headless) answered four questions about the workflows and the design rules correctly from AGENTS.md alone.

Guide

  • New section Adopt in an existing repository: a 9-step procedure and a pitfall table, built from the annotation-management-system migration.
  • The pinning rule now says: workflows by tag, actions by SHA. The org's SHA-pinning policy covers our own actions too.

Security fix

  • verify-npm-hardening accepted any lockfile URL that started with registry.npm. (for example registry.npm.evil.example) and plain http://. It now accepts only https://registry.npmjs.org/. Every known SciFY lockfile already complies.
  • The self-check now expects the action to fail on a look-alike registry host.
  • The action README has one canonical Policy table. The npm-harden skill in scify-agent-tools will link to it.

The tag guard also covers ?ref=vX in fetch commands. Release plan after merge: v0.1.4.

The check accepted any URL that started with registry.npm., so a
tampered lockfile could resolve packages from registry.npm.<attacker
host> and pass. Plain http:// also passed. Every known SciFY lockfile
uses https://registry.npmjs.org/ only.
The security-actions job now points a lockfile entry to
registry.npm.evil.example and expects verify-npm-hardening to fail.
The tag guard also covers ?ref=vX in fetch commands.
- AGENTS.md: part 1 for agents that add the shared workflows to another
  repository, part 2 for agents that change this one; CLAUDE.md imports it
- Guide: 'Adopt in an existing repository' procedure and pitfalls; state
  that workflows are called by tag and actions are pinned by SHA
- verify-npm-hardening README: one canonical policy table
- Pointers to AGENTS.md in the README and the organisation profile
@PavlosIsaris
PavlosIsaris merged commit a27675a into main Oct 1, 2026
28 checks passed
@PavlosIsaris
PavlosIsaris deleted the agent-friendly-docs branch October 1, 2026 06:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant