nga-skills

Structured AI development workflow skills - install once, use everywhere.

Supports Claude Code, Cursor, and GitHub Copilot.

Quick Start

# Interactive install — detects which assistants are configured in your workspace
npx nga-skills-factory

# Install for a specific assistant
npx nga-skills-factory install --claude
npx nga-skills-factory install --cursor
npx nga-skills-factory install --copilot

# Install for all assistants at once
npx nga-skills-factory install --all

# See all available skills
npx nga-skills-factory list

# Overwrite existing files
npx nga-skills-factory install --claude --force

# Install into a specific directory (default: current directory)
npx nga-skills-factory install --claude --dir /path/to/project

# Re-fetch the Helix UI component docs into already-installed assistants
npx nga-skills-factory refresh-helix-docs --all

Helix UI is opt-in. During an interactive install you'll be asked whether you want the Helix Web Components UI support. If you say yes, the installer fetches the canonical component docs from Bitbucket (ifs-pd/ifs-ux-helixwebcomponents) and installs the /nga-helix-ui skill. This step needs Bitbucket credentials — see Helix UI Support below.

What Gets Installed

| Skill | Type | Claude | Cursor | Copilot | | ------------------- | ------------- | ------ | ------ | ------- | | /nga-kairos-setup | Slash command | ✓ | ✓ | ✓ | | /nga-kairos-update | Slash command | ✓ | ✓ | ✓ | | /nga-spec-writer | Slash command | ✓ | ✓ | ✓ | | /nga-spec-normalizer | Slash command | ✓ | ✓ | ✓ | | /nga-gap-analysis | Slash command | ✓ | ✓ | ✓ | | /nga-brainstorm | Slash command | ✓ | ✓ | ✓ | | /nga-write-prd | Slash command | ✓ | ✓ | ✓ | | /nga-architect | Slash command | ✓ | ✓ | ✓ | | /nga-verify-architecture | Slash command | ✓ | ✓ | ✓ | | /nga-epic-planner | Slash command | ✓ | ✓ | ✓ | | /nga-implement | Slash command | ✓ | ✓ | ✓ | | /nga-verify-kairos | Slash command | ✓ | ✓ | ✓ | | /nga-review-pr | Slash command | ✓ | ✓ | ✓ | | /nga-handover | Slash command | ✓ | ✓ | ✓ | | /nga-pickup | Slash command | ✓ | ✓ | ✓ | | /nga-helix-ui (opt-in) | Slash command | ✓ | ✓ | ✓ |

/nga-helix-ui is only installed when you opt into Helix UI support during install (or run refresh-helix-docs). All other skills — including /nga-kairos-setup and its bundled scripts — install by default for every selected assistant.

Install Locations

| Assistant | Files land in | | -------------- | --------------------------------- | | Claude Code | .claude/commands/ | | Cursor | .cursor/rules/ | | GitHub Copilot | .github/copilot-instructions.md |

When Helix UI support is enabled, the fetched component docs are also written to <assistant-base>/docs/helix-ui/ (.claude/docs/helix-ui/, .cursor/docs/helix-ui/, .github/docs/helix-ui/).

Some skills ship runnable helper scripts, bundled the same way the SPEC.md template is. They land in each selected assistant's scripts directory (.claude/scripts/, .cursor/scripts/, .github/scripts/):

• kairos-detect.sh (/nga-kairos-setup) — read-only detection of an existing Kairos install (drives the idempotency gate).
• kairos-setup.sh (/nga-kairos-setup) — the official QuickStart SSH/CLI bootstrap (interactive).
• kairos-cluster-create.sh (/nga-kairos-setup) — creates the local cluster, asking first if one already exists (interactive).
• nsf-handover-new.sh / .ps1 (/nga-handover) — self-contained scaffolder for an append-only .handover/ entry (git-derived frontmatter + embedded template; writes to <repo>/.handover/entries/<yyyy-MM>/). No external template file needed.
• nsf-handover-pickup.sh / .ps1 (/nga-pickup) — cross-branch handover discovery (git log, 96h default lookback) + reader-first briefing, filtered to entries addressed to the reader.
• nsf-handover-check.sh / .ps1 (/nga-handover) — linter: filename, frontmatter, enums, the nine exact headings, append-only, leftover AUTHOR CONFIRM markers, author-slug drift, plus a gap report.
• pr-review-fetch.js (/nga-review-pr) — self-contained Node (core modules only) helper that fetches a Bitbucket Cloud PR's metadata + unified diff and posts inline/summary comments. Authenticates with the stored Bitbucket token — Basic email:token for an Atlassian API token, or Bearer for a Bitbucket access token, chosen automatically with fallback — read from ~/.nga-skills-factory/bitbucket.json (the apiToken field) or BITBUCKET_API_TOKEN. On a missing/invalid token it returns a structured no-credentials / auth signal so the skill can prompt for a token and retry.

