docs: add AGENTS.md and agent workflow guide for AI-assisted edits

[adrianstanca1]

Adds .cursor/skills/local-handbook/ (SKILL.md, logic.md, memory.md) so agents and contributors get a small, repeatable playbook: when to read it, verification commands for this repo, and cross-machine notes via ~/.cursor/skills/local-handbook/memory.md.

Fork main includes PR https://github.com/adrianstanca1/openclaude/pull/1 (merged) plus follow-up docs(cursor): refresh handbook after PR merge — no absolute paths in repo-local memory.

If this is too opinionated for upstream, happy to trim to a minimal SKILL.md only.

Made with Cursor

[adrianstanca1]

Synced adrianstanca1/openclaude:main with Gitlawb/openclaude:main (merge commit 2915f62 on the fork). The .cursor/skills/local-handbook/ files remain; this PR should now be a cleaner delta against current upstream main.

[kevincodex1]

Hi @adrianstanca1 I like the direction of this, but I would suggest that it would be better if we have a unified AGENTS.md file so its not cursor specific.

For reference here is the AGENTS.md from Hermes. if you can work on this it would be much appreciated.

https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md

thank you

[adrianstanca1]

@kevincodex1 Thanks for the feedback — agreed that editor-specific trees are not the right primary home.

Changes (on adrianstanca1/openclaude:main, now at 8eeb7b8):

• Added root AGENTS.md — canonical, tool-agnostic guide: project purpose, Bun/build layout, verification command table, workflow expectations, fork/upstream hygiene, and a link to Hermes AGENTS.md as the structural reference you pointed to.
• Slimmed .cursor/skills/local-handbook/ so SKILL.md / logic.md / memory.md explicitly defer to AGENTS.md and only keep minimal Cursor/fork pointers.

Happy to iterate on section depth or naming if you want it closer to Hermes’ table-of-contents style.

[kevincodex1]

Hi @adrianstanca1 awesome! Thank you for your changes. One more thing I think we can remove .cursor and just rely on AGENTS.md and docs can you expand AGENTS.md and then maybe add those file to docs?

[Vasanthdev2004]

Review: PR #766 — Add local-handbook agent skill for Cursor

Reviewed on head 8eeb7b8. CI green ✅. 4 files.

🔴 Blockers

1. AGENTS.md at repo root conflicts with the existing canonical agent instructions

The repo already has a .github/CONTRIBUTING.md and project-specific conventions. Adding a new root-level AGENTS.md that defines itself as "canonical" creates ambiguity about which file is authoritative. This is especially problematic because:

• The file prescribes workflows ("read before you edit", "smallest useful diff") that may conflict with existing contributor guidelines
• It references commands like bun run smoke, bun run hardening:strict that may not exist in this repo
• It creates a .cursor/ directory structure that's specific to one editor, setting a precedent for other editors to add their own directories

2. .cursor/ directory is editor-specific and shouldn't be in the repo

The .cursor/skills/ structure is proprietary to the Cursor editor. Adding it to the upstream repo means:

• All contributors (who may use VS Code, Neovim, etc.) now have editor-specific config in the repo
• Sets precedent for .vscode/, .jetbrains/, etc.
• The memory.md file contains contributor-specific fork URLs that don't belong upstream

3. Fork-specific URLs in memory.md

The file contains:

- This fork (origin): https://github.com/adrianstanca1/openclaude
- Upstream PR: https://github.com/Gitlawb/openclaude/pull/766
- Fork merge PR: https://github.com/adrianstanca1/openclaude/pull/1

These are contributor-specific and don't belong in the upstream repo.

Suggestion

If Cursor users need a local handbook, this belongs in their fork, not upstream. The AGENTS.md content could be proposed as updates to CONTRIBUTING.md or README.md instead.

Verdict: Needs changes 🔧

[auriti]

QA Review — Cursor local-handbook agent skill

Verdict: REQUEST CHANGES

Issues

