moicle 1.7.0 → 2.0.0

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

@@ -0,0 +1,371 @@
+---
+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
+
+Author project documentation manually following stack conventions. **Use this when you want full control** over the output (README, API.md, ARCHITECTURE.md, CONTRIBUTING.md). For automated batch generation with review loop, use `/docs:sync` instead.
+
+## When to use this skill
+
+- ✅ Authoring or updating a specific document (README, API, ARCHITECTURE, CONTRIBUTING)
+- ✅ Need to write opinionated prose, not just structure
+- ✅ Doc is small / scoped — a single file or section
+- ❌ Want fully automated multi-doc generation → use `/docs:sync`
+- ❌ Just need API reference from OpenAPI spec → use `/feature:api` Phase 4
+
+---
+
+## Workflow
+
+```
+SCAN → ANALYZE → GENERATE → REVIEW (loop)
+```
+
+## Read Architecture First
+
+Before writing, read:
+1. `~/.claude/architecture/ddd-architecture.md` (core)
+2. Stack-specific doc (see Stack Detection below)
+3. `.claude/architecture/` for project overrides (if any)
+
+**Documentation must accurately reflect the architecture and patterns used in the codebase.**
+
+### Stack Detection
+| File | Doc |
+|------|-----|
+| `go.mod` | `go-backend.md` |
+| `package.json` + NestJS dep | `nodejs-nestjs.md` |
+| `package.json` + Vite config | `react-frontend.md` |
+| `remix.config.*` | `remix-fullstack.md` |
+| `composer.json` | `laravel-backend.md` |
+| `pubspec.yaml` | `flutter-mobile.md` |
+
+---
+
+## Phase 1: SCAN
+
+**Goal:** identify what needs documentation.
+
+### Actions
+1. Read architecture doc for the stack
+2. Scan codebase:
+   ```bash
+   tree -L 3 -I 'node_modules|vendor|dist|build'
+   find . -maxdepth 3 -name "*.md" -o -name "README*"
+   ```
+3. Identify documentable items:
+   - README (project overview)
+   - API documentation (endpoints, schemas)
+   - ARCHITECTURE (system design, layer rules)
+   - CONTRIBUTING (dev setup, PR flow, conventions)
+   - Setup / deployment guides
+   - Database schema
+   - Configuration reference
+
+### Gate
+- [ ] Architecture doc read
+- [ ] Existing docs inventoried
+- [ ] Gaps identified
+- [ ] Priorities set (high → low)
+
+---
+
+## Phase 2: ANALYZE
+
+**Goal:** define what each document MUST contain.
+
+For each doc:
+- **Purpose** — what problem does this doc solve?
+- **Audience** — new contributor / API consumer / ops team?
+- **Source** — which files / sections of the codebase feed this doc?
+
+### Required sections per doc type
+
+**README.md** must have:
+- One-line description + badges
+- Quick start (install → run in ≤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** must have:
+- Auth method (Bearer / OAuth / API key) + how to obtain
+- Base URL per environment
+- For each endpoint: method, path, request schema, response schema, error codes, example
+- Pagination convention (one block, not per endpoint)
+- Error response format (one block, not per endpoint)
+- Rate limits, versioning policy
+
+**ARCHITECTURE.md** must have:
+- 1 mermaid diagram of the layer structure (link to `ddd-architecture.md` for rules)
+- Domain list with 1-line responsibility each
+- Cross-domain communication pattern (events)
+- Key tech decisions (why this DB, why this queue, why this auth)
+- Link to stack-specific architecture doc
+
+**CONTRIBUTING.md** must have:
+- 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 clear purpose, audience, source
+- [ ] Required sections listed
+- [ ] Aligned with architecture doc
+
+---
+
+## Phase 3: GENERATE
+
+**Goal:** write each doc using actual code examples from the codebase.
+
+### 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** — use mermaid; one per major concept
+- **Tables** for any list with >3 items and parallel structure (endpoints, env vars, commands)
+
+### Skeleton — README.md
+
+```markdown
+# {Project Name}
+
+> One-line value proposition.
+
+[![ci](badge)](link) [![version](badge)](link)
+
+## Quick Start
+
+```bash
+{install}
+{run}
+```
+
+## Tech Stack
+
+- {language + version}
+- {framework}
+- {DB / queue / cache}
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for layer structure.
+
+## Common Commands
+
+| Command | Purpose |
+|---------|---------|
+| `{cmd}` | {what it does} |
+
+## Project Structure
+
+```
+{top 2 levels only}
+```
+
+## Documentation
+
+- [API.md](./API.md) — endpoint reference
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — system design
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — dev guide
+```
+
+### Skeleton — API.md
+
+```markdown
+# API Reference
+
+**Base URL:** `https://api.example.com/v1`
+**Auth:** Bearer token in `Authorization` header
+
+## Errors
+
+All errors return JSON:
+```json
+{ "error": { "code": "STRING", "message": "STRING", "details": {} } }
+```
+
+## Pagination
+
+Cursor-based: `?cursor=<opaque>&limit=<int, default 20, max 100>`.
+Response includes `pagination.next_cursor` (null if last page).
+
+## Endpoints
+
+### POST /resource
+
+Create a resource.
+
+**Request**
+```json
+{ "field": "value" }
+```
+
+**Response 201**
+```json
+{ "id": "...", "field": "value" }
+```
+
+**Errors:** 400 invalid_field, 401 unauthorized, 409 already_exists
+```
+
+### Skeleton — ARCHITECTURE.md
+
+```markdown
+# Architecture
+
+## Overview
+
+{1-2 paragraphs: what this system does, key constraints}
+
+## Layer Structure
+
+```mermaid
+graph TD
+  App[Application] --> Domain
+  Domain --> Infra[Infrastructure]
+```
+
+See [DDD architecture reference](~/.claude/architecture/ddd-architecture.md) for layer rules.
+
+## Domains
+
+| Domain | Responsibility |
+|--------|----------------|
+| {name} | {one line} |
+
+## Cross-Domain Communication
+
+Domains communicate via **domain events** (no direct imports).
+
+```mermaid
+sequenceDiagram
+  DomainA->>EventBus: raises Event
+  EventBus->>DomainB: Listener consumes
+```
+
+## Key Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| {tech / pattern} | {why} |
+```
+
+### Skeleton — CONTRIBUTING.md
+
+```markdown
+# Contributing
+
+## Prerequisites
+- {runtime + version}
+- {DB / service}
+
+## Setup
+```bash
+{1-5 commands}
+```
+
+## Branch & Commits
+- Branch: `{prefix}/{ticket}-{slug}`
+- Commit: Conventional Commits (`feat:`, `fix:`, `chore:`)
+
+## PR Flow
+1. Open PR against `{base branch}`
+2. CI must pass
+3. At least 1 review approval
+4. Squash merge
+
+## Tests
+```bash
+{test command}
+```
+Coverage target: {N}%
+
+## Help
+- {Slack / issue / discussion link}
+```
+
+### Gate
+- [ ] All planned docs drafted
+- [ ] Code examples taken from real files (no invention)
+- [ ] Diagrams render (mermaid syntax valid)
+- [ ] Cross-links between docs work
+
+---
+
+## Phase 4: REVIEW
+
+**Goal:** verify accuracy, consistency, and clarity.
+
+### Review checklist per doc
+
+- [ ] Reflects current architecture (not outdated)
+- [ ] All commands run as written (try them)
+- [ ] All file paths exist
+- [ ] All endpoints / functions referenced still exist
+- [ ] Links resolve (internal + external)
+- [ ] Code blocks compile / are valid syntax
+- [ ] Diagrams match actual code structure
+
+### Cross-doc consistency
+
+- [ ] README references match other docs' content
+- [ ] Same terminology used everywhere (e.g., "domain" vs "module")
+- [ ] No duplicated info — link instead
+
+### Loop
+If any issue found → go back to **Phase 3** for that doc, fix, re-review.
+
+---
+
+## Final Report
+
+```markdown
+## Documentation Update
+
+### Files Created / Modified
+- `README.md` — {changes}
+- `API.md` — {changes}
+- `ARCHITECTURE.md` — {changes}
+- `CONTRIBUTING.md` — {changes}
+
+### Coverage
+- [x] Project overview
+- [x] API reference
+- [x] Architecture
+- [x] Contributing guide
+- [ ] Deployment (out of scope)
+
+### Verification
+- [x] All commands tested
+- [x] All links resolve
+- [x] All examples compile
+```
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Generate full doc site from codebase automatically | `/docs:sync` |
+| Document a newly added API endpoint | `/feature:api` (Phase 4) |
+| Onboard yourself / new dev to the codebase | `/research:onboarding` |
+| Write release notes / changelog | `release` (manually for now) |
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| SCAN | `@clean-architect` | Identify doc needs from architecture |
+| 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 against code |
+| REVIEW | Stack-specific dev agent | Stack-specific review |

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 |