Development workspace for the Open Sovereign AI Cloud (OSAC) project. This repo provides a meta-workspace that bootstraps all OSAC components for cross-component development and testing, with Claude Code and GSD workflow integration pre-configured.
Choose one of the two development setups:
All dev tools are packaged in a container — no need to install toolchains on your host.
See Distrobox Dev Environment to get started.
Install tools directly on your host.
- git
- gh CLI: Install and authenticate with
gh auth login(required for fork workflow; use--no-forkif you only need read-only access) - Go, Node.js, buf, kubectl, kind, jira CLI (see Setup for details)
# Clone the workspace
git clone https://github.com/osac-project/osac-workspace.git
cd osac-workspace
# Bootstrap all component repos with fork setup (requires gh CLI)
./bootstrap.sh
# Or clone read-only without forking
./bootstrap.sh --no-forkThe bootstrap script clones all OSAC repos into the workspace. Each repo is an independent Git repository on its main branch with remotes configured as:
origin= osac-project (upstream source, PR target)fork= your GitHub fork (push target for feature branches)
Use --no-fork if you only need read-only access or are running in CI.
| Repository | Description |
|---|---|
| fulfillment-service | gRPC/REST API server with PostgreSQL backend — manages VirtualNetworks, Subnets, SecurityGroups, ComputeInstances |
| osac-operator | Kubernetes operator for deploying OpenShift clusters via Hosted Control Planes |
| osac-aap | Ansible Automation Platform roles and playbooks for VM and network provisioning |
| osac-installer | Installation manifests, prerequisites, and demo scripts |
| osac-test-infra | Integration testing infrastructure |
| osac-ui | OSAC UI web console for managing cloud resources |
| enhancement-proposals | Design documents and enhancement proposals |
| docs1 | Architecture documentation, diagrams, and design guides |
This workspace provides a pre-configured AI-assisted development environment:
| File | Purpose |
|---|---|
bootstrap.sh |
Clones or updates all component repos to latest main — re-run anytime to sync |
CLAUDE.md |
Project instructions Claude Code reads automatically — build commands, architecture patterns, conventions |
.claude/settings.json |
Pre-approved shell commands (git, ls, cat, etc.) so Claude doesn't prompt for routine operations |
.planning/config.json |
GSD workflow configuration (parallelization, verification, auto-advance) |
skills/ |
AI skills for Claude Code — EP generation, Jira management, bug fix workflows, demo recording |
.gitignore |
Ignores cloned repos, .planning/, .claude/, credentials, editor files, and build artifacts |
A containerized development environment is provided via distrobox, packaging all required tools (Go, Node.js, buf, kubectl, kind, gh, jira, Claude Code) in a Fedora 42-based container. This gives you a reproducible environment without installing toolchains on your host.
# Build the image and enter the distrobox
make enter
# Or run Claude Code directly inside the distrobox
make claude
# Pass flags to Claude Code
make claude ARGS="--resume"
# Check status of image and distrobox
make status
# Rebuild from scratch
make rebuildThe distrobox shares your home directory by default (override with HOME_DIR). All host files, SSH keys, and credentials are available inside the container.
| Target | Description |
|---|---|
make image |
Build the container image |
make enter |
Enter the distrobox (creates on first run) |
make claude |
Run Claude Code inside the distrobox |
make stop |
Stop the running container |
make rm |
Remove the distrobox |
make rebuild |
Rebuild image from scratch and enter |
make status |
Show image and distrobox status |
After running ./bootstrap.sh to clone all repos:
- kubeconfig: Place your cluster kubeconfig at
./kubeconfig(gitignored) - Tools:
buf,grpcurl,kubectl,jq,rg - Jira CLI:
go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest(orbrew install ankitpokhrel/jira-cli/jira-cli) - GSD workflow:
npx get-shit-done-cc@latest(run from workspace root)- GSD hooks in
.claude/settings.jsonare already configured and will no-op if GSD is not installed
- GSD hooks in
To update all repos to latest main at any time, simply re-run:
./bootstrap.sh# Build and test fulfillment-service
cd fulfillment-service
go build
ginkgo run -r
# Test API against a running cluster
export KUBECONFIG=./kubeconfig
export NAMESPACE=<your-namespace>
ROUTE=$(kubectl get route -n $NAMESPACE fulfillment-api -o jsonpath='{.spec.host}')
TOKEN=$(kubectl create token -n $NAMESPACE admin)
# List resources via REST
curl -sk -H "Authorization: Bearer $TOKEN" "https://$ROUTE/api/fulfillment/v1/virtual_networks" | jq
curl -sk -H "Authorization: Bearer $TOKEN" "https://$ROUTE/api/fulfillment/v1/subnets" | jq
curl -sk -H "Authorization: Bearer $TOKEN" "https://$ROUTE/api/fulfillment/v1/compute_instances" | jq
# List resources via gRPC
grpcurl -insecure -H "Authorization: Bearer $TOKEN" $ROUTE:443 osac.public.v1.VirtualNetworks/ListOnce you have Claude Code running in this workspace, use GSD commands to plan and execute work:
/gsd:new-project # Initialize project with requirements gathering
/gsd:plan-phase # Plan the next phase of work
/gsd:execute-phase # Execute a planned phase
/gsd:progress # Check current project status
/gsd:next # Advance to the next logical step
| Task Type | GSD Command | When to Use |
|---|---|---|
| Epic / new feature | /gsd:new-project |
Starting a multi-phase initiative |
| Jira ticket | /gsd:quick |
Single-ticket work with commit tracking |
| Tiny fix | /gsd:fast |
One-file fixes, no planning overhead |
| Check status | /gsd:progress |
See where you are in the project |
| Next step | /gsd:next |
Auto-advance to the next logical action |
GSD manages all state under .planning/ — milestones, phases, plans, and verification are created as you work.
This workspace includes two approaches for creating OSAC Enhancement Proposals with Claude Code.
Follows the same pattern as flightctl: create a PRD first, merge it, then create the design document (EP). The design template is a lightly modified version of the standard EP format — requirements-heavy sections (Summary, Motivation, User Stories) are shortened with PRD references, and four new subsections are added (Security Considerations, Failure Handling, RBAC/Tenancy, Observability).
Stage 1 — PRD:
/prd:ingest OSAC-XXXXX # Fetch requirements from Jira
/prd:clarify # Iterative Q&A to resolve ambiguities
/prd:draft # Generate PRD
/prd:publish # Submit PR to enhancement-proposals repo
/prd:respond # Address reviewer comments
Stage 2 — Design (EP):
/design:ingest OSAC-XXXXX # Read PRD, explore codebase, capture context
/design:draft # Generate EP using OSAC design template
/design:publish # Submit PR to enhancement-proposals repo
/design:respond # Address reviewer comments
/design:decompose # Break into Jira-ready epics and stories
/design:sync # Sync epics/stories to Jira
Both stages publish to the enhancement-proposals repo under enhancements/<feature-slug>/ — the PRD as prd.md and the design document as README.md.
For simpler proposals that don't need a separate PRD:
/ep.create
Provide rough requirements, meeting notes, or a Jira ticket (e.g., OSAC-XXXXX) and the skill will explore the codebase, ask clarifying questions, generate a full EP, and submit a PR.
Convert an approved EP into Jira work items:
/ep.to-jira
This creates a Jira epic with ordered sub-tasks (proto, backend, controller, tests, docs) and a complexity assessment.
Prerequisites: gh (authenticated), jira CLI, rg
NetworkClass (platform-defined)
└── VirtualNetwork (tenant L2 network with CIDR)
├── Subnet (CIDR range within VirtualNetwork)
└── SecurityGroup (firewall rules)
└── ComputeInstance (KubeVirt VM, attached to Subnet + SecurityGroups)
See CLAUDE.md for detailed development instructions and conventions.
Footnotes
-
Cloned into a subdirectory as
osac-docs↩