Twg

twg

First TWG routing step: choose the shortest reliable path to the data. Use a typed TWG command when the user provides a stable key, URL, ARI, or familiar command family; use twg help, twg help <terms>, or twg help describe <path> before the data call when the command family, arguments, flags, or output contract are uncertain.

After this skill has loaded, do not reread installed skill markdown as a discovery step. Start with the TWG wrapper, live help, and live data outputs.

Overview

Use this skill for TWG CLI work-data tasks. For synthesized outcomes, also load the most specific workflow skill:

• twg-status-rollups for personal, team, org, project, goal, focus-area,

leadership, quarterly, and appraisal readouts.

• twg-context-discovery for topic deep dives, dependency maps, context graphs,

repo discovery, and "catch me up" prompts.

• twg-engineering-work for PR queues, stale reviews, repo contributors, hot

areas, and PR-based status.

• twg-operational-health for on-call handoffs, reliability/HOT/PIR reviews,

Assets/laptop refresh, staffing/capacity, meeting summaries, and operational risk.

Available scripts

• twg - run TWG with agent defaults.

For large outputs, inspect output_files.compact first when present, then read or filter output_files.stdout only when the compact view lacks evidence. See references/OUTPUT.md.

Command Discovery

• Use typed commands directly for familiar common families: resolve, user,

org-tree, work query, search, projects, goals, pull-requests, jira, confluence, docs, and context.

• Person lookup accepts a positional name: twg user search "<name>" --limit 1.

Use --email for exact email lookup.

• Use twg help for top-level compact YAML routing only when the right family is

not clear. In namespace output, $ lists executable child commands under the current namespace.

• Use twg help <terms> before guessing unfamiliar command names, arguments,

flags, choices, or defaults. Treat help as discovery, not evidence: do not run batches of synonym help searches when one family lookup would answer the command-shape question.

• Use twg help describe <path> to inspect either a namespace map or an exact

executable command contract when exact arguments, flags, output fields, or agent summaries matter. Namespace output is compact YAML; executable output is JSON by default.

• Do not front-load help describe for every known family. Use focused help

before the first data command only when the command family or contract is genuinely unclear.

• Keep projection commands conceptually separate from native/federated commands:
• Projection commands provide bounded synthesized views. Use a common mental

model: scope, time, budget, detail, and output.

• Native/federated commands keep product-specific options. Do not assume

projection flags such as --sample, --hydrate, --only-counts, or --agent-fields exist unless twg help describe <path> advertises them.

• Pick starter commands by the user's anchor type: resolve names/URLs/keys

first, use product-native get/query surfaces for known objects, and use projection/context surfaces when the installed help advertises the needed anchor and flags.

• Stable product keys do not need broad discovery when the product family is

clear. For example, use Jira work item commands for Jira issue keys, and use project or goal commands for project/goal keys or URLs before falling back to cross-product search.

• Search/Rovo results are candidate anchors, not hydrated evidence. When a

result provides a stable key, ID, URL, or ARI, switch to the exact executable product get command for that family. Use query for filters. If that exact child command shape is not already known, run one focused twg help describe "<family> get" or twg help describe "<family> query" first. Do not pass result keys to namespace commands or borrow flags from sibling commands.

• For org rollups, prefer roster and aggregate signals first, then selected

user-scoped evidence. Do not compensate for missing org-level scope by running relationship context across every visible person.

• If a context surface is unavailable for an anchor type, say so as a coverage

gap and use search plus product-native hydration for the selected candidates.

• Before writing jq filters for a command, inspect help describe output.

Prefer the advertised output.recommendedSummary and output.recommendedAgentFields over trial-and-error raw JSON inspection.

• Follow next commands from help output exactly; do not synthesize

unsupported help syntax.

• Do not use legacy human --help loops for agent discovery.
• Resolve: use twg resolve --query "<input>" for URLs, keys, ARIs,

exact names, and people.

• Search: use twg search "<query>" --limit 20 for fuzzy topics,

partial titles, nicknames, customers/themes, or unknown products.

• When using app filters, discover valid Rovo app keys first: twg rovo list-apps
• Hydrate: fetch the best 1-3 candidates with exact native get commands for

stable keys/IDs/URLs/ARIs, product query commands for filters, or context commands.

• Synthesize: answer from hydrated evidence, not search snippets.

Rich Content Writes

For Jira/Confluence description, body, and comment writes, match the command's format flag. If it is HTML, use real HTML such as <h2>, <p>, <code>, and <a href="https://...">label</a>.

