[FEATURE] Auto-load openspec/ directory for project context

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Use Case

Many teams maintain project conventions, tech stack documentation, and coding guidelines in a standardised location. OpenSpec provides a convention for this (openspec/project.md), keeping AI-agnostic project context separate from tool-specific configuration.

This separation is useful because:

• Project context (conventions, tech stack, patterns) is relevant to all AI tools and developers
• Tool-specific config (permissions, hooks, MCP servers) belongs in .claude/
• Teams can adopt OpenSpec across multiple AI tools without duplication

Proposed Solution

Proposed Behaviour

Claude Code would auto-load markdown files from openspec/ at project root:

• openspec/project.md - main project context
• openspec/*.md - additional context files

This would follow the same pattern as .claude/rules/ loading.

Alternative Solutions

Current Workaround

Using @openspec/project.md in CLAUDE.md works, but native support would make the convention more discoverable and reduce boilerplate.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

A team maintains a FastAPI microservice with conventions in openspec/project.md:

Project Context

Tech Stack

• Python 3.12, FastAPI, SQLAlchemy (async), Alembic
• Package manager: uv

Conventions

• Use async def for all I/O operations
• Repository pattern for database access
• Pydantic V2 for all schemas
• Factory-boy for test data
• Gitmoji for commits (📝 type: description)

## Don't

• No synchronous database code
• No business logic in API endpoints
• No hardcoded configuration

The problem: This context is useful to:

• Claude Code
• Cursor
• GitHub Copilot
• New developers onboarding
• Code reviewers

Currently: Each tool needs its own config file (CLAUDE.md, .cursorrules, etc.) duplicating the same information. When conventions change, multiple files need updating.

With OpenSpec support: All tools read from openspec/project.md. Tool-specific config (like Claude's MCP servers or permission settings) stays in .claude/. One source of truth for project context, separate config for tool-specific behaviour.