moicle 1.7.0 → 2.1.0

package/assets/skills/docs/write/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: docs-write
+description: Documentation workflow for authoring project documentation manually. Use when documenting, writing docs, generating documentation, or when user says "document", "generate docs", "write docs", "create documentation", "update docs".
+---
+
+# Documentation Workflow
+
+Hand-author project docs (README, API.md, ARCHITECTURE.md, CONTRIBUTING.md) with full control over voice and structure. For automated batch generation of a whole `docs/` tree with a review loop, use `/docs:sync` instead.
+
+## When to use this skill
+
+- ✅ Authoring or updating a specific document
+- ✅ Need opinionated prose, not just structure
+- ✅ Doc is small / scoped — a single file or section
+- ❌ Want automated multi-doc generation → use `/docs:sync`
+- ❌ Just need API reference from OpenAPI → use `/feature:api` Phase 4
+
+## Read Architecture First
+
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + stack doc. Docs must reflect the architecture, not contradict it.
+
+---
+
+## Workflow
+
+```
+SCAN → ANALYZE → GENERATE → REVIEW (loop)
+```
+
+---
+
+## Phase 1: SCAN
+
+```bash
+tree -L 3 -I 'node_modules|vendor|dist|build'
+find . -maxdepth 3 -name "*.md" -o -name "README*"
+```
+
+Identify what needs work:
+- README (project overview)
+- API.md (endpoints, schemas)
+- ARCHITECTURE.md (system design)
+- CONTRIBUTING.md (dev setup, PR flow)
+- Setup / deployment / runbook
+- DB schema, config reference
+
+### Gate
+- [ ] Architecture doc read
+- [ ] Existing docs inventoried
+- [ ] Gaps identified, priorities set
+
+---
+
+## Phase 2: ANALYZE
+
+For each doc define:
+- **Purpose** — what problem does this solve?
+- **Audience** — new contributor / API consumer / on-call?
+- **Source** — which files / sections of the code feed this doc?
+
+### Required sections per doc type
+
+**README.md**
+- One-line description + badges
+- Quick start (≤5 commands)
+- Tech stack (link to architecture)
+- Common commands (build / test / lint / dev)
+- Project structure (top 2 levels only)
+- Link to ARCHITECTURE.md / CONTRIBUTING.md / API.md
+
+**API.md**
+- Auth method + how to obtain credentials
+- Base URL per environment
+- Per endpoint: method, path, request, response, errors, example
+- Pagination convention (one block, not per endpoint)
+- Error response format (one block, not per endpoint)
+- Rate limits, versioning policy
+
+**ARCHITECTURE.md**
+- One mermaid layer diagram
+- Domain list with 1-line responsibility
+- Cross-domain communication pattern (events)
+- Key tech decisions (DB, queue, auth) with rationale
+- Link to `~/.claude/architecture/<stack>.md` for layer rules
+
+**CONTRIBUTING.md**
+- Local dev setup (prerequisites + ≤5 steps)
+- Branch + commit conventions
+- PR flow + review expectations
+- Test commands + coverage expectations
+- Where to ask for help
+
+### Gate
+- [ ] Each doc has purpose, audience, source
+- [ ] Required sections listed
+- [ ] Aligned with architecture doc
+
+---
+
+## Phase 3: GENERATE
+
+### Rules
+- **Use real code from the repo** — never invent examples
+- **Link to architecture docs**, don't duplicate them
+- **Code blocks must be runnable** — copy verbatim from working files
+- **Diagrams** — mermaid; one per major concept
+- **Tables** for any list with >3 parallel items (endpoints, env vars, commands)
+
+### Minimal skeletons
+
+Use these as starting points. For full templates, see `/docs:sync` (which generates the full set).
+
+**README.md** (≤80 lines for most projects)
+```markdown
+# {Project Name}
+
+> One-line value proposition.
+
+## Quick Start
+```bash
+{install}
+{run}
+```
+
+## Tech Stack
+- {language + version}, {framework}, {DB / queue}
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## Commands
+| Command | Purpose |
+|---------|---------|
+| `{cmd}` | {what} |
+
+## Docs
+- [API.md](./API.md) · [ARCHITECTURE.md](./ARCHITECTURE.md) · [CONTRIBUTING.md](./CONTRIBUTING.md)
+```
+
+**API.md** (per-endpoint block)
+```markdown
+### POST /resource
+
+Create a resource. Idempotent via `Idempotency-Key` header.
+
+**Auth:** Bearer
+
+**Request**
+```json
+{ "field": "value" }
+```
+
+**Response 201**
+```json
+{ "id": "...", "field": "value" }
+```
+
+**Errors:** `invalid_field` 400 · `unauthorized` 401 · `already_exists` 409
+```
+
+**ARCHITECTURE.md** opener
+```markdown
+# Architecture
+
+## Overview
+{1-2 paragraphs: what this system does, key constraints}
+
+## Layers
+```mermaid
+graph TD
+  App[Application] --> Domain
+  Domain --> Infra[Infrastructure]
+```
+See [DDD rules](~/.claude/architecture/ddd-architecture.md) for layer details.
+
+## Domains
+| Domain | Responsibility |
+|--------|---------------|
+| {name} | {one line} |
+```
+
+**CONTRIBUTING.md** opener
+```markdown
+# Contributing
+
+## Setup
+```bash
+{1-5 commands}
+```
+
+## Branch + Commits
+- Branch: `{prefix}/{ticket}-{slug}`
+- Commit: Conventional Commits
+
+## PR Flow
+1. Open PR vs `{base}`
+2. CI green
+3. ≥1 review approval
+4. Squash merge
+```
+
+### Gate
+- [ ] All planned docs drafted
+- [ ] Code examples taken from real files
+- [ ] Diagrams render
+- [ ] Cross-links between docs work
+
+---
+
+## Phase 4: REVIEW
+
+### Per-doc checklist
+- [ ] Reflects current architecture (not outdated)
+- [ ] All commands run as written (try them)
+- [ ] All file paths exist
+- [ ] All endpoints / functions referenced still exist
+- [ ] Internal + external links resolve
+- [ ] Code blocks compile / are valid syntax
+- [ ] Diagrams match actual code structure
+
+### Cross-doc consistency
+- [ ] Same terminology everywhere (e.g., "domain" vs "module")
+- [ ] No duplicated info — link instead
+
+### Loop
+If any issue → return to Phase 3 for that doc, fix, re-review.
+
+---
+
+## Final Report
+
+```markdown
+## Documentation Update
+
+### Files
+- `README.md` — {changes}
+- `API.md` — {changes}
+- `ARCHITECTURE.md` — {changes}
+- `CONTRIBUTING.md` — {changes}
+
+### Verification
+- [x] All commands tested
+- [x] All links resolve
+- [x] All examples compile
+```
+
+---
+
+## Hard Rules
+
+- **Real examples only** — invented code drifts and lies
+- **Link, don't duplicate** — refer to architecture docs, don't restate rules
+- **Test every command** before publishing
+- **Update the doc when you change the code** — stale docs are worse than no docs
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Generate full doc site from codebase | `/docs:sync` |
+| Document a newly added API endpoint | `/feature:api` Phase 4 |
+| Onboard self / new dev | `/research:onboarding` |
+| Write blog / social content | `/marketing:content` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| SCAN | `@clean-architect` | Identify doc needs |
+| ANALYZE (API) | `@api-designer` | API doc structure |
+| ANALYZE (DB) | `@db-designer` | Database doc structure |
+| GENERATE | `@docs-writer` | Write all docs |
+| REVIEW | `@code-reviewer` | Verify accuracy vs code |

