Skip to main content

Guide: Developers

As a developer, Workloom keeps your AI tools configured correctly without you thinking about it. No manual copying, no Slack messages asking "did you update your CLAUDE.md?", no surprises.

Daily Workflow​

Morning Sync​

wl pull

That's it. Your AI tools now have the latest team-approved configuration. If there are updates:

✓ Updated @acme/frontend-baseline (1.1.0 → 1.2.0)
  → Updated CLAUDE.md
  → Updated .claude/skills/review/SKILL.md
✓ 2 files updated, 0 conflicts

Check Your Status​

wl status
Workspace: acme/frontend-team (revision 14)
Packages:
  @acme/frontend-baseline@1.2.0  ✓ clean
  @acme/security-review@2.0.1    ✓ clean
  @acme/react-patterns@1.0.0     ⚠ 1 file locally modified

Files:
  CLAUDE.md                       owned_clean
  .claude/settings.json           owned_clean
  .claude/skills/review/SKILL.md  owned_clean
  AGENTS.md                       owned_locally_modified (you edited this)

Making Local Customizations​

You can edit Workloom-managed files. Your changes are tracked:

# Edit CLAUDE.md to add project-specific context
vim CLAUDE.md

# Workloom knows you changed it
wl status
# → CLAUDE.md: owned_locally_modified

Your edits are safe — wl pull will never silently overwrite them. If the upstream changes too, you'll get a conflict notification and choose how to resolve it.

Viewing Diffs​

See what changed between your local version and the desired state:

wl diff
--- desired (from @acme/frontend-baseline@1.2.0)
+++ local
@@ -12,3 +12,6 @@
 - Never use `any` — use `unknown` and narrow

+# Project-Specific
+- This project uses Next.js App Router
+- State management via Zustand

Resolving Conflicts​

If the desired state changed AND you have local modifications:

wl pull
# ⚠ Conflict: CLAUDE.md
#   Your version differs from the new desired state
#   Options: --on-conflict fail|keep-local|restore|promote-to-override
# Exit code: 4

Your options:

# Keep your version (most common)
wl pull --on-conflict keep-local

# Restore to team standard (discard your edits)
wl restore CLAUDE.md

# See what's different
wl diff CLAUDE.md

Contributing Configs Back​

Have a great skill or config pattern? Contribute it upstream:

# Create a new package version with your improvement
wl push --draft

# Your team lead reviews and publishes
# Now everyone benefits from your contribution

Tips for Developers​

  1. Pull regularly: Start of day or after a Slack notification about workspace updates.
  2. Don't fight the system: If you find yourself constantly modifying managed files, talk to your team lead about updating the package.
  3. Use --dry-run: wl pull --dry-run shows what WOULD change without touching files.
  4. Check CI before pushing: Run wl sync --check locally to avoid CI drift failures.
  5. Local additions are fine: Files Workloom doesn't manage are yours. Add project-specific CLAUDE.md sections by promoting to an override.