multimodel-dev-os 0.3.0 → 0.5.1

package/docs/comparison.md

@@ -0,0 +1,33 @@
+# Comparison Guide: multimodel-dev-os vs. Alternatives
+
+Selecting how to manage AI instructions inside a codebase significantly impacts developer speed, token consumption, and context drift. This document contrasts `multimodel-dev-os` with standard configurations.
+
+## The Strategy Matrix
+
+| Feature | AGENTS.md Only (DIY) | Tool-Specific Prompt Packs | MultiModel Dev OS (`.ai/` + CLI) |
+| :--- | :--- | :--- | :--- |
+| **Tool Portability** | Manual copying when changing tools | Zero portability (highly vendor-locked) | **Portable & Vendor-Neutral** (Single source of truth) |
+| **Instruction Synchronization** | Manually synchronizing `.cursorrules`, `CLAUDE.md`, etc. | No synchronization (rules drift quickly) | **Automated** (Adapters mirror root rules instantly) |
+| **Token Optimization** | No budgeting (full rules read every time) | Vague, static rules | **Caveman Mode** (slashes token footprints by **~79%**) |
+| **Structural Segregation** | Flat single-file instructions (easily cluttered) | Disorganized configs | **Concise modular directories** (Context, Skills, Prompts, Checks) |
+| **CI/CD Quality Gates** | None (no structural safety checks) | None | **Verify subcommand** (`npm run verify` protects standard formats) |
+| **Standardized Hand-offs** | Manual human explanations | Manual human explanations | **Sequential hand-off protocol** with structured session logs |
+
+---
+
+## Detailed Evaluation
+
+### 1. The DIY Approach (AGENTS.md Only)
+Many developers start by dropping a single `AGENTS.md` file in their root. While better than nothing, this approach quickly breaks down:
+* **Drift:** You modify a build command in `AGENTS.md`, but forget to update Cursor's `.cursorrules`. Cursor continues running the old build script, causing confusing errors.
+* **Clutter:** A single markdown file gets bloated with styling guidelines, deployment procedures, and troubleshooting steps. Soon, the AI spends 10,000 tokens just reading instructions on every turn.
+
+### 2. Tool-Specific Prompt Packs
+Using tools like `Cursorrules` websites or Claude Code presets locks your project configuration into one vendor's ecosystem:
+* **Vendor Lock:** If your team uses Cursor for coding and Claude Code for debugging, you must duplicate and manually translate the syntax for both tools.
+* **No Collaboration:** Co-workers using different IDEs or terminal utilities cannot benefit from the unified context.
+
+### 3. MultiModel Dev OS
+`multimodel-dev-os` establishes a lightweight, vendor-neutral layer that decouples your project's rules from specific tools:
+* **Translate once, read everywhere:** You write build parameters once in the root. The CLI and adapters expose these configurations cleanly to Cursor, Claude, Antigravity, VS Code, and Codex.
+* **Continuous Integration:** You can add `multimodel-dev-os verify` to your CI pipeline or pre-commit hooks to guarantee that all developers share healthy, correctly-formatted AI configurations.

package/docs/faq.md

@@ -19,16 +19,23 @@ Not "multimodal" (multiple input types like text + image).
 ## Setup
 
 **Do I need Node.js?**
