code-ai-installer 2.5.0 → 3.0.0

package/locales/en/.agents/skills/karpathy-guidelines/SKILL.md

@@ -1,325 +0,0 @@
----
-name: karpathy-guidelines
-description: Behavioral guidelines to reduce common LLM mistakes across all tasks — code, design, analytics, product. Apply always.
-license: MIT
-source: https://x.com/karpathy/status/2015883857489522876
----
-
-# Karpathy Guidelines
-
-Behavioral guidelines to reduce common LLM mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876).
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
-
----
-
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-### Example: Hidden Assumptions
-
-**Request:** "Add a feature to export user data"
-
-❌ **What LLMs do** — silently assume format, fields, scope:
-
-```python
-def export_users(format='json'):
-    users = User.query.all()
-    with open('users.json', 'w') as f:
-        json.dump([u.to_dict() for u in users], f)
-    return f"Exported {len(users)} users"
-```
-
-✅ **What should happen** — surface assumptions and ask:
-
-```
-Before implementing, I need to clarify:
-
-1. Scope: Export all users or filtered subset? (privacy implications)
-2. Format: "export" — download file, background job, or API endpoint?
-3. Fields: Which user fields? (some might be sensitive)
-4. Volume: How many users? (affects approach)
-
-What's your preference?
-```
-
-### Example: Multiple Interpretations
-
-**Request:** "Make the search faster"
-
-❌ **What LLMs do** — silently pick one interpretation and write 200 lines of optimization.
-
-✅ **What should happen:**
-
-```
-"Make the search faster" could mean:
-
-1. Faster response time (< 100ms instead of 500ms)
-   → database indexes, cache | ~2h
-
-2. Handle more concurrent searches (throughput)
-   → async/await, connection pooling | ~4h
-
-3. Faster perceived speed (UX)
-   → show partial results immediately | ~3h
-
-Current search takes ~500ms. Which aspect matters most?
-```
-
----
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-### Example: Over-abstraction
-
-**Request:** "Add a function to calculate discount"
-
-❌ **What LLMs do** — Strategy pattern, ABC, dataclass, configurator:
-
-```python
-class DiscountStrategy(ABC):
-    @abstractmethod
-    def calculate(self, amount: float) -> float: pass
-
-class PercentageDiscount(DiscountStrategy):
-    def __init__(self, percentage: float):
-        self.percentage = percentage
-    def calculate(self, amount: float) -> float:
-        return amount * (self.percentage / 100)
-
-@dataclass
-class DiscountConfig:
-    strategy: DiscountStrategy
-    min_purchase: float = 0.0
-    max_discount: float = float('inf')
-
-# 40 more lines to use one formula
-```
-
-✅ **What should happen:**
-
-```python
-def calculate_discount(amount: float, percent: float) -> float:
-    """Calculate discount amount. percent should be 0-100."""
-    return amount * (percent / 100)
-```
-
-When to add complexity: only when multiple discount types are actually needed.
-
-### Example: Speculative Features
-
-**Request:** "Save user preferences to database"
-
-❌ **What LLMs do** — cache, validator, merge flag, notifications:
-
-```python
-class PreferenceManager:
-    def __init__(self, db, cache=None, validator=None):
-        ...
-    def save(self, user_id, prefs, merge=True, validate=True, notify=False):
-        # 50 lines for what could be 3
-```
-
-✅ **What should happen:**
-
-```python
-def save_preferences(db, user_id: int, preferences: dict):
-    db.execute(
-        "UPDATE users SET preferences = ? WHERE id = ?",
-        (json.dumps(preferences), user_id)
-    )
-```
-
-Add caching, validation, merging later — only when actually needed.
-
----
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-**The test:** Every changed line should trace directly to the user's request.
-
-### Example: Drive-by Refactoring
-
-**Request:** "Fix the bug where empty emails crash the validator"
-
-❌ **What LLMs do** — improve email validation beyond the bug fix, add username validation, change comment style, add docstring.
-
-✅ **What should happen — only the lines that fix empty email:**
-
-```diff
-  def validate_user(user_data):
-      # Check email format
--     if not user_data.get('email'):
-+     email = user_data.get('email', '')
-+     if not email or not email.strip():
-          raise ValueError("Email required")
-
-      # Basic email validation
--     if '@' not in user_data['email']:
-+     if '@' not in email:
-          raise ValueError("Invalid email")
-
-      # Check username  ← untouched, not in scope
-      if not user_data.get('username'):
-          raise ValueError("Username required")
-
-      return True
-```
-
-### Example: Style Drift
-
-**Request:** "Add logging to the upload function"
-
-❌ **What LLMs do** — add type hints, change single quotes to double quotes, add docstring, reformat whitespace.
-
-✅ **What should happen — match existing style:**
-
-```diff
-+ import logging
-+
-+ logger = logging.getLogger(__name__)
-+
-  def upload_file(file_path, destination):
-+     logger.info(f'Starting upload: {file_path}')
-      try:
-          with open(file_path, 'rb') as f:
-              data = f.read()
-
-          response = requests.post(destination, files={'file': data})
-
-          if response.status_code == 200:
-+             logger.info(f'Upload successful: {file_path}')
-              return True
-          else:
-+             logger.error(f'Upload failed: {file_path}, status={response.status_code}')
-              return False
-      except Exception as e:
--         print(f"Error: {e}")
-+         logger.exception(f'Upload error: {file_path}')
-          return False
-```
-
-Matched: single quotes, no type hints, existing boolean pattern, spacing style.
-
----
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-### Example: Incremental with Verification
-
-**Request:** "Add rate limiting to the API"
-
-❌ **What LLMs do** — implement Redis, multiple strategies, config system, and monitoring in one 300-line commit with no clear verification steps.
-
-✅ **What should happen:**
-
-```
-Plan for rate limiting:
-
-1. Basic in-memory rate limiting (single endpoint)
-   Verify: 100 requests → first 10 succeed, rest get 429
-
-2. Extract to middleware (all endpoints)
-   Verify: existing endpoint tests still pass
-
-3. Redis backend (multi-server)
-   Verify: rate limit persists across app restarts
-
-4. Configuration (rates per endpoint)
-   Verify: /search allows 10/min, /users allows 100/min
-
-Start with step 1?
-```
-
-### Example: Reproduce Before Fixing
-
-**Request:** "The sorting breaks when there are duplicate scores"
-
-❌ **What LLMs do** — immediately change sort logic without reproducing the bug.
-
-✅ **What should happen:**
-
-```python
-# 1. First, write a test that reproduces the bug
-def test_sort_with_duplicate_scores():
-    scores = [
-        {'name': 'Alice', 'score': 100},
-        {'name': 'Bob', 'score': 100},
-        {'name': 'Charlie', 'score': 90},
-    ]
-    result = sort_scores(scores)
-    assert result[0]['score'] == 100
-    assert result[2]['score'] == 90
-    assert result[0]['name'] < result[1]['name']  # stable sort
-
-# Verify: test fails → bug reproduced
-
-# 2. Now fix with stable sort
-def sort_scores(scores):
-    return sorted(scores, key=lambda x: (-x['score'], x['name']))
-
-# Verify: test passes
-```
-
----
-
-## Anti-Patterns Summary
-
-| Principle | Anti-Pattern | Fix |
-|---|---|---|
-| Think Before Coding | Silently assumes file format, fields, scope | List assumptions explicitly, ask for clarification |
-| Simplicity First | Strategy pattern for single discount calculation | One function until complexity is actually needed |
-| Surgical Changes | Reformats quotes, adds type hints while fixing bug | Only change lines that fix the reported issue |
-| Goal-Driven | "I'll review and improve the code" | "Write test for bug X → make it pass → verify no regressions" |
-
-## Key Insight
-
-The "overcomplicated" examples aren't obviously wrong — they follow design patterns and best practices. The problem is **timing**: they add complexity before it's needed.
-
-**Good code is code that solves today's problem simply, not tomorrow's problem prematurely.**

