antigravity-ai-kit 3.3.1 → 3.4.0

package/.agent/engine/loading-rules.json

@@ -118,7 +118,7 @@
   },
   "workflowBindings": [
     { "workflow": "brainstorm", "loadAgents": [], "loadSkills": ["brainstorming"], "bindingType": "inferred" },
-    { "workflow": "quality-gate", "loadAgents": [], "loadSkills": ["brainstorming"], "bindingType": "inferred" },
+    { "workflow": "quality-gate", "loadAgents": [], "loadSkills": ["brainstorming"], "loadRules": ["quality-gate"], "bindingType": "inferred" },
     { "workflow": "plan", "loadAgents": ["planner"], "loadSkills": ["plan-writing", "brainstorming", "plan-validation"], "bindingType": "explicit" },
     { "workflow": "create", "loadAgents": [], "loadSkills": ["app-builder", "clean-code"], "bindingType": "inferred" },
     { "workflow": "enhance", "loadAgents": [], "loadSkills": ["clean-code", "testing-patterns"], "bindingType": "inferred" },
@@ -140,7 +140,7 @@
   ],
   "planningMandates": {
     "description": "Mandatory resources loaded for every /plan invocation regardless of keyword matching. Ensures cross-cutting concerns are never omitted.",
-    "alwaysLoadRules": ["security", "testing", "coding-style", "documentation"],
+    "alwaysLoadRules": ["security", "testing", "coding-style", "documentation", "architecture"],
     "alwaysLoadSkills": ["security-practices", "testing-patterns"],
     "crossCuttingSections": [
       "security-considerations",

package/.agent/manifest.json

@@ -88,6 +88,19 @@
         { "name": "test", "file": "workflows/test.md" },
         { "name": "ui-ux-pro-max", "file": "workflows/ui-ux-pro-max.md" }
       ]
+    },
+    "rules": {
+      "count": 8,
+      "items": [
+        { "name": "architecture", "file": "rules/architecture.md" },
+        { "name": "coding-style", "file": "rules/coding-style.md" },
+        { "name": "documentation", "file": "rules/documentation.md" },
+        { "name": "git-workflow", "file": "rules/git-workflow.md" },
+        { "name": "quality-gate", "file": "rules/quality-gate.md" },
+        { "name": "security", "file": "rules/security.md" },
+        { "name": "sprint-tracking", "file": "rules/sprint-tracking.md" },
+        { "name": "testing", "file": "rules/testing.md" }
+      ]
     }
   }
 }

package/.agent/rules/architecture.md

