Imported from hanzlahabib/rcode (AGENTS.md). Install upstream with npx skills add hanzlahabib/rcode. Copyright stays with the author.

AGENTS.md — Rules for AI Agents Working on This Repo

This file is loaded by Claude Code, Codex, and compatible AI coding tools at the start of every session. The rules below are NON-NEGOTIABLE.

🚨 CRITICAL: Never Push Without Explicit Human Approval

The single most important rule:

• NEVER run git push without the user explicitly saying "push", "push it", "push to remote", "push to origin", or similar direct authorization on that specific push.
• NEVER git push --force under any circumstances without the user typing it themselves.
• NEVER push in the background, in a loop, in an "autonomous mode", or as part of a larger task, even if the user previously authorized a push earlier in the session. Every push requires fresh approval.
• NEVER configure CI, hooks, or scripts that auto-push. Commits are fine. Pushes require a human hand.
• If you are unsure whether a push is authorized, STOP and ask. The cost of asking is 5 seconds. The cost of an unauthorized push can be lost work, broken CI, or exposed secrets.

If a user says "just keep going" or "don't stop until done", that authorization applies to local commits only — never to pushes.

Violations of this rule are the most serious form of trust violation in this repository.

Commit Rules

• Follow Conventional Commits format: type(scope): subject
• Types allowed: feat, fix, docs, style, refactor, test, chore, perf, revert
• Scopes allowed: agents, skills, workflows, templates, dashboard, docs, config, github, github-sync, commands, memory, brand, cli, ci, release, meta, tasks, migrations, refs, state, hooks, init, install, parity, triggers, dogfood, namespace, planning, insights, help, roadmap, session, audits, execute, executor, plan, planner, readme, rcode, review, sync, sprint, agent-exp, extensibility, lens-audit, tiers, build, council, doctor, postinstall, progress, security, tools, uninstall, update, test, changelog, scopes, phases, references, kanban, orchestrator, orchpanel, status, bin, brain, dogfeed, new-project, package, rcode-tools, rihal-tools, team, usp, v4, observability, audit, agent-rules, cursor, i18n, phase, scaffold, campaign, ship, getting-started, do-router, milestone-health, modules, project-types, roadmapper, token, benchmarks, eval, scan, map-codebase, verifier, discuss-phase, ui-phase, state-sync, autonomous, seo, scaffold-skill, resume-work, plus numeric phase/sprint scopes (e.g. docs(15), feat(8.3))
• Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
• NEVER add Claude/AI attribution to commit messages. No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
• NEVER use --no-verify to bypass hooks. If hooks fail, fix the underlying issue.
• ALWAYS stage specific files with git add <files> — never git add -A or git add . without reading what would be staged first.

Pull Request Rules

• PR titles follow Conventional Commits (enforced by .github/workflows/semantic.yaml)
• Use the template in .github/pull_request_template.md
• Every skill change must pass the 5-component compliance check:
  1. YAML trigger header with 5-12 trigger phrases + negative boundaries
  2. Overview paragraph
  3. Workflow/instructions
  4. Output Format section
  5. Examples (happy + edge + negative)
• Every agent change must update: team.yaml, dashboard roster, README table

Naming & Branding (per BRAND.md)

• Skill names in frontmatter: rcode-<verb>-<noun> for legacy skills; new branded skills use rcode-<verb>-<noun> ONLY in slash command surface (/rcode-<name>); folder names stay rcode-* because cli/install.js hardcodes that prefix.
• Persona IDs in team.yaml stay rcode-<name> (dashboard scanner reads them by id; renaming breaks rendering).
• Persona display names keep Arabic alongside Latin: Sadiq (صادق), Dalil (دليل), etc.
• Concept primitives (Memory Bank, Distillate, Majlis, Diwan) are named tooling — capitalised, used consistently in user-facing copy.
• Plain English over jargon in flags. Prefer --attack over --adversarial, --edge-cases over --edge-case-hunter. Audience includes non-native English speakers.

File Modification Rules

• Maximum file size: 1000 lines — refactor before exceeding
• Refactor incrementally — never rewrite from scratch
• Preserve existing patterns — don't introduce new conventions without documented justification
• Never remove dependencies without explicit user approval
• Verify imports exist before referencing them

Dashboard Server Rules

• server/dashboard.js is the entry point; server-side logic lives in server/lib/ (api.js, scanner.js, html/) and server/orchestrator.js — split across files, not single-file
• No external framework dependency on the server or client — the client is a Preact SPA built on a vendored copy (server/lib/html/client/vendor/preact.js), not an npm package; keep it that way
• View-only — NEVER add write endpoints, POST handlers, or database code
• Test after every change: node server/dashboard.js must start cleanly

Testing Rules

• Run schema validation after modifying any skill or agent — it enforces the 5-component skill standard (frontmatter, trigger phrases, negative boundary) in place of the old grep-based check:

  node cli/doctor.js                       # full preflight + compliance
  node --test test/artifact-schema.test.cjs   # schema validators only

• Run grep checks before committing renames or refactors. Scope to TODO: and code files only — rcode/, docs/, and skill/workflow markdown legitimately discuss the concept of TODOs (stub-detection guides, the add-todo/check-todos commands, checklists); an unscoped -i "TODO" grep will always be red on this repo:

  grep -rn "TODO:" rcode docs examples README.md server \
    --include="*.js" --include="*.cjs" --include="*.mjs" --include="*.ts"
  # should be empty, or only match deliberate string/regex literals
  # (e.g. rcode/bin/rcode-hooks.cjs's hedging-language detector)

• Test the dashboard server boots without errors before committing dashboard changes

Scope Discipline

• Do EXACTLY what was asked — nothing more
• No "while I'm here" improvements
• No speculative abstractions
• No new files unless necessary
• If the user asks for a bug fix, don't also refactor nearby code

Communication Rules

• Report progress honestly — do not claim work is done if it isn't
• Flag blockers immediately — do not silently fail
• When unsure, ask — do not guess at user intent on destructive operations
• If the user gives a standard to maintain (like the 5-component skills standard), enforce it on every future change

Red Flags — Stop and Reconsider

• About to run git push — STOP. Is this explicitly authorized for THIS push?
• About to add a dependency — stop and ask
• About to delete files — stop and confirm
• About to modify .github/workflows/* — these affect CI; stop and explain what will change
• About to edit AGENTS.md, CONTRIBUTING.md, or CLAUDE.md — these are meta-rules; stop and confirm

When This File Conflicts With the User

If the user explicitly overrides a rule in this file (e.g., "yes, push it now"), the explicit instruction wins for that one action. Do NOT generalize a one-time authorization to a blanket permission.

This file is part of the project. Treat it as load-bearing.