AGENTS.md — Coding Guidelines for Agentic Operations

This guide covers build/test commands, code style, and core rules for agents working in the Tidyco APQP repository.

Quick Commands

Testing

npm test                          # Run all Jest tests
npm test -- path/to/test.test.js  # Run a single test file
npm test -- --testNamePattern="name"  # Run tests matching a pattern
npm run check:all                 # Full validation suite (see below)

Validation & Checks

npm run check:load-order          # Verify script load order in index.html
npm run check:syntax              # Validate JavaScript syntax
npm run check:rls                 # Audit RLS policies
npm run check:subscriptions       # Check realtime cleanup
npm run check:mobile              # Verify mobile breakpoints
npm run check:modals              # Audit modal state handling
npm run check:state               # Track global state variables
npm run check:coverage            # Generate test coverage report

Linting & Formatting (NPI portal only)

npm run lint:npi                  # Run ESLint on NPI portal
npm run format:npi                # Run Prettier on NPI portal

Documentation (Wiki)

npm run wiki:build-index          # Rebuild wiki search index
npm run wiki:check                # Full wiki validation

Architecture Snapshot

• Framework: Vanilla JavaScript SPA (no build pipeline)
• Backend: Supabase (Auth, Postgres, Realtime)
• Package Manager: npm
• Testing: Jest with jsdom environment
• Linting: ESLint (NPI portal)
• Formatting: Prettier
• Script Load Order (critical): state.js → auth.js → db.js → helpers.js → navigation.js → realtime.js → portals → app.js

Hard Rules (Non-Negotiable)

1. Script Order: Always preserve exact load order in index.html. Verify with npm run check:load-order.
2. No Duplicate const: Never introduce duplicate variable declarations in the same scope.
3. Global State: Keep mutable state in core/js/state.js with defaults initialized.
4. HTML Escaping: Use esc() helper for any user data rendered into HTML strings (prevents XSS).
5. Navigation: Use navigate() function for route changes so realtime cleanup runs.
6. Auth-Only RLS: Do NOT filter client queries by user_id; rely on Supabase RLS policies.
7. Documentation: Keep new plans/docs in plans/ unless it is a core root doc.
8. Mobile-First CSS: Use both breakpoints:
   • @media (max-width: 767px) (mobile)
   • @media (min-width: 768px) (desktop)
9. Guide Updates: When adding/changing features on content pages, update the matching entry in GUIDE_CONTENT in utils/js/guide.js.

Code Style & Conventions

Imports & Globals

• No module imports (vanilla JS SPA). All dependencies loaded via <script> tags in index.html.
• Global objects available: supa (Supabase client), db, currentUser, GATE_DEFS, FAMILIES, etc.
• All ESLint-defined globals listed in eslint.config.js for NPI portal scope.

Formatting

• Single quotes for strings: 'string' not "string"
• No semicolons at end of statements
• Tab width: 2 spaces
• Line length: Max 100 characters
• Trailing commas: None
• Tool: npm run format:npi applies Prettier formatting

Variable Naming

• Use camelCase for variables and functions: getCurrentUser(), progId, bomPickTarget
• Use UPPER_CASE for constants: GATE_DEFS, FAMILIES, BOM_TYPES
• Use descriptive names: isLoading not loading_state
• Global state variables tracked in core/js/state.js

Functions & Error Handling

• Keep functions focused and under 50 lines when possible
• Always handle async errors with try-catch or .catch()
• Use early returns to reduce nesting
• Log errors clearly: console.error('Operation failed:', error)
• Return predictable types (null, empty array, or error object)
• Example pattern:

  async function fetchProgram(id) {
    try {
      const { data, error } = await supa.from('programs').select().eq('id', id)
      if (error) throw error
      return data[0] || null
    } catch (err) {
      console.error('Failed to fetch program:', err)
      return null
    }
  }
  

Conditions & Equality

• Use strict equality: === and !== (ESLint enforced)
• Null checks: value == null is allowed for null/undefined comparison
• Prefer explicit boolean: if (isActive === true) over if (isActive)

Testing Guidelines

• Follow Jest Arrange-Act-Assert structure
• Match test file naming to module purpose
• Use jsdom-safe patterns (see jest.setup.js)
• Mock Supabase client calls rather than hitting live services
• Include at least one unhappy path test per new behavior
• Avoid testing implementation internals; test observable behavior
• Keep async tests using async/await (avoid false positives)

Example test structure:

describe('functionName', () => {
  it('should handle the happy path', () => {
    // Arrange
    const input = { /* ... */ }
    // Act
    const result = myFunction(input)
    // Assert
    expect(result).toBe(expected)
  })

  it('should handle errors gracefully', () => {
    // Arrange
    const badInput = null
    // Act & Assert
    expect(() => myFunction(badInput)).toThrow()
  })
})

ID Generation Pattern

Use prefixed short IDs consistently:

const id = 'f_' + Math.random().toString(36).substr(2, 5)

Prefixes: f_ = mode, e_ = effect, c_ = cause, r_ = risk, a_ = action

Save Debouncing

Data persists to Supabase with an 800–900 ms debounce. Plan UX accordingly.

Changelog Management

After each logical change, add one entry near the top of CHANGELOG.md:

## YYYY-MM-DD | Short descriptive title | Brief reason

Example:

## 2026-03-25 | Add mobile-friendly BOM editor | Improve tablet UX for field technicians

Validation Workflow

Before committing:

1. Run npm test — ensure all tests pass
2. Run npm run check:all — run full validation suite
3. Add changelog entry to CHANGELOG.md
4. Verify script order with npm run check:load-order

Canonical Detail Rules

For detailed guidance, consult:

• Test rules: .github/instructions/testing.instructions.md
• Security: .claude/rules/security.md
• Database/RLS: .claude/rules/database.md
• Navigation: .claude/rules/navigation.md
• Realtime: .claude/rules/realtime.md
• Components: .claude/rules/components.md

MCP Tools

This repository has MCP servers configured in .mcp.json:

• Serena (oraios/serena): Use for Serena ALM/Octane integration
• GitHub (github/github-mcp-server): Use for GitHub API operations

OpenWolf Protocol

Follow the rules in .claude/rules/openwolf.md for all file operations. Key points:

• Check .wolf/anatomy.md before reading project files
• Check .wolf/cerebrum.md Do-Not-Repeat list before generating code
• Update .wolf/anatomy.md and append to .wolf/memory.md after writing files
• Log bugs to .wolf/buglog.json after fixes
• Run openwolf designqc when asked to evaluate UI design

User Context

The primary user is non-technical. When communicating, use plain language and avoid technical jargon. Keep error messages and inline comments clear and actionable.