AICF (Augmented Intelligence Client Framework) v0.1

Status: In Development
License: MIT

The Paradigm Shift

Note from the developer: With the rapid evolution of LLMs like Claude Opus, Gemini, and GPT-5, the utility of heavy, abstraction-laden frameworks is diminishing. In modern workflows, we rarely write from a blank slate; we are synthesizing AI-generated modules and orchestrating complex systems.

The goal however, is not to remove the human from the loop. We still love to code — we just want to escape the drudgery of the repetitive and the redundant. We need a paradigm shift where the AI handles the bulk of the boilerplate and structural heavy lifting, allowing the developer to focus on surgical intervention: writing proprietary business logic, owning the high-stakes sections, and refining the architecture.

This distinction is vital for both quality and copyright. A purely generated codebase is an IP gray area; a codebase where the human actively architects, edits, and develops key components is a proprietary asset.Traditional frameworks (React, Next, Angular) are optimized for manual composition. AICF is optimized for collaborative efficiency—an environment where the AI builds the foundation, and the human Architect or Composer steps in to refine, secure, and perfect the execution.

Design Principles

| Principle | Description | |-----------|-------------| | Governor, Not Toolbox | Framework constrains where and how code lives | | Human Readable | Code understandable despite evolving codebase | | Library-First | Use Tailwind, Radix, etc. — AI configures, not writes raw DOM | | Secure by Default | Platform-level sanitization in core |

File Structure

/my-aicf-app
├── core/                       # Framework Kernel (Immutable)
│   ├── kernel.js               # Core runtime (<2KB)
│   ├── router.js               # File-system router
│   ├── signals.js              # Reactive primitives
│   ├── sanitizer.js            # Auto-sanitization (security)
│   └── watcher.js              # Auto-generates project-map.json
│
├── CHANGELOG.md                # Version history (AI updates)
├── context/                    # AI Governance
│   ├── AI_INSTRUCTIONS.md      # [HUMAN] LLM mandatory instructions
│   ├── features.md             # [HUMAN] Feature task list & requirements
│   ├── intent.md               # [HUMAN] Business rules, "why"
│   ├── design.json             # [HUMAN] Design tokens
│   ├── libraries.md            # [HUMAN] Allowed libraries
│   ├── project-map.json        # [AUTO] Routes, components (generated)
│   └── wireframes/             # [OPTIONAL] UI images
│
├── src/
│   ├── index.js                # Entry point
│   ├── App.js                  # Root + Router
│   ├── pages/                  # File-System Routing (source of truth)
│   │   ├── index.js            # → /
│   │   ├── about.js            # → /about
│   │   ├── dashboard/
│   │   │   ├── index.js        # → /dashboard
│   │   │   └── [id].js         # → /dashboard/:id (dynamic)
│   │   └── [...catchAll].js    # → /* (404)
│   ├── components/             # Reusable components
│   ├── features/               # Domain modules
│   ├── store/AppStore.js       # Global state
│   └── styles/
│
├── public/
│   └── assets/images/
│
└── dist/                       # Production build

Routing: File-System Based

Source of truth: The folder structure. No JSON to maintain.

How It Works

