@techshan/ims-agent-skill

The knowledge pack that lets an AI coding agent work on — or integrate with — TECHSHAN-IMS without guessing.

TECHSHAN-IMS is a multi-tenant inventory, point-of-sale, accounting, HR and e-commerce platform for every kind of business: shops, groceries, pharmacies, restaurants, salons, repair workshops, hotels, wholesalers, manufacturers and digital sellers. It is one product (web, mobile, desktop and a public marketplace) with a public API of about 1,380 endpoints and an MCP server for AI assistants.

This package is two Markdown documents an agent reads before it touches the code or the API. They hold what the source code alone cannot tell it: why the system is shaped the way it is, the rules each written after a real defect, how to prove a change works, and what every module does for the person using it.

Works with any agent that can read a file: Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, Devin, Antigravity, or your own.

What is inside

SKILL.md: how to work in the repository

| Section | What the agent learns | |---|---| | Architecture & scope | The monorepo: Express/TypeScript backend, Next.js web app, Electron desktop shell, Expo mobile app (web app in a hardened WebView plus eight native offline pages), the global marketplace, the MCP server, nginx, load tests and recovery scripts. | | 24 working rules | Each one is the residue of a real defect: money reaches the ledger through one posting boundary; derived caches the database refuses to let you write; migrations never edited once applied; a document without a location is worse than one refused; every /api router is either on the public API or excluded for a stated reason; PgBouncer transaction mode means no session state; nothing shared lives in process memory; background jobs state their tenant scope; document numbers come from a counter, not MAX()+1; every email is built from the email kit. | | Validation & verification | The exact commands: type checks, the backend suite (with the three traps that produced false "passing" results), module workflow suites with their pass counts, standing invariants (and why their clean number is not always zero), fresh-install proofs that build from an empty database, and the business-template gate. | | The public API | /api/v1 mounts the same routers the dashboard uses: an API key acts as a person (its bound user's role and sites), scopes narrow access and never widen it, a switched-off business feature answers CAPABILITY_DISABLED, and the discovery endpoints (/api/v1, /endpoints, /openapi.json, /whoami) are generated from the live route table. | | The MCP server | How the downloadable techshan-ims-mcp.mjs is built and served, its nine tools, read/write separation, bulk import, loading a catalogue of eBooks with their files, and how it explains switched-off features instead of retrying. | | Business templates & capabilities | The 15 business types, the 20 feature switches, where they are enforced (API, menus, item editor, till, mobile), and how to add a feature without changing anything for existing companies. | | Scale & operations | PgBouncer, the API/worker split, replicas, Redis-backed caches and rate limits, the reporting pool, the webhook inbox, ledger month balances, request tracing, Prometheus metrics, and recovery (point-in-time, off-site, per-shop backups). | | Compliance & legal | Versioned policies with re-acceptance, consent records, data export and deletion, marketing mail with one-click unsubscribe, takedown workflow, per-country rules, a tamper-evident audit log. | | Security architecture | Storage split by trust, tenant isolation in every statement plus row-level security, a restricted database role, scoped API keys, step-up verification, append-only audit logs, and the known-fragile areas. | | Module deep-dives | POS terminals, the general ledger, recurring orders. |

SYSTEM_KNOWLEDGE.md: what the product is

A manual for an agent that has never seen the UI. It covers every module, page, automation and integration:

• Core retail: inventory (goods, services, digital, units, variants, serials), batches & expiry, dashboards and the live Today band, warehouses, purchasing, POS with split payments, tips, deposits and trade-ins, terminals and cashier shifts, recurring orders, returns.
• Business types & trade features: job cards, appointments and packages, tables and kitchen display, price lists, prescriptions and eye tests, warranty, metal-rate pricing and old gold, off-cuts, recipes and kits, stays.
• E-commerce: online orders, reviews, Stripe, store settings, shipment tracking.
• Finance: double-entry general ledger, financial statements, fiscal years and year-end close, tax returns, import/export.
• People & settings: staff, HR & payroll, shift management, business setup, the onboarding guide, self-service registration.
• Clients: desktop (Electron), mobile (hybrid, offline-first), global web marketplace.
• Integration surface: the public API and the MCP server.
• Security, operations & compliance.

Install

npm install --save-dev @techshan/ims-agent-skill

The files land in node_modules/@techshan/ims-agent-skill/.

Use it with your agent

Point the agent at the two files. Some common set-ups:

Claude Code (as a skill):

mkdir -p .claude/skills/techshan-ims
cp node_modules/@techshan/ims-agent-skill/SKILL.md .claude/skills/techshan-ims/SKILL.md
cp node_modules/@techshan/ims-agent-skill/SYSTEM_KNOWLEDGE.md .claude/skills/techshan-ims/

Cursor / Windsurf (project rules): reference both files from your rules file, or copy SKILL.md into .cursor/rules/.

Codex / Gemini CLI / Copilot: add a line to AGENTS.md, GEMINI.md or .github/copilot-instructions.md:

Before working on TECHSHAN-IMS, read node_modules/@techshan/ims-agent-skill/SKILL.md
(how to work in the repo) and SYSTEM_KNOWLEDGE.md (what the product does).

Any other agent: include the files in its context, or tell it to read them first.

Example prompts

Read the TECHSHAN-IMS skill, then add a "loyalty tier" column to the customer export and prove it with the backend suite.

Using the IMS skill's API section, write a script that pulls yesterday's sales dashboard through /api/v1/dashboard/sales with an API key.

Following the skill's email-kit rule, add a "low stock" email and send me a preview.

Working with a live company account

To let an assistant read and manage a company's data rather than its code, use the MCP server: download techshan-ims-mcp.mjs from the IMS dashboard (Settings → API Keys → Download MCP server) and add it to your MCP client with an API key. The skill's MCP Server section explains its tools and safety model.

Changelog

3.0.0 (2026-10-04): covers the platform through 2026-10-04.

• Business templates and capabilities (Module 33): 15 templates, 20 capabilities, the CAPABILITY_DISABLED gate, and Business setup in sign-up, onboarding and Settings.
• Trade features: job cards, appointments and packages, dining and kitchen, price lists, prescriptions and eye tests, warranty and trade-ins, metal rates and old gold, units, weighed items and off-cuts, recipes and kits, deposits, tips, service charge, split payments.
• Public API: thirty trade-feature routers bridged (143 groups, ~1,380 endpoints) with four new scopes, a test that fails if a router is neither bridged nor denied, and whoami reporting the company's business setup. MCP server v1.3.0.
• Bulk import: takes services, sold-by, durations, commission, warranty and prescription-only columns; blank cells keep values; exports round-trip.
• Scalability and operations: PgBouncer by default, the IMS_ROLE worker split, replicas, Redis caches and limits, reporting pool, webhook inbox, ledger month balances, request tracing and metrics. Backups: point-in-time recovery off-site, Google Drive, per-shop. Production under row-level security as a restricted role.
• Product: the compliance framework, the hybrid mobile app, and a unified professional email system (one kit, templates by area, preview script).
• Working rules 17–24.

2.2.0: row-level security (migration 134) as the second half of tenant isolation; the retirement of request-path self-healing DDL; the five rebuilt dashboards on the public API; the Batches, Expiry & Returns module; self-service registration with an emailed code and a 30-day trial; MCP server v1.2.0; the digital-goods upload ceiling raised to 2 GB.

2.1.0: MCP server v1.1.0 (download from Settings → API Keys, ims_create_digital_products, ims_upload_digital_file), digital-goods columns in the inventory import, mobile parity additions.

License

MIT