Developer Workflows

This page documents the practical workflows available through the agentic system — how to use them, what they do, and how to extend them.

Daily Briefing

Command: /gm or /briefing

The daily briefing gathers OSDU platform activity and combines it with your vault goals to produce a structured morning report.

What Happens

Step	Action	Source
1	Gather open MRs across monitored OSDU repos	GitLab API via `osdu-activity`
2	Check pipeline status for recent failures	GitLab API
3	Read current goals and key results	Vault (`01-goals/`)
4	Read project monitoring config	Vault (`02-projects/`)
5	Generate briefing note	Wingman (briefing skill)
6	Write to vault	`brain` skill → `00-inbox/YYYY-MM-DD.md`
7	Print summary to terminal	Wingman

Output

The briefing note includes:

Open MRs requiring attention (yours and others')
Pipeline failures or degraded services
Goal progress and upcoming deadlines
Suggested priorities for the day

Ship-It Workflow

Command: /send

Reviews, checks, commits, pushes, and creates a merge request in one flow.

What Happens

Phase	Action	Details
Preflight	Check branch and working tree	Ensure on a feature branch, no uncommitted conflicts
Review	Lite code review	Scan changes for obvious issues, security concerns
Quality	Run quality checks	`terraform fmt -check`, PowerShell syntax validation
Commit	Generate commit message	Via `wt step commit` (worktrunk) or `aipr commit`
Push	Push to remote	`git push -u origin <branch>`
MR	Create merge request	`glab mr create --fill --target-branch dev`

Prerequisites

On a feature branch (not dev or main)
Changes staged or unstaged (the workflow handles staging)
glab CLI authenticated to GitLab

Clone-and-Scan Workflow

Commands: /clone then /dep-scan

Clone OSDU repositories and analyze their dependencies.

Clone Phase

The /clone command sets up OSDU repos in .osdu/ using a bare clone + worktree layout:

.osdu/
├── os-partition/
│   ├── .git/              # Bare clone
│   └── master/            # Worktree (default branch)
├── os-entitlements/
│   ├── .git/
│   └── master/
└── ...

Available categories:

Category	Repos
libraries	os-core-common, os-core-lib-azure, os-oqm
core	os-partition, os-entitlements, os-legal, os-storage, os-search, os-indexer
reference	os-wellbore, os-well-delivery, os-seismic
ingestion	os-ingestion-workflow, os-csv-parser, os-manifest-ingestion
domain	os-reservoir, os-well-planning, os-dataset

Scan Phase

The /dep-scan command runs a comprehensive dependency analysis:

Discover — Find all dependency manifests (pom.xml, package.json, requirements.txt)
Fetch — Run Trivy vulnerability scan, parse dependency trees
Assess — Score each dependency by risk (version age, CVEs, category)
Distill — Generate summary with recommendations
Write — Store report in vault (04-reports/)

Debug-and-Verify Workflow

Commands: /debug then /verify

Systematic root cause analysis followed by evidence-based completion verification.

Debug Phase

The /debug command triggers the iac-debug skill's four-phase investigation:

Phase	Action
Gather evidence	Read logs, events, pod status, recent deployments
Check recent changes	`git log`, terraform state, helm history
Form hypothesis	Correlate evidence with known failure patterns
Implement fix	Apply the fix, test, document

Verify Phase

The /verify command triggers the iac-verify skill, which refuses to mark work complete without running verification commands:

Check	Command
Cluster health	`kubectl get nodes`, `kubectl get pods -A`
AKS safeguards	`kubectl get constrainttemplates`
Elasticsearch	`curl elasticsearch-es-http:9200/_cluster/health`
PostgreSQL	`kubectl cnpg status postgresql`
cert-manager	`kubectl get certificates -A`
Istio	`kubectl get peerauthentication -A`

Workspace Layout

The project uses git worktrees managed by worktrunk (wt) for parallel development.

Branching Model

main ← dev ← feature/*

main — clean deployable surface (read-only reference)
dev — integration branch (daily work)
feature/* — individual changes, branched from dev

Worktree Structure

cimpl-azure-provisioning/          # Bare repo root
├── main/                          # main branch worktree
├── dev/                           # dev branch worktree (primary)
├── feature/docs-restructure/      # Feature branch worktree
└── .osdu/                         # OSDU service repos (bare + worktree)

Worktrunk Configuration

Defined in .config/wt.toml:

default-branch = "dev"              # Feature branches start from dev
post-create = "wt step copy-ignored --from dev"  # Copy .env files to new worktrees

[ci]
platform = "gitlab"

Common Commands

# Create a feature branch
wt switch --create feature/<name> --base dev

# See all changes since branching
wt step diff -- --stat

# Commit with generated message
wt step commit

# Push and create MR
git push -u origin $(git branch --show-current)
glab mr create --fill --target-branch dev

Extending the System

Adding a New Skill

Create SKILL.md in the appropriate location:
- Shared: .github/skills/<name>/SKILL.md
- Wingman: .ai-wingman/skills/<name>/SKILL.md
- OSDU: .ai-osdu/skills/<name>/SKILL.md

Define the skill with:

# Skill Name

## Triggers
- keyword1, keyword2, phrase

## Protocol
1. Step one
2. Step two

## Constraints
- Rule one
- Rule two

Add routing entry in .github/routing.md
Add trigger mapping in .claude/CLAUDE.md skill loading table

Adding a New Slash Command

Create a file in .claude/commands/<name>.md with the command protocol. The filename becomes the command (e.g., deploy.md → /deploy).

Adding a New Prompt

Create a file in .github/prompts/<name>.prompt.md. Prompts are longer multi-step workflows that can be invoked by commands or agents.

Adding a Vault Template

Create a template in .ai-brain/templates/<name>.md with YAML frontmatter and Obsidian-compatible markdown. Templates are used by the brain skill when creating new notes.