ADR-027: CODITECT Skills Container Integration and Multi-CLI Compatibility

Status: Proposed Date: 2025-10-19 Decision Makers: Engineering Team Consulted: Web research on 9 major llm CLI tools (Claude Code, Gemini, Aider, Cursor, Windsurf, Amazon Q, JetBrains, GitHub Copilot, theia)

Context

CODITECT has developed 14 proven automation skills (build-deploy-workflow, gcp-resource-cleanup, git-workflow-automation, token-cost-tracking, etc.) that provide significant value:

Time savings: 89 min/day per user (build-deploy 40min, cleanup 28min, git 8min, docs 13min)
Token efficiency: 70-80% reduction vs reinventing solutions
Cost savings: $50-100/month in cloud resources + token budget optimization
ROI: 17-34x return on investment for users

Current State:

Skills are in .claude/ directory (tied to Claude Code branding)
Only accessible to developers working on T2 project locally
Not available to CODITECT end-users in production containers

User Requirements:

Deliver skills to CODITECT users (MONITOR, CODI, and other capabilities)
Support multiple llm CLIs (Claude Code, Cursor, Windsurf, Amazon Q, Gemini, JetBrains, future tools)
Enable automatic updates via container versioning
Maintain brand identity (CODITECT vs Claude)

Key Questions:

Should .claude/ be renamed to .coditect/ for brand alignment?
Will renaming break compatibility with Claude Code and other llm CLIs?
How should skills be delivered in containers (baked in, ConfigMap, API)?
How to version and update skills in production?

Related Documentation:

Multi-CLI Configuration Discovery Patterns - Web research findings
Token Cost Tracking Skill
Build Deploy Workflow Skill

Decision

We will implement a phased approach with dual-path compatibility:

Phase 1: Immediate (Sprint 3 - 1 day)

Use .coditect/ as primary directory with environment variable compatibility

Directory Structure:

/workspace/.coditect/           # Primary configuration directory
  ├── skills/                   # 14 automation skills
  │   ├── REGISTRY.json         # Fast skill discovery
  │   ├── build-deploy-workflow/
  │   ├── gcp-resource-cleanup/
  │   ├── git-workflow-automation/
  │   ├── token-cost-tracking/
  │   └── ...
  ├── agents/                   # 8 specialized agents
  │   ├── orchestrator.md
  │   ├── codebase-analyzer.md
  │   └── ...
  ├── commands/                 # 52 workflow commands
  ├── mcp.json                  # MCP server configuration
  └── settings.json             # CODITECT settings

/workspace/.claude/    → .coditect/  # Symlink for backwards compatibility
/workspace/.theia/     → .coditect/  # Optional (theia uses THEIA_CONFIG_DIR)

Environment Variables (set in container):

export THEIA_CONFIG_DIR=/workspace/.coditect      # theia native
export CLAUDE_CONFIG_DIR=/workspace/.coditect     # Claude Code compat
export CODITECT_CONFIG_DIR=/workspace/.coditect   # Primary
export XDG_CONFIG_HOME=/workspace/.config         # Linux standard

Phase 2: ConfigMap Updates (Sprint 4 - 4 hours)

Enable centralized skill updates without container rebuild

# kubernetes/configmap-skills.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: coditect-skills
  namespace: coditect-app
data:
  REGISTRY.json: |
    {
      "version": "1.1.0",
      "skills": [...]
    }
  # Individual skill files as keys

Mount in Deployment:

volumeMounts:
  - name: skills-config
    mountPath: /workspace/.coditect/skills
    readOnly: true

Phase 3: Per-User Overlay (Sprint 5 - 1 week)

Allow users to customize base skills

Base Skills (read-only):
  /workspace/.coditect/skills/     # Container-provided

User Customizations (read-write):
  /workspace/.coditect-user/       # Per-user volume
    ├── skills/                    # User-added skills
    └── settings.json              # User preferences

Merged at runtime: base + user customizations

Phase 4: Skills API Marketplace (Future - 1 month)

Community-contributed skills via API

// Skills API
GET /api/v5/skills                  # List available skills
GET /api/v5/skills/:name            # Get skill details
POST /api/v5/skills/:name/install   # Install skill
POST /api/v5/skills/                # Publish skill (authenticated)

Rationale

Why `.coditect/` Instead of `.claude/`

Brand Alignment:

Product name is "CODITECT AI IDE", not "Claude IDE"
.coditect/ aligns with company branding and product identity
Avoids confusion with Anthropic's Claude Code product
Establishes independent brand presence

Technical Compatibility:

