SocialApp Lite — Agentic AI Project Template

This project is a simple Facebook-like application scaffold designed to be used with AI coding agents such as OpenAI Codex, Claude Code, Gemini CLI, GitHub Copilot or other agentic coding tools.

It includes:

• a working React + TypeScript + Vite application;
• modules for identity, posts, chat and marketplace;
• tests and validation scripts;
• an AI-ready repository structure;
• AGENTS.md for Codex and shared agent rules;
• CLAUDE.md, GEMINI.md and .github/copilot-instructions.md as tool adapters;
• .ai/context/* for functional context routing;
• .ai/prompts/* for reusable agent prompts;
• .ai/workflows/* for team workflows;
• ADR, architecture and security documentation.

Quick start

npm install
npm run dev

Open the local URL printed by Vite.

Validate the project

npm run validate

This runs:

• context routing validation;
• unit tests;
• production build.

Useful commands

npm run dev
npm run build
npm run test
npm run test:chat
npm run test:posts
npm run test:identity
npm run validate:context

How to use this project with an AI agent

1. Start with the repository protocol

The agent should read:

AGENTS.md
.ai/context/application.md

Then it should identify the impacted module and read the relevant module context:

.ai/context/modules/<module>.md

If the request touches a durable behavior, it should also read a capability file:

.ai/context/capabilities/<capability>.md

2. Ask the agent to produce a routing report before coding

Use:

.ai/prompts/plan.md

The agent must produce an Agent Context Routing Report before non-trivial implementation.

3. Implement only after the plan is clear

Use:

.ai/prompts/implement.md

The agent should modify only the targeted files, run tests, and summarize risks.

Codex usage examples

Codex uses AGENTS.md as the shared project protocol in this repository.

Example prompt for a planning task:

codex "Read AGENTS.md, then use .ai/prompts/plan.md. Plan the feature described in agent-requests/feature-chat-image-message.md. Do not edit code yet."

Example prompt for implementation after approval:

codex "Read AGENTS.md and .ai/prompts/implement.md. Implement the approved plan for adding image attachments to chat messages. Modify only the files listed in the plan and run the targeted tests."

Example debugging prompt:

codex "Read AGENTS.md and .ai/prompts/debug.md. Investigate why empty chat messages are accepted. Produce a minimal fix and add a non-regression test."

Claude Code usage examples

Claude Code uses CLAUDE.md as a Claude-specific adapter, which points back to AGENTS.md.

Example prompt for a planning task:

claude "Read CLAUDE.md and AGENTS.md, then use .ai/prompts/plan.md. Plan the feature described in agent-requests/feature-chat-image-message.md. Do not edit code yet."

Example prompt for implementation after approval:

claude "Read CLAUDE.md, AGENTS.md and .ai/prompts/implement.md. Implement the approved plan for adding image attachments to chat messages. Modify only the files listed in the plan and run the targeted tests."

Example debugging prompt:

claude "Read CLAUDE.md, AGENTS.md and .ai/prompts/debug.md. Investigate why empty chat messages are accepted. Produce a minimal fix and add a non-regression test."

Recommended agent workflow

1. Identify the request.
2. Read AGENTS.md.
3. Read .ai/context/application.md.
4. Identify the impacted module.
5. Read .ai/context/modules/<module>.md.
6. Read .ai/context/capabilities/<capability>.md only if relevant.
7. Read SECURITY.md if a security trigger applies.
8. Read relevant ADRs only if architecture, security, data, tool, production or technology decisions are affected.
9. Produce an Agent Context Routing Report.
10. Implement only after validation.
11. Run targeted tests.
12. Summarize what changed, what was not changed, tests run and residual risks.

Example agent requests

See:

agent-requests/feature-chat-image-message.md
agent-requests/bug-empty-message.md
agent-requests/simple-ui-label-change.md
agent-requests/architecture-cassandra-chat.md

Project structure

src/modules/identity
src/modules/posts
src/modules/chat
src/modules/marketplace
.ai/context
.ai/prompts
.ai/workflows
docs/adr
docs/architecture
docs/security

Notes

This is a lightweight template. It is intentionally simple so that an agent can extend it into a fully functional application while respecting architecture, security and context-routing rules.