diff --git a/.ai/skills/beads-jira-sync/SKILL.md b/.ai/skills/beads-jira-sync/SKILL.md new file mode 100644 index 000000000..d19b87b35 --- /dev/null +++ b/.ai/skills/beads-jira-sync/SKILL.md @@ -0,0 +1,62 @@ +--- +name: beads-jira-sync +description: >- + Syncs beads issues to the Jira DNA project with import-beads.js from the standalone + beads-jira-import repo. Covers dry-run, state-file backup, live sync, initiative labels on + epics, and bead/Jira key lookup. Use for the weekly beads to Jira sync, linking an epic to a + DNA initiative, or finding the Jira key for a bead id. +--- + + + +# Beads → Jira sync + +`import-beads.js` lives in the local `beads-jira-import` checkout (no remote; extracted from `adobe-mcp-servers` `src/corp-jira/scripts/`). Fix bugs in the TypeScript source and rebuild `dist/` before a live sync. Below, `$BJI` is that checkout (e.g. `~/Projects/beads-jira-import`). + +## Safety rules + +* **Never run `--help`.** Unknown flags are ignored and the script falls through to a LIVE sync. +* Safe modes: `--lookup `, `--dry-run`, `--discover`. Check the argument parser before using any other flag. +* Always `--dry-run` first, and back up `$BJI/scripts/beads-jira-map.json` before a live sync. +* Known issue: `--dry-run` can fail with ENOBUFS when the beads export exceeds 1 MiB (bead `cr71`). +* Known issue: nested epics with both a parent and an initiative label overwrite the same Parent Link field (bead `vd61`). + +## Weekly sync + +1. `bd dolt pull` so the export is current. +2. Back up state: `cp -f $BJI/scripts/beads-jira-map.json $BJI/scripts/beads-jira-map.json.bak`. +3. Dry run: `node $BJI/dist/scripts/import-beads.js --dry-run`. Review the preview with the user. +4. After approval, run live: `node $BJI/dist/scripts/import-beads.js`. +5. Report created/updated issues and any diagnostics. + +## Sprints + +The sync assigns sprints itself (`operations/sprints.ts`): closed beads go to the sprint containing their close date, `in_progress` beads go to the active sprint, open beads stay in the backlog. Jira rejects adds to closed sprints, so beads closed in an already-closed sprint are skipped. The board is the project's first scrum board, or `BEADS_JIRA_BOARD_ID`. Open and close sprints in Jira first so the active sprint is the current one. + +## Initiative linking + +New beads get `bd create --parent `. Work with no labeled ancestor epic never reaches an initiative or a status update. The sync prints the count of beads closed in the last 30 days with no initiative; reparent them with `bd update --parent `. Environment and personal-tooling tasks (MCP config, local TUI setup) are exempt. + +Only **Epics** link to Initiatives, through the `initiative:DNA-XXXX` label. One initiative per epic; omit the label if none fits. + +* New epic: `bd create -t epic -l initiative:DNA-XXXX ...` +* Existing epic: `bd label add initiative:DNA-XXXX` + +Initiatives: + +| Key | Theme | +| -------- | -------------------------------------- | +| DNA-1522 | Adaptive support per platform | +| DNA-1520 | Multi-platform governance | +| DNA-1516 | Metrics | +| DNA-1740 | Per-platform usage baselines | +| DNA-1741 | Connect Web/iOS/Android to design data | +| DNA-1747 | AI-authored Spectrum 2 code | +| DNA-1748 | Documentation | +| DNA-1796 | Design data authoring | + +## Lookup + +`node $BJI/dist/scripts/import-beads.js --lookup ` + +Ad hoc Jira work (not bulk sync) uses the `corp-jira` MCP server tools. diff --git a/.gitignore b/.gitignore index 5bfe3cf79..9e37b6ad3 100644 --- a/.gitignore +++ b/.gitignore @@ -180,3 +180,8 @@ tools/demo/videos/out/ *.db .beads-credential-key .beads/proxieddb/ +.beads.gate.lock + +# Local OpenCode setup +.opencode/ +opencode.jsonc diff --git a/AGENTS.md b/AGENTS.md index b5184cbf0..680613db0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,12 +93,12 @@ cp -rf source dest # NOT: cp -r source dest ## Jira Initiative Tracking -Beads sync to Jira (`DNA` project) with `import-beads.js` from the standalone `beads-jira-import` repo (local checkout, no remote; extracted from `adobe-mcp-servers` `src/corp-jira/scripts/`), run manually each week. Run `--dry-run` first and back up its `scripts/beads-jira-map.json` state file before a live sync. Only **Epics** link to Initiatives, through the `initiative:DNA-XXXX` label. +Beads sync to Jira (`DNA` project) weekly. Use the `beads-jira-sync` skill (`.ai/skills/beads-jira-sync/SKILL.md`) for the sync, initiative labels, the initiative list, and key lookups. -* New epic: `bd create -t epic -l initiative:DNA-XXXX ...`. Existing epic: `bd label add initiative:DNA-XXXX`. -* One initiative per epic. Leave the label off if no initiative fits. -* Initiatives: `DNA-1522` adaptive support per platform, `DNA-1520` multi-platform governance, `DNA-1516` metrics, `DNA-1740` per-platform usage baselines, `DNA-1741` connect Web/iOS/Android to design data, `DNA-1747` AI-authored Spectrum 2 code, `DNA-1748` documentation, `DNA-1796` design data authoring. -* Look up a Jira key or bead id: `node /dist/scripts/import-beads.js --lookup `. +* Only **Epics** link to Initiatives, through the `initiative:DNA-XXXX` label, one per epic. Create new beads with `--parent ` so work rolls up to an initiative; environment and personal-tooling tasks are exempt. The sync reports closed work with no initiative. +* **Sprints**: the sync assigns sprints itself. Closed beads go to the sprint containing their close date, `in_progress` beads go to the active sprint, and open beads stay in the backlog. Jira rejects adds to closed sprints, so work closed in an already-closed sprint is skipped. +* Sprints run two weeks on the `Data System Scrum Board` and are opened and closed by hand in Jira. Before a weekly sync, check that the active sprint covers today's date. If it is stale, close it and any sprints that have passed (oldest first), then start the current one, or the sync will file work into the wrong sprint. +* Completing a sprint sets its completion date to the day it was closed, so close stale sprints promptly. * Ad hoc Jira work uses the `corp-jira` MCP server tools. ## Code Intelligence (MCP) diff --git a/docs/hub-prototype/.gitignore b/docs/hub-prototype/.gitignore new file mode 100644 index 000000000..8bd1e31c0 --- /dev/null +++ b/docs/hub-prototype/.gitignore @@ -0,0 +1 @@ +.awesome/