adevkit 0.1.0__py3-none-any.whl

devkit/scaffold/__init__.py

@@ -0,0 +1,16 @@
+from .agents_md import generate_agents_md
+from .prd_md import generate_prd_template, import_prd_file
+from .git_setup import setup_git_repository
+from .env_setup import setup_python_environment, setup_node_environment, setup_dotenv_file
+from .vscode_setup import setup_vscode_config
+
+__all__ = [
+    "generate_agents_md",
+    "generate_prd_template",
+    "import_prd_file",
+    "setup_git_repository",
+    "setup_python_environment",
+    "setup_node_environment",
+    "setup_dotenv_file",
+    "setup_vscode_config",
+]

devkit/scaffold/agents_md.py

@@ -0,0 +1,152 @@
+from pathlib import Path
+from typing import List
+from ..skills.catalog import AVAILABLE_SKILLS
+
+def generate_agents_md(
+    target_dir: Path,
+    project_name: str,
+    template_id: str,
+    installed_skills: List[str],
+) -> Path:
+    """Generate a comprehensive AGENTS.md guide tailored to the project stack and skills."""
+    target_dir = Path(target_dir)
+    file_path = target_dir / "AGENTS.md"
+
+    # Stack-specific run commands
+    commands_section = ""
+    if "python" in template_id or "ai_agents" in template_id:
+        commands_section = """### Environment & Commands
+- **Activate Virtual Environment**: `.\\.venv\\Scripts\\activate` (Windows) or `source .venv/bin/activate` (POSIX)
+- **Run API Server**: `python -m app.main` or `uvicorn app.main:app --reload`
+- **Run Tests**: `pytest tests/ -v`
+- **Install Dependencies**: `pip install -r requirements.txt`
+"""
+    elif "nextjs" in template_id or "saas" in template_id:
+        commands_section = """### Environment & Commands
+- **Dev Server**: `npm run dev` (or `pnpm dev` / `bun dev`)
+- **Build Production**: `npm run build`
+- **Lint**: `npm run lint`
+- **Typecheck**: `npx tsc --noEmit`
+"""
+    elif "vite" in template_id or "design_system" in template_id:
+        commands_section = """### Environment & Commands
+- **Dev Server**: `npm run dev`
+- **Build Production**: `npm run build`
+- **Preview Build**: `npm run preview`
+"""
+    elif "content" in template_id or "astro" in template_id:
+        commands_section = """### Environment & Commands
+- **Dev Server**: `npm run dev`
+- **Build Production**: `npm run build`
+- **Preview**: `npm run preview`
+"""
+    elif "expo_fullstack" in template_id:
+        commands_section = """### Environment & Commands
+- **Mobile Dev**: `npm run dev:mobile`
+- **Backend Dev**: `npm run dev:backend`
+"""
+    elif "expo" in template_id:
+        commands_section = """### Environment & Commands
+- **Start Expo Metro**: `npm start`
+- **Run Android**: `npm run android`
+- **Run iOS**: `npm run ios`
+- **Run Web**: `npm run web`
+"""
+    else:
+        commands_section = """### Environment & Commands
+- Inspect `package.json`, `pyproject.toml`, or `requirements.txt` for available build and run scripts.
+"""
+
+    # Skills descriptions
+    skills_lines = []
+    has_design_skills = False
+    has_vercel_skills = False
+    has_ponytail_skills = False
+
+    for sid in installed_skills:
+        info = AVAILABLE_SKILLS.get(sid)
+        desc = info.description if info else "Curated skill"
+        name = info.name if info else sid
+        skills_lines.append(f"- **`{sid}`** ({name}): {desc}")
+
+        if sid in ["impeccable", "design-taste-frontend", "ui-ux-pro-max", "emil-design-eng", "animate", "design", "design-system"]:
+            has_design_skills = True
+        if "vercel" in sid:
+            has_vercel_skills = True
+        if "ponytail" in sid:
+            has_ponytail_skills = True
+
+    skills_section = "\n".join(skills_lines) if skills_lines else "- No special skills installed."
+
+    design_directives = ""
+    if has_design_skills:
+        design_directives = """
+---
+
+## 4. Design Craftsmanship & Aesthetic Directives
+*(Activated via `impeccable`, `design-taste-frontend`, `ui-ux-pro-max`, `emil-design-eng`)*
+
+1. **Anti-Generic Aesthetic**:
+   - Reject generic AI templates: avoid purple/cyan pill-shaped gradients on pure black cards.
+   - Use high-contrast editorial typography, curated warm dark-modes, and deliberate whitespace.
+2. **Micro-Interactions & Spring Motion**:
+   - Use snappiness over sluggishness: micro-interactions must resolve in 120ms–200ms.
+   - Prefer spring physics over linear easing for natural responsiveness.
+3. **Ergonomics & Accessibility**:
+   - Ensure touch targets are at least 44x44px.
+   - Guarantee WCAG AA contrast (minimum 4.5:1 on text) and visible `:focus-visible` rings.
+"""
+
+    vercel_directives = ""
+    if has_vercel_skills:
+        vercel_directives = """
+---
+
+## 5. Vercel & React Architecture Directives
+*(Activated via `vercel-labs/agent-skills`)*
+
+1. **Server-First (RSC)**: Keep components server-side by default; only push `'use client'` to the leaf interaction nodes.
+2. **Server Actions & Mutations**: Mutate data through Server Actions with proper revalidation (`revalidatePath`).
+3. **Streaming UI**: Wrap slower database / API calls in `<Suspense fallback={<Skeleton />}>` for instant perceived performance.
+"""
+
+    content = f"""# AGENTS.md — AI Agent Pairing Guidelines for {project_name}
+
+Welcome! This document provides essential architectural context, commands, and rules for AI coding assistants (Antigravity, Cursor, Claude Code, Gemini CLI, Copilot) collaborating on **{project_name}**.
+
+---
+
+## 1. Project Context & Stack
+- **Project Name**: {project_name}
+- **Template / Architecture**: {template_id}
+- **Scaffolded by**: Aayush's DevKit
+
+{commands_section}
+
+---
+
+## 2. Active Agent Skills (`.agents/skills/`)
+The following skills are installed in `.agents/skills/` and tracked in `skills-lock.json`:
+
+{skills_section}
+
+> **Directive**: Before performing complex architectural decisions, refactors, or audits, consult the relevant skill in `.agents/skills/<skill-name>/SKILL.md`.
+
+---
+
+## 3. General Agent Principles & Coding Standards
+1. **Minimal, High-Leverage Changes**:
+   - Write the smallest amount of code that cleanly solves the problem.
+   - Avoid speculative abstractions, unnecessary wrapper layers, or bloat.
+2. **Preserve Integrity**:
+   - Never remove existing docstrings, tests, or comments unrelated to your task.
+   - Keep TypeScript types strict and Python type hints explicit.
+3. **Verification First**:
+   - Always run tests or build verification commands before claiming completion.
+   - If tests fail, diagnose root causes rather than disabling the tests.
+4. **Product Alignment**:
+   - Consult `PRD.md` for functional requirements and scope constraints.
+{design_directives}{vercel_directives}
+"""
+    file_path.write_text(content, encoding="utf-8")
+    return file_path