Do not pass Jira wiki markup such as h2. Heading, [label|url], or *bold*. If live help supports it, choose an explicit markdown/plain flag instead, such as --description-format markdown, --body-format markdown, or --body-format plain.

Routing

Concrete scope matters: use a Jira key, page URL, PR URL, repo slug, account ID, team/project/goal/focus-area name, customer/topic name, "me", or a time window. If there is no concrete or partial scope, ask before running broad searches.

Rules

• Never guess IDs, flags, Jira keys, project keys, account IDs, page IDs,

workspace/repo slugs, ARIs, or object IDs.

• For Jira workitem custom fields, first discover metadata with

twg jira workitem field create-metadata before create, or twg jira workitem field update-metadata before update. Use returned customfield_* IDs in --field/--fields-json; display names are only for readability and may conflict. Do not pass the same field key in both --field and --fields-json; the command rejects collisions. --field values parse as JSON when valid, so quote JSON strings to force string IDs.

• To read back custom field values, use twg jira workitem get <KEY> --field customfield_*

or --fields customfield_*,summary; do not use admin twg jira field commands for value reads.

• Do not use twg jira field create/update/delete for workitem field values.

That namespace is admin CRUD for global Jira custom field definitions.

• Atlassian Admin operations use twg admin. Admin commands use a separate

Admin API key via twg admin auth login; never reuse or expose normal user auth tokens for admin workflows.

• If an Atlassian URL includes https://<site>.atlassian.net/..., pass

--site <site> on the first related typed command.

• Treat search/Rovo results as candidate anchors only.
• Fan-out is bounded: resolve scope first, then hydrate selected artifacts.
• For broad reports, prefer summary output and local filtering over flooding

stdout.

• Avoid using rg to inspect TWG JSON payloads. Use output_files.compact when

present, or targeted jq against output_files.stdout.

• For multi-file or multi-field evidence, batch local projection or inspect

compact summaries directly instead of repeating one-field filters.

• If a command returns a deterministic contract or validation error, make one

focused correction from the error. If the same failure persists, report the CLI limitation instead of trying repeated variants.

• For personal, user, or org pull-request queues, prefer twg pull-requests query

with the requested scope and role. --state is the canonical lifecycle filter; --status is accepted as an alias.

• For Jira board or "what should I pick next" prompts, do not use broad work

activity as the ranking source. If the board name is a Jira project key, query open Jira work directly with JQL and order by priority/rank; use board/backlog commands when the user supplies or asks for a concrete board backlog.

• Use context user for the root manager, explicit review subject, or another

central collaborator whose graph changes the answer. For sampled org members, prefer work query, pr-tree, docs/search, and product-native artifacts over per-person context user calls. If a context user call fails with a backend GraphStore error or "No relationships match", record that as a coverage gap and continue instead of retrying nearby filters.

• For org/team rollups, avoid exhaustive per-person fanout across every surface.

Resolve the roster, pull aggregate/team/project/goal signals first, then sample representative people or outliers before synthesizing.

• For writes, read current state first and state the intended mutation unless the

user explicitly asked you to execute it.

Anti-Patterns

• Do not use local workspace inspection, cached-output spelunking, or process

diagnostics as the first move for work-data prompts unless the user asks about local files or process state.

• Prefer canonical command paths in examples and plans when live help shows both

a canonical path and a compatibility alias. Compatibility aliases such as user-search, page, blog, whiteboard, database, folder, or issue mainly rescue stale prompts; ergonomic singular/plural names and flag aliases may still be advertised by live help. For Confluence content, the canonical surface is twg confluence content <verb> (type auto-inferred from the positional ID, e.g. content get <ID>, content update <ID>); for spaces, use twg confluence space <verb>.

• Do not route normal work-data tasks through raw graph-query or debugging

surfaces just because the task says "graph" or "dependency." Use typed context, project, goal, Jira, Confluence, docs/search, PR, and visualization surfaces first. Use raw graph-query surfaces only when the user explicitly asks for that query language or typed commands cannot express the requested graph edge.

• Do not start an org or topic report by fanning out work query for dozens of

people. Resolve the scope and sample the most relevant anchors first.

• Do not stop at the wrapper YAML summary when the answer requires item names,

owners, status, URLs, or evidence. Inspect output_files.compact first; if it is absent or insufficient, use targeted jq on output_files.stdout.

References

