Skip to content

DOC

Workflows

Step-by-step workflows for common development scenarios with ulk.

Workflows

Five complete workflows, each with real commands and agent delegation. All workflows assume ulk is installed and you are in a Claude Code session.

Workflow 1 — New project from scratch

Situation: empty repo, vague brief, no spec, no tech decisions made yet.

Step 1 — Single entry point

/ulk:bruce go

Bruce invokes Godspeed, reads the empty state, then asks Tony to handle the architecture decision.

Step 2 — Architecture (Tony, agent 50)

Tony asks a short questionnaire: target users, expected scale, preferred stack, deployment constraints, timeline. It produces:

  • Stack recommendation with rationale
  • Architecture overview
  • Phase breakdown with time estimates
  • Handoff to Stark for the design system and Shuri for documentation

Example Tony output structure:

Stack: Astro 5 SSG + TypeScript strict + Tailwind v4
Hosting: Vercel (free tier sufficient for < 10K monthly visits)
Phases: 4 × 0.5 day = 2 days solo
Next: → Stark (design) → Shuri (spec + todo)

Step 3 — Design system (Stark, agent 58)

If a brand, URL, or Figma file is provided, Stark extracts the visual language and produces:

  • docs/design.md — design source of truth (palette, typography, spacing, anti-patterns)
  • design-model.yaml — machine-readable design tokens
  • tokens.css — CSS custom properties
  • HTML previews of key components

If no visual reference exists, Stark builds from the brief. Agathe (60) acts as art director and validates the output.

Step 4 — Spec and backlog (Shuri, agent 01)

Shuri reads Tony + Stark outputs and produces:

docs/spec.md     ← narrative spec (frontmatter + 9 sections, Obsidian-compatible)
docs/todo.md     ← Kanban board (Backlog / Todo / In Progress / Blocked / Done)
CLAUDE.md        ← project context (updated with stack, agents, doc-mode)
README.md        ← project overview

The todo.md format is compatible with the Obsidian Kanban plugin (mgmeyers/obsidian-kanban).

Step 5 — Prompt decomposition (Project Decomposer, agent 35)

Transforms the todo into self-contained Claude Code prompts stored in docs/prompts.md. Each prompt works without prior context, which protects against drift in long sessions.

Step 6 — Implementation

/ulk:bruce next     # Execute first task
/ulk:bruce next     # Execute second task
# ...

Bruce delegates each task to Task Runner (04), which reads docs/todo.md and executes sequentially. For heavy exploration (understanding a large dependency, reading many files), Bruce spawns a sub-agent to keep the main context clean.

If a build breaks:

/ulk:robocop

Step 7 — Session checkpoint (2b3, agent 08)

At the end of each session:

/ulk:2b3

2b3 runs: tsc strict → lint → tests → simplification pass → todo update → memory capture → commit. If Verify (65) finds a CRITICAL gap between spec and code, 2b3 flags it but still allows the commit (non-blocking in this phase).

Step 8 — Pre-launch audit

/ulk:sargeras       # 10-axis audit (security, perf, tests, a11y, CI/CD...)
/ulk:ed209          # Security deep dive
/ulk:killbill       # Cost audit (Vercel, GitHub, Neon)

Or all four in parallel:

/ulk:blackemperor

Step 9 — Deploy

/ulk:xavier         # Verify you're on the right account before deploying
/ulk:deploy-vercel  # Deploy to Vercel

Deliverables

  • docs/spec.md, docs/todo.md, docs/design.md, CLAUDE.md, README.md
  • design-model.yaml, tokens.css
  • Clean git history with one commit per logical step
  • Sargeras audit report archived in docs/audits/
  • Project deployed and live

Workflow 2 — Audit an existing project

Situation: legacy repo, inherited codebase, or a project not touched in months. Goal: understand the state, identify problems, produce an actionable plan.

Step 1 — Initial cartography

/ulk:bruce

