macca-method 1.1.0 → 2.1.1

package/.agents/skills/_shared/scripts/validate-skills.py

@@ -7,8 +7,17 @@ import sys
 from pathlib import Path
 
 
-ROOT = Path(__file__).resolve().parents[4]
-SKILLS_DIR = ROOT / ".agents" / "skills"
+SKILLS_DIR = Path(__file__).resolve().parents[2]
+ALLOWED_FRONTMATTER = {
+    "name",
+    "description",
+    "license",
+    "compatibility",
+    "metadata",
+    "allowed-tools",
+}
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+MARKDOWN_LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
 
 
 def read(path: Path) -> str:
@@ -19,11 +28,93 @@ def has_toc(text: str) -> bool:
     return "## Daftar Isi" in text or "## Table of Contents" in text
 
 
+def parse_frontmatter(path: Path, text: str) -> tuple[dict[str, object], list[str]]:
+    issues: list[str] = []
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        return {}, [f"{path}: SKILL.md must start with YAML frontmatter on line 1"]
+
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        return {}, [f"{path}: frontmatter closing delimiter is missing"]
+
+    data: dict[str, object] = {}
+    current_map: str | None = None
+    for line_number, line in enumerate(lines[1:end], start=2):
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if line.startswith("  "):
+            if current_map != "metadata" or ":" not in line:
+                issues.append(f"{path}:{line_number}: unsupported nested frontmatter value")
+                continue
+            key, value = line.strip().split(":", 1)
+            metadata = data.setdefault("metadata", {})
+            assert isinstance(metadata, dict)
+            metadata[key] = value.strip().strip('"\'')
+            continue
+        if ":" not in line:
+            issues.append(f"{path}:{line_number}: invalid frontmatter line")
+            continue
+        key, value = line.split(":", 1)
+        key = key.strip()
+        if key in data:
+            issues.append(f"{path}:{line_number}: duplicate frontmatter key {key}")
+        value = value.strip()
+        if value:
+            data[key] = value.strip('"\'')
+            current_map = None
+        else:
+            data[key] = {}
+            current_map = key
+
+    return data, issues
+
+
+def check_local_links(path: Path, text: str) -> list[str]:
+    issues: list[str] = []
+    for raw_target in MARKDOWN_LINK_RE.findall(text):
+        target = raw_target.split("#", 1)[0].strip()
+        if not target or "://" in target or target.startswith("#"):
+            continue
+        resolved = (path.parent / target).resolve()
+        if not resolved.exists():
+            issues.append(f"{path}: broken local link {raw_target}")
+    return issues
+
+
 def check_skill_file(path: Path) -> list[str]:
     issues: list[str] = []
     text = read(path)
     lines = text.splitlines()
 
+    frontmatter, frontmatter_issues = parse_frontmatter(path, text)
+    issues.extend(frontmatter_issues)
+    if frontmatter:
+        unknown = sorted(set(frontmatter) - ALLOWED_FRONTMATTER)
+        if unknown:
+            issues.append(f"{path}: unsupported frontmatter fields: {', '.join(unknown)}")
+
+        name = frontmatter.get("name")
+        description = frontmatter.get("description")
+        if not isinstance(name, str) or not NAME_RE.fullmatch(name) or len(name) > 64:
+            issues.append(f"{path}: invalid skill name {name!r}")
+        elif name != path.parent.name:
+            issues.append(f"{path}: name {name!r} does not match folder {path.parent.name!r}")
+        if not isinstance(description, str) or not description or len(description) > 1024:
+            issues.append(f"{path}: description must contain 1-1024 characters")
+        metadata = frontmatter.get("metadata")
+        if metadata is not None and (
+            not isinstance(metadata, dict)
+            or any(not isinstance(key, str) or not isinstance(value, str) for key, value in metadata.items())
+        ):
+            issues.append(f"{path}: metadata must be a string-to-string map")
+        compatibility = frontmatter.get("compatibility")
+        if compatibility is not None and (
+            not isinstance(compatibility, str) or not 1 <= len(compatibility) <= 500
+        ):
+            issues.append(f"{path}: compatibility must contain 1-500 characters")
+
     if len(lines) > 500:
         issues.append(f"{path}: more than 500 lines ({len(lines)})")
 
@@ -37,6 +128,11 @@ def check_skill_file(path: Path) -> list[str]:
             f"{path}: possible broken nested fence; check and use 4 backticks for the outer template"
         )
 
