Skip to content

AI Coding & Agent Workflows Guide

Comprehensive developer guide for human pair-programmers and autonomous AI coding agents (Cursor, Claude, Gemini, Antigravity, Copilot) working on the TidyFactor-Go codebase.

🤖 1. Overview of the .agents Directory

TidyFactor-Go includes a built-in .agents/ context root designed to guide AI assistants and guarantee zero-regression feature additions:

.agents/
├── AGENTS.md               # Strict operational, design, and subfolder portability rules
├── agent_instructions.md  # Terminal commands, test suites, and environment setup
├── architecture.md         # System diagrams, dynamic hydration, and 11-layer protocol
├── Design.md              # Swiss Flat UI design tokens (colors, typography, grid borders)
├── specs.md               # CMS 11-key schema contract and SQLite transaction rules
└── skills/                 # Task skills (tidyfactor-go-json-contract, shadcn, tidyfactor-doc)

🔒 2. Non-Negotiable Rules for AI Agents

When modifying or expanding code, AI agents MUST follow these mandatory rules:

[!CAUTION] Database & Core Logic Integrity - NEVER alter the SQLite database schema or PDO connection logic in SqliteConnection.php. - NEVER delete, disable, or hide the Raw JSON Editor under Advanced Settings in AdminPage.tsx. - NEVER rename public type interfaces in src/content/types.ts.

[!WARNING] Clean HTTP Cache & Subfolder Resolution - NEVER pollute API request strings with timestamp queries (_t=${Date.now()}). Use standard fetch headers: fetch(resolveApiUrl('api/...'), { cache: 'no-store' }). - ALWAYS wrap relative backend fetch URLs with resolveApiUrl('api/...') from src/lib/apiUrl.ts to ensure subfolder depth portability.

[!IMPORTANT] Abstract Business Concept Decoupling - Fallbacks in Home.tsx, Solutions.tsx, and defaultContent.ts MUST use Abstract Business Concepts ("Performance", "Operational Integrity", "Global Compliance") rather than hardcoded specific industries (like "Fire safety" or "CCTV").

📋 3. The 11-Layer New Page Protocol

When creating new CMS pages or sections (e.g., pricing, blog, careers), AI agents MUST execute all 11 layers in strict order:

1. types.ts ➜ 2. defaultContent.ts ➜ 3. index.html ➜ 4. ContentService.php ➜ 5. AdminPage.tsx
 ➜ 6. NewPageSectionForm.tsx ➜ 7. NewPage.tsx ➜ 8. AppRouter.tsx ➜ 9. usePageSeo.ts 
 ➜ 10. content.php (sitemap) ➜ 11. Database Seeding
  1. src/content/types.ts: Declare interface, add key to ManagedSiteContent, extend seo page union.
  2. src/content/defaultContent.ts: Add fallback data block, default SEO meta, and nav links in header.navLinks and footer.quickLinks.
  3. index.html: Add route path (e.g. '/pricing') to routes array in the inline base detection script.
  4. backend/cms-api/src/Service/ContentService.php: Add to validateSchema(), inject default PHP schema, and update SEO validation loops.
  5. src/pages/admin/AdminPage.tsx: Add key to requiredKeys in handleApplyRawJson(), add section item to sidebar navigation list, and render <NewPageSectionForm />.
  6. src/pages/admin/NewPageSectionForm.tsx: Build workspace form using inline FieldRow elements and Content / Settings / SEO tabs.
  7. src/pages/NewPage.tsx: Build public page using useContent(), getLocalizedText(), and isEnabled().
  8. src/routes/AppRouter.tsx: Register route inside <MainLayout> block.
  9. src/App.tsx & src/lib/usePageSeo.ts: Map path slug to page key in getPageKey() and SEO_PAGE_BY_PATH.
  10. backend/cms-api/routes/content.php: Add path slug to $pages array in /api/sitemap.xml.
  11. Database Seeding: Execute PHP seed script to update database.sqlite and baseline database-baseline.sqlite.

🎨 4. Swiss Flat Design System & UI Rules

AI agents generating React components must adhere to the Swiss Flat aesthetic:

  • 1px Grid Borders: Separate layouts and cards using crisp 1px lines (border-border) rather than thick empty whitespace separators.
  • Compact Padding: Minimize vertical margins (py-16 to py-24).
  • Colors: Use primary blue #0A2540, accent red #D62828, dark depth #081C30, and border variable var(--border).
  • Buttons: Soft square corners (rounded-sm). Avoid large pill shapes except for standalone status badges.

🛠️ 5. Pre-Check Verification Checklist for AI Agents

Before declaring a coding task complete, AI agents MUST run the following commands:

# 1. Typecheck
npx tsc --noEmit

# 2. Production Bundle Test
npm run build

# 3. Backend PHP Syntax Verification
php -l backend/cms-api/public/index.php