Bruce calls Godspeed, which scans and reports: stack, state (greenfield / in progress / stalled / production), key files present or absent, visible debt.

Step 2 — Reconstruct missing documentation

If docs/spec.md is absent or outdated:

/ulk:strange

Strange reverse-engineers a spec from the code. It reads the directory structure, entry points, dependencies, and produces a narrative spec that can be edited and committed.

If any AI-generated outputs exist and you want to understand the prompts that produced them:

/ulk:strange mode=prompt

Step 3 — Full audit

/ulk:sargeras

10-axis scored report. Violations sorted by severity. Typical axes:

  • Security (secrets, dependencies, headers)
  • Performance (bundle, Core Web Vitals, queries)
  • Architecture (coupling, patterns, consistency)
  • Tests (coverage, quality, regression)
  • CI/CD (pipeline health, deploy frequency)
  • Accessibility (WCAG 2.1/2.2)
  • SEO (meta, structure, performance)
  • Documentation (completeness, freshness)
  • Tech debt (age, churn, complexity hotspots)
  • Cost (cloud spend, unused resources)

Step 4 — Targeted audits

/ulk:ed209          # OWASP Top 10 security
/ulk:killbill       # Cloud cost analysis with savings plan
/context-audit      # Token health score (CLAUDE.md bloat, unused MCPs, missing settings)

For a single consolidated report from all four:

/ulk:blackemperor

Step 5 — Convert findings to tasks

Shuri reads the audit reports and pushes findings into docs/todo.md with a datestamped category:

/ulk:shuri

Deliverables

  • Comprehensive project state report
  • Prioritized fix list (security first, cost second, tech debt third)
  • Cloud savings plan with estimated amounts
  • Updated docs/todo.md ready for the next development session

Workflow 3 — Daily development session

Situation: active project, working on it regularly. Goal: maximize throughput without saturating context.

Morning routine

1. Context verification (Xavier, agent 57)

/ulk:xavier

Verifies: correct repo, correct account, last git state, last session summary. If --with-xavier-hook was passed at install, this runs automatically at session start.

2. Memory surface (Lovecraft, agent 47)

/ulk:lovecraft memory surface

Read-only summary of architectural decisions, known issues, and preferences from previous sessions. This is auto-integrated in Godspeed’s Phase 1.5 when Bruce invokes it.

3. Project pulse (Godspeed, agent 00)

/ulk:godspeed

Current state: which tests are red, last commit, where are we in the todo, any CI failures.

Development routine

4. One task per session (Hygiene Rule 2)

Pick one task from docs/todo.md. No chaining of unrelated tasks. After completion: commit → /clear → new session.

/ulk:bruce next     # Takes the next task from todo.md and executes it

5. Sub-agents for heavy exploration (Hygiene Rule 3)

When understanding a module requires reading many files, do not explore in the main session:

Launch a sub-agent to summarize how the authentication module works

The sub-agent returns only the synthesis. The main context stays clean.

6. Proactive /compact at 50-60% (Hygiene Rule 4)

When the context indicator reaches 50%:

