@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-issue/SKILL.md

@@ -0,0 +1,745 @@
+# /figma-issue — GitHub Issue Manager for Figma Components
+
+## Purpose
+
+Creates and manages GitHub Issues for Figma component implementations. Resolves component metadata from the registry, creates structured issues using the issue template format, adds them to the **Figma Components** Projects V2 board with custom fields, and provides sub-commands for ongoing issue management.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/figma-issue open <url>[,<url>] [--team <team>]` | Create GitHub issue |
+| `/figma-issue assign <#N>` | Assign issue to current user (GitHub + Jira if linked) |
+| `/figma-issue bind-jira <#N> <{jira.projectKey}-XXXXX>` | Link an existing Jira task (both directions) |
+| `/figma-issue phase <#N> <phase>` | Update phase on project board |
+| `/figma-issue block <#N> by <#M>` | Mark issue #N as blocked by #M |
+| `/figma-issue unblock <#N>` | Remove blocked status |
+| `/figma-issue close <#N>` | Close the issue |
+| `/figma-issue status [#N]` | Show issue status or list all open |
+
+---
+
+## Constants
+
+```
+REPO_ROOT       = git repo root (auto-detect)
+REGISTRY_UTIL   = ${REPO_ROOT}/{repos.common.path}/.build/debug/FigmaRegistryUtility
+GH_REPO         = {github.componentsRepo}
+GH_ORG          = {github.org}
+PROJECT_ID      = {github.projectV2Id}
+JIRA_BASE_URL   = {jira.baseUrl}
+JIRA_PROJECT    = {jira.projectKey}
+JIRA_LABELS     = ["redesign_ios_ui_component", "MobRedesign"]
+JIRA_ISSUE_TYPE = Task
+```
+
+### Jira Authentication
+
+Jira token is stored in macOS Keychain under service name `JIRA_TOKEN`:
+
+```bash
+JIRA_TOKEN=$(security find-generic-password -a "$USER" -s "JIRA_TOKEN" -w 2>/dev/null)
+```
+
+If not found, prompt the user to add it:
+```bash
+security add-generic-password -a "$USER" -s "JIRA_TOKEN" -w "<PAT>"
+```
+
+### Project Field IDs
+
+```
+STATUS_FIELD    = {github.projectV2Fields.status}
+  Todo          = 25f3e7a3
+  In Develop    = bc6c45f7
+  In Review     = bdb0d8ef
+  Bugfix        = e46fa72d
+  Done          = 6275b69e
+  Blocked       = 95949fd8
+  Stale         = 457a1e74
+
+PHASE_FIELD     = {github.projectV2Fields.phase}
+  Implementation = 0577dcda
+  Testing        = 106b64ce
+  Code Connect   = 5384b1e1
+  Documentation  = 7307fb8f
+
+FIGMA_PAGE_FIELD = {github.projectV2Fields.figmaPage}
+  Home Screen    = 72d24832
+  Booker         = a143357e
+  Check-in       = 5c204dd7
+  Modals         = 72983b95
+  Cards          = e8dedeee
+  Buttons        = f57b9f30
+  Navigation Bar = 54bfd163
+  Other          = 62a5ecbe
+
+JIRA_FIELD      = {github.projectV2Fields.jira}
+```
+
+### Figma Page Mapping
+
+Map the registry `pageName` to the project board's Figma Page option. Use substring matching:
+
+| pageName contains | Option ID |
+|---|---|
+| `Home` | `72d24832` |
+| `Booker` | `a143357e` |
+| `Check-in`, `Boarding Pass` | `5c204dd7` |
+| `Modal` | `72983b95` |
+| `Card` | `e8dedeee` |
+| `Button` | `f57b9f30` |
+| `Navigation` | `54bfd163` |
+| *(everything else)* | `62a5ecbe` (Other) |
+
+---
+
+## Command: `open <url>[,<url>,...]`
+
+### STEP 0 — Parse Input
+
+1. Extract all Figma URLs from `$ARGUMENTS` (comma-separated or space-separated).
+2. For each URL, extract `node-id` query parameter. Keep as-is (e.g., `2251-15872`).
+3. Deduplicate by `node-id` — if the same node-id appears multiple times, process it only once.
+4. Print: "Found N unique Figma component(s) to process."
+
+**For each component, run STEPs 1-6 sequentially.** The specs prompt (STEP 2.5) is asked once per component.
+
+### STEP 1 — Registry Lookup
+
+```bash
+cd ${REPO_ROOT}/{repos.common.path}
+.build/debug/FigmaRegistryUtility lookup --node-id <NODE_ID>
+```
+
+Collect from JSON output:
+- `name` → Registry name (e.g., `Modals/Title`)
+- `suggestedComponentName` → PascalCase name (e.g., `ModalsTitle`)
+- `pageName` → Figma page name (e.g., `❖ Modals`)
+- `suggestedArtifactPath` → Artifact path
+- `suggestedComponentLocation` → Component location
+
+If lookup fails, mark as **unregistered**.
+
+### STEP 1.5 — Dependency Detection
+
+Uses the **exact same algorithm** as `confluence-component-status-upload.py` → `readiness()`:
+1. Build unified `name → nodeId` lookup from catalog + registry + graph
+2. Resolve sub-component names to nodeIds
+3. Check each resolved nodeId for `codeConnect.ios` and `skip`
+4. Unresolved names (nodeId = None) are NOT blockers (same as `all_comps.get(sub_nid)` returning None)
+
+```bash
+COMMON_PATH="${REPO_ROOT}/{repos.common.path}"
+FIGMA_DIR="${COMMON_PATH}/Shared/Figma"
+```
+
+#### 1.5a. Compute readiness (single Python script)
+
+Run the following as a single Python block. It replicates `build_component_index()` + `readiness()` from `confluence-component-status-upload.py`:
+
+```bash
+cd ${REPO_ROOT}
+python3 -c "
+import json, os, glob
+
+FIGMA_DIR = '${FIGMA_DIR}'
+NODE_ID = '<NODE_ID>'
+
+# --- 1. Load all Components/*.json into dict keyed by nodeId ---
+components = {}
+comp_dir = os.path.join(FIGMA_DIR, 'Components')
+for f in glob.glob(os.path.join(comp_dir, '*.json')):
+    with open(f) as fh:
+        reg = json.load(fh)
+    nid = reg.get('nodeId', os.path.basename(f)[:-5].replace('-', ':'))
+    components[nid] = reg
+
+# --- 2. Build name → nodeId lookup (same as confluence-component-status-upload.py lines 143-164) ---
+name_to_nid = {}
+for nid, c in components.items():
+    cn = c.get('componentName', {})
+    ios_name = cn.get('ios', '') if isinstance(cn, dict) else cn or ''
+    if ios_name:
+        name_to_nid[ios_name] = nid
+        # Strip Image. prefix for graph name matching: Image.caretRight → caretRight → CaretRight
+        if '.' in ios_name:
+            suffix = ios_name.split('.', 1)[1]
+            if suffix not in name_to_nid:
+                name_to_nid[suffix] = nid
+            upper = suffix[0:1].upper() + suffix[1:]
+            if upper not in name_to_nid:
+                name_to_nid[upper] = nid
+
+# Also add catalog names from component-catalog.json if available
+cat_path = os.path.join(FIGMA_DIR, 'Generated', 'component-catalog.json')
+if os.path.isfile(cat_path):
+    with open(cat_path) as f:
+        catalog = json.load(f)
+    for file_entry in catalog.get('files', []):
+        for page in file_entry.get('pages', []):
+            for comp in page.get('components', []):
+                cn = comp.get('name', '')
+                fn = comp.get('figmaName', '')
+                cnid = comp.get('nodeId', '')
+                if cn: name_to_nid[cn] = cnid
+                if fn and fn not in name_to_nid: name_to_nid[fn] = cnid
+
+# --- 3. Load graph, get sub-components for this node ---
+graph_path = os.path.join(FIGMA_DIR, 'sub-component-graph.json')
+with open(graph_path) as f:
+    graph = json.load(f).get('graph', {})
+entry = graph.get(NODE_ID, {})
+sub_names = entry.get('subComponents', [])
+
+if not sub_names:
+    print(json.dumps({'status': 'no_deps', 'subComponents': []}))
+else:
+    # --- 4. Resolve names → nodeIds, then compute readiness per sub-component ---
+    results = []
+    for sname in sub_names:
+        sub_nid = name_to_nid.get(sname)
+        if not sub_nid:
+            # Unresolved — not in any registry/catalog (same as all_comps.get() → None → not a blocker)
+            results.append({'name': sname, 'nodeId': None, 'status': 'unresolved'})
+            continue
+        sc = components.get(sub_nid)
+        if not sc:
+            results.append({'name': sname, 'nodeId': sub_nid, 'status': 'unresolved'})
+            continue
+        if sc.get('skip', False):
+            results.append({'name': sname, 'nodeId': sub_nid, 'status': 'skipped'})
+            continue
+
+        # NEW: status.ios.implemented is the canonical source of truth after
+        # the architecture-update migration. Fall back to legacy signals for
+        # components that haven't been backfilled yet.
+        ios_status = sc.get('status', {}).get('ios', {})
+        impl_value = ios_status.get('implemented', {}).get('value', False)
+
+        if impl_value:
+            results.append({'name': sname, 'nodeId': sub_nid, 'status': 'implemented'})
+            continue
+
+        # Legacy fallback 1: top-level codeConnect.ios (pre-architecture-update)
+        if sc.get('codeConnect', {}).get('ios', False):
+            results.append({'name': sname, 'nodeId': sub_nid, 'status': 'implemented'})
+            continue
+
+        # Legacy fallback 2: does a Swift file with this component name exist?
+        # Catches components implemented in code but never backfilled. Delete
+        # this fallback after backfill-status.py has been run and the legacy
+        # codeConnect field is no longer the primary source.
+        comp_name = (sc.get('componentName') or {}).get('ios')
+        sources_dir = os.environ.get('UICOMPONENTS_SOURCES', '')
+        if comp_name and sources_dir and os.path.isdir(sources_dir):
+            pattern = os.path.join(sources_dir, '**', comp_name + '.swift')
+            if glob.glob(pattern, recursive=True):
+                results.append({'name': sname, 'nodeId': sub_nid, 'status': 'implemented'})
+                continue
+
+        results.append({'name': sname, 'nodeId': sub_nid, 'status': 'not_implemented'})
+    print(json.dumps({'status': 'checked', 'subComponents': results}))
+"
+```
+
+Parse the JSON output. Only `not_implemented` entries are blockers — `implemented`, `skipped`, and `unresolved` (not in any registry) are NOT blockers.
+
+**Readiness precedence (architecture-update):**
+1. `status.ios.implemented.value` (new canonical field, set by `phase4-finalize.py`)
+2. Legacy `codeConnect.ios` (pre-architecture-update components)
+3. Swift-file-exists check (final fallback for un-backfilled components;
+   requires `UICOMPONENTS_SOURCES` env var or falls through as not_implemented)
+
+Delete fallbacks 2 and 3 after `backfill-status.py` has been run and all
+active components have been re-run through the pipeline at least once.
+
+#### 1.5b. Find existing issues for blockers
+
+For each `not_implemented` sub-component:
+
+```bash
+gh issue list --repo ${GH_REPO} --state open --label component \
+  --search "<SubComponentName>" --json number,title --jq '.[0]'
+```
+
+Collect: `BLOCKING_DEPS` = list of `{name, nodeId, issueNumber (or null)}` — only `not_implemented` entries.
+
+#### 1.5c. Report
+
+```
+Dependencies (from sub-component-graph.json):
+  - <SubName> → ✅ implemented
+  - <SubName> → ⏭️ skipped
+  - <SubName> → unresolved (not in registry)
+  - <SubName> → #N (not implemented)
+  - <SubName> → ❌ not implemented, no issue
+
+This issue will be auto-blocked after creation.
+```
+
+If zero `not_implemented` → **no blockers**, do NOT auto-block.
+
+Store `BLOCKING_DEPS` for use in STEP 3.5.
+
+### STEP 2 — Duplicate Check
+
+```bash
+gh issue list --repo ${GH_REPO} --state open --search "node-id=<NODE_ID>" --json number,title,url
+```
+
+If a match is found, print warning and stop:
+"Issue already exists: #N — <title> (<url>)"
+
+### STEP 2.5 — Specs & Acceptance Criteria
+
+Present the component info and **STOP. Do not proceed to STEP 3.** Wait for the user's next message.
+
+**Print exactly this and nothing else:**
+
+```
+-------------------------------------------
+  Component:  <SuggestedComponentName>
+  Registry:   <RegistryName>
+  Page:       <PageName>
+  Figma:      <FIGMA_URL>
+-------------------------------------------
+
+Write your acceptance criteria and specs below.
+You can include:
+- Acceptance criteria (checkbox list)
+- Design specs (variants, states, animations)
+- Dependencies (nested components, tokens)
+- Edge cases or constraints
+
+Type "skip" to create without specs.
+```
+
+**STOP HERE. The user's next message is the specs content.**
+
+When the user responds:
+- If the response is `skip` (case-insensitive): set `SPECS = ""`, proceed to STEP 3.
+- Otherwise: the user's message is the specs input. You MAY read referenced files to gather context and understand the user's intent better — this helps write clearer specs. Then rewrite the user's input into clean, actionable acceptance criteria (checkbox list) that another AI can easily follow when it fetches this issue for implementation. Do NOT implement anything — this skill only creates issues, not code. Then proceed to team selection / STEP 3.
+
+If `SPECS` is not empty, include it in the issue body under `### Acceptance Criteria` (see STEP 3 body template).
+
+### STEP 3 — Create GitHub Issue
+
+**Title:**
+```
+feat: <TEAM_SHORT> Implement <SuggestedComponentName>
+```
+
+Where `<TEAM_SHORT>` is mapped from the team label:
+
+| Label | Short |
+|---|---|
+| `team:core` | `core` |
+| `team:shopping-and-payment` | `shopping` |
+| `team:add-services` | `add-services` |
+| `team:miles-and-smiles` | `miles` |
+| `team:post-ops-irrops` | `post-ops` |
+
+If unregistered: `feat: <TEAM_SHORT> Implement component (node-id: <NODE_ID>)`
+
+**Body** — must match the issue template field headers exactly:
+
+```markdown
+### Figma URL
+
+<FIGMA_URL>
+
+### Node ID
+
+<NODE_ID>
+
+### Registry Name
+
+<REGISTRY_NAME>
+
+### Component Name (PascalCase)
+
+<SUGGESTED_COMPONENT_NAME>
+
+### Figma Page
+
+<PAGE_NAME>
+
+### Jira Issue
+
+_No response_
+
+### Progress
+
+| Flag | State |
+|---|---|
+| Implementation | ⚪ |
+| Testing        | ⚪ |
+| Code Connect   | ⚪ |
+| Wiki           | ⚪ |
+
+<!--
+State legend:
+  🟢 green  — flag is set and validated against the current implementation version
+  🟡 yellow — flag was validated against an older impl version (or Figma moved ahead, for implemented)
+  ⚪ gray   — flag is not set
+
+The Progress table is rewritten automatically by update-issue-from-registry.py
+on every phase finalize. Do not hand-edit this section; edits will be
+overwritten on the next pipeline run.
+-->
+
+
+### Acceptance Criteria
+
+<SPECS or "_No response_" if empty>
+
+### Pull Requests
+
+- **common:**
+- **uicomponents:**
+
+### Notes
+
+_No response_
+```
+
+### Team Label Mapping
+
+If `--team` was provided, map to a label:
+
+| Argument (case-insensitive) | Label |
+|---|---|
+| `core` | `team:core` |
+| `post-ops-irrops`, `post-ops`, `irrops` | `team:post-ops-irrops` |
+| `add-services`, `additional-services` | `team:add-services` |
+| `miles-and-smiles`, `miles`, `m&s` | `team:miles-and-smiles` |
+| `shopping-and-payment`, `shopping`, `payment` | `team:shopping-and-payment` |
+
+If `--team` was NOT provided, ask the user which team before creating the issue. Print and STOP:
+
+```
+Which team?
+1. Core
+2. Post-Ops & Irrops
+3. Additional Services
+4. Miles & Smiles
+5. Shopping & Payment
+```
+
+Wait for the user's response (number or name), then map to the label.
+
+```bash
+gh issue create \
+  --repo ${GH_REPO} \
+  --title "<TITLE>" \
+  --label "component" \
+  --label "redesign" \
+  --label "<TEAM_LABEL>" \
+  --body "<BODY>"
+```
+
+**No `phase:*` label on creation.** The per-flag labels
+(`impl:green`, `impl:yellow`, `test:green`, etc.) are applied
+automatically by `update-issue-from-registry.py` once a phase finalize
+script has populated `status` in the registry. On creation the issue
+has zero flag labels (all gray) — that's the correct initial state for
+a component nobody has implemented yet.
+
+Legacy `phase:*` labels are stripped from existing issues on any sync;
+new issues never get them.
+
+Capture the issue number and URL from the output.
+
+### STEP 3.5 — Auto-Block (if dependencies detected)
+
+If `BLOCKING_DEPS` from STEP 1.5 has any `not_implemented` sub-components:
+
+1. Add `blocked` label:
+```bash
+gh issue edit <N> --repo ${GH_REPO} --add-label "blocked"
+```
+
+2. Comment with blocking info:
+```bash
+gh issue comment <N> --repo ${GH_REPO} --body "**Auto-blocked** — unimplemented sub-components (from sub-component-graph.json):
+- <SubName> → #M
+- <SubName> → no issue
+
+Will be auto-unblocked when all dependencies are implemented."
+```
+
+The issue will be auto-unblocked by `/figma-iteration-commit` STEP 5 when blocking components get implemented.
+
+### STEP 4 — Add to Project Board
+
+#### 4a. Add issue to project
+
+```bash
+# Get issue node ID
+ISSUE_NODE_ID=$(gh api graphql -f query='{ repository(owner: "{github.org}", name: "{project.slug}-components") { issue(number: <ISSUE_NUMBER>) { id } } }' --jq '.data.repository.issue.id')
+
+# Add to project
+ITEM_ID=$(gh api graphql -f query='mutation { addProjectV2ItemById(input: { projectId: "{github.projectV2Id}", contentId: "'"$ISSUE_NODE_ID"'" }) { item { id } } }' --jq '.data.addProjectV2ItemById.item.id')
+```
+
+#### 4b. Set Status = Todo
+
+```bash
+gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "{github.projectV2Id}", itemId: "'"$ITEM_ID"'", fieldId: "{github.projectV2Fields.status}", value: { singleSelectOptionId: "25f3e7a3" } }) { projectV2Item { id } } }'
+```
+
+#### 4c. Set Phase = Implementation
+
+```bash
+gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "{github.projectV2Id}", itemId: "'"$ITEM_ID"'", fieldId: "{github.projectV2Fields.phase}", value: { singleSelectOptionId: "0577dcda" } }) { projectV2Item { id } } }'
+```
+
+#### 4d. Set Figma Page
+
+Map `pageName` using the Figma Page Mapping table, then:
+
+```bash
+gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "{github.projectV2Id}", itemId: "'"$ITEM_ID"'", fieldId: "{github.projectV2Fields.figmaPage}", value: { singleSelectOptionId: "<MAPPED_PAGE_OPTION_ID>" } }) { projectV2Item { id } } }'
+```
+
+### STEP 5 — Summary
+
+Print:
+
+```markdown
+Issue created:
+
+| Field | Value |
+|-------|-------|
+| Issue | [#N](url) |
+| Component | <SuggestedComponentName> |
+| Registry | <RegistryName> |
+| Page | <PageName> |
+| Phase | Implementation |
+| Status | Todo |
+| Assignee | unassigned |
+```
+
+---
+
+## Command: `assign <#N>`
+
+Assign the issue to the current GitHub user. If a Jira task is linked, also assign it.
+
+### STEP 1 — Assign GitHub Issue
+
+```bash
+gh issue edit <N> --repo ${GH_REPO} --add-assignee @me
+```
+
+### STEP 2 — Assign Jira (if linked)
+
+Read the issue body and check the `### Jira Issue` section for a linked key.
+
+If a Jira key is found (not `_No response_`):
+
+```bash
+JIRA_TOKEN=$(security find-generic-password -a "$USER" -s "JIRA_TOKEN" -w 2>/dev/null)
+USERNAME=$(curl -s "${JIRA_BASE_URL}/rest/api/2/myself" \
+  -H "Authorization: Bearer ${JIRA_TOKEN}" | python3 -c "import sys,json; print(json.load(sys.stdin)['name'])")
+
+curl -s -X PUT "${JIRA_BASE_URL}/rest/api/2/issue/<JIRA_KEY>/assignee" \
+  -H "Authorization: Bearer ${JIRA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"name\": \"${USERNAME}\"}"
+```
+
+If Jira token not found or VPN unreachable, skip with warning.
+
+Print: "Issue #N assigned to you." (+ "Jira <KEY> assigned." if applicable)
+
+---
+
+## Command: `bind-jira <#N> <{jira.projectKey}-XXXXX>`
+
+Link an existing Jira task to the GitHub issue (both directions).
+
+### STEP 1 — Update GitHub Issue Body
+
+1. Read current issue body:
+```bash
+BODY=$(gh issue view <N> --repo ${GH_REPO} --json body --jq '.body')
+```
+
+2. Replace the Jira section:
+   - Find `### Jira Issue` section
+   - Replace the line after it (`_No response_` or existing key) with:
+   ```
+   [<JIRA_KEY>]({jira.baseUrl}/browse/<JIRA_KEY>)
+   ```
+
+3. Update:
+```bash
+gh issue edit <N> --repo ${GH_REPO} --body "<UPDATED_BODY>"
+```
+
+### STEP 2 — Update Project Board Jira Field
+
+```bash
+# Get item ID from project
+ITEM_ID=$(gh api graphql -f query='{ node(id: "{github.projectV2Id}") { ... on ProjectV2 { items(first: 100) { nodes { id content { ... on Issue { number } } } } } } }' --jq '.data.node.items.nodes[] | select(.content.number == <N>) | .id')
+
+# Set Jira field
+gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "{github.projectV2Id}", itemId: "'"$ITEM_ID"'", fieldId: "{github.projectV2Fields.jira}", value: { text: "<JIRA_KEY>" } }) { projectV2Item { id } } }'
+```
+
+### STEP 3 — Update Jira Description with GitHub Link
+
+```bash
+JIRA_TOKEN=$(security find-generic-password -a "$USER" -s "JIRA_TOKEN" -w 2>/dev/null)
+
+# Get current Jira description
+JIRA_DESC=$(curl -s "${JIRA_BASE_URL}/rest/api/2/issue/<JIRA_KEY>?fields=description" \
+  -H "Authorization: Bearer ${JIRA_TOKEN}" | python3 -c "import sys,json; print(json.load(sys.stdin)['fields'].get('description','') or '')")
+
+# Append GitHub issue link if not already present
+GITHUB_URL=$(gh issue view <N> --repo ${GH_REPO} --json url --jq '.url')
+
+curl -s -X PUT "${JIRA_BASE_URL}/rest/api/2/issue/<JIRA_KEY>" \
+  -H "Authorization: Bearer ${JIRA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"fields\": {\"description\": \"${JIRA_DESC}\n\nh3. GitHub Issue\n${GITHUB_URL}\"}}"
+```
+
+If Jira token is not found, skip this step with a warning.
+
+Print: "Issue #N linked to [JIRA_KEY]({jira.baseUrl}/browse/JIRA_KEY)"
+
+---
+
+## Command: `phase <#N> <phase>` — **DEPRECATED**
+
+This command is deprecated as of the architecture-update. Phase state
+is now tracked per-flag in the component registry
+(`status.ios.{implemented,tested,codeConnect,wiki}`), not as a single
+enum. The `phase:*` labels are no longer used — they're replaced by
+per-flag `impl:green`/`impl:yellow`/`test:green`/etc. labels, which are
+applied automatically by `update-issue-from-registry.py` after every
+phase finalize script writes the registry.
+
+If you run this command:
+
+```
+/figma-issue phase 42 testing
+```
+
+Print this message and stop (do NOT touch the issue):
+
+```
+/figma-issue phase is deprecated. Phase state is now computed from the
+component registry (Shared/Figma/Components/{nodeId}.json → status.ios).
+
+To update an issue's labels and Progress table from the current
+registry state, run:
+
+  python3 .instructions/figma/figma-to-swiftui/scripts/update-issue-from-registry.py \
+      --node-id <NODE_ID>
+
+To bulk-sync all backfilled issues:
+
+  python3 .instructions/figma/figma-to-swiftui/scripts/bulk-sync-issues.py
+```
+
+Do not update the Projects V2 Phase field from this command anymore.
+If you need to change Projects V2 field state, do it manually via
+`gh api graphql` or the GitHub UI.
+
+---
+
+## Command: `block <#N> by <#M>`
+
+Mark issue #N as blocked by issue #M.
+
+### Steps
+
+1. Add `blocked` label to issue #N:
+```bash
+gh issue edit <N> --repo ${GH_REPO} --add-label "blocked"
+```
+
+2. Add a comment to issue #N:
+```bash
+gh issue comment <N> --repo ${GH_REPO} --body "Blocked by #<M>"
+```
+
+3. Set Status = "Todo" on project board (blocked issues shouldn't be "In Progress").
+
+Print: "Issue #N is now blocked by #M."
+
+---
+
+## Command: `unblock <#N>`
+
+Remove blocked status from issue #N.
+
+### Steps
+
+1. Remove `blocked` label:
+```bash
+gh issue edit <N> --repo ${GH_REPO} --remove-label "blocked"
+```
+
+2. Add a comment:
+```bash
+gh issue comment <N> --repo ${GH_REPO} --body "Unblocked."
+```
+
+Print: "Issue #N unblocked."
+
+---
+
+## Command: `close <#N>`
+
+1. Check all progress checkboxes in the issue body.
+2. Set Status = Done on project board.
+3. Close the issue:
+```bash
+gh issue close <N> --repo ${GH_REPO}
+```
+
+Print: "Issue #N closed."
+
+---
+
+## Command: `status [#N]`
+
+### With issue number — show single issue
+
+```bash
+gh issue view <N> --repo ${GH_REPO} --json number,title,state,assignees,labels,body
+```
+
+Also fetch project fields:
+```bash
+gh api graphql -f query='{ node(id: "{github.projectV2Id}") { ... on ProjectV2 { items(first: 100) { nodes { id fieldValues(first: 10) { nodes { ... on ProjectV2ItemFieldSingleSelectValue { field { ... on ProjectV2SingleSelectField { name } } name } ... on ProjectV2ItemFieldTextValue { field { ... on ProjectV2Field { name } } text } } } content { ... on Issue { number } } } } } } }' --jq '.data.node.items.nodes[] | select(.content.number == <N>)'
+```
+
+Print a formatted summary with issue details + board fields.
+
+### Without issue number — list all open
+
+```bash
+gh issue list --repo ${GH_REPO} --state open --label component --json number,title,assignees --jq '.[] | "| #\(.number) | \(.title) | \(.assignees | map(.login) | join(", ")) |"'
+```
+
+Print as a table.
+
+---
+
+## Error Handling
+
+- **FigmaRegistryUtility not built**: Run `cd ${REPO_ROOT}/{repos.common.path} && swift build --product FigmaRegistryUtility`.
+- **Issue not found**: Print error and stop.
+- **Invalid phase**: Print valid options: `implementation`, `testing`, `code-connect`, `documentation`.
+- **Duplicate issue**: Print existing issue link and stop — do not create.
+- **GraphQL errors**: Print the error message from the API response.
+- **Jira token not found**: Prompt user to add to keychain: `security add-generic-password -a "$USER" -s "JIRA_TOKEN" -w "YOUR_PAT"`.
+- **Jira API error (401/403)**: Token expired or invalid — prompt user to update keychain.
+- **Jira API error (404)**: Wrong issue key — print error and continue.
+- **Jira VPN not reachable**: Print warning, skip Jira steps, continue with GitHub-only operations.