Output Artifacts

All skills write their output to _nsf_output/ in your project root:

| Skill | Output file(s) | | ------------------- | ---------------------------------------------------------------------------------------------------------------- | | /nga-kairos-setup | No file — runs the Kairos QuickStart setup (SSH/CLI install + ./kairos cluster create) against the live machine | | /nga-kairos-update | No file — updates an existing Kairos CLI/env (git pull + ./kairos + kairos update + certificate trust) against the live machine | | /nga-spec-writer | _nsf_output/docs/raw-storming.md, context-map.md, domain-brief.md, master-spec.md, spec-<context>.md × N | | /nga-spec-normalizer | _nsf_output/CBI.md | | /nga-gap-analysis | _nsf_output/CBI.md (enriched in place — resolved answers + inline gap annotations) | | /nga-brainstorm | _nsf_output/BRAINSTORM.md (+ _nsf_output/REFINED_CBI.md when using the full pipeline) | | /nga-write-prd | _nsf_output/master-prd.md, prd-<context>.md × N | | /nga-architect | _nsf_output/master-architecture.md + architecture-<context>.md × N | | /nga-verify-architecture | Appends ## Verification — verify-architecture section to _nsf_output/master-architecture.md | | /nga-epic-planner | _nsf_output/epic-<context>.md × N | | /nga-implement | _nsf_output/IMPLEMENTATION_LOG.md; on first run freezes the planning artifacts and creates _nsf_output/CHANGED_LOG.md | | /nga-verify-kairos | Appends ## Verification — verify-kairos section to _nsf_output/IMPLEMENTATION_LOG.md | | /nga-review-pr | _nsf_output/PR_REVIEW.md (full findings + verdict) and _nsf_output/pr-<id>.diff / pr-<id>-meta.json (fetched inputs). Optionally posts inline + summary comments to the Bitbucket PR on per-finding confirmation. | | /nga-handover | .handover/entries/<yyyy-MM>/<id>.md — an append-only handover entry committed on the working branch (not _nsf_output/; context travels with the code). | | /nga-pickup | No file — reads .handover/entries/ across branches and briefs the incoming shift (read-only). | | /nga-helix-ui | Ready-to-use UI code, plus a table showing which doc each component came from. Reads the docs from <assistant>/docs/helix-ui/. |

Frozen artifacts & CHANGED_LOG.md

/nga-implement is the pipeline's freeze point. The first time it runs it locks the six upstream planning artifacts — docs/master-spec.md, CBI.md, REFINED_CBI.md, BRAINSTORM.md, master-prd.md, and master-architecture.md — and creates _nsf_output/CHANGED_LOG.md. After the freeze those files are never edited again: every change is recorded as an append-only, structured entry (CL-####) in CHANGED_LOG.md. Every pipeline skill reads the log and treats the effective state of a frozen artifact as the frozen file plus all log entries targeting it (entries win on conflict). Per-context files (prd-<context>.md, architecture-<context>.md, epic-<context>.md, …) and IMPLEMENTATION_LOG.md are not frozen and remain editable.

Kairos-Aware

