mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-07 15:52:52 +03:00
1efb94b102
* 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>
56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
@AGENTS.md
|
|
|
|
**All project rules live in [`AGENTS.md`](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.
|