Skip to main content

Plan: H.5.8 - Four-Database Setup Integration

Task ID: H.5.8 Status: ✅ COMPLETE Created: 2026-01-23 Completed: 2026-01-23 Author: Claude Opus 4.5

Current State Analysis​

What EXISTS in CODITECT-CORE-INITIAL-SETUP.py​

The setup script (v2.8.0) already creates all 4 databases:

StepDatabaseWhat It DoesStatus
4context.dbCreates schema for sessions, messages, decisions✅ Schema created
12platform.dbCreates schema + indexes all components via component-indexer.py✅ Fully populated
13platform-index.dbCreates schema for component embeddings✅ Schema only
14projects.dbCreates schema for project registration✅ Schema only

What's MISSING​

  1. platform-index.db - Schema created but embeddings NOT generated

    • Need: Call platform-index-db.py --embed-all or similar

  2. projects.db - Schema created but NO projects registered

    • Need: Auto-register the user's current/first project

  3. User Type Differentiation - No distinction between:

    • Internal Contributors: Working ON coditect-core
    • Customers/Partners: Working WITH coditect-core on THEIR projects

User Types​

Type 1: Internal Contributors​

  • Working directory: coditect-rollout-master or coditect-core
  • Need: Register coditect-core as project_type='internal'
  • Projects to index: coditect-core itself (for /cxq --scope-framework)

Type 2: Customers/Partners​

  • Working directory: Their own project (e.g., ~/my-app)
  • Need: Register THEIR project as project_type='customer'
  • Projects to index: Their project (for /cxq --scope-project)

Proposed Changes​

During setup Step 14, detect user type based on:

  1. Is current directory inside coditect-core? → Internal Contributor
  2. Otherwise → Customer/Partner

Then:

  • Internal: Register coditect-core as internal project
  • Customer: Prompt to register current working directory as their project

Option B: Manual Selection​

Add --user-type flag to setup script:

python3 CODITECT-CORE-INITIAL-SETUP.py --user-type internal
python3 CODITECT-CORE-INITIAL-SETUP.py --user-type customer

Option C: Defer Registration​

Don't auto-register any project during setup. Instruct user:

After installation, register your project:
  /cx --register-project ~/my-project

Then index it:
  /cx --index-project ~/my-project

Implementation Tasks​

H.5.8.1: Update initialize_projects_database()​

  • Add project detection logic
  • Auto-register based on user type
  • Call projects-db.py --register

H.5.8.2: Generate platform-index.db Embeddings​

  • Add new step or modify Step 13
  • Call platform-index-db.py --embed-all (if sentence-transformers available)
  • Skip gracefully if not available (embeddings optional)

H.5.8.3: Update Post-Setup Instructions​

  • Show which databases were created
  • Show registered project (if any)
  • Show next steps for indexing/embeddings

H.5.8.4: Add User Type Flag (Optional)​

  • --contributor flag for internal users
  • --customer flag for customers
  • Auto-detect if neither specified

Questions for User​

  1. Should we auto-detect user type or require explicit flag?

  2. Should we auto-generate embeddings during setup?

    • Pro: Ready to use immediately
    • Con: Adds 2-5 minutes to setup, requires sentence-transformers

  3. For customers, should we:

    • A) Auto-register their current working directory
    • B) Prompt them to specify a path
    • C) Show instructions only (defer registration)

  4. Should internal contributors have coditect-core auto-indexed during setup?

    • Pro: Unified search works immediately
    • Con: First-time setup takes longer (~5-10 min for full indexing)

Based on user feedback and CODITECT principles:

User Type Detection​

  1. Auto-detect user type from working directory
    • If CWD contains coditect-core or coditect-rollout-master → Internal Contributor
    • Otherwise → Customer/Partner

Project Registration Strategy​

Problem: User might be in ~/PROJECTS/ with multiple sub-projects:

~/PROJECTS/
├── my-webapp/
├── api-service/
├── mobile-app/
└── coditect-rollout-master/

Solution: Smart project discovery with interactive selection

  1. Scan CWD for git repositories (projects with .git folder)
  2. Display discovered projects with option to register
  3. Let user select which projects to register (multi-select or skip)
  4. Defer indexing to post-setup (user runs /cx --index-project)

Implementation Flow​

Step 14: Initializing projects database (ADR-103)

✓ Created projects.db schema

Scanning for projects in /Users/hal/PROJECTS...
Found 4 potential projects:

  [1] my-webapp        ~/PROJECTS/my-webapp
  [2] api-service      ~/PROJECTS/api-service
  [3] mobile-app       ~/PROJECTS/mobile-app
  [4] coditect-core    ~/PROJECTS/coditect-rollout-master (internal)

Register projects now? (Enter numbers, 'all', or 'skip')
> 1,2

✓ Registered: my-webapp
✓ Registered: api-service

To index these projects later:
  /cx --index-project my-webapp
  /cx --index-project api-service

Or index all registered projects:
  python3 ~/.coditect/scripts/projects-db.py --index-all

Embeddings​

  • Skip during setup (faster installation)
  • User can generate later: /cx --embed-project my-webapp

This approach:

  • Handles multi-project workspaces
  • Gives user control over which projects to register
  • Keeps setup fast (no indexing/embedding during install)
  • Provides clear next steps

Files to Modify​

FileChanges
scripts/CODITECT-CORE-INITIAL-SETUP.pyUpdate Step 14, add detection logic
scripts/projects-db.pyEnsure --init creates schema only
CLAUDE.mdUpdate step documentation
docs/getting-started/USER-QUICK-START.mdUpdate setup instructions

Estimated Effort​

TaskEstimate
H.5.8.1: Project detection & registration4h
H.5.8.2: Optional embedding generation2h
H.5.8.3: Post-setup instructions1h
H.5.8.4: User type flag (optional)2h
Total~9h

Dependencies​

  • H.5.7.1-H.5.7.4: ✅ Complete (Four-Database Architecture)
  • projects-db.py: ✅ Fully functional
  • platform-index-db.py: ✅ Fully functional
  • unified-search.py: ✅ Fully functional

Next Step: Get user input on questions above, then proceed with implementation.