• references/HELP.md - help discovery and exact-command schemas
• references/OUTPUT.md - output envelopes and large payload handling
• references/PRODUCTS.md - product caveats and mental model
• references/QUERY-LANGUAGES.md - JQL, CQL, AQL, and TQL
• ../twg-status-rollups/SKILL.md - status, leadership, project/goal, and appraisal readouts
• ../twg-context-discovery/SKILL.md - deep context, dependency maps, and graph visualization
• ../twg-engineering-work/SKILL.md - PR, review, repo, and engineering work recipes
• ../twg-operational-health/SKILL.md - handoff, reliability, assets, staffing, and operational health recipes

Help Discovery

TWG command grammar is discovered at runtime. Static skill docs explain strategy; twg help explains exact commands, arguments, flags, choices, defaults, and examples.

Primary Flow

Use twg help directly. Do not extract a help file path from stdout. With no arguments it emits the compact YAML command map for routing.

twg help
twg help jira
twg help jira workitem
twg help jira workitem link goal
twg help confluence page get
twg help describe "jira"
twg help describe "jira workitem"

twg help describe <namespace> emits compact YAML. The $ key lists executable child commands directly under that namespace; other keys are child namespaces. Use the returned next.describe commands to inspect exact executable contracts. Do not infer flags or arguments from namespace YAML.

kind: help_namespace
path: [jira]
depth: 2
next:
  describe:
    - "twg help describe \"jira workitem get\""
legend:
  $: executable child commands
tree:
  workitem:
    $: [create, get, query, update]
    link: {}

The default output for loose search is JSONL. The first record is type: "meta" and matching command records are type: "idx".

Use describe when you are about to inspect a namespace or execute an unfamiliar command. Exact executable commands return JSON by default:

twg help describe "jira workitem query"
twg help describe "confluence page get"
twg help describe "user search"

The output object in help describe is the first place to look before filtering JSON. If present, use its recommendedSummary, recommendedAgentFields, and agentFieldPresets instead of probing raw payloads with repeated jq calls:

twg help describe "context user"
twg context user <accountId> --output json --output-summary auto --agent-fields @compact

Only use jq after reading that contract and only against the bounded stdout file named by the summary envelope. Prefer the documented preset paths over trial-and-error filters.

Use rendered text help only when the user specifically asks for human help:

twg -o text help describe "jira workitem query"

Command Selection Rules

• If a command name is uncertain, run twg help <terms> first.
• If you need exact arguments, options, choices, defaults, or agent output

guidance, run twg help describe <path>. If the path is a namespace, follow its next.describe suggestions to an exact command.

• Follow the next commands returned by help; do not invent unsupported help

syntax.

• If the command grammar changed, trust live help over every skill reference.
• If help says a command requires a workspace, repo, page ID, account ID, ARI, or

project key, resolve that value before executing the command.

• Keep experimental commands out of parallel batches until help confirms the

shape.

• After search/Rovo returns candidates, hydrate selected candidates through the

exact executable get contract for that surface. Use query for filters; do not pass candidate keys to namespace commands.

Common Discovery Patterns

Compatibility Alias Guard

Compatibility aliases such as user-search, page, and issue may exist to rescue stale prompts. Do not use them in examples or plans. Prefer the canonical command path shown by live help.

Agent Output

The twg command is optimized for agents. For non-help commands it adds --mode agent, defaults missing output to --output json, and writes large payloads to files while keeping stdout compact.

The CLI core applies the same file-backed protection for direct structured agent calls such as twg --mode agent --output json work query. It only applies when the caller has not explicitly chosen --output-summary, --output-file, or --output text.

Envelope Shape

The wrapper usually prints a YAML summary like:

output_files:
  stdout: "$TMPDIR/twg/.../stdout.json"
  stdout_lines: 1050
  stdout_bytes: 39779
  compact: "$TMPDIR/twg/.../stdout.compact.json"
  compact_bytes: 1402
command: "jira workitem query"
resource_type: "jira:workitem"
agent_output:
  summary: "stats"
  view: "compact"
  fields: [data.issues.key, data.issues.summary, data.issues.status]
stdout_stats:
  top_level_keys: [apiVersion, command, data, meta]
  array_fields: 1
  max_array_length: 50
---END---

Small payloads may include stdout_inline with the full JSON payload. Large payloads include stdout_stats and sometimes stdout_shape.

Reading Rule

The YAML summary is a pointer, not the answer.

• If stdout_inline is present, you may answer from it.
• If output_files.compact is present, inspect that compact JSON first. It is

generated from the command's advertised output contract and is usually enough for routing, titles, owners, statuses, URLs, and dates.

• If stdout_stats or stdout_shape is present and output_files.compact is

absent or insufficient, filter output_files.stdout with targeted jq.

• For answers that require item names, URLs, owners, statuses, blockers, dates, or

evidence, read the JSON file even when the summary looks plausible.

