ai-dev-starter 0.0.0-stage → 1.0.0

package/core/review-methodology.md

@@ -0,0 +1,154 @@
+# Code Review Methodology
+
+> **Scope:** Core reference — loaded by the Code Review workflow.
+> **Source:** Adapted from PR-Agent (Qodo / The-PR-Agent, MIT License) for IDE-native use.
+
+---
+
+## Philosophy
+
+Effective code review is:
+- **Diff-centric:** Focus on what changed, not the entire codebase.
+- **Evidence-based:** Every finding must cite specific code.
+- **Prioritized:** Not all issues are equal. Distinguish critical from cosmetic.
+- **Actionable:** Every finding must suggest a concrete fix.
+- **Conservative:** When uncertain, ask rather than fabricate.
+
+---
+
+## Review Dimensions
+
+Inspect each changed file along these dimensions, in priority order:
+
+### Dimension 1 — Correctness and Business Logic
+- Does the code do what the commit message, PR description, or task requires?
+- Are there off-by-one errors, wrong operators, or inverted conditions?
+- Are null / undefined / empty values handled?
+- Are error paths handled correctly?
+- Are return values checked?
+
+### Dimension 2 — Security
+- Injection vulnerabilities (SQL, command, XSS, SSTI).
+- Authentication and authorization gaps (missing checks, privilege escalation).
+- Sensitive data exposure (logs, error messages, API responses).
+- Insecure deserialization or file handling.
+- Unsafe use of `eval`, `exec`, `shell_exec`, `system`.
+- Missing CSRF protection on state-changing endpoints.
+- Hardcoded credentials or secrets.
+
+### Dimension 3 — Data Integrity
+- Database transactions wrapping multi-step operations.
+- Race conditions and concurrency issues.
+- Missing foreign key constraints or on-delete behavior.
+- Unsafe mass assignment.
+- Migration reversibility.
+
+### Dimension 4 — Performance
+- N+1 queries (loop containing a database call).
+- Missing indexes for new query patterns.
+- Unbounded queries (missing LIMIT on user-controlled input).
+- Synchronous blocking operations in async contexts.
+- Large payload responses without pagination.
+
+### Dimension 5 — Architecture
+- Does the change respect existing layer boundaries?
+- Is business logic leaking into controllers, views, or routes?
+- Are dependencies introduced cleanly (not bypassing interfaces)?
+- Is coupling increased unnecessarily?
+
+### Dimension 6 — Testability and Coverage
+- Does the change have unit or integration tests?
+- Are critical branches covered?
+- Are edge cases tested?
+- Do existing tests still pass with the change?
+
+### Dimension 7 — Code Quality
+- Is the code readable and self-documenting?
+- Are magic numbers or strings explained?
+- Is complexity appropriate?
+- Note: Flag quality issues as P3 (Low). Do not spend significant review effort on style.
+
+---
+
+## Verification Before Reporting
+
+For every candidate finding:
+
+1. **Re-read** the relevant code section.
+2. **Check** whether the issue is in the new code (diff) or pre-existing.
+3. **Trace** the execution path that produces the problem.
+4. **Search** for mitigating factors (middleware, validators, tests).
+5. **Confirm** the finding is realistic, not theoretical.
+
+If you cannot complete steps 3–5 with concrete evidence, downgrade the finding or discard it.
+
+---
+
+## Finding Format
+
+Each finding must follow this structure:
+
+```markdown
+### [SEVERITY] Short description
+
+**File:** `path/to/file.ext`
+**Line:** 42 (or range 42–55)
+
+**Problem:**
+One or two sentences describing the specific defect.
+
+**Evidence:**
+```language
+// The specific code that is problematic
+relevant_code_here
+```
+
+**Impact:**
+Realistic description of what could happen if this is not fixed.
+Avoid "could potentially maybe" language. If impact is uncertain, say so.
+
+**Fix:**
+Concrete suggestion. Code snippet if helpful.
+
+**Verification:**
+How to confirm the fix works (test command, manual step, etc.).
+```
+
+---
+
+## Summary Report Structure
+
+```markdown
+## Review Summary
+
+**Branch:** feature/xyz → main
+**Files changed:** N
+**Commits reviewed:** M
+
+### Findings by Severity
+| Severity | Count |
+|----------|-------|
+| P0 Critical | 0 |
+| P1 High | 2 |
+| P2 Medium | 3 |
+| P3 Low | 4 |
+
+### Walkthrough
+<2–4 sentence summary of what this change does>
+
+---
+
+## Findings
+
+<findings ordered P0 → P3>
+
+---
+
+## Observations
+<pre-existing issues noticed but outside diff scope>
+
+---
+
+## Positive Notes
+<what was done well — optional but encouraged>
+```

