codingwithagent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nitish Kafle
+
+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.

package/README.md

@@ -0,0 +1,37 @@
+# 🤖 Agentic Code Standards
+
+**Production-ready coding standards and best practices for AI coding agents**
+
+Stop fighting with inconsistent AI code output. Get enterprise-grade standards that work across **all major AI coding tools** — Cursor, Windsurf, Google Antigravity, GitHub Copilot, Cline, and more.
+
+## 🎯 What You Get
+
+- ♿ **Accessibility-First**: WCAG 2.1 AA+ compliance built-in
+- ⚛️ **Modern Stack**: React, TypeScript, Node.js, Python best practices
+- 🧪 **Testing Ready**: Unit, integration, E2E testing standards
+- 🔒 **Security**: OpenSSF-aligned secure coding practices
+- 📊 **Code Quality**: Maintainable, scalable patterns from day one
+- 🌍 **Universal**: One standard, every AI coding agent
+
+## 🚀 Quick Start
+
+# Using npx (no installation needed!)
+
+```bash
+npx codingwithagent init
+```
+
+# Or install globally
+
+```
+npm i -g codingwithagent
+codingwithagent init
+```
+
+## Choose your setup:
+
+- Minimal (essential rules only)
+- Standard (recommended baseline) ⭐
+- Strict (all rules enforced)
+- Accessibility-focused
+- Custom (pick and choose)