`stdout_shape` samples are statistical, not exhaustive. The shape shows a merged schema with a small number of example string values per field — it is not a complete inventory. For context commands this matters most: external artifact links (Figma, GitHub, Google Docs, and other third-party app URLs) appear toward the tail of relationship arrays and are the entries most likely to be absent from stdout_shape samples. If the goal is relationship or URL discovery, always read output_files.stdout rather than treating shape samples as the full result. The related workflow guidance lives in twg-context-discovery/SKILL.md.

Output Budget Controls

Use these flags to keep agent stdout manageable:

twg <cmd> --output-summary stats
twg <cmd> --output-summary auto
twg <cmd> --agent-fields data.items.key,data.items.status

• --output-summary stats - smallest stdout; best for broad discovery.
• --output-summary auto - inline small results, summarize large results.
• --output-summary inline - force inline selected data; in agent mode very

large inline payloads are capped and fall back to file-backed summary output.

• --agent-fields - narrow the summary while preserving the full JSON file.

If output_files.compact is present, use it instead of probing the raw JSON. If field paths are unknown, run twg help describe "<exact command>" and use the advertised output view or jq snippet.

For structured JSON, inspect the top-level shape once and then write a targeted projection. Do not retry multiple incompatible .data.*, .result.*, or array-vs-object guesses. Combine related facts in one jq projection per output file instead of running repeated jq . or one-field probes.

When comparing many compact files, avoid a sequence of one-file wrappers such as jq '{Alice:.}' file. Use one combined projection with jq -n/slurp inputs, or read the compact summaries directly and only filter the few raw files that will change the answer.

When To Pass --output-file

Default: do not pass it. The wrapper already writes a full JSON payload and reports the path in output_files.stdout.

Pass --output-file only when stable filenames make a recipe easier, for example a parallel context batch:

twg jira workitem get PROJ-123 --output-file "$TMPDIR/PROJ-123.json"
twg context jira workitem PROJ-123 --output-file "$TMPDIR/ctx_PROJ-123.json"

Use $TMPDIR, not hard-coded /tmp, because agent sandboxes vary.

Large Payload Strategy

Examples:

jq '.data.edges[].node | {key, title, status, url}' "$OUT"
jq '.data.items[] | {name, owner, updatedAt}' "$OUT"

Do not use rg to inspect TWG JSON. It treats structured data like text and can re-expose hundreds of KiB of raw payload. Use jq with the paths from twg help describe "<exact command>".

Do not paste giant JSON into the final answer. Extract the facts and cite the artifact URLs or keys that support them.

Products And Surfaces

This reference explains durable product concepts and common routing traps. Use twg help for exact command syntax.

Discovery Surfaces

• resolve is for IDs, URLs, keys, exact names, and canonical entity lookup.
• search / rovo search is for fuzzy topics, nicknames, partial titles, and

cross-product discovery.

• Product-native commands are for final evidence, exact filters, mutations,

comments, page bodies, PR diffs, and product-specific semantics.

• context commands are for explicit graph relationships around a known entity.

They do not replace native get commands for source fields.

• Advanced raw graph-query commands are for debugging or gaps in typed surfaces,

not first-line discovery for normal status, dependency, or context tasks.

Use search results as candidates, not final facts. Hydrate important hits with native or context commands before synthesis.

Product Mental Model

Confluence Command Routing

Always use these commands for Confluence content operations. The content type is auto-inferred from the ID — you do NOT need --type on get/update/delete/ archive/unarchive/move. Lifecycle verbs take the content ID as a positional argument (e.g. update 12345, not update --id 12345).

Note: subresource verbs (labels, permissions, comments, tasks, versions) keep the --id <ID> flag for the parent content because a secondary entity ID (--comment-id, --task-id, --version) is also passed — named flags avoid positional ambiguity. Only the lifecycle verbs use positional <ID>.

Cross-Product Search Rules

• Start with resolve --query "<input>" when the input could already be a URL,

key, exact entity name, or account/person identifier.

• When the prompt already names the product family and provides a stable key,

URL, or ARI, go directly to that product's native get or query command. Use cross-product search only if the typed read fails or the prompt is fuzzy.

• If resolve is weak, use search "<query>" --limit 20 or app/type filters from

live help.

• For sensitive or people-heavy searches, narrow by app, type, time window,

contributor, assignee, owner, or space when available.

• Hydrate 1-3 top candidates. Avoid treating snippets as authoritative.

Context And Graph Rules

For a known entity, pair source fetch and graph context:

Default to summary detail. Escalate to full detail only for the central artifact. When drawing a graph, produce validated graph JSON and use the TWG visualization command discovered from help.