devkit/scaffold/env_setup.py

@@ -0,0 +1,59 @@
+import shutil
+import sys
+from pathlib import Path
+from typing import Tuple, Optional
+from ..utils.system import detect_node_package_manager, which_tool, run_command
+
+def setup_python_environment(target_dir: Path) -> Tuple[bool, str]:
+    """Create .venv and install requirements if present."""
+    target_dir = Path(target_dir)
+    python_exe = sys.executable
+
+    # 1. Create .venv
+    venv_dir = target_dir / ".venv"
+    if not venv_dir.exists():
+        code, out, err = run_command([python_exe, "-m", "venv", ".venv"], cwd=target_dir)
+        if code != 0:
+            return False, f"Failed to create virtual environment: {err}"
+
+    # 2. Determine pip path
+    if sys.platform == "win32":
+        pip_path = venv_dir / "Scripts" / "pip.exe"
+    else:
+        pip_path = venv_dir / "bin" / "pip"
+
+    req_file = target_dir / "requirements.txt"
+    if req_file.exists() and pip_path.exists():
+        code, out, err = run_command([str(pip_path), "install", "-r", "requirements.txt"], cwd=target_dir)
+        if code != 0:
+            return False, f"Failed to install requirements: {err}"
+
+    return True, "Python virtual environment and requirements configured."
+
+def setup_node_environment(target_dir: Path) -> Tuple[bool, str]:
+    """Detect package manager and install node modules."""
+    target_dir = Path(target_dir)
+    pkg_json = target_dir / "package.json"
+    if not pkg_json.exists():
+        return True, "No package.json found; skipping Node dependencies."
+
+    pm = detect_node_package_manager()
+    pm_bin = which_tool(pm)
+    if not pm_bin:
+        return False, f"No Node.js package manager found in PATH (tried bun, pnpm, yarn, npm)."
+
+    code, out, err = run_command([pm, "install"], cwd=target_dir)
+    if code != 0:
+        return False, f"Failed to install node modules via {pm}: {err}"
+
+    return True, f"Installed node modules via {pm}."
+
+def setup_dotenv_file(target_dir: Path) -> bool:
+    """Copy .env.example to .env if .env doesn't exist yet."""
+    target_dir = Path(target_dir)
+    env_example = target_dir / ".env.example"
+    env_file = target_dir / ".env"
+    if env_example.exists() and not env_file.exists():
+        shutil.copy2(env_example, env_file)
+        return True
+    return False