-No. The installer scripts use bash or PowerShell only.
-`package.json` is included for metadata and future CLI support.
+It depends on your installation path:
+* **Yes:** If you run the primary, recommended `npx multimodel-dev-os@latest init` workflow, Node.js is required.
+* **No:** If you run the fallback automated shell installer scripts (`install.sh` or `install.ps1`), they run purely on native bash or PowerShell and download resources directly.
+
+**Why not just write a single manual AGENTS.md myself?**
+While you can write a raw markdown instruction file manually, `multimodel-dev-os` offers a standardized development environment:
+1. **Automated Bridging:** Rather than copying and pasting rules into `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, and `.gemini/settings.json`, our adapters dynamically references your root source of truth.
+2. **Standardized Context Segregation:** Separates concerns cleanly (`MEMORY.md` for architectural context, `TASKS.md` for task state tracking, `RUNBOOK.md` for incident response, and `.ai/` for skills and prompts).
+3. **Structured Verification:** Pre-packaged CLI and verification scripts test and assert the structural completeness of your rules.
+4. **Token Savings:** Seamlessly switches into Caveman Mode to slash token footprints by **~79%** for smaller models.
 
 **Can I use just one AI tool?**
 Yes. Use a single adapter. The multi-agent features are optional.
 
 **Which files are required?**
 At minimum: `AGENTS.md`. Everything else is optional.
-The installer creates the full structure, but you can delete what you
-don't need.
+The installer creates the full structure, but you can delete what you don't need.
 
 ## Adapters
 
@@ -64,3 +71,13 @@ should coordinate. Runtime orchestration is planned for v0.2+.
 **Do I need the orchestrator for single-agent workflows?**
 No. The orchestrator is only relevant when multiple agents work
 on the same codebase.
+
+## Diagnostics & Validation
+
+**What is the difference between `validate` and `doctor`?**
+* **`validate`** is strict and verifies that your workspace strictly complies with the multimodel-dev-os directory schema. It checks for the existence of core files/directories and ensures enabled adapter rule references are not broken. If any checks fail, it exits with an error status (exit code 1).
+* **`doctor`** is advisory. It inspects compatibility constraints, warning you about potential context bloat (e.g. missing `.gitignore` files or non-ignored build directories) or active rules missing matching files. It reports warnings without blocking execution.
+
+**How do I view available scaffolding templates?**
+You can use `node bin/multimodel-dev-os.js templates` (or `list-templates`) to view all available tech stacks and detailed blueprints, or `show-template <name>` to inspect a specific template's specifications.
+

package/docs/installers.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Cross-platform scripts that scaffold multimodel-dev-os into any project. Located in `scripts/`.
+While `npx multimodel-dev-os@latest init` is the primary and recommended route to bootstrap your project, we provide cross-platform automated shell script installers as robust, dependency-free fallbacks for environments without Node.js. These are located in `scripts/`.
 
 ## Usage
 

package/docs/launch-kit.md

@@ -0,0 +1,99 @@
+# Public Launch & Social Sharing Kit
+
+Use these curated marketing templates and outlines to announce the release of `multimodel-dev-os` to developer communities.
+
+---
+
+## 1. Product Hunt Style Launch Info
+* **Product Tagline:** Portable, vendor-neutral project context for all your AI coding tools.
+* **Elevator Pitch:** Stop copy-pasting system instructions when switching between Cursor, Claude Code, Antigravity, and VS Code. Run a single command to sync, verify, and optimize your codebase context.
+
+---
+
+## 2. GitHub Repository Metadata
+* **Short Description:** Portable, vendor-neutral project configuration and CLI tool for AI coding agents. Think `.editorconfig` but optimized for LLMs, Cursor, Claude Code, and VS Code.
+* **Topics/Keywords:** `ai-dev-os`, `multi-agent`, `ai-coding`, `developer-tools`, `cursorrules`, `claude-code`, `antigravity`
+
+---
+
+## 3. X / Twitter Post (The Hook)
+```text
+Pair programming with AI is fast, until you switch tools. 
+
+You design architecture in Claude Code, implement locally in Cursor, and audit with Gemini. Every switch drops context, and rules start to drift.
+
+Stop copy-pasting. Say hello to multimodel-dev-os! 🧠
+
+npx multimodel-dev-os@latest init
+
+👉 Single source of truth for all tools (Cursor, Claude, VS Code, Gemini, Codex)
+👉 Slashing token consumption by up to ~79% with Caveman Mode
+👉 Strict CLI validation commands to protect context health
+👉 Fully vendor-neutral and zero-dependency
+
+Check it out: https://github.com/rizvee/multimodel-dev-os
+#AIDev #OpenSource #SoftwareEngineering #AItools
+```
+
+---
+
+## 4. LinkedIn Post (The Deep Dive)
+```text
+The hidden developer tax when coding with AI: Context Drift. 💸
+
+When pair programming with AI agents, we often switch between platforms to leverage their unique strengths:
+- Claude Code for terminal actions and system layouts
+- Cursor for local autocomplete and quick edits
+- Gemini / Antigravity for large-scale security and performance audits
+
+But there's a problem: every tool has its own custom settings, systems, and instructions files. You modify a build command in one place, forget to update it in another, and the agent breaks on compile. 
+
+To solve this, we are launching `multimodel-dev-os` — a portable, vendor-neutral operating configuration layer for AI coding tools.
+
+Think `.editorconfig` but designed for LLMs. 
+
+How it works:
+1. Initialize in seconds: `npx multimodel-dev-os@latest init`
+2. Configure your instructions in one root directory (AGENTS.md, MEMORY.md, TASKS.md)
+3. Zero-duplication adapters dynamically present these instructions to Cursor (.cursorrules), Claude (CLAUDE.md), VS Code, and Gemini.
+4. Slash token bills by up to ~79% using Caveman Mode for small-context turns.
+
+Fully open-source, zero-dependency, and built to keep your context aligned across every coding tool.
+
+GitHub: https://github.com/rizvee/multimodel-dev-os
+Let me know what you think in the comments! 👇
+```
+
+---
+
+## 5. Reddit-Style Post (/r/webdev, /r/LocalLLaMA)
+* **Title:** Show Show HN / Show Reddit: I built multimodel-dev-os — a vendor-neutral context management layer for Cursor, Claude Code, and VS Code.
+* **Content:**
+  Hey everyone,
+  
+  If you pair program with multiple AI tools, you've probably noticed how fast rules drift. You edit a command in your system prompts, but forget to update Cursor's `.cursorrules`, causing the model to continuously fail.
+  
+  I built **multimodel-dev-os** to solve this. It's a simple, zero-dependency CLI that scaffolds a unified context layout and uses lightweight adapters to route a single source of truth to all your tools.
+  
+  ### Key Features:
+  * **Primary Init:** Run `npx multimodel-dev-os@latest init` to bootstrap in 2 seconds.
+  * **Vendor-Neutral:** One config routes to Cursor (`.cursorrules`), Claude Code (`CLAUDE.md`), VS Code (`settings.json`), and Gemini/Antigravity (`settings.json`).
+  * **Caveman Mode:** Strips out examples and descriptions to save **~79% of tokens** when context budgets are tight.
+  * **Linter Guard:** Run `npx multimodel-dev-os@latest verify` to confirm structure health before pushing commits.
+  
+  Open-source and MIT licensed. I'd love to hear your feedback on the layout structure!
+  
+  GitHub: https://github.com/rizvee/multimodel-dev-os
+
+---
+
+## 6. Dev.to Article Outline
+* **Title:** Stop Copy-Pasting AI Prompts: How to Build a Portable Context Layer in Your Codebase
+* **Outline:**
+  1. **Introduction:** The multi-model developer reality (switching Cursor, Claude, Gemini).
+  2. **The Problem:** The "context synchronization tax" and rules drift.
+  3. **The Concept:** Decoupling rules from specific IDE extension configurations.
+  4. **Introducing multimodel-dev-os:** Setup in seconds using `npx multimodel-dev-os@latest init`.
+  5. **Deep Dive on Token Budgeting:** How Caveman Mode preserves structural intent while cutting token usage by ~79%.
+  6. **CI/CD Integration:** Adding `verify` commands to enforce healthy setups across team repositories.
+  7. **Conclusion & CTA:** Join the open-source project and build custom adapters.

package/docs/multimodel-workflow.md

@@ -104,18 +104,17 @@ Both: read shared MEMORY.md, coordinate via TASKS.md
 3. **Atomic tasks** — each agent completes a coherent unit before handing off
 4. **Single writer** — only one agent should modify a given file at a time
 
-## Limitations (v0.1)
+## Limitations (v0.3)
 
-- Manual enforcement only — no runtime checks
-- No automatic conflict detection
-- No real-time agent-to-agent messaging
-- Handoff logs must be written manually by the agent
+- Local structural audits and templates are automated, but active daemon runtime orchestrations are not yet implemented.
+- Handoff logs are structured but must be generated by agents/humans at task completion.
+- Real-time model-to-model active messaging is not supported.
 
 ## Roadmap
 
-| Version | Feature |
-|---------|---------|
-| v0.2 | CLI reads config and routes tasks |
-| v0.3 | Automatic session log generation |
-| v0.4 | Conflict detection |
-| v0.5 | Real-time coordination |
+| Version | Feature | Status |
+|---------|---------|--------|
+| v0.2.0 | Local CLI & stack templates | ✅ Completed |
+| v0.3.0 | npm / npx dynamic installer integrations | ✅ Completed |
+| v0.4.0 | Adapter automated synchronization (`sync`) | 📋 Planned |
+| v0.5.0 | Dynamic conflict assertions & daemon tracking | 📋 Planned |

package/docs/npm-publishing.md

@@ -12,13 +12,13 @@ Before publishing, always test the built package locally by compiling a compress
    ```bash
    npm pack
    ```
-   This creates a file named like `multimodel-dev-os-0.1.0.tgz` in your directory root.
+   This creates a file named like `multimodel-dev-os-0.3.0.tgz` in your directory root.
 
 2. **Verify bundle contents:**
    Create an empty temporary workspace, extract the tarball, and confirm that only required scaffold folders are included (no `.github/`, test configurations, or local system files):
    ```bash
    mkdir -p /tmp/package-test && cd /tmp/package-test
