rob
/
development-hub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
development-hub/CLAUDE.md

6.9 KiB
Raw Blame History

CLAUDE.md

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

Project Overview

Development Hub is the central orchestration project for Rob's multi-project development ecosystem. It provides:

  1. GUI Application - PyQt6-based workspace with project list, splittable terminal panes, and session persistence
  2. CLI Tools - Scripts to create and manage projects following consistent patterns

GUI Application

Running the App

cd ~/PycharmProjects/development-hub
source .venv/bin/activate
python -m development_hub

Architecture

src/development_hub/
├── __init__.py
├── __main__.py           # Entry point
├── app.py                # QApplication subclass
├── main_window.py        # Main window with menus
├── project_list.py       # Left panel - project discovery & context menu
├── workspace.py          # Right panel - splittable panes with tabs
├── terminal_widget.py    # PTY terminal with pyte emulation
├── project_discovery.py  # Parse projects from build-public-docs.sh
├── dialogs.py            # New Project (with Ramble), Settings dialogs
├── settings.py           # JSON persistence for settings & session
└── styles.py             # Dark theme stylesheet

Key Classes

Class File Purpose
MainWindow main_window.py QMainWindow with menus, splitter layout
ProjectListWidget project_list.py Project list with context menu actions
WorkspaceManager workspace.py Manages splittable pane layout
PaneWidget workspace.py Tab container within a pane
TerminalWidget terminal_widget.py PTY-based terminal with pyte screen emulation

Features

  • Project List: Discovers projects from build-public-docs.sh config
  • Context Menu: Open terminal, editor, Gitea, docs, deploy
  • Splittable Panes: Horizontal/vertical splits, each pane has own tab bar
  • Terminal: Full PTY with pyte for TUI support (vim, htop work)
  • Drag & Drop: Drop files/folders into terminal to inject paths
  • Session Persistence: Remembers pane layout and open terminals
  • New Project Dialog: Integrates with Ramble for voice input

Keyboard Shortcuts

Global Shortcuts

Shortcut Action
Ctrl+Shift+T New terminal tab
Ctrl+Shift+W Close current tab
Ctrl+Shift+D Split pane horizontal
Ctrl+Shift+E Split pane vertical
Ctrl+Shift+P Close active pane
Ctrl+Alt+Left/Right Switch panes
Ctrl+B Toggle project panel
Ctrl+N New project dialog
Ctrl+D New discussion
Ctrl+Z Undo (in dashboard)
Ctrl+Shift+Z Redo (in dashboard)
F5 Refresh project list

Dashboard Shortcuts (when dashboard tab is active)

Shortcut Action
/ Focus add todo input
Ctrl+1 Switch to priority view
Ctrl+2 Switch to milestone view
Ctrl+3 Switch to show all view
Ctrl+] Expand all sections
Ctrl+[ Collapse all sections

Dashboard Data Sync

The dashboard automatically syncs data between documentation files:

  • Deliverables → TODOs: When loading a project dashboard, deliverables from milestones.md tables are synced to todos.md. If a deliverable doesn't exist as a todo (matched by text + milestone ID), it's added with the appropriate @M# tag and priority.
  • TODOs → Milestone Progress: The milestone progress bar is calculated from linked todos (items tagged with @M#), not from the deliverables table.

This means you can define major work items in milestone deliverable tables, and they'll automatically appear in your todo list for tracking.

CLI Scripts

bin/new-project

Creates a new project in the ecosystem with all the standard setup:

# Full usage
new-project myproject --title "My Project" --tagline "Short description"

# Interactive mode (prompts for title/tagline)
new-project myproject

# Options
--title "..."     Display title for the project
--tagline "..."   Short description
--dry-run         Show what would happen without making changes
--skip-gitea      Skip Gitea repository creation (for offline use)

What it does:

  1. Creates Gitea repository via API
  2. Creates local project directory with git
  3. Generates project files from templates (CLAUDE.md, README.md, .gitignore, pyproject.toml)
  4. Sets up documentation symlink to project-docs
  5. Updates build-public-docs.sh to include the new project
  6. Creates initial commit and pushes

Project Structure

development-hub/
├── src/development_hub/      # GUI application (see Architecture above)
├── bin/
│   └── new-project           # CLI scaffolding script
├── templates/
│   ├── gitignore.template    # Python .gitignore with docs exclusion
│   ├── CLAUDE.md.template    # AI context file
│   ├── README.md.template    # Basic README
│   ├── pyproject.toml.template
│   ├── overview.md.template  # Docs overview
│   └── updating-documentation.md.template
├── docs/                     # Symlink to project-docs
├── pyproject.toml            # Python packaging with PyQt6 dep
├── CLAUDE.md                 # This file
├── README.md
└── .gitignore

Template Placeholders

Templates use these placeholders (replaced by sed):

  • {{PROJECT_NAME}} - lowercase project name (e.g., "my-tool")
  • {{PROJECT_TITLE}} - display title (e.g., "My Tool")
  • {{PROJECT_TAGLINE}} - short description
  • {{YEAR}} - current year
  • {{DATE}} - creation date
  • {{GITEA_URL}} - https://gitea.brrd.tech
  • {{GITEA_OWNER}} - rob

Configuration

Gitea API Token

The script needs a Gitea API token to create repositories:

  1. Environment variable: GITEA_TOKEN
  2. Config file: ~/.config/development-hub/gitea-token

To create a token:

  1. Go to https://gitea.brrd.tech/user/settings/applications
  2. Generate a new token with 'repo' scope
  3. The script will prompt and save it automatically

Documentation

Documentation lives in the centralized docs system:

  • Source: ~/PycharmProjects/project-docs/docs/projects/development-hub/
  • Public URL: https://pages.brrd.tech/rob/development-hub/

When updating documentation:

  1. Edit files in docs/ (the symlink)
  2. Use public: true frontmatter for public-facing docs
  3. Run ~/PycharmProjects/project-docs/scripts/build-public-docs.sh development-hub --deploy to publish

Related Projects

This project manages and creates projects in the ecosystem:

  • CmdForge - AI-powered CLI tool builder
  • CascadingDev - Cascading Development Framework
  • Orchestrated Discussions - AI Discussion Framework
  • Artifact Editor - Code Artifact Editor
  • Ramble - Voice Note Transcription

All projects follow the same documentation pattern and can be created using new-project.