1. Fork-specific content in upstream repo (critical)
memory.md contains URLs specific to your personal fork (adrianstanca1/openclaude, fork PR #1). This is personal configuration that doesn't belong in the upstream repository.

2. .cursor/ directory in upstream (major)
Editor-specific directories (.cursor/, .vscode/, .idea/) generally don't belong in a shared upstream repo unless the project has explicitly adopted them. This sets a precedent — other contributors could add their own editor configs. The PR description acknowledges this: "If this is too opinionated for upstream, happy to trim."

3. AGENTS.md duplicates existing docs (major)
The verification commands table and workflow expectations overlap with what's already in README.md (Source Build section) and CONTRIBUTING.md. Adding a parallel document creates drift risk — when commands change, two files need updating instead of one.

What has merit

The concept of an AGENTS.md as a single canonical guide for AI assistants is reasonable, especially for a project that's itself an AI coding agent. The structure is clean and the separation between generic (AGENTS.md) and Cursor-specific (skill/) is well thought out.

Suggested path forward

1. Remove .cursor/ entirely — keep it in your fork if useful for your workflow
2. Remove memory.md or strip all fork-specific references
3. For AGENTS.md: open a Discussion first to get maintainer buy-in on whether this adds value over the existing README/CONTRIBUTING. If accepted, ensure it references (not duplicates) existing docs
4. Consider adding AGENTS.md content to CLAUDE.md instead, which already exists in the repo as the agent guide

[adrianstanca1]

Updated adrianstanca1:main to address the latest review thread (especially @kevincodex1): no .cursor/ tree on the branch, expanded material lives in docs/agent-workflow.md, and AGENTS.md is a short editor-agnostic checklist that defers to CONTRIBUTING.md / README.md for authority.

Fork backup of the previous main tip (includes merged #2/#3 and deploy-related history): adrianstanca1/openclaude:fork/main-backup-pre-pr766-rewrite. Ongoing deploy work remains on cursor/deploy-scripts-docs — rebase that branch onto the new main when you want it on top of upstream again.

Local verification: bun run smoke ✅ on this tip.

Happy to tweak naming or section depth if you want AGENTS.md closer to Hermes’ TOC style without growing the root file again.

[Vasanthdev2004]

Requesting changes for contributor workflow regressions:

• .vscode/tasks.json shells through ${workspaceFolder}/scripts/cursor-dev-path.sh, but that script is not in the repository, so the advertised tasks fail immediately.
• docs/deploy.md documents Bash-only deploy commands and VS Code tasks without any Windows/Git Bash/WSL note, even though the repo already has Windows-oriented setup docs elsewhere.

Residual gap: I still do not see CI coverage for the new editor tasks or deploy-script path.

[gnanam1990]

A few things before this can land: (1) the .cursor/skills/local-handbook/ subtree is personal / machine-specific tooling (MCP configs, shell fragments, apply-machine-config.sh) and probably shouldn't live in the upstream repo. (2) bun.lock and package.json are touched in what's framed as a docs-only PR, which usually indicates unintentional local-setup side-effects. (3) the branch is currently conflicting with main. Suggestion: split into a minimal PR with just AGENTS.md + docs/agent-workflow.md + README nudge (no lockfile changes, no .cursor/ subtree). Happy to review that. Thanks!

[Vasanthdev2004]

Thanks for the updates. This is a targeted re-review of the current head b028d53ad142ea005fe2ec52ccdacc2a79441e88.

Verdict: Needs changes

Blocking issues:

1. .cursor/skills/local-handbook/ is still personal / machine-specific upstream content. On the current head, it still contains hardcoded local environment details, personal fork/PR history, private/local handbook repo notes, and scripts that write into ~/.claude and ~/.cursor. That remains out of scope for upstream.
2. The PR is still much broader than the stated docs change. package.json, bun.lock, docs/deploy.md, .vscode/tasks.json, scripts/deploy-from-source.sh, and scripts/cursor-dev-path.sh make this a packaging/tooling/dependency PR, not just an AGENTS.md + workflow-docs cleanup.
3. The branch is currently not mergeable with main.

Non-blocking notes:

• AGENTS.md plus docs/agent-workflow.md is the part that looks closest to upstreamable if broken out cleanly.
• I do not currently see GitHub checks on this head.
• The PR body should be updated once the branch is narrowed, since it no longer matches the current diff.

Happy to re-review once the current head is narrowed and rebased.

[jatmn]

closing as stale. Its a good idea, but should include discussion of the direction to take this so there is no conflict with other .md files that otherwise direct the agent as it is.