| File Path | Route | Description | |-----------|-------|-------------| | src/pages/index.js | / | Home page | | src/pages/about.js | /about | Static page | | src/pages/dashboard/index.js | /dashboard | Dashboard home | | src/pages/dashboard/[id].js | /dashboard/:id | Dynamic route | | src/pages/blog/[...slug].js | /blog/* | Catch-all route | | src/pages/[...catchAll].js | /* | 404 fallback |

Dynamic Route Syntax

Yes, [id].js is the actual filename! The brackets indicate a dynamic segment:

src/pages/
├── users/
│   ├── index.js        → /users
│   ├── [id].js         → /users/123, /users/abc
│   └── [id]/
│       └── posts.js    → /users/123/posts

React Router vs File-System Routing

| Aspect | React Router (Manual) | File-System (AICF/Next.js) | |--------|----------------------|---------------------------| | Define routes | Write JSX in App.js | Create files in pages/ | | Dynamic params | <Route path="/user/:id"> | Name file [id].js | | Catch-all | <Route path="*"> | Name file [...slug].js | | Conflicts | Runtime errors | Impossible (filesystem) | | Team scaling | Merge conflicts | Folders isolate teams |

React Router Example:

// src/App.js - Manual route definitions
import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/dashboard/:id" element={<DashboardDetail />} />
        <Route path="/users/:userId/posts/:postId" element={<Post />} />
        <Route path="*" element={<NotFound />} />
      </Routes>
    </BrowserRouter>
  );
}

AICF File-System Example:

src/pages/
├── index.js                    → / (Home)
├── about.js                    → /about
├── dashboard/
│   ├── index.js                → /dashboard
│   └── [id].js                 → /dashboard/:id
├── users/
│   └── [userId]/
│       └── posts/
│           └── [postId].js     → /users/:userId/posts/:postId
└── [...catchAll].js            → /* (NotFound)

No App.js routing code needed. The router reads the folder structure automatically.

Auto-Generated Project Map

A watcher generates context/project-map.json for AI to read:

{
  "routes": [
    { "path": "/", "file": "src/pages/index.js" },
    { "path": "/dashboard", "file": "src/pages/dashboard/index.js" },
    { "path": "/dashboard/:id", "file": "src/pages/dashboard/[id].js" }
  ],
  "components": ["Button", "Modal", "DataTable"],
  "generatedAt": "2026-01-13T10:00:00Z"
}

Result: AI reads JSON (fast), source of truth is filesystem (safe).

Context Files

🤖 LLM INSTRUCTION: Before building or modifying this app, you MUST read the context files below. See context/AI_INSTRUCTIONS.md for full workflow details.

| File | Updated By | Purpose | |------|------------|---------| | context/AI_INSTRUCTIONS.md | Human | Start here - LLM mandatory instructions | | context/features.md | Human/AI | Feature task list & requirements (use [x] for done) | | context/intent.md | Human | Business rules, design decisions, "why" | | context/design.json | Human | Colors, spacing, typography | | context/libraries.md | Human | Allowed libraries (Tailwind, Radix, etc.) | | CHANGELOG.md | AI | Version history (update after each feature) | | context/project-map.json | Auto-generated | Routes, component inventory |

context/libraries.md Example

# Allowed Libraries

## CSS
- Tailwind CSS (use utility classes)

## Components
- @radix-ui/react (headless primitives)
- @shadcn/ui (styled components)

## Data
- axios (HTTP requests)
- date-fns (date formatting)

## AI Instructions
When building components, use Radix primitives for accessibility.
For styling, use Tailwind classes, not inline styles.

Security: Platform-Level

core/sanitizer.js auto-sanitizes all user inputs:

// AI doesn't need to remember - core handles it
import { sanitize } from '../core/sanitizer.js';

// All user input passes through sanitizer automatically
const safeInput = sanitize(userInput);

AI Generation Boundaries

| Scope | AI Generates | Human Audits | |-------|--------------|--------------| | Components | ✅ Using allowed libraries | Review | | Feature Logic | ✅ Business code | Audit required | | Routes | ❌ Creates files in pages/ | Filesystem | | Security | ❌ Core handles | Automatic | | Context Intent | ❌ Never | Author only |

Improvement Roadmap

1. Core Sanitizer - Platform-level auto-sanitization
2. File-System Router - Auto project-map generation
3. Library Adapter - Tailwind, Radix, Shadcn integration
4. Optimized Tree-Shaking - Dead code elimination
5. Selective Hydration - Progressive hydration for SSR
6. DevTools Extension - Browser debugging for AICF
7. Migration CLI - React → AICF converter

Getting Started

# Coming soon
npx create-aicf-app my-app
cd my-app
npm run dev

FAQ: Addressing Criticisms

❓ "Raw code leads to 500+ line files and code bloat"

Answer: AICF explicitly supports library usage via context/libraries.md.

• CSS bloat? Use Tailwind → class="flex items-center p-4" instead of 50 lines of CSS
• HTML/JS bloat? Use component libraries (Radix, Shadcn) → AI writes 5 lines of config, not 50 lines of DOM

The key differentiator: AICF allows libraries and the AI knows which ones from context files.

❓ "Markdown governance is fragile — AI might ignore rules"

Answer: We split context into two types:

| Type | File | Enforcement | |------|------|-------------| | Human intent | intent.md, libraries.md | Soft guidance | | Auto-generated | project-map.json | Always accurate |

Long-term: Add aicf.config.ts for hard constraints (build fails on violation).

❓ "Hybrid JSON routing causes merge conflicts"

Answer: We moved to file-system routing (like Next.js):

• Source of truth = folder structure (impossible to conflict)
• AI reads auto-generated project-map.json (no manual JSON)
• Teams work in isolated folders

❓ "Security via AI memory is dangerous"

Answer: Security is now platform-level in core/sanitizer.js:

• All user input auto-sanitized before reaching components
• AI doesn't need to "remember" — framework handles it
• Explicit dangerouslySetInnerHTML for trusted content (audited)

License

MIT