Most CLIs support environment variables for custom paths:
- ✅ Claude Code: CLAUDE_CONFIG_DIR (excellent support)
- ✅ theia: THEIA_CONFIG_DIR (excellent support, XDG compliant)
- ⚠️ Gemini: Hardcoded ~/.gemini (requires separate directory)
- ⚠️ Amazon Q: Hardcoded ~/.aws/amazonq (requires separate directory)
- ⚠️ Cursor/Windsurf: Project-level configs work (.cursor/, .windsurfrules)
Symlinks provide backwards compatibility for tools without env var support

CLI Compatibility Matrix:

Tool	Compatibility Method	Status	Notes
Claude Code	`CLAUDE_CONFIG_DIR=/workspace/.coditect`	✅ Full	Native env var support
Eclipse theia	`THEIA_CONFIG_DIR=/workspace/.coditect`	✅ Full	Native env var + XDG
Cursor	Project config `.cursor/mcp.json`	✅ Partial	MCP config only
Windsurf	Symlink `~/.codeium/windsurf → .coditect`	⚠️ Untested	May work
Amazon Q	Project config `.amazonq/mcp.json`	✅ Partial	MCP config only
Gemini CLI	Separate `.gemini/` directory	⚠️ Limited	Hardcoded path
Aider	Symlink `~/.aider.conf.yml → .coditect/aider.conf.yml`	⚠️ Untested	May work
JetBrains	`IDEA_PROPERTIES` with custom paths	✅ Partial	Product-specific
GitHub Copilot	`VSCODE_EXTENSIONS=/workspace/.coditect/extensions`	✅ Partial	Extensions only

Risk Mitigation:

Symlink fallback for tools without env var support
Project-level configs (.cursor/, .amazonq/) for tools requiring specific paths
Backwards compatibility maintained via .claude/ symlink

Why Phased Approach

Phase 1 Benefits:

Fast: 1 day implementation
Low Risk: Backwards compatible via symlinks
High Value: Immediate user access to 14 skills
Validates Concept: Test user adoption before complex infrastructure

Phase 2 Benefits:

Centralized Updates: Update skills without container rebuild
Faster Deployment: No image rebuild for skill changes
Easier Rollback: Revert ConfigMap vs container image

Phase 3 Benefits:

User Customization: Per-user skill additions and settings
Multi-Tenancy: Isolate user customizations
Personalization: Users can add custom workflows

Phase 4 Benefits:

Community Growth: Users contribute and share skills
Marketplace Revenue: Potential monetization opportunity
Network Effects: More skills = more value = more users

Consequences

Positive

Brand Consistency:
- .coditect/ aligns with product name and company branding
- Establishes independent identity separate from Claude Code
- Professional appearance for enterprise users
Multi-CLI Support:
- Works with Claude Code, theia, Cursor, Windsurf, Amazon Q, JetBrains
- Future-proof for new llm CLIs (environment variable pattern is standard)
- Symlink fallback for tools without env var support
Token Efficiency:
- 70-80% reduction in token usage (using skills vs reinventing)
- Example: 5,000 tokens (reinvent) → 1,500 tokens (use skill)
- Projected savings: $500-1,000/month across user base
Time Savings:
- 89 min/day per user (build-deploy 40min, cleanup 28min, git 8min, docs 13min)
- 370 hours/year per user
- ROI: 17-34x for users
Cost Optimization:
- GCP resource cleanup saves $50-100/month per user
- Token cost tracking enables budget management
- Build automation reduces manual errors and deployment time
Scalability:
- ConfigMap updates (Phase 2) enable rapid skill distribution
- Per-user overlay (Phase 3) supports customization
- Skills API (Phase 4) enables marketplace ecosystem

Negative

