Skip to content

refactor(cli): remove redundant per-agent instruction files from webjs create templates #1366

Description

@vivek7405

Problem

When scaffolding a new WebJs app (webjs create), the CLI currently emits multiple individual per-agent instruction files (CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md, .cursor/hooks.json, .gemini/settings.json, .opencode/plugins/nudge-uncommitted.ts, etc.) to bridge rules to specific AI tools.

Now that .agents/skills/webjs/ (along with root AGENTS.md) is universally recognized as the open cross-agent standard by modern AI agents and harnesses (Cursor, Windsurf, Antigravity, opencode, Copilot, Claude Code), end-user WebJs apps no longer need individual per-agent instruction files or per-tool bridge configs. Emitting them creates unnecessary file clutter in freshly scaffolded end-user projects and risks instruction drift across agent-specific files.

Design / approach

  1. Consolidate to Open Standard: End-user WebJs apps emitted by webjs create will ship only AGENTS.md, CONVENTIONS.md, and .agents/skills/webjs/ (plus .agents/rules/workflow.md), serving as the single cross-agent source of truth.
  2. Remove Redundant Templates: Remove per-agent instruction and bridge files (CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md) and per-agent tool hook directories (.cursor/, .gemini/, .opencode/) from packages/cli/templates/.
  3. Streamline Generator Logic: Update packages/cli/lib/create.js (templateFiles array, PROSE_REWRITE Set, and file copy logic) to omit per-agent instruction files.
  4. Update Generator Tests & Docs: Update packages/cli/test/create.test.js assertions, packages/cli/README.md, and documentation to reflect the streamlined cross-agent scaffold structure.

Implementation notes (for the implementing agent)

  • Where to edit:
    • packages/cli/lib/create.js: Update templateFiles list (lines 570–625) and PROSE_REWRITE Set (lines 631–635).
    • packages/cli/templates/: Delete per-agent files (CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md, .cursor/, .gemini/, .opencode/).
    • packages/cli/test/create.test.js: Update scaffold file tree assertions.
    • packages/cli/README.md & AGENTS.md: Update docs describing generated app layout.
  • Invariants to respect:
    • .agents/skills/webjs/ and root AGENTS.md remain the authoritative cross-agent source of truth for WebJs applications.
    • Freshly scaffolded apps must pass webjs check and webjs doctor cleanly.
  • Test + doc surfaces:
    • node --test packages/cli/test/create.test.js
    • E2E scaffold verification: npx webjs create test-app && ( cd test-app && npx webjs check )

Acceptance criteria

  • Individual per-agent instruction files (CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md) and per-agent tool directories (.cursor/, .gemini/, .opencode/) are removed from scaffold templates.
  • webjs create emits only AGENTS.md, CONVENTIONS.md, and .agents/skills/webjs/ as the single cross-agent instruction surface.
  • packages/cli/test/create.test.js passes with updated file tree assertions.
  • A freshly scaffolded app boots and passes webjs check without errors.
  • packages/cli/README.md and documentation reflect the streamlined scaffold layout.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

  • Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions