# Architecture — Single-Package Multi-Feature

`@synity/bitrix-skills` uses a single npm package with a `src/features/*` layout. One publish, one changelog, one version.

## Feature structure

```
src/features/<name>/
├── feature.json      # metadata (name, displayName, version, target, requires)
├── install.ts        # install logic
└── assets/           # files to copy on install
```

## feature.json schema

```json
{
  "name": "bx-task",
  "displayName": "Bitrix Task Skill",
  "version": "1.1.0",
  "target": "global",            // "project" = installs to <projectRoot>/, "global" = ~/.claude/skills/
  "description": "...",
  "requires": {
    "mcp": ["bitrix-synity-mcp"]
  }
}
```

## Adding a new feature

1. Create `src/features/<name>/` with the structure above
2. Implement `install.ts` — export `async function install(opts: InstallOpts): Promise<InstallResult>`
3. Put assets to copy in `assets/`
4. Add `feature.json` (set `target` appropriately)
5. Run `pnpm test` — the feature registry auto-discovers it

## Shared lib (`src/lib/`)

| Module | Purpose |
|--------|---------|
| `manifest.ts` | Read/write `.bitrix-tools.json` (installed features, checksums) |
| `feature-registry.ts` | Discover features from `feature.json` files |
| `bb-formatter.ts` | Markdown → Bitrix BB code conversion |
| `time-parser.ts` | Duration format/parse (`30s`, `5m 12s`) |
| `bitrix-rest.ts` | Typed Bitrix webhook wrapper (build/test only) |
| `bb-formatter.ts` | Markdown → Bitrix BB code conversion |

## SemVer convention

- `patch` = bug fix in existing feature
- `minor` = new feature added
- `major` = breaking CLI interface change