@@ -0,0 +1,111 @@
+# Architecture Rules
+
+> **Priority**: HIGH — Enforced in design reviews
+> **Scope**: All workspaces — universal architectural constraints
+
+---
+
+## Architecture Principles
+
+| Principle                | Enforcement                                                   |
+| :----------------------- | :------------------------------------------------------------ |
+| Separation of Concerns   | Each module has a single, well-defined responsibility         |
+| Dependency Direction     | Dependencies ALWAYS point inward — domain never imports infra |
+| Contract-First Design    | Define API contracts before implementation begins             |
+| Explicit Over Implicit   | Configuration, dependencies, and boundaries must be explicit  |
+| Composition Over Inherit | Prefer composition and dependency injection over inheritance  |
+
+---
+
+## Boundary Enforcement
+
+- **NEVER** import backend code from frontend or vice versa
+- **NEVER** skip architectural layers — each layer imports only from the layer directly below
+- **NEVER** hold direct object references across aggregate or module boundaries — use IDs
+- Shared types and contracts are defined at the API boundary and replicated per consumer
+- Cross-module communication uses events or explicit service interfaces, not direct coupling
+
+---
+
+## Project Structure
+
+Projects should follow one of these organizational patterns:
+
+| Pattern          | When to Use                                              |
+| :--------------- | :------------------------------------------------------- |
+| **Monorepo**     | Multiple apps sharing code (Turborepo, Nx, Rush)         |
+| **Polyrepo**     | Independent services with separate lifecycles            |
+| **Modular Mono** | Single deployable with clear bounded context separation  |
+
+> **Customization**: Project-specific structure decisions should be documented in `decisions/` as Architecture Decision Records (ADRs).
+
+---
+
+## Layered Architecture
+
+```
+Thin Routes / Controllers → Service Layer → Models / Data Access
+                              ↕
+                          Domain Logic
+```
+
+| Layer            | Responsibility                            | Rules                                              |
+| :--------------- | :---------------------------------------- | :------------------------------------------------- |
+| Routes           | HTTP handling, auth enforcement           | MAX 10 lines per handler, delegate to services      |
+| Services         | Business logic, validation, orchestration | Pure functions where possible, fully testable       |
+| Models / Data    | Database schema, relationships            | ORM-managed, migration-controlled                   |
+| Schemas          | Request/response contracts                | Validated models, explicit field constraints         |
+
+---
+
+## Database Conventions
+
+- **Migrations** for ALL schema changes — no manual SQL in production
+- Table names: `snake_case`, plural (`users`, `funnel_events`)
+- Column names: `snake_case`
+- Always include: `id` (UUID recommended), `created_at`, `updated_at`
+- Foreign keys: `<entity>_id` naming convention
+- Indexes: create for all foreign keys and frequent query columns
+- Soft deletes preferred over hard deletes for audit-sensitive data
+
+---
+
+## API Design Principles
+
+| Principle            | Standard                                                    |
+| :------------------- | :---------------------------------------------------------- |
+| Versioning           | URL-prefix (`/api/v1/`) or header-based — be consistent    |
+| Methods              | Standard HTTP methods and status codes (RESTful)            |
+| Response Format      | All endpoints return validated, structured JSON             |
+| Pagination           | Offset-based (`skip`/`limit`) or cursor-based — documented |
+| Error Format         | `{ "detail": "Human-readable message" }` minimum           |
+| Rate Limiting        | Documented per endpoint, enforced server-side               |
+
+---
+
+## Architecture Decision Records
+
+When making significant architectural decisions, document them using ADRs in the `decisions/` directory:
+
+- Choosing between architectural approaches (monolith vs microservices)
+- Selecting a technology (database, framework, library)
+- Establishing a pattern (event sourcing vs CRUD)
+- Making a trade-off (consistency vs availability)
+
+ADR format: `decisions/adr-NNN-<decision-title>.md`
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/architecture/SKILL.md` — deep architectural patterns (DDD, Clean Architecture, 12-Factor, SOLID)
+- **Agent**: `.agent/agents/architect.md` — architecture review process and checklists
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                                |
+| :------ | :--------- | :----------------------------------------------------- |
+| 1.0.0   | 2026-03-16 | Initial generic architecture enforcement rules for kit |
+

package/.agent/rules/quality-gate.md

@@ -0,0 +1,117 @@
+# Quality Gate Rules
+
+> **Priority**: HIGH — Enforced before implementation of new features and refactors
+> **Scope**: All workspaces — applies to `feat()` and `refactor()` tasks only
+
+---
+
+## Scope Filter
+
+| Task Type                         | Quality Gate Required? |
+| :-------------------------------- | :--------------------- |
+| `feat()` — new features           | ✅ Required            |
+| `refactor()` — structural changes | ✅ Required            |
+| `fix()` — bug fixes               | ❌ Skip                |
+| `chore()` — maintenance           | ❌ Skip                |
+| `docs()` — documentation          | ❌ Skip                |
+| `test()` — test additions         | ❌ Skip                |
+
+---
+
+## Pre-Execution Research Checklist
+
+Before implementing any in-scope task, **ALL** items must be completed. If any item is incomplete, execution is forbidden.
+
+### ☐ 1. Market Research Completed
+
+- Analyze **minimum 5** competitors or market leaders in the feature domain
+- Document how each implements the same or similar feature
+- Identify user adoption drivers: UX simplicity, accuracy, speed, transparency
+
+### ☐ 2. Outdated Pattern Verification
+
+- Verify the proposed approach does not use deprecated, abandoned, or criticized patterns
+- If outdated → propose a modern, evidence-based alternative (mandatory)
+- Document which patterns are considered harmful or legacy
+
+### ☐ 3. Baseline Parity Validation
+
+- Confirm the project **meets or exceeds** the current market baseline
+- Gaps must be explicitly listed with severity assessment
+- No gap left unaddressed without documented justification
+
+### ☐ 4. Enhancement Definition
+
+- Define exactly how the project **improves upon** the market baseline
+- Improvement must be intentional and documented
+- Consider: transparency, ethical automation, user-centricity, measurable outcomes
+
+### ☐ 5. Ethics & Automation Risk Assessment
+
+- Evaluate: privacy implications, AI bias risks, automation safety, user autonomy
+- Mitigation strategies must be documented for each identified risk
+- Data protection compliance must be considered for data-touching features
+
+### ☐ 6. Implementation Plan Prepared
+
+- Structured plan ready before execution begins
+- Plan includes research summary, key insights, risks, execution steps
+- Plan reviewed and approved before implementation may begin
+
+---
+
+## Enhancement Principle
+
+| Scenario                                    | Required Action                  |
+| :------------------------------------------ | :------------------------------- |
+| Competitors offer a standard                | **Meet or exceed** it            |
+| Competitors use unethical automation        | **Reject and improve**           |
+| Feature can be more transparent             | **Enhance by default**           |
+| Feature can be more user-centric            | **Enhance by default**           |
+| Feature can offer measurable outcomes       | **Enhance by default**           |
+
+**Never replicate patterns without improvement.**
+
+---
+
+## Cross-Cutting Deference
+
+Quality gate enforcement defers to specialized rules for domain-specific checks:
+
+- **Security**: See `rules/security.md` for input validation, auth, data protection
+- **Testing**: See `rules/testing.md` for coverage requirements, test types
+- **Code Quality**: See `rules/coding-style.md` for naming, file limits, immutability
+- **Documentation**: See `rules/documentation.md` for doc hierarchy, SSOT
+
+---
+
+## Reject & Escalate Rules
+
+| Condition                                   | Action                                 |
+| :------------------------------------------ | :------------------------------------- |
+| No market research provided                 | ❌ Reject — enforce research protocol  |
+| Clearly outdated or harmful patterns        | ❌ Reject — propose modern alternative |
+| Below-market standard solutions             | ❌ Reject — document gap               |
+| Ethics, privacy, or automation safety risks | ❌ Reject — document mitigation        |
+| Bypassing research ("just implement it")    | ❌ Reject — enforce protocol           |
+
+### Escalation Response
+
+> "This task cannot proceed in its current form, as it does not meet quality and market standards. Below are the identified risks and gaps. A revised, modern alternative is proposed."
+
+---
+
+## Related Resources
+
+- **Workflow**: `.agent/workflows/quality-gate.md` — step-by-step research procedure
+- **Skill**: `.agent/skills/brainstorming/SKILL.md` — Socratic questioning patterns
+- **Next Step**: After approval, proceed to `/plan` for implementation planning
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                           |
+| :------ | :--------- | :------------------------------------------------ |
+| 1.0.0   | 2026-03-16 | Initial generic quality gate protocol for kit     |
+

package/.agent/workflows/quality-gate.md

@@ -190,6 +190,7 @@ If any of these conditions are met, **REJECT** the task:
 
 ## Related Resources
 
+- **Rule**: `.agent/rules/quality-gate.md` (enforcement principles for this workflow)
 - **Previous**: `/brainstorm` (explore options before validation)
 - **Next**: `/plan` (implementation planning after approval)
 - **Related**: `/retrospective` (post-sprint audit applies similar rigor)

package/lib/verify.js

@@ -189,6 +189,32 @@ function runAllChecks(projectRoot) {
     results.push(checkJsonFile(path.join(agentDir, ENGINE_DIR, engineFile), `engine:${engineFile}`));
   }
 
+  // --- Check 10a: Rule files exist ---
+  const manifestRules = manifest.capabilities?.rules?.items || [];
+  for (const rule of manifestRules) {
+    const rulePath = path.join(agentDir, rule.file);
+    const exists = fs.existsSync(rulePath);
+    results.push({
+      name: `rule-file:${rule.name}`,
+      status: exists ? 'pass' : 'fail',
+      message: exists ? `Rule exists: ${rule.name}` : `Missing rule file: ${rule.file}`,
+    });
+  }
+
+  // --- Check 10b: Rule count matches ---
+  const ruleCountManifest = manifest.capabilities?.rules?.count || 0;
+  const ruleCountFS = fs.existsSync(path.join(agentDir, 'rules'))
+    ? fs.readdirSync(path.join(agentDir, 'rules')).filter((f) => f.endsWith('.md') && f !== 'README.md').length
+    : 0;
+  results.push({
+    name: 'rule-count',
+    status: ruleCountManifest === ruleCountFS ? 'pass' : 'fail',
+    message:
+      ruleCountManifest === ruleCountFS
+        ? `Rule count matches: ${ruleCountFS}`
+        : `Rule count mismatch: manifest=${ruleCountManifest}, filesystem=${ruleCountFS}`,
+  });
+
   // --- Check 11: Hooks file valid ---
   results.push(checkJsonFile(path.join(agentDir, HOOKS_DIR, 'hooks.json'), 'hooks-json'));
 
@@ -212,6 +238,19 @@ function runAllChecks(projectRoot) {
           });
         }
       }
+      // --- Check 13: Cross-reference — alwaysLoadRules files exist ---
+      const mandatoryRules = loadingRules.planningMandates?.alwaysLoadRules || [];
+      for (const ruleName of mandatoryRules) {
+        const rulePath = path.join(agentDir, 'rules', `${ruleName}.md`);
+        const ruleExists = fs.existsSync(rulePath);
+        results.push({
+          name: `xref:mandatory-rule:${ruleName}`,
+          status: ruleExists ? 'pass' : 'fail',
+          message: ruleExists
+            ? `Mandatory rule "${ruleName}" exists`
+            : `Mandatory rule "${ruleName}" referenced in alwaysLoadRules but file missing: rules/${ruleName}.md`,
+        });
+      }
     } catch {
       results.push({ name: 'xref:loading-rules', status: 'warn', message: 'Could not parse loading-rules.json for cross-reference check' });
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "antigravity-ai-kit",
-  "version": "3.3.1",
-  "description": "🚀 Trust-Grade AI development framework with a 29-module runtime engine — 19 Agents, 32 Skills, 31 Commands, 14 Workflows, 327 Tests. Workflow enforcement, task governance, agent reputation, self-healing, and skill marketplace.",
+  "version": "3.4.0",
+  "description": "🚀 Trust-Grade AI development framework with a 29-module runtime engine — 19 Agents, 32 Skills, 31 Commands, 14 Workflows, 8 Rules, 330 Tests. Workflow enforcement, task governance, agent reputation, self-healing, and skill marketplace.",
   "main": "bin/ag-kit.js",
   "bin": {
     "ag-kit": "./bin/ag-kit.js"