-   tar -xzf /path/to/multimodel-dev-os-0.1.0.tgz
+   tar -xzf /path/to/multimodel-dev-os-0.3.0.tgz
    ls -la package/
    ```
 

package/docs/quickstart.md

@@ -2,7 +2,24 @@
 
 Get multimodel-dev-os into your project in under 2 minutes.
 
-## Option A: One-Line Install
+## Option A: NPX Scaffolding (Recommended)
+
+Initialize any project immediately without local clones using our public npm registry:
+
+```bash
+# Standard interactive initialization in current directory
+npx multimodel-dev-os@latest init
+
+# Target specific stack templates and specific tool adapters
+npx multimodel-dev-os@latest init --template nextjs-saas --adapter cursor --adapter claude
+
+# Run a dry-run preview before executing file writes
+npx multimodel-dev-os@latest init --dry-run
+```
+
+## Option B: Fallback One-Line Scripts
+
+If you choose to run installation scripts directly:
 
 **macOS / Linux / WSL (bash):**
 ```bash
@@ -14,45 +31,38 @@ curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scrip
 irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.ps1 | iex
 ```
 
-## Option B: Manual Scaffolding
-
-```bash
-git clone https://github.com/rizvee/multimodel-dev-os.git /tmp/mmdos
-cp /tmp/mmdos/AGENTS.md    your-project/
-cp /tmp/mmdos/MEMORY.md    your-project/
-cp /tmp/mmdos/TASKS.md     your-project/
-cp /tmp/mmdos/RUNBOOK.md   your-project/
-cp /tmp/mmdos/.gitattributes your-project/
-cp -r /tmp/mmdos/.ai       your-project/
-```
-
 ## Option C: Caveman Mode (Minimal Tokens)
 
+Reduce token footprint by **~79%** with our lightweight variants:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --caveman
 ```
 