package/bin/init.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+/**
+ * Agentic Code Standards CLI
+ * Interactive installer for AI coding agent standards
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function header() {
+  console.log('');
+  log('🤖 Agentic Code Standards', 'cyan');
+  log('━'.repeat(60), 'cyan');
+  log('Production-ready standards for AI coding agents', 'bright');
+  console.log('');
+}
+
+function detectAITool() {
+  const cwd = process.cwd();
+  
+  if (fs.existsSync(path.join(cwd, '.cursorrules'))) return 'cursor';
+  if (fs.existsSync(path.join(cwd, '.windsurfrules'))) return 'windsurf';
+  if (fs.existsSync(path.join(cwd, '.agent'))) return 'antigravity';
+  if (fs.existsSync(path.join(cwd, '.github', 'copilot-instructions.md'))) return 'copilot';
+  
+  return null;
+}
+
+function question(prompt) {
+  return new Promise((resolve) => {
+    rl.question(`${colors.bright}${prompt}${colors.reset} `, resolve);
+  });
+}
+
+async function selectProfile() {
+  console.log('');
+  log('📋 Choose your profile:', 'blue');
+  console.log('');
+  log('  1. Minimal        Essential rules only (great for getting started)');
+  log('  2. Standard       Recommended baseline ⭐ (most popular)');
+  log('  3. Strict         All rules enforced (maximum code quality)');
+  log('  4. Accessibility  WCAG 2.1+ focused (a11y priority)');
+  console.log('');
+  
+  const answer = await question('Enter number (1-4) [default: 2]:');
+  const choice = answer.trim() || '2';
+  
+  const profiles = {
+    '1': 'minimal',
+    '2': 'standard',
+    '3': 'strict',
+    '4': 'accessibility'
+  };
+  
+  return profiles[choice] || 'standard';
+}
+
+async function selectTool() {
+  const detected = detectAITool();
+  
+  if (detected) {
+    console.log('');
+    log(`✅ Detected: ${detected.charAt(0).toUpperCase() + detected.slice(1)}`, 'green');
+    const answer = await question(`Continue with ${detected}? (Y/n):`);
+    if (!answer.trim() || answer.toLowerCase() === 'y') {
+      return detected;
+    }
+  }
+  
+  console.log('');
+  log('🛠️  Select your AI coding tool:', 'blue');
+  console.log('');
+  log('  1. Cursor           (.cursorrules)');
+  log('  2. Windsurf         (.windsurfrules)');
+  log('  3. Antigravity      (.agent/rules/)');
+  log('  4. GitHub Copilot   (.github/copilot-instructions.md)');
+  log('  5. Universal        Works with most tools ⭐');
+  console.log('');
+  
+  const answer = await question('Enter number (1-5) [default: 5]:');
+  const choice = answer.trim() || '5';
+  
+  const tools = {
+    '1': 'cursor',
+    '2': 'windsurf',
+    '3': 'antigravity',
+    '4': 'copilot',
+    '5': 'universal'
+  };
+  
+  return tools[choice] || 'universal';
+}
+
+function copyTemplate(profile, tool) {
+  const templatesDir = path.join(__dirname, '..', 'templates');
+  const cwd = process.cwd();
+  
+  try {
+    if (tool === 'antigravity') {
+      // Copy Antigravity .agent/rules/ structure
+      const sourceDir = path.join(templatesDir, 'antigravity', profile, '.agent', 'rules');
+      const targetDir = path.join(cwd, '.agent', 'rules');
+      
+      if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+      }
+      
+      const files = fs.readdirSync(sourceDir);
+      files.forEach(file => {
+        fs.copyFileSync(
+          path.join(sourceDir, file),
+          path.join(targetDir, file)
+        );
+      });
+      
+      console.log('');
+      log(`✨ Created .agent/rules/ with ${profile} profile`, 'green');
+      log(`   Files: ${files.join(', ')}`, 'cyan');
+      
+    } else if (tool === 'copilot') {
+      const sourceFile = path.join(templatesDir, profile, '.cursorrules');
+      const targetDir = path.join(cwd, '.github');
+      const targetFile = path.join(targetDir, 'copilot-instructions.md');
+      
+      if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+      }
+      
+      fs.copyFileSync(sourceFile, targetFile);
+      
+      console.log('');
+      log(`✨ Created .github/copilot-instructions.md with ${profile} profile`, 'green');
+      
+    } else {
+      const sourceFile = path.join(templatesDir, profile, '.cursorrules');
+      let targetFile;
+      
+      if (tool === 'windsurf') {
+        targetFile = path.join(cwd, '.windsurfrules');
+      } else {
+        targetFile = path.join(cwd, '.cursorrules');
+      }
+      
+      fs.copyFileSync(sourceFile, targetFile);
+      
+      console.log('');
+      log(`✨ Created ${path.basename(targetFile)} with ${profile} profile`, 'green');
+    }
+    
+    return true;
+  } catch (error) {
+    console.log('');
+    log(`❌ Error: ${error.message}`, 'red');
+    return false;
+  }
+}
+
+function showNextSteps(tool, profile) {
+  console.log('');
+  log('🎉 Setup complete!', 'green');
+  console.log('');
+  log('Next steps:', 'bright');
+  log('  1. Review your rules file(s)');
+  log('  2. Customize for your project needs');
+  log('  3. Start coding with your AI agent!');
+  console.log('');
+  
+  log('📚 Documentation:', 'blue');
+  log('  https://github.com/netshdev/codingwithagent');
+  console.log('');
+  
+  if (tool === 'antigravity') {
+    log('💡 Tip: Antigravity auto-loads rules from .agent/rules/', 'yellow');
+  } else if (tool === 'copilot') {
+    log('💡 Tip: Copilot reads instructions from .github/copilot-instructions.md', 'yellow');
+  } else {
+    log('💡 Tip: Your AI agent will automatically use these rules', 'yellow');
+  }
+  
+  console.log('');
+  log('⭐ Star us on GitHub if this helped!', 'cyan');
+  console.log('');
+}
+
+async function main() {
+  try {
+    header();
+    
+    const profile = await selectProfile();
+    const tool = await selectTool();
+    
+    console.log('');
+    log('⚙️  Installing...', 'cyan');
+    
+    const success = copyTemplate(profile, tool);
+    
+    if (success) {
+      showNextSteps(tool, profile);
+    }
+    
+    rl.close();
+    process.exit(success ? 0 : 1);
+    
+  } catch (error) {
+    console.log('');
+    log(`❌ Error: ${error.message}`, 'red');
+    log('Please report this issue on GitHub', 'yellow');
+    rl.close();
+    process.exit(1);
+  }
+}
+
+// Handle command line args
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === 'init') {
+  main();
+} else if (args[0] === '--version' || args[0] === '-v') {
+  const packageJson = require('../package.json');
+  console.log(packageJson.version);
+  process.exit(0);
+} else if (args[0] === '--help' || args[0] === '-h') {
+  console.log('');
+  log('Usage: npx codingwithagent [command]', 'cyan');
+  console.log('');
+  log('Commands:');
+  log('  init              Initialize standards (default)');
+  log('  --version, -v     Show version');
+  log('  --help, -h        Show this help');
+  console.log('');
+  process.exit(0);
+} else {
+  log('Unknown command. Use --help for usage information.', 'red');
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "codingwithagent",
+  "version": "1.0.0",
+  "description": "Production-ready coding standards for AI coding agents. Works with Cursor, Windsurf, Antigravity, and GitHub Copilot.",
+  "main": "bin/init.js",
+  "bin": {
+    "codingwithagent": "./bin/init.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "node -e \"console.log('Publishing codingwithagent...')\"",
+    "postinstall": "echo 'Run: npx codingwithagent init'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netshdev/codingwithagent.git"
+  },
+  "keywords": [
+    "ai",
+    "coding-standards",
+    "cursor",
+    "windsurf",
+    "antigravity",
+    "copilot",
+    "accessibility",
+    "wcag",
+    "react",
+    "typescript",
+    "code-quality",
+    "best-practices",
+    "a11y",
+    "linting",
+    "development",
+    "productivity",
+    "cursorrules",
+    "windsurfrules"
+  ],
+  "author": "Nitish Kafle <kaflenit@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/netshdev/codingwithagent/issues"
+  },
+  "homepage": "https://github.com/netshdev/codingwithagent#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {}
+}

package/templates/accessibility/.cursorrules

@@ -0,0 +1,342 @@
+# Agentic Code Standards - Accessibility-Focused Profile
+
+# Version: 1.0.0
+
+# Profile: WCAG 2.1+ priority - accessibility first
+
+## Mission
+
+Every user, regardless of ability, deserves equal access to your application. This profile prioritizes accessibility above all else while maintaining code quality.
+
+## WCAG 2.1 Level AA Compliance (Minimum)
+
+### Perceivable - Everyone Can "See" This
+
+#### Text Alternatives
+
+- ALL images MUST have alt text (or alt="" if decorative)
+- Complex images (charts, diagrams) MUST have detailed descriptions
+- Icons with meaning MUST have accessible labels
+- Decorative images MUST have empty alt attributes
+
+#### Multimedia
+
+- ALL videos MUST have captions
+- ALL audio content MUST have transcripts
+- Captions MUST be accurate and synchronized
+- Audio descriptions MUST be provided for visual-only content
+
+#### Adaptable Content
+
+- Use semantic HTML (nav, main, header, footer, article, section)
+- Proper heading hierarchy (h1 → h2 → h3, no skipping)
+- Meaningful landmarks for screen reader navigation
+- Reading order MUST match visual order
+- Content MUST be understandable when CSS is disabled
+
+#### Distinguishable
+
+- **Color Contrast Requirements:**
+  - Normal text: 4.5:1 minimum (7:1 for AAA)
+  - Large text (18pt+ or 14pt+ bold): 3:1 minimum
+  - UI components and graphics: 3:1 minimum
+  - Use Color Contrast Analyzer tool
+- NEVER use color alone to convey information
+- Add patterns, icons, or text in addition to color
+- Audio MUST have option to pause/stop
+- No auto-playing audio >3 seconds
+
+### Operable - Everyone Can Use This
+
+#### Keyboard Accessible
+
+- ALL functionality MUST work with keyboard only
+- Visible focus indicators REQUIRED (2px outline minimum)
+- Focus order MUST be logical and intuitive
+- NO keyboard traps (user can always escape)
+- NEVER use `tabIndex > 0`
+- Support standard keys: Tab, Enter, Space, Escape, Arrow keys
+
+#### Enough Time
+
+- NO time limits unless:
+  - User can turn off the limit
+  - User can adjust limit to 10x default
+  - User is warned and given 20 seconds to extend
+- Provide pause/stop for moving content
+- Auto-updates MUST have controls
+
+#### Seizures and Physical Reactions
+
+- NOTHING flashes more than 3 times per second
+- Avoid large flashing areas
+- Provide warnings for flashing content
+- Animation MUST respect `prefers-reduced-motion`
+
+#### Navigable
+
+- Skip navigation links for keyboard users
+- Descriptive page titles
+- Meaningful link text (avoid "click here", "read more")
+- Multiple ways to find pages (search, sitemap, navigation)
+- Clear focus indicators
+- Breadcrumbs for complex navigation
+
+### Understandable - Everyone Can Comprehend This
+
+#### Readable
+
+- Set language of page: `<html lang="en">`
+- Set language of parts: `<span lang="es">Hola</span>`
+- Use plain language (8th grade reading level or below)
+- Define unusual words and abbreviations
+- Expansion available for abbreviations
+
+#### Predictable
+
+- Consistent navigation across pages
+- Consistent identification (icons, buttons)
+- NO automatic context changes on focus
+- NO automatic context changes on input (without warning)
+- Forms submit ONLY on explicit action
+
+#### Input Assistance
+
+- Labels for ALL form inputs
+- Clear error messages with suggestions
+- Error prevention for legal/financial/data transactions
+- Confirmation pages for submissions
+- Ability to review and correct before final submission
+
+### Robust - All Devices Can Use This
+
+#### Compatible
+
+- Valid HTML (pass W3C validator)
+- Proper ARIA attributes when needed
+- Name, role, value for all UI components
+- Status messages programmatically determinable
+- Works with assistive technologies
+- Test with NVDA, JAWS, VoiceOver, TalkBack
+
+## ARIA - Use Carefully
+
+### When to Use ARIA
+
+- Only when semantic HTML isn't sufficient
+- Custom widgets (tabs, accordions, modals)
+- Live regions for dynamic content
+- Relationship indicators
+
+### ARIA Rules
+
+1. First Rule of ARIA: Don't use ARIA (use semantic HTML first)
+2. Never change semantic meaning
+3. All interactive ARIA controls must be keyboard accessible
+4. Don't hide visible and actionable elements from screen readers
+5. All interactive elements must have an accessible name
+
+### Common ARIA Patterns
+
+- `role="button"` - Only if you can't use `<button>`
+- `aria-label` - Provide name when visual label isn't present
+- `aria-labelledby` - Associate existing label
+- `aria-describedby` - Additional description
+- `aria-live` - Announce dynamic content changes
+- `aria-expanded` - State of collapsible content
+- `aria-hidden="true"` - Hide decorative elements
+
+## Forms Accessibility
+
+### Form Field Requirements
+
+- ALL inputs MUST have associated `<label>` elements
+- Use `<label for="inputId">` or wrap input
+- Required fields MUST be indicated (not just with color/asterisk)
+- Error messages MUST be programmatically associated
+- Validation MUST happen on blur or submit, not on input
+
+### Form Patterns
+
+```javascript
+// Good: Associated label
+<label htmlFor="email">Email Address *</label>
+<input id="email" type="email" required aria-describedby="email-help" />
+<small id="email-help">We'll never share your email</small>
+
+// Good: Error handling
+<input
+  id="email"
+  type="email"
+  aria-invalid={hasError}
+  aria-describedby="email-error"
+/>
+{hasError && <p id="email-error" role="alert">Please enter a valid email</p>}
+```
+
+### Form Validation
+
+- Inline validation on blur
+- Clear error messages with solutions
+- Error summary at top of form
+- Focus management to first error
+- Success confirmation
+
+## React Accessibility
+
+### Component Requirements
+
+- Semantic HTML elements preferred over divs
+- Button elements for actions, links for navigation
+- Proper heading hierarchy maintained
+- Focus management in modals and dynamic content
+- Announce dynamic content with aria-live
+
+### Focus Management
+
+```javascript
+// Good: Focus management in modal
+useEffect(() => {
+  if (isOpen) {
+    modalRef.current?.focus();
+  }
+}, [isOpen]);
+
+// Good: Trap focus in modal
+const handleKeyDown = (e) => {
+  if (e.key === "Escape") closeModal();
+  if (e.key === "Tab") trapFocus(e);
+};
+```
+
+### Live Regions
+
+```javascript
+// Good: Announce loading state
+<div role="status" aria-live="polite" aria-atomic="true">
+  {isLoading ? "Loading..." : `${results.length} results found`}
+</div>
+```
+
+## Testing Requirements
+
+### Automated Testing
+
+- axe-core or jest-axe in unit tests
+- Lighthouse accessibility audit (score 100)
+- pa11y or similar in CI/CD
+- ESLint jsx-a11y plugin enabled
+
+### Manual Testing
+
+1. Keyboard navigation (Tab, Enter, Space, Escape)
+2. Screen reader testing:
+   - NVDA (Windows - free)
+   - JAWS (Windows - paid)
+   - VoiceOver (Mac/iOS - built-in)
+   - TalkBack (Android - built-in)
+3. Color contrast analyzer
+4. Zoom to 200% (text must remain readable)
+5. Browser with CSS disabled
+6. prefers-reduced-motion testing
+
+### Testing Checklist
+
+- [ ] All functionality keyboard accessible
+- [ ] Visible focus indicators
+- [ ] Logical focus order
+- [ ] Screen reader announces content correctly
+- [ ] Color contrast passes
+- [ ] Alt text for images
+- [ ] Form labels associated
+- [ ] Error messages clear
+- [ ] No automatic timeouts
+- [ ] No flashing content
+- [ ] Semantic HTML used
+- [ ] Zoom to 200% works
+
+## Code Examples
+
+### Accessible Button
+
+```javascript
+// Good: Semantic button
+<button onClick={handleClick} aria-pressed={isPressed}>
+  Toggle {isPressed ? 'On' : 'Off'}
+</button>
+
+// Bad: Div as button
+<div onClick={handleClick}>Click me</div>
+```
+
+### Accessible Modal
+
+```javascript
+const Modal = ({ isOpen, onClose, children }) => {
+  const modalRef = useRef();
+
+  useEffect(() => {
+    if (isOpen) {
+      modalRef.current?.focus();
+    }
+  }, [isOpen]);
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="modal-title"
+      ref={modalRef}
+      tabIndex={-1}
+      onKeyDown={(e) => e.key === "Escape" && onClose()}
+    >
+      <h2 id="modal-title">Modal Title</h2>
+      {children}
+      <button onClick={onClose}>Close</button>
+    </div>
+  );
+};
+```
+
+### Accessible Navigation
+
+```javascript
+<nav aria-label="Main navigation">
+  <ul>
+    <li>
+      <a href="/" aria-current={isHome && "page"}>
+        Home
+      </a>
+    </li>
+    <li>
+      <a href="/about">About</a>
+    </li>
+    <li>
+      <a href="/contact">Contact</a>
+    </li>
+  </ul>
+</nav>
+```
+
+## Resources
+
+### Guidelines
+
+- WCAG 2.1: https://www.w3.org/WAI/WCAG21/quickref/
+- ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
+- WebAIM: https://webaim.org/
+
+### Testing Tools
+
+- axe DevTools: https://www.deque.com/axe/devtools/
+- WAVE: https://wave.webaim.org/
+- Color Contrast Analyzer: https://www.tpgi.com/color-contrast-checker/
+
+### Screen Readers
+
+- NVDA (free): https://www.nvaccess.org/
+- VoiceOver: Built into Mac/iOS
+- TalkBack: Built into Android
+
+Accessibility is not optional.
+Full documentation: https://github.com/netshdev/codingwithagent