🚀 AI WebApp Rules + Memory System

One-command setup for AI-powered web development with production-ready rules and intelligent memory.

✨ Features

📋 Engineering Rules

• ✅ Senior Architect workflow (8-step process)
• ✅ SOLID principles & Clean Code standards
• ✅ Frontend: Page/Container/Presentational architecture
• ✅ Backend: Controller/Service/Repository pattern
• ✅ Mandatory JSDoc & constants
• ✅ Security & validation best practices

🧠 Memory System

• ✅ Global memory (role, stack, preferences)
• ✅ Project memory (architecture, naming, domain rules)
• ✅ Stack policy enforcement (ask/warn/reject)
• ✅ Verbosity control (low/medium/high)
• ✅ Auto-validation & versioning
• ✅ Hybrid update workflow (manual + AI suggestions)

🚀 Quick Start

Installation

# Install globally
npm install -g ai-webapp-rules

# Or use npx
npx ai-webapp-rules

Setup (One Command)

# In your project directory
npx ai-webapp-rules

# Then setup memory
npm run memory:setup

That's it! 🎉

📋 What Gets Installed

your-project/
├── .agent/
│   ├── rules/                    # Engineering rules
│   │   ├── 01-workflow.md
│   │   ├── 02-engineering-standards.md
│   │   ├── 03-system-design.md
│   │   ├── 04-frontend.md
│   │   └── 05-backend.md
│   ├── workflows/                # Memory workflows
│   │   ├── one-command-setup.md
│   │   ├── setup-project-memory.md
│   │   └── update-memory.md
│   ├── templates/                # Templates
│   │   └── project-memory-template.md
│   ├── scripts/                  # Automation scripts
│   │   ├── setup-memory.js
│   │   └── validate-memory.js
│   ├── skill.yaml               # AI skill definition
│   ├── SKILL.md                 # Skill documentation
│   ├── README.md                # Memory system overview
│   ├── SETUP.md                 # Quick setup guide
│   └── ... (other docs)
└── package.json                 # Updated with memory scripts

🎯 Usage

Step 1: Install Rules + Memory System

npx ai-webapp-rules

Output:

🚀 AI WebApp Rules + Memory System Setup...

✅ Created directory: .agent
✅ Created directory: .agent/rules
   -> Copied rules/01-workflow.md
   -> Copied rules/02-engineering-standards.md
   ...
✅ Copied skill.yaml
✅ Copied SKILL.md

📦 Installing Memory System...
   -> Copied README.md
   -> Copied SETUP.md
   ...
✅ Memory system files installed

📝 Updating package.json...
✅ Added memory scripts to package.json

🎉 Success! AI Rules + Memory System installed!

📋 Next Steps:
   1. Setup memory: npm run memory:setup
   2. Copy .agent/user-rules-template.md to AI settings
   3. Ask AI: "load skills from .agent/skill.yaml"
   4. Ask AI: "Show current memory"

Step 2: Setup Memory

# Interactive (recommended)
npm run memory:setup

# Or quick mode (use defaults)
npm run memory:setup:quick

This will:

1. Ask for project info (name, type, stack, etc.)
2. Generate .agent/project-memory.md
3. Generate .agent/user-rules-template.md
4. Validate automatically

Step 3: Copy User Rules to AI

# View generated user rules
cat .agent/user-rules-template.md

# Copy entire content
# Paste into your AI assistant settings → Custom Instructions

Where to paste:

• Cursor/Windsurf: Settings → Rules for AI
• GitHub Copilot: Settings → Custom Instructions
• ChatGPT: Settings → Custom Instructions
• Claude: Project Knowledge

Step 4: Load Skills & Test

Ask your AI:

load skills from .agent/skill.yaml

Then test:

Show current memory

Expected response:

📋 Current Memory:
- Role: fullstack
- Stack: react, typescript, nodejs, express, mongodb
- Verbosity: medium
- Project: your-project-name
- Stack policy: ask before using unknown libs

