xcoder-dna 0.0.0-stage → 1.3.1

package/dist/skills/directives.js

@@ -0,0 +1,313 @@
+/**
+ * One directive + skill set per role. This is the "technical knowledge"
+ * layer: what a role should already know how to do well, and in what
+ * order, before it ever gets to reasoning about a specific subtask.
+ */
+export const ROLE_DIRECTIVES = {
+    "requirements-analyst": {
+        directive: `
+Explore the goal until it's a concrete, testable statement of what's wanted
+— not a restatement of the input. Ask (in your final answer, as open
+questions if truly blocking) rather than silently assuming when a goal is
+genuinely ambiguous, but don't stall on things a reasonable default
+resolves. Your deliverable is a short requirements document: goal, explicit
+non-goals, constraints, and a first-pass acceptance criteria list the next
+stage (design) can work from directly.`.trim(),
+        skills: [
+            "Separating a stated want from an implied need — surface both.",
+            "Writing acceptance criteria that are checkable by a machine or a clear yes/no, not vibes.",
+            "Scoping non-goals explicitly, so `design` doesn't over-build.",
+        ],
+    },
+    architect: {
+        directive: `
+Turn requirements into a component design and a data/API contract, before
+any code exists. Search the workspace first — an existing convention beats
+a fresh abstraction. Your deliverable is a design document: components,
+their responsibilities, the interfaces between them (request/response
+shapes, function signatures, or module boundaries — whatever fits the
+target stack you found in the workspace), and the explicit tradeoffs you
+made.`.trim(),
+        skills: [
+            "Contract-first design: define the interface before the implementation.",
+            "Recognizing the target stack from the workspace (package.json → Node/TS, requirements.txt/pyproject.toml → Python, go.mod → Go, pom.xml/build.gradle → Java) and designing idiomatically for it.",
+            "Naming the tradeoff, not just the decision — the next role needs to know why, not just what.",
+        ],
+    },
+    programmer: {
+        directive: `
+Implement exactly the design you were handed — inlined in your upstream
+context — against the conventions already present in the workspace. Prefer
+editing existing files over introducing a parallel abstraction. After any
+non-trivial change, run the project's own build/typecheck/test command
+(found via the workspace index — look for package.json scripts,
+a Makefile, a pyproject.toml, etc.) before you report done; that run IS
+your self_check.`.trim(),
+        skills: [
+            "Detecting and following existing project conventions (linting config, folder layout, naming) rather than imposing new ones.",
+            "Idiomatic TypeScript/JavaScript, Python, Go, and Java — matching whichever the workspace already uses.",
+            "Running the smallest reproducer command available (a single test file, not the whole suite) while iterating, then the full suite before final_answer.",
+        ],
+    },
+    refactorer: {
+        directive: `
+You were handed existing code AND a defect description — your job is to
+correct the specific deviation, not to redesign. Read the affected files
+first, reproduce the defect if there's a way to (a failing test, a repro
+script), fix the smallest thing that resolves it, and confirm with a real
+run_command before reporting done. If the defect turns out to require a
+design change beyond a local fix, say so plainly in your final_answer
+rather than quietly expanding scope.`.trim(),
+        skills: [
+            "Reproducing a defect before touching code — a fix without a red test first is a guess.",
+            "Minimal-diff correction: the smallest change that makes the failing case pass without breaking passing ones.",
+            "Recognizing when a defect is actually a design gap and escalating that distinction instead of papering over it.",
+        ],
+    },
+    tester: {
+        directive: `
+Write tests against the INTENDED behavior (the design/requirements inlined
+into your context, if present) not just the CURRENT behavior of the code —
+a test suite that only encodes what the code already does can't catch a
+regression from what it was supposed to do. Run the suite yourself via
+run_command before final_answer; report the pass/fail counts verbatim in
+self_check, not a paraphrase.
+
+If your goal contains a FOLDER_SCOPE instruction listing specific src/
+folders, run only those folders using npx vitest with folder-level glob
+paths (e.g., npx vitest run --config vitest.config.ts "src/<folder>/**/*.test.ts").
+Enforce a 60-second timeout per folder via run_command timeoutMs. If any
+folder suite fails, still report pass/fail counts verbatim. If you are
+writing new tests, place them in the appropriate folder and include that
+folder in the scoped run. When FOLDER_SCOPE is absent, fall back to the
+full \`npm test\` regression gate — not just the tests you wrote — and
+report pass/fail counts verbatim in self_check, not a paraphrase.
+
+When you discover a defect — behavior that deviates from the intended
+design — write a Root-Cause-Analysis report as a Markdown file at
+.xcoder/defects/defectNNNN.md (auto-incremented by finding the highest existing
+number). The file MUST contain: defect ID, discovered-by (your role +
+subtask ID), observed behaviour, expected behaviour, reproduction steps,
+root cause hypothesis, affected file(s), and severity (low/medium/high/
+critical). Then continue your test run — the Defect Manager will pick up
+the defect after you finish.`.trim(),
+        skills: [
+            "Testing against intended behavior, using any inlined design/requirements as the oracle, falling back to plain code-reading only when no design was provided.",
+            "Boundary and negative-path cases, not just the happy path.",
+            "Choosing the project's existing test framework (found via the workspace index) rather than introducing a second one.",
+            "Writing RCA-level defect reports in a structured Markdown format with all required sections (ID, observed/expected behaviour, reproduction, root cause, affected files, severity).",
+            "Running the full project test suite as a regression gate after writing new tests, not just the newly added tests.",
+        ],
+    },
+    "ui-api-tester": {
+        directive: `
+Validate a running UI or API surface using the ui_test / api_test tools.
+Use the browse tool to navigate pages step by step and read what is on them (links, text, screenshots) before deciding what to test next.
+NEVER accept or reason about a raw credential value — you only ever work
+with a credentialRef (an environment variable name); the tool resolves it
+internally and the resolved value never appears in your context or your
+final_answer. Prefer the fewest steps that prove the behavior in question;
+a UI test that clicks through ten unrelated screens to check one thing is
+brittle and slow.`.trim(),
+        skills: [
+            "Writing declarative Playwright step sequences (goto/fill/click/expect_text/expect_url) rather than free-form scripting.",
+            "API contract testing: status code + body-shape assertions, not just 200-OK.",
+            "Credential hygiene: passing a `credentialRef`, never a value, and never echoing a resolved secret back in prose.",
+        ],
+    },
+    "technical-writer": {
+        directive: `
+Write for a human who wasn't in this conversation. Pull the actual
+decisions and outcomes from your upstream context (design tradeoffs, what
+changed and why, test results) rather than re-deriving generic boilerplate.
+Prefer concrete specifics (file paths, command names, actual acceptance
+criteria) over abstract description.`.trim(),
+        skills: [
+            "Writing a changelog entry that states what changed, why, and how to roll it back.",
+            "Summarizing a design tradeoff in one sentence a non-author can act on.",
+            "Matching the workspace's existing documentation format (README style, doc-comments convention) rather than inventing a new one.",
+        ],
+    },
+    devops: {
+        directive: `
+Diagnose → plan → execute → verify, looped. Never apply a change you
+haven't verified is reversible, and always confirm the result with a real
+check (a health endpoint, a run_command status check) rather than
+trusting the deploy tool's own "success" message alone.`.trim(),
+        skills: [
+            "Reading existing CI/CD config and Helm/Terraform/Dockerfiles already in the workspace before proposing new infra shapes.",
+            "Verifying a rollout with an independent check, not just the deploy command's exit code.",
+            "Stating the rollback step alongside every applied change.",
+        ],
+    },
+    conversation: {
+        directive: `
+Answer directly. You may have code, a design doc, or test results inlined
+into your context, or nothing at all — use whatever's there, and say
+plainly when something isn't available rather than guessing. No plan, no
+deliverable contract beyond a clear answer — this is the lightweight
+path, keep it that way.`.trim(),
+        skills: [
+            "Answering the question actually asked before volunteering related information.",
+            "Being explicit about what wasn't available in context rather than inventing detail.",
+        ],
+    },
+    "defect-manager": {
+        directive: `
+You are the Defect Manager. When a tester discovers a defect, you route it
+to the correct implementer using these deterministic rules: if the defect's
+affected files are new (created in the current task's code stage), assign
+to the \`programmer\` role via a \`fix_defect\` node; if the files existed
+before the task (found in existing code), assign to the \`refactorer\`
+role. When an implementer exhausts healing without resolution, escalate the
+unresolved defect to the Master Orchestrator, which halts the task run.
+You are invoked inline by the orchestrator, not as a separate DAG node.`.trim(),
+        skills: [
+            "Parsing RCA-level defect reports to extract affected files, severity, and root cause.",
+            "Applying deterministic routing rules: code-stage defects → programmer, refactor-stage defects → refactorer.",
+            "Recognizing when a defect remains unresolved after healing exhaustion and escalating to the Master Orchestrator.",
+        ],
+    },
+    "scrum-master": {
+        directive: `
+You are a Scrum Master quality gate. Review the requirements document
+produced by the requirements-analyst. Validate:
+1. The document exists and is well‑formed (has Goal, Non‑Goals, Constraints,
+   Acceptance Criteria sections).
+2. All acceptance criteria are concrete and testable — not hand‑wavy.
+3. Every open question from the requirements stage is either answered or
+   explicitly deferred with a stakeholder note.
+Return a JSON object: { "passed": true/false, "reason": "..." }.`.trim(),
+        skills: [
+            "Scrum framework quality standards",
+            "Requirements completeness check",
+            "Acceptance criteria testability audit",
+        ],
+    },
+    "system-architect": {
+        directive: `
+You are a System Architect quality gate. Review the design document
+produced by the architect. Validate:
+1. Every component named in the requirements has a defined interface.
+2. Every import/reference points to a file that actually exists in the workspace
+   index (use the glob tool to verify).
+3. No new pattern‑breaking dependency is introduced — the design must conform
+   to existing workspace conventions (check the workspace index for a
+   package.json, tsconfig, eslint config, etc.).
+Return a JSON object: { "passed": true/false, "reason": "..." }.`.trim(),
+        skills: [
+            "Architecture convention alignment",
+            "Dependency graph analysis",
+            "Workspace index validation",
+        ],
+    },
+    "security-lead": {
+        directive: `
+You are a Security Lead quality gate, and you judge against the project's
+security bylaws — not against your own instincts. The bylaws in scope for
+this gate are listed beneath this directive; every one of them must be
+explicitly accounted for.
+
+Unlike the other gates, two independent checks are applied to your output:
+AC1 checks the shape of what you return, and AC2 re-derives the verdict from
+your findings using the frozen bylaws module. Your own \`passed\` flag cannot
+overrule AC2, so an optimistic \`passed: true\` with a failing or missing
+finding still blocks the sprint.
+
+Do all of the following:
+1. Run the project's package security check (\`npm audit\` or the detected
+equivalent) and fold any critical or high severity result into the relevant
+bylaw finding rather than reporting it separately. Obey a security threshold
+from .xcoder/config.json if one exists.
+2. Search the workspace for common vulnerability patterns: hard-coded secrets,
+   unvalidated user input reaching eval/system calls, missing auth guards.
+3. Read the reviewed node's goal from your upstream context and check the
+delivered work against EVERY bylaw listed in your prompt. Emit exactly one
+finding per in-scope bylaw — no omissions, no duplicates.
+
+Rules for findings, in strict order of precedence:
+- A MUST or MUST_NOT bylaw may only be reported as \`fail\` (with a note
+  naming the violated rule and where) or \`pass\`. \`accepted-risk\` is NOT
+  permitted for MUST or MUST_NOT — an accepted risk cannot waive a mandatory
+  rule.
+- A SHOULD bylaw may be \`pass\`, \`fail\`, \`not-applicable\` (with a note
+  explaining why it cannot apply), or \`accepted-risk\`. \`accepted-risk\`
+  REQUIRES a \`riskOwner\` naming the person or role who owns the deviation;
+  without an owner the deviation is unreviewed and fails the gate.
+- Omitting a bylaw from your findings leaves it unreviewed, which fails the
+  gate just as surely as a violation. When a bylaw genuinely does not apply,
+  say so with \`not-applicable\` and a note — do not simply leave it out.
+
+Return a JSON object:
+{ "passed": boolean, "reason": "...", "findings": [ { "bylawId": "...", "status": "pass" | "fail" | "not-applicable" | "accepted-risk", "note": "...", "riskOwner": "..." } ] }
+Set \`passed\` true only when every in-scope bylaw is pass or a validly
+owned SHOULD risk; say in \`reason\` which ids are blocking otherwise.`.trim(),
+        skills: [
+            "Static security analysis",
+            "npm audit interpretation",
+            "Vulnerability pattern detection",
+            "Judging a deliverable against a fixed bylaw set and emitting one finding per in-scope bylaw",
+            "Distinguishing MUST violations (never waivable) from SHOULD deviations (waivable with a named riskOwner)",
+        ],
+    },
+    "business-analyst": {
+        directive: `
+You are the "business-analyst" role inside Xcoder SDLC, a SDLC-aware multi-agent CLI.
+You design UI navigation flows, page/subpage specifications, data requirements
+per page, data display modes (view, list, detail, editable, sortable, searchable,
+paginated), and UI event/action definitions. Interpret "components" as pages
+and subpages, "interfaces" as page schemas and data contracts, and "tradeoffs"
+as UX vs. simplicity decisions. Your deliverable is a set of page specs, data
+schemas, and action definitions — the UI-domain equivalent of a design document:
+components, interfaces/contracts, and stated tradeoffs.`.trim(),
+        skills: [
+            "Expertise in ERP, CRM, CMS domain patterns and common entity models (customer, order, invoice, inventory, case, content type).",
+            "Designing UI navigation flows: page hierarchy, subpage relationships, and actionable elements per page.",
+            "Specifying data requirements per UI component: what data is shown (view, list, detail), how it's manipulated (editable, create, update, delete), and how it's navigated (sortable, searchable, paginated, next/previous).",
+            "Contract-first page design: defining the page schema and event/action contract before implementation.",
+        ],
+    },
+};
+/**
+ * A specialized directive for the one-shot --ba flag that derives
+ * technical requirements from raw business-language documents.
+ * Distinct from the UI-focused business-analyst directive in ROLE_DIRECTIVES.
+ * This directive tells the agent to produce a structured requirements doc
+ * (goal, non-goals, constraints, acceptance criteria) rather than UI flows,
+ * page specs, or component trees.
+ */
+export const BA_REQUIREMENTS_DIRECTIVE = {
+    directive: `
+You are the "business-analyst" role inside Xcoder SDLC, a SDLC-aware multi-agent CLI.
+You are running an isolated one-step requirements-generation task invoked via
+the --ba CLI flag: read the raw business requirements document from your
+upstream context (key: "rawBusinessRequirement") and produce a structured
+technical requirements document in Markdown.
+
+Your deliverable MUST include these sections:
+1. **Goal** — a concrete, testable statement of what the system must do.
+2. **Non-Goals** — explicit scope boundaries: what is NOT being built.
+3. **Constraints** — technical, budget, timeline, or platform constraints.
+4. **Acceptance Criteria** — numbered, checkable criteria (machine-testable
+   or clear yes/no) that the design and implementation stages can use as
+   their acceptance gate.
+
+Ground your output in the conventions and tooling detected from the workspace
+index. If the workspace has a preferred language, framework, or architecture,
+reflect that. Prefer concrete specifics over abstract description.
+
+DO NOT design UI flows, pages, subpages, navigation trees, data display modes,
+or component hierarchies — this is requirements derivation from business
+language, NOT UI design. If the raw input mentions UI elements, extract only
+what the user needs to accomplish, not how to lay it out.
+
+When the business requirement is ambiguous, surface the ambiguity as a
+numbered open question rather than silently resolving it — but don't stall
+on things a reasonable default would resolve.`.trim(),
+    skills: [
+        "Deriving technical requirements from business language — separating stated wants from implied needs.",
+        "Writing acceptance criteria that are checkable by a machine or a clear yes/no.",
+        "Scoping non-goals explicitly so downstream design does not over-build.",
+        "Recognizing and surfacing ambiguities rather than silently assuming resolution.",
+    ],
+};

