crewkit 0.1.0 → 1.1.0

package/README.md

@@ -1,5 +1,127 @@
 # crewkit
 
+Framework de context engineering para desenvolvimento assistido por IA. Um comando para configurar agents, skills, hooks, rules e memory no seu projeto.
+
+## O que faz
+
+O `crewkit` escaneia sua codebase e gera um setup completo e calibrado de context engineering:
+
+- **Agents** (5) — explorer, architect, coder, tester, reviewer com roles definidos e tiers de modelo
+- **Skills** (4) — full-workflow, hotfix, explore-and-plan, review-pr
+- **Hooks** (4) — session-start, protect-sensitive-files, post-compact-recovery, stop-quality-gate
+- **Rules** — regras de codigo por stack geradas a partir de padroes detectados
+- **Memory** (`.ai/memory/`) — architecture, conventions, commands, testing, lessons
+- **CLAUDE.md** — hard rules do projeto derivadas de padroes reais do codigo
+- **settings.json** — permissoes conservadoras + registro de hooks
+- **.mcp.json** — MCP servers detectados da sua infraestrutura (PostgreSQL, Redis, Sentry, etc.)
+
+Tudo calibrado pro seu codigo real — nao e boilerplate generico.
+
+## Instalacao
+
+```bash
+npx crewkit install
+```
+
+Copia a skill para `~/.claude/skills/crewkit-setup/` (setup unico).
+
+## Uso
+
+Abra qualquer projeto no Claude Code e rode:
+
+```
+/crewkit-setup
+```
+
+A IA escaneia sua codebase (~8-15 min) e gera o setup completo. Zero perguntas durante o scan — detecta tudo a partir do codigo, historico git e docs.
+
+### O que acontece
+
+1. **Pre-flight** — verifica modelo, detecta re-runs, oferece backup
+2. **Phase 0** — cria estrutura de diretorios, atualiza .gitignore
+3. **Phase 1-3** — detecta stacks, le docs, mapeia estrutura do projeto
+4. **Phase 4** — leitura profunda de arquivos representativos, detecta padroes com score de confianca
+5. **Phase 5** — health check (opcional, com `--check-health`)
+6. **Phase 6** — apresenta perfil pra sua revisao antes de gerar
+7. **Phase 7** — gera todos os arquivos em ordem de falha graceful
+
+### Re-runs
+
+Se voce rodar `/crewkit-setup` de novo num projeto que ja tem setup:
+
+- **[R] Regenerate** — backup do existente, regenera tudo
+- **[M] Memory only** — re-scan e atualiza memory + CLAUDE.md, preserva agents/hooks/skills
+- **[C] Cancel**
+
+## Stacks suportadas
+
+Detectadas automaticamente a partir de arquivos de manifesto:
+
+| Stack | Detectado por |
+|-------|--------------|
+| .NET | `*.csproj`, `*.sln` |
+| Node.js | `package.json` (Express, Next.js, Nest, etc.) |
+| Python | `pyproject.toml`, `requirements.txt` |
+| Go | `go.mod` |
+| Rust | `Cargo.toml` |
+| Java/Kotlin | `pom.xml`, `build.gradle` |
+| Ruby | `Gemfile` |
+| Elixir | `mix.exs` |
+| PHP | `composer.json` |
+| Dart/Flutter | `pubspec.yaml` |
+
+## Agents gerados
+
+| Agent | Modelo | Funcao |
+|-------|--------|--------|
+| explorer | Sonnet | Exploracao read-only da codebase |
+| architect | Opus | Review de arquitetura + gate de aprovacao |
+| coder | Sonnet | Diffs minimos, padroes existentes |
+| tester | Sonnet | Workflow completo de testes + accountability de cobertura |
+| reviewer | Opus | Code review de alto sinal, sem ruido |
+
+## Skills opcionais
+
+Alem das 4 skills core (instaladas automaticamente), voce pode adicionar skills opcionais:
+
+```bash
+npx crewkit add retro          # post-mortem de tarefas
+npx crewkit add dev-metrics    # metricas de desenvolvimento via git
+npx crewkit add security-scan  # scan OWASP top 10
+npx crewkit add impact         # analise de blast radius
+```
+
+## IDEs suportadas
+
+- **Claude Code** — suporte completo (agents, skills, hooks, rules, memory)
+- **GitHub Copilot** — auto-detectado, gera `copilot-instructions.md`, agents e prompts
+- **Cursor** — auto-detectado, gera rules com globs e `AGENTS.md`
+
+A IDE e detectada automaticamente durante o setup. `.ai/memory/` e compartilhado entre todas as IDEs.
+
+## O que e commitado vs ignorado
+
+**Commitado** (compartilhado com o time):
+- `CLAUDE.md`, `.claude/agents/`, `.claude/rules/`, `.claude/skills/`, `.claude/hooks/`
+- `.claude/settings.json`, `.ai/memory/`
+
+**Ignorado** (pessoal/metadata):
+- `.claude/settings.local.json`, `.crewkit/`, `.crewkit-backup/`
+
+## Requisitos
+
+- Node.js >= 20
+- Claude Code, GitHub Copilot ou Cursor
+- Opus ou Sonnet recomendado (Haiku funciona mas gera scans mais rasos)
+
+## Licenca
+
+MIT
+
+---
+
+# English
+
 Context engineering framework for AI-assisted development. One command to set up agents, skills, hooks, rules, and memory for your project.
 
 ## What it does
