Merge pull request #8 from durandom/chore/ci-and-readme-updates

ci: add GitHub Actions CI and update README

Author: durandom

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - run: uv sync --frozen --extra dev
+
+      - run: uv run ruff check .
+
+      - run: uv run ruff format --check .
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: uv sync --frozen --extra dev
+
+      - run: uv run pytest -v

DESIGN.md .planning/DESIGN.mdDESIGN.md renamed to .planning/DESIGN.md

@@ -1,7 +1,7 @@
 repos:
   # Python linting and formatting
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
+    rev: v0.15.10
     hooks:
       - id: ruff
         args: [--fix]

.pre-commit-config.yaml

@@ -10,37 +10,71 @@
 
 ```
 rhdh-skill/
+├── commands/                    # Slash commands for Claude Code
 ├── skills/
-│   ├── rhdh/              # Orchestrator skill (Python CLI + routing)
-│   │   ├── rhdh/          # Python CLI package (stdlib only)
-│   │   ├── scripts/       # Entry point (./scripts/rhdh)
-│   │   ├── references/    # General tool references (GitHub, JIRA)
-│   │   └── SKILL.md       # Routes to overlay skill
-│   └── overlay/           # Overlay skill (markdown only)
-│       ├── workflows/     # Plugin workflows (onboard, update, fix)
-│       ├── references/    # Overlay-specific references
-│       └── SKILL.md       # Overlay workflow routing
-├── tests/                 # pytest test suite (dev only)
-└── pyproject.toml         # Dev dependencies (pytest)
+│   ├── rhdh/                    # Orchestrator skill (Python CLI + routing)
+│   │   ├── rhdh/                # Python CLI package (stdlib only)
+│   │   ├── scripts/             # Entry point (./scripts/rhdh)
+│   │   ├── references/          # Tool refs (GitHub, JIRA, repos, versions)
+│   │   └── SKILL.md             # Main intake + routing to sub-skills
+│   ├── overlay/                 # Overlay skill (markdown only)
+│   │   ├── workflows/           # Plugin workflows (onboard, update, fix, triage)
+│   │   ├── references/          # Overlay-specific refs (CI, labels, metadata)
+│   │   ├── templates/           # Workspace file templates
+│   │   └── SKILL.md             # Overlay workflow routing
+│   ├── rhdh-local/              # Local testing skill (Python CLI + workflows)
+│   │   ├── rhdh_local/          # Python CLI package (compose, health, sync)
+│   │   ├── scripts/             # Entry point (./scripts/rhdh-local)
+│   │   ├── workflows/           # Local workflows (enable, disable, test, switch)
+│   │   ├── references/          # Customization, env, troubleshooting refs
+│   │   └── SKILL.md             # Local testing intake
+│   ├── create-backend-plugin/   # Bootstrap backend dynamic plugins
+│   ├── create-frontend-plugin/  # Bootstrap frontend dynamic plugins
+│   ├── export-and-package/      # Export & package as OCI/tgz/npm
+│   └── generate-frontend-wiring/ # Configure mount points, routes, tabs
+├── .claude-plugin/              # Plugin manifest + marketplace listing
+├── .planning/                   # Planning docs for future features
+├── tests/                       # pytest test suite (dev only)
+└── pyproject.toml               # Dev dependencies (pytest, ruff)
 ```
 
-## CLI
+## CLIs
 
-The CLI is stdlib-only and runs with any Python 3.9+:
+Two stdlib-only Python CLIs (Python 3.9+), auto-detecting output format (**TTY** → human-readable, **Piped** → JSON):
+
+### `rhdh` — Orchestrator CLI
+
+```bash
+./skills/rhdh/scripts/rhdh                   # Status (orientation)
+./skills/rhdh/scripts/rhdh doctor            # Full environment check
+./skills/rhdh/scripts/rhdh config init       # Create config with auto-detection
+./skills/rhdh/scripts/rhdh config show       # Show resolved paths
+./skills/rhdh/scripts/rhdh config set <k> <v> # Set config value
+./skills/rhdh/scripts/rhdh setup submodule list  # List available repos
+./skills/rhdh/scripts/rhdh setup submodule add --all  # Add all required repos
+./skills/rhdh/scripts/rhdh workspace list    # List plugin workspaces
+./skills/rhdh/scripts/rhdh workspace status <name>
+./skills/rhdh/scripts/rhdh log add "msg" --tag x  # Activity worklog
+./skills/rhdh/scripts/rhdh log show / search
+./skills/rhdh/scripts/rhdh todo add / list / done / note / show
+./skills/rhdh/scripts/rhdh local up / down / status / apply / health  # Delegates to rhdh-local
+```
+
+### `rhdh-local` — Local Testing CLI
 
 ```bash
-./skills/rhdh/scripts/rhdh           # Status check
-./skills/rhdh/scripts/rhdh doctor    # Full environment check
-./skills/rhdh/scripts/rhdh --json    # Force JSON output
+./skills/rhdh-local/scripts/rhdh-local       # Standalone local testing CLI
 ```
 