For dependencies, prefer typed context and product-native links over raw graph schema exploration. If a typed surface does not expose a relationship, state the coverage gap and use hydrated search/product candidates as inferred evidence.

Mutation Safety

• Read current state before updating, linking, unlinking, commenting, or deleting.
• Resolve both source and target to stable IDs/ARIs/keys before relationship writes.
• For Jira workitem create/update with custom or required fields, discover the

workitem field metadata first and use returned customfield_* IDs. Avoid display names in mutations unless metadata shows they are unambiguous. Do not provide the same key in both --field and --fields-json; --field values parse as JSON when valid, so quote JSON strings to force string IDs.

• For Jira custom field value readback, use `twg jira workitem get <KEY>

--field customfield_` or `--fields customfield_,summary`.

• Use --body-file for multiline page/comment bodies.
• For relationship mutations, report the source, target, relationship type, and

resulting key/URL.

• Do not mutate if the source entity identity is ambiguous.

Operational Caveats

• Bitbucket auth can fail independently of Atlassian/Jira auth.
• Some graph/context endpoints can be ACL-sensitive or slower than product-native

reads. Fall back to native surfaces when graph hydration fails.

• Recently viewed data is current-user scoped and time-limited.
• Meeting recordings and transcripts are not guaranteed to exist for every meeting.
• Assets joins often fail because of wrong schema/type/attribute assumptions; inspect

the schema first.

Query Languages

Use this reference for durable query semantics that help records cannot fully teach. Exact command names and flags still come from twg help.

Contents

• JQL - Jira Workitems
• CQL - Confluence
• AQL - Assets
• TQL / Planning Queries
• Native Query Vs Rovo Search

JQL - Jira Workitems

Use JQL when the target is definitely Jira and the user needs exact issue filters.

Common patterns:

assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC
project = PROJ AND statusCategory != Done ORDER BY priority DESC, updated DESC
project = PROJ AND issuetype in (Bug, Task) AND statusCategory != Done
parent = PROJ-123 ORDER BY updated DESC
key in (PROJ-1, PROJ-2, PROJ-3)
text ~ "customer name" AND statusCategory != Done
updated >= -14d ORDER BY updated DESC

Guidance:

• Prefer statusCategory != Done for open work when exact statuses vary.
• Use updated >= -14d or similar windows for recent activity.
• For "top items from a board" where the supplied board name is also a Jira

project key, start with project-key JQL and limit the output before hydrating individual issues. Use jira board backlog when exact board backlog order is required or a numeric board ID is supplied.

• Agile sprint functions can require board permissions; if denied, fall back to

date/status filters.

• For issue relationships and linked artifacts, use Jira context in addition to

JQL.

CQL - Confluence

Use CQL when the target is definitely Confluence and you need exact page/blog/task search.

Common patterns:

type = page AND title ~ "runbook"
type = page AND text ~ "customer name" ORDER BY lastmodified DESC
space = "ENG" AND type = page AND lastmodified >= now("-30d")
creator = "<account-id>" AND type = page ORDER BY created DESC
label = "strategy" AND type = page

Guidance:

• Prefer Rovo search for fuzzy discovery across products.
• Use CQL for Confluence-only constraints such as space, label, title, creator,

and modified time.

• Fetch full page body only for the selected central page.

AQL - Assets

Use AQL when querying Jira Assets/CMDB. Schema and attribute names are site-specific, so inspect the schema/type first.

Common patterns:

objectType = Laptops
objectType = Laptops AND "Calculated user" IS NOT EMPTY
objectSchema = "<schema>" AND objectType = Laptops AND "Calculated user" = "<handle>"
objectType = Services AND Status = Active

Laptop/person join guidance:

• Prefer discovered user-like attributes in this order when present:

Calculated user, Assigned to (user), User, Current Owner, Owner, Name.

• Once Calculated user exists on the target type, stop using broad display-name

filters as the main strategy.

• Classify failures as wrong schema/type, right type but wrong join field, or true no match.

TQL / Planning Queries

Use planning filters for Atlas goals, projects, and focus areas when exact fields matter.

Common patterns:

phase = in_progress AND status = off_track
phase = in_progress AND status = at_risk
name ~ "migration"
owner = "<account-id>"

Guidance:

• Prefer first-class flags when live help exposes them, such as scope, status,

role, owner, account ID, and updated-since.

• For goal status, compare goal health with linked project status and latest

status updates.

• For project reviews, lead with current state, owner, update recency, risks, and

linked goals.

Native Query Vs Rovo Search