AI Configuration Restructure Implementation Plan

Overview

Restructure the repository's AI tooling configuration to create a unified, scalable setup that works across Claude, Cursor, and GitHub Copilot. This includes organizing MCPs, agents, skills, and shared instructions in a maintainable structure while preserving backward compatibility.

Current State Analysis

Existing Structure:

CLAUDE.md - Root-level Claude instructions (references ai/WORKSPACE.md and ai/CONTRIB.md)
.github/copilot-instructions.md - TypeScript/Angular best practices for Copilot
.mcp.json - Single MCP server configuration (nx-mcp)
.claude/settings.local.json - Claude permissions and MCP settings
.claude/agents/ - 3 agent definitions (codebase-locator, analyzer, pattern-finder)
.claude/commands/rpi/ - 8 RPI workflow commands
ai/WORKSPACE.md - Project overview and architecture
ai/CONTRIB.md - Contribution guidelines
ai/RPI-WORKFLOW.md - RPI workflow documentation
ai/thoughts/shared/plans/ - Empty directory for implementation plans

Issues:

No Cursor configuration
Each tool has separate configuration (not DRY)
Agents only available to Claude
Skills/commands locked to Claude format
No scalable MCP structure
Missing thought output directories (research/, sessions/, cloud/)
No clear documentation for AI tooling setup

Desired End State

A unified .ai/ directory structure where:

All tools share common instructions and configurations
MCPs are centrally configured with documentation
Agents and skills are tool-agnostic and reusable
Tool-specific overrides exist where needed
Backward compatibility is maintained via symlinks
Complete RPI workflow directories exist
Clear documentation guides AI tooling usage

What We're NOT Doing

