Gus CLI

Gus CLI

Interact with Gus (Salesforce Agile Accelerator org) via sf CLI. Requires alias gus in sf alias list.

Safety

• Queries (sf data query, sf alias list): run without asking
• Writes (create, update): do not execute until user explicitly confirms
  • Present the draft (subject, epic, details, assignee). Ask: "Create this work item?" or "Update work item X?"
  • Draft format: Use bullet list, not markdown table (tables can render blank in some viewers). Put Details__c in a code block so HTML content is visible.
  • Only run sf data create record / sf data update record after user says yes (or equivalent)
  • Answering scope questions (e.g. "just createProject") is not confirmation—still ask
• Epic selection: when less than 50% sure which epic a work item belongs in, ask the user
• IDs vs Names: Id (e.g. a07...) is for CLI commands. Name (e.g. W-12345) is for human display and PR titles appended as - W-12345 at the end per pr-draft Title format. NEVER use Id in PR titles or descriptions. Always query Name after creation.

Prerequisites

1. Run sf alias list --json; parse result for alias matching gus (case-insensitive)
2. If missing: instruct user sf org login web -a gus
3. All commands use -o gus

Runner identity

Cache: $HOME/.claude/runner-identity.json — {userId, username, ownerPrefix, slackId, githubLogin}.

1. sf alias list --json → entry /^gus$/i. Missing → sf org login web -a gus. Value = currentUsername.
2. Cache hit (file exists, all 5 fields, cached.username === currentUsername) → use it.
3. Miss → resolve:
   • sf data query --query "SELECT Id FROM User WHERE Username = '<currentUsername>' LIMIT 1" -o gus --result-format json → userId
   • Match currentUsername to ## Team members row → githubLogin, slackId. ownerPrefix = initials lowercase (Shane McLaughlin → sm; one-word → first 2 chars).
   • Not in table → caller's error.
   • mkdir -p $HOME/.claude && write JSON.

Invalidate: alias change auto-detects. Manual: rm $HOME/.claude/runner-identity.json.

Same session: reuse conversation value; don't re-read.

Constants

Always use User Story RecordTypeId. Never create Bug records. If user describes a bug/repro, still create it as a User Story.

Objects: ADM_Work__c, ADM_Epic__c (not ADM_Theme__c).

Team members (Assigneec, QA_Engineerc)

Default when unassigned: Platform Dev Tools Scrum Team 005B0000000GIODIA4 – use when work isn't assigned to a person yet.

Work items (ADM_Work__c)

Base select: SELECT Id, Name, Subject__c, Status__c, Story_Points__c, Epic__c, RecordType.Name FROM ADM_Work__c

Optional display/detail fields (append to SELECT only for single-WI/triage queries; do NOT add to bulk team/epic queries unless asked—keeps base lean, avoids widening every result set/terminal table):

• Priority__c — picklist P0-P4.
• Epic_Name__c — formula/string; epic name w/o Epic__r join. Bulk lists use existing Epic__c id or a separate epic-name lookup (formula evaluated per-row otherwise).
• Due_Date__c (datetime) + Out_of_SLA__c (boolean) — SLA tracking.
• Security trio: Security__c (label "Locked by Security", boolean), Security_Vulnerability_Category__c (picklist, 30+ values), Security_Source__c (label "Source", picklist, 30+ values—run sf sobject describe for full lists).

Query patterns (combine as needed; use LIMIT on broad queries):

Open/unfinished filters use the WHITELIST Status__c IN (<open list>), never NOT IN (<terminal>) — the open list + why a blacklist leaks legacy terminals (incl. the Bug-no-fix set) live in statuses.md. Use LIMIT 50 (or 100) when querying team or epic work.

Body fields (Details__c vs Details_and_Steps_to_Reproduce__c)

The validated User Story body is Details__c. Three rules, one place:

• ≥20 chars required. Details__c (field label "Description") has a User Story validation rule: <20 chars → create fails with Description must be at least 20 characters to submit a User Story. Despite docs marking it optional, treat as required on create.
• Don't confuse with Description__c — a DIFFERENT field (label "Comment", unvalidated). The validated body is Details__c.
• Bug records store the body in Details_and_Steps_to_Reproduce__c (richtextarea), not Details__c. Querying only Details__c misses Bug/PVR content, and a null Details__c on a Bug record ≠ under-specified. Single-WI fetch of unknown/mixed record type → SELECT both, use whichever is populated.

Sequencing prefix: When planning an epic or when the user states a dependency, prefix Subject__c with a sequence number + space (e.g. 1.2 Add config loader). See work-item-sequencing. Optional — skip for independent work.

Create & update → writes.md

sf data create/update record has real traps — -v/--flags-dir incompatibility, space-splitting that truncates multi-word values, HTML-only Details__c, href-stripping, and silent wrong-Id overwrites. The create-then-update recipe, formatting, and verify-Id steps live in writes.md. Read it before any write.

Epics (ADM_Epic__c)

Creating an epic or bulk-creating its work items → epics.md (fields, Scheduled_Build__c, the Details__c ≥20-char + CLI-warning-breaks-JSON gotchas, bulk-create loop).

Query team epics (exclude closed):

sf data query --query "SELECT Id, Name, Description__c FROM ADM_Epic__c WHERE Team__c = 'a00B0000000w9xPIAQ' AND Health__c NOT IN ('Completed', 'Canceled')" -o gus --result-format json

Closed = Health__c in ('Completed', 'Canceled'). Use Description__c when populated to match work to epic.

Description__c is not filterable in SOQL — WHERE/LIKE on it errors field 'Description__c' can not be filtered in a query call. To match an epic by text, fetch all open epics and match on Name, or post-filter Description__c client-side (e.g. with jq). Only SELECT it.