package/assets/skills/feature/api/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: feature-api
+description: API integration workflow for adding new endpoints or integrating external APIs. Use when adding API endpoints, integrating third-party APIs, or when user says "integrate api", "add endpoint", "new api", "connect api", "api integration".
+---
+
+# API Integration Workflow
+
+End-to-end workflow for designing, implementing, testing, and documenting APIs — both internal endpoints and third-party integrations.
+
+## When to use this skill
+
+- ✅ Adding a new REST / GraphQL endpoint to your service
+- ✅ Integrating a third-party API (Stripe, OpenAI, etc.) into the system
+- ✅ Replacing or upgrading an existing API integration
+- ❌ Just need a one-off HTTP call in a script → use Bash directly
+- ❌ Need to research which API to use → use `/research:web` first
+- ❌ Building a whole new domain → use `/feature:new` (which calls this skill internally for the API surface)
+
+---
+
+## Workflow
+
+```
+DESIGN → IMPLEMENT → TEST → DOCUMENT → REVIEW LOOP
+```
+
+## Read Architecture First
+
+Before any phase, read:
+1. `~/.claude/architecture/ddd-architecture.md` (core DDD)
+2. Stack-specific doc (`go-backend.md`, `nodejs-nestjs.md`, etc.)
+3. Existing API conventions in the project (look at 1–2 existing endpoints as reference)
+
+---
+
+## Phase 1: DESIGN
+
+**Goal:** lock the API contract before writing any code.
+
+### Actions
+1. Identify API type: REST / GraphQL / gRPC / third-party client
+2. Define contract:
+   - Endpoints / operations (method + path)
+   - Request / response schema (use real types from domain entities)
+   - Auth method
+   - Error codes per endpoint
+   - Pagination (cursor or offset) — pick ONE, apply to all list endpoints
+   - Idempotency keys for POST/PUT (if applicable)
+3. Write the contract as **OpenAPI 3.0** (REST) or **GraphQL SDL**
+
+### Minimal OpenAPI skeleton
+
+```yaml
+openapi: 3.0.0
+info: { title: <name>, version: 1.0.0 }
+servers: [{ url: https://api.example.com/v1 }]
+components:
+  securitySchemes:
+    BearerAuth: { type: http, scheme: bearer }
+  schemas:
+    Error: { type: object, properties: { code: { type: string }, message: { type: string } } }
+paths:
+  /resource:
+    post:
+      summary: Create resource
+      security: [{ BearerAuth: [] }]
+      requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/CreateInput' } } } }
+      responses:
+        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/Resource' } } } }
+        '400': { description: Validation error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
+```
+
+### Gate
+- [ ] Endpoints listed in a table (method, path, auth, purpose)
+- [ ] Request / response schemas defined
+- [ ] Error codes listed (with stable string codes, not just HTTP status)
+- [ ] Pagination strategy chosen (cursor preferred)
+- [ ] **User CONFIRMED contract** before continuing
+
+---
+
+## Phase 2: IMPLEMENT
+
+**Goal:** implement the contract per stack conventions, respecting DDD layers.
+
+### Layered placement (DDD)
+
+| Concern | Layer | Notes |
+|---------|-------|-------|
+| Route definition | `application/ports/http/` | Thin handler: parse → service → respond |
+| Request / Response DTOs | `application/ports/http/dto/` | NOT domain types |
+| Validation | Handler or domain (depending on stack) | Reject bad input before reaching usecase |
+| Business logic | `domain/{domain}/usecases/` | NEVER in the handler |
+| External API client | `infrastructure/adapters/` | Implements a port in `domain/{domain}/ports/` |
+| Auth check | Middleware / decorator | NOT inline in handler |
+
+### Standard error response
+
+All endpoints return errors in the same shape:
+
+```json
+{ "error": { "code": "STRING", "message": "human-readable", "details": {} } }
+```
+
+`code` is stable across versions; `message` may change. Map domain errors → HTTP codes in ONE place (middleware / interceptor).
+
+### Standard pagination (cursor)
+
+```
+GET /resource?cursor=<opaque>&limit=<int 1..100, default 20>
+→
+{
+  "data": [...],
+  "pagination": { "next_cursor": "..." | null }
+}
+```
+
+### Gate
+- [ ] Routes registered in router / app module
+- [ ] Handler is thin (parse → service → respond)
+- [ ] Business logic in usecase, not handler
+- [ ] External calls go through infrastructure adapter
+- [ ] Auth + validation in middleware, not handler
+- [ ] Build passes: `{stack_build_command}`
+
+---
+
+## Phase 3: TEST
+
+**Goal:** verify the contract holds and breaks safely.
+
+### Test layers
+
+| Layer | Type | What |
+|-------|------|------|
+| Handler | Unit | Validation, error mapping (mock service) |
+| UseCase | Unit | Business logic (mock port) |
+| Adapter (external API) | Integration | Real HTTP call to sandbox OR contract test with `nock` / `WireMock` |
+| End-to-end | Integration | Full request → response, real DB |
+
+### Mandatory test cases per endpoint
+- [ ] Happy path
+- [ ] Auth failure (missing / invalid token)
+- [ ] Validation failure (each required field missing)
+- [ ] Permission failure (valid token, wrong scope)
+- [ ] Not found (where applicable)
+- [ ] Rate limit / quota (where applicable)
+- [ ] Idempotency (POST with same key returns same response)
+
+### Gate
+- [ ] All mandatory cases covered
+- [ ] Tests pass: `{stack_test_command}`
+- [ ] Error response shape verified in tests
+
+---
+
+## Phase 4: DOCUMENT
+
+**Goal:** update API docs so consumers can use it without reading code.
+
+### What to update
+1. **OpenAPI spec** committed to repo (`openapi.yaml` or per-resource files)
+2. **API.md** — append the new endpoint(s) (or refer to `/docs:write` skill for full re-author)
+3. **CHANGELOG.md** — note breaking / additive changes
+4. **README.md** — if this changes quick-start
+
+### Endpoint doc entry (minimal)
+
+```markdown
+### POST /resource
+
+Create a resource. Idempotent via `Idempotency-Key` header.
+
+**Auth:** Bearer
+
+**Request**
+```json
+{ "field": "value" }
+```
+
+**Response 201**
+```json
+{ "id": "...", "field": "value" }
+```
+
+**Errors**
+| Code | HTTP | Meaning |
+|------|------|---------|
+| `invalid_field` | 400 | `field` failed validation |
+| `unauthorized` | 401 | Token missing or invalid |
+| `already_exists` | 409 | Same idempotency key with different body |
+```
+
+### Gate
+- [ ] OpenAPI spec updated and lints
+- [ ] API.md entry added
+- [ ] CHANGELOG entry
+- [ ] At least 1 example request runs successfully (curl / Postman)
+
+---
+
+## Phase 5: REVIEW LOOP
+
+Run `/review:architect` for the touched domain. Loop until score ≥ B.
+
+```
+LOOP:
+  1. Run /review:architect {stack} {domain}
+  2. Fix violations
+  3. Re-run tests + build
+  4. GOTO 1 (until score ≥ B)
+```
+
+---
+
+## Final Report
+
+```markdown
+## API Integration Complete
+
+### Endpoints Added / Changed
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | /v1/resource | Create resource |
+
+### Files Created
+- `application/ports/http/resource_handler.{ext}`
+- `domain/{domain}/usecases/create_resource.{ext}`
+- `infrastructure/adapters/{external_service}.{ext}` (if applicable)
+
+### Tests
+- {N} test files, {M} test cases
+- Coverage: handler, usecase, adapter, e2e
+
+### Documentation
+- [x] OpenAPI spec updated
+- [x] API.md entry added
+- [x] CHANGELOG entry
+
+### Review Score: {A/B}
+```
+
+---
+
+## Hard Rules
+
+- **NEVER put business logic in the handler** — handler is thin parse-call-respond
+- **NEVER call an external API directly from a usecase** — go through an infrastructure adapter that implements a domain port
+- **Error codes are stable strings**, not just HTTP status — frontend/SDK depend on them
+- **Pick one pagination style** for the whole API (cursor preferred), don't mix
+- **Idempotency key required** for any POST that creates state
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Designing the API contract from scratch | `@api-designer` agent |
+| Adding the endpoint as part of a larger feature | `/feature:new` (calls this internally) |
+| Writing tests for the endpoint | `/review:tdd` |
+| Documenting the full API surface | `/docs:write` |
+| Reviewing architecture compliance | `/review:architect` |
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| DESIGN | `@api-designer` | API contract design (OpenAPI / GraphQL) |
+| DESIGN | `@clean-architect` | Ensure DDD compliance |
+| IMPLEMENT | Stack-specific dev agent | Implementation |
+| IMPLEMENT | `@db-designer` | DB schema if new tables needed |
+| TEST | `@test-writer` | Unit + integration tests |
+| TEST | `@security-audit` | Auth / injection / rate-limit checks |
+| DOCUMENT | `@docs-writer` | OpenAPI + API.md |