OctoMesh Development Tools — Natural Language Interface

CRITICAL — quoting and path examples:

• CORRECT: bash "${CLAUDE_PLUGIN_ROOT}/skills/octo-devtools/scripts/run_pwsh.sh" 'Get-AllGitRepStatus'
• CORRECT: bash "${CLAUDE_PLUGIN_ROOT}/skills/octo-devtools/scripts/run_pwsh.sh" 'Invoke-BuildAll -configuration DebugL -excludeFrontend $true'
• WRONG: bash "..." "Invoke-BuildAll -excludeFrontend $true" (double quotes — bash eats $true!)
• WRONG: pwsh -Command "Get-AllGitRepStatus" (profile not loaded!)
• WRONG: cd ... && bash scripts/run_pwsh.sh '...' (causes permission prompts!)

Always use single quotes around the PowerShell command argument so that PowerShell variables like $true and $false are not consumed by bash.

Build Strategy — CRITICAL

OctoMesh is a monorepo where repos produce NuGet packages consumed by downstream repos. The build system handles copying these NuGet packages between repos automatically — but ONLY when using Invoke-BuildAll.

When to use Invoke-BuildAll (DEFAULT CHOICE)

Use Invoke-BuildAll whenever building after code changes that could affect NuGet packages, or when unsure. This is the safe default. It builds repos in dependency order AND copies NuGet packages to the shared nuget/ folder between each step.

# Full build (all repos including frontends)
Invoke-BuildAll -configuration DebugL

# Backend only — skips Angular frontends (saves significant time)
Invoke-BuildAll -configuration DebugL -excludeFrontend $true

# Core repos only — skips optional/additional repos AND frontends
Invoke-BuildAll -configuration DebugL -excludeFrontend $true -excludeAdditional $true

Use Invoke-BuildAll for:

• After pulling latest changes (Sync-AllGitRepos)
• After switching branches
• When changes touch library repos (mm-common, octo-construction-kit-engine, octo-sdk, octo-common-services, octo-distributedEventHub, octo-construction-kit-engine-mongodb)
• When unsure whether changes affect NuGet packages
• Clean builds after deleting bin/obj folders
• First build after clone

When Invoke-Build is safe (SINGLE REPO, NO NUGET IMPACT)

Invoke-Build builds one repo in isolation. It does NOT handle NuGet package propagation.

Invoke-Build is ONLY appropriate when:

• Making changes within a single service repo (e.g., octo-asset-repo-services, octo-identity-services)
• The changes do NOT affect any NuGet package produced by that repo
• All upstream NuGet dependencies are already up-to-date in the nuget/ folder

# Safe: editing a controller in asset repo services
Invoke-Build -repositoryPath ./octo-asset-repo-services -configuration DebugL

NEVER use Invoke-Build to propagate NuGet changes. Do not attempt to manually chain Invoke-Build + Copy-NuGetPackages to replicate what Invoke-BuildAll does — use Invoke-BuildAll with the appropriate exclusion flags instead.

Command Quick Reference

For full parameter details, read references/command-reference.md in this skill directory. For common multi-step workflows, read references/workflows.md in this skill directory.

Build & Compilation

Service Management

Infrastructure

Git Repository Management

Branch Management

NuGet Package Management

Cleanup & Maintenance

Authentication / Environment

Certificates

Kubernetes

Versioning & Templates

Safety Rules

Read-only (execute directly, no confirmation)

Get-AllGitRepStatus, Get-OctoInfrastructureStatus, Find-AllGitRepos, Compare-BranchStatus

Mutating — local (execute with brief confirmation)

Invoke-BuildAll, Invoke-Build, Invoke-BuildFrontend, Invoke-Publish, Start-OctoInfrastructure, Stop-OctoInfrastructure, Install-OctoInfrastructure, Sync-AllGitRepos, Sync-GitRepo, Invoke-CloneMainRepos, Sync-AllSubmodules, New-TestBranch, Sync-TestBranch, Invoke-SwitchAllBranches, Copy-AllNuGetPackages, Copy-NuGetPackages, Sync-NuGetPackages, Invoke-OctoCliLogin*, New-RootCertificate, New-ServerCertificate, AspNetDeveloperCertificate, Join-KubeConfigs, Invoke-MongoPortForward, Sync-YamlTemplates, Update-MeshmakerVersion, Invoke-KillDotnet

Mutating — remote (confirm with emphasis)

Push-AllGitRepos, Push-GitRepo

Destructive (explicit confirmation + warning)

Remove-BinAndObjFolders, Remove-GlobalNuGetPackages, Invoke-CleanAllGitRepos, Uninstall-OctoInfrastructure, Remove-TestBranch, Invoke-CleanupInfraContainerDisks

Interactive (warn about session blocking)

Start-Octo, Invoke-BuildAndStartOcto — these commands block the terminal session until services are stopped via keypress. Always display this warning before executing:

Warning: This command will block the current session until you press a key to stop the services. The session will not be available for other commands while services are running.

Smart Behaviors

Natural language mapping

• "build everything" / "build all" → Invoke-BuildAll -configuration DebugL
• "build without frontend" / "build backend" → Invoke-BuildAll -configuration DebugL -excludeFrontend $true
• "build core only" / "build libraries" / "build base" → Invoke-BuildAll -configuration DebugL -excludeFrontend $true -excludeAdditional $true
• "build asset repo" → Invoke-Build -repositoryPath ./octo-asset-repo-services -configuration DebugL (only if no NuGet changes!)
• "rebuild after pull" / "sync and build" → Sync-AllGitRepos then Invoke-BuildAll -configuration DebugL
• "git status" / "repo status" → Get-AllGitRepStatus
• "pull latest" / "sync repos" → Sync-AllGitRepos
• "push everything" → Push-AllGitRepos (confirm first!)
• "start infra" / "start docker" → Start-OctoInfrastructure
• "stop infra" / "stop docker" → Stop-OctoInfrastructure
• "infra status" / "docker status" → Get-OctoInfrastructureStatus
• "clean build" → confirm, then Remove-BinAndObjFolders + Invoke-BuildAll -configuration DebugL
• "clean everything" → confirm each destructive step separately
• "switch to local" / "login local" → Invoke-OctoCliLoginLocal
• "create test branch" → New-TestBranch with user-provided version + description

Default configuration

Always use -configuration DebugL for build commands unless the user explicitly specifies a different configuration. This is the standard local development configuration.

Build order awareness

When the user asks to build, default to Invoke-BuildAll with exclusion flags to limit scope — do NOT attempt to manually orchestrate Invoke-Build calls in dependency order or manually copy NuGet packages. The Invoke-BuildAll script already handles the correct build order and NuGet propagation. Only use Invoke-Build for a single service repo where no NuGet packages are affected.

Workflow suggestions

When the user describes a high-level goal (e.g., "set up a fresh dev environment"), suggest the appropriate multi-step workflow from references/workflows.md and offer to execute it step by step.

Execution Flow

1. Parse intent — Map natural language to cmdlet(s) from the tables above
2. Check safety level — Determine if read-only, mutating, destructive, or interactive
3. Confirm if needed — For mutating/destructive ops, show the command + summary, wait for confirmation
4. Warn if interactive — For Start-Octo and Invoke-BuildAndStartOcto, display blocking warning
5. Execute — Run via the wrapper script and present results clearly
6. Suggest next steps — After completion, suggest logical follow-up actions (e.g., after build → start services)