feat: abstract AI CLI layer for multi-provider support (issue #11)

[Raj2503]

Description

Related Issue

Closes #

Changes

Checklist

• Tests pass locally (node test-all.mjs)
• No hardcoded paths (/Users/, /home/, C:\Users\)
• No personal data (emails, phone numbers, addresses)
• Documentation updated (if applicable)
• Mode files have required markdown heading (if adding/modifying modes)
• Commit messages follow conventional commits (feat:, fix:, docs:, ci:)

[Copilot]

Pull request overview

Adds a provider-agnostic “instructions” layer so the repository can be used with multiple AI CLIs by generating provider-specific instruction files from a shared template, plus minor workflow/docs updates to support environments without sub-agent delegation.

Changes:

• Introduces an instructions template and a generator script to emit per-provider instruction files (Copilot/Claude/Gemini/Cursor/Windsurf).
• Adds CLI provider detection helper and wires both scripts into package.json.
• Updates mode/docs guidance for sequential fallbacks when parallel sub-agents aren’t available and updates setup docs for Multi-CLI usage.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
templates/instructions.template.md	New shared template used to generate provider-specific instruction files.
scripts/generate-instructions.mjs	Generates instruction files for each supported CLI from the shared template.
scripts/detect-cli.mjs	Detects likely CLI provider via env vars and prints the instruction file path.
package.json	Adds npm scripts for instruction generation and provider detection; updates keywords.
README.md	Rebrands to Multi-CLI edition and documents instruction generation + supported CLIs.
docs/SETUP.md	Updates prerequisites and adds steps for generating provider instructions.
modes/_shared.md	Adds cross-CLI tool concept section (abstraction guidance).
modes/pipeline.md	Documents sequential fallback when sub-agent delegation isn’t supported.
modes/batch.md	Adds sequential fallback guidance when sub-agents are unavailable.
.github/copilot-instructions.md	Updates Copilot instructions to align with new multi-CLI template structure.
CLAUDE.md	New Claude Code instruction file generated from template.
GEMINI.md	New Gemini CLI instruction file generated from template.
.cursor/rules/career-copilot.mdc	New Cursor rule/instructions file generated from template.
.windsurfrules	New Windsurf instructions file generated from template.

[Copilot]

The new “Cross-CLI Tool Concepts” section says the mode files “use semantic operations”, but the mode files still reference concrete Copilot tool names (e.g. task, view, edit). This is misleading for non-Copilot CLIs; either update the wording to reflect that modes are Copilot-oriented and must be translated, or actually refactor mode files to use the semantic concept names consistently.

Suggested change

	These mode files use semantic operations so they can run across Copilot CLI, Claude Code, Gemini CLI, Cursor, and Windsurf. Map equivalent provider tools before execution.
	These mode files are authored for Copilot-style tool names and workflows. The concepts below are the semantic translation layer to use when adapting them for Claude Code, Gemini CLI, Cursor, Windsurf, or other providers. If a mode references a concrete Copilot tool, map it to the equivalent provider capability before execution.

[Copilot]

generate-instructions and detect-cli are added as supported scripts, but they aren’t exercised by the repo’s automated test runner (test-all.mjs currently executes a fixed allowlist of scripts). Add these scripts to the test suite (at least a smoke run) so regressions (missing template, path issues) are caught in CI/local testing.

[Copilot]

This doc section is titled “Quick Start (5 steps)”, but the instructions now include steps 1–7 (including the newly added instruction-generation step). Update the heading/step numbering so the guide stays consistent.

[RajjjAryan]

Review: Abstract AI CLI Layer (#61)

The direction is right — multi-provider support via detect-cli.mjs + generate-instructions.mjs is exactly what #11 asks for. However, this PR has a critical problem: it strips ~520 lines of domain-specific detail from copilot-instructions.md and replaces them with a generic 244-line template.

🔴 Critical: Loss of essential domain knowledge

The following sections are deleted with no equivalent in the template:

Removed Section	Why It Matters
Onboarding Checklist & Flow	Guides first-time setup
Routing Rules	Maps user intents to mode files
Report Numbering & Naming	{num}-{slug}-{date}.md convention
Field Definitions (TSV format)	Exact tracker column spec
Pipeline Integrity Rules	Cross-checks for data consistency
State Transition Rules	Valid status progressions
Error Handling & Edge Cases	Browser fallback, rate limiting
Report File Structure	Dimension scores template
Batch & Parallel Processing	Worker constraints
Customization Workflow	What users can/can't change

Without these, the AI agent won't know how to generate proper reports, validate the pipeline, or handle edge cases. The generic template covers about 30% of what the agent needs to function.

✅ What's good

• scripts/detect-cli.mjs — clean provider detection from env vars
• scripts/generate-instructions.mjs — solid template approach
• templates/instructions.template.md — good skeleton
• Tool mapping table (section 13) — exactly right
• README + SETUP.md updates — helpful

🛠️ Suggested approach

Instead of replacing the detailed instructions, extend them:

1. Keep the full copilot-instructions.md as-is (all 600+ lines)
2. Add the tool mapping table (section 13) and provider notes to it
3. Use the template to generate CLAUDE.md, GEMINI.md, etc. by including the full domain content + provider-specific tool names
4. Or: keep domain content in a shared templates/domain-knowledge.md that all provider instruction files reference

The template should be: domain knowledge + provider-specific tool mapping, not generic skeleton only.

🟡 Minor issues

• .cursor/rules/ — adds a hidden directory; consider documenting in .gitignore or README
• No tests for detect-cli.mjs or generate-instructions.mjs
• PR body is mostly empty — please fill in the Description and Changes sections

---

TL;DR: Love the architecture, but the current implementation deletes critical domain knowledge. The fix is to keep the full content and add multi-provider support on top of it rather than replacing it.

[RajjjAryan]

This is superseded by #66, which has been merged and closes #11. Closing this stale PR to keep the queue clean.