Add State Hub bootstrap workplan and agent integration files

Seed workplans/ with bootstrap workplan to satisfy ADR-001 C-01.
Includes regenerated dev-hub session-protocol and agent instruction files.
This commit is contained in:
2026-06-22 21:44:32 +02:00
parent 2691215f62
commit 08c87dead1
14 changed files with 660 additions and 406 deletions

View File

@@ -1,58 +1,18 @@
# CLAUDE.md
# Binect-JS — Claude Code Instructions
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
@SCOPE.md
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/credential-routing.md
@.claude/rules/agents.md
## Build Commands
## Kaizen Agents
```bash
npm install # Install dependencies
npm run build # Build TypeScript to dist/
npm test # Run tests with vitest
npm run typecheck # Type check without emitting
```
## Project Overview
Binect-JS is a JavaScript/TypeScript wrapper for the Binect REST API (https://app.binect.de/index.jsp?id=api) that enables sending PDF documents as physical mail. The project consists of two artifacts:
1. **Binect-JS SDK** (`@binect/js`) - A thin API wrapper in `src/`
2. **Binect Explorer** - A browser-based interactive tool in `explorer/`
## Architecture
The SDK is organized around domain-aligned sub-clients that mirror the API vocabulary:
- `client.documents` - PDF upload, status inspection, parameter modification
- `client.attachments` - Attachment handling
- `client.sendings` - Mail dispatch triggers, cancellation
- `client.accounts` - Account management
- `client.invoices` - Invoice access
### SDK Layer Separation
**Core API Layer** (authoritative): 1:1 semantic mapping to REST endpoints. Methods like `documents.upload`, `documents.get`, `sendings.send`, `sendings.cancel`.
**Convenience Layer** (optional, non-authoritative): Additive helpers in `src/helpers.ts` like status predicates (`isShippable`), error extraction, polling helpers. These must never be the only way to perform an action.
## Design Constraints
- **No runtime dependencies**: Uses native `fetch` API only
- **No semantic reinterpretation**: Wrapper must not alter business meaning or outcomes
- **Transparency over abstraction**: Developers must reason about actual API calls
- **No default retries**: Network behavior must be explicit and opt-in
- **Authentication**: HTTP Basic Auth, credentials are ephemeral (not stored/cached)
## Key Files
- `src/client.ts` - Main BinectClient class
- `src/clients/*.ts` - Domain sub-clients
- `src/types.ts` - TypeScript type definitions
- `src/errors.ts` - BinectApiError and BinectAuthError
- `src/http.ts` - Low-level HTTP client
- `src/helpers.ts` - Convenience helpers (predicates, polling)
- `explorer/index.html` - Standalone Explorer UI
## API Integration Notes
- Uploads use base64-encoded PDFs (max 12 MB)
- All non-success responses surface as structured `BinectApiError`
- Document status codes: 1=Preparing, 2=Shippable, 3=Queue, 4=Printing, 5=Sent, 6=Canceled, 7=Error
Specialized kaizen agent personas are available on demand via the state-hub MCP —
discover with `list_kaizen_agents()` and load with `get_kaizen_agent("<name>")`,
then read and follow their instructions. Full guidance in `.claude/rules/agents.md`.