--- name: nhcx-full description: >- Build India's NHCX (National Health Claims Exchange) provider-side claims integration into an existing HMIS codebase, end to end: beneficiary policy search, coverage eligibility, the payer's insurance plan, pre-authorisation, payer queries, claim, reprocess and release, and payment notices, with the NHCX gateway (JWE, x-hcx headers, ABDM session tokens, registry, callbacks) embedded in the application. Use when adding NHCX or PMJAY cashless claims to a hospital system as a whole, or when unsure which part of NHCX is needed. metadata: version: "1.2.0" --- **Version 1.2.0**, built 2026-09-30, checked against NHA's NHCX package 1.0.0. Copied from github.com/nha-in/nhcx-skills on 1 October 2026, over commit `305efb9`. The NHCX documentation is the place to look when this folder does not carry enough. This folder is a snapshot. Re-download the whole folder from the portal's /skills/nhcx-full/ path when it is older than the work you are doing: this router and every file under `apis/`, `callbacks/`, `database/`, `fhir/`, `gateway/`, `payer/`, `references/`, `screens/`, `steps/` and `tests/`. Fetching this file alone leaves its pointers aimed at files you do not have. If the nhcx-docs MCP server is connected, trust its answers over this folder. It serves the Catalogue live, which holds 536 NHCX atoms, and this folder cites none of them. What the claims here rest on. The protocol comes from the knowledge source the skill records at its first step: the nhcx-docs MCP server, or a release of the NHCX package checked against its `MANIFEST`. What was seen only on the NHCX sandbox is marked [SANDBOX], and what depends on the payer is marked [PAYER]. **Try asking** - "Build the whole NHCX integration into this system, on whichever side it sits" - "What has to be in place before my first NHCX call?" - "Walk me through the NHCX test cases before go-live" Loaded with no task? Say in three lines what this skill does. Offer the prompts above. Then ask what the person is building, and whether the code for it exists yet. # READ FIRST: CORE Before anything else, read [references/CORE.md](references/CORE.md) and keep it in mind for the whole task. Its **Instructions** are binding: follow them strictly in every step and every file, and re-read them at the start of each step (L1 to L8). Its **Confusions** settle what easily mixed-up terms mean; when a word is ambiguous, CORE.md decides. It also holds the base URLs and, for every exchange, the route, bundle, workflow id and callback. # WHICH SIDE This skill is the **provider side**: it builds NHCX into a hospital's HMIS, the participant that asks (eligibility, plan, pre-authorisation, claim) and is answered. The folder [payer/](payer/SKILL.md) is the **payer side** of the same skill: an insurer, TPA or scheme system, the participant that answers, files cases and decides them. The two share nothing but the gateway design; their ids (S1, A1, C1) are numbered separately and never mix. Decide the side at the start of L1 discovery, before any spec is matched, and record it as `side` in `nhcx-plan/discovery.json` and in the progress log: - **provider** when the target admits patients, keeps practitioners and encounters, bills an insurer, or has a claims desk that submits: continue with this file and the specs, steps and references at this root, and ignore `payer/` entirely. - **payer** when the target keeps members or beneficiaries, products or policies and their enrolments, adjudicates claims on a desk, or disburses money: stop here, open [payer/SKILL.md](payer/SKILL.md) and follow it as the whole skill from its own L1, and ignore every spec, step and reference at this root. Everything it links to is inside `payer/`. - **both** (a system that admits patients and also runs a scheme): two integrations, one per side, each planned and logged on its own; do the side the user asked for first, and never mix the two id sets in one plan file. When in doubt, ask the user which side the target is before L1.1. A later prompt that finds the other side was meant logs a `corrected` entry and starts again from L1 on the right side. # GOAL Add NHCX provider-side claims to the target HMIS, from policy search to payment, with the NHCX gateway running inside the application. This skill holds only the specs this goal needs; the SCOPE section lists them. Specs it names but does not hold are marked with the skill that has them. # REQUIREMENTS - **The target HMIS source**, with its build, test and migration commands working. - **NHCX participant credentials** for the facility: participant code, ABDM client id and client secret, and the private key of the encryption certificate registered for that code. - **A public URL** NHCX can reach, registered as the participant's `endpoint_url`, routed to the application's inbound path (`/in/` or `/v1/`). - **A knowledge source**: the nhcx-docs MCP server, or network access to download the NHCX package (see KNOWLEDGE SOURCE). - For end-to-end tests: sandbox credentials, a sandbox payer that answers, and test beneficiaries. # KNOWLEDGE SOURCE NHCX facts (API paths and headers, FHIR profiles and example bundles, codes, workflow ids, error codes, go-live rules) come from one knowledge source, chosen at the start of L1 and recorded in `nhcx-plan/knowledge.json`. Details: [references/KNOWLEDGE.md](references/KNOWLEDGE.md). 1. **nhcx-docs MCP.** If the `nhcx-docs` MCP server is connected (`catalogue_info` answers), use it: `search_docs`, `get_operation`, `get_fhir_profile`, `get_fhir_example`, `validate_fhir`, `validate_request`, `decode_error`. 2. **GitHub package.** Otherwise download the latest release zip from [github.com/nha-in/nhcx-package/releases](https://github.com/nha-in/nhcx-package/releases) (`nhcx-package-v.zip`), keep it as `nhcx-plan/knowledge/nhcx-package-v.zip`, extract it to `nhcx-plan/knowledge/nhcx-package/`, and check it against its `MANIFEST`. On the protocol the knowledge source wins over these specs; on what the application does, the specs win. Statements that are not the protocol are marked [REF](references/PAYERS.md#markers) (a reference-implementation choice), [PAYER](references/PAYERS.md#markers) (depends on the payer adapter) or [SANDBOX](references/PAYERS.md#markers) (seen only in the sandbox); every payer-specific value is in [references/PAYERS.md](references/PAYERS.md). Its ids (NHA use cases such as `C5`) are not this skill's ids: write them as `nha:C5`. # STEPS Follow [steps/INDEX.md](steps/INDEX.md) in order. Each step writes one file under `nhcx-plan/` in the target repository, and every sub-step and file change is logged in `nhcx-plan/progress.json` and `nhcx-plan/progress.md` ([steps/LOG.md](steps/LOG.md)). At the end of every prompt, whatever it did, run the report builder to rebuild `nhcx-plan/report.html`: every plan file (progress, log, discovery, mapping, plan, code, validation, dry-run and end-to-end results) on its own tab of one self-contained page, errors first, with a refresh button; `nhcx-plan/make-report.sh` and `make-report.bat` rebuild it every 10 seconds ([steps/LOG.md](steps/LOG.md#logh-reporthtml)). 1. [L1 Discovery](steps/L1-discovery.md): the knowledge source, the target's technology, and every spec item in SCOPE found, partial or missing, with file and lines. 2. [L2 Mapping](steps/L2-mapping.md): target fields to database columns and FHIR elements. 3. [L3 Integration Planning](steps/L3-integration-planning.md): phases, steps and sub-steps for this target, in the build order of the [SCAFFOLDING](references/SCAFFOLDING.md), including the "Claims" entry on the HMIS home screen, sidebar or navbar. 4. [L4 Code Planning](steps/L4-code-planning.md): files, functions and order, laid out by mapping the [SCAFFOLDING](references/SCAFFOLDING.md) onto the target's conventions. 5. [L5 Write Code](steps/L5-write-code.md): file by file, recorded in `nhcx-plan/code.json`, keeping the scaffolding's dependency rules. 6. [L6 Validate Code](steps/L6-validate-code.md): each file against its specs. 7. [L7 Dry-run Tests](steps/L7-dry-run-tests.md): no network; fakes for NHCX and the registry. 8. [L8 End-to-end Tests](steps/L8-e2e-tests.md): against the NHCX sandbox, the T tests in [references/TESTS.md](references/TESTS.md), each run through the screens (GUI) and from the command line (CLI). # SCAFFOLDING [references/SCAFFOLDING.md](references/SCAFFOLDING.md) is the shape the code takes in the target HMIS. Read it before L3 and keep it open through L5. - **One NHCX module** (`nhcx/`) holding `gateway/` (G, in-process), `fhir/` (F, pure builders and parsers), `services/` (A), `callbacks/` (C), `models/` and `migrations/` (D), `screens/` and `routes` (S), and the message `archive`. - **Existing HMIS modules** change only for the fields NHCX needs: patient ABHA (D3), practitioner HPR id and qualification (D2), facility HFR id and participant code (D1), and the "Claims" navigation entry. - **Dependency rules:** screens call services and read models; only services and callbacks write claim tables; FHIR builders never touch the database or the gateway; the gateway knows nothing about claims; a reply found by polling is applied by the same callback handler. - **Outside the repository:** the gateway config, client secret, private key, ledger and archive directories. - **Tests** under `tests/nhcx/` (dry-run and end-to-end), and **plan files** under `nhcx-plan/`. - **Build order** in phases, from the gateway foundation to the navigation entry; L3 plans in that order and leaves out phases whose specs are not in SCOPE. L4 maps these placeholder names onto the target's own conventions (a Django app, a Spring module, a Node package); the split between parts and the dependency direction do not change. # SCOPE The specs this skill holds: - **Screens** (16): [S1](screens/S1-search-policy.md), [S2](screens/S2-select-policy.md), [S3](screens/S3-policy-discovery.md), [S4](screens/S4-claim-creation-form.md), [S5](screens/S5-claim-master.md), [S6](screens/S6-claim-detail.md), [S7](screens/S7-insurance-plan.md), [S8](screens/S8-line-items.md), [S9](screens/S9-preauthorisation.md), [S10](screens/S10-communication.md), [S11](screens/S11-claim-submission.md), [S12](screens/S12-payments.md), [S13](screens/S13-patient-list.md), [S14](screens/S14-patient-registration-form.md), [S15](screens/S15-patient-detail.md), [S16](screens/S16-practitioner-master.md) - **APIs** (16): [A1](apis/A1-policy-search.md), [A2](apis/A2-coverage-eligibility-check.md), [A3](apis/A3-insurance-plan-request.md), [A4](apis/A4-preauth-submit.md), [A5](apis/A5-claim-submit.md), [A6](apis/A6-task-submit.md), [A7](apis/A7-communication-on-request.md), [A8](apis/A8-paymentnotice-on-request.md), [A10](apis/A10-txn-related.md), [A11](apis/A11-txn-dispatch.md), [A12](apis/A12-txn-fhir.md), [A13](apis/A13-txn-list.md), [A14](apis/A14-adjudicator-user-role.md), [A15](apis/A15-adjudicator-process-case.md), [A16](apis/A16-gateway-token.md), [A17](apis/A17-claim-state.md) - **Callbacks** (10): [C1](callbacks/C1-callback-door.md), [C2](callbacks/C2-coverage-eligibility-on-check.md), [C3](callbacks/C3-auth-requirements-on-check.md), [C4](callbacks/C4-insuranceplan-on-request.md), [C5](callbacks/C5-preauth-on-submit.md), [C6](callbacks/C6-claim-on-submit.md), [C7](callbacks/C7-cancel-on-submit.md), [C8](callbacks/C8-enquiry-on-submit.md), [C9](callbacks/C9-communication-request.md), [C10](callbacks/C10-paymentnotice-request.md) - **FHIR** (19): [F1](fhir/F1-bundle.md), [F2](fhir/F2-coverage-eligibility-request.md), [F3](fhir/F3-coverage-eligibility-response.md), [F4](fhir/F4-task-insuranceplan.md), [F5](fhir/F5-insuranceplan.md), [F6](fhir/F6-questionnaire.md), [F7](fhir/F7-questionnaireresponse.md), [F8](fhir/F8-claim.md), [F9](fhir/F9-claimresponse.md), [F10](fhir/F10-task-claim-actions.md), [F11](fhir/F11-communicationrequest.md), [F12](fhir/F12-communication.md), [F13](fhir/F13-paymentnotice.md), [F14](fhir/F14-payment-acknowledgement.md), [F15](fhir/F15-patient.md), [F16](fhir/F16-practitioner.md), [F17](fhir/F17-organization.md), [F18](fhir/F18-coverage.md), [F19](fhir/F19-other-resources.md) - **Database** (30): [D1](database/D1-organization.md), [D2](database/D2-practitioner.md), [D3](database/D3-patient.md), [D4](database/D4-encounter.md), [D5](database/D5-condition.md), [D6](database/D6-observation.md), [D7](database/D7-allergy.md), [D8](database/D8-terminology.md), [D9](database/D9-claim.md), [D10](database/D10-claim-plan.md), [D11](database/D11-claim-plan-benefit.md), [D12](database/D12-claim-plan-form.md), [D13](database/D13-claim-auth.md), [D14](database/D14-claim-auth-item.md), [D15](database/D15-claim-auth-requirement.md), [D16](database/D16-claim-line.md), [D17](database/D17-claim-form-answer.md), [D18](database/D18-claim-preauth.md), [D19](database/D19-claim-predetermination.md), [D20](database/D20-claim-submission.md), [D21](database/D21-claim-payment.md), [D22](database/D22-claim-payment-detail.md), [D23](database/D23-claim-query.md), [D24](database/D24-claim-adjudication.md), [D25](database/D25-claim-diagnosis.md), [D26](database/D26-claim-care-team.md), [D27](database/D27-claim-item.md), [D28](database/D28-claim-document.md), [D29](database/D29-claim-enquiry.md), [D30](database/D30-counter.md) - **Gateway** (11): [G1](gateway/G1-embedding.md), [G2](gateway/G2-configuration.md), [G3](gateway/G3-session-token.md), [G4](gateway/G4-registry.md), [G5](gateway/G5-protocol-headers.md), [G6](gateway/G6-encryption.md), [G7](gateway/G7-send.md), [G8](gateway/G8-receive.md), [G9](gateway/G9-ledger.md), [G10](gateway/G10-beneficiary-registry.md), [G11](gateway/G11-startup-checks.md) - **Tests** (18): [T1](tests/T1-test-configuration.md), [T2](tests/T2-test-runners.md), [T3](tests/T3-irdai-policy-and-eligibility.md), [T4](tests/T4-irdai-plan-and-auth-requirements.md), [T5](tests/T5-irdai-preauth-approved.md), [T6](tests/T6-irdai-preauth-rejected.md), [T7](tests/T7-irdai-query-answered.md), [T8](tests/T8-irdai-enhancement.md), [T9](tests/T9-irdai-cancel-and-status.md), [T10](tests/T10-irdai-claim.md), [T11](tests/T11-irdai-payment.md), [T12](tests/T12-irdai-reprocess-and-release.md), [T13](tests/T13-pmjay-eligibility-and-package-master.md), [T14](tests/T14-pmjay-preauth-adjudicated.md), [T15](tests/T15-pmjay-query-by-resubmission.md), [T16](tests/T16-pmjay-rejection-and-enhancement.md), [T17](tests/T17-pmjay-claim-adjudicated.md), [T18](tests/T18-pmjay-payment-status-cancel.md) Other skills built from the same source: - **nhcx-coverage**: beneficiary policy search and coverage eligibility. - **nhcx-preauth**: pre-authorisation: the payer's plan, line items, authorisation requirements, pre-auth, enhancement, cancel and status. - **nhcx-claim**: claim submission after discharge, its verdict and status. - **nhcx-communication**: payer queries, notifications and notes, and the replies to them. - **nhcx-payment**: payment notices and their acknowledgement. - **nhcx-reprocess**: reprocess and balance release on a decided or partly paid claim. # VERSION This is nhcx-full version 1.2.0, built on 2026-09-30. Its protocol tables (workflow ids, statuses, base URLs) were checked against NHA's NHCX package 1.0.0 ([github.com/nha-in/nhcx-package](https://github.com/nha-in/nhcx-package)). - Record it when the work starts: `nhcx-plan/knowledge.json` and the `target` of `nhcx-plan/progress.json` carry `skill` and `skill_version`, and the header of `nhcx-plan/report.html` shows them. - If a later prompt runs with a different version of this skill than the one recorded, say so to the user before continuing, log it as a `corrected` entry naming both versions, and re-check the steps already done against the specs that changed. - A knowledge source newer than 1.0.0 wins on the protocol, as KNOWLEDGE SOURCE says; note the difference in `knowledge.json`. # REFERENCES - [references/CORE.md](references/CORE.md): base URLs, and every exchange with its route, bundles, workflow id and callback, on one page. - [references/KNOWLEDGE.md](references/KNOWLEDGE.md): the NHCX knowledge source, MCP or GitHub package, and which lookup answers which question. - [references/SCREENS.md](references/SCREENS.md): every screen in scope, its route and what it does. - [references/API.md](references/API.md): every API call in scope and what it does. - [references/CALLBACK.md](references/CALLBACK.md): every NHCX callback in scope and what it does. - [references/GATEWAY.md](references/GATEWAY.md): every part of the in-process NHCX gateway and what it does. - [references/FHIR.md](references/FHIR.md): every FHIR resource in scope, sent or read, and what it is. - [references/DATABASE.md](references/DATABASE.md): every table in scope, what one row is, and which screens, APIs, callbacks and FHIR resources use it. - [references/PAYERS.md](references/PAYERS.md): the payer adapters, their workflow ids and rules, and what the [REF](references/PAYERS.md#markers), [PAYER](references/PAYERS.md#markers) and [SANDBOX](references/PAYERS.md#markers) markers mean. - [references/OPERATIONS.md](references/OPERATIONS.md): production cutover, and running the application as more than one instance. - [references/TESTS.md](references/TESTS.md): every end-to-end test in scope, IRDAI and PMJAY, each run through the screens and from the command line. - [references/READSETS.md](references/READSETS.md): for each screen, API, callback and gateway part, the other specs to read before implementing it. - [references/SCAFFOLDING.md](references/SCAFFOLDING.md): the module layout in the target, what each part holds and where each spec lands. # OUTPUT In the target repository: - **Code** in the NHCX module and the changed HMIS modules, as laid out in SCAFFOLDING. - **Tests** under `tests/nhcx/`: dry-run (L7) and end-to-end (L8), the end-to-end ones with a GUI runner and a CLI runner (`nhcx-e2e`). - **Plan files** under `nhcx-plan/`: `knowledge.json`, `discovery.json`, `mapping.json`, `plan.json`, `code-plan.json`, `code.json`, `validation.json`, `dry-run.json`, `e2e.json`, the log `progress.json` with `progress.md`, and `report.html`, rebuilt at the end of every prompt by the report builder (`report.py` or the target language's equivalent) with its `make-report.sh` and `make-report.bat` beside it.