feat: improve agentic AI development flow and guidelines

[jescalada]

Closes #1410.

Note: This PR summary was generated via the /summary command and manually tweaked.

What: Add CLAUDE.md and a set of Cursor/Claude commands under .claude/commands to support AI-assisted development and consistent agent workflows.

Why: Agents need proper context for GitProxy’s architecture and conventions. Furthermore, the new commands help speed up typical tasks such as issue creation, PR summaries, docs updates, linting, and review follow-up to improve the dev experience and help humans focus on quality control and more pressing issues.

Changes:

• Add CLAUDE.md with project overview, build/run steps, high-level architecture (proxy, service, config, UI), development guidelines, and agent workflow (delegation).
• Add .claude/commands/ with seven commands:
  • address-review (apply review feedback)
  • commit (incremental conventional commits)
  • docs (update README/Architecture/CLAUDE from branch changes)
  • implement (issue → branch → code → commit → summary)
  • issue (summarize issue for implementation)
  • lint (run lint/format)
  • summary (PR description summary).
• Update .gitignore to ignore /plans (where command outputs are stored).
• Update README.md Contributing section to point to CLAUDE.md and .claude/commands for AI-assisted development.

How to verify:

1. Open CLAUDE.md and confirm it describes proxy, service, config, UI, and push/pull/default chains.
2. Run each command (e.g. /summary, /docs) and confirm they behave as described in their files.
3. Confirm plans/ is ignored by Git and that README.md links to CLAUDE.md and .claude/commands.

Credit goes to @sudiptob2 for original implementation in Armada Spark!

[netlify]

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Name	Link
🔨 Latest commit	2d65d3f
🔍 Latest deploy log	https://app.netlify.com/projects/endearing-brigadeiros-63f9d0/deploys/699e8504cdb64b0008d65024

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.78%. Comparing base (6713757) to head (2d65d3f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1411   +/-   ##
=======================================
  Coverage   81.78%   81.78%           
=======================================
  Files          67       67           
  Lines        4766     4766           
  Branches      827      827           
=======================================
  Hits         3898     3898           
  Misses        852      852           
  Partials       16       16           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dcoric]

Nice improvement! This should help steer AI-assisted code changes toward consistent repo rules. I left a couple of small nits.

One additional improvement: make the setup cross-tool friendly by using a canonical policy file + thin bridge files.

Proposal:

1. Use AGENTS.md as the canonical repo policy.
2. In AGENTS.md, add a rule like: “For command workflows, read .claude/commands/*.md.”
3. Add thin tool-specific bridge files:
   • CLAUDE.md -> points to AGENTS.md + .claude/commands
   • GEMINI.md -> points to AGENTS.md (or mirrors the key rules)
   • .cursor/rules/00-agents.mdc (or .md) -> points to AGENTS.md

Notes / compatibility:

• Codex: uses AGENTS.md.
• Cursor: uses AGENTS.md / CLAUDE.md and .cursor/rules (commands via .cursor/commands).
• Gemini CLI: defaults to GEMINI.md, but can be configured to read AGENTS.md via context.fileName.
• Claude Code: custom slash commands live in .claude/commands.

Refs:

• Claude Code slash commands: https://docs.claude.com/en/docs/claude-code/slash-commands
• Cursor rules: https://docs.cursor.com/context/rules-for-ai
• Cursor commands: https://docs.cursor.com/en/agent/chat/commands
• Cursor CLI: https://docs.cursor.com/en/cli/using
• Gemini GEMINI.md: https://geminicli.com/docs/cli/gemini-md
• Gemini config: https://geminicli.com/docs/get-started/configuration/
• Codex + AGENTS.md: https://openai.com/index/introducing-codex/

For a real-world OSS example of this pattern, see:
https://github.com/ghostty-org/ghostty

It demonstrates a clean canonical policy file with tool-specific bridges, which aligns well with this proposal.

[dcoric]

This conflicts with git push rule from line 46 in this file. Pushing detached HEAD will fail with regular git push as instructed. I think this should be limited for a review purposes, or extend git push to use git push <remote> HEAD:<pr-head-branch> which will work with --detach

[dcoric]

Just a suggestion as REST endpoint does not return resolved status on comments, it just lists them, there is alternative to use gh command with GraphQL:

gh api graphql -f query='
query($owner:String!, $repo:String!, $number:Int!, $cursor:String) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$number) {
      reviewThreads(first:100, after:$cursor) {
        pageInfo { hasNextPage endCursor }
        nodes {
          isResolved
          isOutdated
          path
          line
          originalLine
          comments(first:100) {
            nodes {
              databaseId
              body
              author { login }
              createdAt
              url
            }
          }
        }
      }
    }
  }
}' -F owner={owner} -F repo={repo} -F number=<number> -F cursor=<cursor>

That gives unresolved review threads with the latest comment details;
This avoids double tool-calling