twg

name	twg
description	Root operating skill for the TWG CLI. Use for Atlassian work-data tasks across Jira, Confluence, Bitbucket, goals/projects/focus areas, JSM, Assets, Admin, people, teams, org structure, docs, meetings, videos, search, graph context, and supported mutations. Exact command syntax must come from live `twg help`.

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

Area	Surfaces
Product-native	Jira, Confluence, Bitbucket, goals/projects/focus areas, JSM, Assets, Admin
People/org	users, teams, org-tree, collaborators
Cross-product	Rovo search, docs, meetings, videos, work activity
Graph/context	resolve, context, visualization
Workflows	twg-status-rollups, twg-context-discovery, twg-engineering-work, twg-operational-health

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