-## Option D: Node.js CLI Scaffolding (v0.2.0+)
+## Option D: Node.js Local Scaffolding CLI
 
-For a direct, highly customized local setup using our zero-dependency CLI utility:
+For offline execution or customized packaging within a cloned workspace:
 1. Clone this repository locally:
    ```bash
    git clone https://github.com/rizvee/multimodel-dev-os.git
    ```
-2. Run the CLI to scaffold into your target project:
+2. Run the CLI directly using the absolute target path:
    ```bash
    node bin/multimodel-dev-os.js init --target /path/to/your-project --template nextjs-saas --adapter cursor
    ```
 
-## Option E: npx Scaffolding (Planned v0.3.0+)
+## Option E: Manual Scaffolding
 
-Once published to the public npm registry, you can initialize any project globally without local clones using:
-```bash
-# General setup
-npx multimodel-dev-os init
+If you prefer absolute manual control over copying files:
 
-# Target specific layouts and templates
-npx multimodel-dev-os init --template nextjs-saas --adapter cursor
+```bash
+git clone https://github.com/rizvee/multimodel-dev-os.git /tmp/mmdos
+cp /tmp/mmdos/AGENTS.md    your-project/
+cp /tmp/mmdos/MEMORY.md    your-project/
+cp /tmp/mmdos/TASKS.md     your-project/
+cp /tmp/mmdos/RUNBOOK.md   your-project/
+cp /tmp/mmdos/.gitattributes your-project/
+cp -r /tmp/mmdos/.ai       your-project/
 ```
 
 ## After Install
@@ -65,15 +75,18 @@ npx multimodel-dev-os init --template nextjs-saas --adapter cursor
    - VS Code: `cp -r adapters/vscode/.vscode/ .vscode/`
 4. **Start coding** — your AI tools will read the shared config
 
-## Verify
+## Verify & Diagnose
 
-You can run our strict verification script to validate structural health:
+You can run our strict validation check or advisory doctor checkup to validate structural health:
 ```bash