Every skill auto-detects whether the current project is a Kairos component (by go.mod references to kairos-component-common / kairos-gen / nga-common, presence of pkg/schema/ and the standard internal/ layout, presence of topic-config.json, or CLAUDE.md mentioning Kairos). When Kairos mode triggers, the skills produce Kairos-shaped output: bounded-context-to-component mapping, EntityBase aggregates with 2-column JSONB persistence, Fiber endpoints using api.SuccessResponse / api.ErrorResponse, CloudEvent message schemas under pkg/schema/, kairos-gen-aware make generate gates, and Component Map rows routed to the matching layer skills (domain-model-development, repository-development, service-development, client-api-development, event-handler-development, message-schema-development, kairos-testing, kairos-feature-scaffolding).

For non-Kairos projects the skills fall back to generic templates. Each skill records the detected mode in its output header (Mode: Kairos | Generic). Users can override with "use generic" or "use kairos" in their prompt.

Every skill also honours CLAUDE.md and AGENTS.md — project rules override skill defaults.

Skills Reference

/nga-kairos-setup (environment onboarding, before any development)

Walks you through installing Kairos and creating your local development cluster, following the official IFS Kairos QuickStart Guide (Confluence space NGA, page 2308014843) as its single source of truth — WSL 2 + Ubuntu 24.04, the official SSH/CLI setup script, and ./kairos cluster create. It drives three bundled, interactive helper scripts installed under the assistant's scripts directory (.claude/scripts/, .cursor/scripts/, or .github/scripts/) — kairos-detect.sh, kairos-setup.sh, kairos-cluster-create.sh — rather than inlining shell commands. It is idempotent and conservative: kairos-detect.sh first reports what already exists (the kairos CLI, the nga-local-dev repo, the SSH key, a running cluster) and, if anything is present, the skill stops and asks for explicit per-artifact confirmation before reinstalling or recreating — never silently (the cluster script enforces this guard itself too). It applies hard rules straight from the guide: WSL/Ubuntu only (never /mnt/c/), VPN disconnected before running the setup script, Docker CE rather than Docker Desktop, and Docker Hub login using a personal access token. After the cluster is up it points you at the landing page (https://127.0.0.1.nip.io) and the Eventing Challenge as the next step. Runs setup commands against your machine; it produces no _nsf_output/ file.

/nga-kairos-update (environment maintenance — update an existing install)

Updates an already-installed Kairos CLI and local environment to the latest version, following the official IFS update steps in order: pull the latest nga-local-dev (cd ~/nga-local-dev && git pull), run ./kairos to detect and apply updates (interactive — the user runs it in their own WSL terminal; it may prompt for Docker Hub creds, shell completion, and a sudo password to install tools like atlas), run kairos tools update --all if ./kairos flags outdated tools (go/helm/docker), run kairos update (which regenerates the certificate and cycles — restarts — the local cluster automatically, so the skill warns before that step), then trust the new certificate (accept the trust window, or wsl --shutdown from Windows and kairos certificate trust from WSL). Runs inside WSL 2 Ubuntu from ~/nga-local-dev. Pre-flight checks that an install actually exists — if there's no nga-local-dev repo or kairos CLI yet, it stops and points you at /nga-kairos-setup. Runs commands against your machine; it produces no _nsf_output/ file.

/nga-spec-writer (Phase 0 - event storming path)

Takes raw event storming artifacts as input and converts them into a full set of structured specs. Organises stickies into domain events, commands, aggregates, actors, policies, hot spots, and external systems. Identifies bounded contexts and classifies their relationships (Customer/Supplier, Partnership, Conformist, ACL). In Kairos mode, also produces a bounded-context-to-Kairos-component mapping (this repo / existing component / new component repo — defaulting to colocation) and adds Go-naming hints to the ubiquitous language glossary. Then generates a domain brief, a master spec (with Kairos NFR defaults in Kairos mode — tenant isolation, idempotency, ETag concurrency, audit log, correlation propagation), and one focused spec per bounded context. All outputs land in _nsf_output/docs/. Feeds into /nga-spec-normalizer (full pipeline) or directly into /nga-brainstorm (legacy path).

/nga-spec-normalizer (deterministic — any spec to CBI)

Takes any unstructured input — /nga-spec-writer output, a filled SPEC.md, a greenfield brief, or inline freeform text — and extracts the stated facts into a Canonical Brainstorm Input (CBI) with a fixed 6-section schema. Deterministic: extracts only what is explicitly stated, never invents or infers. Fields not stated in the source are marked [not stated] so gaps are visible. Produces _nsf_output/CBI.md. Feeds into /nga-gap-analysis.