Not modifying the docs/ directory (keeping it separate as it's outdated)
Not changing any application code or build configurations
Not modifying .gitignore (will add that as a follow-up if needed)
Not migrating or removing existing git history
Not changing how Claude Code currently works (maintaining compatibility)

Implementation Approach

Use a phased migration approach:

Create new .ai/ structure alongside existing files
Migrate content progressively with transformations where needed
Update tool configurations to reference new locations
Create symlinks for backward compatibility
Validate all tools work correctly
Clean up old locations

This ensures we can test at each phase without breaking existing functionality.

Phase 1: Create New Directory Structure

Overview

Create the new .ai/ directory with all subdirectories, README files, and .gitkeep files for empty directories.

Changes Required:

1. Create Root .ai/ Directory Structure

Directories to create:

bash

.ai/
.ai/config/
.ai/config/shared/
.ai/config/mcp/
.ai/config/tools/
.ai/agents/
.ai/agents/codebase/
.ai/skills/
.ai/skills/rpi/
.ai/thoughts/
.ai/thoughts/shared/
.ai/thoughts/shared/research/
.ai/thoughts/shared/sessions/
.ai/thoughts/shared/cloud/
.ai/thoughts/shared/plans/

2. Create Main README

File: .ai/README.md

Content:

markdown

# AI Configuration

This directory contains unified configuration for AI development tools (Claude, Cursor, GitHub Copilot) used in this repository.

## Structure

- **config/** - Shared and tool-specific configuration files
  - **shared/** - Instructions and guidelines shared across all AI tools
  - **mcp/** - Model Context Protocol (MCP) server configurations
  - **tools/** - Tool-specific configuration overrides
- **agents/** - Reusable agent definitions for specialized tasks
- **skills/** - Reusable workflow skills and commands
- **thoughts/** - Output artifacts from AI-assisted work (research, plans, sessions)

## Quick Start

### For Claude Code Users
Claude automatically reads from `.claude/settings.local.json` which references this directory.

### For Cursor Users
Cursor reads `.cursorrules` which includes instructions from `.ai/config/shared/`.

### For GitHub Copilot Users
Copilot reads `.github/copilot-instructions.md` which references `.ai/config/shared/instructions.md`.

### For MCP Configuration
All tools share MCP configuration from `.ai/config/mcp/mcp.json`.

## Documentation

- [Shared Instructions](config/shared/instructions.md) - Common coding guidelines
- [Workspace Overview](config/shared/workspace.md) - Project architecture and commands
- [Contributing Guidelines](config/shared/contributing.md) - Commit conventions and workflow
- [MCP Setup](config/mcp/README.md) - MCP server configuration guide
- [Agents Guide](agents/README.md) - Using and creating agents
- [Skills Guide](skills/README.md) - Available workflow skills

## Adding New AI Tools

To add support for a new AI tool:
1. Create tool-specific config in `config/tools/{tool-name}.md`
2. Configure tool to read from `config/shared/` for common instructions
3. Reference MCPs from `config/mcp/mcp.json`
4. Document tool-specific setup in this README

3. Create Config READMEs

File: .ai/config/README.md

Content:

markdown

# Configuration Files

## Shared Configuration

Common instructions and guidelines used by all AI tools:

- **instructions.md** - TypeScript, Angular, and coding best practices
- **workspace.md** - Project overview, architecture, development commands
- **contributing.md** - Commit message format and contribution workflow
- **workflows.md** - Special workflows like Research-Plan-Implement (RPI)

## MCP Configuration

Model Context Protocol server configuration:

- **mcp/mcp.json** - MCP server definitions
- **mcp/*.md** - Documentation for each MCP server

## Tool-Specific Configuration

Optional overrides for specific tools:

- **tools/claude.md** - Claude-specific instructions
- **tools/cursor.md** - Cursor-specific instructions
- **tools/copilot.md** - GitHub Copilot-specific instructions

## Usage by Tool

### Claude Code
Reads via `.claude/settings.local.json` and `CLAUDE.md` symlink.

### Cursor
Reads via `.cursorrules` file.

### GitHub Copilot
Reads via `.github/copilot-instructions.md` file.

File: .ai/config/mcp/README.md

Content:

markdown

# MCP Server Configuration

## Overview

Model Context Protocol (MCP) servers provide specialized capabilities to AI tools. This directory contains the shared MCP configuration used by all supported tools.

## Configuration File

**mcp.json** - Main MCP server definitions

## Configured Servers

### nx-mcp
Provides tools for working with Nx monorepo workspaces.

**Documentation**: [nx-mcp.md](./nx-mcp.md)

**Capabilities:**
- Workspace architecture and project dependency analysis
- Nx documentation retrieval
- Project details and target information
- Generator discovery and schema access
- Task monitoring and CI/CD analysis

## Adding New MCP Servers

1. Add server configuration to `mcp.json`:
```json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["package-name@latest"]
    }
  }
}

Create documentation file server-name.md with:
- Server purpose and capabilities
- Installation requirements
- Usage examples
- Configuration options
Update .claude/settings.local.json to enable the server:

json

{
  "enabledMcpjsonServers": ["nx-mcp", "server-name"]
}

Test the server with each AI tool to ensure compatibility.

Tool Support

Claude Code: Full support via .claude/settings.local.json
Cursor: Check Cursor documentation for MCP support
GitHub Copilot: MCP support status TBD


#### 4. Create Agents README

**File**: `.ai/agents/README.md`

**Content**:
```markdown
# AI Agents

## Overview

Agents are specialized AI sub-agents that can be spawned to handle specific tasks autonomously. They operate with access to specific tools and are designed for complex, multi-step work.

## Available Agents

### Codebase Agents

#### codebase-locator
**Purpose**: Find files, directories, and components relevant to a feature or task
**Tools**: Grep, Glob, LS
**Usage**: Spawn when you need to locate code without analyzing contents

#### codebase-analyzer
**Purpose**: Analyze implementation details and understand how components work
**Tools**: Read, Grep, Glob, LS
**Usage**: Spawn when you need to understand existing code implementation

#### codebase-pattern-finder
**Purpose**: Find similar implementations, usage examples, and patterns to model after
**Tools**: Grep, Glob, Read, LS
**Usage**: Spawn when implementing new features to find existing patterns

## Agent Definition Format

Agents are defined in Markdown files with frontmatter:

```markdown
---
name: agent-name
description: Brief description of agent's purpose
tools: Tool1, Tool2, Tool3
---

[Detailed instructions for the agent...]

Creating New Agents

Identify a specialized, repeatable task that requires multiple steps
Define which tools the agent needs access to
Create agent definition in appropriate subdirectory
Document the agent's purpose and usage patterns
Test the agent with various scenarios

Tool Compatibility

Claude Code: Full support via Task tool with subagent_type parameter
Cursor: Agent support status TBD
GitHub Copilot: Not applicable (doesn't support sub-agents)


#### 5. Create Skills README

**File**: `.ai/skills/README.md`

**Content**:
```markdown
# AI Skills

## Overview

Skills (also called Commands) are user-invocable workflow prompts that guide the AI through specific processes. They're reusable instructions that provide step-by-step guidance for complex workflows.

## Available Skills

### RPI (Research-Plan-Implement) Workflow

A structured workflow for tackling complex development tasks:

1. **research-codebase** - Deep codebase exploration with parallel agents
2. **create-plan** - Create detailed, phased implementation plans
3. **validate-plan** - Verify implementation matches plan specifications
4. **implement-plan** - Execute plan systematically with progress tracking
5. **save-progress** - Save work session state for later resumption
6. **resume-work** - Resume from previously saved session
7. **define-test-cases** - Define comprehensive test cases
8. **refresh-knowledge** - Refresh codebase knowledge before starting work

See [RPI Workflow Documentation](../config/shared/workflows.md) for detailed usage.

## Skill Definition Format

Skills are defined in Markdown files with clear sections:

```markdown
# Skill Name

Brief description of what this skill does.

## When to Use

- Scenario 1
- Scenario 2

## Process Steps

### Step 1: [Name]
Detailed instructions...

### Step 2: [Name]
Detailed instructions...

## Examples

[Usage examples...]

Creating New Skills

Identify a repeatable workflow that needs guidance
Break down the workflow into clear, actionable steps
Include decision points and conditional logic
Add examples of successful usage
Document when to use vs. not use the skill

Tool Compatibility

Claude Code: Full support via Skill tool (slash commands like /rpi:create_plan)
Cursor: Can be adapted as custom instructions
GitHub Copilot: Can be referenced in conversation context


#### 6. Create Thoughts .gitkeep Files

**Files to create:**

.ai/thoughts/shared/research/.gitkeep .ai/thoughts/shared/sessions/.gitkeep .ai/thoughts/shared/cloud/.gitkeep


**Note**: `.ai/thoughts/shared/plans/` already exists and contains this plan.

### Success Criteria

#### Automated Verification:
- [ ] Directory structure created: `find .ai -type d | wc -l` should show 14 directories
- [ ] README files exist: `find .ai -name "README.md" | wc -l` should show 5 files
- [ ] .gitkeep files exist: `find .ai/thoughts -name ".gitkeep" | wc -l` should show 3 files

#### Manual Verification:
- [ ] All directories exist and are properly nested
- [ ] README files are readable and contain proper formatting
- [ ] Structure matches the proposed design

---

## Phase 2: Migrate Shared Configuration Files

### Overview
Migrate and consolidate shared instruction files into the new `.ai/config/shared/` directory.

### Changes Required:

#### 1. Create Shared Instructions

**File**: `.ai/config/shared/instructions.md`

**Source**: Merge content from `.github/copilot-instructions.md` and relevant parts of `CLAUDE.md`

**Content**: TypeScript, Angular, and coding best practices (consolidated from both sources)

#### 2. Migrate Workspace Documentation

**File**: `.ai/config/shared/workspace.md`

**Action**: Copy from `ai/WORKSPACE.md`

**Changes**: None needed (content is already comprehensive)

#### 3. Migrate Contributing Guidelines

**File**: `.ai/config/shared/contributing.md`

**Action**: Copy from `ai/CONTRIB.md`

**Changes**: None needed

#### 4. Create Workflows Documentation

**File**: `.ai/config/shared/workflows.md`

**Source**: Content from `ai/RPI-WORKFLOW.md` plus expanded documentation

**Content**:
```markdown
# AI-Assisted Workflows

## Research-Plan-Implement (RPI) Framework

A structured approach to tackling complex development tasks through systematic research, detailed planning, and careful implementation.

### Overview

The RPI framework breaks down complex work into three phases:

1. **Research**: Thoroughly explore the codebase to understand context
2. **Plan**: Create detailed, phased implementation plans
3. **Implement**: Execute plans systematically with validation

### Workflow Commands

#### /rpi:research_codebase
Deep codebase exploration using parallel AI agents to understand architecture, patterns, and existing implementations.

**When to use:**
- Starting work on unfamiliar parts of the codebase
- Need to understand how existing features work
- Looking for patterns to follow for new implementation

**Output**: Research findings saved to `.ai/thoughts/shared/research/`

#### /rpi:create_plan
Create detailed, phased implementation plans through interactive, iterative process.

**When to use:**
- Before implementing non-trivial features
- When multiple approaches are possible
- For changes affecting multiple files

**Output**: Implementation plan saved to `.ai/thoughts/shared/plans/NNN_description.md`

#### /rpi:validate_plan
Verify that implementation matches the plan specifications.

**When to use:**
- After completing implementation
- Before creating pull requests
- To ensure all plan phases are complete

**Output**: Validation report

#### /rpi:implement_plan
Execute an implementation plan systematically with progress tracking.

**When to use:**
- After plan is approved
- For step-by-step guided implementation

**Output**: Updates to plan file with progress checkmarks

#### /rpi:save_progress
Save current work session state for later resumption.

**When to use:**
- End of work session
- Before switching to different task
- To preserve context for team members

**Output**: Session summary in `.ai/thoughts/shared/sessions/`

#### /rpi:resume_work
Resume from a previously saved session.

**When to use:**
- Returning to saved work
- Picking up where someone else left off

**Input**: Session file from `.ai/thoughts/shared/sessions/`

#### /rpi:define_test_cases
Define comprehensive test cases for features or changes.

**When to use:**
- During planning phase
- Before implementation
- To ensure test coverage

**Output**: Test case definitions

#### /rpi:refresh_knowledge
Refresh understanding of codebase before starting work.

**When to use:**
- After long break from codebase
- Before starting new feature work
- When codebase has changed significantly

**Output**: Updated codebase knowledge summary

### Output Locations

- **Research findings**: `.ai/thoughts/shared/research/`
- **Implementation plans**: `.ai/thoughts/shared/plans/`
- **Session summaries**: `.ai/thoughts/shared/sessions/`
- **Cloud analyses**: `.ai/thoughts/shared/cloud/`

### Best Practices

1. Always research before planning for non-trivial features
2. Get plan approval before implementation
3. Save progress at end of each session
4. Validate implementation against plan before PR
5. Document deviations from plan in implementation

Success Criteria

Automated Verification:

[ ] All files exist: ls .ai/config/shared/*.md | wc -l should show 4 files
[ ] Files are not empty: find .ai/config/shared -name "*.md" -size +0 | wc -l should show 4

Manual Verification:

[ ] instructions.md contains merged content from Copilot and Claude instructions
[ ] workspace.md matches ai/WORKSPACE.md content
[ ] contributing.md matches ai/CONTRIB.md content
[ ] workflows.md comprehensively documents RPI workflow

Phase 3: Migrate MCP Configuration

Overview

Move MCP configuration to centralized location with documentation.

Changes Required:

1. Create MCP Configuration File

File: .ai/config/mcp/mcp.json

Action: Copy from .mcp.json

Content:

json

{
  "mcpServers": {
    "nx-mcp": {
      "command": "npx",
      "args": ["nx-mcp@latest"]
    }
  }
}

2. Create nx-mcp Documentation

File: .ai/config/mcp/nx-mcp.md

Content:

markdown

# nx-mcp Server

## Overview

The Nx MCP server provides tools for working with Nx monorepo workspaces.

## Installation

```bash
npx nx-mcp@latest

Capabilities

Workspace Architecture

Understand workspace architecture and project dependencies
Retrieve project graph and configuration
Analyze nx.json settings

Documentation Access

Retrieve up-to-date Nx documentation
Get configuration options and best practices

Project Management

Explore individual project details
View project targets and execution commands
Understand project dependencies

Code Generation

Discover available generators
Access generator schemas and options
Scaffold new code following workspace patterns

CI/CD Integration

Monitor running tasks
View task output
Analyze CI/CD pipeline performance
Interact with Nx Cloud

Usage Examples

Get workspace information

Ask Claude: "What's the structure of this Nx workspace?"

Find project details

Ask Claude: "Show me the configuration for the recruitee app"

Discover generators

Ask Claude: "What Nx generators are available?"

Check CI status

Ask Claude: "What's the status of CI tasks?"

Configuration

Enabled in .claude/settings.local.json:

json

{
  "enabledMcpjsonServers": ["nx-mcp"]
}

Documentation

Official: https://www.npmjs.com/package/nx-mcp


### Success Criteria

#### Automated Verification:
- [ ] MCP config exists: `test -f .ai/config/mcp/mcp.json && echo "exists"`
- [ ] nx-mcp docs exist: `test -f .ai/config/mcp/nx-mcp.md && echo "exists"`
- [ ] JSON is valid: `node -e "require('./.ai/config/mcp/mcp.json')" && echo "valid"`

#### Manual Verification:
- [ ] mcp.json contains correct nx-mcp configuration
- [ ] nx-mcp.md documentation is comprehensive
- [ ] All MCP capabilities are documented

---

## Phase 4: Migrate Agents

### Overview
Move agent definitions to new structure with updated paths.

### Changes Required:

#### 1. Migrate codebase-locator Agent

**File**: `.ai/agents/codebase/locator.md`

**Action**: Copy from `.claude/agents/codebase-locator.md`

**Changes**: Update frontmatter to use consistent naming

```markdown
---
name: codebase-locator
description: Locates files, directories, and components relevant to a feature or task
tools: Grep, Glob, LS
category: codebase
---

[Rest of content remains the same...]

2. Migrate codebase-analyzer Agent

File: .ai/agents/codebase/analyzer.md

Action: Copy from .claude/agents/codebase-analyzer.md

Changes: Update frontmatter

markdown

---
name: codebase-analyzer
description: Analyzes codebase implementation details and how components work
tools: Read, Grep, Glob, LS
category: codebase
---

[Rest of content remains the same...]

3. Migrate codebase-pattern-finder Agent

File: .ai/agents/codebase/pattern-finder.md

Action: Copy from .claude/agents/codebase-pattern-finder.md

Changes: Update frontmatter

markdown

---
name: codebase-pattern-finder
description: Finds similar implementations, usage examples, and patterns to model after
tools: Grep, Glob, Read, LS
category: codebase
---

[Rest of content remains the same...]

Success Criteria

Automated Verification:

[ ] All agents migrated: find .ai/agents/codebase -name "*.md" | wc -l should show 3 files
[ ] Files are not empty: find .ai/agents/codebase -name "*.md" -size +0 | wc -l should show 3

Manual Verification:

[ ] All agent files have updated frontmatter with category field
[ ] Agent content is unchanged except for frontmatter
[ ] File names match pattern: locator.md, analyzer.md, pattern-finder.md

Phase 5: Migrate Skills (RPI Commands)

Overview

Move RPI workflow commands to new skills structure.

Changes Required:

1. Migrate All RPI Commands

Files to create (in .ai/skills/rpi/):

research-codebase.md (from .claude/commands/rpi/research_codebase.md)
create-plan.md (from .claude/commands/rpi/create_plan.md)
validate-plan.md (from .claude/commands/rpi/validate_plan.md)
implement-plan.md (from .claude/commands/rpi/implement_plan.md)
save-progress.md (from .claude/commands/rpi/save_progress.md)
resume-work.md (from .claude/commands/rpi/resume_work.md)
define-test-cases.md (from .claude/commands/rpi/define_test_cases.md)
refresh-knowledge.md (from .claude/commands/rpi/refresh_codebase_knowledge.md)

Changes: Update all path references from ai/thoughts/ to .ai/thoughts/

Script to update paths:

bash

# For each file, replace ai/thoughts/ with .ai/thoughts/
find .ai/skills/rpi -name "*.md" -exec sed -i '' 's|ai/thoughts/|.ai/thoughts/|g' {} \;

Success Criteria

Automated Verification:

[ ] All skills migrated: find .ai/skills/rpi -name "*.md" | wc -l should show 8 files
[ ] No old paths remain: grep -r "ai/thoughts/" .ai/skills/rpi/ | wc -l should show 0
[ ] New paths present: grep -r ".ai/thoughts/" .ai/skills/rpi/ | wc -l should be > 0

Manual Verification:

[ ] All RPI skills are present and readable
[ ] File names use hyphens instead of underscores
[ ] All references to output paths are updated

Phase 6: Update Tool-Specific Configurations

Overview

Update tool-specific configuration files to reference the new .ai/ structure.

Changes Required:

1. Update Claude Configuration

File: .claude/settings.local.json

Changes: Update to reference new MCP location (will use symlink)

New content:

json

{
  "permissions": {
    "allow": [
      "Bash(find:*)",
      "Bash(node -e:*)",
      "Bash(node /private/tmp/claude-501/-Users-adam-Recruitee-recruitee/99c39201-f895-46e3-80ae-4836f4a8e3cc/scratchpad/count-keys.js:*)",
      "Bash(for app in /Users/adam/Recruitee/recruitee/domains/*/apps/*/src/main.ts /Users/adam/Recruitee/recruitee/domains/*/apps/*/src/bootstrap.ts)",
      "Bash(do)",
      "Bash(if [ -f \"$app\" ])",
      "Bash(then)",
      "Bash(if grep -q \"translate\\\\|appTranslations\" \"$app\")",
      "Bash(echo:*)",
      "Bash(fi)",
      "Bash(done)",
      "Bash(cat:*)",
      "Bash(chmod:*)",
      "Bash(node tools/translations/remove-unused-webapp-keys.mjs:*)"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": [
    "nx-mcp"
  ]
}

Note: MCP configuration will be read from .mcp.json symlink

2. Update CLAUDE.md Root File

File: CLAUDE.md

Changes: Update to reference new structure

New content:

markdown

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Important Instructions

This repository uses a unified AI configuration structure. All shared instructions and guidelines are located in the `.ai/` directory.

### Core Documentation

- @.ai/config/shared/instructions.md - TypeScript, Angular, and coding best practices
- @.ai/config/shared/workspace.md - Project overview, architecture, development commands
- @.ai/config/shared/contributing.md - Commit message format and contribution workflow
- @.ai/config/shared/workflows.md - RPI and other AI-assisted workflows

### Additional Resources

- Agents: `.ai/agents/` - Specialized sub-agents for specific tasks
- Skills: `.ai/skills/` - Reusable workflow commands
- MCPs: `.ai/config/mcp/` - Model Context Protocol server configuration

For more information about the AI tooling setup, see `.ai/README.md`.

3. Create Cursorrules File

File: .cursorrules

Content:

markdown

# Cursor Configuration

This repository uses unified AI configuration from the `.ai/` directory.

## Shared Instructions

@.ai/config/shared/instructions.md
@.ai/config/shared/workspace.md
@.ai/config/shared/contributing.md

## Cursor-Specific Notes

You have access to the same coding guidelines and project context as other AI tools. Follow the TypeScript, Angular, and architectural patterns defined in the shared instructions.

For additional context:
- RPI Workflows: `.ai/config/shared/workflows.md`
- Project structure: See workspace.md for complete monorepo architecture
- Available agents: `.ai/agents/README.md`

4. Update Copilot Instructions

File: .github/copilot-instructions.md

Changes: Update to reference shared instructions

New content:

markdown

# GitHub Copilot Configuration

This repository uses unified AI configuration from the `.ai/` directory.

## Core Instructions

For complete coding guidelines, see:
- `.ai/config/shared/instructions.md` - TypeScript, Angular, and coding best practices
- `.ai/config/shared/workspace.md` - Project architecture and development commands
- `.ai/config/shared/contributing.md` - Commit conventions and workflow

## Quick Reference (Inline Copy)

[Include key highlights from instructions.md here for Copilot's quick access]

### TypeScript Best Practices
- Use strict type checking
- Prefer type inference when the type is obvious
- Avoid the `any` type; use `unknown` when type is uncertain

### Angular Best Practices
- Always use standalone components over NgModules
- Don't use explicit `standalone: true` (it is implied by default)
- Use signals for state management
- Use `input()` and `output()` functions instead of decorators
- Set `changeDetection: ChangeDetectionStrategy.OnPush`
- Use native control flow: `@if`, `@for`, `@switch`

### Component Standards
- Keep components focused on single responsibility
- Use `computed()` for derived state
- Prefer Reactive forms over Template-driven ones
- Use class/style bindings instead of `ngClass`/`ngStyle`

### Styling (CSS/Less)
- Use variables from `'theme/vars'` for consistency
- Use `:host` for component scoping
- Use `rem` for font sizes (0.1rem = 1px), `px` for borders/paddings
- Never hardcode colors - always use theme variables
- Use attribute utilities: `layout`, `padding-tb-small-xx`, etc.

For complete details, see `.ai/config/shared/instructions.md`.

5. Create Tool-Specific Config Files

File: .ai/config/tools/claude.md

Content:

markdown

# Claude-Specific Configuration

## Overview

Claude Code reads configuration from multiple locations:
1. `.claude/settings.local.json` - Permissions and MCP settings
2. `CLAUDE.md` - Main instructions file (references shared config)
3. `.ai/config/shared/` - Shared instructions and guidelines

## Claude-Specific Features

### Agents
Claude can spawn specialized sub-agents from `.ai/agents/` using the Task tool.

### Skills (Slash Commands)
Claude supports workflow skills from `.ai/skills/` via slash commands:
- `/rpi:research_codebase`
- `/rpi:create_plan`
- `/rpi:implement_plan`
- etc.

### MCP Servers
Claude reads MCP configuration from `.mcp.json` (symlinked to `.ai/config/mcp/mcp.json`).

## Additional Notes

No Claude-specific instruction overrides are currently needed. All instructions are shared across tools.

File: .ai/config/tools/cursor.md

Content:

markdown

# Cursor-Specific Configuration

## Overview

Cursor reads configuration from:
1. `.cursorrules` - Main configuration file (references shared config)
2. `.ai/config/shared/` - Shared instructions and guidelines

## Cursor-Specific Features

Cursor has access to the same guidelines as other tools. Check Cursor documentation for:
- MCP support status
- Custom command support
- Agent-like functionality

## Additional Notes

No Cursor-specific instruction overrides are currently needed. All instructions are shared across tools.

File: .ai/config/tools/copilot.md

Content:

markdown

# GitHub Copilot-Specific Configuration

## Overview

GitHub Copilot reads configuration from:
1. `.github/copilot-instructions.md` - Main instructions file
2. `.ai/config/shared/` - Shared instructions and guidelines (referenced)

## Copilot-Specific Features

GitHub Copilot works best with:
- Inline code suggestions
- Code completion based on context
- Instructions provided in `.github/copilot-instructions.md`

## Limitations

- No MCP support (as of current version)
- No agent/sub-agent support
- No custom command/skill invocation

## Additional Notes

Copilot instructions file includes inline copy of key guidelines for quick access, since Copilot may not follow file references as reliably as other tools.

Success Criteria

Automated Verification:

[ ] CLAUDE.md references new paths: grep -q ".ai/config/shared" CLAUDE.md && echo "updated"
[ ] .cursorrules exists: test -f .cursorrules && echo "exists"
[ ] Tool configs exist: find .ai/config/tools -name "*.md" | wc -l should show 3 files

Manual Verification:

[ ] CLAUDE.md properly references new structure
[ ] .cursorrules includes shared instructions
[ ] copilot-instructions.md references shared config with inline highlights
[ ] All tool-specific config files are documented

Phase 7: Create Symlinks for Backward Compatibility

Overview

Create symlinks to maintain backward compatibility with existing tools and scripts.

Changes Required:

1. Create MCP Configuration Symlink

Command:

bash

cd /Users/adam/Recruitee/recruitee
rm -f .mcp.json
ln -s .ai/config/mcp/mcp.json .mcp.json

Purpose: Claude and other tools expect .mcp.json at repository root

2. Create ai/ Directory Symlink

Command:

bash

cd /Users/adam/Recruitee/recruitee
rm -rf ai/
ln -s .ai ai

Purpose: Maintain backward compatibility for any scripts or documentation referencing ai/ path

3. Update .claude/agents Symlink

Command:

bash

cd /Users/adam/Recruitee/recruitee/.claude
rm -rf agents/
ln -s ../.ai/agents agents

Purpose: Claude looks for agents in .claude/agents/

4. Update .claude/commands Symlink

Command:

bash

cd /Users/adam/Recruitee/recruitee/.claude
rm -rf commands/
ln -s ../.ai/skills commands

Purpose: Claude looks for commands/skills in .claude/commands/

Success Criteria

Automated Verification:

[ ] .mcp.json is symlink: test -L .mcp.json && echo "is symlink"
[ ] ai/ is symlink: test -L ai && echo "is symlink"
[ ] .claude/agents is symlink: test -L .claude/agents && echo "is symlink"
[ ] .claude/commands is symlink: test -L .claude/commands && echo "is symlink"
[ ] Symlinks are valid: find . -maxdepth 2 -type l ! -exec test -e {} \; -print | wc -l should show 0 (no broken symlinks)

Manual Verification:

[ ] Can access .mcp.json and see nx-mcp config
[ ] Can navigate to ai/ and see all subdirectories
[ ] Can access .claude/agents/ and see agent definitions
[ ] Can access .claude/commands/rpi/ and see skill files

Phase 8: Validation and Cleanup

Overview

Validate that all tools work correctly with new structure and clean up old files if needed.

Changes Required:

1. Validate Claude Code Works

Manual tests:

bash

# Test that Claude can read instructions
# Check CLAUDE.md is properly loaded

# Test MCP configuration
# Verify nx-mcp tools are available

# Test agents are accessible
# Try spawning a codebase-locator agent

# Test skills are accessible
# Try running /rpi:create_plan command

2. Validate Cursor Works

Manual tests:

bash

# Open Cursor
# Check that .cursorrules is loaded
# Verify coding guidelines are available
# Test code suggestions follow guidelines

3. Validate GitHub Copilot Works

Manual tests:

bash

# Open VS Code with Copilot
# Check that instructions are loaded
# Test code suggestions follow guidelines

4. Create Validation Script

File: .ai/scripts/validate-config.sh

Content:

bash

#!/bin/bash

echo "Validating AI Configuration Structure..."
echo

# Check directories
echo "Checking directories..."
REQUIRED_DIRS=(
  ".ai"
  ".ai/config"
  ".ai/config/shared"
  ".ai/config/mcp"
  ".ai/config/tools"
  ".ai/agents"
  ".ai/agents/codebase"
  ".ai/skills"
  ".ai/skills/rpi"
  ".ai/thoughts/shared/research"
  ".ai/thoughts/shared/plans"
  ".ai/thoughts/shared/sessions"
  ".ai/thoughts/shared/cloud"
)

for dir in "${REQUIRED_DIRS[@]}"; do
  if [ -d "$dir" ]; then
    echo "  ✓ $dir"
  else
    echo "  ✗ $dir (missing)"
    exit 1
  fi
done

echo
echo "Checking files..."

# Check required files
REQUIRED_FILES=(
  ".ai/README.md"
  ".ai/config/README.md"
  ".ai/config/shared/instructions.md"
  ".ai/config/shared/workspace.md"
  ".ai/config/shared/contributing.md"
  ".ai/config/shared/workflows.md"
  ".ai/config/mcp/README.md"
  ".ai/config/mcp/mcp.json"
  ".ai/config/mcp/nx-mcp.md"
  ".ai/config/tools/claude.md"
  ".ai/config/tools/cursor.md"
  ".ai/config/tools/copilot.md"
  ".ai/agents/README.md"
  ".ai/agents/codebase/locator.md"
  ".ai/agents/codebase/analyzer.md"
  ".ai/agents/codebase/pattern-finder.md"
  ".ai/skills/README.md"
  "CLAUDE.md"
  ".cursorrules"
  ".github/copilot-instructions.md"
)

for file in "${REQUIRED_FILES[@]}"; do
  if [ -f "$file" ]; then
    echo "  ✓ $file"
  else
    echo "  ✗ $file (missing)"
    exit 1
  fi
done

echo
echo "Checking symlinks..."

# Check symlinks
SYMLINKS=(
  ".mcp.json"
  "ai"
  ".claude/agents"
  ".claude/commands"
)

for link in "${SYMLINKS[@]}"; do
  if [ -L "$link" ]; then
    if [ -e "$link" ]; then
      echo "  ✓ $link -> $(readlink "$link")"
    else
      echo "  ✗ $link (broken symlink)"
      exit 1
    fi
  else
    echo "  ✗ $link (not a symlink)"
    exit 1
  fi
done

echo
echo "Validating RPI skills..."

# Check RPI skills
RPI_SKILLS=(
  ".ai/skills/rpi/research-codebase.md"
  ".ai/skills/rpi/create-plan.md"
  ".ai/skills/rpi/validate-plan.md"
  ".ai/skills/rpi/implement-plan.md"
  ".ai/skills/rpi/save-progress.md"
  ".ai/skills/rpi/resume-work.md"
  ".ai/skills/rpi/define-test-cases.md"
  ".ai/skills/rpi/refresh-knowledge.md"
)

for skill in "${RPI_SKILLS[@]}"; do
  if [ -f "$skill" ]; then
    echo "  ✓ $skill"
  else
    echo "  ✗ $skill (missing)"
    exit 1
  fi
done

echo
echo "Checking for old path references..."

# Check that no old paths remain in skills
OLD_PATHS=$(grep -r "ai/thoughts/" .ai/skills/ 2>/dev/null | wc -l)
if [ "$OLD_PATHS" -eq 0 ]; then
  echo "  ✓ No old path references in skills"
else
  echo "  ✗ Found $OLD_PATHS old path references in skills"
  grep -r "ai/thoughts/" .ai/skills/
  exit 1
fi

echo
echo "✓ All validations passed!"
echo
echo "AI Configuration structure is valid and ready to use."

Make executable:

bash

chmod +x .ai/scripts/validate-config.sh

5. Document Old File Locations (Optional)

File: .ai/MIGRATION.md

Content:

markdown

# Migration from Old Structure

This document tracks the migration from the old AI configuration structure to the new unified structure.

## Old → New Mappings

### Configuration Files
- `CLAUDE.md` → Updated to reference `.ai/config/shared/`
- `ai/WORKSPACE.md` → `.ai/config/shared/workspace.md`
- `ai/CONTRIB.md` → `.ai/config/shared/contributing.md`
- `ai/RPI-WORKFLOW.md` → `.ai/config/shared/workflows.md`
- `.github/copilot-instructions.md` → Updated to reference `.ai/config/shared/instructions.md`
- `.mcp.json` → `.ai/config/mcp/mcp.json` (symlinked back)

### Agents
- `.claude/agents/codebase-locator.md` → `.ai/agents/codebase/locator.md`
- `.claude/agents/codebase-analyzer.md` → `.ai/agents/codebase/analyzer.md`
- `.claude/agents/codebase-pattern-finder.md` → `.ai/agents/codebase/pattern-finder.md`

### Skills/Commands
- `.claude/commands/rpi/research_codebase.md` → `.ai/skills/rpi/research-codebase.md`
- `.claude/commands/rpi/create_plan.md` → `.ai/skills/rpi/create-plan.md`
- `.claude/commands/rpi/validate_plan.md` → `.ai/skills/rpi/validate-plan.md`
- `.claude/commands/rpi/implement_plan.md` → `.ai/skills/rpi/implement-plan.md`
- `.claude/commands/rpi/save_progress.md` → `.ai/skills/rpi/save-progress.md`
- `.claude/commands/rpi/resume_work.md` → `.ai/skills/rpi/resume-work.md`
- `.claude/commands/rpi/define_test_cases.md` → `.ai/skills/rpi/define-test-cases.md`
- `.claude/commands/rpi/refresh_codebase_knowledge.md` → `.ai/skills/rpi/refresh-knowledge.md`

### Symlinks Created
- `.mcp.json` → `.ai/config/mcp/mcp.json`
- `ai/` → `.ai/`
- `.claude/agents/` → `.ai/agents/`
- `.claude/commands/` → `.ai/skills/`

## Backward Compatibility

All old paths remain accessible via symlinks. No scripts or workflows should break.

## Old Files Status

Old files in original locations can be safely removed after validation, as they are now:
1. Migrated to new locations
2. Accessible via symlinks
3. Referenced from new structure

## Migration Date

[To be filled in after completion]

Success Criteria

Automated Verification:

[ ] Validation script exists: test -f .ai/scripts/validate-config.sh && echo "exists"
[ ] Validation script is executable: test -x .ai/scripts/validate-config.sh && echo "executable"
[ ] Validation script passes: .ai/scripts/validate-config.sh exits with code 0

Manual Verification:

[ ] Claude Code can load instructions and access MCP
[ ] Claude Code can spawn agents from new location
[ ] Claude Code skills (/rpi:*) work from new location
[ ] Cursor can read .cursorrules and shared instructions
[ ] GitHub Copilot can read updated instructions
[ ] All symlinks are valid and point to correct locations
[ ] No broken references in any configuration files

Testing Strategy

Unit Testing

Not applicable - this is a configuration restructure without code changes.

Integration Testing

Claude Code Integration
- Load Claude Code in repository
- Verify CLAUDE.md is loaded correctly
- Test MCP tools are available (nx-mcp functions)
- Spawn each agent type and verify they work
- Run each RPI skill command and verify they execute
- Create test plan in .ai/thoughts/shared/plans/ to verify output location
Cursor Integration
- Open repository in Cursor
- Verify .cursorrules is loaded
- Check that shared instructions are accessible
- Test code suggestions follow guidelines
GitHub Copilot Integration
- Open repository in VS Code with Copilot
- Verify instructions are loaded
- Test code suggestions follow guidelines
- Check inline suggestions match coding standards
MCP Functionality
- Test nx-mcp tools in Claude
- Verify MCP configuration is read from new location
- Test adding a new MCP server to validate extensibility

Manual Testing Steps

Verify Directory Structure
bash
```
tree -L 4 .ai
```
Confirm all directories and files are present
Test Symlinks
bash
```
ls -la .mcp.json ai .claude/agents .claude/commands
```
Verify all symlinks exist and point to correct locations
Run Validation Script
bash
```
.ai/scripts/validate-config.sh
```
Should pass all checks
Test Each Tool
- Test Claude Code with all features
- Test Cursor with shared instructions
- Test Copilot with updated instructions
Test RPI Workflow End-to-End
- Run /rpi:research_codebase on a sample topic
- Run /rpi:create_plan for a sample feature
- Verify outputs go to correct .ai/thoughts/ locations
Check Documentation
- Read .ai/README.md and verify links work
- Check all README files in subdirectories
- Verify MCP documentation is accessible

Performance Considerations

This restructure should have minimal performance impact:

Symlinks add negligible overhead
File reads are unchanged (same content, new locations)
No additional processing required

Potential benefits:

Clearer organization may improve AI tool context loading
Centralized configuration reduces redundant file reads
Better structure for future scalability

Migration Notes

Rollback Plan

If issues arise, rollback is straightforward:

Remove symlinks:

bash

rm -f .mcp.json ai
rm -f .claude/agents .claude/commands

Restore original files from git:

bash

git checkout HEAD -- .mcp.json ai/ .claude/

Remove .ai/ directory:
bash
```
rm -rf .ai
```

Git Considerations

Add .ai/ to git (not in .gitignore)
Commit symlinks to git
Consider adding .ai/thoughts/ to .gitignore (except README files)
Old ai/ directory will be replaced by symlink

Future Extensibility

This structure supports future additions:

New MCP Servers: Add to .ai/config/mcp/mcp.json and create docs
New Agents: Add to appropriate .ai/agents/ subdirectory
New Skills: Add to appropriate .ai/skills/ subdirectory
New Tools: Add tool-specific config in .ai/config/tools/
New Workflows: Document in .ai/config/shared/workflows.md

Communication

After implementation:

Update team documentation about new structure
Share .ai/README.md as primary reference
Document how to add new MCPs, agents, or skills
Update onboarding materials

Completion Checklist

[x] Phase 1: Directory structure created
[x] Phase 2: Shared configuration migrated
[x] Phase 3: MCP configuration migrated
[x] Phase 4: Agents migrated
[x] Phase 5: Skills migrated
[x] Phase 6: Tool configurations updated
[x] Phase 7: Symlinks created
[x] Phase 8: Validation completed
[x] All automated tests pass
[ ] All manual tests pass
[x] Documentation is complete
[ ] Team is notified

mcp

AI Configuration Restructure Implementation Plan ​

Overview ​

Current State Analysis ​

Desired End State ​

What We're NOT Doing ​

Implementation Approach ​

Phase 1: Create New Directory Structure ​

Overview ​

Changes Required: ​

1. Create Root .ai/ Directory Structure ​

2. Create Main README ​

3. Create Config READMEs ​

Tool Support ​

Creating New Agents ​

Tool Compatibility ​

Creating New Skills ​

Tool Compatibility ​

Success Criteria ​

Automated Verification: ​

Manual Verification: ​

Phase 3: Migrate MCP Configuration ​

Overview ​

Changes Required: ​

1. Create MCP Configuration File ​

2. Create nx-mcp Documentation ​

Capabilities ​

Workspace Architecture ​

Documentation Access ​

Project Management ​

Code Generation ​

CI/CD Integration ​

Usage Examples ​

Get workspace information ​

Find project details ​

Discover generators ​

Check CI status ​

Configuration ​

Documentation ​

2. Migrate codebase-analyzer Agent ​

3. Migrate codebase-pattern-finder Agent ​

Success Criteria ​

Automated Verification: ​

Manual Verification: ​

Phase 5: Migrate Skills (RPI Commands) ​

Overview ​

Changes Required: ​

1. Migrate All RPI Commands ​

Success Criteria ​

Automated Verification: ​

Manual Verification: ​

Phase 6: Update Tool-Specific Configurations ​

Overview ​

Changes Required: ​

1. Update Claude Configuration ​

2. Update CLAUDE.md Root File ​

3. Create Cursorrules File ​

4. Update Copilot Instructions ​

5. Create Tool-Specific Config Files ​

Success Criteria ​

Automated Verification: ​

Manual Verification: ​

Phase 7: Create Symlinks for Backward Compatibility ​

Overview ​

Changes Required: ​

1. Create MCP Configuration Symlink ​

2. Create ai/ Directory Symlink ​

3. Update .claude/agents Symlink ​

4. Update .claude/commands Symlink ​

Success Criteria ​

Automated Verification: ​

Manual Verification: ​

Phase 8: Validation and Cleanup ​

Overview ​

Changes Required: ​

1. Validate Claude Code Works ​

2. Validate Cursor Works ​

3. Validate GitHub Copilot Works ​

4. Create Validation Script ​

5. Document Old File Locations (Optional) ​

AI Configuration Restructure Implementation Plan

Overview

Current State Analysis

Desired End State

What We're NOT Doing

Implementation Approach

Phase 1: Create New Directory Structure

Overview

Changes Required:

1. Create Root .ai/ Directory Structure

2. Create Main README

3. Create Config READMEs

Tool Support

Creating New Agents

Tool Compatibility

Creating New Skills

Tool Compatibility

Success Criteria

Automated Verification:

Manual Verification:

Phase 3: Migrate MCP Configuration

Overview

Changes Required:

1. Create MCP Configuration File

2. Create nx-mcp Documentation

Capabilities

Workspace Architecture

Documentation Access

Project Management

Code Generation

CI/CD Integration

Usage Examples

Get workspace information

Find project details

Discover generators

Check CI status

Configuration

Documentation

2. Migrate codebase-analyzer Agent

3. Migrate codebase-pattern-finder Agent

Success Criteria

Automated Verification:

Manual Verification:

Phase 5: Migrate Skills (RPI Commands)

Overview

Changes Required:

1. Migrate All RPI Commands

Success Criteria

Automated Verification:

Manual Verification:

Phase 6: Update Tool-Specific Configurations

Overview

Changes Required:

1. Update Claude Configuration

2. Update CLAUDE.md Root File

3. Create Cursorrules File

4. Update Copilot Instructions

5. Create Tool-Specific Config Files

Success Criteria

Automated Verification:

Manual Verification:

Phase 7: Create Symlinks for Backward Compatibility

Overview

Changes Required:

1. Create MCP Configuration Symlink

2. Create ai/ Directory Symlink

3. Update .claude/agents Symlink

4. Update .claude/commands Symlink

Success Criteria

Automated Verification:

Manual Verification:

Phase 8: Validation and Cleanup

Overview

Changes Required:

1. Validate Claude Code Works

2. Validate Cursor Works

3. Validate GitHub Copilot Works

4. Create Validation Script

5. Document Old File Locations (Optional)

Success Criteria