@@ -80,6 +202,25 @@ Detected automatically from manifest files:
 | tester | Sonnet | Full test workflow + coverage accountability |
 | reviewer | Opus | High signal code review, no noise |
 
+## Optional skills
+
+In addition to the 4 core skills (auto-installed), you can add optional skills:
+
+```bash
+npx crewkit add retro          # task post-mortem
+npx crewkit add dev-metrics    # development metrics from git
+npx crewkit add security-scan  # OWASP top 10 scan
+npx crewkit add impact         # blast radius analysis
+```
+
+## Supported IDEs
+
+- **Claude Code** — full support (agents, skills, hooks, rules, memory)
+- **GitHub Copilot** — auto-detected, generates `copilot-instructions.md`, agents and prompts
+- **Cursor** — auto-detected, generates rules with globs and `AGENTS.md`
+
+IDE is auto-detected during setup. `.ai/memory/` is shared across all IDEs.
+
 ## What gets committed vs ignored
 
 **Committed** (shared with team):
@@ -92,7 +233,7 @@ Detected automatically from manifest files:
 ## Requirements
 
 - Node.js >= 20
-- Claude Code (v0.1 — Copilot and Cursor support planned for v0.2)
+- Claude Code, GitHub Copilot, or Cursor
 - Opus or Sonnet recommended (Haiku works but produces shallower scans)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewkit",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Context engineering framework for AI-assisted development. One command to set up agents, skills, hooks, rules, and memory for your project.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -142,6 +142,21 @@ For each stack, detect the build and test commands:
 
 Read `package.json` scripts, CI configs, or Makefiles to find the actual commands used in this project. Prefer project-specific over generic.
 
+### IDE Target Detection
+
+Detect which IDEs are in use or configured in this project:
+
+| IDE | Detection signals |
+|-----|------------------|
+| Claude Code | **Always** — this skill runs inside Claude Code |
+| GitHub Copilot | `.github/` directory exists OR `.github/copilot-instructions.md` found |
+| Cursor | `.cursor/` directory exists OR `.cursorrules` file found |
+
+Save all detected IDE targets to the scan data. Example:
+```
+IDE targets: Claude Code (always), GitHub Copilot (detected: .github/ exists), Cursor (not detected)
+```
+
 **Store results as: `ReconProfile`** — write to `.crewkit/scan-phase1-recon.md` for persistence.
 
 Report: "Phase 1 complete. Detected: [stacks], [CI], [DBs], [build/test commands]."
@@ -393,6 +408,9 @@ Compile all profiles into a single summary and present it to the user.
 - Build: `[command]`
 - Test: `[command]`
 - Dev server: `[command]` (if detected)