The CBI schema covers: Problem / Goals / Users / Actors; Domain Concepts / Actions / Events; Business Rules / Workflows; Integrations / Constraints; Assumptions / Unknowns / Risks; NFRs / Success Metrics / Out of Scope. In Kairos mode, also populates a Section 7 with component scope, aggregates, commands/events, tenant scoping, policies, and external systems.

/nga-gap-analysis (deterministic — enrich CBI before brainstorming)

Reads _nsf_output/CBI.md and systematically analyses every section for missing fields, inconsistencies, ambiguities, and open questions. Reports findings by severity (critical / missing / inconsistency / ambiguity), referencing the CBI section for every finding. Loops with the user — accepts answers, updates the CBI in memory, re-analyses, reports delta — until the user is satisfied. Enriches _nsf_output/CBI.md in place: writes resolved answers back into the fields and embeds gap notes inline (✅ resolved, ⚠️ open, ❓ ambiguous) plus an Open Gaps Summary table, bumping the header to version 1.1. Feeds into /nga-brainstorm (Path D). In Kairos mode, also checks Kairos-specific assumptions (tenant scoping, idempotency, ETag concurrency, cross-component coupling).

/nga-brainstorm

Run this before writing any requirements. Leads a structured 4-phase ideation session: forces you to articulate the real pain and user, challenges hidden assumptions, generates 3 contrasting approaches, and gives a clear recommendation. In Kairos mode, the assumption-challenging step surfaces Kairos-specific risks (tenant model, idempotency, ETag concurrency, cross-component coupling, master-data ownership), and the approach options are labelled with their Kairos shape (single-component, context-by-context, vertical slice, new repo). Produces _nsf_output/BRAINSTORM.md.

/nga-write-prd

