AGENTS.md
# agents — norsain-ai/.github

This file provides instructions for coding agents working in NORSAIN’s organization-level `.github` repository. This repository contains shared GitHub standards and automations consumed by downstream private repositories.

## scope

This repository is limited to:

- reusable workflows and templates under `.github/workflows/`
- repository templates and governance UX under `.github/` (PR templates, issue forms, CODEOWNERS, contributing docs)
- documentation that explains how downstream repositories should consume the above

Do not generate application or product code that belongs in downstream repositories.

## working agreement

### baseline behavior

- keep changes small and low-risk by default (prefer a single purpose PR; target ≤ 5 files)
- treat reusable workflows as shared contracts: avoid breaking changes; when unavoidable, include a migration note and versioning guidance
- never introduce or request secrets/tokens in repo content
- prefer explicitness and determinism over “magic” automation

### planning gate (required)

Before implementation work begins, verify there is an **accepted todo** artifact for the change.

- if an accepted todo exists: proceed
- if not: create a planning artifact (inbox/backlog/plans) and propose a todo for human acceptance; do not implement until it is accepted

If the repository does not yet contain the planning workspace structure, propose the minimal structure and stop.

## security baseline for workflows

When changing workflows, enforce:

- **least privilege for `GITHUB_TOKEN`**: set minimal `permissions:` (read by default; elevate per job only when required)
- avoid executing untrusted PR code with elevated permissions or secret access
- **do not use `pull_request_target`** unless explicitly requested and mitigations are documented
- prefer pinned and reputable actions; avoid adding new third-party actions for privileged jobs without justification
- failures must be clear and actionable (what is missing and how to fix it)

## change workflow

### proposal-first

For any non-trivial change, produce a short plan before editing:

- what will change
- why it is needed
- risks and mitigations
- verification approach

### implementation rules

- prefer minimal diffs and stable naming
- keep required checks names stable (avoid breaking enforcement in downstream repos)
- avoid file moves/renames unless there is clear shared benefit and a migration note
- keep documentation in sync with templates/workflows when behavior changes

## verification

At minimum, ensure:

- YAML is valid and workflow syntax is correct
- permissions are minimal and justified
- templates render correctly (PR template + issue forms)
- changes can be validated via a safe PR flow (test branch or limited-scope change)

If the repository defines lint/validation scripts or workflows, run/trigger them and report results.

## output contract

When you respond with a proposed change, include:

1. summary (2–6 sentences): what + why
2. risk notes: what could break and mitigations
3. unified diff (per file)
4. verification plan: how maintainers should validate safely

## precedence and related files

- repository-wide chat guidance: `.github/copilot-instructions.md`
- path-scoped guidance: `.github/instructions/**/*.instructions.md`
- custom agents (VS Code): `.github/agents/*.agent.md`

If instructions conflict, follow the stricter rule and call out the conflict explicitly.