-# Via CLI
-node bin/multimodel-dev-os.js verify --target /path/to/your-project
+# Strict directory schema validation
+node bin/multimodel-dev-os.js validate --target /path/to/your-project
 
-# Via verification shell script
-bash scripts/verify.sh
+# Advisory doctor workspace compatibility audit
+node bin/multimodel-dev-os.js doctor --target /path/to/your-project
+
+# Legacy verification script
+node bin/multimodel-dev-os.js verify --target /path/to/your-project
 ```
 
 ## Next Steps

package/docs/templates-guide.md

@@ -0,0 +1,65 @@
+# multimodel-dev-os Templates Guide
+
+`multimodel-dev-os` ships with 5 production-ready, stack-specific real-world templates that turn simple directories into structured developer profiles.
+
+## Available Templates
+
+### 1. `nextjs-saas`
+- **Stack:** Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Prisma ORM, Stripe payments
+- **Use Case:** Subscription-based applications and SaaS products.
+- **Skill File:** `.ai/skills/nextjs-action-build.md` (React Server Actions security guidelines).
+
+### 2. `wordpress-site`
+- **Stack:** WordPress Core, PHP, Gutenberg Block APIs, theme customization hooks, MySQL
+- **Use Case:** Headless or standard custom themes and plugins.
+- **Skill File:** `.ai/skills/plugin-boilerplate.md` (Sanitization gates and `$wpdb->prepare` queries).
+
+### 3. `ecommerce-store`
+- **Stack:** Headless Store API, cart states, secure payment webhooks (Stripe/Medusa)
+- **Use Case:** PCI-compliant headless e-commerce store with secure checkout loops.
+- **Skill File:** `.ai/skills/webhook-handler.md` (Payment webhooks listener auditing).
+
+### 4. `seo-landing-page`
+- **Stack:** Astro, HTML5, structured JSON-LD SEO markup, asset minification frameworks
+- **Use Case:** Ultra-fast static marketing and landing page layouts.
+- **Skill File:** `.ai/skills/seo-audit.md` (Google Lighthouse and Core Web Vitals optimization audit).
+
+### 5. `general-app`
+- **Stack:** Node.js, Express, ES6 Javascript, PostgreSQL, Jest
+- **Use Case:** Universal backend APIs, CLI tools, and default projects.
+- **Skill File:** `.ai/skills/example-skill.md` (Generic backend standard routing/validation rules).
+
+---
+
+## Scaffolding Directory Structure
+
+```
+├── AGENTS.md                   # Stack building conventions
+├── MEMORY.md                   # Architectural decisions record
+├── TASKS.md                    # Active task tracking
+├── RUNBOOK.md                  # Team operations runbook
+└── .ai/
+    ├── config.yaml             # Core adapters setup
+    ├── context/                # Context budgets & maps
+    │   ├── project-brief.md
+    │   ├── architecture.md
+    │   ├── model-map.md
+    │   └── context-budget.md
+    └── skills/                 # High-fidelity programming skills
+        └── [template-specific-skill].md
+```
+
+## CLI Configuration Commands
+
+To view and list templates directly from your shell:
+
+```bash
+# List all templates
+node bin/multimodel-dev-os.js templates
+
+# Inspect nextjs-saas layout details
+node bin/multimodel-dev-os.js show-template nextjs-saas
+
+# Bootstrap target using a template
+node bin/multimodel-dev-os.js init --target ../my-new-app --template nextjs-saas
+```

package/docs/use-cases.md

@@ -0,0 +1,39 @@
+# Use Cases & Stack Scaffolding
+
+`multimodel-dev-os` ships with pre-configured template profiles tailored for specific development environments. This guide explains how to leverage these profiles for maximum context-efficiency.
+
+---
+
+## 1. Next.js SaaS Stack
+Designed for modern web applications using the Next.js App Router, React, and TypeScript.
+* **Command:** `npx multimodel-dev-os@latest init --template nextjs-saas`
+* **Scaffolds:** Optimized `.ai/context/architecture.md` focusing on server components, edge routing, Prisma schema rules, and custom state boundaries.
+* **Benefits:** AI agents are instantly aligned on routing rules, avoiding common imports errors (e.g. Mixing server vs. Client components).
+
+## 2. Headless E-commerce Store
+Tailored for fast front-ends integrated with Shopify, Stripe, or MedusaJS.
+* **Command:** `npx multimodel-dev-os@latest init --template ecommerce-store`
+* **Scaffolds:** Context files defining critical payment gateways flow, secure Webhook signatures, and shopping cart session logic.
+* **Benefits:** Guides AI models to implement strict validation rules for sensitive checkout states without manual prompt injection.
+
+## 3. SEO Static Landing Page
+Optimized for high-performance static websites built with Astro, Hugo, or Tailwind CSS.
+* **Command:** `npx multimodel-dev-os@latest init --template seo-landing-page`
+* **Scaffolds:** Rules outlining Core Web Vitals targets, structured JSON-LD schemes, and image optimization constraints.
+* **Benefits:** Establishes automatic quality gates where the AI checks metadata structures before completing edits.
+
+## 4. WordPress Custom Site
+Built for PHP-based environments, custom plugins, and block theme architectures.
+* **Command:** `npx multimodel-dev-os@latest init --template wordpress-site`
+* **Scaffolds:** Strict configurations detailing WordPress coding standards, sanitization techniques (`esc_html`, `wp_kses`), and database queries structure.
+* **Benefits:** Prevents AI from writing insecure direct SQL statements or outdated styling actions.
+
+## 5. General Application Scaffolding
+The universal fallback layout for Python, Go, Rust, or general backend setups.
+* **Command:** `npx multimodel-dev-os@latest init --template general-app`
+* **Scaffolds:** High-level project specifications, basic memory structures, and generic agent build instructions.
+* **Benefits:** Fast, lightweight starting point for any software repository.
+
+---
+
+For a complete breakdown of all files, scaffolding structures, and custom developer skills included in each profile, refer to the [Templates Guide](templates-guide.md).

package/examples/ecommerce-store/.ai/config.yaml

@@ -1,4 +1,7 @@
-version: "0.1"
-project:
-  name: "ecommerce-headless-store"
-  mode: "standard"
+adapters:
+  cursor: false
+  claude: false
+  vscode: false
+mode: standard
+orchestrator:
+  mode: sequential

package/examples/ecommerce-store/.ai/context/architecture.md

@@ -0,0 +1,6 @@
+# E-commerce Store — Architecture Map
+
+## Directory Boundaries
+- `/services` — Inventory verification and payment orchestration classes.
+- `/api` — Checkout APIs and Stripe webhook routes.
+- `/storefront` — Next.js or Astro UI pages representing product collections.

package/examples/ecommerce-store/.ai/context/context-budget.md

@@ -0,0 +1,4 @@
+# E-commerce Store — Context Budget
+
+- Keep total context files under **15,000 tokens** per Turn.
+- Never pass large dependencies like `node_modules` or local databases into context.

package/examples/ecommerce-store/.ai/context/model-map.md

@@ -0,0 +1,4 @@
+# E-commerce Store — Model Map
+
+- **Claude / Antigravity:** Best for payment hooks creation and catalog database procedures.
+- **Cursor / Codex:** Best for cart state updates and layout presentation rules.

package/examples/ecommerce-store/.ai/context/project-brief.md

@@ -0,0 +1,3 @@
+# E-commerce Store — Project Brief
+
+This project is a headless e-commerce system that focuses on safe checkout states management, secure stripe webhook routing, and PCI-compliant inventory queries.

package/examples/ecommerce-store/.ai/skills/webhook-handler.md

@@ -0,0 +1,15 @@
+# Skill: Secure webhook endpoint implementation
+
+Use this skill when implementing a secure checkout webhook listener:
+
+1. **Verify Signatures:** Always verify the incoming payload signature using the webhook secret:
+   ```javascript
+   const event = stripe.webhooks.constructEvent(
+       req.body,
+       req.headers['stripe-signature'],
+       process.env.STRIPE_WEBHOOK_SECRET
+   );
+   ```
+2. **Replay Attack Mitigation:** Validate timestamp tolerances inside payload events.
+3. **Idempotency:** Implement idempotency gates in the database so that processing the same webhook event ID twice does not duplicate order entries.
+4. **Fast Response:** Return a `200 OK` status immediately before running heavy asynchronous background tasks to prevent Stripe from resending payloads.

package/examples/ecommerce-store/AGENTS.md

@@ -1,5 +1,18 @@
 # E-commerce Store — Agent Instructions
 
 project: ecommerce-headless-store
-stack: React, Next.js, Shopify Storefront API, Tailwind CSS
-description: High-performance headless e-commerce store implementation
+stack: MedusaJS, Stripe API, Node, React, Redis, Postgres
+description: Headless e-commerce system with Stripe checkout loops and cart state validations.
+
+## Build Commands
+```
+dev:   npm run dev
+build: npm run build
+test:  npm run test
+lint:  npm run lint
+```
+
+## Coding Conventions
+- **Language:** ES6 TypeScript/JavaScript.
+- **PCI-Compliance:** Never log or save raw credit card details on server logs; delegate billing operations strictly to Stripe.
+- **Cart Validation:** Validate all quantities and product variant IDs against the backend database before creating checkout sessions.

package/examples/ecommerce-store/MEMORY.md

@@ -1,4 +1,5 @@
-# E-commerce Store — Memory
+# E-commerce Store — Project Memory
 
-## Architecture Decisions
-- Integrated static generation ISR for product details pages.
+## Architectural Decisions
+- **Stripe Session Handlers:** Utilized Stripe checkout sessions directly to minimize custom database operations for token vaults.
+- **Webhook Security:** Configured secure, cryptographically validated stripe webhook receivers in order routers to mitigate replay attacks.

package/examples/ecommerce-store/TASKS.md

@@ -0,0 +1,10 @@
+# E-commerce Store — Starter Tasks
+
+- [ ] Catalog Setup & Inventory Check
+  - [ ] Set up basic MedusaJS product tables
+  - [ ] Implement cart inventory checks before checkout launches
+- [ ] Payment Integrations
+  - [ ] Securely integrate Stripe API endpoints for checkouts
+  - [ ] Write a secure webhook listener for checkout session payments
+- [ ] Deployment & PCI Verification
+  - [ ] Validate environment variable encryptions on deployment

package/examples/general-app/.ai/config.yaml

@@ -1,4 +1,7 @@
-version: "0.1"
-project:
-  name: "general-project-template"
-  mode: "standard"
+adapters:
+  cursor: false
+  claude: false
+  vscode: false
+mode: standard
+orchestrator:
+  mode: sequential

package/examples/general-app/.ai/context/architecture.md

@@ -0,0 +1,12 @@
+# Architecture Map
+
+```mermaid
+graph TD
+  Client[Client Layer] --> Router[Express Router]
+  Router --> Middleware[Sanitization & Auth Middleware]
+  Middleware --> Controllers[Route Controller Handlers]
+  Controllers --> Services[Business Logic Services]
+  Services --> Database[(PostgreSQL Pool)]
+```
+
+The system uses standard model-view-controller (MVC) inspired REST patterns for robust API separation of concerns.

package/examples/general-app/.ai/context/context-budget.md

@@ -0,0 +1,5 @@
+# General App — Context Budget
+
+- Keep total context files under **10,000 tokens** per prompt.
+- Never pass large dependencies directories like `node_modules` or local `build` artifacts into model prompts.
+- Consolidate file reads to avoid context bloating.

package/examples/general-app/.ai/context/model-map.md

@@ -0,0 +1,7 @@
+# Model Map
+
+Define LLM task allocations for the General App context:
+
+- **Coding & Implementation:** Gemini 3.5 Pro or Claude 3.5 Sonnet for precise code writing.
+- **Refactoring & Lint Fixing:** Gemini 3.5 Flash for rapid low-cost iteration loops.
+- **Validation & Auditing:** Claude 3.5 Sonnet for testing and code validation pipelines.

package/examples/general-app/.ai/context/project-brief.md

@@ -0,0 +1,6 @@
+# Project Brief
+
+This project acts as a general baseline application profile. It uses a lightweight Node.js/Express backend setup with relational PostgreSQL storage, designed for API microservices.
+- Ensure strict JSON validation.
+- Deliver secure backend routes.
+- Focus on clean modular architecture.

package/examples/general-app/.ai/skills/example-skill.md

@@ -0,0 +1,8 @@
+# Skill: Generic backend instructions and coding standards
+
+Use this skill when developing standard backend API endpoints or refactoring general application logic:
+
+1. **State Isolation:** Ensure clean separation of routing, middleware, controllers, and services.
+2. **Parameters validation:** Validate all HTTP incoming payloads (body, query, headers) using validator middleware.
+3. **Connection safety:** Ensure database connections are released back to pools even on errors.
+4. **Environment Isolation:** Never hardcode credentials. Retrieve secrets strictly from `process.env`.