devkit/scaffold/git_setup.py

@@ -0,0 +1,69 @@
+from pathlib import Path
+from typing import Optional
+from ..utils.system import detect_git, run_command
+
+def setup_git_repository(target_dir: Path, has_python: bool, has_node: bool) -> bool:
+    """Initialize git repository and write stack-tailored .gitignore."""
+    target_dir = Path(target_dir)
+
+    gitignore_lines = [
+        "# General & OS",
+        ".DS_Store",
+        "Thumbs.db",
+        "*.log",
+        ".env",
+        ".env.local",
+        ".env.*.local",
+        "",
+        "# Editor & IDE",
+        ".idea/",
+        "*.suo",
+        "*.ntvs*",
+        "*.njsproj",
+        "*.sln",
+        "*.sw?",
+    ]
+
+    if has_node:
+        gitignore_lines.extend([
+            "",
+            "# Node & Frontend",
+            "node_modules/",
+            "npm-debug.log*",
+            "yarn-debug.log*",
+            "yarn-error.log*",
+            "pnpm-debug.log*",
+            "dist/",
+            "build/",
+            ".next/",
+            "out/",
+            ".expo/",
+            "web-build/",
+            ".turbo/",
+        ])
+
+    if has_python:
+        gitignore_lines.extend([
+            "",
+            "# Python",
+            ".venv/",
+            "env/",
+            "venv/",
+            "__pycache__/",
+            "*.py[cod]",
+            "*$py.class",
+            ".pytest_cache/",
+            ".coverage",
+            "htmlcov/",
+            "*.egg-info/",
+            "dist/",
+            "build/",
+        ])
+
+    gitignore_path = target_dir / ".gitignore"
+    gitignore_path.write_text("\n".join(gitignore_lines) + "\n", encoding="utf-8")
+
+    if detect_git():
+        exit_code, _, _ = run_command(["git", "init"], cwd=target_dir)
+        return exit_code == 0
+    return False

devkit/scaffold/prd_md.py