Migration Effort:
- Rename .claude/ → .coditect/ in container images
- Update Dockerfiles with new COPY paths
- Test symlink compatibility with all CLIs
- Mitigation: Automate with script, test thoroughly
Symlink Risks:
- Claude Code has known symlink bugs (Issue #764)
- Relative paths may fail in symlinked directories
- Mitigation: Use CLAUDE_CONFIG_DIR instead of symlinks where possible
CLI-Specific Limitations:
- Gemini CLI: Cannot use .coditect/ directly (hardcoded ~/.gemini)
- Amazon Q: Cannot use .coditect/ directly (hardcoded ~/.aws/amazonq)
- Mitigation: Provide project-level configs (.gemini/, .amazonq/)
Documentation Burden:
- Must document CLI-specific setup for each tool
- Users need guidance on environment variable configuration
- Mitigation: Create comprehensive setup guide per CLI
Testing Complexity:
- Must test with multiple CLIs (Claude Code, Cursor, Windsurf, etc.)
- Each CLI has different configuration patterns
- Mitigation: Create automated test suite for each CLI

Risks

Symlink Compatibility (Medium Risk):
- Some CLIs may not follow symlinks correctly
- Mitigation: Test all CLIs, fall back to environment variables
Environment Variable Precedence (Low Risk):
- Multiple env vars may conflict (CLAUDE_CONFIG_DIR vs THEIA_CONFIG_DIR)
- Mitigation: Clear precedence order documented
User Confusion (Low Risk):
- Users may not understand which directory to use
- Mitigation: Clear documentation, single-command setup script
Future CLI Changes (Low Risk):
- New CLIs may not support environment variables
- Mitigation: Monitor CLI ecosystem, adapt as needed

Implementation Plan

Phase 1: Dual-Path Support (Sprint 3 - 1 day)

Step 1: Rename Directory (30 min)

# In repository
cd /home/hal/v4/PROJECTS/t2
git mv .claude .coditect

# Update .gitignore
sed -i 's/.claude/.coditect/g' .gitignore

# Commit
git add .
git commit -m "feat(config): Rename .claude → .coditect for brand alignment

- Establish CODITECT brand identity
- Maintain CLI compatibility via environment variables
- Ref: ADR-027"

Step 2: Update dockerfile.combined (30 min)

# Before
COPY .claude/ /workspace/.claude/

# After
COPY .coditect/ /workspace/.coditect/

# Add environment variables
ENV THEIA_CONFIG_DIR=/workspace/.coditect
ENV CLAUDE_CONFIG_DIR=/workspace/.coditect
ENV CODITECT_CONFIG_DIR=/workspace/.coditect

# Create backwards-compatible symlink
RUN ln -s /workspace/.coditect /workspace/.claude

Step 3: Update Documentation (1 hour)

# Update CLAUDE.md
# Update README.md
# Update .coditect/CLAUDE.md
# Create SETUP-GUIDE.md for each CLI

Step 4: Build and Test (2 hours)

# Build new image
gcloud builds submit --config cloudbuild-combined.yaml .

# Test with Claude Code
export CLAUDE_CONFIG_DIR=/workspace/.coditect
claude

# Test with theia
export THEIA_CONFIG_DIR=/workspace/.coditect
theia

# Verify symlink works
ls -la /workspace/.claude  # Should point to .coditect

Total Phase 1 Time: 4 hours

Phase 2: ConfigMap Updates (Sprint 4 - 4 hours)

Step 1: Create ConfigMap (1 hour)

# kubernetes/configmap-skills.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: coditect-skills
  namespace: coditect-app
  labels:
    app: coditect
    component: skills
    version: "1.0.0"
data:
  REGISTRY.json: |
    {
      "version": "1.0.0",
      "skills": [...]
    }
  # Add each skill as individual key

Step 2: Update Deployment (1 hour)

# kubernetes/deployment-combined.yaml
volumeMounts:
  - name: skills-config
    mountPath: /workspace/.coditect/skills
    readOnly: true

volumes:
  - name: skills-config
    configMap:
      name: coditect-skills

Step 3: Test Updates (2 hours)

# Update ConfigMap
kubectl apply -f kubernetes/configmap-skills.yaml

# Verify mounted correctly
kubectl exec -it deployment/coditect-combined -- ls -la /workspace/.coditect/skills

# Test skill discovery
kubectl exec -it deployment/coditect-combined -- cat /workspace/.coditect/skills/REGISTRY.json

Total Phase 2 Time: 4 hours

Phase 3: Per-User Overlay (Sprint 5 - 1 week)

Step 1: Design Merge Logic (1 day)

Load base skills from /workspace/.coditect/skills/ (read-only)
Load user skills from /workspace/.coditect-user/skills/ (read-write)
Merge REGISTRY.json entries
User skills override base skills (same name)

Step 2: Implement PersistentVolumeClaim (1 day)

# Per-user PVC for customizations
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: coditect-user-${USER_ID}
  namespace: coditect-app
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Step 3: Update Skill Discovery (2 days)

// src/config/skill-discovery.ts
async function loadSkills(): Promise<SkillRegistry> {
  const baseSkills = await loadFromPath('/workspace/.coditect/skills/');
  const userSkills = await loadFromPath('/workspace/.coditect-user/skills/');

  return mergeSkills(baseSkills, userSkills);
}

Step 4: Test and Deploy (1 day)

Total Phase 3 Time: 5 days

Phase 4: Skills API Marketplace (Future - 1 month)

Deferred to Sprint 6+ - Focus on Phase 1-3 first.

Alternatives Considered

Alternative 1: Keep `.claude/` Name

Rejected - Does not align with CODITECT brand. Causes confusion with Anthropic's Claude Code product.

Alternative 2: Use Multiple Directories (`.claude/`, `.cursor/`, `.amazonq/` all separate)

Rejected - Duplicates content, increases maintenance burden. Violates DRY principle.

Alternative 3: Single Directory with No Symlinks (`.coditect/` only)

Rejected - Breaks compatibility with CLIs that have hardcoded paths (Gemini, Amazon Q). Too risky without fallback.

Alternative 4: Wait for All CLIs to Support Custom Paths

Rejected - Blocks progress indefinitely. Gemini CLI has had feature request since 2017 with no implementation.

Alternative 5: Build Skills API First (Phase 4 before Phase 1)

Rejected - Over-engineering. Need to validate user adoption before complex marketplace infrastructure.

Validation

Success Criteria (Phase 1):

✅ Container builds successfully with .coditect/ directory
✅ Claude Code recognizes skills via CLAUDE_CONFIG_DIR
✅ theia recognizes skills via THEIA_CONFIG_DIR
✅ Symlink /workspace/.claude → .coditect works
✅ Skills discoverable in CODITECT IDE
✅ Users can execute skills (build-deploy, cleanup, git, etc.)

Success Criteria (Phase 2):

✅ ConfigMap updates skills without container rebuild
✅ Skill changes propagate to all pods within 60 seconds
✅ No downtime during skill updates

Success Criteria (Phase 3):

✅ Users can add custom skills
✅ User skills persist across pod restarts
✅ User skills override base skills correctly
✅ REGISTRY.json merges base + user skills

Testing Plan:

Unit tests for skill discovery logic
Integration tests for each CLI (Claude Code, theia, Cursor)
Load tests with 100+ concurrent users
User acceptance testing with 10 beta users

Rollback Plan:

Phase 1: Revert git commit, rebuild container with .claude/
Phase 2: Delete ConfigMap, fall back to baked-in skills
Phase 3: Unmount PVC, fall back to Phase 2

References

Research:

Related ADRs:

ADR-014: Eclipse theia Foundation
ADR-010: MCP Protocol Integration
ADR-013: Agentic Architecture

Skills Documentation:

Status: Proposed (Awaiting approval) Next Steps:

Review and approve ADR-027
Execute Phase 1 implementation (Sprint 3)
Validate with beta users
Proceed to Phase 2 (Sprint 4)

Decision Date: 2025-10-19 Last Updated: 2025-10-19

Context​

Decision​

Phase 1: Immediate (Sprint 3 - 1 day)​

Phase 2: ConfigMap Updates (Sprint 4 - 4 hours)​

Phase 3: Per-User Overlay (Sprint 5 - 1 week)​

Phase 4: Skills API Marketplace (Future - 1 month)​

Rationale​

Why .coditect/ Instead of .claude/​

Why Phased Approach​

Consequences​

Positive​

Negative​

Risks​

Implementation Plan​

Phase 1: Dual-Path Support (Sprint 3 - 1 day)​

Phase 2: ConfigMap Updates (Sprint 4 - 4 hours)​

Phase 3: Per-User Overlay (Sprint 5 - 1 week)​

Phase 4: Skills API Marketplace (Future - 1 month)​

Alternatives Considered​

Alternative 1: Keep .claude/ Name​

Alternative 2: Use Multiple Directories (.claude/, .cursor/, .amazonq/ all separate)​

Alternative 3: Single Directory with No Symlinks (.coditect/ only)​

Alternative 4: Wait for All CLIs to Support Custom Paths​

Alternative 5: Build Skills API First (Phase 4 before Phase 1)​

Validation​

References​

Context

Decision

Phase 1: Immediate (Sprint 3 - 1 day)

Phase 2: ConfigMap Updates (Sprint 4 - 4 hours)

Phase 3: Per-User Overlay (Sprint 5 - 1 week)

Phase 4: Skills API Marketplace (Future - 1 month)

Rationale

Why `.coditect/` Instead of `.claude/`

Why Phased Approach

Consequences

Positive

Negative

Risks

Implementation Plan

Phase 1: Dual-Path Support (Sprint 3 - 1 day)

Phase 2: ConfigMap Updates (Sprint 4 - 4 hours)

Phase 3: Per-User Overlay (Sprint 5 - 1 week)

Phase 4: Skills API Marketplace (Future - 1 month)

Alternatives Considered

Alternative 1: Keep `.claude/` Name

Alternative 2: Use Multiple Directories (`.claude/`, `.cursor/`, `.amazonq/` all separate)

Alternative 3: Single Directory with No Symlinks (`.coditect/` only)

Alternative 4: Wait for All CLIs to Support Custom Paths

Alternative 5: Build Skills API First (Phase 4 before Phase 1)

Validation

References