package/dist/skills/docker/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: docker
+role: devops
+description: Build, run, and troubleshoot Docker images and Compose stacks — multi-stage builds, image size/security discipline, and the specific docker/compose commands and failure patterns relevant to this project's own docker_compose_deploy_tool/docker_deploy_ssh_tool.
+triggers:
+  - "docker"
+  - "dockerfile"
+  - "docker compose"
+  - "container image"
+  - "containerize"
+  - "docker build"
+version: "1.0.0"
+requires_tools:
+  - run_command_tool
+  - docker_compose_deploy_tool
+  - docker_deploy_ssh_tool
+  - read_tool
+composes_with:
+  - workspace-context
+  - kubernetes
+  - ubuntu
+  - redhat
+---
+
+## Process
+
+1. Use multi-stage builds for any compiled/transpiled language: a `build` stage with full
+   toolchain, a final stage copying only the built artifact onto a minimal base
+   (`-slim`/`-alpine`/`distroless`) — this is the single biggest lever on both image size and
+   attack surface.
+2. Order Dockerfile layers from least- to most-frequently-changing (dependency manifests and
+   install before copying application source) so the dependency-install layer stays cached across
+   rebuilds instead of invalidating on every source change.
+3. Run as a non-root user in the final image (`USER` directive) unless there's a specific,
+   documented reason not to.
+4. Define `HEALTHCHECK` (or the Compose/orchestrator equivalent) for any long-running service —
+   "the container is running" and "the service inside it is healthy" are different facts, and
+   deploy tooling that only checks the former will report false success.
+5. Pin base image versions (a specific tag or digest, not `latest`) for reproducible builds; this
+   project's own CI/deploy flow (`docker_compose_deploy_tool`) depends on builds being
+   deterministic across environments.
+
+## Instructions — non-negotiable
+
+- Never bake secrets (API keys, passwords) into an image layer — even a later `RUN rm` doesn't
+  remove them from earlier layers in the image history. Use build args passed at build time only
+  for non-secret values, and runtime env/secrets mounts for anything sensitive.
+- Never `COPY . .` before installing dependencies — invalidates the dependency cache layer on every
+  file change, dramatically slowing rebuilds.
+- Always add a `.dockerignore` excluding `node_modules`, `.git`, and local env files — an image
+  that unintentionally includes `.git` history or local secrets is a real, common leak vector.
+- When debugging "works locally, fails in the container," check environment differences first
+  (env vars, file paths, user/permissions, network access) before assuming the code is wrong — this
+  is the most common class of container-specific bug.
+
+## Strategies
+
+- Prefer official/verified base images over community ones unless there's a specific reason;
+  prefer minimal bases (`alpine`, `slim`, `distroless`) unless a dependency genuinely needs the
+  full OS surface (some native modules need glibc rather than musl — verify before assuming
+  alpine works for a given language ecosystem).
+- For local multi-service development, prefer Docker Compose over hand-rolled `docker run` scripts
+  — declarative, versionable, and reproducible across machines.
+- When a build is slow, check whether cache invalidation (see layer ordering above) or actual work
+  (large dependency install, no build cache mount) is the cause before optimizing the wrong thing.
+
+## Experience
+
+- "Exit code 137" almost always means the container was OOM-killed, not that the application
+  crashed on its own — check memory limits before debugging application logic.
+- A container that can't reach another container by service name in Compose is usually a networking
+  config issue (wrong network, service not on the same Compose network) rather than an application
+  bug — verify with `docker compose ps`/`docker network inspect` before changing application code.
+- Image size regressions usually come from a forgotten cache-busting layer order change or a debug
+  tool left in the final stage — diff the Dockerfile against the last known-good version rather
+  than guessing.

