mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-06 23:32:12 +03:00

Files

Diego Rodrigues de Sa e Souza 1efb94b102 docs: centralize agent instructions in AGENTS.md (CLAUDE/GEMINI point to it) (#9508 )

* docs: centralize agent instructions in AGENTS.md; CLAUDE/GEMINI point to it

- AGENTS.md becomes the single source of truth: full CLAUDE.md content (main
  data) merged with the AGENTS.md-only sections (documentation accuracy,
  repository map, review focus, upstream contributions) and the GEMINI.md-only
  file-placement/root-hygiene and local-access rules. Adds the base-green
  check section (PRs must not be born red) and fixes the stale
  _tasks/release-flow path in Hard Rule 21.
- CLAUDE.md: @AGENTS.md pointer + Claude-Code-only operational deltas
  (EnterWorktree, subagent stash-ban replication, superpowers path overrides,
  base-green/sweep-reds pointers).
- GEMINI.md: pointer + Gemini-only notes; the stale 10-item hard-rule mirror
  is removed (source is the 22-rule list in AGENTS.md).
- ci(release-green): label the not-green tracking issue with base-red.

* docs: retarget docs-sync provider/MCP claims to AGENTS.md and fix test placeholder

---------

Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>

2026-08-05 19:20:16 -03:00

3.3 KiB

Raw Blame History

CLAUDE.md

@AGENTS.md

All project rules live in AGENTS.md — the single source of truth for every AI assistant (architecture, conventions, testing, quality gates, git workflow, the 22 Hard Rules, PII learnings). Read it in full; do not re-add project rules here. Everything below applies ONLY to Claude Code — operational refinements of rules already defined in AGENTS.md.

Worktree isolation — Claude Code specifics

The full mandatory worktree protocol (base-branch confirmation, .claude/worktrees/ canonical path, cp -al node_modules, teardown rules) is in AGENTS.md → Git Workflow → "Worktree isolation". Claude-Code-specific points:

Confirm the base branch with the operator via AskUserQuestion (Hard Rule #19) unless they already told you.
Prefer the native EnterWorktree tool — it already creates worktrees under .claude/worktrees/ (the canonical path). Create the worktree with the documented git worktree add command, then call EnterWorktree with its path.

Cross-session safety — Claude Code specifics

Hard Rules #19/#21/#22 (in AGENTS.md) govern parallel sessions. Operational reminders for this harness:

Replicate the git stash ban verbatim in the prompt of every subagent that touches git (Agent tool / Workflow scripts) — subagents do not inherit this file, and the recorded recurrence of the stash incident came through a subagent.
Before merging or pushing to any PR you did not create this session, run git worktree list and re-check gh pr view <N> --json state,headRefOid (Hard Rule #22b).
End every session with the main checkout on the branch it started on.

Superpowers / planning artifacts — path overrides

The _tasks/ convention is defined in AGENTS.md → "Planning & Research Artifacts". The superpowers skills ship with defaults that point at docs/… — those defaults are overridden here. When a superpowers skill announces a path like "saved to docs/superpowers/plans/…", rewrite it to the _tasks/… equivalent before writing:

Artifact (skill)	Default (do NOT use)	Save here instead
Plans (`writing-plans`)	`docs/superpowers/plans/`	`_tasks/superpowers/plans/YYYY-MM-DD-<feature>.md`
Specs / design (`brainstorming`)	`docs/superpowers/specs/`	`_tasks/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
Research (`deep-research`, ad-hoc)	`docs/research/`	`_tasks/research/…`
Hand-offs (`/handoff`)	—	`_tasks/hands-off/<YYYY-MM-DD>_<branch>_v<versão>_sess-<id>/`

Commit those artifacts inside the _tasks/ repo (git -C _tasks …), never in the main repo.

Base-green before opening PRs

Before cutting a branch or opening a PR, run the base-green check (AGENTS.md → Git Workflow → "Base-green check"; project skills reference it as .agents/skills/_shared/base-green.md). A PR opened while the base tip is red must carry ⚠️ base-red inherited: #<issue> in its body. To drain an accumulated red state (base tip + red PRs), use the /sweep-reds skill.