-Auto-detects output format: **TTY** → human-readable, **Piped** → JSON.
+Both CLIs follow [agentic CLI design patterns](https://github.com/durandom/dotfiles/blob/main/skills/recipes/references/agentic-cli.md) (`/recipes agentic-cli`).
 
 ## Key Patterns
 
 - `OutputFormatter` handles JSON/human rendering — commands build data dicts
-- Workflows live in `skills/overlay/workflows/` — doctor points agents there for setup
+- Workflows live in `skills/overlay/workflows/` and `skills/rhdh-local/workflows/`
 - Config discovery: env vars → project config → user config → auto-detection
+- `commands/` dir provides slash commands that Claude Code auto-discovers
+- `rhdh` CLI delegates `local` subcommands to `rhdh_local.cli` module
 
 ## Versioning
 

CLAUDE.md

@@ -14,7 +14,7 @@ claude plugin install --scope project rhdh
 ### From Published Plugin
 
 ```bash
-claude plugin marketplace add durandom/rhdh-skill
+claude plugin marketplace add redhat-developer/rhdh-skill
 claude plugin install --scope project rhdh
 ```
 
@@ -32,14 +32,19 @@ If `needs_setup: true`, follow the setup instructions to configure required repo
 
 ## Architecture
 
-The skill is split into two focused components:
+The plugin consists of an orchestrator skill that routes to specialized workflow skills:
 
 | Skill | Purpose | Contents |
 |-------|---------|----------|
 | `rhdh` | Orchestrator | Python CLI + routing logic |
-| `overlay` | Workflows | Markdown-only workflow definitions |
+| `overlay` | Overlay workflows | Onboard, update, fix, triage plugins |
+| `create-backend-plugin` | Backend plugins | Bootstrap new backend dynamic plugins |
+| `create-frontend-plugin` | Frontend plugins | Bootstrap new frontend dynamic plugins |
+| `export-and-package` | Packaging | Export plugins as OCI/tgz/npm |
+| `generate-frontend-wiring` | Frontend wiring | Mount points, routes, entity tabs |
+| `rhdh-local` | Local testing | Enable/disable/test plugins locally |
 
-This separation allows the orchestrator to be portable (stdlib-only Python) while keeping workflow documentation easy to maintain.
+The orchestrator is portable (stdlib-only Python) while workflow skills are markdown-only for easy maintenance.
 
 ## The RHDH CLI
 
@@ -78,7 +83,9 @@ This redirects `worklog.jsonl` and `TODO.md` to the specified directory.
 ./skills/rhdh/scripts/rhdh              # Status / orientation
 ./skills/rhdh/scripts/rhdh doctor       # Full environment check
 ./skills/rhdh/scripts/rhdh config init  # Create config with auto-detection
+./skills/rhdh/scripts/rhdh setup        # Environment setup commands
 ./skills/rhdh/scripts/rhdh workspace list  # List plugin workspaces
+./skills/rhdh/scripts/rhdh local        # Local RHDH customization operations
 
 # Activity tracking
 ./skills/rhdh/scripts/rhdh log add "Started onboard" --tag onboard
@@ -89,27 +96,37 @@ This redirects `worklog.jsonl` and `TODO.md` to the specified directory.
 
 | Command | Description |
 |---------|-------------|
-| `/rhdh` | Show status and route to appropriate workflow |
+| `/rhdh` | Show status and route to appropriate workflow (skill) |
 | `/onboard-plugin` | Add a new plugin to Extensions Catalog |
 | `/update-plugin` | Bump plugin to newer upstream version |
 | `/fix-plugin-build` | Debug CI/publish failures |
+| `/plugin-status` | Check plugin health and compatibility status |
 | `/triage-overlay-prs` | Prioritize open PRs (Core Team) |
 | `/analyze-overlay-pr` | Analyze specific PR (Core Team) |
+| `/session-log` | Document session accomplishments to logs |
 
 ## Project Structure
 
 ```
 rhdh-skill/
+├── .claude-plugin/        # Plugin manifest + marketplace listing
+├── commands/              # Slash command definitions
 ├── skills/
 │   ├── rhdh/              # Orchestrator skill
 │   │   ├── rhdh/          # Python CLI package (stdlib only)
 │   │   ├── scripts/rhdh   # Entry point
-│   │   ├── references/    # GitHub, JIRA tool guides
+│   │   ├── references/    # GitHub, JIRA, version refs
 │   │   └── SKILL.md       # Routing logic
-│   └── overlay/           # Workflow skill (markdown only)
-│       ├── workflows/     # onboard, update, fix, triage
-│       ├── references/    # Overlay-specific docs
-│       └── SKILL.md       # Workflow definitions
+│   ├── overlay/           # Overlay workflow skill
+│   │   ├── workflows/     # onboard, update, fix, triage
+│   │   ├── templates/     # Workspace file templates
+│   │   ├── references/    # Overlay-specific docs
+│   │   └── SKILL.md       # Workflow definitions
+│   ├── create-backend-plugin/
+│   ├── create-frontend-plugin/
+│   ├── export-and-package/
+│   ├── generate-frontend-wiring/
+│   └── rhdh-local/        # Local RHDH testing
 ├── tests/                 # pytest test suite
 └── pyproject.toml         # Dev dependencies
 ```

README.md

@@ -16,6 +16,7 @@ include = ["rhdh*"]
 dev = [
     "pytest>=7.0",
     "pyyaml>=6.0",  # Only for SKILL.md structure tests
+    "ruff>=0.4.0",
 ]
 
 [project.scripts]