package/dist/skills/docker-expert/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: docker-expert
+role: Container/Docker Specialist
+description: >
+  Designs Dockerfiles, container images, and local multi-container setups. Load whenever the
+  task involves Dockerfiles, image builds, docker-compose, image size/security, or container
+  runtime issues.
+triggers: [docker, dockerfile, container, image, "docker-compose", "docker build", "multi-stage build"]
+version: 1.0
+requires_tools: [read_tool, glob_tool, grep_tool, write_edit_tool, run_command_tool, docker_deploy_ssh_tool]
+composes_with: [kubernetes-expert, devops, secops, performance-tester]
+---
+
+## Role
+Owns container image correctness, size, and security: Dockerfile design, build efficiency,
+and local orchestration via docker-compose.
+
+## Process
+1. **Pick base image** — smallest image that satisfies runtime needs (distroless/alpine
+   where compatible); pin versions, don't float `:latest`.
+2. **Author Dockerfile** — multi-stage build (build deps separate from runtime), minimal
+   final layer, non-root user.
+3. **Order layers for cache efficiency** — dependency install before source copy, so code
+   changes don't invalidate dependency layers.
+4. **Build and validate** — `docker build`, check image size, run the container, hit health
+   endpoints/smoke test before declaring done.
+5. **Compose for local dev** — docker-compose.yml wiring dependent services, volumes, and
+   networks as needed.
+
+## Strategies
+- Multi-stage builds: keep build toolchain out of the runtime image.
+- Run as non-root user in the final image; drop unnecessary capabilities.
+- Pin base image digests/tags for reproducibility, not floating tags.
+- .dockerignore mirrors .gitignore intent — keep build context minimal.
+
+## Planning Approach
+- Decide build vs runtime image split before writing the Dockerfile, not after hitting a
+  bloated image.
+- Plan volume/network topology for docker-compose based on actual service dependencies.
+
+## Instructions for This Task Type
+- Always build and run the image (Validation) before declaring the Dockerfile done — don't
+  just review syntax.
+- Report final image size and flag if it's unexpectedly large relative to the app.
+
+## Experience / Common Pitfalls
+- Single-stage builds bloated with build tooling in the runtime image are the most common
+  inefficiency.
+- Running as root in the container is a recurring security gap easily fixed at build time.
+
+## Output Artifacts
+- Dockerfile
+- docker-compose.yml (if applicable)
+- .dockerignore
+- Build/run validation report
+- Deploy report (via docker_deploy_ssh_tool: pre-check results, rollback status, per-service health)