Translates a brainstorm doc or spec file into a complete, unambiguous Product Requirements Document. Reads _nsf_output/BRAINSTORM.md (or a spec you provide), fills gaps with targeted questions, then produces a split PRD like the spec-writer output — a master anchor _nsf_output/master-prd.md (product-wide problem/goal/non-goals, system-wide NFRs, success metrics, context index) plus one _nsf_output/prd-<context>.md per bounded context (testable functional requirements, user stories, acceptance criteria, edge cases, data model, integrations), generated one at a time. Kairos mode uses Kairos NFR defaults (tenant isolation, at-least-once idempotency, ETag optimistic concurrency, audit log, correlation propagation, structured observability), names aggregates instead of generic entities, and flags technical leakage (any FR/NFR prescribing implementation detail that should be /nga-architect's call). Stays product-level — persistence shape and library choices are left to /nga-architect.

/nga-architect

Designs the full technical architecture before any code is written. Reads the /nga-write-prd output (_nsf_output/master-prd.md + every prd-<context>.md), makes explicit decisions on each architectural area with options, trade-offs, and a clear recommendation. In Kairos mode the decision areas are Kairos-specific (aggregate placement, EntityBase shape, 2-column JSONB persistence, ServicesFactory wiring, Fiber endpoints, pkg/schema/ messages, internal/event-handler/ map, cross-component integration via topic-config.json, layer-specific testing tools). The output is split like the PRD: a _nsf_output/master-architecture.md anchor (cross-context principles, the message-schema registry, cross-component integration, the context index & build order, and the system-wide security/performance baseline) plus one _nsf_output/architecture-<context>.md per bounded context (domain model with EntityBase, 2-column JSONB persistence + JSONB-path index hints, API contracts using api.SuccessResponse / api.ErrorResponse, the schemas it owns, the event/command handler map, and a Component Map with a Layer Skill column per row plus an explicit make generate step between schemas and dependents). Generic projects get a stack-appropriate generic template instead.

/nga-verify-architecture

The gate between /nga-architect and /nga-implement. Reads _nsf_output/master-architecture.md + every architecture-<context>.md and the PRD (master-prd.md + every prd-<context>.md), auto-detects Kairos vs. generic mode, then runs three passes — a PRD ↔ Architecture coverage matrix per context (FRs from each prd-<context>.md against that context's Component Map), mode-specific convention checks (per-context Kairos invariants or generic anti-patterns, plus master-level checks: schema-registry completeness, cross-component integration, build-order DAG), and cross-cutting concerns (security, performance, testing) — grading findings CRITICAL / MAJOR / MINOR. An interactive fix loop then proposes a fix per finding and, with your per-finding confirmation, applies it directly to the right file (master or per-context). It re-grades from whatever stays open and appends a ## Verification — verify-architecture section to master-architecture.md with the post-fix verdict (✅ pass / ⚠️ pass with notes / ❌ block) that /nga-implement's pre-flight reads as a gate. Does not write application code or improvise alternative designs. Refuses to run if no master-architecture.md exists.

/nga-epic-planner

Turns the approved architecture and its PRDs into a planned, traceable delivery backlog — one _nsf_output/epic-<context>.md per bounded context — right before /nga-implement (it runs after /nga-architect / /nga-verify-architecture). Acting as a product owner / delivery planner, it reads the /nga-write-prd output (master-prd.md + the prd-<context>.md files) and, by default, generates epics for every context in one pass (it can also work one context at a time — it asks which you prefer when more than one PRD exists, defaulting to all; /nga-epic-planner <context> scopes to a single context). For each context it breaks the PRD's user stories into epics grouped by a single aggregate or one user journey, makes every story trace to at least one domain event (in Kairos mode the commands/events named in the PRD's FRs and Integration section; in generic mode a past-tense business state change), attaches a Definition of Done per story, and flags every dependency on another bounded context in both the owning story and a summary table. When the architecture is present it orders the epics by the cross-context build order (master-architecture.md §5) and each context's Implementation Sequence, and reconciles each story's events/aggregates against that context's Component Map and the master schema registry (mismatches are flagged, not silently overridden). A self-review pass flags stories with no domain event, untraceable stories, missing DoDs, incoherent epics, FR coverage gaps, and (Kairos) invented events or mutation stories missing idempotency/audit/ETag in their DoD. Each file is built from its own context's PRD only — cross-context needs are flagged, never satisfied by importing another context's stories. Refuses to run without a PRD and never invents requirements absent from it. Feeds /nga-implement, where each story's Definition of Done is the per-row acceptance bar.

/nga-implement

Executes the architecture, scoped to a single bounded context — it never loads or builds against another context's architecture or PRD. Reads _nsf_output/master-architecture.md + the target context's architecture-<context>.md, the target context's PRD (master-prd.md + the one prd-<context>.md), and the /nga-epic-planner backlog (epic-<context>.md). When epic files exist it runs in story-driven mode: it lists every epic per context and the user stories under each, marks each story ✅ Ready or ⛔ Blocked (by an unmet prerequisite story or cross-context dependency — and stops if the dependency graph has a cycle), and asks which user story to build — then implements just that story's slice (its Component Map rows) end-to-end against the story's Definition of Done, one story per run, re-offering the menu after each so a developer can build without colliding with other epics or stories. Story status (⬜/🟡/✅) is written back to epic-<context>.md as work completes, so the backlog is the resumable record of progress across sessions. With no epic files it falls back to phase-driven mode (a whole Implementation Sequence phase at a time). It validates the Component Map and Implementation Sequence and builds components in the declared order. First pre-flight step reads any ## Verification — verify-architecture section: a ❌ block verdict halts implementation until /nga-architect is re-run; ⚠️ pass with notes surfaces MAJORs for per-item resolved/accepted confirmation (accepted items logged as deviations); ✅ pass continues silently; section absent warns once and asks whether to proceed without independent verification. In Kairos mode, each Component Map row is routed to its layer skill (domain-model-development, message-schema-development, repository-development, service-development, client-api-development, event-handler-development, kairos-testing); aggregate-shaped maps invoke kairos-feature-scaffolding as orchestrator for the ServicesFactory / AppConfig wiring. make generate is a hard gate — after any schema or topic-config.json change, generation runs before dependents build, and kairos-gen outputs (sql/1.gen/, generated topic subscriptions) are never hand-edited. Writes tests alongside each component via kairos-testing, runs verification after each unit (make generate idempotent, build, vet, test, lint — plus, in story-driven mode, every Definition-of-Done criterion), and stops at every milestone for review. Logs all progress, generated-code refreshes, and deviations to _nsf_output/IMPLEMENTATION_LOG.md.

/nga-verify-kairos

The gate between /nga-implement and merge. Reads _nsf_output/IMPLEMENTATION_LOG.md, the architecture (master-architecture.md + the implemented architecture-<context>.md), and the PRD (master-prd.md + every prd-<context>.md) to scope the review to the work actually claimed, then delegates the diff-level review to the kairos-review skill running in Kairos mode against the local repo (no Bitbucket token, no PR URL). Cross-references every CRITICAL/MAJOR finding back to the Component Map row and FR-N that produced it, re-runs the verification commands recorded in IMPLEMENTATION_LOG.md to confirm they still pass on a clean run, and appends a ## Verification — verify-kairos section to IMPLEMENTATION_LOG.md with the outcome. When the implementation included Helix Web Component UI (detected from nga-helix-ui layer-skill rows in the log or <hx-*> tags in the diff), it adds an independent Helix UI sub-phase the Go-only checks miss — re-runs the UI build/typecheck fresh, re-checks every Helix tag/attribute/slot/event and accessibility prerequisite against .claude/docs/helix-ui/<component>.md, and confirms every UI-facing FR-N has a built component (soft-reduces to build + FR coverage when Helix docs are absent, skips with an "N/A" note when there's no UI). Review-only with one narrow exception: mechanical, doc-traceable Helix UI fixes (wrong attribute/slot/event name, missing documented ARIA, inline-style → documented CSS property) can be applied in place with the user's per-finding confirmation and re-validated by a fresh UI build — structural UI issues, build failures, missing components, and all backend findings stay review-only and route back to /nga-implement. Refuses to run if no implementation artifacts exist, if the project isn't Kairos-shaped, or if the kairos-review skill is not installed (fails fast in Phase 0.0 with two alternative-command suggestions).

/nga-review-pr (review a Bitbucket Cloud PR from its URL)

Reviews a Bitbucket Cloud pull request given its URL — the PR-URL mirror of /nga-verify-kairos (which reviews the local working tree). It fetches the PR's metadata and unified diff deterministically via the bundled pr-review-fetch.js helper (Bitbucket REST 2.0, authenticating with the stored token — Basic email:token for an Atlassian API token, or Bearer for a Bitbucket access token, chosen automatically with fallback — read silently from ~/.nga-skills-factory/bitbucket.json or BITBUCKET_API_TOKEN), then reviews the diff with a hybrid engine: the general correctness + reuse/simplification/efficiency lens of the built-in /code-review always runs, and the Kairos checklist is delegated to the kairos-review skill (tenant isolation, EntityBase + 2-column JSONB, api.SuccessResponse/api.ErrorResponse, idempotency, ETag concurrency, pkg/schema/ contracts, handler wiring, make generate freshness) when the project is a Kairos component and kairos-review is installed — otherwise it runs the general lens alone and says so once. It is report-first: it writes _nsf_output/PR_REVIEW.md (severity-graded findings + verdict) and walks the user through the findings, then posts findings back to the PR as inline comments only on the user's per-finding confirmation — never automatically (posting publishes to a shared artifact). Findings anchor to the diff's new-file line numbers. Bitbucket Cloud only — other hosts are handed off to /code-review (local) or /review. If no URL is given it asks for one. It never asks for the token up front; only if the saved token is missing or invalid (401/403) does it prompt for one, save it back to ~/.nga-skills-factory/bitbucket.json, and retry. If the bundled script is missing it stops with setup guidance.

/nga-handover (write a resumable, git-native shift handover)

Captures the working context that git commits don't — the exact stopping point (file:line + a runnable Resume block), what to do in the first 30 minutes, decisions, deviations from spec, workarounds, concerns, and verification. It is git-native: every entry is a new append-only markdown file under <repo>/.handover/entries/<yyyy-MM>/ with schema: handover/v1 frontmatter and nine fixed H2 sections, committed on the working branch so context travels with the code. Collision-proof filenames (UTC-minute + author + topic) make merge conflicts structurally impossible — there is deliberately no INDEX.md or rollup file ("latest" is computed by /nga-pickup, never stored). It drives the bundled, self-contained nsf-handover-new + nsf-handover-check scripts (PowerShell + bash twins; no external template file) and pre-drafts TL;DR, Stopping point, Next steps, Workarounds, and Verification from git evidence only — it never invents Decisions, Deviations, or Concerns; anything unevidenced gets a <!-- AUTHOR CONFIRM: … --> marker and is asked, and the lint fails on any leftover marker. The skip rule: a 5-line entry is always acceptable; zero entries on a day you pushed code is not. Works for any team — follow-the-sun (sl/uk/ca), squad-to-squad, or solo across days. Read-side mirror: /nga-pickup.

/nga-pickup (brief the incoming shift from git-native handovers)

The read-side mirror of /nga-handover. Discovers append-only handover entries under <repo>/.handover/entries/ on any branch (including unmerged feature branches) with plain git log — no server, no index file. It drives the bundled nsf-handover-pickup script with a 96-hour default lookback (so a Monday or post-break pickup still sees Friday's entries; widen with -Since 7.days), filters entries to those addressed to the reader (handover_to ∈ {your shift, any}), and presents TL;DR + Stopping point + Next steps first — the reader's 10-minute budget is for resuming, not archaeology (full entries on demand with -Full). It then reconciles each entry's Next steps against commits made since that entry's last_commit and flags items already done, surfaces any blocked / blocking: true / build_state: red first, and prompts the ack loop ("picked up — <id>"). Read-only — corrections are new /nga-handover entries with supersedes:, never edits.

/nga-helix-ui

The UI/UX subject-matter expert for IFS Helix Web Components. Builds, modifies, or reviews Web Component UI using the canonical component docs fetched into <assistant>/docs/helix-ui/ at install time. Iron Law: every Helix component in generated markup must trace to a doc file — the skill reads the doc end-to-end (tag name, attributes, slots, events, CSS custom properties, accessibility notes) before writing markup and refuses to invent component APIs when a doc is available. Decomposes the request into affordances, maps each to a documented component, surfaces uncovered affordances once for the user to confirm (compose from primitives, approved generic build marked out-of-system, or defer), then generates framework-idiomatic markup and a tag→doc traceability table. When docs/helix-ui/ is missing, it soft-falls-back to generic Web Component patterns with a single one-line notice — no halt, no nagging. /nga-implement routes any UI / Web Component row (markup, page, form, dialog, Helix tags like <hx-button>) to this skill when it is installed.

Helix UI Support

/nga-helix-ui is gated behind a separate opt-in because it needs the canonical Helix component docs, which live in a private Bitbucket repo (ifs-pd/ifs-ux-helixwebcomponents).

Enabling it. During an interactive install you'll be asked whether you want Helix UI support. Say yes and provide:

• Atlassian / Bitbucket email
• API token — create one at https://id.atlassian.com/manage-profile/security/api-tokens

The installer fetches every component doc from the repo, mirrors them into each chosen assistant's docs/helix-ui/ directory (one <component>.md per component), and installs the /nga-helix-ui skill. Stale docs (components removed/renamed upstream) are pruned on each fetch.

Credential storage. Credentials are only persisted after a successful fetch validates them, and only if you confirm. When saved they go to ~/.nga-skills-factory/bitbucket.json (mode 600) and are reused on later installs/refreshes without re-prompting. The Authorization header is never forwarded across hosts on redirect, so the token is not leaked to Bitbucket's CDN origin.

Refreshing docs. When components change upstream, re-fetch into already-installed assistants without re-running the full installer:

npx nga-skills-factory refresh-helix-docs --all      # or --claude / --cursor / --copilot

With no flags, refresh-helix-docs auto-detects which assistant directories already exist in the workspace.

If the fetch fails (bad token, network), install continues and the skills soft-fall-back to generic Web Component patterns — fix the credentials and run refresh-helix-docs.

Workflow

Full pipeline (recommended)

Run this when starting from any spec — event storming output, a filled SPEC.md, or a freeform brief:

/nga-spec-writer (or write SPEC.md)  →  /nga-spec-normalizer  →  /nga-gap-analysis  →  /nga-brainstorm  →  /nga-write-prd  →  /nga-architect  →  /nga-verify-architecture  →  /nga-epic-planner (optional)  →  /nga-implement  →  /nga-verify-kairos

/nga-epic-planner is an optional planning step between /nga-verify-architecture and /nga-implement: with the architecture approved, it turns the PRDs into an epic/story delivery backlog (epic-<context>.md per context) with each story traced to a domain event, a Definition of Done, and cross-context dependency flags — ordered by the architecture's Implementation Sequence. Skip it if you don't need a formal backlog — /nga-implement walks the per-context architecture-<context>.md Component Map directly either way.

The new stages ensure that /nga-brainstorm always receives a complete, consistent, gap-analysed input regardless of how the spec was written:

1. /nga-spec-normalizer extracts stated facts from any spec format into a fixed-schema CBI — deterministic, no assumptions.
2. /nga-gap-analysis surfaces missing information, inconsistencies, and ambiguities in a structured loop until the CBI is sufficient.
3. /nga-brainstorm detects _nsf_output/CBI.md (Path D) and uses the enriched CBI as its foundation — skips all intake, goes straight to challenging the framing.
4. /nga-brainstorm (Path D) saves both BRAINSTORM.md and REFINED_CBI.md — the updated canonical product model ready for /nga-write-prd and /nga-architect.

Legacy paths (still fully supported)

Event storming path — spec-writer output feeds directly into brainstorm:

/nga-spec-writer  →  /nga-brainstorm  →  /nga-write-prd  →  /nga-architect  →  /nga-verify-architecture  →  /nga-implement  →  /nga-verify-kairos

Spec-first path — fill a SPEC.md and feed directly into brainstorm:

(fill SPEC.md)  →  /nga-brainstorm  →  /nga-write-prd  →  /nga-architect  →  /nga-verify-architecture  →  /nga-implement  →  /nga-verify-kairos

Greenfield path — brainstorm from scratch with no prior spec:

/nga-brainstorm  →  /nga-write-prd  →  /nga-architect  →  /nga-verify-architecture  →  /nga-implement  →  /nga-verify-kairos

Pipeline entry points

You can enter the pipeline at any point — if you already have a PRD, start with /nga-architect; if you have an architecture, start with /nga-verify-architecture (or /nga-implement if you want to skip the gate).

/nga-verify-architecture is an optional but strongly recommended gate between /nga-architect and /nga-implement — it runs an independent fresh-context pass with an explicit PRD ↔ Architecture coverage matrix and appends a verdict that /nga-implement's pre-flight reads as a gate.

/nga-verify-kairos is an optional but recommended last step on Kairos projects — run it once /nga-implement reports "Implementation complete" to put the diff through the kairos-review checklist and re-run the recorded verification commands before merge.

Adding New Skills

1. Add skills/claude/commands/<name>/SKILL.md (full version) and/or skills/cursor/skills/<name>/SKILL.md (condensed version)
2. Add the condensed definition to skills/copilot/copilot-instructions.md
3. Register it in src/manifest.js (in pipeline order)
4. Run npm test — the consistency suite checks every manifest skill has its files and a copilot section, and that claude/cursor stay in parity
5. Publish: npm publish (the version is bumped automatically — see below)

The version in package.json + package-lock.json no longer needs a manual bump: a tracked pre-commit git hook (.githooks/pre-commit) auto-increments the patch version on every commit and stages both files into that commit.

Git hooks (version auto-bump)

This repo ships a tracked pre-commit hook at .githooks/pre-commit that runs npm version patch --no-git-tag-version on every commit, so package.json and package-lock.json are bumped and staged automatically.

After cloning, enable it once:

npm run setup:hooks   # sets git config core.hooksPath .githooks

• It is skipped during merges, rebases, and cherry-picks (those replay existing commits).
• To skip it for a single commit: NO_VERSION_BUMP=1 git commit ...

Publishing

npm login
npm publish --access public

Users then run: npx nga-skills-factory