@@ -0,0 +1,85 @@
+import shutil
+from pathlib import Path
+from typing import Optional
+
+def generate_prd_template(
+    target_dir: Path,
+    project_name: str,
+    overview: str = "",
+    target_users: str = "",
+    core_features: str = "",
+) -> Path:
+    """Generate a structured, professional PRD.md."""
+    target_dir = Path(target_dir)
+    file_path = target_dir / "PRD.md"
+
+    ov = overview.strip() or f"High-level vision and objectives for {project_name}."
+    users = target_users.strip() or "Primary target users and stakeholders."
+    features = core_features.strip() or "- Core Feature 1\n- Core Feature 2\n- Core Feature 3"
+
+    content = f"""# Product Requirements Document (PRD): {project_name}
+
+**Status**: Draft / In Progress  
+**Author**: Aayush  
+**Last Updated**: Auto-generated by Aayush's DevKit  
+
+---
+
+## 1. Executive Summary & Problem Statement
+### Overview
+{ov}
+
+### The Problem
+- Clearly define the pain points this project addresses.
+- What friction exists in current alternatives?
+
+---
+
+## 2. Target Audience & Personas
+### Target Users
+{users}
+
+### Key User Scenarios
+1. **Scenario A**: Primary day-to-day workflow.
+2. **Scenario B**: Edge-case or administrator workflow.
+
+---
+
+## 3. Core Functional Requirements (MVP)
+{features}
+
+### Requirements Breakdown
+| ID | Feature | Priority | Description | Acceptance Criteria |
+|---|---|---|---|---|
+| F-01 | Initial Scaffolding | P0 | Project bootstraps cleanly with zero errors | Commands run cleanly |
+| F-02 | Core Logic | P0 | Core business logic implementation | Tests pass |
+| F-03 | Polish & Verification | P1 | UI / API polishing and edge cases | Verified manually & automated |
+
+---
+
+## 4. Technical & Non-Functional Requirements
+- **Performance**: Instantaneous responses, lean bundle size.
+- **Reliability**: Graceful error handling and robust tests.
+- **Security**: No hardcoded secrets; use environment variables (`.env`).
+- **Maintainability**: Clear folder hierarchy, clean type definitions.
+
+---
+
+## 5. Milestones & Success Metrics
+- [ ] **Milestone 1**: Scaffolding & environment verified.
+- [ ] **Milestone 2**: Core MVP functionality completed.
+- [ ] **Milestone 3**: Automated test suite passing.
+- [ ] **Milestone 4**: Final documentation and deployment.
+"""
+    file_path.write_text(content, encoding="utf-8")
+    return file_path
+
+def import_prd_file(target_dir: Path, source_path: Path) -> Optional[Path]:
+    """Copy an existing PRD file from source_path to target_dir/PRD.md."""
+    target_dir = Path(target_dir)
+    source_path = Path(source_path).expanduser().resolve()
+    if not source_path.exists() or not source_path.is_file():
+        return None
+    dest_path = target_dir / "PRD.md"
+    shutil.copy2(source_path, dest_path)
+    return dest_path

devkit/scaffold/vscode_setup.py

@@ -0,0 +1,38 @@
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+def setup_vscode_config(target_dir: Path, has_python: bool, has_node: bool) -> Path:
+    """Write customized .vscode/settings.json and extensions.json."""
+    target_dir = Path(target_dir)
+    vscode_dir = target_dir / ".vscode"
+    vscode_dir.mkdir(parents=True, exist_ok=True)
+
+    settings: Dict[str, Any] = {
+        "editor.formatOnSave": True,
+        "editor.tabSize": 2,
+        "files.eol": "\n",
+        "files.trimTrailingWhitespace": True,
+    }
+
+    extensions = [
+        "eamodio.gitlens",
+    ]
+
+    if has_python:
+        settings["python.defaultInterpreterPath"] = "${workspaceFolder}/.venv/Scripts/python.exe"
+        settings["python.testing.pytestEnabled"] = True
+        settings["python.testing.pytestArgs"] = ["tests"]
+        extensions.extend(["ms-python.python", "ms-python.vscode-pylance", "charliermarsh.ruff"])
+
+    if has_node:
+        settings["editor.defaultFormatter"] = "esbenp.prettier-vscode"
+        extensions.extend(["dbaeumer.vscode-eslint", "esbenp.prettier-vscode", "bradlc.vscode-tailwindcss"])
+
+    settings_file = vscode_dir / "settings.json"
+    settings_file.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+
+    extensions_file = vscode_dir / "extensions.json"
+    extensions_file.write_text(json.dumps({"recommendations": extensions}, indent=2), encoding="utf-8")
+
+    return vscode_dir

devkit/skills/__init__.py

@@ -0,0 +1,10 @@
+from .catalog import AVAILABLE_SKILLS, SKILL_BUNDLES, get_recommended_skills_for_template, SkillInfo
+from .installer import install_skills
+
+__all__ = [
+    "AVAILABLE_SKILLS",
+    "SKILL_BUNDLES",
+    "get_recommended_skills_for_template",
+    "SkillInfo",
+    "install_skills",
+]