+    if "[GATE — Fix mode: report-first]" in text and "Approval Resume Protocol" not in text:
+        issues.append(f"{path}: report-first gate has no approval resume protocol")
+
+    issues.extend(check_local_links(path, text))
+
     return issues
 
 
@@ -56,16 +152,22 @@ def check_reference_file(path: Path) -> list[str]:
             f"{path}: chained reference to runtime-config; caller skill should read shared refs directly"
         )
 
+    issues.extend(check_local_links(path, text))
+
     return issues
 
 
 def main() -> int:
     issues: list[str] = []
+    skill_files = sorted(SKILLS_DIR.glob("**/SKILL.md"))
+    if not skill_files:
+        print(f"Skill validator findings:\n- {SKILLS_DIR}: no SKILL.md files found")
+        return 1
 
-    for skill_md in SKILLS_DIR.glob("**/SKILL.md"):
+    for skill_md in skill_files:
         issues.extend(check_skill_file(skill_md))
 
-    for ref in SKILLS_DIR.glob("**/references/*.md"):
+    for ref in sorted(SKILLS_DIR.glob("**/references/*.md")):
         issues.extend(check_reference_file(ref))
 
     if not issues:

package/.agents/skills/add-feature/SKILL.md

@@ -1,19 +1,24 @@
 ---
 name: add-feature
-description: Skill for adding new features to running projects. Read current specs, identify all affected documents, update every impacted spec, then add a phase and tasks to Task.md.
-persona: "Galbi"
-persona_role: "Project Manager"
+description: Adds an approved new feature to a running project by updating every affected spec and delegating a new Task.md phase. Use only when the user explicitly asks to expand official product or business scope.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
 ---
 
 # Add Feature
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 At startup:
 
-1. Read `../_shared/references/runtime-config.md`.
+1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/output-ownership.md`.
-3. Use `languagePreferences.communication.normalized` for feature analysis and reports.
+3. Read `../_shared/references/scope-rules.md`.
+4. Use `languagePreferences.communication.normalized` for feature analysis and reports.
 
 ---
 
@@ -114,7 +119,7 @@ For each **IMPACTED** document, update it in this order:
 7. `project-context/plans/` — if a plan file exists for the affected phase (for example `plans/phase-2-checkout.md`), update it to reflect the new scope. Add a section: `## Feature Addition: [feature name]` with a short description of the approach change. Do not overwrite existing plan content.
 
 ### Update Principles:
-- **Add, do not overwrite** — append to the relevant section; do not change existing content unless there is a conflict
+- **Preserve unrelated content and IDs** — make the smallest targeted edit needed to keep each affected document internally consistent; update an existing statement when the approved feature changes it
 - **Match the existing style** — follow the current document format and tone
 - **Make additions clear** — place them logically; no special tags are needed
 - **Preserve old IDs** — assign new IDs for new items using the existing pattern
@@ -185,6 +190,6 @@ To start building, call `developer`.
 1. **Read all specs before impact analysis** — no assumptions
 2. **Every impacted spec MUST be updated** — no exceptions
 3. **Get user approval after impact analysis** — before making changes
-4. **Only add** — do not overwrite unless there is a real conflict
+4. **Preserve unrelated content** — update stale affected statements instead of appending contradictions
 5. **Update Task.md last** — via `brainstorm-task` after all specs are done
 6. **Acceptance criteria must be testable** — not vague descriptions

