crewkit 0.1.0 → 1.1.0

package/skill/adapters/cursor.md

@@ -0,0 +1,215 @@
+# Adapter: Cursor
+
+This adapter is executed during Phase 7, Step 10 of `/crewkit-setup`.
+You are the AI. Follow every instruction in this file to generate Cursor-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 `.cursor/rules/` and `AGENTS.md` at the project root.
+
+---
+
+## 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. Cursor has no equivalent for skills/prompts — skip `.claude/skills/` entirely.
+5. Create `.cursor/rules/` directory if it does not exist.
+
+---
+
+## Step U1 — `.cursor/rules/project.md`
+
+**Source:** `CLAUDE.md`
+**Transformation:** Reformat for Cursor. Add required frontmatter. Remove agent/skill/hook sections that are Claude Code-specific.
+
+**Required Cursor frontmatter:**
+```markdown
+---
+description: "Project rules"
+alwaysApply: true
+---
+```
+
+**Expected output format:**
+```markdown
+---
+description: "Project rules"
+alwaysApply: true
+---
+# [PROJECT NAME] — Project Rules
+
+## 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.]
+
+1. [Rule 1]
+2. [Rule 2]
+...
+
+Details for each rule → `.ai/memory/conventions.md`
+
+---
+
+## Project Memory (`.ai/memory/`)
+
+Load context on demand:
+
+| 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
+- `## Skills (slash commands)` section
+- `## Architect Decision Gate` section
+- `## Test Safety Loop` section
+
+---
+
+## Step U2 — `.cursor/rules/*.md`
+
+**Source:** `.claude/rules/*.md`
+**Transformation:** Convert frontmatter to Cursor 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}"
+---
+```
+
+Cursor frontmatter format:
+```markdown
+---
+description: "Node.js coding rules"
+globs: "src/**/*.{js,ts}"
+---
+```
+
+**Mapping:**
+- `globs:` → `globs:` (keep as-is — Cursor uses the same key)
+- `description:` → keep as-is, but shorten to the rule name without the "applied when editing..." suffix if present
+- Body: copy verbatim
+
+**File naming:** `.claude/rules/dotnet.md` → `.cursor/rules/dotnet.md`
+Keep the same filename — just place it under `.cursor/rules/`.
+
+**Example — source `.claude/rules/python.md`:**
+```markdown
+---
+description: "Python coding rules — applied when editing **/*.py"
+globs: "**/*.py"
+---
+
+# Python Rules
+
+- Use type hints on all function signatures
+- Validate input with Pydantic models at API boundaries
+```
+
+**Example — target `.cursor/rules/python.md`:**
+```markdown
+---
+description: "Python coding rules"
+globs: "**/*.py"
+---
+
+# Python Rules
+
+- Use type hints on all function signatures
+- Validate input with Pydantic models at API boundaries
+```
+
+---
+
+## Step U3 — `AGENTS.md` (project root)
+
+**Source:** All `.claude/agents/*.md` files
+**Transformation:** Concatenate all agents into a single markdown file with `##` sections. Strip `model:` frontmatter from each. Remove the `<!-- crewkit:context-start -->...<!-- crewkit:context-end -->` block from each agent. Keep the `name:` and `description:` from frontmatter and all agent instructions.
+
+**Output format:**
+```markdown
+# Agents
+
+This file describes the AI agents available in this project.
+Each agent has a specific role and scope. Invoke the appropriate agent for each task type.
+
+---
+
+## [Agent Name]
+
+> [description from frontmatter]
+
+[agent body — full instructions, stripped of model: and crewkit context block]
+
+---
+
+## [Agent Name 2]
+
+> [description from frontmatter]
+
+[agent body]
+
+---
+```
+
+**Agent order:** explorer, architect, coder, tester, reviewer (same order as in `.claude/agents/`).
+
+**What to strip from each agent:**
+- `model:` frontmatter line
+- `name:` frontmatter line (becomes the `## heading` instead)
+- `description:` frontmatter line (becomes the `> blockquote` instead)
+- The entire `<!-- crewkit:context-start -->...<!-- crewkit:context-end -->` block (inclusive)
+- The YAML frontmatter delimiters (`---`) — the content moves to the `##` section body
+
+**File location:** `AGENTS.md` at the project root (not under `.cursor/`).
+
+---
+
+## Step U4 — Skills
+
+**Source:** `.claude/skills/`
+**Action:** Skip entirely. Cursor has no equivalent concept for skills or prompts.
+
+Do NOT generate any file for this step. Log: "Cursor adapter: skills skipped (no Cursor equivalent)."
+
+---
+
+## Completion Checklist — Cursor Adapter
+
+Before reporting done, verify each item:
+
+- [ ] `.cursor/rules/project.md` — exists, has `alwaysApply: true` frontmatter, contains hard rules, does NOT contain Agent Discipline or slash command sections
+- [ ] `.cursor/rules/` — one `.md` file per `.claude/rules/*.md` source file (plus `project.md`)
+- [ ] `.cursor/rules/*.md` — each has `globs:` frontmatter matching the source rule file
+- [ ] `AGENTS.md` — exists at project root, has `##` section for each of the 5 agents
+- [ ] `AGENTS.md` — no `model:` lines, no `crewkit:context-start` blocks, no YAML frontmatter delimiters
+- [ ] `.ai/memory/` — NOT duplicated under `.cursor/` (shared, no copy needed)
+- [ ] `.claude/skills/` — NOT copied (no Cursor equivalent, intentionally skipped)
+- [ ] No Portuguese in any generated file

package/skill/templates/agents/coder.md

@@ -47,6 +47,7 @@ If your project uses `.claude/rules/` directory rules, they are loaded automatic
 - Do not create a new file when adding to an existing file achieves the same goal
 - Do not add `TODO` comments — either fix it now or leave it for the plan
 - **NEVER create test files** — test creation is the **tester agent's exclusive responsibility**
+- **NEVER mark phases, tasks, or features as completed** in `napkin.md`, `state.md`, or any memory/status file — only the orchestrator does this, and only after tester PASS + reviewer APPROVED
 
 ## Return Format
 

package/skill/templates/skills/dev-metrics/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: dev-metrics
+description: "Generate development metrics from git history — commit patterns, fix loop frequency, agent usage, file hotspots, and workflow efficiency."
+---
+
+Generate development metrics for: $ARGUMENTS
+
+If $ARGUMENTS is empty, analyze the last 90 days of git history.
+If $ARGUMENTS is a number (e.g. `30`), use that many days.
+If $ARGUMENTS is a branch or date range, scope to that.
+
+---
+
+## Steps
+
+### 1. Collect raw data
+
+Run all commands in parallel:
+
+```bash
+# Commit volume and cadence
+git log --oneline --since="90 days ago" --format="%ad %s" --date=short
+
+# File change frequency (hotspots)
+git log --since="90 days ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -30
+
+# Author breakdown (if multi-contributor)
+git shortlog -sn --since="90 days ago"
+
+# Fix/correction commits (heuristic: commit message contains fix, hotfix, correction, revert)
+git log --oneline --since="90 days ago" --grep="fix\|hotfix\|correction\|revert\|bugfix" -i
+
+# Merge commits (PR merges)
+git log --oneline --since="90 days ago" --merges
+```
+
+Adapt the `--since` window to match $ARGUMENTS if provided.
+
+### 2. Compute metrics
+
+From raw data, derive:
+
+#### Commit patterns
+| Metric | Value |
+|--------|-------|
+| Total commits | count |
+| Commits per week (avg) | count |
+| Peak activity day/week | date or range |
+| Fix/correction commit ratio | fix commits / total commits (%) |
+
+#### Fix loop frequency
+Estimate fix loop frequency by counting sequential commits on the same file within a 24h window.
+Flag any file with 3+ consecutive fix commits as a **fix loop hotspot**.
+
+| File | Fix loop count | Most recent |
+|------|---------------|-------------|
+| ... | ... | ... |
+
+#### File hotspots
+Top 10 most-changed files:
+
+| File | Change count | Risk level |
+|------|-------------|-----------|
+| ... | ... | HIGH if auth/tenant/migration, MEDIUM if handler/service, LOW otherwise |
+
+Apply risk classification using `.ai/memory/conventions.md` if present (read it).
+
+#### Workflow efficiency signals
+| Signal | Value | Health |
+|--------|-------|--------|
+| Fix commit ratio | X% | GREEN <15%, YELLOW 15-30%, RED >30% |
+| Revert count | N | GREEN 0, YELLOW 1-2, RED 3+ |
+| Hotfix commits | N | flag if >2 in window |
+| Files changed per commit (avg) | N | GREEN <5, YELLOW 5-10, RED >10 |
+
+#### Agent usage (if detectable from commit messages)
+If commit messages contain agent names (coder, tester, reviewer, architect, explorer),
+tally usage per agent. Otherwise, skip this section.
+
+### 3. Identify systemic risks
+
+Cross-reference hotspot files with risk classification:
+- If a HIGH-risk file (auth, tenant, billing, migration) is in the top 5 hotspots → flag as **systemic risk**
+- If fix commit ratio > 30% → flag as **process health concern**
+- If the same file appears in both hotspots and fix loops → flag as **instability candidate**
+
+### 4. Suggest improvements
+
+For each systemic risk or process health concern, propose one concrete action:
+- Do not propose vague items ("write more tests")
+- Each suggestion must reference a specific file, module, or metric
+
+---
+
+## Return Format
+
+```markdown
+---
+**Dev Metrics Report**
+**Period:** [date range]
+**Total commits analyzed:** N
+
+## Commit Patterns
+[table]
+
+## Fix Loop Frequency
+[table or "No fix loop hotspots detected"]
+
+## File Hotspots (top 10)
+[table]
+
+## Workflow Efficiency
+[table with GREEN/YELLOW/RED indicators]
+
+## Agent Usage
+[table or "Not detectable from commit messages"]
+
+## Systemic Risks
+[list or "None identified"]
+
+## Suggested Improvements
+[numbered list, max 5, concrete and actionable]
+---
+```
+
+Keep the report structured and scannable. Do not include raw git output.

package/skill/templates/skills/full-workflow/SKILL.md

@@ -121,81 +121,11 @@ If a durable lesson was learned, append to the appropriate `lessons-{domain}.md`
 
 ---
 
-# Part 2 — Operational Policies
-
-## Exit gate
-
-**HARD BLOCK: No task is complete without reviewer APPROVED (clean).**
-
-- Tester PASS alone is **not sufficient**
-- Reviewer APPROVED is **mandatory** before Summarize
-- **APPROVED with IMPORTANT+ findings is NOT clean.** Fix, then re-run tester + reviewer.
-- Both must be clean (PASS + APPROVED without IMPORTANT+ findings) before Summarize.
-
-## Findings consolidation
-
-After tester and reviewer finish:
-
-1. **Collect** results from both
-2. **Classify:** Tester = PASS/FAIL. Reviewer = APPROVED/NEEDS_CHANGES
-3. **Deduplicate** — same file + same concern → keep higher severity
-4. **APPROVED with IMPORTANT+ findings** = treat as NEEDS_CHANGES
-5. **Decision matrix:**
-
-| Tester | Reviewer | Action |
-|--------|----------|--------|
-| PASS | APPROVED (clean) | Done → Summarize |
-| PASS | APPROVED with IMPORTANT+ | Fix loop |
-| PASS | NEEDS_CHANGES | Fix loop (reviewer findings) |
-| FAIL | APPROVED | Fix loop (test failures) |
-| FAIL | NEEDS_CHANGES | Fix loop (merge into ONE list for coder) |
-
-When both fail, call coder **once** with the merged list.
-
-## Fix loop
-
-1. **Fix:**
-   - Risk **HIGH**: all fixes through **coder** — never auto-fix
-   - Risk LOW/MEDIUM: `auto_fixable: yes` → orchestrator applies directly. Else → coder
-   - When fix changes an exception type or interface → instruct coder to grep for all test doubles/fakes
-2. **Revalidate in parallel** (tester fix-loop mode + reviewer)
-3. Consolidate again
-4. Exit when PASS + APPROVED
-5. **Max 5 iterations** — then STOP and report to user.
-
-**MINOR findings** do not trigger fix loop alone.
-
-**Tester time budget:** if the tester reports pre-existing failures unrelated to the current task, the orchestrator must NOT ask the tester to fix them. Note them for a separate task and proceed.
-
-## Test creation rule
-
-**Every behavioral change must be validated by tests.** The tester creates them automatically.
-
-- New feature with logic → unit tests + integration when applicable
-- Bug fix → test that reproduces the bug + verifies the fix
-- Refactor with preserved behavior → existing tests are sufficient
-- Cosmetic/text/DTO change without logic → build + review is sufficient
-
-## HIGH risk rules
-
-- Never auto-fix — all through coder
-- Full test suite on every revalidation
-- Reviewer always mandatory
-- Architect mandatory if any design decision is open
-
-## Stop conditions
-
-STOP and escalate when:
-- Build doesn't stabilize after 2 corrections
-- Reviewer flags an architectural problem
-- Tester finds widespread failures outside task scope
-- Root cause unclear after 1 fix loop
-- Affected files grow beyond plan
-- SMALL/MEDIUM reveals structural impact
+> **Operational policies** (exit gate, fix loop, findings consolidation, stop conditions): load `references/operational-policies.md` when entering consolidation or fix loop.
 
 ---
 
-# Part 3 — Stack Configuration
+# Part 2 — Stack Configuration
 
 The orchestrator must tell subagents which build/test commands to use. Read `.ai/memory/commands.md` at the start and use the correct commands for each stack.
 

package/skill/templates/skills/full-workflow/references/operational-policies.md

@@ -0,0 +1,85 @@
+# Full-Workflow — Operational Policies
+
+Referenced by `SKILL.md`. Load when entering consolidation, fix loop, or stop conditions.
+
+---
+
+## Exit gate
+
+**HARD BLOCK: No task is complete without reviewer APPROVED (clean).**
+
+- Tester PASS alone is **not sufficient**
+- Reviewer APPROVED is **mandatory** before Summarize
+- **APPROVED with IMPORTANT+ findings is NOT clean.** Fix, then re-run tester + reviewer.
+- Both must be clean (PASS + APPROVED without IMPORTANT+ findings) before Summarize.
+
+---
+
+## Findings consolidation
+
+After tester and reviewer finish:
+
+1. **Collect** results from both
+2. **Classify:** Tester = PASS/FAIL. Reviewer = APPROVED/NEEDS_CHANGES
+3. **Deduplicate** — same file + same concern → keep higher severity
+4. **APPROVED with IMPORTANT+ findings** = treat as NEEDS_CHANGES
+5. **Decision matrix:**
+
+| Tester | Reviewer | Action |
+|--------|----------|--------|
+| PASS | APPROVED (clean) | Done → Summarize |
+| PASS | APPROVED with IMPORTANT+ | Fix loop |
+| PASS | NEEDS_CHANGES | Fix loop (reviewer findings) |
+| FAIL | APPROVED | Fix loop (test failures) |
+| FAIL | NEEDS_CHANGES | Fix loop (merge into ONE list for coder) |
+
+When both fail, call coder **once** with the merged list.
+
+---
+
+## Fix loop
+
+1. **Fix:**
+   - Risk **HIGH**: all fixes through **coder** — never auto-fix
+   - Risk LOW/MEDIUM: `auto_fixable: yes` → orchestrator applies directly. Else → coder
+   - When fix changes an exception type or interface → instruct coder to grep for all test doubles/fakes
+2. **Revalidate in parallel** (tester fix-loop mode + reviewer)
+3. Consolidate again
+4. Exit when PASS + APPROVED
+5. **Max 5 iterations** — then STOP and report to user.
+
+**MINOR findings** do not trigger fix loop alone.
+
+**Tester time budget:** if the tester reports pre-existing failures unrelated to the current task, the orchestrator must NOT ask the tester to fix them. Note them for a separate task and proceed.
+
+---
+
+## Test creation rule
+
+**Every behavioral change must be validated by tests.** The tester creates them automatically.
+
+- New feature with logic → unit tests + integration when applicable
+- Bug fix → test that reproduces the bug + verifies the fix
+- Refactor with preserved behavior → existing tests are sufficient
+- Cosmetic/text/DTO change without logic → build + review is sufficient
+
+---
+
+## HIGH risk rules
+
+- Never auto-fix — all through coder
+- Full test suite on every revalidation
+- Reviewer always mandatory
+- Architect mandatory if any design decision is open
+
+---
+
+## Stop conditions
+
+STOP and escalate when:
+- Build doesn't stabilize after 2 corrections
+- Reviewer flags an architectural problem
+- Tester finds widespread failures outside task scope
+- Root cause unclear after 1 fix loop
+- Affected files grow beyond plan
+- SMALL/MEDIUM reveals structural impact

package/skill/templates/skills/impact/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: impact
+description: "Analyze blast radius of changing a file, handler, entity, or module. Maps callers, tests, endpoints, and UI pages affected."
+---
+
+Analyze blast radius of: $ARGUMENTS
+
+$ARGUMENTS must be a file path, handler name, entity name, module name, or endpoint.
+Examples: `src/Orders/OrderHandler.cs`, `OrderEntity`, `POST /api/orders`, `Orders module`
+
+---
+
+## When to use
+
+Use before starting any MEDIUM or LARGE task to understand the full scope of change.
+Use before `/explore-and-plan` when the target is already known but blast radius is uncertain.
+Use after a production incident to understand what else might be affected by the fix.
+
+---
+
+## Steps
+
+### 1. Identify the target
+
+From $ARGUMENTS, determine:
+- **Target type:** file / class / handler / entity / endpoint / module
+- **Target location:** resolve to exact file path(s) if not already a path
+- **Stack:** infer from path extension and `.ai/memory/architecture.md`
+
+Read `.ai/memory/architecture.md` and `.ai/memory/conventions.md` to understand layer rules
+and naming conventions before searching.
+
+### 2. Map direct callers
+
+Search for all direct references to the target:
+
+```bash
+# Search for imports, usages, and references
+# Adapt search patterns to the detected stack:
+# - .NET: class name, interface name, constructor injection, handler registration
+# - Node.js: require/import of the file, function call sites
+# - Blazor: component references, @inject, @page routes, event handlers
+# - SQL/migrations: table name, column name in queries and seeders
+```
+
+Build the direct caller list:
+
+| File | Reference type | Layer |
+|------|---------------|-------|
+| ... | import / call / inject / inherit | controller / service / handler / UI / test |
+
+### 3. Map transitive impact
+
+For each direct caller, check if it is itself called by other files:
+- Go one level deeper if the direct caller is an interface, base class, or shared service
+- Stop at two levels unless the target is a core shared abstraction (entity, base class, shared interface)
+- Flag if the dependency graph is too wide to enumerate (>20 unique callers at any level)
+
+### 4. Map tests
+
+Find all test files that directly or indirectly test the target:
+
+```bash
+# Search test directories for the target name, class name, or endpoint path
+# Look for test doubles (mocks, fakes, stubs) of the target
+```
+
+| Test file | Tests what | Has mock/fake of target? |
+|-----------|-----------|--------------------------|
+| ... | ... | yes / no |
+
+Flag any test file that uses a mock/fake of the target — changing the target's interface or
+exception types will require updating those fakes.
+
+### 5. Map API endpoints and UI pages
+
+If the target is a handler, service, or entity:
+- Find which API endpoints call it (controller/route → handler)
+- Find which UI pages or components consume those endpoints (if frontend source is available)
+
+| Endpoint | Method | UI page/component | Consumer type |
+|----------|--------|------------------|---------------|
+| ... | ... | ... | internal / public API |
+
+Mark endpoints as **public API** if they are exposed externally — changes to those have higher blast radius.
+
+### 6. Classify blast radius
+
+| Dimension | Count | Assessment |
+|-----------|-------|-----------|
+| Direct callers | N | — |
+| Transitive callers | N | — |
+| Test files affected | N | — |
+| API endpoints affected | N | — |
+| UI pages affected | N | — |
+| Public API contracts affected | N | HIGH risk if >0 |
+| Auth/tenant code affected | yes/no | HIGH risk if yes |
+| DB schema affected | yes/no | HIGH risk if yes |
+
+**Overall blast radius:**
+- **LOW** — 1-2 files, same layer, no public API, no auth/schema
+- **MEDIUM** — 3-7 files, cross-layer, no public API change
+- **HIGH** — 8+ files, or public API, or auth/tenant, or DB schema change
+
+### 7. Identify change categories
+
+Classify what types of changes to the target would cause breakage vs. safe changes:
+
+| Change type | Breakage risk | Affected consumers |
+|-------------|--------------|-------------------|
+| Add new field (non-breaking) | LOW | none |
+| Rename field or method | HIGH | all callers + test fakes |
+| Change return type | HIGH | all callers |
+| Change exception thrown | MEDIUM | test fakes + callers that catch |
+| Add required parameter | HIGH | all call sites |
+| Add optional parameter | LOW | none |
+| Split into two classes | HIGH | all callers + DI registrations |
+| Change DB column | HIGH | queries + migrations |
+
+---
+
+## Return Format
+
+```markdown
+---
+**Impact Analysis: [target name]**
+**Target type:** [file / class / handler / entity / endpoint / module]
+**Stack:** [detected]
+
+## Direct Callers
+[table from Step 2]
+
+## Transitive Impact
+[table or "None — direct callers are leaf nodes"]
+
+## Tests Affected
+[table from Step 4]
+[Flag: "N test files use a mock/fake of this target — update them if interface changes"]
+
+## Endpoints and UI Pages
+[table from Step 5, or "Not applicable"]
+
+## Blast Radius Summary
+[table from Step 6]
+
+**Blast radius: LOW / MEDIUM / HIGH**
+
+## Safe vs. Breaking Changes
+[table from Step 7]
+
+## Recommendation
+[1-3 sentences: what to do before making this change, and what to watch for]
+---
+```
+
+If $ARGUMENTS does not resolve to a known file or name, ask for clarification before proceeding.
+Do not guess at the target.