/compact Preserve: arch decision (option B), files in progress (src/auth.ts), active bug (#A042). Discard: abandoned approaches.

7. Build broken? Robocop

/ulk:robocop

Robocop identifies the root cause (broken import, type error, failing test), applies the fix, re-runs the check.

End-of-session routine

8. Checkpoint (2b3, agent 08)

/ulk:2b3

Runs: lint → tests → tsc strict → simplification → todo update → memory capture → commit message suggestion → commit.

9. Clear (Hygiene Rule 2)

/clear

After 2b3, always /clear before starting the next unrelated task.

Cloud routines (without a local machine)

Sessions that run autonomously without requiring you to be at a computer. Configure via agent Routine (53):

/ulk:routine

Recommended schedule:

  • 2b3 daily at 18:00 — auto end-of-day checkpoint
  • Godspeed weekly — weekly project health
  • Robocop / CI Guard on check_suite.completed (failed) — auto-fix broken CI
  • Sargeras weekly Monday — weekly audit
  • Lovecraft daily at 08:00 — memory surface before the workday
  • ED-209 monthly — security audit
  • Killbill monthly on the 1st — cost review

Workflow 4 — Release / ship

Situation: feature complete, ready to release. Goal: verify quality, audit, deploy.

Step 1 — Completeness review

/ulk:bruce review

Bruce checks: spec vs code completeness, open tasks in todo.md, test coverage, documentation freshness.

Alternatively, run Verify directly:

/ulk:verify

Verify checks 3 dimensions:

  • Completeness: everything planned was delivered
  • Correctness: what was delivered matches requirements
  • Coherence: code respects design decisions and repo conventions

A CRITICAL finding blocks the audit phase. A WARNING is noted but does not block. A SUGGESTION is informational.

Step 2 — Pre-release audit

/ulk:sargeras       # 10-axis audit
/ulk:ed209          # Security

Or in parallel:

/ulk:blackemperor

Step 3 — Cost check

/ulk:killbill

Verify the deployment will not introduce unexpected cloud costs. Killbill runs in dry-run mode by default — no actual changes are made.

Step 4 — Account verification (Xavier)

/ulk:xavier

Confirms: correct GitHub account, correct Vercel account, correct API keys. A deploy to the wrong account is a common and avoidable mistake.

Step 5 — Deploy

/ulk:deploy-vercel    # Vercel
/ulk:deploy-netlify   # Netlify
/ulk:deploy-fly       # Fly.io
/ulk:deploy-aws       # AWS
/ulk:deploy-cloudflare # Cloudflare Workers/Pages
/ulk:deploy-docker    # Docker build + push

Step 6 — Post-deploy checkpoint

/ulk:2b3

Final commit (changelog, version bump if applicable), memory capture, session close.

Workflow 5 — Team onboarding

Situation: sharing ulk with teammates. Goal: each team member has the same agents, same conventions, same vocabulary.

Installation (each team member)

git clone https://github.com/izo/ulk
cd ulk
./install.sh

The install is per-machine, per-user (~/.claude/). Agents are not shared via the project repo — each developer installs their own copy.

Project CLAUDE.md as shared context

The project’s CLAUDE.md (at the project root, committed to git) is the shared source of truth for:

  • Stack and architecture decisions
  • Ulk agents used and why
  • Doc mode (faru / obsidian)
  • Custom agent configurations

All team members get the same CLAUDE.md on git pull.

Shared vocabulary

All team members use the same slash commands:

/ulk:bruce     → start any session
/ulk:2b3       → end any session
/ulk:sargeras  → audit before PR merge
/ulk:godspeed  → project health check

This creates a common language across the team — no more ad hoc prompts that vary per person.

CI integration (CI Guard, agent 54)

For teams using GitHub Actions, CI Guard can be configured as a Managed Agent triggered by CI failures:

./install.sh --with-managed-agents

Then configure the GitHub webhook to send check_suite.completed events to the CI Guard trigger handler (framework/managed-agents/triggers/webhook-github.ts).

CI Guard automatically investigates failures, proposes fixes, and can open a PR with the fix.

Agent Teams (experimental)

For coordinated multi-agent work, Agent Teams can be enabled:

./install.sh --with-teams

Agent Teams allow multiple agents to work concurrently on related tasks, with Bruce coordinating the outputs. This feature requires a settings.local.json configuration — see framework/ for examples.

Audit trail

For teams that need governance over AI-assisted changes:

./install.sh --with-accountability

This installs a PostToolUse hook that logs all file mutations (Edit, Write, Bash) to .ulk-reports/accountability.jsonl. A companion log tracks file reads in read-coverage.jsonl.

# View the audit trail
./framework/tools/accountability-report.sh
./framework/tools/accountability-report.sh --since 2026-05-01 --tool Edit
./framework/tools/accountability-report.sh --read-coverage