Skip to content

scaffold: per-tool rule files diverge in mandatory-workflow ordering #134

Description

@vivek7405

Problem

Surfaced by the self-review loop on PR #133. The scaffold ships three per-tool rule files that are supposed to "say the same thing" per the AI-first-is-plumbing blog post (blog/ai-first-is-plumbing.md:29). They diverge structurally:

  • packages/cli/templates/.cursorrules orders the mandatory list as TESTS (1), DOCS (2), CONVENTIONS (3), PRE-MERGE SELF-REVIEW LOOP (4). Tests collapses server + browser into one bullet.
  • packages/cli/templates/.agents/rules/workflow.md (the new Antigravity file from scaffold: rename Windsurf surfaces to Antigravity (post-merger) #132) orders the same list as Server tests (1), Browser tests (2), Documentation (3), Convention check (4), Pre-merge self-review loop (5). Tests are split.
  • packages/cli/templates/.github/copilot-instructions.md uses a six-item list with "commit per logical unit" as item 1; the other two files put commit-per-unit under a separate Git rules section.

Not a substance bug. Same rules in all three. But an AI agent reading two files for the same project sees three different shapes, and a future edit that updates one file will probably miss the others.

Design / approach

Pick the canonical shape. Strong candidates:

  1. Five-item list shape (Server tests, Browser tests, Documentation, Convention check, Pre-merge self-review loop) per workflow.md. Reads cleanly because each item is a single concern.
  2. Four-item list shape (Tests, Docs, Conventions, Pre-merge self-review loop) per .cursorrules. Reads more compactly.

Pick one, apply to all three files. The commit-per-logical-unit rule stays under Git rules in all three to match where it lives today.

Acceptance criteria

  • Pick the canonical shape (note the decision in the PR body).
  • All three files share the same numbered list under "Mandatory workflow" (or whatever heading).
  • All three files share the same Pre-merge self-review loop phrasing (already aligned for primitive-mention as of scaffold: rename Windsurf surfaces to Antigravity (Google) #133).
  • Pre-existing wording differences (Cursor "open a NEW composer tab" vs Copilot "open a NEW chat" vs Antigravity "Cascade thread") are intentional and stay tool-specific.

Activity

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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

  • Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions