ai-dev-starter 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,35 @@
+MIT License
+
+Copyright (c) 2026 AI Dev Starter Kit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## Third-Party Attributions
+
+Review methodology concepts, severity classification, and anti-speculation 
+principles were adapted from PR-Agent by Qodo (formerly CodiumAI):
+  https://github.com/Qodo-AI/pr-agent
+  Copyright (c) 2023 CodiumAI
+  Licensed under the MIT License
+
+No source code from PR-Agent was copied. Only conceptual approaches
+(diff-centric review, severity classification, verification methodology)
+were studied and re-implemented independently for IDE-native use.

package/README.md

@@ -1,3 +1,384 @@
-# Temporary Holding Version
+# Universal AI Development Starter Kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A production-quality, reusable AI development system for AI-assisted coding.
+Provides structured workflows for code review, bug fixing, feature development,
+refactoring, security auditing, performance auditing, architecture analysis, and
+test generation — all running inside your IDE's native AI, with no external LLM API key required.
+
+**Primary target:** Google Antigravity  
+**Also supports:** Cursor  
+**Architecture:** Framework-agnostic (PHP/Laravel, React/Next.js, Node.js/TypeScript, Python, and more)
+
+---
+
+## What It Does
+
+| Workflow | Description |
+|----------|-------------|
+| **Code Review** | Analyzes Git changes (committed, staged, unstaged) with evidence-based findings at P0–P3 severity |
+| **Bug Fix** | Root-cause investigation, minimal fix proposal, approval-gated implementation |
+| **Feature Development** | Requirements-first, plan-then-implement, convention-following feature implementation |
+| **Refactoring** | Test-coverage-aware structural improvement with behavioral preservation |
+| **Security Audit** | OWASP-aligned static inspection: injection, auth, sensitive data, mass assignment, CSRF |
+| **Performance Audit** | Evidence-supported: N+1 queries, missing indexes, synchronous blocking, caching gaps |
+| **Architecture Review** | Layer boundaries, coupling, cohesion, dependency quality, scalability |
+| **Test Generation** | Framework-aware test writing using the project's existing testing setup |
+
+**Review reports are generated in Persian by default** (configurable to English in `project-context.md`).
+
+---
+
+## Supported IDEs
+
+| IDE | Integration | Status |
+|-----|-------------|--------|
+| Google Antigravity | `AGENTS.md` + `.agents/skills/` (native Skills system) | ✅ Full |
+| Cursor | `.cursor/rules/*.mdc` (native Rules system) | ✅ Full |
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+ (only for the installer; no runtime dependencies)
+- Git (for the code review workflow)
+
+### Quick Start
+
+```bash
+# Clone or copy the ai-dev-starter directory into your projects location
+# Then install into your existing project:
+
+node /path/to/ai-dev-starter/scripts/ai-dev-starter.js init \
+  --ide antigravity \
+  --target /path/to/your-project
+```
+
+### IDE-Specific Installation
+
+```bash
+# For Google Antigravity only
+node scripts/ai-dev-starter.js init --ide antigravity --target /your/project
+
+# For Cursor only
+node scripts/ai-dev-starter.js init --ide cursor --target /your/project
+
+# For both IDEs
+node scripts/ai-dev-starter.js init --ide both --target /your/project
+```
+
+### Install in Current Directory
+
+```bash
+cd /your/project
+node /path/to/ai-dev-starter/scripts/ai-dev-starter.js init --ide antigravity
+```
+
+### Post-Installation
+
+After installation, fill in the project context file:
+
+```
+.agents/project-context.md
+```
+
+This file tells the AI about your project's tech stack, commands, conventions, and constraints.
+**Do not store credentials in this file.**
+
+---
+
+## Updating
+
+```bash
+node scripts/ai-dev-starter.js update --target /your/project
+```
+
+The update command:
+- Shows a diff for files you have manually modified.
+- Asks before overwriting user-modified files.
+- Never silently overwrites.
+
+---
+
+## Uninstallation
+
+```bash
+node scripts/ai-dev-starter.js uninstall --target /your/project
+```
+
+- Removes all files tracked in the manifest.
+- Preserves files you have manually modified.
+- Removes the manifest file.
+
+---
+
+## Health Check & Detection
+
+```bash
+# Verify integrity of installed files and configuration
+node scripts/ai-dev-starter.js doctor --target /your/project
+
+# Preview what the stack detector discovers in your repository
+node scripts/ai-dev-starter.js detect --target /your/project
+```
+
+- `doctor`: Verifies all expected files are present, identifies missing or user-modified files.
+- `detect`: Scans `composer.json`, `package.json`, `pyproject.toml`, directories and configs to show the detected stack without modifying files.
+
+---
+
+## Workflow Invocation
+
+### Google Antigravity
+
+Speak naturally. The skills are auto-discovered:
+
+```
+"review my code"
+"review my changes on this branch"
+"fix this bug: [paste error or stack trace]"
+"implement feature: user can reset password via email"
+"refactor the OrderController"
+"run a security audit on the auth module"
+"performance review on the API layer"
+"architecture review"
+"generate tests for UserService"
+```
+
+### Cursor
+
+Mention the rule file or use natural language (the `core-rules.mdc` rule routes automatically):
+
+```
+@code-review.mdc — review my code
+@bug-fix.mdc — fix this error: [paste error]
+@feature-development.mdc — implement X
+@refactor-and-security.mdc — refactor this
+@performance-arch-tests.mdc — performance audit
+```
+
+Or just type naturally — `core-rules.mdc` has `alwaysApply: true` and routes to the right workflow.
+
+---
+
+## Project Context Configuration
+
+Edit `.agents/project-context.md` after installation.
+
+**Key fields:**
+
+```yaml
+project_name: "My SaaS"
+backend_framework: "laravel"
+backend_version: "Laravel 11"
+frontend_framework: "react"
+databases:
+  - type: "mysql"
+    orm: "eloquent"
+test: "php artisan test"
+report_language: "fa"    # fa = Persian, en = English
+```
+
+---
+
+## Examples by Project Type
+
+### Laravel + React Project
+
+```bash
+# Install
+node scripts/ai-dev-starter.js init --ide both --target /var/www/my-laravel-app
+
+# project-context.md configuration:
+# backend_framework: laravel
+# frontend_framework: react
+# test: "php artisan test"
+# report_language: fa
+```
+
+Invoke:
+```
+"review my code"              → Reviews git diff, produces Persian report
+"fix this 500 error: ..."    → Investigates Eloquent / controller layer
+"write tests for OrderService" → Generates PHPUnit/Pest tests
+```
+
+### Next.js Project
+
+```bash
+# Install
+node scripts/ai-dev-starter.js init --ide both --target /home/user/my-nextjs-app
+
+# project-context.md configuration:
+# backend_framework: nextjs
+# frontend_framework: next
+# test: "npm test"
+# report_language: en
+```
+
+Invoke:
+```
+"architecture review" → Evaluates App Router structure, component coupling
+"security audit"      → Inspects API routes, auth, XSS vectors
+"performance audit"   → Finds client-side data fetching, bundle issues
+```
+
+### Node.js / TypeScript API
+
+```bash
+# Install
+node scripts/ai-dev-starter.js init --ide antigravity --target /home/user/my-api
+
+# project-context.md configuration:
+# backend_framework: express
+# backend_language: typescript
+# test: "npm test"
+```
+
+---
+
+## Customization
+
+### Adding Project-Specific Rules
+
+Edit `AGENTS.md` (Antigravity) or `.cursor/rules/ai-core-rules.mdc` (Cursor) to add project-specific always-on rules. The installer will warn before overwriting user-modified files on subsequent updates.
+
+### Adding a New Workflow
+
+1. Create `workflows/my-workflow.md` following the existing structure.
+2. Create `adapters/antigravity/skills/my-workflow/SKILL.md` with YAML frontmatter.
+3. Create `adapters/cursor/my-workflow.mdc` with YAML frontmatter.
+4. Add entries to `ANTIGRAVITY_FILES` and `CURSOR_FILES` in `scripts/ai-dev-starter.js`.
+5. Run `update` to deploy.
+
+### Adding a New IDE Adapter
+
+1. Research the IDE's native rules/instructions format.
+2. Create `adapters/<ide-name>/` directory.
+3. Add a file manifest array in the installer script (following `ANTIGRAVITY_FILES` as a model).
+4. Add the new IDE option to the CLI `--ide` argument parser.
+
+### Changing Report Language
+
+In `.agents/project-context.md`:
+```yaml
+report_language: "en"   # English
+# or
+report_language: "fa"   # Persian (default)
+```
+
+---
+
+## Architecture
+
+```
+ai-dev-starter/
+├── core/                        # Universal, IDE-independent instructions
+│   ├── agent-principles.md      # Agent identity, safety rules, communication
+│   ├── safety-policy.md         # Destructive action protocol
+│   ├── git-analysis.md          # Git command sequences, diff interpretation rules
+│   ├── review-methodology.md    # Review dimensions, verification checklist, formats
+│   └── severity-levels.md       # P0–P3 definitions with examples
+│
+├── workflows/                   # Task-specific execution sequences
+│   ├── code-review.md
+│   ├── bug-fix.md
+│   ├── feature-development.md
+│   ├── refactor.md
+│   ├── security-audit.md
+│   ├── performance-audit.md
+│   ├── architecture-review.md
+│   └── test-generation.md
+│
+├── standards/                   # Technology-agnostic coding standards
+│   ├── backend.md
+│   ├── frontend.md
+│   ├── database.md
+│   ├── security.md
+│   └── testing.md
+│
+├── adapters/
+│   ├── antigravity/             # Google Antigravity native format
+│   │   ├── AGENTS.md            # Always-on rules (project root)
+│   │   └── skills/              # One SKILL.md bundle per workflow
+│   └── cursor/                  # Cursor native format
+│       └── *.mdc                # One .mdc rule file per workflow cluster
+│
+├── templates/
+│   ├── project-context.md       # Fill-in template for project-specific config
+│   ├── review-report.md         # Bilingual review report structure
+│   └── architecture-decision.md # ADR template
+│
+├── scripts/
+│   ├── ai-dev-starter.js        # Installer CLI (no external dependencies)
+│   └── detector.js              # Project context & tech stack detector
+│
+├── tests/
+│   └── test-installer.js        # Automated test suite (54 assertions)
+│
+├── package.json                 # npm scripts & metadata
+├── README.md
+└── LICENSE
+```
+
+### Design Decisions
+
+**Why no external API key?** The kit uses your IDE's native AI. No subscription, no key rotation, no cost per review.
+
+**Why Node.js for the installer?** Node.js is available on all major platforms and in most project environments. The installer uses only built-in modules — no `npm install` required.
+
+**Why AGENTS.md + Skills instead of a single file?** Progressive disclosure: `AGENTS.md` is always-on and minimal. Skills are loaded only when invoked. This prevents wasting context on irrelevant workflows.
+
+**Why are core files referenced by path?** Workflows instruct the AI to load specific core files at runtime. This avoids duplicating content across adapters while maintaining a single source of truth.
+
+---
+
+## Limitations
+
+| Limitation | Detail |
+|-----------|--------|
+| No CI integration | Cannot run as a GitHub Action or comment on PRs. Use this inside your IDE. |
+| Static analysis only | Cannot run DAST, profiling, or dynamic tests automatically. |
+| Git access required | Code Review workflow requires a git repository and read access to `git diff`. |
+| No IDE API access | Cannot post inline comments in PRs — output is text in the IDE chat. |
+| Test execution | AI reports test results only when tests are actually run in the IDE's terminal access. |
+| Cursor non-interactivity | Cursor rules cannot call shell commands directly — the AI must use the terminal panel. |
+
+---
+
+## Troubleshooting
+
+**"Skill not being triggered in Antigravity"**
+- Confirm `.agents/skills/<name>/SKILL.md` exists.
+- Check the `description:` field in the SKILL.md frontmatter is descriptive enough.
+- Run `ai-dev-starter doctor` to verify file presence.
+
+**"Cursor rules not loading"**
+- Confirm files are in `.cursor/rules/*.mdc` (not `.cursorrules`).
+- Confirm `alwaysApply: true` is set in `core-rules.mdc`.
+- Check Cursor version supports `.mdc` files (requires Cursor 0.43+).
+
+**"Review report is in English but I want Persian"**
+- In `.agents/project-context.md`, set `report_language: fa`.
+
+**"Update is overwriting my custom AGENTS.md"**
+- The update command will show a diff and ask before overwriting.
+- If the file is listed as user-modified in the manifest, it will warn and prompt.
+- Answer `n` to skip overwrite.
+
+---
+
+## Attribution
+
+Review methodology and prompt design principles adapted from:
+**PR-Agent** by Qodo (formerly CodiumAI) — https://github.com/Qodo-AI/pr-agent  
+Licensed under the MIT License.
+
+Adaptations are conceptual (review dimensions, severity classification, anti-speculation rules, diff-centric focus) and do not include direct source code reproduction.
+
+---
+
+## License
+
+MIT License — see [LICENSE](./LICENSE).

package/adapters/antigravity/AGENTS.md

@@ -0,0 +1,59 @@
+# AI Development Rules — Universal
+
+> **Scope:** These rules are always loaded for every task in this project.
+> **Keep this file short.** Full workflow details live in `.agents/skills/`.
+
+---
+
+## Core Identity
+
+You are a Principal Software Engineer embedded in this project.
+You are precise, evidence-based, and conservative about irreversible actions.
+
+---
+
+## Always-On Rules
+
+1. **Never commit, push, merge, or deploy automatically.**
+2. **Never overwrite user-modified files without showing a diff and asking.**
+3. **Never expose credentials, tokens, or secrets in any output.**
+4. **Never claim tests passed unless you executed them and observed output.**
+5. **Never fabricate code findings — every reported issue must have file + line evidence.**
+6. **Make the smallest change that solves the problem. No scope creep.**
+7. **Preserve existing architecture, naming conventions, and coding style.**
+
+---
+
+## Workflow Invocation
+
+Activate the appropriate skill for each task:
+
+| Task | Say | Skill |
+|------|-----|-------|
+| Review code changes | "review my code" | `code-review` |
+| Fix a bug | "fix this bug" or paste error | `bug-fix` |
+| Build a feature | "implement feature X" | `feature-development` |
+| Refactor code | "refactor this" | `refactor` |
+| Security audit | "security audit" | `security-audit` |
+| Performance audit | "performance review" | `performance-audit` |
+| Architecture review | "architecture review" | `architecture-review` |
+| Generate tests | "write tests for X" | `test-generation` |
+
+---
+
+## Project Context
+
+Before starting any task, check `.agents/project-context.md` for:
+- Tech stack and framework versions.
+- Development and test commands.
+- Coding conventions.
+- Review report language setting.
+
+If the file does not exist, ask the user to run `ai-dev-starter init` or fill in the template at `.agents/project-context.md`.
+
+---
+
+## Report Language
+
+Default: **Persian (Farsi)**. Preserve English for code, identifiers, file paths, commands.
+Override in `.agents/project-context.md` → `report_language: en` to switch to English.

package/adapters/antigravity/skills/architecture-review/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: architecture-review
+description: >-
+  Evaluates the structural health, layer boundaries, coupling, cohesion,
+  dependency quality, and scalability of the codebase. Produces findings at
+  the architectural level, not code-level defects. Read-only. Use when asked
+  for "architecture review", "design review", "بررسی معماری".
+---
+
+# Architecture Review Skill
+
+## Instructions
+
+Execute the Architecture Review workflow from `workflows/architecture-review.md`.
+
+Before starting, load:
+- `core/agent-principles.md`
+- `.agents/project-context.md`
+
+Follow the 7-step execution sequence:
+1. Map the directory structure and file distribution.
+2. Identify the architectural pattern in use.
+3. Evaluate layer boundaries (fat controllers, DB in controllers, etc.).
+4. Evaluate coupling and cohesion.
+5. Evaluate third-party dependencies.
+6. Evaluate scalability potential.
+7. Generate structured report.
+
+## Key Constraints
+
+- **Read-only.** Make no changes.
+- **Structural findings only.** Code-level bugs belong in Code Review, not here.
+- Cite specific files and metrics (line counts, import counts) as evidence.

package/adapters/antigravity/skills/bug-fix/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: bug-fix
+description: >-
+  Investigates a reported bug, identifies root cause with evidence, proposes a
+  minimal fix, and implements only after user approval. Use when the user shares
+  an error message, stack trace, test failure, or describes unexpected behavior.
+  Trigger phrases: "fix this bug", "this is broken", "باگ", "خطا".
+---
+
+# Bug Fix Skill
+
+## Instructions
+
+Execute the Bug Fix workflow from `workflows/bug-fix.md`.
+
+Before starting, load:
+- `core/agent-principles.md`
+- `core/safety-policy.md`
+- `.agents/project-context.md`
+
+Follow the 8-step execution sequence:
+1. Understand the bug report.
+2. Establish evidence (search, grep, read).
+3. Identify root cause.
+4. Identify affected code.
+5. Propose fix (with plan).
+6. **Wait for explicit user approval.**
+7. Implement.
+8. Run tests and report output.
+
+## Key Constraints
+
+- **Never implement without user approval** of the proposed fix plan.
+- **Minimal change only.** Do not fix unrelated issues encountered during investigation.
+- **Never auto-commit** the fix.
+- Run only the tests relevant to the fix — report actual output.

package/adapters/antigravity/skills/code-review/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: code-review
+description: >-
+  Performs a structured, evidence-based code review of current Git changes.
+  Reviews committed, staged, and unstaged changes. Produces a prioritized
+  findings report with file/line citations. Use when asked to "review my code",
+  "code review", "بررسی کد", or "ریویو کن".
+---
+
+# Code Review Skill
+
+## Instructions
+
+Execute the Code Review workflow from `workflows/code-review.md`.
+
+Before starting, load:
+- `core/agent-principles.md`
+- `core/git-analysis.md`
+- `core/review-methodology.md`
+- `core/severity-levels.md`
+- `.agents/project-context.md` (if present in the project)
+
+Then follow the 8-step execution sequence defined in `workflows/code-review.md`.
+
+## Key Constraints
+
+- **Read-only.** Do not modify any files.
+- **Evidence-only.** Every finding must include file path, line number, and code evidence.
+- **No speculation.** Do not report issues you cannot trace to specific changed lines.
+- **Report language:** Use the `report_language` from `.agents/project-context.md` (default: Persian).
+
+## Output
+
+A structured review report following the template in `templates/review-report.md`.

package/adapters/antigravity/skills/feature-development/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: feature-development
+description: >-
+  Implements a new feature by first understanding requirements, inspecting
+  existing architecture, presenting a plan, and implementing incrementally
+  following project conventions. Use when asked to "add feature X",
+  "implement Y", "build Z", "اضافه کن", "پیاده‌سازی کن".
+---
+
+# Feature Development Skill
+
+## Instructions
+
+Execute the Feature Development workflow from `workflows/feature-development.md`.
+
+Before starting, load:
+- `core/agent-principles.md`
+- `core/safety-policy.md`
+- `.agents/project-context.md`
+- Relevant standards from `standards/` based on detected tech stack.
+
+Follow the 8-step execution sequence:
+1. Understand and confirm requirements (ask max 3 clarifying questions if needed).
+2. Inspect existing architecture.
+3. Present implementation plan.
+4. **Wait for user approval.**
+5. Implement incrementally (migration → model → service → controller → tests).
+6. Follow existing conventions exactly.
+7. Write tests.
+8. Run tests and report output.
+
+## Key Constraints
+
+- Present a plan and **wait for approval before writing any files**.
+- Do not introduce new dependencies without approval.
+- Do not modify code outside the authorized scope.
+- Match existing naming conventions, file structure, and coding style exactly.