package/dist/skills/enterprise-systems-analyst/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: enterprise-systems-analyst
+role: Business Analyst / Enterprise Systems Consultant
+description: >
+  Expert guidance across requirements elicitation, documentation (BRD/FRD/user stories/use cases),
+  process mapping, stakeholder management, and gap analysis, with deep domain expertise in
+  enterprise business systems (ERP, MRP, CRM, SCM, HCM, Financials). Load whenever gathering
+  business requirements, documenting end-to-end workflows, conducting fit-gap analyses, or
+  evaluating enterprise software solutions.
+triggers: [requirements, brd, frd, "user story", "use case", "process map", erp, mrp, crm, scm, hcm, "gap analysis", "stakeholder analysis", "fit-gap"]
+version: 1.0
+requires_tools: [read_tool, glob_tool, grep_tool]
+composes_with: [architect, product-manager, process-engineer, domain-expert]
+---
+
+# Business Analyst
+
+Acts as an experienced Business Analyst (BA) who can run requirements work end-to-end and speak fluently in specific enterprise domains.
+
+## How to use this skill
+
+1. **Requirements/process work** (BRD, FRD, user stories, use cases, process maps, stakeholder or gap analysis) → use the **BA Core Toolkit** below.
+2. **Domain-specific question** (ERP, MRP, CRM, SCM, HCM, Financial Systems) → open the matching file in `references/` for module breakdowns, terminology, common pain points, and sample requirements. Load only the reference file(s) relevant to the user's question.
+3. **Mixed request** (e.g. "write a BRD for a CRM implementation") → combine both: use the BA Core Toolkit for structure/format, and the relevant domain reference for accurate content and terminology.
+4. If the domain isn't listed in `references/`, apply general BA method and note that domain-specific detail wasn't available rather than inventing terminology.
+
+---
+
+## BA Core Toolkit
+
+### Elicitation techniques
+- **Interviews** — 1:1 with stakeholders for depth; best early in discovery.
+- **Workshops (JAD sessions)** — group requirements gathering; good for resolving cross-functional conflicts fast.
+- **Document analysis** — mining existing SOPs, contracts, system docs for as-is state.
+- **Observation (job shadowing)** — watching actual work to catch requirements people don't think to mention.
+- **Surveys** — scaling input across many stakeholders when interviews aren't feasible.
+- **Prototyping** — mockups/wireframes to validate understanding before full build.
+
+### Documentation types
+| Document | Purpose | Audience |
+|---|---|---|
+| **BRD** (Business Requirements Document) | Captures *why* — business needs, objectives, scope, success criteria | Sponsors, stakeholders |
+| **FRD** (Functional Requirements Document) | Captures *what* the system must do, in detail | Dev/QA teams |
+| **User Story** | Small, testable slice of functionality: *"As a [role], I want [goal], so that [benefit]"* | Agile teams |
+| **Use Case** | Actor-system interaction flow, incl. alternate/exception paths | Dev/QA, detailed design |
+| **Process Map (BPMN)** | Visual as-is/to-be workflow | Cross-functional stakeholders |
+
+### Analysis techniques
+- **Gap Analysis** — compare current state ("as-is") to desired state ("to-be"); identify what's missing.
+- **SWOT** — Strengths, Weaknesses, Opportunities, Threats; used in strategic/initial scoping.
+- **MoSCoW prioritization** — Must have / Should have / Could have / Won't have, for scope negotiation.
+- **RACI matrix** — Responsible, Accountable, Consulted, Informed; clarifies decision rights across stakeholders.
+- **Root Cause Analysis (5 Whys, fishbone)** — for diagnosing a business problem before jumping to a solution.
+- **Cost-Benefit / ROI analysis** — justifies a proposed change financially.
+
+### Stakeholder analysis
+- Map stakeholders on **power vs. interest** to decide engagement level (manage closely, keep satisfied, keep informed, monitor).
+- Identify the **process owner** (accountable for outcomes) vs. **end users** (day-to-day operators) — their requirements often differ and both matter.
+
+### Requirements quality checklist
+A good requirement is: Clear, Unambiguous, Testable, Traceable (to a business objective), and Feasible. Flag requirements that fail these — e.g. vague ("system should be fast") needs a measurable target ("page load under 2 seconds").
+
+---
+
+## Domain References
+
+| Domain | File | Covers |
+|---|---|---|
+| ERP | `references/erp.md` | Core modules, major vendors, fit-gap, data migration, integration |
+| MRP | `references/mrp.md` | BOM, MPS, lot sizing, capacity planning, MRP I vs II |
+| CRM | `references/crm.md` | Lead-to-cash pipeline, marketing automation, service/support, vendors |
+| SCM | `references/scm.md` | Procurement, logistics, warehouse mgmt, demand planning, S&OP |
+| HCM | `references/hcm.md` | Payroll, recruiting (ATS), performance mgmt, benefits admin |
+| Financial Systems | `references/financial-systems.md` | GL, AP/AR, budgeting, financial close, compliance (SOX) |
+
+---
+
+## General Directives
+- Lead with the **business problem**, not the system — a BA's job is translating business need into requirements, not selling a tool.
+- Always distinguish **as-is vs. to-be** explicitly; conflating them causes scope confusion.
+- When comparing systems/modules, note tradeoffs rather than declaring a single "best" — fit depends on company size, industry, and existing tech stack.
+- Flag when a "requirement" is actually a **solution in disguise** (e.g. "we need a dropdown for X" is a UI solution — the real requirement is what decision that dropdown supports).
+- Keep terminology consistent with the domain reference in use; enterprise systems overload terms (e.g. "order" means different things in CRM vs. ERP vs. MRP).

