Here’s a more robust architecture designed specifically for Cursor, Claude Code, Codex, Gemini CLI, OpenAI agents, and future coding assistants. The goal is to eliminate file conflicts, enable self-improving documentation, and establish a single source of truth.

.ai/
├── README.md                     # AI architecture and usage guide
├── CONSTITUTION.md               # Non-negotiable engineering principles (read-only)
├── PROJECT.md                    # High-level project overview
├── ROADMAP.md                    # Product roadmap
├── ARCHITECTURE.md               # System architecture
├── CODING_STANDARDS.md           # Coding conventions
├── BUSINESS_RULES.md             # Core business rules
├── GLOSSARY.md                   # Shared terminology
├── CHANGELOG.md                  # High-level project changes
│
├── knowledge/                    # Curated, long-term knowledge
│   ├── decisions.md              # Architecture Decision Records (ADR)
│   ├── lessons.md                # Lessons learned
│   ├── patterns.md               # Proven implementation patterns
│   ├── anti-patterns.md          # Practices to avoid
│   ├── bugs.md                   # Known bugs and resolutions
│   ├── security.md               # Security knowledge
│   ├── performance.md            # Performance improvements
│   ├── testing.md                # Testing strategies
│   └── troubleshooting.md        # Common issues and fixes
│
├── agents/                       # Agent-specific instructions
│   ├── cursor.md
│   ├── claude-code.md
│   ├── codex.md
│   ├── gemini-cli.md
│   ├── openai.md
│   └── shared.md                 # Shared prompts and conventions
│
├── workspace/                    # Temporary working memory (append-only)
│   ├── cursor/
│   ├── claude/
│   ├── codex/
│   ├── gemini/
│   └── openai/
│
├── reviews/
│   ├── architecture/
│   ├── code/
│   ├── security/
│   ├── ux/
│   └── testing/
│
├── prompts/
│   ├── implementation.md
│   ├── code-review.md
│   ├── testing.md
│   ├── debugging.md
│   ├── refactoring.md
│   └── documentation.md
│
├── templates/
│   ├── adr.md
│   ├── bug-report.md
│   ├── feature.md
│   ├── test-plan.md
│   └── release.md
│
├── logs/
│   ├── cursor/
│   ├── claude/
│   ├── codex/
│   ├── gemini/
│   └── openai/
│
└── archive/

Agent responsibilities

Agent	Primary responsibility	Writes to
Cursor	Feature development, UI/UX, refactoring	workspace/cursor/
Claude Code	Architecture, business logic, security	workspace/claude/
Codex	Tests, CI/CD, documentation, code review	workspace/codex/
Gemini CLI	Research, large-scale analysis, optimisation	workspace/gemini/
OpenAI	Planning, requirements, orchestration	workspace/openai/

No agent writes directly to the shared knowledge/ folder.

Self-improving workflow

Read
     ↓
Analyse
     ↓
Implement
     ↓
Record findings
     ↓
Append to agent workspace
     ↓
Knowledge Librarian reviews
     ↓
Merge into knowledge/

This prevents agents from overwriting one another while allowing knowledge to improve over time.

Rules

1. All agents read every file under knowledge/.
2. Agents never edit files in knowledge/.
3. Agents write only to their own workspace/<agent>/ directory.
4. Workspace files are append-only—never rewrite or delete previous entries.
5. A designated Knowledge Librarian reviews and merges validated information into knowledge/.
6. All code changes go through Git branches and pull requests.
7. Architecture decisions are recorded as ADRs in knowledge/decisions.md.

Recommended Knowledge Librarian prompt

You are the Knowledge Librarian. Review all agent workspace notes. Remove duplicates, resolve conflicts, validate against the project architecture and business rules, update the appropriate files in knowledge/, archive obsolete information, and maintain a clean, concise, and authoritative project knowledge base. Never modify source code—only maintain documentation and shared knowledge.

This architecture scales well whether you’re using two AI coding assistants or ten, because it separates implementation, temporary reasoning, and long-term project knowledge, eliminating most overwrite conflicts while creating a continuously improving documentation system.