+
+## IDE Targets
+- [list each detected IDE — e.g., "Claude Code (always), GitHub Copilot (detected: .github/ exists)"]
 ```
 
 ### Save profile
@@ -883,18 +901,23 @@ Write calibrated hooks to `.claude/hooks/`.
 
 ---
 
-### Step 7 — `.claude/skills/` (templates, copied directly)
+### Step 7 — `.claude/skills/` (templates + references)
 
-Read all 4 core skill templates from `~/.claude/skills/crewkit-setup/templates/skills/`:
-- `full-workflow/SKILL.md`
+Read all core skill templates from `~/.claude/skills/crewkit-setup/templates/skills/`:
+- `full-workflow/SKILL.md` + `full-workflow/references/`
 - `hotfix/SKILL.md`
 - `explore-and-plan/SKILL.md`
 - `review-pr/SKILL.md`
 
-Copy each skill template to `.claude/skills/[name]/SKILL.md`.
+Copy each skill template to `.claude/skills/[name]/SKILL.md`. **If the template has a `references/` subdirectory, copy it too.**
 
 These skill templates are **stack-agnostic** by design — they reference `.ai/memory/commands.md` for build/test commands and `.ai/memory/` for project context. No variable substitution needed.
 
+**Skill design principle — inline vs. references:**
+- **Inline** in SKILL.md: content needed on every invocation (commands, classification tables, return format)
+- **`references/`**: content needed only on certain branches (fix loop policies, stack-specific adapters, error catalogs). The SKILL.md tells the agent WHEN to load each reference.
+- Never extract always-needed content to references — it adds tool calls without benefit.
+
 ---
 
 ### Step 8 — `.claude/QUICKSTART.md` (onboarding guide)
@@ -976,6 +999,22 @@ For any placeholder tokens, add a comment in the profile or tell the user to fil
 
 ---
 
+### Step 10 — IDE Adapters
+
+If IDE targets beyond Claude Code were detected in Phase 1 (e.g., GitHub Copilot, Cursor):
+
+1. For each additional IDE target detected:
+   a. Determine the adapter file path: `~/.claude/skills/crewkit-setup/adapters/{ide}.md`
+      - GitHub Copilot → `adapters/copilot.md`
+      - Cursor → `adapters/cursor.md`
+   b. If the adapter file does not exist: WARN the user ("Adapter file not found for [IDE] — skipping") and continue to the next IDE. Do not fail.
+   c. If the adapter file exists: read it completely, then MANDATORY: follow ALL instructions in it. The adapter reads scan data from `.crewkit/last-scan.md` and uses the already-generated Claude Code files (Steps 1-9) as its source.
+2. If no additional IDE targets were detected, skip this step entirely.
+
+**Note:** The adapters do NOT duplicate `.ai/memory/` — that directory is shared across all IDEs without transformation.
+
+---
+
 ## Final Report
 
 After all generation steps, run the **Completion Checklist** (at the bottom of this document). Then present the summary:
@@ -994,7 +1033,7 @@ After all generation steps, run the **Completion Checklist** (at the bottom of t
 - `.claude/napkin.md` — priorities board
 - `.claude/QUICKSTART.md` — onboarding guide
 - `.mcp.json` — [N] MCP servers
-- Validation: [N]/15 checks passed
+- Validation: [N]/17 checks passed
 
 ## Commands detected
 - Build: `[command]`
@@ -1046,5 +1085,7 @@ Before presenting the Final Report, go through EVERY item. Fix failures before r
 - [ ] `.crewkit/last-scan.md` — exists with full profile including Domain section
 - [ ] `.crewkit/scan-phase*.md` — all 4 phase files exist with content
 - [ ] No Portuguese in any generated file (only in user-facing output)
+- [ ] If Copilot target detected: `.github/copilot-instructions.md` exists and contains the project hard rules
+- [ ] If Cursor target detected: `.cursor/rules/project.md` exists and has `alwaysApply: true` frontmatter
 
-Report checklist results as: "Validation: X/15 checks passed." If any failed, list which ones and why.
+Report checklist results as: "Validation: X/17 checks passed." If any failed, list which ones and why.

package/skill/adapters/copilot.md

@@ -0,0 +1,239 @@
+# Adapter: GitHub Copilot
+
+This adapter is executed during Phase 7, Step 10 of `/crewkit-setup`.
+You are the AI. Follow every instruction in this file to generate GitHub Copilot-compatible context files.
+
+**Input:** Read `.crewkit/last-scan.md` for the project profile. The Claude Code files generated in Steps 1-9 are your source of truth.
+**Output:** Files under `.github/` that mirror the Claude Code setup for GitHub Copilot.
+
+---
+
+## Rules for this adapter
+
+1. All generated files MUST be in **English**.
+2. Do NOT duplicate `.ai/memory/` — it is shared between all IDEs. No transformation needed.
+3. `model:` frontmatter from `.claude/agents/*.md` is Claude Code-only — strip it.
+4. Skills are lossy when converted to Copilot prompts — extract workflow intent only, drop multi-agent orchestration mechanics.
+5. Create `.github/` subdirectories if they do not exist.
+
+---
+
+## Step C1 — `.github/copilot-instructions.md`
+
+**Source:** `CLAUDE.md`
+**Transformation:** Reformat for Copilot. Remove the Agent Discipline, Skills (slash commands), Architect Decision Gate, and Test Safety Loop sections — these are Claude Code-specific orchestration mechanics that do not apply to Copilot. Keep the hard rules, overview, memory loading instructions, and output format.
+
+**Expected output format:**
+```markdown
+# [PROJECT NAME] — Copilot Instructions
+
+## Overview
+[1-2 sentences from CLAUDE.md overview — what the project is, main stack]
+[Business domain: what it does, core entities, risk profile]
+
+**Stack:** [stacks]
+**Architecture:** [key patterns]
+
+---
+
+## Hard rules (apply to every response)
+
+[Numbered list — copy from CLAUDE.md hard rules verbatim. These are non-negotiable.]
+
+1. [Rule 1]
+2. [Rule 2]
+...
+
+Details for each rule → `.ai/memory/conventions.md`
+
+---
+
+## Project Memory (`.ai/memory/`)
+
+Load context on demand — do not load all files every time:
+
+| File | When to load |
+|------|-------------|
+| `architecture.md` | Always — modules, layers, dependencies |
+| `conventions.md` | Always — naming, patterns, anti-patterns |
+| `commands.md` | When running build/test/deploy |
+| `testing.md` | When creating or running tests |
+| `lessons-{domain}.md` | When working on that domain |
+
+---
+
+## Output Format
+
+Always return:
+- **Summary** — what was done
+- **Files changed** — list with brief description
+- **Tests** — pass/fail count (if tests were run)
+- **Risks / Next steps** — if any
+```
+
+**What to REMOVE from CLAUDE.md:**
+- `## Agent Discipline` section (orchestrator/worker model is Claude Code-only)
+- `## Skills (slash commands)` section (slash commands are Claude Code-only)
+- `## Architect Decision Gate` section
+- `## Test Safety Loop` section (keep the intent as a single sentence in the output format instead)
+
+**What to ADD:**
+- At the top, after the title: `> These instructions apply to all GitHub Copilot interactions in this repository.`
+- In the output format section: `> Always think step by step. Never report success with failing tests.`
+
+---
+
+## Step C2 — `.github/instructions/*.instructions.md`
+
+**Source:** `.claude/rules/*.md`
+**Transformation:** Convert frontmatter to Copilot format. Keep glob patterns and all rule content unchanged.
+
+Claude Code frontmatter format:
+```markdown
+---
+description: "Node.js coding rules — applied when editing src/**/*.{js,ts}"
+globs: "src/**/*.{js,ts}"
+---
+```
+
+Copilot instructions format:
+```markdown
+---
+applyTo: "src/**/*.{js,ts}"
+---
+# Node.js Rules
+
+[rule content unchanged]
+```
+
+**Mapping:**
+- `globs:` → `applyTo:`
+- `description:` → remove from frontmatter, use as the first `# heading` in the body instead
+- All rule content (body): copy verbatim
+
+**File naming:** `.claude/rules/dotnet.md` → `.github/instructions/dotnet.instructions.md`
+Strip any existing `.md` suffix and append `.instructions.md`.
+
+**Example — source `.claude/rules/node.md`:**
+```markdown
+---
+description: "Node.js coding rules — applied when editing src/**/*.{js,ts}"
+globs: "src/**/*.{js,ts}"
+---
+
+# Node.js Rules
+
+- Use async/await, not .then() chains
+- Validate all external input at the handler boundary
+```
+
+**Example — target `.github/instructions/node.instructions.md`:**
+```markdown
+---
+applyTo: "src/**/*.{js,ts}"
+---
+# Node.js Rules
+
+- Use async/await, not .then() chains
+- Validate all external input at the handler boundary
+```
+
+---
+
+## Step C3 — `.github/agents/*.agent.md`
+
+**Source:** `.claude/agents/*.md`
+**Transformation:** Strip `model:` frontmatter line. Keep `name:` and `description:`. Remove the `<!-- crewkit:context-start -->...<!-- crewkit:context-end -->` block — Copilot agents do not use this inline context injection. Keep the full agent role description and instructions.
+
+**Copilot agent frontmatter format:**
+```markdown
+---
+name: explorer
+description: "Read-only reconnaissance agent. Maps files, dependencies, and caller chains."
+tools:
+  - read_file
+  - list_directory
+  - search_files
+---
+```
+
+**`tools:` mapping — add if applicable:**
+| Agent | Suggested Copilot tools |
+|-------|------------------------|
+| explorer | `read_file`, `list_directory`, `search_files` |
+| architect | `read_file`, `search_files` |
+| coder | `read_file`, `create_file`, `replace_string_in_file` |
+| tester | `read_file`, `create_file`, `run_in_terminal` |
+| reviewer | `read_file`, `search_files` |
+
+**What to strip:**
+- `model:` line
+- The entire `<!-- crewkit:context-start -->...<!-- crewkit:context-end -->` block (inclusive)
+
+**File naming:** `.claude/agents/explorer.md` → `.github/agents/explorer.agent.md`
+
+---
+
+## Step C4 — `.github/prompts/*.prompt.md`
+
+**Source:** `.claude/skills/*/SKILL.md`
+**Transformation:** LOSSY. Extract the workflow intent as single-shot guidance. Drop multi-agent orchestration, agent routing, fix loops, and exit gates — Copilot prompts are single-turn, not multi-agent pipelines.
+
+**Extract:**
+- What the skill is for (description)
+- The key steps the user should follow or the AI should perform
+- Any output format requirements
+
+**Drop:**
+- `→ explorer → architect → coder → tester → reviewer` routing
+- Fix loop mechanics (`FAIL → fix → re-run`)
+- Exit gate conditions
+- Phase breakdown with parallel agents
+- Any reference to Claude Code slash commands (`/compact`, `/crewkit-setup`)
+
+**Example — source `full-workflow/SKILL.md` intent:**
+```
+Routes tasks through explore → implement → test → review agents.
+```
+
+**Example — target `.github/prompts/full-workflow.prompt.md`:**
+```markdown
+---
+name: full-workflow
+description: "Complete development workflow: explore, implement, test, and review."
+---
+# Full Workflow
+
+Use this prompt to complete a development task end-to-end.
+
+## Steps
+1. **Explore** — Read relevant files. Map dependencies and callers. Do not modify anything.
+2. **Implement** — Write the smallest correct diff. Follow all rules in `.ai/memory/conventions.md`.
+3. **Test** — Verify tests pass. Add tests if missing. Never report success with failing tests.
+4. **Review** — Check for bugs, security issues, and rule violations before finalizing.
+
+## Output
+- Summary of changes
+- Files changed with brief description
+- Test results (pass/fail count)
+- Any risks or follow-up needed
+```
+
+**File naming:** `full-workflow/SKILL.md` → `.github/prompts/full-workflow.prompt.md`
+Use the skill directory name as the prompt file name.
+
+---
+
+## Completion Checklist — Copilot Adapter
+
+Before reporting done, verify each item:
+
+- [ ] `.github/copilot-instructions.md` — exists, contains hard rules, does NOT contain Agent Discipline or slash command sections
+- [ ] `.github/instructions/` — one `.instructions.md` file per `.claude/rules/*.md` source file
+- [ ] `.github/instructions/*.instructions.md` — each has `applyTo:` frontmatter (not `globs:`)
+- [ ] `.github/agents/` — one `.agent.md` per `.claude/agents/*.md` source file
+- [ ] `.github/agents/*.agent.md` — no `model:` line, no `crewkit:context-start` block, has `tools:` frontmatter
+- [ ] `.github/prompts/` — one `.prompt.md` per `.claude/skills/*/SKILL.md` source file
+- [ ] `.github/prompts/*.prompt.md` — each has `name:` and `description:` frontmatter, no multi-agent routing language
+- [ ] `.ai/memory/` — NOT duplicated under `.github/` (shared, no copy needed)
+- [ ] No Portuguese in any generated file