package/dist/skills/enterprise-systems-analyst/references/crm.md

@@ -0,0 +1,41 @@
+# CRM (Customer Relationship Management)
+
+## What it is
+A system for managing all interactions with prospects and customers across marketing, sales, and service — the goal is a single view of the customer relationship instead of contact info scattered across inboxes and spreadsheets.
+
+## Core functional areas
+- **Lead/Contact Management** — capturing and qualifying prospects, deduplication, contact/account hierarchy.
+- **Sales Pipeline Management** — opportunity stages, forecasting, quote generation, deal tracking.
+- **Marketing Automation** — email campaigns, lead scoring, nurture sequences, campaign ROI tracking.
+- **Customer Service/Support** — case/ticket management, SLAs, knowledge base, omnichannel support (chat, email, phone).
+- **Reporting/Analytics** — pipeline health, conversion rates, customer lifetime value (CLV), churn.
+
+## The lead-to-cash flow (typical)
+Lead → Marketing Qualified Lead (MQL) → Sales Qualified Lead (SQL) → Opportunity → Quote → Closed-Won/Lost → (handoff to ERP for order fulfillment/invoicing, if separate systems).
+
+## Major vendors (landscape, not endorsements)
+- **Enterprise:** Salesforce, Microsoft Dynamics 365 Sales, Oracle CX
+- **Mid-market/SMB:** HubSpot, Zoho CRM, Pipedrive
+- **Industry-specific:** Veeva (life sciences), ServiceTitan (field service)
+
+## Common BA tasks
+- Defining lead scoring/qualification criteria (what makes a lead "sales-ready").
+- Mapping the sales stage definitions and required exit criteria per stage (prevents deals "stuck" in a stage indefinitely).
+- Specifying CRM-to-ERP integration points (e.g. Closed-Won opportunity should create a sales order in ERP without duplicate data entry).
+- Data quality/dedup rules — CRM data rots fast without governance (duplicate accounts, stale contacts).
+- Defining SLA rules for support cases (response time by priority/tier).
+
+## Common pain points driving CRM projects
+- Sales reps tracking deals in personal spreadsheets — no pipeline visibility for leadership.
+- Marketing and sales disagreeing on what counts as a qualified lead (misalignment kills conversion).
+- No single customer view — support doesn't know what sales promised, sales doesn't know open support issues.
+- Manual, error-prone handoff from "deal closed" to actual order fulfillment.
+
+## Sample requirements (illustrative)
+- *"As a Sales Manager, I want automated stage-to-stage validation (e.g. can't move to 'Proposal' without an attached quote), so that pipeline data reflects real deal status."*
+- *"As a Marketing Manager, I want leads auto-routed to the right sales rep based on territory and lead score, so that hot leads aren't sitting unassigned."*
+- *"As a Support Agent, I want to see a customer's full purchase history and open opportunities on the case screen, so that I can respond with full context."*
+
+## Terminology notes
+- "Opportunity" (CRM) ≠ "Order" (ERP) — an opportunity becomes an order only after it's won; conflating them in requirements causes integration design errors.
+- "Account" in CRM usually means a company/organization, not a financial ledger account (as in ERP) — always clarify in cross-domain requirements docs.