package/locales/en/.agents/skills/karpathy-guidelines/agents/claude.json

@@ -1,22 +0,0 @@
-{
-  "name": "karpathy-guidelines",
-  "display_name": "Karpathy Guidelines",
-  "description": "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution.",
-  "default_prompt": "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design.",
-  "triggers": [
-    "karpathy-guidelines",
-    "karpathy",
-    "Karpathy Guidelines",
-    "think before coding",
-    "simplicity first",
-    "surgical changes",
-    "goal-driven execution"
-  ],
-  "capabilities": [
-    "quality",
-    "guidelines",
-    "best-practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/karpathy-guidelines/agents/copilot.json

@@ -1,22 +0,0 @@
-{
-  "name": "karpathy-guidelines",
-  "display_name": "Karpathy Guidelines",
-  "description": "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution.",
-  "default_prompt": "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design.",
-  "triggers": [
-    "karpathy-guidelines",
-    "karpathy",
-    "Karpathy Guidelines",
-    "think before coding",
-    "simplicity first",
-    "surgical changes",
-    "goal-driven execution"
-  ],
-  "capabilities": [
-    "quality",
-    "guidelines",
-    "best-practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/karpathy-guidelines/agents/gemini.json

@@ -1,22 +0,0 @@
-{
-  "name": "karpathy-guidelines",
-  "display_name": "Karpathy Guidelines",
-  "description": "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution.",
-  "default_prompt": "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design.",
-  "triggers": [
-    "karpathy-guidelines",
-    "karpathy",
-    "Karpathy Guidelines",
-    "think before coding",
-    "simplicity first",
-    "surgical changes",
-    "goal-driven execution"
-  ],
-  "capabilities": [
-    "quality",
-    "guidelines",
-    "best-practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/karpathy-guidelines/agents/kimi.yaml

@@ -1,18 +0,0 @@
-name: "karpathy-guidelines"
-display_name: "Karpathy Guidelines"
-description: "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution."
-default_prompt: "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design."
-triggers:
-  - "karpathy-guidelines"
-  - "karpathy"
-  - "Karpathy Guidelines"
-  - "think before coding"
-  - "simplicity first"
-  - "surgical changes"
-  - "goal-driven execution"
-capabilities:
-  - "quality"
-  - "guidelines"
-  - "best-practices"
-tools: []
-implicit_invocation: true

package/locales/en/.agents/skills/karpathy-guidelines/agents/openai.yaml

@@ -1,8 +0,0 @@
-interface:
-  display_name: "Karpathy Guidelines"
-  short_description: "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution."
-  default_prompt: "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design."
-dependencies:
-  tools: []
-policy:
-  allow_implicit_invocation: true

package/locales/en/.agents/skills/karpathy-guidelines/agents/qwen.json

@@ -1,22 +0,0 @@
-{
-  "name": "karpathy-guidelines",
-  "display_name": "Karpathy Guidelines",
-  "description": "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution.",
-  "default_prompt": "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design.",
-  "triggers": [
-    "karpathy-guidelines",
-    "karpathy",
-    "Karpathy Guidelines",
-    "think before coding",
-    "simplicity first",
-    "surgical changes",
-    "goal-driven execution"
-  ],
-  "capabilities": [
-    "quality",
-    "guidelines",
-    "best-practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/karpathy-guidelines/agents/skill.yaml

@@ -1,25 +0,0 @@
-version: 1
-name: "karpathy-guidelines"
-display_name: "Karpathy Guidelines"
-description: "Behavioral guidelines to reduce common LLM mistakes — think before coding, simplicity first, surgical changes, goal-driven execution."
-default_prompt: "Use $karpathy-guidelines when the task requires quality discipline: writing code, reviewing, refactoring, analysis, or design."
-triggers:
-  - "karpathy-guidelines"
-  - "karpathy"
-  - "Karpathy Guidelines"
-  - "think before coding"
-  - "simplicity first"
-  - "surgical changes"
-  - "goal-driven execution"
-capabilities:
-  - "quality"
-  - "guidelines"
-  - "best-practices"
-tools: []
-invocation:
-  explicit: true
-  implicit: true
-localization:
-  default_locale: "en"
-  available_locales:
-    - "en"

package/locales/en/.agents/skills/memory/SKILL.md

@@ -1,219 +0,0 @@
----
-name: memory
-description: Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions.
----
-
-# Skill: Memory (context between sessions)
-
-Do not lose context: decisions, contracts, requirements, results.
-
-**Sections:**
-1. [Workflow](#1-workflow)
-2. [What to Store](#2-what-to-store)
-3. [Storage Strategy](#3-storage-strategy)
-4. [Retrieval Patterns](#4-retrieval-patterns)
-5. [Conflict Resolution](#5-conflict-resolution)
-6. [Session Handoff](#6-session-handoff)
-
----
-
-## 1. Workflow
-
-```
-1. During work:
-   ├── Save decisions as they happen (ADR, assumptions)
-   ├── Save deliverables (PRD, specs, contracts)
-   └── Save issues/findings (bugs, review findings)
-
-2. Before delegating to agent:
-   ├── Retrieve relevant context for task
-   ├── Include in Context Pack (max 5-15 items)
-   └── Check for conflicts with previous decisions
-
-3. Between sessions:
-   ├── Session handoff summary (section 6)
-   └── Update docs/ with current state
-```
-
----
-
-## 2. What to Store
-
-### By priority
-
-| Priority | What | Where | When to update |
-|----------|------|-------|---------------|
-| 🔴 **Critical** | PRD | `docs/prd.md` | On change + version |
-| 🔴 **Critical** | Architecture + ADR | `docs/architecture.md`, `docs/adr/` | On architecture decision |
-| 🔴 **Critical** | API Contracts | `docs/api-contracts.md` | On API change |
-| 🟠 **Important** | UX Spec | `docs/ux-spec.md` | On UX change |
-| 🟠 **Important** | Data Model | `docs/data-model.md` | On schema change |
-| 🟠 **Important** | Review findings (P0) | Review report artifacts | After each review |
-| 🟠 **Important** | Test results | Test report artifacts | After each test run |
-| 🟠 **Important** | Backlog + Board | `docs/backlog.md`, board in messages | After each gate |
-| 🟡 **Useful** | Design decisions | Design intake report | When design changes |
-| 🟡 **Useful** | Session summaries | Session handoff docs | End of each session |
-
----
-
-## 3. Storage Strategy
-
-### Filesystem-based (primary)
-
-```
-docs/
-├── prd.md                          # PRD (versioned)
-├── ux-spec.md                      # UX Spec
-├── architecture.md                 # Architecture Doc
-├── api-contracts.md                # API Contracts
-├── data-model.md                   # Data Model
-├── backlog.md                      # Product Backlog
-├── adr/
-│   ├── ADR-001-database-choice.md  # Architecture Decision Records
-│   ├── ADR-002-design-system.md
-│   └── ...
-├── reviews/
-│   ├── rev-01-settings-api.md      # Review reports
-│   └── ...
-├── tests/
-│   ├── test-plan-v1.md             # Test plans
-│   ├── test-report-iter1.md        # Test reports
-│   └── ...
-└── sessions/
-    ├── session-1-handoff.md        # Session summaries
-    └── ...
-```
-
-### Naming conventions
-
-| Type | Format | Example |
-|------|--------|---------|
-| ADR | `ADR-NNN-short-title.md` | `ADR-001-mongodb-choice.md` |
-| Review | `rev-NN-scope.md` | `rev-01-settings-api.md` |
-| Test report | `test-report-iterN.md` | `test-report-iter1.md` |
-| Session | `session-N-handoff.md` | `session-3-handoff.md` |
-
----
-
-## 4. Retrieval Patterns
-
-### Before delegating task to agent
-
-```
-1. Identify scope of task (e.g., "implement settings API")
-
-2. Retrieve relevant documents:
-   ├── PRD → user stories for this feature
-   ├── UX Spec → screen specs for this feature
-   ├── API Contracts → endpoints for this feature
-   ├── Architecture → layer rules, tech decisions
-   ├── ADRs → relevant decisions
-   └── Previous review findings → avoid re-introducing issues
-
-3. Include in Context Pack:
-   ├── MAX 5-15 items (focus on relevant)
-   ├── Full paths to files
-   └── Key excerpts if files are long
-```
-
-### Retrieval commands
-
-```bash
-# Find relevant documents
-find_by_name: Pattern="*.md" SearchDirectory="docs/"
-
-# Find ADRs
-find_by_name: Pattern="ADR-*" SearchDirectory="docs/adr/"
-
-# Search for specific topic
-grep_search: Query="settings" SearchPath="docs/"
-
-# Find previous review findings
-grep_search: Query="P0" SearchPath="docs/reviews/"
-```
-
----
-
-## 5. Conflict Resolution
-
-### When new proposal contradicts existing decision
-
-```markdown
-### ⚠️ CONFLICT DETECTED
-
-**Topic:** <what's in conflict>
-**Existing decision:** ADR-001 — <summary> (date: YYYY-MM-DD)
-**New proposal:** <what's being proposed>
-
-**Impact if changed:**
-- <downstream effects on architecture>
-- <downstream effects on existing code>
-- <downstream effects on contracts>
-
-**Options:**
-1. Keep existing decision (no change)
-2. Update decision (create new ADR, update affected docs)
-3. Defer to user for decision
-
-**Recommendation:** <1/2/3 with rationale>
-```
-
-### Rules
-
-| Rule | Explanation |
-|------|------------|
-| ADR decisions are immutable without new ADR | Can't silently change |
-| API contracts require version bump | Breaking changes need explicit approval |
-| PRD scope changes need user approval | Only user can expand/reduce scope |
-| UX Spec changes need UX re-review | Design changes cascade to dev |
-
----
-
-## 6. Session Handoff
-
-### At end of session, create summary:
-
-```markdown
-# Session N Handoff
-
-**Date:** YYYY-MM-DD
-**Duration:** ~Xh
-**Conversation ID:** <id>
-
-## What was accomplished
-- [x] <completed task 1>
-- [x] <completed task 2>
-- [ ] <started but not finished>
-
-## Current state
-| Gate | Status | Notes |
-|------|:------:|-------|
-| PM | ☑ | PRD approved |
-| UX | ☑ | UX Spec approved |
-| ARCH | ☑ | Architecture approved |
-| DEV | ⏳ | Settings API done, UI in progress |
-| REV | ☐ | — |
-
-## Key artifacts updated
-| Artifact | Path | Change |
-|----------|------|--------|
-| PRD | docs/prd.md | No change |
-| Settings schema | server/models/Settings.js | Created |
-
-## Blockers / Open items
-- <blocker 1>
-- <open question 1>
-
-## Next session should
-1. Continue DEV: Settings UI
-2. Then: REV gate
-3. Then: OPS + TEST
-```
-
----
-
-## See also
-- `$handoff` — context pack for delegating
-- `$board` — project board (tracks progress)
-- `$adr-log` — architecture decision records
-- `$gates` — gate definitions