package/core/safety-policy.md

@@ -0,0 +1,70 @@
+# Safety Policy
+
+> **Scope:** Universal — applies to every workflow and IDE.
+> **Trigger:** Always loaded alongside agent-principles.md.
+
+---
+
+## Destructive Action Protocol
+
+Before executing any action that is **irreversible or high-risk**, you must:
+
+1. **Identify** the action as destructive (see classification below).
+2. **State** clearly what you are about to do, what files or data will be affected.
+3. **Request explicit approval** using language such as:
+   > "This action will delete X. Please confirm by typing 'yes, proceed'."
+4. **Wait** for the user's written confirmation before proceeding.
+5. **Abort** if confirmation is ambiguous or absent.
+
+---
+
+## Destructive Action Classification
+
+### Always Requires Confirmation
+- Deleting files or directories.
+- Dropping database tables, collections, or indexes.
+- Running `git reset --hard`, `git clean -fd`, or similar destructive Git commands.
+- Overwriting a file that the user may have modified manually.
+- Running `rm`, `rmdir`, `del`, or equivalent destructive shell commands.
+- Disabling or removing authentication or authorization checks.
+- Modifying production environment variables or secrets.
+
+### Requires Scope Confirmation
+- Making changes to more than 5 files in a single operation.
+- Modifying CI/CD pipeline definitions.
+- Changing database migration files after they have been applied.
+- Altering shared library code that affects multiple services.
+
+### Never Permitted (No Override)
+- Automatically pushing to `main`, `master`, `production`, or `release` branches.
+- Automatically merging pull requests.
+- Executing deployment commands.
+- Accessing or logging credentials, tokens, or private keys.
+- Making HTTP requests to external services without user awareness.
+
+---
+
+## Credential Safety
+
+- Never read `.env`, `*.key`, `*.pem`, `secrets.yaml`, or similar files for any reason other than confirming their existence.
+- Never print, log, or include credential values in reports or responses.
+- When referencing configuration that contains credentials, refer only to the key name, not the value.
+
+---
+
+## Conflict Detection
+
+When the installation CLI detects that a target file already exists and may have been user-modified:
+1. Show a diff between the existing file and the new version.
+2. Ask the user to choose: `keep`, `overwrite`, `merge`, or `skip`.
+3. Never silently overwrite.
+
+---
+
+## Audit Trail
+
+For every file modified during an implementation workflow, the agent must:
+- State the file path.
+- State the nature of the change (added / modified / deleted).
+- State the reason for the change.
+- Not proceed to the next file until the current change is confirmed or the user has acknowledged the plan.

package/core/severity-levels.md