package/.agents/skills/brainstorm-api/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: brainstorm-api
-description: Interview users and generate `api.md` (Endpoint Documentation / API Contract). Use after `schema.md` is complete to document all API endpoints.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Interviews users and generates `api.md` for REST, GraphQL, RPC/tRPC, event-driven, or mixed contracts, including lifecycle and reliability. Use only when the user explicitly requests an API contract after applicable architecture/data decisions.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Brainstorm API
@@ -32,14 +34,17 @@ You are **@Fachri — Tech Lead**, a **Senior API Architect** who designs clear,
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before any interview:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `../_shared/references/brainstorm-session.md`.
-3. Read `../_shared/references/scope-rules.md`.
-4. Use `languagePreferences.communication.normalized` for chat.
-5. Use `languagePreferences.documents.normalized` for the final `project-context/api.md`.
-6. Apply `brainstormPreferences.discussionMode` and `brainstormPreferences.recommendations` using the shared session policy.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/config-mutation.md`.
+3. Read `../_shared/references/brainstorm-session.md`.
+4. Read `../_shared/references/scope-rules.md`.
+5. Use `languagePreferences.communication.normalized` for chat.
+6. Use `languagePreferences.documents.normalized` for the final `project-context/api.md`.
+7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 
@@ -63,7 +68,7 @@ Before any interview:
     - **provider contract mode** → document endpoints as backend implementation contracts, including relevant data/auth/service dependencies.
     - **full contract mode** → combine consumer + provider views as the project requires.
 
-5. Run the shared runtime setup above. For this skill, ask whether to cover the 5 global topics one by one or three at once, then apply the stored or chosen recommendation preference.
+5. Run the shared runtime setup above and apply all three pacing modes from the shared session policy. If preferences are saved, announce and proceed without another confirmation.
 
 6. Run the interview in the chosen mode. Wait for answers.
 
@@ -75,22 +80,30 @@ Before any interview:
 
 ## Interview Topics (5 Topics)
 
-Ask all five topics. Wait for the answer before moving on.
+Ask all five topics using the selected batch size. First determine the API style from `architecture.md`: REST, GraphQL, tRPC/RPC, event-driven, or mixed. Use protocol-neutral terms until that choice is known.
+
+Protocol mapping:
+- REST: method, path, HTTP status, body/query/path parameters
+- GraphQL: operation type/name, arguments, selection/result type, errors
+- tRPC/RPC: procedure name/type, input/output schema, typed errors
+- Event-driven: channel/topic, producer/consumer, payload schema, delivery/idempotency rules
+- Mixed: separate sections per protocol; do not force one protocol's fields onto another
 
-### 1. Base URL, Versioning, Auth & Contract Status
-*"What is the base URL? Is versioning in the URL? How do users authenticate? Is the contract confirmed, proposed, or mock-only?"*
+### 1. Entry Point, Versioning, Auth & Contract Status
+*"What is the API entry point and protocol? How is compatibility/versioning handled? How do users authenticate? Is the contract confirmed, proposed, or mock-only?"*
 
 Collect:
-- Base URL (dev: `http://localhost:3000/api/v1`, prod: `https://api.domain.com/v1`)
-- Versioning strategy (URI path `/v1/` or header `api-version`)
-- Auth header (Bearer token, Cookie, API Key)
+- Entry point appropriate to the selected protocol (base URL, GraphQL endpoint, RPC router, channel/broker)
+- Compatibility/versioning strategy appropriate to the protocol
+- Deprecation policy for external consumers: support window, notice channel, replacement operation, and sunset criteria
+- Authentication/identity transport appropriate to the protocol
 - Does cookie/session auth need CSRF protection?
 - Token lifetime, refresh, rotation, logout behavior
 - Standard response wrapper format (for example `{ success, data, message, meta }`)
 - Contract status by area: `confirmed`, `proposed`, `mock-only`, `backend-owned`, `pending backend confirmation`
 
 ### 2. Error Catalog
-*"What is the error response format? Which HTTP status codes are used?"*
+*"What is the error format for the selected protocol? For REST, which HTTP status codes are used; for typed protocols, which error codes/types are exposed?"*
 
 Collect:
 - Consistent error response structure
@@ -104,197 +117,41 @@ Collect:
   - `429` Too Many Requests — rate limit reached
   - `500` Internal Server Error
 - Application-level error codes in the response body? (for example `{ "code": "USER_NOT_FOUND" }`)
+- Retry classification: retryable or terminal, client action, timeout interaction, backoff, and `Retry-After`/protocol equivalent
 
-### 3. Endpoint List by Resource
-*"What endpoints are needed? List them by resource or module."*
+### 3. Operation List by Resource
+*"What operations are needed? List endpoints, queries/mutations, procedures, or events by resource/module."*
 
 Collect per resource:
-- Are standard CRUD endpoints needed? `GET /` (list), `GET /:id`, `POST /`, `PUT /:id`, `PATCH /:id`, `DELETE /:id`
-- Custom non-CRUD endpoints (for example `POST /auth/login`, `POST /orders/:id/cancel`)
-- Which endpoints require authentication?
-- Authorization/ownership rules per endpoint?
+- Which protocol-native operations are needed: REST actions, GraphQL queries/mutations/subscriptions, RPC procedures, or produced/consumed events?
+- Which operations require authentication?
+- Authorization/ownership rules per operation?
 
 ### 4. Request & Response Details
