Workspace Codemap Structure

Source: workspace-codemap-structure.md (ingested 2026-03-28)

erfect! Here's your Workspace Codemap:

📊 Workspace Structure

C:\Users\mesha\Desktop\GitHub/ ├── github.com/ │ ├── alawein/ (30 repos) │ ├── morphism-systems/ (1 repo) │ └── blackmalejournal/ (1 repo) ├── workspace/ (4 shared projects) ├── docs/ (documentation) ├── config/ (configuration) └── Justfile (task runner)

📦 Project Breakdown by Type

Node.js Projects (11) — Web Apps & Design System

• _devkit — Design system monorepo (@alawein/* packages)
• meshal-web — Personal portfolio (cyberpunk quantum theme)
• attributa, bolts, gymboy, llmworks, qmlab, repz, scribd, simcore — Consumer apps using @alawein/ui
• atelier-rounaq — E-commerce (contact@atelier-rounaq.com)
• ingesta-toolkit — Tool integration framework

Python Projects (13) — Data/ML/Science

• _ops — Operations framework
• _pkos — Personal knowledge OS (identity canon, resume)
• edfp — Event Discovery Framework (Phase 7 complete: 73 tests)
• meatheadphysicist, qaplibria, maglogic, qmatsim, scicomp — ML/science tools
• adil, loopholelab, neper, qubeml, spincirc — Research/algorithmic

Governance/Architecture (1) — Meta

• morphism — Governance-as-code for agent systems (hybrid tools strategy)

Miscellaneous (5)

• alawein, helios, chshlab, blackmalejournal — Archived/special repos

Workspace Shared (4)

• notion-email-sync, scientific-pub-kit — Shared utilities

---

🎯 Key Deployments (14 Live)

All deployed to Vercel under alawein Pro team:

┌─────────────────────────┬───────────────────────────┬───────────┐ │ Domain │ Repo │ Type │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ meshal.ai │ meshal-web │ Portfolio │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ attributa.dev │ attributa │ Platform │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ bolts.fit │ bolts │ Coaching │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ gymboy.coach │ gymboy │ Coaching │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ repzcoach.com │ repz │ Coaching │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ simcore.dev │ simcore │ SaaS │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ llmworks.dev │ llmworks │ Tools │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ qmlab.online │ qmlab │ Research │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ atelier-rounaq.com │ atelier-rounaq │ E-com │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ morphism.systems │ morphism │ Meta │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ scribd.fit │ scribd │ Coaching │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ aiclarity.com │ event-discovery-framework │ Discovery │ ├─────────────────────────┼───────────────────────────┼───────────┤ │ + 2 more internal tools │ │ │ └─────────────────────────┴───────────────────────────┴───────────┘

---

🛠️ Tech Patterns

• Frontend: React/Next.js + Tailwind, design system via @alawein/* packages
• Backend: Node.js, Python (ML/science)
• Data: SQLite, Supabase (where applicable)
• CI/CD: GitHub Actions (Python: ruff + pytest, Node: lint + build + test)
• Infrastructure: Vercel (all Node apps), custom for Python

---

Want deeper analysis? I can:

• 📋 Generate repo-by-repo dependency map
• 🔍 Analyze shared utils usage across projects
• 📊 Document design system package relationships
• 🏗️ Map integration points (Morphism hybrid tools, Notion, Firebase, etc.)

What would be most useful for your next task?

⎿  UserPromptSubmit hook error

● Let me map out the final consolidated structure and show the dependency graph:

Read 1 file (ctrl+o to expand)

● Now the dependency flow and theme extraction strategy:

Read 1 file (ctrl+o to expand)

● Visual: How It All Connects

┌─────────────────────────────────────────────────────────────────────────────┐ │ ALAWEIN WORKSPACE ECOSYSTEM │ └─────────────────────────────────────────────────────────────────────────────┘

                  SOURCE OF TRUTH LAYER
                  ═══════════════════════════════════

                  _pkos/
                  ├─ WORKSPACE.yaml (repo manifest)
                  └─ MASTER_REFERENCE.md (standards)
                         ↓ informs ↓


         DESIGN & INFRASTRUCTURE LAYER
         ═════════════════════════════════════════════════════════════════

         _design-tokens/                    _devkit/ (Turborepo)
         ├─ tokens/ (JSON)                  ├─ @alawein/ui
         ├─ build-tokens.ts    ←─ synced ─→ ├─ @alawein/theme-*
         └─ dist/alawein.css                ├─ @alawein/icons
            (static CSS)                    └─ Changesets (versioning)
                  ↓                               ↓
         [Can be published                [Published to npm]
          as standalone pkg]               [@alawein scope]


              OPERATIONS & META LAYER
              ═════════════════════════════════════════════════════════════

              _ops/
              ├─ deployment/deploy-all.sh (orchestrates releases)
              ├─ integrations/notion-email-sync
              └─ clis/ (tooling for monorepo)


                   CONSUMPTION LAYER
                   ═════════════════════════════════════════════════════════

      meshal-web           attributa           bolts           simcore
      ├─ @alawein/ui       ├─ @alawein/ui      ├─ @alawein/ui   ├─ @alawein/ui
      ├─ @alawein/         ├─ @alawein/        ├─ @alawein/     ├─ @alawein/
      │  theme-cyberpunk   │  theme-cyberpunk  │  theme-luxury   │  theme-glass
      └─ @alawein/         └─ [+ custom CSS]   ├─ [extensions]   └─ [custom]
         theme-quantum                        └─ Tailwind


           MULTI-ORG STRATEGY (Future)
           ═════════════════════════════════════════════════════════════

   github.com/morphism-systems/
   └─ design-system/
      ├─ @morphism/ui
      ├─ @morphism/theme-strategic
      ├─ depends on: alawein-design-tokens ← SHARED
      └─ [independent, org-branded]

   github.com/blackmalejournal/
   └─ design-system/
      ├─ @blackmalejournal/ui
      ├─ @blackmalejournal/theme-custom
      └─ depends on: alawein-design-tokens ← SHARED

---

Migration Checklist

Step 1: Consolidate workspace/ → _ops/ and _pkos/

mv workspace/notion-email-sync/ → github.com/alawein/_ops/integrations/ mv workspace/scientific-pub-kit/ → github.com/alawein/_pkos/academic-publishing/ rm workspace/

Step 2: Rename for clarity

mv github.com/alawein/_workspace/ → github.com/alawein/_design-tokens/

Step 3: Update references in _devkit

(package.json, build scripts to reference _design-tokens paths)

Step 4: Publish _design-tokens as standalone

In _design-tokens/package.json:

"name": "alawein-design-tokens"

npm publish

Step 5: Update consumer apps (if needed)

Some apps may want to import tokens independently:

npm install alawein-design-tokens

import "alawein-design-tokens/dist/alawein.css"

Step 6: Document in WORKSPACE.yaml (from _pkos)

Add entries for each repo with dependencies clearly marked

Ready to proceed with consolidation, or want to refine the multi-org strategy first?

✻ Sautéed for 59s

/superpowers:writing-plans ● Investigation & Consolidation Prompt for Claude Opus

TASK: Finalize Alawein Workspace Architecture (Hub-and-Spoke Canonical)

Executive Summary

Transform github.com/alawein/ into a canonical control center for design systems, standards, and governance. All repos in alawein and spoke orgs (morphism-systems, blackmalejournal) consume @alawein/* npm packages and reference canonical standards from _pkos/. This is a structural consolidation, not a feature addition.

Status: PLANNING PHASE Owner: Claude Opus (investigation & execution) Timeline: Execute in phases, checkpoints at each phase

---

Current State (2026-03-19)

Directory Structure (Before Consolidation)

C:\Users\mesha\Desktop\GitHub/ ├── github.com/alawein/ │ ├── _devkit/ [Turborepo monorepo with @alawein/* packages] │ ├── _workspace/ [PROBLEM: named confusingly, is design-tokens] │ ├── _ops/ [Operational scripts, missing integrations] │ ├── _pkos/ [Standards repo, CANONICAL but underutilized] │ ├── ingesta-toolkit/ [MCP + CLI framework] │ ├── 11 consumer apps [meshal-web, simcore, attributa, bolts, etc.] │ └── 6 research repos [qaplibria, meatheadphysicist, etc.] │ ├── workspace/ [PROBLEM: redundant, should move into _ops/_pkos] │ ├── notion-email-sync/ [Gmail↔Notion sync, 4 files, Google Apps Script] │ └── scientific-pub-kit/ [Academic publishing templates, 7 dirs] │ └── Justfile [Top-level task runner]

Key Facts

• _devkit: @alawein/ui, @alawein/theme-* (7 families), @alawein/eslint-config, etc. @ v0.1.0
• _workspace: actually named "alawein-design-system", generates dist/alawein.css
• _workspace is NOT a git repo (missing .git directory)
• _pkos: Has WORKSPACE.yaml (repo manifest), should be source of truth
• _ops: Has shell scripts but missing organized structure for integrations
• All consumer apps import @alawein/* packages
• CI/CD: GitHub Actions workflows in most repos

Truth Hierarchy (Current — Broken)

1. _pkos/CLAUDE.md exists but not referenced by all repos
2. _workspace/ and _devkit/ both claim to be "design system" (naming conflict)
3. workspace/ at root duplicates some _ops responsibilities
4. Consumer apps have local CLAUDE.md but don't reference canonical

---

INVESTIGATION PHASE: Discover Exact Current State

Phase 1.1: Map Current Dependencies

Objective: Understand what each _workspace/ and workspace/ does exactly

Tasks:

1. Read _workspace/package.json completely
   • Document its exports, dependencies, build scripts
   • Confirm: is it truly a design-tokens system?
2. Read workspace/notion-email-sync/Code.gs (Google Apps Script)
   • Document: what does it sync, how often, what auth?
3. Read workspace/scientific-pub-kit/README.md
   • Document: is this internal or publishable?
4. List all files in _workspace/ recursively
   • Count tokens/, themes/, scripts/
   • Check if tokens/ are JSON or other format
5. Verify: _workspace is NOT a git repo
   • Check: should it be? (vs. should it move into _devkit/?)

Outputs:

• findings/workspace-analysis.md with all details
• findings/workspace-vs-devkit-comparison.md side-by-side

---

Phase 1.2: Map Consumer App Dependencies

Objective: Understand how each consumer app uses @alawein/* packages

Tasks:

1. For each of: meshal-web, simcore, attributa, bolts, qmlab, repz, scribd, rounaq-atelier, gymboy, llmworks

   • Read package.json
   • Document: which @alawein/* packages imported
   • Document: which theme imported
   • Check: does CLAUDE.md exist? Does it reference canonical?
   • Check: does LESSONS.md exist?

2. For morphism-systems/morphism and bolts (under morphism-systems but deployed under alawein)

   • Confirm: which npm scope they import from
   • Confirm: are they using @alawein/ui or @morphism/ui?

Outputs:

• findings/consumer-app-inventory.md with dependency matrix
• findings/theme-usage-map.md showing which apps use which themes

---

Phase 1.3: Audit Standards Documents

Objective: Understand current state of CLAUDE.md, LESSONS.md, AGENTS.md

Tasks:

1. Read _pkos/CLAUDE.md

   • Document: global rules, standards, preferences
   • Check: is it comprehensive?
   • Note: any gaps or outdated sections

2. Read _pkos/LESSONS.md

   • Document: what patterns are documented
   • Check: are they referenced by consumer apps?

3. Read _pkos/AGENTS.md

   • Document: MCP integrations, agent setup
   • Check: what's the scope?

4. Read _pkos/MASTER_REFERENCE.md

   • Document: code conventions, naming, standards

5. Check each consumer app's local CLAUDE.md (sample: meshal-web, attributa)

   • Document: do they reference canonical?
   • Document: what local overrides do they have?

6. Check _ops/ (Operations)

   • List all shell scripts, Python scripts
   • Document purpose of each
   • Check: is structure organized?

Outputs:

• findings/standards-audit.md documenting current state
• findings/claude-md-variance.md showing what differs across repos

---

Phase 1.4: Validate Git & Publishing Status

Objective: Understand version control and npm publishing state

Tasks:

1. Confirm _devkit is a git repo with remotes

   • Check: package.json version (should be 0.1.0)
   • Check: .changesets/ structure
   • Check: npm scope configured

2. Confirm _design-tokens (currently _workspace) git status

   • Is it a git repo? (expected: NO)
   • Should it be moved INTO _devkit or become separate git repo?

3. Check _ops git status

   • Is it a git repo? (expected: NO, it's scripts)
   • Should it be? (likely: NO)

4. Check _pkos git status

   • Confirm: is git repo with WORKSPACE.yaml as SSOT

5. Verify: all consumer apps are git repos

   • Check: do they have .vercel/project.json?
   • Check: are they deployed to Vercel?

Outputs:

• findings/git-status-report.md documenting all repos
• findings/npm-publishing-readiness.md for _devkit

---

Phase 1.5: Map Actual File Locations & Counts

Objective: Understand what we're moving where

Tasks:

# Count files in workspace/
find workspace/ -type f | wc -l
find workspace/ -type d | wc -l

# Count files in _workspace/
find github.com/alawein/_workspace/ -type f | wc -l
find github.com/alawein/_workspace/ -type d | wc -l

# Check: are notion-email-sync and scientific-pub-kit git repos?
ls -la workspace/notion-email-sync/.git 2>&1
ls -la workspace/scientific-pub-kit/.git 2>&1

Outputs:
- findings/file-inventory.md with counts
- Verification: what needs to be moved vs. copied vs. symlinked

---
CONSOLIDATION PHASE: Execute the Migration

Phase 2.1: Plan Git Migrations

Objective: Decide how to move files without losing history

Tasks:
1. For _workspace/ rename to _design-tokens/:
  - Decision: should this be done via git mv or separate directory?
  - If NOT a git repo, can just rename
2. For workspace/notion-email-sync/ → _ops/integrations/notion-email-sync/:
  - Is it a git repo? If yes, preserve git history
  - Decision: git subtree? Copy? Symlink?
3. For workspace/scientific-pub-kit/ → _pkos/academic-publishing/:
  - Is it a git repo? If yes, preserve history
  - Decision: git subtree? Copy? Symlink?

Outputs:
- plans/migration-strategy.md with step-by-step commands
- plans/git-history-preservation.md if any repos involved

---
Phase 2.2: Execute Consolidation (Dry Run First)

Objective: Perform the moves with safety checks

Prerequisite: All findings from Phase 1 completed

Tasks:
1. Create branches for each move:
git checkout -b consolidate/workspace-to-ops
git checkout -b consolidate/rename-design-tokens
git checkout -b consolidate/update-references
2. Move notion-email-sync:
mkdir -p github.com/alawein/_ops/integrations/
(copy or git subtree add) workspace/notion-email-sync/ → destination
Update any path references in _ops/package.json or scripts
3. Move scientific-pub-kit:
mkdir -p github.com/alawein/_pkos/academic-publishing/
(copy or git subtree add) workspace/scientific-pub-kit/ → destination
Update _pkos documentation to reference new path
4. Rename _workspace → _design-tokens:
(if not git repo, simple mv)
Update any imports in _devkit/ that reference _workspace
5. Test: verify no broken imports
  - In _devkit/, check if any files import from _workspace
  - In consumer apps, verify @alawein/* imports still work
  - Check Justfile paths (if any reference workspace/)

Outputs:
- Dry run report showing all changes
- Checklist of what can be auto-tested vs. manual verification

---
Phase 2.3: Update Standards (CLAUDE.md, LESSONS.md, etc.)

Objective: Ensure canonical sources are complete and current

Tasks:
1. In _pkos/CLAUDE.md:
  - Add section: "Hub-and-Spoke Model"
  - Document: alawein is canonical source
  - Document: all repos should reference this
  - Add instructions for spoke orgs
2. In _pkos/LESSONS.md:
  - Add section: "Workspace Consolidation (2026-03-19)"
  - Document: why we consolidated
  - Document: patterns that emerged
3. In _pkos/MASTER_REFERENCE.md:
  - Add: directory structure diagram
  - Add: data flow diagrams
  - Add: multi-org strategy
4. In _pkos/WORKSPACE.yaml:
  - Verify: all repos listed
  - Update: paths after consolidation
  - Verify: dependency graph is accurate
5. Review _ops/README.md (create if missing):
  - Document: what _ops does
  - Document: integrations structure
  - Document: deployment orchestration

Outputs:
- Updated .md files in _pkos/
- Verification: all internal links still valid

---
Phase 2.4: Validate Consumer Apps Reference Canonical

Objective: Ensure consumer apps follow hub-and-spoke model

Tasks:
1. For each consumer app (meshal-web, simcore, attributa, etc.):
  - Check: CLAUDE.md exists
  - If exists, add/verify header: "Extends github.com/alawein/_pkos/CLAUDE.md"
  - If missing, create template CLAUDE.md with canonical reference
2. For spoke orgs (morphism-systems, blackmalejournal):
  - Verify: they reference alawein canonical
  - If not, create documentation showing expected structure
3. Test: run lint checks on all consumer apps
  - Verify: eslint-config is working
  - Verify: prettier is consistent
  - Verify: TypeScript compiles

Outputs:
- findings/consumer-app-standards-compliance.md
- List of any apps needing manual updates

---
VERIFICATION PHASE: Confirm Structure is Sound

Phase 3.1: Dependency Audit

Objective: Verify no broken imports, all versions aligned

Tasks:
1. In _devkit/:
npm install
npm run build
npm run validate (if available)
npm run test (if available)
  - Verify: no errors
  - Verify: all packages build
2. In each consumer app:
npm install
npm run build (or next build)
  - Verify: builds succeed
  - Verify: @alawein/* imports work
  - Verify: no version conflicts
3. Check Justfile
  - Verify: all paths still valid
  - Verify: setup targets still work

Outputs:
- findings/build-validation-report.md
- List of any broken dependencies

---
Phase 3.2: Git History Validation

Objective: Ensure no commits were lost in consolidation

Tasks:
1. If notion-email-sync was git repo:
  - Verify: all commits preserved in new location
  - Verify: git log shows full history
2. If scientific-pub-kit was git repo:
  - Verify: all commits preserved in new location
3. Verify: _workspace → _design-tokens renaming preserved git history
  - Check: git log shows proper history

Outputs:
- findings/git-history-validation.md
- Confirmation: no commits lost

---
Phase 3.3: Cross-Org Verification

Objective: Ensure spoke orgs still work correctly

Tasks:
1. For morphism-systems/morphism:
  - Verify: @alawein/ui import still works
  - Verify: npm install succeeds
  - Verify: build succeeds
  - Verify: CLAUDE.md references alawein canonical
2. For blackmalejournal (if applicable):
  - Same verification steps
3. For bolts (shared between alawein and morphism-systems):
  - Verify: works under both contexts
  - Verify: dependencies resolve correctly

Outputs:
- findings/spoke-org-validation.md
- Confirmation: no breaking changes for spokes

---
Phase 3.4: Standards Compliance Audit

Objective: Verify all repos follow canonical standards

Tasks:
1. Check: all repos have CLAUDE.md
  - Count: how many have it?
  - Count: how many reference canonical?
  - List: repos missing CLAUDE.md
2. Check: all repos have .github/workflows/ci.yml
  - Verify: they all follow same pattern
  - Verify: linting rules match eslint-config
3. Check: version consistency
  - Verify: all @alawein/* imports specify ^0.1.0 (or latest)
  - Verify: no version conflicts
4. Check: no orphaned files
  - Verify: workspace/ directory is empty (or deleted)
  - Verify: no references to old paths

Outputs:
- findings/standards-compliance-report.md
- Scorecard: % of repos compliant

---
DOCUMENTATION PHASE: Record the Architecture

Phase 4.1: Create Architecture Documentation

Objective: Document final structure for future reference

Tasks:
1. Create: docs/workspace-architecture.md
  - Hub-and-spoke model explanation
  - Tier structure (design system, standards, operations)
  - Data flow diagrams
  - Multi-org strategy
2. Create: docs/consolidation-changelog.md
  - What changed and why
  - Migration steps taken
  - Lessons learned
3. Create: docs/integration-guide.md
  - How to integrate new app into alawein
  - How to create spoke org
  - Standards checklist
4. Update: README.md files
  - alawein/ main README explaining hub role
  - _devkit/ README explaining npm packages
  - _pkos/ README explaining canonical standards
  - _ops/ README explaining operations

Outputs:
- Comprehensive documentation in /docs/
- Accessible to future developers

---
Phase 4.2: Create Onboarding & Maintenance Procedures

Objective: Document ongoing operations

Tasks:
1. Create: docs/maintenance-schedule.md
  - Weekly tasks (pattern review)
  - Bi-weekly tasks (release cycle)
  - Monthly tasks (standards audit)
2. Create: docs/spoke-org-template.md
  - Template for new orgs
  - Checklist for spoke setup
  - Example CLAUDE.md
3. Create: docs/troubleshooting.md
  - Common issues after consolidation
  - How to debug version conflicts
  - How to sync standards

Outputs:
- Operational runbooks for maintainers

---
SUCCESS CRITERIA

✅ Phase 1 (Investigation): All findings documented, no blockers identified
✅ Phase 2 (Consolidation): All files moved, all references updated
✅ Phase 3 (Verification): All builds pass, all tests pass, no broken imports
✅ Phase 4 (Documentation): Comprehensive docs in place

Final Checklist:
- workspace/ directory deleted or empty
- _workspace/ renamed to _design-tokens/
- notion-email-sync/ in _ops/integrations/
- scientific-pub-kit/ in _pkos/academic-publishing/
- All consumer apps build successfully
- All consumer apps reference canonical standards
- _devkit/ packages publish to npm
- Spoke orgs (morphism-systems, blackmalejournal) verified working
- Documentation complete and current
- Justfile updated with new paths
- No broken imports or references

---
ROLLBACK PLAN (If Needed)

If anything breaks:
1. Revert git branches (all changes uncommitted during dry run)
2. Restore from git history
3. Document what went wrong in findings/
4. Adjust plan and retry

Risk Level: LOW (mostly file moves, no code changes)
Reversibility: HIGH (git history preserved)

---
Next Steps

1. Start Phase 1 (Investigation)
2. Document all findings in findings/ directory
3. After all Phase 1 tasks complete, request approval to proceed to Phase 2
4. Execute phases sequentially with checkpoint validations
5. Final deliverable: consolidated workspace + comprehensive documentation

Timeline: ~4-6 hours for investigation, ~2-3 hours for consolidation, ~1-2 hours for verification

---
Notes for Claude Opus

- Be thorough in investigation — rushing Phase 1 leads to consolidation errors
- Document everything, assume nothing
- Test builds after each major move
- Preserve git history where possible
- Update this plan as you discover new information
- Checkpoint after each phase: verify all tasks completed before proceeding
- If you find issues, update findings/ and flag for human review before proceeding

Good luck! 🚀