@@ -0,0 +1,104 @@
+# Severity Classification
+
+> **Scope:** Universal — used by all review and audit workflows.
+
+---
+
+## Severity Levels
+
+### P0 — Critical
+
+**Definition:** The issue will cause data loss, security breach, service outage, or financial loss in production under normal or near-normal usage. Requires immediate attention before merge.
+
+**Characteristics:**
+- Exploitable without special access or knowledge.
+- Data corruption or exposure of sensitive user information.
+- Authentication bypass or privilege escalation.
+- Production crash under expected load.
+- Irreversible data deletion triggered by common operations.
+
+**Examples:**
+- SQL injection in a user-facing query.
+- Password stored in plaintext.
+- Missing authorization check on an admin endpoint.
+- Division by zero in payment calculation.
+- Database write without transaction in a critical multi-step operation.
+
+---
+
+### P1 — High
+
+**Definition:** The issue causes incorrect behavior, significant security weakness, or degraded reliability. Likely to impact users or data correctness. Must be fixed before merge unless risk is explicitly accepted.
+
+**Characteristics:**
+- Incorrect business logic that affects real users.
+- Security weakness requiring non-trivial exploitation.
+- Data integrity risk under moderate load or concurrency.
+- Unhandled error that causes visible failure to users.
+
+**Examples:**
+- N+1 query that will cause timeout at production scale.
+- Missing CSRF protection on a state-changing form.
+- Race condition in inventory or booking logic.
+- Sensitive data included in API response unnecessarily.
+- Exception swallowed silently, hiding errors.
+
+---
+
+### P2 — Medium
+
+**Definition:** The issue degrades quality, maintainability, or reliability without immediate user impact. Should be fixed in this PR or tracked in a follow-up task.
+
+**Characteristics:**
+- Logic that works now but is fragile or will fail under edge cases.
+- Missing error handling that may surface under unusual conditions.
+- Performance issue that is not yet bottlenecking but will under growth.
+- Code that violates architectural patterns in a way that creates technical debt.
+
+**Examples:**
+- Missing input validation on a non-critical field.
+- Hardcoded configuration value that should be an environment variable.
+- Missing index for a new query pattern on a small-but-growing table.
+- Function exceeding 60 lines doing multiple things.
+
+---
+
+### P3 — Low
+
+**Definition:** Minor quality, style, or documentation issue. No functional impact. Consider fixing as a habit.
+
+**Characteristics:**
+- Code style inconsistency.
+- Unhelpful variable names.
+- Missing docblock on a public method.
+- Redundant code with no behavioral effect.
+- Typos in comments or strings.
+
+**Examples:**
+- Variable named `$temp` or `$data` without context.
+- Missing return type declaration.
+- Commented-out code left in without explanation.
+
+---
+
+## Severity Assignment Rules
+
+1. **Default to lower severity** when evidence is incomplete.
+2. **Upgrade to higher severity** only when you can demonstrate a concrete exploit or failure path.
+3. **Security issues start at P1** unless they are trivially unexploitable, in which case P2.
+4. **Data loss issues are always P0.**
+5. **Style and naming issues are always P3.**
+6. **Never report a P0 or P1 without code-level evidence.**
+
+---
+
+## Effort Estimates (Optional in Reports)
+
+Optionally classify fixes by implementation effort:
+
+| Label | Meaning |
+|-------|---------|
+| `XS`  | 1–5 minutes, one-liner fix |
+| `S`   | 15–30 minutes, small change |
+| `M`   | 1–4 hours, moderate refactor |
+| `L`   | Half a day or more, requires planning |

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "ai-dev-starter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Universal AI Development Starter Kit for Google Antigravity, Cursor, and modern AI coding IDEs. Production-quality workflows for code review, bug fixing, refactoring, and security auditing without separate LLM API keys.",
+  "main": "scripts/ai-dev-starter.js",
+  "bin": {
+    "ai-dev-starter": "bin/ai-dev-starter.js"
+  },
+  "files": [
+    "core",
+    "workflows",
+    "standards",
+    "adapters",
+    "templates",
+    "scripts",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "preferGlobal": true,
+  "scripts": {
+    "test": "node tests/test-installer.js"
+  },
+  "keywords": [
+    "antigravity",
+    "cursor",
+    "ai-agent",
+    "agent-skills",
+    "skills",
+    "code-review",
+    "pr-agent",
+    "vibe-coding",
+    "workflows",
+    "security-audit",
+    "developer-experience"
+  ],
+  "author": "AI Dev Starter Contributors",
+  "license": "MIT"
+}