package/dist/skills/enterprise-systems-analyst/references/erp.md

@@ -0,0 +1,40 @@
+# ERP (Enterprise Resource Planning)
+
+## What it is
+A single integrated system that manages core business processes — finance, procurement, inventory, manufacturing, sales, HR — on one shared database, so departments stop working off disconnected spreadsheets and siloed tools.
+
+## Core modules
+- **Financials / GL** — general ledger, accounts payable/receivable, fixed assets, financial close.
+- **Procurement** — purchase requisitions, purchase orders, vendor management, three-way match (PO/receipt/invoice).
+- **Inventory Management** — stock levels, warehouse locations, stock transfers, cycle counting.
+- **Manufacturing/Production** — work orders, BOM, shop floor control (often integrates with or includes MRP — see `mrp.md`).
+- **Sales & Order Management** — quote-to-order, order fulfillment, invoicing.
+- **HR/Payroll** — often a lighter module vs. dedicated HCM systems (see `hcm.md`).
+- **Reporting/BI** — cross-module dashboards and analytics.
+
+## Major vendors (landscape, not endorsements)
+- **Enterprise/large:** SAP S/4HANA, Oracle Fusion Cloud ERP
+- **Mid-market:** Microsoft Dynamics 365, NetSuite, Infor, Epicor
+- **Manufacturing-focused:** SAP Business One, Sage X3
+
+## Common BA tasks on ERP projects
+- **Fit-gap analysis** — compare out-of-box ERP functionality against documented business requirements; classify gaps as configuration, customization, or process-change-instead.
+- **Business process reengineering** — ERP implementations often force process standardization; BA reconciles "how we do it today" against the system's native workflow.
+- **Data migration requirements** — define what master data (customers, vendors, items, chart of accounts) must migrate, cleansing rules, and mapping from legacy systems.
+- **Integration mapping** — document what other systems (CRM, e-commerce, banking, EDI) must connect to the ERP, and via what method (API, middleware, flat file).
+- **Role/security matrix** — define who can see/do what (segregation of duties matters a lot here for financial controls).
+
+## Common pain points driving ERP projects
+- Disconnected systems causing duplicate data entry and reconciliation effort.
+- No real-time visibility into inventory, cash position, or order status.
+- Manual, error-prone month-end close.
+- Inability to scale reporting/compliance as the company grows (e.g. multi-entity, multi-currency).
+
+## Sample requirements (illustrative)
+- *"As a Controller, I want the system to auto-post inventory transactions to the GL in real time, so that financial reports reflect current inventory value without manual journal entries."*
+- *"As a Purchasing Manager, I want a three-way match between PO, receipt, and invoice before an invoice can be paid, so that we prevent duplicate or fraudulent payments."*
+- *"As an Operations Director, I want role-based dashboards showing open orders by warehouse, so that fulfillment bottlenecks are visible without pulling manual reports."*
+
+## Terminology notes
+- "Order" in ERP usually means a **sales order** or **purchase order** — distinct from a CRM "opportunity" or MRP "work order."
+- "Chart of Accounts" (COA) is the backbone of financial reporting — changes to it late in a project are costly.

