nga-skills-factory 0.0.1

package/README.md

@@ -0,0 +1,145 @@
+# nga-skills
+
+Structured AI development workflow skills - install once, use everywhere.
+
+Supports **Claude Code**, **Cursor**, and **GitHub Copilot**.
+
+---
+
+## Quick Start
+
+```bash
+# 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
+```
+
+---
+
+## What Gets Installed
+
+
+| Skill          | Type          | Claude | Cursor | Copilot |
+| -------------- | ------------- | ------ | ------ | ------- |
+| `/spec-writer` | Slash command | ✓      | ✓      | ✓       |
+| `/brainstorm`  | Slash command | ✓      | ✓      | ✓       |
+| `/write-prd`   | Slash command | ✓      | ✓      | ✓       |
+| `/architect`   | Slash command | ✓      | ✓      | ✓       |
+| `/implement`   | Slash command | ✓      | ✓      | ✓       |
+
+
+### Install Locations
+
+
+| Assistant      | Files land in                     |
+| -------------- | --------------------------------- |
+| Claude Code    | `.claude/commands/`               |
+| Cursor         | `.cursor/rules/`                  |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+
+### Output Artifacts
+
+All skills write their output to `_nsf_output/` in your project root:
+
+
+| Skill          | Output file(s)                                                                                                   |
+| -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `/spec-writer` | `_nsf_output/docs/raw-storming.md`, `context-map.md`, `domain-brief.md`, `master-prd.md`, `prd-<context>.md` × N |
+| `/brainstorm`  | `_nsf_output/BRAINSTORM.md`                                                                                      |
+| `/write-prd`   | `_nsf_output/PRD.md`                                                                                             |
+| `/architect`   | `_nsf_output/ARCHITECTURE.md`                                                                                    |
+| `/implement`   | `_nsf_output/IMPLEMENTATION_LOG.md`                                                                              |
+
+
+---
+
+## 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
+
+### `/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 PRD (with Kairos NFR defaults in Kairos mode — tenant isolation, idempotency, ETag concurrency, audit log, correlation propagation), and one focused PRD per bounded context. All outputs land in `_nsf_output/docs/`. Feeds directly into `/brainstorm`.
+
+### `/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`.
+
+### `/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 `_nsf_output/PRD.md` with testable functional requirements, user stories, acceptance criteria, edge cases, and success metrics. **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 `/architect`'s call). Stays product-level — persistence shape and library choices are left to `/architect`.
+
+### `/architect`
+
+Designs the full technical architecture before any code is written. Reads `_nsf_output/PRD.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 resulting `_nsf_output/ARCHITECTURE.md` includes: domain model with `EntityBase`, 2-column JSONB persistence + JSONB-path index hints, API contracts using `api.SuccessResponse` / `api.ErrorResponse`, a message schema table, an 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.
+
+### `/implement`
+
+Executes the architecture one phase at a time. Reads `_nsf_output/ARCHITECTURE.md`, validates the Component Map and Implementation Sequence, and builds components in the declared order. 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 phase (`make generate` idempotent, build, vet, test, lint), and stops at every milestone for review. Logs all progress, generated-code refreshes, and deviations to `_nsf_output/IMPLEMENTATION_LOG.md`.
+
+---
+
+## Workflow
+
+Both paths run through the full pipeline. The only difference is whether you start with event storming data or a raw idea:
+
+**Event storming path** — you have a domain model from a storming session:
+
+```
+/spec-writer  →  /brainstorm  →  /write-prd  →  /architect  →  /implement
+```
+
+**Greenfield path** — you have an idea but no formal domain model:
+
+```
+/brainstorm  →  /write-prd  →  /architect  →  /implement
+```
+
+When `/spec-writer` output is present in `_nsf_output/docs/`, `/brainstorm` automatically detects it and switches to a domain-informed mode — it skips the raw intake questions and focuses on product strategy (MVP scope, constraints, success metrics) instead. The bounded contexts from the domain model drive the approach options.
+
+You can enter the pipeline at any point — if you already have a PRD, start with `/architect`; if you have an architecture, start with `/implement`.
+
+---
+
+## Adding New Skills
+
+1. Add the skill file to `skills/claude/commands/<name>/SKILL.md` and/or `skills/cursor/rules/<name>.mdc`
+2. Register it in `src/manifest.js`
+3. Bump the version in `package.json`
+4. Publish: `npm publish`
+
+---
+
+## Publishing
+
+```bash
+npm login
+npm publish --access public
+```
+
+Users then run: `npx nga-skills-factory`

package/bin/nga-skills.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const { program } = require('commander');
+const { install } = require('../src/installer');
+const { list } = require('../src/lister');
+const pkg = require('../package.json');
+
+program
+  .name('nga-skills-factory')
+  .description('Install IFS NGA skills into your AI assistant workspace')
+  .version(pkg.version);
+
+program
+  .command('install', { isDefault: true })
+  .description('Install skills into the current workspace (default command)')
+  .option('--claude', 'Install for Claude Code only')
+  .option('--cursor', 'Install for Cursor only')
+  .option('--copilot', 'Install for GitHub Copilot only')
+  .option('--all', 'Install for all AI assistants')
+  .option('--force', 'Overwrite existing skill files')
+  .option('--dir <path>', 'Target workspace directory', process.cwd())
+  .action(install);
+
+program
+  .command('list')
+  .description('List all available skills')
+  .action(list);
+
+program.parse(process.argv);

package/bitbucket-pipelines.yml

@@ -0,0 +1,33 @@
+image: node:20
+
+definitions:
+  caches:
+    npm: ~/.npm
+
+  steps:
+    - step: &install-test
+        name: Install & Test
+        caches:
+          - npm
+        script:
+          - npm ci
+          - npm test
+
+pipelines:
+  default:
+    - step: *install-test
+
+  branches:
+    master:
+      - step: *install-test
+      - step:
+          name: Publish to npm
+          deployment: production
+          condition:
+            changesets:
+              includePaths:
+                - "package.json"
+                - "package-lock.json"
+          script:
+            - npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
+            - npm publish --access public

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "nga-skills-factory",
+  "version": "0.0.1",
+  "description": "IFS NGA skills installer for AI coding assistants (Claude Code, Cursor, GitHub Copilot)",
+  "main": "src/index.js",
+  "bin": {
+    "nga-skills-factory": "./bin/nga-skills.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "ifs",
+    "nga",
+    "ai-skills",
+    "claude",
+    "cursor",
+    "copilot",
+    "developer-tools"
+  ],
+  "author": "IFS NGA",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.6"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}