feat(instructions): when the JavaScript ecosystem is chosen, write TypeScript -- an architecture-choice rule, not just a style guide

[MarkMichaelis]

Owner request (2026-09-14)

When choosing architecture, favor TypeScript over JavaScript (when that technology is selected).

Gap

The shared instructions route .ts, .js and package.json files to typescript.instructions.md, but that file (applyTo: '**/*.ts') only governs how to write TypeScript. Nothing says which to choose. So a new Node/browser component can be started in plain JavaScript by default, and the instructions never push back.

Proposal

Add an architecture-choice rule where technology decisions are made: the shared conventions in .github/copilot-instructions.md, and the @plan agent's design step.

• When the JavaScript ecosystem is the chosen technology (Node, browser, a CLI or tooling script, a web front end), write TypeScript, not plain JavaScript. Record the choice in the plan or design.
• Scope: new components and new projects. Existing plain-JS code is not rewritten because of this rule. Migrating an existing JS codebase is a separate, explicitly-decided piece of work with its own issue. It is never a side effect of an unrelated change.
• Allowed exceptions, stated in the design when taken: a host that requires plain JS and cannot run a build step (for example, a script executed directly by a tool that loads .js), a one-file throwaway, or a consumer-mandated constraint.
• Add a matching line to typescript.instructions.md's intent, so the .js routing points somewhere that says "prefer TypeScript for new code".

Project-agnostic. No new command-line options.

Acceptance

• The rule is in the shared instructions and in @plan's design step, with the new-code scope and the stated exceptions.
• typescript.instructions.md states the preference for new code.
• Section-scoped tests, and the instruction lint passes.

Open question for the owner (not blocking)

The web-api-discovery toolkit is plain CommonJS JavaScript today. Under this rule it stays as-is unless a migration is explicitly decided, and that migration would be its own issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fda3nBeB9rJBPdJSmD7sRN

[MarkMichaelis]

Prioritized priority-2 / area:workflow: the owner's request, small and settled, but it changes future design decisions rather than unblocking current work.

[MarkMichaelis]

Owner decision (2026-09-14) on the open question: the web-api-discovery toolkit stays plain JavaScript for now. Get the pipeline working first; a TypeScript migration is not urgent and gets its own issue only once the pipeline's correctness work is done.