package/dist/skills/enterprise-systems-analyst/references/financial-systems.md

@@ -0,0 +1,35 @@
+# Financial Systems
+
+## What it is
+Covers the systems and processes for recording, controlling, and reporting a company's financial position — usually the financial core of an ERP, but sometimes a standalone/best-of-breed system.
+
+## Core functional areas
+- **General Ledger (GL)** — the system of record for all financial transactions, organized by Chart of Accounts.
+- **Accounts Payable (AP)** — vendor invoices, payment processing, three-way match (PO/receipt/invoice).
+- **Accounts Receivable (AR)** — customer invoicing, cash application, collections, aging.
+- **Fixed Assets** — asset tracking, depreciation schedules, disposal.
+- **Budgeting/Planning (FP&A)** — budget creation, forecasting, variance analysis.
+- **Financial Close/Consolidation** — month/quarter/year-end close process, multi-entity consolidation, intercompany eliminations.
+- **Financial Reporting/Compliance** — statutory reporting, audit trail, controls (e.g. SOX in the US).
+
+## Common BA tasks
+- Documenting the close process calendar and identifying manual/bottleneck steps (a classic driver for financial systems projects).
+- Defining approval workflows and segregation-of-duties requirements (who can create a vendor vs. approve a payment — critical for fraud prevention and audit).
+- Mapping Chart of Accounts structure and multi-entity/multi-currency requirements.
+- Specifying audit trail requirements (who changed what, when — often a hard compliance requirement, not optional).
+- Reconciliation requirements between subledgers (AP, AR, Fixed Assets) and the GL.
+
+## Common pain points driving financial systems projects
+- Slow, manual month-end close (spreadsheet consolidation across entities).
+- Weak controls — same person can create and approve a payment (audit finding waiting to happen).
+- No real-time visibility into cash position or budget-vs-actual.
+- Difficulty supporting multi-entity/multi-currency/multi-GAAP reporting as the company scales.
+
+## Sample requirements (illustrative)
+- *"As a Controller, I want automated intercompany elimination entries during consolidation, so that the close process doesn't rely on manual spreadsheet reconciliation."*
+- *"As an AP Clerk, I want the system to block invoice approval when a vendor is flagged as a duplicate or inactive, so that we prevent erroneous payments."*
+- *"As a CFO, I want real-time budget-vs-actual dashboards by department, so that spending overruns are visible before period-end instead of after."*
+
+## Terminology notes
+- "Close" refers to the period-end financial close process — distinct from "closing" a sales opportunity (CRM) or "closing" a work order (MRP/manufacturing). Always disambiguate in cross-domain documentation.
+- SOX (Sarbanes-Oxley) compliance applies to US public companies and drives strict controls/audit-trail requirements — flag as a hard constraint, not a nice-to-have, when applicable.