diff --git a/README.md b/README.md index 58236f2..876aa1b 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,81 @@ ![devcontext logo](public/logo.png) +Repo-aware AI coding guidelines assistant. Wizard or Repo Scan — your context, ready. -Build high-signal agent and instruction files from community-proven best practices. +## What DevContext does +- Generates AI‑ready files for your project: Copilot instructions, Cursor rules, and agent guidance. +- Works two ways: start from scratch with a guided wizard or scan a public GitHub repository to prefill answers. +- Surfaces examples, trade‑offs, tags, and authoritative docs so choices are transparent and revisitable. -## What devcontext does -- Transforms curated community knowledge into ready-to-use instructions for agents, coding copilots, and repo guides. -- Guides you through a multi-step wizard that selects files, stacks, and scenario-specific topics. -- Surfaces examples, trade-offs, and documentation links so every choice is backed by trusted references. +## Two ways to use +- New Project (Wizard) + - Start from curated stacks or go fully custom. + - Answer focused questions (general, architecture, performance, security, commits, etc.). + - Apply smart defaults when unsure; you can edit everything later. +- Existing Project (Repo Scan) + - Paste an `owner/repo` or full URL. DevContext detects languages, frameworks, tooling, tests, and conventions. + - The wizard is prefilled with detected signals; you only confirm or fill gaps. -## How the wizard works -1. Launch the app and switch from the landing hero to the Instructions Wizard. -2. Pick the instruction file you want to assemble (from templates defined in `data/files.json`). -3. Choose your stack and automatically load its follow-up question set (dynamic imports from `data/questions/.json`). -4. Answer topic prompts across general, architecture, performance, security, commits, and more—or lean on the recommended defaults when you need a fast decision. -5. Review a completion summary that highlights what made it into your file and which areas still need decisions. +See the Scan → Wizard pipeline in docs/scan-flow.md. -## Architecture docs -- [Scan → Wizard Flow](docs/scan-flow.md) – how repository scans feed conventions, defaults, and final instruction files. +## What repo scan detects +- Languages and frameworks (e.g., Next.js, React, Vue, Python) +- Tooling and testing (ESLint, Prettier, TypeScript; Jest, Vitest, Playwright, Cypress, pytest) +- Structure (src/, components/, tests/, monorepo/workspaces) and package manager +- Routing, styling, state management, data fetching +- Auth, validation, logging, CI/CD, code quality tools +- Editor and naming conventions; commit message style -## Community knowledge base -- Every topic originates from the developer community—playbooks, real-world retrospectives, and shared tooling habits. -- JSON entries in `data/` capture those insights: each answer carries labels, examples, pros/cons, tags, and authoritative `docs` links. -- Disabled options mark ideas that the community is still refining; they stay visible so contributors can track demand. -- Icon choices use Simple Icons with automatic contrast adjustments for readability across themes. +The detected summary is converted into wizard answers and ultimately into tailored instruction files. -## Key interaction details -- Tooltips open from the info icon, letting you explore examples, pros/cons, tags, and external docs without losing your place. -- Multi-select questions let you apply the curated default choice with a single click so momentum never stalls. -- Progress indicators keep a running count of answered versus unanswered items, making gaps obvious before export. +## Outputs +- `copilot-instructions.md` (from `file-templates/copilot-instructions-template.md`) +- `agents.md` (from `file-templates/agents-template.md`) +- `.cursor/rules` (from `file-templates/cursor-rules-template.json`) + +Templates are mapped via `lib/template-config.ts` and populated by `lib/template-render.ts`. -## Run devcontext locally +## Run locally ```bash git clone https://github.com/spivx/devcontext.git cd devcontext npm install + +# Set your GitHub token for repo scans (required) +cp .env.local.example .env.local # if present, otherwise create it +echo "GITHUB_TOKEN=YOUR_TOKEN_HERE" >> .env.local + npm run dev ``` -Then open the printed local URL in your browser to explore the wizard. +Open the printed local URL. On the landing page you can: +- Launch the wizard (Start from stacks or custom) +- Scan a public GitHub repo (prefills the wizard) -## Contribute back to the community -- Add or improve topics in `data/*.json` with clear labels, examples, and `docs` links. -- Propose new stack questionnaires under `data/questions/`, keeping the schema consistent. -- Share hooks, utilities, or UI refinements that make the wizard easier to reason about for first-time contributors. +Notes: +- Scanning requires a GitHub personal access token (`GITHUB_TOKEN`) to avoid low rate limits. +- Only public repositories are supported. + +## Testing +- Unit tests (Vitest): `npm run test` +- E2E tests (Playwright): `npm run test:e2e` +- Validate question IDs: `npm run validate:ids` + +## Community knowledge base +- All selectable answers are defined in `data/*.json` and stack‑specific files under `data/questions/.json`. +- Each answer can include `value`, `label`, `icon`, `example`, `infoLines` (from pros/cons), `tags`, `isDefault`, `disabled`, `disabledLabel`, and `docs`. +- Disabled choices show as “Soon” and are non‑interactive. +- Icons come from `simple-icons` and auto‑adjust for dark mode readability. + +## Key interaction details +- Tooltips open from the info icon and remain interactive, with External Link icons to docs. +- You can apply recommended defaults per question to keep momentum. +- A completion summary highlights answered items and remaining gaps. -Every addition helps the community build better instruction files faster. +## Contributing +- Add new stacks by updating `data/stacks.json`, adding `data/questions/.json`, and (optionally) `conventions/.json`. +- When adding logic: move shared TypeScript types into `types/` (e.g., `types/wizard.ts`). +- Extract reusable effect logic into hooks under `hooks/` and reuse across components. +- Keep PRs focused; include docs or examples where helpful. ## License -MIT License — see [`LICENSE`](LICENSE) for the full text. +MIT — see `LICENSE`.