From 0a3a12aec59d320336df1ea41afe86c903105708 Mon Sep 17 00:00:00 2001 From: Cioc Alexandru Date: Wed, 15 Apr 2026 02:47:08 +0200 Subject: [PATCH] feat: add AI agent governance configs --- .amazonq/rules/governance.md | 53 +++++++++++++++++++++++ .claude/governance.md | 66 +++++++++++++++++++++++++++++ .clinerules | 52 +++++++++++++++++++++++ .continuerules | 50 ++++++++++++++++++++++ .cursor/rules/governance.mdc | 39 +++++++++++++++++ .github/copilot-instructions.md | 40 ++++++++++++++++++ .rules | 59 ++++++++++++++++++++++++++ .windsurf/rules/governance.md | 53 +++++++++++++++++++++++ AGENTS.md | 74 +++++++++++++++++++++++++++++++++ CLAUDE.md | 41 ++++++++++++++++++ GEMINI.md | 37 +++++++++++++++++ 11 files changed, 564 insertions(+) create mode 100644 .amazonq/rules/governance.md create mode 100644 .claude/governance.md create mode 100644 .clinerules create mode 100644 .continuerules create mode 100644 .cursor/rules/governance.mdc create mode 100644 .github/copilot-instructions.md create mode 100644 .rules create mode 100644 .windsurf/rules/governance.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/.amazonq/rules/governance.md b/.amazonq/rules/governance.md new file mode 100644 index 00000000..d4901122 --- /dev/null +++ b/.amazonq/rules/governance.md @@ -0,0 +1,53 @@ + +# Amazon Q Rules — flask + +> Generated from governance.md by crag. Regenerate: `crag compile --target amazonq` + +## About + +(No description) + +**Stack:** python + +**Runtimes detected:** python + +## How Amazon Q Should Behave on This Project + +### Code Generation + +1. **Run governance gates before suggesting commits.** The gates below define the quality bar. +2. **Respect classifications:** MANDATORY (default) blocks on failure; OPTIONAL warns; ADVISORY is informational only. +3. **Respect scopes:** Path-scoped gates run from that directory. Conditional gates skip when their file does not exist. +4. **No secrets.** - No hardcoded secrets — grep for sk_live, AKIA, password= before commit +5. **Minimal diffs.** Prefer editing existing code over creating new files. Do not refactor unrelated areas. + +### Quality Gates + +- `uv run ruff check .` +- `uv run ruff format --check .` +- `uv run mypy .` +- `uv run tox run` +- `python -m build` +- `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +- `uv run --locked --no-default-groups --group dev tox run` +- `uv run --locked --no-default-groups --group dev tox run -e typing` + +### Commit Style + +Follow project commit conventions. + +### Boundaries + +- All file operations must stay within this repository. +- No destructive shell commands (rm -rf above repo root, DROP TABLE without confirmation, force-push to main). +- No new dependencies without an explicit reason. + +## Authoritative Source + +When these instructions seem to conflict with something in the repo, **`.claude/governance.md` is the source of truth**. This file is a compiled view. + +--- + +**Tool:** crag — https://www.npmjs.com/package/@whitehatd/crag + + diff --git a/.claude/governance.md b/.claude/governance.md new file mode 100644 index 00000000..9183cb68 --- /dev/null +++ b/.claude/governance.md @@ -0,0 +1,66 @@ +# Governance — flask +# Inferred by crag analyze — review and adjust as needed + +## Identity +- Project: flask +- Stack: python + +## Gates (run in order, stop on failure) +### Lint +- uv run ruff check . +- uv run ruff format --check . +- uv run mypy . + +### Test +- uv run tox run + +### Build +- python -m build + +### CI (inferred from workflow) +- uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files +- uv run --locked --no-default-groups --group dev tox run +- uv run --locked --no-default-groups --group dev tox run -e typing + +## Advisories (informational, not enforced) +- actionlint # [ADVISORY] + +## Branch Strategy +- Trunk-based development +- Free-form commits +- Commit trailer: Co-Authored-By: Claude + +## Security +- No hardcoded secrets — grep for sk_live, AKIA, password= before commit + +## Autonomy +- Auto-commit after gates pass + +## Architecture +- Type: monolith + +## Key Directories +- `.github/` — CI/CD +- `docs/` — documentation +- `src/` — source +- `tests/` — tests + +## Testing +- Framework: pytest +- Layout: flat +- Naming: test_*.py + +## Code Style +- Indent: 4 spaces +- Line length: 88 + +## Dependencies +- Package manager: uv (uv.lock) + +## Anti-Patterns + +Do not: +- Do not catch bare `Exception` — catch specific exceptions +- Do not use mutable default arguments (e.g., `def f(x=[])`) +- Do not use `import *` — use explicit imports + diff --git a/.clinerules b/.clinerules new file mode 100644 index 00000000..0d6a138f --- /dev/null +++ b/.clinerules @@ -0,0 +1,52 @@ + +# Cline Rules — flask + +Generated from governance.md by crag. Regenerate with: `crag compile --target cline` + +## About this project + +(No description) + +Stack: python +Runtimes: python + +## Mandatory behavior + +1. Read this file at the start of every session. Read `governance.md` for full context. +2. Run all mandatory quality gates before proposing a commit. +3. If a gate fails, attempt an automatic fix (lint/format) with bounded retry (max 2 attempts). If it still fails, escalate to the user. +4. Never modify files outside this repository. +5. Never run destructive system commands (rm -rf /, DROP TABLE, force-push to main, curl|bash). +6. Use conventional commits. + +## Quality gates + +Run these in order, stop on first MANDATORY failure: + +- uv run ruff check . +- uv run ruff format --check . +- uv run mypy . +- uv run tox run +- python -m build +- uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files +- uv run --locked --no-default-groups --group dev tox run +- uv run --locked --no-default-groups --group dev tox run -e typing + +## Security + +- No hardcoded secrets — grep for sk_live, AKIA, password= before commit + +## Workflow + +For every task: +1. Read the governance.md file first +2. Understand which files need to change +3. Make minimal, focused changes +4. Run all mandatory gates +5. Commit with a conventional commit message + +## Tool context + +This project uses **crag** — the governance engine for AI coding agents. https://www.npmjs.com/package/@whitehatd/crag + + diff --git a/.continuerules b/.continuerules new file mode 100644 index 00000000..5bdac702 --- /dev/null +++ b/.continuerules @@ -0,0 +1,50 @@ + +# Continue Rules — flask + +> Generated from governance.md by crag. Regenerate: `crag compile --target continue` + + + +## Project Context + +- **Stack:** python +- **Runtimes:** python +- **Governance source:** `.claude/governance.md` (single source of truth) + +## Coding Rules + +Always follow these when generating or modifying code: + +1. **Run gates before committing.** Every change must pass the mandatory gates below. +2. **Classifications matter:** + - `MANDATORY` — must pass (default) + - `OPTIONAL` — should pass, warn on failure + - `ADVISORY` — informational only +3. **Path-scoped gates** run from their declared directory. +4. **Conditional gates** only run when their referenced file exists. +5. **No secrets.** - No hardcoded secrets — grep for sk_live, AKIA, password= before commit +6. Follow project commit conventions. + +## Quality Gates + + - uv run ruff check . + - uv run ruff format --check . + - uv run mypy . + - uv run tox run + - python -m build + - uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files + - uv run --locked --no-default-groups --group dev tox run + - uv run --locked --no-default-groups --group dev tox run -e typing + +## Boundaries + +- All file operations stay within this repository +- No destructive shell commands +- No new dependencies without justification +- Prefer editing existing files over creating new ones + +## Powered by crag + +This rule file is auto-generated from a single `governance.md` via **crag** (https://www.npmjs.com/package/@whitehatd/crag). To update, edit governance.md and re-run `crag compile --target continue`. + + diff --git a/.cursor/rules/governance.mdc b/.cursor/rules/governance.mdc new file mode 100644 index 00000000..e3814c96 --- /dev/null +++ b/.cursor/rules/governance.mdc @@ -0,0 +1,39 @@ +--- +description: Governance rules for flask — quality gates, security, conventions +globs: + - "**/*.py" +alwaysApply: true +--- + +# Governance — flask + +> Generated from governance.md by crag. Regenerate: `crag compile --target cursor` + +**Stack:** python + +## Quality Gates + +Run these checks in order before committing: +### Lint +- `uv run ruff check .` +- `uv run ruff format --check .` +- `uv run mypy .` + +### Test +- `uv run tox run` + +### Build +- `python -m build` + +### Ci (inferred from workflow) +- `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +- `uv run --locked --no-default-groups --group dev tox run` +- `uv run --locked --no-default-groups --group dev tox run -e typing` +## Security + +- No hardcoded secrets — grep for sk_live, AKIA, password= before commit + +## Conventions + +- Follow project commit conventions +- Runtimes: python diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..a2768954 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,40 @@ + +# Copilot Instructions — flask + +> Generated from governance.md by crag. Regenerate: `crag compile --target copilot` + + + +**Stack:** python + +## Runtimes + +python + +## Quality Gates + +When you propose changes, the following checks must pass before commit: + +- **lint**: `uv run ruff check .` +- **lint**: `uv run ruff format --check .` +- **lint**: `uv run mypy .` +- **test**: `uv run tox run` +- **build**: `python -m build` +- **ci (inferred from workflow)**: `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +- **ci (inferred from workflow)**: `uv run --locked --no-default-groups --group dev tox run` +- **ci (inferred from workflow)**: `uv run --locked --no-default-groups --group dev tox run -e typing` + +## Expectations for AI-Assisted Code + +1. **Run gates before suggesting a commit.** If you cannot run them (no shell access), explicitly remind the human to run them. +2. **Respect classifications.** `MANDATORY` gates must pass. `OPTIONAL` gates should pass but may be overridden with a note. `ADVISORY` gates are informational only. +3. **Respect workspace paths.** When a gate is scoped to a subdirectory, run it from that directory. +4. **No hardcoded secrets.** - No hardcoded secrets — grep for sk_live, AKIA, password= before commit +5. Follow project commit conventions. +6. **Conservative changes.** Do not rewrite unrelated files. Do not add new dependencies without explaining why. + +## Tool Context + +This project uses **crag** (https://www.npmjs.com/package/@whitehatd/crag) as its AI-agent governance layer. The `governance.md` file is the authoritative source. If you have shell access, run `crag check` to verify the infrastructure and `crag diff` to detect drift. + + diff --git a/.rules b/.rules new file mode 100644 index 00000000..06235914 --- /dev/null +++ b/.rules @@ -0,0 +1,59 @@ + +# Zed Assistant Rules — flask + +> Generated from governance.md by crag. Regenerate: `crag compile --target zed` + +## Project Summary + +(No description) + +**Stack:** python + +**Runtimes:** python + +## Rules for Zed AI Assistant + +When suggesting edits or running the inline assistant: + +### 1. Quality Gates + +These must pass before any commit. Run them via Zed's terminal integration: + +- `uv run ruff check .` +- `uv run ruff format --check .` +- `uv run mypy .` +- `uv run tox run` +- `python -m build` +- `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +- `uv run --locked --no-default-groups --group dev tox run` +- `uv run --locked --no-default-groups --group dev tox run -e typing` + +### 2. Classification Semantics + +- **MANDATORY** — stop if this fails +- **OPTIONAL** — warn and continue +- **ADVISORY** — log and continue (informational) + +### 3. Scope Rules + +- `path:dir/` — run the gate from that directory +- `if:file` — skip the gate's section when the file does not exist + +### 4. Behavior Boundaries + +- All file operations must stay within this repository. +- Never run destructive system commands (`rm -rf /`, `DROP TABLE`, `curl|bash`, force-push to main). +- - No hardcoded secrets — grep for sk_live, AKIA, password= before commit +- Follow project commit conventions. + +### 5. Authoritative Source + +When these rules conflict with ad-hoc instructions, **governance.md wins**. It is the single source of truth for this project's policies. + +--- + +**Generated by crag** — https://www.npmjs.com/package/@whitehatd/crag + +To update these rules, edit `.claude/governance.md` and re-run `crag compile --target zed`. + + diff --git a/.windsurf/rules/governance.md b/.windsurf/rules/governance.md new file mode 100644 index 00000000..c6d8136c --- /dev/null +++ b/.windsurf/rules/governance.md @@ -0,0 +1,53 @@ +--- +trigger: always_on +description: Governance rules for flask — compiled from governance.md by crag +--- + +# Windsurf Rules — flask + +Generated from governance.md by crag. Regenerate: `crag compile --target windsurf` + +## Project + +(No description) + +**Stack:** python + +## Runtimes + +python + +## Cascade Behavior + +When Windsurf's Cascade agent operates on this project: + +- **Always read governance.md first.** It is the single source of truth for quality gates and policies. +- **Run all mandatory gates before proposing changes.** Stop on first failure. +- **Respect classifications.** OPTIONAL gates warn but don't block. ADVISORY gates are informational. +- **Respect path scopes.** Gates with a `path:` annotation must run from that directory. +- **No destructive commands.** Never run rm -rf, dd, DROP TABLE, force-push to main, curl|bash, docker system prune. +- - No hardcoded secrets — grep for sk_live, AKIA, password= before commit +- Follow the project commit conventions. + +## Quality Gates (run in order) + +1. `uv run ruff check .` +2. `uv run ruff format --check .` +3. `uv run mypy .` +4. `uv run tox run` +5. `python -m build` +6. `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +7. `uv run --locked --no-default-groups --group dev tox run` +8. `uv run --locked --no-default-groups --group dev tox run -e typing` + +## Rules of Engagement + +1. **Minimal changes.** Don't rewrite files that weren't asked to change. +2. **No new dependencies** without explicit approval. +3. **Prefer editing** existing files over creating new ones. +4. **Always explain** non-obvious changes in commit messages. +5. **Ask before** destructive operations (delete, rename, migrate schema). + +--- + +**Tool:** crag — https://www.npmjs.com/package/@whitehatd/crag diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..090b2ace --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ + +# AGENTS.md + +> Generated from governance.md by crag. Regenerate: `crag compile --target agents-md` + +## Project: flask + + +## Quality Gates + +All changes must pass these checks before commit: + +### Lint +1. `uv run ruff check .` +2. `uv run ruff format --check .` +3. `uv run mypy .` + +### Test +1. `uv run tox run` + +### Build +1. `python -m build` + +### Ci (inferred from workflow) +1. `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +2. `uv run --locked --no-default-groups --group dev tox run` +3. `uv run --locked --no-default-groups --group dev tox run -e typing` + +## Coding Standards + +- Stack: python +- Follow project commit conventions + +## Architecture + +- Type: monolith + +## Key Directories + +- `.github/` — CI/CD +- `docs/` — documentation +- `src/` — source +- `tests/` — tests + +## Testing + +- Framework: pytest +- Layout: flat +- Naming: test_*.py + +## Code Style + +- Indent: 4 spaces +- Line length: 88 + +## Anti-Patterns + +Do not: +- Do not catch bare `Exception` — catch specific exceptions +- Do not use mutable default arguments (e.g., `def f(x=[])`) +- Do not use `import *` — use explicit imports + +## Security + +- No hardcoded secrets — grep for sk_live, AKIA, password= before commit + +## Workflow + +1. Read `governance.md` at the start of every session — it is the single source of truth. +2. Run all mandatory quality gates before committing. +3. If a gate fails, fix the issue and re-run only the failed gate. +4. Use the project commit conventions for all changes. + + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..1a42a0fd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,41 @@ + +# CLAUDE.md — flask + +> Generated from governance.md by crag. Regenerate: `crag compile --target claude` + + + +**Stack:** python +**Runtimes:** python + +## Quality Gates + +Run these in order before committing. Stop on first MANDATORY failure: + +- `uv run ruff check .` +- `uv run ruff format --check .` +- `uv run mypy .` +- `uv run tox run` +- `python -m build` +- `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +- `uv run --locked --no-default-groups --group dev tox run` +- `uv run --locked --no-default-groups --group dev tox run -e typing` + +## Rules + +1. Read `governance.md` at the start of every session — it is the single source of truth. +2. Run all mandatory quality gates before committing. +3. If a gate fails, attempt an automatic fix (lint/format) with bounded retry (max 2 attempts). If it still fails, escalate to the user. +4. Never modify files outside this repository. +5. Never run destructive system commands (`rm -rf /`, `DROP TABLE`, force-push to main). +- Follow project commit conventions + +## Security + +- No hardcoded secrets — grep for sk_live, AKIA, password= before commit + +## Tool Context + +This project uses **crag** (https://www.npmjs.com/package/@whitehatd/crag) as its governance engine. The `governance.md` file is the authoritative source. Run `crag audit` to detect drift and `crag compile --target all` to recompile all targets. + + diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..0c03e29b --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,37 @@ + +# GEMINI.md + +> Generated from governance.md by crag. Regenerate: `crag compile --target gemini` + +## Project Context + +- **Name:** flask +- **Stack:** python +- **Runtimes:** python + +## Rules + +### Quality Gates + +Run these checks in order before committing any changes: + +1. [lint] `uv run ruff check .` +2. [lint] `uv run ruff format --check .` +3. [lint] `uv run mypy .` +4. [test] `uv run tox run` +5. [build] `python -m build` +6. [ci (inferred from workflow)] `uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files` +7. [ci (inferred from workflow)] `uv run --locked --no-default-groups --group dev tox run` +8. [ci (inferred from workflow)] `uv run --locked --no-default-groups --group dev tox run -e typing` + +### Security + +- No hardcoded secrets — grep for sk_live, AKIA, password= before commit + +### Workflow + +- Follow project commit conventions +- Run quality gates before committing +- Review security implications of all changes + +