🔧 Available Commands

After installation, you have these commands:

# Memory Management
npm run memory:setup              # Interactive setup
npm run memory:setup:quick        # Quick setup (no prompts)
npm run memory:validate           # Validate memory file
npm run memory:validate:verbose   # Validate with details
npm run memory:show               # Show current memory

📚 Documentation

| File | Purpose | |------|---------| | .agent/SETUP.md | Quick setup guide (START HERE) | | .agent/README.md | Memory system overview | | .agent/HOW_TO_RUN.md | Detailed guide | | .agent/QUICK_REFERENCE.md | Quick reference card | | .agent/rules/01-workflow.md | Engineering workflow | | .agent/SKILL.md | Skill documentation |

🎯 How It Works

Engineering Rules

The AI follows an 8-step workflow:

1. Requirements & Tech Selection - Confirm stack
2. Design (HLD) - Define architecture
3. Project Structure - Organize files
4. Checkpoint - Technical audit
5. Implementation - Atomic coding
6. Quality Gate - Self-review

Memory System

Global Memory (user-level):

• Role, stack, preferences
• Hard rules (no untested code, mandatory JSDoc)
• Forbidden libraries (jquery, moment, lodash)
• Stack policy (ask/warn/reject)

Project Memory (.agent/project-memory.md):

• Architecture patterns
• Naming conventions
• Domain rules
• Tech stack
• Allowed/forbidden libraries

AI Behavior:

• Auto-loads memory on every request
• Enforces stack policy
• Follows naming conventions
• Applies verbosity level
• Validates library usage

🧪 Examples

Test Stack Policy

User: "Use jquery for DOM manipulation"

AI: ❌ Cannot proceed.
Rule violated: libraries.forbidden includes 'jquery'
Alternative: Use React refs or vanilla JS
Reason: jQuery conflicts with React's virtual DOM

Test Verbosity Levels

User: remember: verbosity: low
User: "Create a button component"

AI (low verbosity - checklist only):
✅ Created Button.jsx
✅ Added styles
✅ Exported

User: remember: verbosity: medium
User: "Create a button component"

AI (medium verbosity - checklist + context):
✅ Created Button.jsx
   - PascalCase per convention
✅ Added styles
   - Styled-components for scoped CSS
✅ Exported
   - Named export for tree-shaking

Update Memory

User: remember:
  preferences.verbosity: low

AI: ✅ Memory updated
- preferences.verbosity: medium → low
- Version: 1.0.0 → 1.0.1
- Updated: 2026-01-19

🛠️ Tech Stack Support

Frontend

• React (18, 19)
• Next.js
• TypeScript
• Styled Components
• Vanilla CSS

Backend

• Node.js (ESM)
• Express
• NestJS
• MongoDB
• PostgreSQL
• Redis

Tools

• pnpm / npm / yarn / bun
• ESLint + Prettier
• Git

📦 Package Contents

This package includes:

• Engineering Rules: 5 comprehensive rule files
• Memory System: Complete memory management
• Workflows: Setup and update workflows
• Scripts: Automation scripts (setup, validate)
• Templates: Project memory template
• Documentation: Comprehensive guides

🤝 Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Follow the engineering rules in .agent/rules/
4. Submit a PR

📄 License

MIT

🔗 Links

• GitHub Repository
• NPM Package
• Documentation

✅ Success Checklist

After setup, verify:

• [ ] .agent/ directory created
• [ ] Rules installed in .agent/rules/
• [ ] Memory system files installed
• [ ] package.json updated with scripts
• [ ] npm run memory:setup completed
• [ ] User rules copied to AI settings
• [ ] AI loads skills: "load skills from .agent/skill.yaml"
• [ ] AI shows memory: "Show current memory"
• [ ] Stack policy works: Try "Use jquery" (should reject)
• [ ] Verbosity works: Try different levels

Happy coding with AI! 🚀