For Humans: This repository contains best practices and conventions for working effectively with AI coding assistants. Use these guides to structure your projects for maximum AI productivity.
For AI Agents: This repository contains canonical reference documentation for AI-first development patterns. Read these guides to understand how to structure work, maintain documentation, and collaborate effectively with human developers. When asked to update topics, follow the governance documents in
_meta/.
A Single Source of Truth (SSOT) for AI-first development knowledge.
- Repository Structure
- Core Files
- Engineering Guides
- Tools & Protocols
- Platform References
- Governance
- Quick Start
- How to Contribute
- When to Use Each Guide
- Integration Patterns
- License
ssot/
├── README.md # This file - repository overview
├── files/ # Core AI-first development files
│ ├── README.md # Files directory guide
│ ├── AGENTS.md # AI agent operational documentation
│ ├── CHANGELOG.md # Version history format
│ ├── PLANS.md # ExecPlans for complex tasks
│ ├── SKILL.md # Agent Skills specification
│ └── SSOT.md # Single Source of Truth principles
├── engineering/ # Engineering methodologies
│ ├── README.md # Engineering guides overview
│ ├── context.md # Context engineering patterns
│ └── prompt.md # Prompt engineering patterns
├── tools/ # AI development tools & protocols
│ ├── README.md # Tools and protocols overview
│ └── mcp.md # Model Context Protocol guide
├── platforms/ # Platform-specific implementations
│ ├── README.md # Platform guides overview
│ ├── openai/ # OpenAI-specific guides
│ │ ├── agents-sdk.md # Responses API patterns
│ │ ├── agent-kit.md # AgentKit framework concepts
│ │ └── codex.md # Code generation patterns
│ ├── anthropic/ # Anthropic-specific guides
│ │ ├── claude-code.md # Claude Code agentic tool
│ │ └── claude-agent-sdk.md # Claude Agent SDK
│ ├── google/ # Google-specific guides
│ │ └── a2a.md # Agent2Agent protocol
│ └── langchain/ # LangChain-specific guides
│ ├── langchain.md # LangChain framework
│ └── langgraph.md # LangGraph orchestration
├── _meta/ # Governance & style guides
│ ├── CONTRIBUTING.md # How to add/update content
│ ├── STYLE.md # Writing conventions
│ └── TAXONOMY.md # Canonical tag vocabulary
├── _templates/ # Templates for new content
│ ├── TOPIC_TEMPLATE.md # New topic template
│ └── SECTION_TEMPLATE.md # Section templates
└── .github/ # GitHub automation
├── workflows/ # CI/CD pipelines
│ ├── markdownlint.yml # Markdown quality checks
│ └── linkcheck.yml # Broken link detection
├── ISSUE_TEMPLATE/ # Issue templates
│ ├── topic_update.md # Request topic updates
│ └── new_topic.md # Propose new topics
└── PULL_REQUEST_TEMPLATE.md # PR checklist
Design Philosophy:
files/- Core AI-first development file conventions (1 topic = 1 file)engineering/- Deep technical methodologies (context, prompting)tools/- Cross-platform tools and communication protocolsplatforms/- Vendor-specific implementations (OpenAI, Anthropic, Google, LangChain)_meta/- How to maintain this repository_templates/- Scaffolding for new content
OpenAI AGENTS.md convention for AI-agent-friendly operational documentation
- Machine-focused operational procedures
- Development environment setup
- Testing, linting, and PR workflows
- Security policies and best practices
- Cross-platform agent compatibility
Use when: Setting up project conventions for AI agents, defining development workflows, establishing operational procedures.
Single Source of Truth principles for canonical documentation
- Governance patterns for authoritative documentation
- Canonical definitions and data contracts
- API specifications and schemas
- Policy management
- Conflict resolution strategies
Use when: Establishing canonical definitions, preventing documentation drift, managing data contracts and API specifications.
Anthropic Agent Skills specification for domain expertise packaging
- Progressive disclosure model
- Skill structure (YAML metadata + Markdown instructions)
- Security considerations
- Platform support (Claude API, Claude Code, Claude.ai)
- Skill development workflow
Use when: Packaging reusable domain expertise, creating specialized agent capabilities, building skill libraries.
ExecPlans workflow for documenting complex initiatives
- Document structure and format
- Progress tracking and decision logging
- Surprise and discovery capture
- Multi-session task continuity
- Retrospective documentation
Use when: Starting multi-hour tasks, coordinating complex features, ensuring task resumability, tracking decisions.
Keep a Changelog format for version history
- Semantic versioning practices
- User-facing change communication
- Release note structure
- Automation compatibility (Openchangelog)
- Maintenance best practices
Use when: Tracking project changes, communicating releases, maintaining version history, coordinating with users.
Best practices for designing, retrieving, and evaluating context bundles
- Four Context Pillars: Relevance, Recency, Reliability, Responsibility
- Context pipeline architecture (retrieval, filtering, formatting, delivery)
- Multi-document structuring strategies
- Long-context optimization techniques
- Context quality monitoring and evaluation
Use when: Building RAG systems, optimizing retrieval pipelines, structuring prompts with extensive context, evaluating context quality.
Sources: Anthropic, DAIR.AI, DeepMind research
Cross-platform prompt engineering patterns
- Universal principles (clarity, specificity, examples)
- Platform-specific techniques (Anthropic Claude, Google Gemini, OpenAI GPT)
- Constraint-first prompt design
- Chain-of-thought and reasoning patterns
- Prompt iteration workflows
Use when: Designing effective prompts, troubleshooting AI outputs, optimizing for specific platforms, establishing prompt standards.
Sources: Anthropic, Google Vertex AI, OpenAI, DeepMind
Open standard for connecting LLM applications to external data sources and tools
- Client-server architecture using JSON-RPC 2.0
- Five core primitives: Prompts, Resources, Tools, Roots, Sampling
- Official SDKs: Python, TypeScript, C#, Java, Go
- Pre-built servers for GitHub, PostgreSQL, Google Drive, Slack, Puppeteer
- Security considerations and vulnerability mitigation
- Integration with Claude Desktop, OpenAI Agents SDK, custom applications
Use when: Building AI applications requiring standardized external data access, creating reusable tool integrations across multiple AI platforms, implementing secure bidirectional AI-to-system communication.
Introduced: November 2024 by Anthropic Adopted by: OpenAI (March 2025), Microsoft, Google
Production patterns for OpenAI Responses API
- Python & TypeScript quickstarts
- Tool calling and function execution
- Streaming responses
- Session management
- Production deployment patterns
Use when: Building agents with OpenAI SDKs, implementing tool calling, deploying production OpenAI integrations.
Higher-level agent framework patterns
- Agent orchestration abstractions
- Memory management patterns (Redis, vector stores)
- Safety policy enforcement
- Logging and evaluation hooks
- Multi-agent workflows
Use when: Designing agent frameworks, implementing memory layers, building agent orchestration systems.
Note: Conceptual patterns—verify against official OpenAI releases.
Modern code-assistance patterns (post-Codex)
- Recommended models (GPT-4.1, GPT-4.1-mini, GPT-4o-mini)
- Code completion strategies
- Refactoring and editing patterns
- IDE integration approaches
- Legacy Codex migration guide
Use when: Building code generation features, migrating from Codex, optimizing code assistance tools.
Agentic coding tool for terminal and web
- Natural language development workflow
- Direct file editing, command execution, and Git integration
- Custom slash commands for repeated workflows
- MCP integration for extended capabilities
- GitHub Actions for automated code assistance
- Headless mode for CI/CD integration
- Supports Opus 4.1, Sonnet 4.5, Haiku 3.5 models
Use when: Building features rapidly, refactoring code, automating development tasks, integrating AI assistance into Git workflows and CI/CD pipelines.
Availability: CLI (macOS, Linux, Windows), Web (claude.ai/code), Mobile (iOS preview)
SDK for building custom AI agents
- Programmatic access to Claude Code infrastructure
- Async streaming API with full agent capabilities
- Custom tools as in-process MCP servers
- Fine-grained tool permissions and security controls
- Automatic context management (compact feature)
- External MCP server integration
- Python 3.10+ and TypeScript support
Use when: Building custom autonomous agents, integrating agents into applications, extending beyond coding use cases (research, data analysis, workflow automation).
Powers: Claude Code CLI and web interface
Open-source automated auditing framework for AI safety research
- AI agents test target models across diverse scenarios
- Multi-turn conversation testing with simulated users and tools
- Automated scoring across safety risk categories (deception, sycophancy, power-seeking, refusal failure)
- Built on UK AISI's Inspect framework
- Supports major model API providers
- Ships with 111 seed instructions, runs in minutes
- Detects misaligned behaviors: autonomous deception, oversight subversion, whistleblowing
Use when: Evaluating AI model safety, testing for risky behaviors, conducting AI safety research, validating model alignment, automating model auditing, comparing safety across models.
Powers: Claude 4 and Claude Sonnet 4.5 System Cards, OpenAI collaboration for reward hacking detection
Open protocol for AI agent interoperability
- JSON-RPC 2.0 over HTTP(S) communication standard
- Agent discovery via Agent Cards
- Async-first design for long-running tasks
- Server-Sent Events (SSE) streaming
- Opaque execution model for privacy and security
- Linux Foundation hosted open-source project
Use when: Building multi-agent systems, enabling cross-framework agent communication, implementing agent discovery and task delegation.
Industry Support: Hosted by Linux Foundation with support from 50+ companies including AWS, Microsoft, Google, Salesforce, SAP, and ServiceNow.
Open-source framework for building LLM-powered applications
- Modular architecture with chains, agents, and memory
- Extensive integrations with LLM providers and vector databases
- Retrieval-Augmented Generation (RAG) patterns
- LCEL (LangChain Expression Language) for declarative workflows
- LangServe for API deployment
- LangSmith for observability and evaluation
- Python and JavaScript/TypeScript support
Use when: Building chatbots, document analysis systems, RAG applications, conversational agents with memory, or any LLM-powered workflow requiring structured composition.
Ecosystem: Used by companies including Replit, Clay, Rippling, Cloudflare, and Workday.
Graph-based orchestration for stateful multi-agent workflows
- Directed graph architecture for complex agent orchestration
- Built-in state management and persistence (checkpoints)
- Human-in-the-loop workflows with pause/resume capability
- Time-travel debugging for exploring alternative execution paths
- Streaming real-time updates
- LangGraph Studio for visual debugging
- Multi-agent coordination with conditional branching
Use when: Building multi-agent systems, workflows requiring conditional logic or parallel execution, agents needing human approval, long-running tasks that pause/resume, or applications requiring state persistence.
Deployment: LangGraph Cloud (managed), self-hosted, or VPC deployment options.
Planned additions:
platforms/anthropic/- Claude API, prompt caching, extended context (additional guides)platforms/google/- Gemini API, Vertex AI, multimodal patterns (additional guides)platforms/microsoft/- Azure OpenAI, Copilot integration
How to add, update, and maintain knowledge in this repository
- Information addition workflow (human and AI-assisted)
- Section mapping guide
- Conflict resolution strategies
- Quality checklist
- Maintenance schedules
Read this first when contributing to the repository.
Writing conventions, formatting rules, and structural patterns
- YAML frontmatter format
- Heading conventions
- Citation and reference format
- Code block standards
- Markdown linting rules
- Commit message format
Reference this when writing or editing any markdown file.
Controlled vocabulary for tags and terminology
- Canonical tags by category
- Tag definitions and scope
- Synonyms and related concepts
- Tag validation rules
- Deprecation process
Check this before adding tags to frontmatter.
- Start with AGENTS.md - Understand the foundational convention
- Review SSOT.md - Learn about canonical documentation
- Check tools/README.md - If working with AI integration protocols
- Explore platforms/README.md - If integrating specific AI platforms
- Consult engineering/README.md - When planning context or prompt strategies
- Read _meta/CONTRIBUTING.md - If you plan to contribute
- Read all topic files to understand conventions
- Reference _meta/CONTRIBUTING.md when asked to update content
- Follow _meta/STYLE.md for all edits
- Validate tags against _meta/TAXONOMY.md
- Use _templates/TOPIC_TEMPLATE.md when creating new topics
- Browse files/ to find relevant existing documents
- Check .github/ISSUE_TEMPLATE/ for issue templates
- Review _meta/CONTRIBUTING.md for workflow guidance
- Use _templates/ for consistent structure
- Submit PRs following .github/PULL_REQUEST_TEMPLATE.md
We welcome contributions of insights, best practices, and new knowledge.
- Identify the source (article, documentation, research paper)
- Find the relevant file (e.g.,
files/AGENTS.md) - Open an issue using Topic Update template
- Or submit a PR following the Contributing Guide
- Verify the topic doesn't exist in
files/,engineering/, orplatforms/ - Check it's substantial (>2000 words potential)
- Open an issue using New Topic template
- Gather initial sources (2-3 authoritative references)
- Use _templates/TOPIC_TEMPLATE.md when approved
Prompt template for adding information:
Please update files/AGENTS.md with the following information:
Source: https://example.com/article
Section: Core Patterns
Key Points:
- [Point 1]
- [Point 2]
Instructions:
1. Read the source
2. Integrate into the specified section
3. Add reference [R#] with proper citation
4. Update frontmatter (last_updated, sources array)
5. Add entry to Update Log
6. Follow _meta/STYLE.md conventions
See _meta/CONTRIBUTING.md for detailed AI interaction patterns.
- AGENTS.md - Set up operational documentation
- SSOT.md - Establish canonical definitions
- CHANGELOG.md - Initialize version tracking
- PLANS.md - Create ExecPlan for multi-hour tasks
- SKILL.md - Package domain expertise
- SSOT.md - Reference canonical definitions
- AGENTS.md - Follow testing and PR procedures
- context.md - Design retrieval pipelines
- prompt.md - Optimize prompts
- Model Context Protocol - Implement standardized tool integrations
- OpenAI Agents SDK - Implement OpenAI agents
- OpenAI AgentKit - Design agent frameworks
- OpenAI Code Generation - Build code assistance
- Update CHANGELOG.md - Document user-facing changes
- Close PLANS.md - Add retrospective
- Update SSOT.md - Add new canonical definitions
These guides form an integrated system:
| Guide | Purpose | Example Use |
|---|---|---|
| AGENTS.md | How to work | Testing procedures, linting commands |
| SSOT.md | What things are | API endpoints, data schemas |
| PLANS.md | Complex initiatives | Multi-step features, refactoring projects |
| SKILL.md | Domain expertise | Financial analysis, form filling |
| CHANGELOG.md | What changed | Version history, release notes |
Implementing a new authentication feature:
- Create ExecPlan (PLANS.md) outlining phases
- Reference canonical schemas from SSOT.md
- Follow testing procedures from AGENTS.md
- Use prompt patterns from prompt.md when working with AI
- Package auth logic as a Skill (SKILL.md) for reuse
- Document changes in CHANGELOG.md
This repository includes automated quality checks:
- Markdown Linting - Runs on every PR (markdownlint)
- Link Checking - Runs on PRs and weekly (linkcheck)
# Run markdown linting
npx markdownlint-cli2 "**/*.md"
# Check links
npx markdown-link-check files/*.md engineering/*.md- Monthly: Check References for link rot
- Quarterly: Review tags against TAXONOMY.md, audit document status
- Annually: Major refactoring, template updates, structural improvements
draft→living→stable→deprecated- Track status in frontmatter
statusfield - Never delete deprecated content—mark and retain for historical reference
MIT License
This repository synthesizes best practices from:
- Anthropic - Claude documentation, prompt engineering guides, Agent Skills
- OpenAI - AGENTS.md convention, Responses API, code generation patterns
- Google - Vertex AI prompt design, Gemini documentation, Agent2Agent protocol
- Linux Foundation - A2A Protocol Project, agent interoperability standards
- DAIR.AI - Context engineering research
- DeepMind - Prompting research and techniques
- Community - Keep a Changelog, Semantic Versioning
Repository Maintainer: AI-First Development Team
Last Updated: 2025-10-24
Canonical URL: https://github.com/artificial-intelligence-first/ssot