ai-vscode-basics

🧰 ai-vscode-basics

A model-agnostic scaffold for repositories where AI coding agents do real work. Drop-in instructions, configs, skills, tracking, and a tiny Makefile + xops layer that work the same across GitHub Copilot, Claude, Gemini, Codex CLI, Cursor, OpenCode, Aider, and local models (Ollama / LM Studio).

---

⚡ Quickstart in 60 seconds

# 1. One-liner install (scaffolds into ./my-repo, creates it if needed)
curl -fsSL https://raw.githubusercontent.com/metaphy6/ai-vscode-basics/main/install.sh \
  | bash -s -- --target ./my-repo

# 2. Or clone + scaffold manually
git clone https://github.com/metaphy6/ai-vscode-basics.git ~/code/ai-vscode-basics
~/code/ai-vscode-basics/xops/init/scaffold.sh --target ./my-repo

# 3. Verify + orient the first agent session
cd ./my-repo
make doctor
xops/agent/session-bootstrap.sh

---

🎯 What this is

ai-vscode-basics is a bootstrapper (not a template you fork). You keep this repo around once, then scaffold its agent framework into any new or existing project with one command:

xops/init/scaffold.sh --target /path/to/your-project

It gives every project the same shape:

• 📜 One rulebook (AGENTS.md) that every AI assistant reads first, plus thin per-vendor entry points (CLAUDE.md, GEMINI.md, CONVENTIONS.md, .github/copilot-instructions.md, .cursor/rules/, .codex-plugin/, …) that all delegate back to it. No drift between assistants.
• 📊 A 9-column ai/tracking.csv that records every meaningful agent action (plan / implement / test / review / commit / revert / note / block) — the single source of truth make git reads to build commit messages.
• 🤖 make git / make git.dry — agents never run git commit / git push; they append a tracking row and stage files, the human (or make git) commits.
• 🗺️ A ROADMAP.md template + docs/{code,project,design,planning,tracking,guides} layout so agents always know where to put things.
• 🧪 xops/ — a tiny ops tree with safe-run.sh (crash-safe command wrapper), session-bootstrap.sh (orient a fresh agent session), tracking_append.sh (validated CSV appender), and Python ops scripts for make git.
• 🧠 .agents/skills/ — a curated, general-purpose skill library (TDD, systematic debugging, code review, documentation discipline, MCP usage, parallel subagents, AI output stability, …) that any project can benefit from. Skills live under .agents/skills/<name>/SKILL.md and are accessible via the VS Code Copilot / command.

CI/CD, language-specific tooling, and project-specific business rules are intentionally excluded — those live in your project.

---

🚀 Scaffold options

# Dry run first (shows every file that would be created / skipped)
./xops/init/scaffold.sh --target /path/to/your-project --dry-run

# Real run (idempotent — existing files are left alone unless --force)
./xops/init/scaffold.sh --target /path/to/your-project

Choose a preset:

./xops/init/scaffold.sh --target /path/to/your-project --preset minimal
./xops/init/scaffold.sh --target /path/to/your-project --preset full   # default

Pick exactly which agent surfaces you want:

./xops/init/scaffold.sh --target /path/to/your-project \
  --agents copilot,claude,gemini --no-cursor --no-aider

Add a language preset:

./xops/init/scaffold.sh --target /path/to/your-project --lang python
# also: node | go | rust — adds .gitignore lines + Makefile.lang.mk

After scaffolding

In your project:

make help          # list every target
make git.dry       # preview what would be committed (read-only)
make git           # commit pending tracking rows + push
make track.add ACTION=note SUMMARY="..."   # append a tracking row
make doctor        # sanity-check the framework is wired correctly

The agent in your project reads AGENTS.md first. That's it.

---

🗂️ What gets installed