Developer Workflows
Repeatable operating patterns that tie the system together. Each workflow shows how the default assistant, specialists, capabilities, and brain compose into real work. Most days start with the default assistant, switch to a specialist only when operating deeply, and end with /send or a recorded decision.
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#036A6E', 'primaryTextColor': '#fff', 'primaryBorderColor': '#034f52', 'lineColor': '#036A6E', 'secondaryColor': '#0a8f94', 'tertiaryColor': '#0a8f94'}}}%%
graph LR
A["/gm\nBriefing"] --> B["Observe\n& Plan"] --> C["Operate\ncimpl or osdu"] --> D["/send\nShip"]Environment Provisioning
Who: New developers or platform engineers setting up a CIMPL environment on Azure.
What happens: The @cimpl agent clones cimpl-azure-provisioning, verifies Azure authentication, and provisions the full infrastructure stack using azd up. This is usually the first step for new users.
| Phase | What happens |
|---|---|
| Clone & Auth | Clone cimpl-azure-provisioning, verify az login and azd auth login |
| Check Environments | List existing azd environments, ask to create new or use existing |
| Provision | azd up creates resource group, AKS, networking, OSDU services |
| Report | Summarize deployed services, connection endpoints, next steps |
Provisioning typically takes 20–30 minutes, depending on your Azure setup.
Daily Briefing
Who: Every developer, every morning.
What happens: The assistant gathers your goals from the vault, checks GitLab for open MRs and pipeline failures across monitored OSDU repos, measures goal progress, and recommends what to start first.
| Step | What the assistant does |
|---|---|
| Search vault | Pull goals from 01-goals/ and active projects from 02-projects/ |
| Check GitLab | Open MRs, pipeline failures, recent activity across monitored repos |
| Synthesize | Score priorities by urgency and goal alignment |
| Write | Save briefing note to $OSDU_BRAIN/00-inbox/YYYY-MM-DD.md |
| Recommend | Present top priorities and suggested first task |
When the vault exists, the briefing note is saved to $OSDU_BRAIN/00-inbox/ so future sessions can reference what was planned. Without the vault, the briefing is printed to the terminal only.
Clone and Scan
Who: Service developers working across OSDU repos.
What happens: Clone an OSDU service repository, run dependency analysis, and optionally remediate issues.
osdu, clone the partition service
osdu, scan partition dependencies
osdu, remediate low-risk items, flag anything high
| Step | What the @osdu agent does |
|---|---|
| Clone | Bare clone + worktree layout, matching project conventions |
| Scan | Trivy vulnerability scanning, POM analysis, risk scoring |
| Report | Save dependency report to the vault under 04-reports/, or to the working directory if the vault is not configured |
| Remediate | Batch LOW-risk updates, test MEDIUM individually, flag HIGH for review |
Risk-tiered remediation
Updates are scored by risk: LOW (0–1) are batched together, MEDIUM (2–3) are updated individually with testing, HIGH (4+) require research before updating. Risk factors include package category, version jump type, known CVEs, and fix location.
Debug and Verify
Who: Platform engineers troubleshooting infrastructure issues.
What happens: Systematic root cause analysis followed by evidence-based verification.
| Phase | What the @cimpl agent does |
|---|---|
| Gather evidence | kubectl logs, pod status, recent events, error messages |
| Check recent changes | git log, Terraform state, Helm release history |
| Form hypothesis | Correlate evidence with changes, propose root cause |
| Implement fix | Apply targeted fix, verify cluster health |
After the fix is applied:
The verify step runs actual commands against the cluster and reports evidence of success or remaining issues. It never claims "done" without proof.
Ship
Who: Every developer, end of work session.
What happens: Review changes, run quality checks, commit, push, and create a merge request in one command.
| Step | What the assistant does |
|---|---|
| Review | Diff staged and unstaged changes, flag anything unexpected |
| Quality checks | terraform fmt, PowerShell syntax, linting (context-dependent) |
| Commit | Generate commit message (via worktrunk if available, or git), commit changes |
| Push | Push branch to remote with tracking |
| Merge request | Create MR targeting dev with generated description |
The entire flow runs in sequence. If any step fails, it stops and reports what went wrong before continuing.
QA Testing
Who: Service developers and platform engineers validating OSDU services.
What happens: Run tests across environments, analyze failures, compare results, and generate reports.
osdu, run smoke tests on cimpl/qa
osdu, compare test results between cimpl/lab and cimpl/qa
osdu, generate a quality report for core services
| Step | Sub-Agent | What happens |
|---|---|---|
| Health check | Runner | Verify environment connectivity before testing |
| Execute | Runner | Run test collections in parallel across environments |
| Analyze | Analyzer | Categorize failures (service, data, config, infrastructure) |
| Compare | Comparator | Diff results across environments, identify regressions |
| Report | Reporter | Generate dashboard or markdown report |
The runner always health-checks before executing tests. Reports are saved to $OSDU_BRAIN/04-reports/qa/ when the vault exists, or to the current working directory otherwise.
Acceptance Testing
Who: Service developers verifying OSDU services against a live cimpl environment.
What happens: Run Java acceptance or integration tests from a service repository against your deployed cimpl environment. The skill resolves environment configuration (URLs, Keycloak auth) from cimpl-azure-provisioning automatically.
| Phase | What happens |
|---|---|
| Locate | Find the service repo and identify test structure (standalone or provider-specific) |
| Analyze | Read Config.java to discover required env vars and auth mechanism |
| Resolve | Extract service URL, Keycloak credentials, and tenant from the azd environment |
| Execute | Build test-core (if needed), run mvn clean test with resolved env vars |
| Report | Parse Surefire results and present structured summary |
For coverage gap analysis before running tests, use osdu-quality:
This compares test classes across providers in CI and highlights what CSP integration tests cover that cimpl acceptance tests don't.
Learn and Consolidate
Who: Developers building shared team knowledge.
What happens: Acquire knowledge from external sources and maintain vault hygiene.
Learning
| Step | What the learn skill does |
|---|---|
| Fetch | Retrieve content from GitLab wikis, URLs, or documentation |
| Distill | Extract key insights into structured notes |
| Write | Save to 03-knowledge/ using the appropriate template |
| Index | QMD re-indexes automatically, making knowledge available to future sessions |
Consolidation
| Step | What the consolidate skill does |
|---|---|
| Scan | Check notes in 03-knowledge/ for last-verified age |
| Compare | Cross-reference related notes for contradictions |
| Report | Surface findings without deleting |
| Confirm | Update last-verified on notes confirmed as still accurate |
Run monthly. Notes with source: human in frontmatter are immune to decay. You decide what to archive or update.
Decision Capture
Who: Anyone making a decision worth preserving.
What happens: The brain skill records a structured decision note in the vault so future sessions can reference it.
Record this decision: we're using CNPG instead of Azure Database
for PostgreSQL because managed PaaS doesn't support the extensions
OSDU needs
| Step | What happens |
|---|---|
| Classify | Determine decision type (ADR, lightweight, project) |
| Write | Create structured decision note under 03-knowledge/ using the decision template |
| Index | Note is indexed and available to all future sessions |
The assistant can reference recorded decisions when related topics come up later.
Workflow by Persona
Different roles use different workflows most often:
A typical day:
/gm— morning briefing with goal progress and OSDU activityosdu, clone <service>— set up a service repo for workosdu, scan <service> dependencies— check for vulnerabilities- Work on the service code
/send— ship changes with review, quality checks, and MR
A typical day:
/gm— morning briefing with infrastructure and OSDU activitycimpl, debug <issue>— investigate a platform problemcimpl, verify <fix>— prove the fix works with evidence- Work on Terraform, Helm, or Kustomize changes
/send— ship changes with review, quality checks, and MR
See also
- Getting Started — first-time setup and your first session
- Specialist Agents — when to use
@cimplvs@osdu - Capabilities — full catalog of system capabilities
- Brain — how persistent knowledge supports these workflows