package/adapters/antigravity/skills/performance-audit/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: performance-audit
+description: >-
+  Identifies measurable performance bottlenecks in database queries, API calls,
+  frontend rendering, and background jobs. Prioritizes evidence-supported issues
+  over theoretical ones. Read-only. Use when asked for "performance audit",
+  "slow queries", "optimize", "بررسی کارایی", "کوئری کند".
+---
+
+# Performance Audit Skill
+
+## Instructions
+
+Execute the Performance Audit workflow from `workflows/performance-audit.md`.
+
+Before starting, load:
+- `core/agent-principles.md`
+- `core/severity-levels.md`
+- `.agents/project-context.md`
+
+Follow the 7-step execution sequence:
+1. Define scope.
+2. Database query analysis (N+1, missing indexes, unbounded queries).
+3. API and HTTP analysis (synchronous calls, missing caching).
+4. Frontend analysis (bundle size, non-lazy routes, unnecessary renders).
+5. Background job analysis.
+6. Assess each finding for evidence and scale impact.
+7. Generate report.
+
+## Key Constraints
+
+- **Read-only.** Make no changes.
+- **Evidence-supported findings only.** Speculative performance concerns are not reported.
+- Each finding must include estimated impact at realistic scale.

package/adapters/antigravity/skills/refactor/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: refactor
+description: >-
+  Improves code structure and readability without changing observable behavior.
+  Checks for test coverage first, presents a plan, implements step by step,
+  and verifies tests still pass after each step. Use when asked to "refactor",
+  "clean up", "simplify", "ریفکتور", "بهبود کد".
+---
+
+# Refactor Skill
+
+## Instructions
+
+Execute the Refactoring workflow from `workflows/refactor.md`.
+
+Before starting, load:
+- `core/agent-principles.md`
+- `core/safety-policy.md`
+- `.agents/project-context.md`
+
+Follow the 6-step execution sequence:
+1. Understand scope.
+2. Assess test coverage (warn if none, offer to generate tests first).
+3. Identify improvements.
+4. Present refactoring plan.
+5. **Wait for user approval.**
+6. Implement in small steps, running tests after each.
+
+## Key Constraints
+
+- **Stop immediately if any test fails.** Report and revert the last step.
+- **No feature additions during refactoring.**
+- **No changes to public APIs.**
+- Do not reformat code outside the changed functions.
+- Behavior must be observably identical before and after.