devkit/skills/catalog.py

@@ -0,0 +1,156 @@
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Dict, Optional
+from ..config import EMBEDDED_SKILLS_DIR
+
+@dataclass
+class SkillInfo:
+    id: str
+    name: str
+    description: str
+    category: str
+    source: str = "embedded"
+    source_type: str = "local"
+    recommended_for: Optional[List[str]] = None
+
+def _categorize_skill(skill_id: str) -> str:
+    """Categorize skills by their domain."""
+    if any(k in skill_id for k in ["animat", "motion"]):
+        return "Animations & Motion"
+    elif any(k in skill_id for k in ["taste", "impeccable", "design", "ui-ux", "styling", "apple-design"]):
+        return "Design & UI/UX"
+    elif "vercel" in skill_id or "deploy" in skill_id or "web-design" in skill_id:
+        return "Vercel & Next.js"
+    elif "ponytail" in skill_id:
+        return "Code Quality (Ponytail)"
+    elif any(k in skill_id for k in ["mobile", "native", "swift"]):
+        return "Mobile & Native"
+    elif any(k in skill_id for k in ["gemini", "ai", "agent"]):
+        return "AI & Agentic"
+    elif any(k in skill_id for k in ["devtools", "guidance"]):
+        return "Browser & Web Standards"
+    return "Developer Tools"
+
+def _extract_skill_meta(skill_id: str, skill_dir: Path) -> tuple[str, str]:
+    """Extract name and description from SKILL.md frontmatter."""
+    skill_md = skill_dir / "SKILL.md"
+    name = skill_id.replace("-", " ").title()
+    desc = f"Curated skill for {skill_id}."
+
+    if skill_md.exists():
+        try:
+            content = skill_md.read_text(encoding="utf-8", errors="ignore")
+            # Match frontmatter YAML block
+            fm_match = re.search(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
+            if fm_match:
+                fm_text = fm_match.group(1)
+                for line in fm_text.splitlines():
+                    if line.startswith("name:"):
+                        name = line.split(":", 1)[1].strip().strip('"').strip("'")
+                    elif line.startswith("description:"):
+                        desc = line.split(":", 1)[1].strip().strip('"').strip("'")
+                        # Handle multiline YAML folded scalar >-
+                        if desc in [">-", "|-", ">", "|"]:
+                            # Look at next lines
+                            lines = fm_text.splitlines()
+                            idx = lines.index(line)
+                            collected = []
+                            for nxt in lines[idx + 1:]:
+                                if nxt.startswith("  "):
+                                    collected.append(nxt.strip())
+                                else:
+                                    break
+                            if collected:
+                                desc = " ".join(collected)
+        except Exception:
+            pass
+
+    # Truncate overly long descriptions for display
+    if len(desc) > 160:
+        desc = desc[:157] + "..."
+
+    return name, desc
+
+def load_all_skills() -> Dict[str, SkillInfo]:
+    """Dynamically discover and build the full catalog of embedded skills."""
+    skills: Dict[str, SkillInfo] = {}
+
+    lock_file = EMBEDDED_SKILLS_DIR / "skills-lock.json"
+    lock_data: Dict = {}
+    if lock_file.exists():
+        try:
+            with open(lock_file, "r", encoding="utf-8") as f:
+                lock_data = json.load(f).get("skills", {})
+        except Exception:
+            lock_data = {}
+
+    if EMBEDDED_SKILLS_DIR.exists():
+        for item in sorted(EMBEDDED_SKILLS_DIR.iterdir()):
+            if item.is_dir():
+                sid = item.name
+                name, desc = _extract_skill_meta(sid, item)
+                cat = _categorize_skill(sid)
+
+                lock_entry = lock_data.get(sid, {})
+                source = lock_entry.get("source", f"embedded/{sid}")
+                source_type = lock_entry.get("sourceType", "builtin")
+
+                # Setup recommendation tags
+                recs = ["all"] if "ponytail" in sid else []
+                if sid in ["impeccable", "design-taste-frontend", "ui-ux-pro-max", "emil-design-eng", "animate"]:
+                    recs.extend(["nextjs", "vite_react", "saas_fullstack", "design_system", "content_site", "expo_mobile", "expo_fullstack"])
+                if "vercel" in sid or sid in ["web-design-guidelines"]:
+                    recs.extend(["nextjs", "saas_fullstack", "design_system", "content_site"])
+                if sid in ["modern-web-guidance", "chrome-devtools"]:
+                    recs.extend(["nextjs", "vite_react", "saas_fullstack", "content_site", "design_system"])
+                if "gemini" in sid:
+                    recs.extend(["all"])
+                if sid in ["mobile-native", "animate-expo", "vercel-react-native-skills"]:
+                    recs.extend(["expo_mobile", "expo_fullstack"])
+
+                skills[sid] = SkillInfo(
+                    id=sid,
+                    name=name,
+                    description=desc,
+                    category=cat,
+                    source=source,
+                    source_type=source_type,
+                    recommended_for=recs,
+                )
+
+    return skills
+
+AVAILABLE_SKILLS: Dict[str, SkillInfo] = load_all_skills()
+
+SKILL_BUNDLES: Dict[str, Dict] = {
+    "ponytail_suite": {
+        "title": "Ponytail Suite (Lazy Senior Dev Mode)",
+        "skills": ["ponytail", "ponytail-audit", "ponytail-review", "ponytail-debt"],
+        "description": "Essential code quality, minimal architecture, and anti-bloat review suite.",
+    },
+    "design_craft_suite": {
+        "title": "Design Craftsmanship & Aesthetics Suite",
+        "skills": ["impeccable", "design-taste-frontend", "ui-ux-pro-max", "emil-design-eng", "animate"],
+        "description": "World-class UI design, anti-generic art direction, and micro-interactions.",
+    },
+    "vercel_fullstack_suite": {
+        "title": "Vercel & Next.js Performance Suite",
+        "skills": ["vercel-react-best-practices", "vercel-composition-patterns", "vercel-optimize", "deploy-to-vercel"],
+        "description": "Production Next.js App Router patterns, RSC, and deployment optimization.",
+    },
+    "mobile_native_suite": {
+        "title": "Mobile Native & Fluid Interaction Suite",
+        "skills": ["animate-expo", "mobile-native", "vercel-react-native-skills", "apple-design"],
+        "description": "Touch physics, haptics, responsive gestures, and native performance.",
+    },
+}
+
+def get_recommended_skills_for_template(template_id: str) -> List[str]:
+    """Get the list of skill IDs recommended for a particular template."""
+    recommended = []
+    for skill_id, skill in AVAILABLE_SKILLS.items():
+        if skill.recommended_for and ("all" in skill.recommended_for or template_id in skill.recommended_for):
+            recommended.append(skill_id)
+    return recommended

devkit/skills/embedded/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ponytail
+description: >
+  Lazy senior dev mode: the smallest change that fully solves the task, and a
+  reply a busy human understands in one read. Use on any coding task (writing,
+  fixing, refactoring, reviewing, choosing dependencies) and when the user says
+  "ponytail", "be lazy", "simplest solution", "yagni", or complains about
+  over-engineering or bloat. Levels: lite, full (default), ultra.
+argument-hint: "[lite|full|ultra|off]"
+license: MIT
+---
+
+# Ponytail
+
+You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
+
+Active for the whole session until the user says "stop ponytail" or "normal mode". Switch level: `/ponytail lite|full|ultra`.
+
+## Before you write
+
+Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
+
+## The smallest complete change
+
+Take the first option that fully works:
+
+1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
+2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
+3. Standard library or a platform feature? Use it, unless the project has its own. A house component beats a native widget.
+4. An installed dependency? Use it. Never add a dependency for a few lines.
+5. Can it be one line a reader gets at a glance? One line.
+6. Otherwise: the minimum code that works.
+
+- Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
+- No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
+- The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
+- Comment only the why the code cannot show, in one line.
+- Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
+- Code you move or merge keeps its error handling and validation.
+- Between options of equal size, take the one that is correct on edge cases.
+- Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
+- A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
+
+Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
+
+## Levels
+
+| Level | Behavior |
+|-------|----------|
+| **lite** | Build what was asked. Name the smaller option in one line and let the user pick. |
+| **full** | The rules above. Default. |
+| **ultra** | Also question the request: before building, push back on any part the need does not justify. |