-*"For each endpoint, what data is sent and returned? Include real examples."*
+*"For each operation, what input is accepted and what result or event is produced? Include protocol-native examples."*
 
-Collect per endpoint:
-- **Request:** JSON body, path params (`:id`), query params (`?page=1&limit=20`)
-- **Success Response:** Schema + real JSON example
-- **Error Response:** Schema for each relevant error code
-- Field constraints (required/optional, type, validation)
-- Security notes: CSRF, idempotency, signed webhooks, upload limits, ownership checks
+Collect by selected protocol:
+- **REST:** method/path, body/path/query/header inputs, success/error response and status
+- **GraphQL:** operation name/type, arguments, selection/result type, union/error behavior
+- **RPC/tRPC:** procedure type/name, typed input/output, typed errors
+- **Event-driven:** channel/topic, producer/consumer, payload, key/order, delivery and retry semantics
+- **All modes:** field constraints, authorization/ownership, idempotency/replay, upload/payload limits, and real examples
 
 ### 5. Pagination, Filtering, Rate Limiting & Abuse Protection
-*"For list endpoints, how do pagination and filtering work? How are sensitive endpoints protected?"*
-
-Collect:
-- **Pagination:** Offset-based (`?page=1&limit=20`) or cursor-based (`?after=cursor_id`)?
-- **Response envelope:** How are list data + metadata structured? (`total`, `page`, `hasNext`, etc.)
-- **Filtering:** Query params for filtering (for example `?status=active&category=books`)
-- **Sorting:** `?sort=created_at&order=desc`
-- **Rate Limiting:** Limit per minute/hour? Response headers?
-- **Sensitive endpoints:** Which need extra protection (login, password reset, upload, webhook, payment)?
-- **Idempotency/Replay Protection:** Which endpoints need it?
-
-## api.md Output Format
-
-````markdown
-# API Documentation
-
-## Document Role
-- **Source of Truth:** External API contract for this project
-- **Primary Owner:** `brainstorm-api`
-- **Out of Scope:** Internal service architecture, DB migration details, and UI copy
-
-## Scope Summary
-| Area | Status | Notes |
-|------|--------|-------|
-| [resource / module] | Covered / Planned / Deferred | [short note] |
-
-## Canonical Terminology
-| Term | Meaning |
-|------|---------|
-| [term] | [exact meaning used in this API contract] |
-
-## Environments
-| Environment | Base URL |
-|-------------|----------|
-| Development | `http://localhost:3000/api/v1` |
-| Staging | `https://staging-api.domain.com/v1` |
-| Production | `https://api.domain.com/v1` |
-
-## Versioning
-- **Strategy:** URI path `/v1/` / Header `api-version: 1`
-- **Current Version:** v1
-
-## Authentication
-- **Method:** Bearer Token (JWT)
-- **Header:** `Authorization: Bearer <token>`
-- **Login Endpoint:** `POST /auth/login`
-- **Refresh Endpoint:** `POST /auth/refresh`
-
-## Security Controls
-- **CSRF Protection:** Yes / No / Not applicable — [when it applies]
-- **Ownership/Authorization Rules:** [access control summary]
-- **Sensitive Endpoints:** [login / password reset / upload / webhook / payment / admin actions]
-- **Idempotency/Replay Protection:** [which endpoints need it and how]
-- **Webhook Verification/Signing:** [if external integrations exist]
-
-## Standard Response Format
-```json
-{
-  "success": true,
-  "data": {},
-  "message": "string (optional)",
-  "meta": {
-    "page": 1,
-    "limit": 20,
-    "total": 100,
-    "hasNext": true
-  }
-}
-```
-
-## Error Catalog
-| HTTP Code | Internal Code | Meaning |
-|-----------|---------------|---------|
-| 400 | `VALIDATION_ERROR` | Invalid input; details in the `errors` field |
-| 401 | `UNAUTHORIZED` | Missing or expired token |
-| 403 | `FORBIDDEN` | No permission for this resource |
-| 404 | `NOT_FOUND` | Resource does not exist |
-| 409 | `CONFLICT` | Duplicate data (for example email already registered) |
-| 422 | `UNPROCESSABLE` | Business logic validation failed |
-| 429 | `RATE_LIMIT` | Too many requests; check the `Retry-After` header |
-| 500 | `SERVER_ERROR` | Internal server error |
-
-**Error Response Format:**
-```json
-{
-  "success": false,
-  "message": "User-friendly error message",
-  "code": "INTERNAL_CODE",
-  "errors": [
-    { "field": "email", "message": "Invalid email format" }
-  ]
-}
-```
-
-## Pagination
-- **Type:** Offset-based / Cursor-based
-- **Default:** `limit=20`, `page=1`
-- **Max Limit:** `100`
-
-## Rate Limiting
-- **Limit:** [X requests per minute]
-- **Headers:** `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
-
-## Endpoint Inventory
-| ID | Method | Path | Auth | Trace to |
-|----|--------|------|------|----------|
-| API-01 | GET | `/[resource]` | Required / Public | `FEAT-01` |
-| API-02 | POST | `/[resource]` | Required | `FEAT-01` |
-
----
-
-## Resource: [Resource Name]
-**Trace to:** [FEAT-01 / AC-01]
-
-### API-01 — GET /[resource]
-**Description:** Get a list of [resource]
-**Auth:** Required / Public
-**Authorization:** [role / ownership rule]
-
-**Query Params:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| page | number | 1 | Page number |
-| limit | number | 20 | Items per page |
-| [filter] | string | - | Filter by [field] |
-
-**200 Response:**
-```json
-{
-  "success": true,
-  "data": [{ "id": "uuid", "...": "..." }],
-  "meta": { "page": 1, "limit": 20, "total": 100, "hasNext": true }
-}
-```
+*"How do collection/stream access, flow control, and abuse protection work for the selected protocol?"*
 
----
-
-### API-02 — POST /[resource]
-**Description:** Create a new [resource]
-**Auth:** Required
-**Authorization:** [role / ownership rule]
-
-**Request Body:**
-```json
-{
-  "field": "string | required",
-  "field2": "number | optional"
-}
-```
-
-**201 Response:**
-```json
-{
-  "success": true,
-  "data": { "id": "uuid", "...": "..." }
-}
-```
+Collect by selected protocol:
+- **REST/GraphQL/RPC:** cursor/offset pagination where applicable, filtering, sorting, query complexity/depth, batching, and rate/concurrency limits
+- **Event-driven:** partition/key strategy, ordering, backpressure, delivery guarantee, retry/dead-letter policy, deduplication, and consumer limits
+- **All modes:** sensitive operations, quotas, idempotency/replay protection, and how clients observe limit errors
+- API-specific SLOs inherited from PRD NFRs: latency, availability, timeout, and error target where relevant
+- Contract-test invariants/examples required to verify consumer/provider compatibility
 
-**Possible Errors:** `400` (validation), `409` (duplicate), `401` (not logged in)
-
-**Security Notes:** [CSRF / idempotency / upload limits / ownership checks / none]
-
----
+## api.md Output
 
-*[Repeat for each endpoint]*
+After discovery is complete and immediately before generating `project-context/api.md`, read `assets/api.template.md`.
 
-## Assumptions & Open Questions
-- [Unresolved API assumption or question]
-- [Decision still pending confirmation]
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ## After api.md Is Created
 

package/.agents/skills/brainstorm-api/assets/api.template.md

@@ -0,0 +1,147 @@
+# API Documentation
+
+## Document Role
+- **Source of Truth:** External API or integration contract for this project
+- **Primary Owner:** `brainstorm-api`
+- **Out of Scope:** Internal service architecture, DB migration details, and UI copy
+
+## Scope Summary
+| Area | Status | Notes |
+|------|--------|-------|
+| [resource / module] | Covered / Planned / Deferred | [short note] |
+
+## Canonical Terminology
+| Term | Meaning |
+|------|---------|
+| [term] | [exact meaning used in this API contract] |
+
+## Protocol Profile
+- **Style:** REST / GraphQL / RPC-tRPC / Event-driven / Mixed
+- **Entry Point:** [base URL / endpoint / router / broker/topic namespace]
+- **Versioning:** [strategy and current version]
+- **Deprecation:** [notice channel, support window, replacement, sunset criteria]
+
+## Authentication and Security Controls
+- **Authentication:** [method and transport]
+- **Authorization:** [role/ownership summary]
+- **Sensitive Operations:** [login / password reset / upload / webhook / payment / admin actions]
+- **CSRF / Replay / Signature / Idempotency:** [applicable controls]
+- **Rate / Concurrency Limits:** [limit and client-visible signals]
+
+## Error Catalog
+| Protocol Code | Internal Code | Meaning | Retryable | Client Action |
+|---------------|---------------|---------|-----------|---------------|
+| [400 / UNAUTHENTICATED / EVENT_RETRY / etc.] | `[CODE]` | [meaning] | Yes / No | [action] |
+
+## Reliability and SLO
+- **Latency Target:** [p95/p99 or N/A]
+- **Availability/Error Target:** [target or inherited NFR]
+- **Timeout Ownership:** [client/server/gateway/consumer]
+- **Retry Policy:** [which failures, backoff, max attempts]
+- **Contract Test Invariants:** [critical examples/compatibility rules]
+
+## Operation Inventory
+| ID | Operation Type | Name / Path / Topic | Auth | Trace to |
+|----|----------------|---------------------|------|----------|
+| API-01 | [REST GET / GraphQL query / RPC procedure / Event publish] | [identifier] | Required / Public | `FEAT-01` |
+
+---
+
+## REST Section (include only for REST or Mixed)
+
+### Environments
+| Environment | Base URL |
+|-------------|----------|
+| Development | `http://localhost:3000/api/v1` |
+| Staging | `https://staging-api.domain.com/v1` |
+| Production | `https://api.domain.com/v1` |
+
+### Standard Response Format
+```json
+{
+  "success": true,
+  "data": {},
+  "message": "string (optional)",
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "hasNext": true
+  }
+}
+```
+
+### Pagination and Filtering
+- **Type:** Offset-based / Cursor-based
+- **Defaults:** [limit/page or cursor rules]
+- **Sorting/Filtering:** [query parameters]
+
+### Resource: [Resource Name]
+**Trace to:** [FEAT-01 / AC-01]
+
+#### API-01 — [METHOD] /[path]
+- **Description:** [what it does]
+- **Auth:** [Required / Public]
+- **Authorization:** [rule]
+- **Input:** [body/path/query/header fields]
+- **Success Response:** [example]
+- **Possible Errors:** [codes]
+- **Security Notes:** [CSRF / idempotency / upload / ownership]
+
+---
+
+## GraphQL Section (include only for GraphQL or Mixed)
+
+### Endpoint and Transport
+- **Endpoint:** `/graphql`
+- **Realtime:** Subscriptions / polling / none
+
+### Operation: [Query / Mutation / Subscription Name]
+**Trace to:** [FEAT-01 / AC-01]
+
+- **Type:** Query / Mutation / Subscription
+- **Arguments:** [typed input]
+- **Selection/Result Shape:** [expected result]
+- **Auth & Authorization:** [rules]
+- **Errors:** [codes/unions/extensions]
+- **Complexity / Depth / Pagination:** [rules]
+
+---
+
+## RPC / tRPC Section (include only for RPC or Mixed)
+
+### Router / Namespace
+- **Entry Point:** [router/namespace]
+
+### Procedure: [Name]
+**Trace to:** [FEAT-01 / AC-01]
+
+- **Type:** Query / Mutation / Subscription / Procedure
+- **Input Schema:** [typed input]
+- **Output Schema:** [typed output]
+- **Auth & Authorization:** [rules]
+- **Typed Errors:** [codes/types]
+- **Retry / Idempotency:** [rules]
+
+---
+
+## Event-Driven Section (include only for Event-driven or Mixed)
+
+### Channel Topology
+- **Broker / Bus:** [service]
+- **Topics / Streams / Queues:** [list]
+
+### Event Contract: [Topic / Event Name]
+**Trace to:** [FEAT-01 / AC-01]
+
+- **Producer:** [service/component]
+- **Consumer:** [service/component]
+- **Payload Schema:** [fields/example]
+- **Ordering / Partition Key:** [rules]
+- **Delivery Guarantee:** [at-least-once / exactly-once / best effort]
+- **Retry / Dead-letter / Deduplication:** [rules]
+- **Security / Signature / Replay:** [controls]
+
+## Assumptions & Open Questions
+- [Unresolved API assumption or question]
+- [Decision still pending confirmation]