hatch3r 1.0.0 → 1.2.0

package/commands/board/shared-gitlab.md

@@ -0,0 +1,142 @@
+---
+id: hatch3r-board-shared-gitlab
+type: shared-context
+description: GitLab-specific platform details for board shared context. Covers GitLab Issues, Issue Boards, glab CLI, and label-based sync.
+tags: [board, team, gitlab]
+---
+# Board Shared Reference — GitLab Platform Details
+
+Platform-specific procedures for GitLab. Referenced from `hatch3r-board-shared`.
+
+---
+
+## Platform Detection — GitLab
+
+Use `glab` CLI. Issues = GitLab Issues. PRs = Merge Requests (MRs). Board = GitLab Issue Boards. Requires `glab auth login` or `GITLAB_TOKEN`.
+
+### CLI Command Reference
+
+| Action | Command |
+|--------|---------|
+| Create issue | `glab issue create -R {namespace}/{project}` |
+| List issues | `glab issue list -R {namespace}/{project}` |
+| View issue | `glab issue view N -R {namespace}/{project}` |
+| Update issue | `glab issue update N -R {namespace}/{project}` |
+| Close issue | `glab issue close N -R {namespace}/{project}` |
+| Create MR | `glab mr create -R {namespace}/{project}` |
+| Add label | `glab issue update N --label "x"` |
+| Add comment | `glab issue note N -R {namespace}/{project}` |
+| Board sync | Board list = label-based |
+
+### MCP Tool Reference
+
+GitLab MCP tools are not currently available. All operations use the `glab` CLI.
+
+### Terminology
+
+| Concept | GitLab Term |
+|---------|-------------|
+| Work unit | Issue |
+| Code review | Merge Request (MR) |
+| Board | GitLab Issue Boards |
+| Labels | Labels |
+| Project identifier | project ID |
+| Status tracking | Board lists/labels |
+
+---
+
+## GitLab Context
+
+Derived from `.agents/hatch.json` board config:
+
+- **Namespace:** top-level `owner` (GitLab group or user namespace)
+- **Project:** top-level `repo` (GitLab project name)
+- **Default branch:** `board.defaultBranch` (fallback: `"main"`)
+- **Type labels:** `board.labels.types`
+- **Executor labels:** `board.labels.executors`
+- **Status labels:** `board.labels.statuses`
+- **Scoped labels:** GitLab supports scoped labels (`status::ready`, `type::bug`). Map hatch3r label format (`status:ready`) to GitLab scoped format (`status::ready`) when creating labels.
+- **Issue templates:** Check `.gitlab/issue_templates/` if present.
+- **MR template:** Check `.gitlab/merge_request_templates/` if present.
+
+### GitLab Project Reference (cache for the full run)
+
+- **Project path:** `{namespace}/{project}`
+- **Board:** GitLab Issue Boards use label-based lists. Each status maps to a board list label.
+- **Board ID:** `board.projectNumber` (repurposed as GitLab Board ID if configured)
+
+---
+
+## GitLab Board Label-Based Sync
+
+> **Skip entirely if board is not configured.**
+
+GitLab Boards use labels to organize issues into lists. Board sync is achieved by updating issue labels to match the target status.
+
+**Status label → Board list mapping:**
+
+GitLab board lists are label-based. Each status corresponds to a scoped label:
+
+| Label                | GitLab Scoped Label |
+| -------------------- | ------------------- |
+| `status:triage`      | `status::triage`    |
+| `status:ready`       | `status::ready`     |
+| `status:in-progress` | `status::in-progress` |
+| `status:in-review`   | `status::in-review` |
+| `status:blocked`     | `status::blocked`   |
+
+**Steps for each issue to sync:**
+
+1. **Update labels:** `glab issue update {N} -R {namespace}/{project} --unlabel "status::*" --label "status::{new-status}"`. GitLab scoped labels auto-replace within the same scope, so setting `status::ready` automatically removes `status::triage`.
+2. **Verify:** `glab issue view {N} -R {namespace}/{project}` and confirm labels match.
+
+**For MRs:** `glab mr update {N} -R {namespace}/{project} --label "status::{new-status}"`.
+
+**Resilience:** If any call fails, retry once. If it still fails, surface a warning and continue. If `glab` CLI is unavailable, warn: "GitLab Board sync skipped -- run `glab auth login` or set GITLAB_TOKEN."
+
+---
+
+## Sub-Issue Linking — GitLab
+
+### Three-Tier Fallback Chain
+
+1. **Primary — API link:**
+   `glab api projects/{project_id}/issues/{parent_iid}/links --method POST --field target_project_id={project_id} --field target_issue_iid={child_iid}`.
+   Record link status as `native`.
+
+2. **Fallback 1 — Comment trace:**
+   If API linking fails:
+   `glab issue note {epic} -R {namespace}/{project} --message "Sub-issue: #{child} — {title} (linking failed)"`.
+   Record link status as `comment-only`.
+
+### Verification
+
+After linking, verify via `glab api projects/{project_id}/issues/{epic_iid}/links` and check linked issues.
+
+---
+
+## Board Sync Enforcement — GitLab
+
+1. **Status updates:** Set via `glab issue update --label`.
+2. **Fallback escalation:** `glab issue update` CLI → surface error to user. Silent skipping is prohibited.
+3. **Board item tracking:** After updating an issue, store the issue ID in the run cache keyed by issue number.
+
+---
+
+## Cross-Cutting Tooling — GitLab CLI-First
+
+**Prerequisites:** `glab auth login` must be completed, or `GITLAB_TOKEN` environment variable set.
+
+| Operation            | Primary (`glab` CLI)                                          | Fallback (MCP) |
+| -------------------- | ------------------------------------------------------------- | -------------- |
+| List issues          | `glab issue list -R {namespace}/{project}`                    | N/A            |
+| Read issue details   | `glab issue view N -R {namespace}/{project}`                  | N/A            |
+| Create/update issues | `glab issue create` / `glab issue update N`                   | N/A            |
+| Search issues        | `glab issue list --search "..."`                              | N/A            |
+| Manage relations     | `glab issue note N --message "Related to #M"` (advisory only) | N/A            |
+| Add comments         | `glab issue note N -R {namespace}/{project}`                  | N/A            |
+| Create MRs           | `glab mr create -R {namespace}/{project}`                     | N/A            |
+| Read MR details      | `glab mr view N -R {namespace}/{project}`                     | N/A            |
+| Manage labels        | `glab label create` / `glab label list`                       | N/A            |
+| Board sync           | Label updates (automatic board list placement)                | N/A            |
+| CI/Pipelines         | `glab ci list` / `glab ci view`                               | N/A            |

package/commands/hatch3r-agent-customize.md

@@ -2,7 +2,13 @@
 id: hatch3r-agent-customize
 type: command
 description: Configure per-agent customization including model overrides, description changes, and project-specific markdown instructions
+tags: [customize]
 ---
+
+## Agent Pipeline
+
+This command runs as a single orchestrator without sub-agent delegation. Customization file management is performed inline.
+
 # Agent Customization — Per-Agent Configuration
 
 Customize individual agent behavior for project-specific needs via `.hatch3r/agents/` configuration files. Supports structured YAML overrides and free-form markdown instruction injection, all propagated to every adapter output on sync.
@@ -124,6 +130,38 @@ enabled: false
 
 The agent's canonical definition remains in `.agents/agents/` but no adapter output is generated for it.
 
+## Protected Agents
+
+Some agents have `protected: true` in their canonical frontmatter. This field marks agents whose core behavior must not be weakened or bypassed through customization, because they enforce critical quality and security invariants.
+
+### Currently Protected Agents
+
+| Agent | Why Protected |
+|-------|--------------|
+| `hatch3r-reviewer` | Enforces code quality, privacy invariants, and security review. Weakening or disabling it would allow unsafe code to merge unreviewed. |
+| `hatch3r-security-auditor` | Enforces security rules, access control auditing, and privacy invariant verification. Disabling it would leave security gaps undetected. |
+| `hatch3r-test-writer` | Enforces test coverage requirements and regression testing. Disabling it would allow untested code to ship. |
+
+### What Protection Means
+
+- **Cannot be disabled.** Setting `enabled: false` in a `.customize.yaml` file for a protected agent is ignored. The agent is always included in adapter output.
+- **Cannot have scope or description overridden.** The `description` field in a `.customize.yaml` file is ignored for protected agents. Their canonical description is always used to prevent narrowing or misrepresenting the agent's responsibilities.
+- **Model overrides ARE allowed.** You can override the `model` field for protected agents via `.customize.yaml` or `hatch.json`. Choosing a more capable model for a protected agent is a valid use case.
+- **Markdown customization IS allowed.** You can add project-specific instructions via `.customize.md` (e.g., domain-specific review checklists, compliance requirements). These are appended to the canonical content and extend the agent's scope — they cannot reduce it.
+
+### Frontmatter Format
+
+```yaml
+---
+id: hatch3r-reviewer
+description: Expert code reviewer for the project...
+protected: true
+model: standard
+---
+```
+
+The `protected` field is set in the canonical agent definition and cannot be overridden by customization files.
+
 ## Workflow
 
 1. Identify which agent to customize
@@ -142,5 +180,5 @@ The agent's canonical definition remains in `.agents/agents/` but no adapter out
 - Skill customization: `hatch3r-skill-customize` command
 - Command customization: `hatch3r-command-customize` command
 - Rule customization: `hatch3r-rule-customize` command
-- Model selection: [docs/model-selection.md](../docs/model-selection.md) — configuration, aliases, resolution order
-- Platform support: [docs/adapter-capability-matrix.md](../docs/adapter-capability-matrix.md) — model emission per adapter (native vs guidance)
+- Model selection: [Model Selection](https://docs.hatch3r.com/docs/guides/model-selection) — configuration, aliases, resolution order
+- Platform support: [Adapter Capability Matrix](https://docs.hatch3r.com/docs/reference/adapter-capability-matrix) — model emission per adapter (native vs guidance)

package/commands/hatch3r-api-spec.md

@@ -2,48 +2,310 @@
 id: hatch3r-api-spec
 type: command
 description: Generate or validate an OpenAPI specification from the codebase. Scans route definitions, extracts schemas, and produces a complete API spec.
+tags: [planning]
 ---
-# API Specification Generator
 
-## Inputs
+## Agent Pipeline
 
-- **Mode:** `generate` (create spec from code) or `validate` (check existing spec against code)
-- **Format:** `yaml` (default) or `json`
-- **Output path:** default `docs/api/openapi.yaml`
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Codebase Scan | `hatch3r-researcher` (codebase-analysis mode) | No | Yes |
+| 2. Schema Extraction | Orchestrator (inline) | No | Yes |
+| 3. Spec Generation | `hatch3r-docs-writer` | No | Yes |
+| 4. Validation | `hatch3r-reviewer` | No | Yes (if validate mode) |
 
-## Procedure
+# API Specification Generator — OpenAPI from Code or Code-vs-Spec Drift Detection
 
-### Generate Mode
+Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 specification (`docs/api/`), or take an existing spec and compare it against the live codebase to surface undocumented, stale, or drifted endpoints. The researcher sub-agent scans route definitions, decorators, and handlers; the orchestrator extracts TypeScript types and validation schemas inline; the docs-writer assembles the final spec document; and the reviewer validates structural correctness. AI proposes all outputs; user confirms before any files are written.
 
-1. **Scan the codebase** for route/endpoint definitions. Check common patterns:
-   - Express/Fastify route handlers
-   - NestJS/Spring controllers with decorators
-   - tRPC routers
-   - GraphQL schema definitions
-2. **Extract for each endpoint:** method, path, path params, query params, request body type, response type, status codes, auth requirements.
-3. **Build the OpenAPI 3.1 document:**
-   - `info` block from `package.json` (name, version, description)
-   - Group endpoints by resource/tag
-   - Create `components/schemas` from TypeScript types/interfaces or equivalent
-   - Add `securitySchemes` matching the project's auth mechanism
-4. **Write the spec** to the output path.
-5. **Run validation** on the generated spec using `spectral` or `redocly` if available.
+---
+
+## Shared Context
+
+**Read the `hatch3r-board-shared` command at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
+
+**Read the `hatch3r-api-design` rule** if it exists. This rule contains the project's API design conventions (naming, versioning, error shapes, pagination patterns) that the generated spec must conform to.
+
+## Token-Saving Directives
+
+1. **Do not re-read files already cached.** Once the researcher's route scan is collected, reference it in memory — do not re-scan the same directories.
+2. **Limit schema reads.** Read only the imported type file — not the entire module tree. Follow one level of imports; stop there.
+3. **Structured output only.** All sub-agent prompts require structured markdown output — no prose dumps.
+4. **Batch schema extraction.** Group types by source file. Read each file once and extract all referenced types in a single pass.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Gather API Context
+
+1. **ASK:** "I'll generate or validate an OpenAPI specification from your codebase. I need:
+   - **Mode:** `generate` (create spec from code) or `validate` (check existing spec against code)
+   - **Output format:** `yaml` (default) or `json`
+   - **Output path:** default `docs/api/openapi.yaml` — or specify a custom path
+   - **Scope:** full API, or limit to specific route prefixes / modules (e.g., `/api/v2/`, `src/routes/billing/`)
+   - **Spec version:** OpenAPI 3.1 (default) or 3.0
+
+   If you have an existing spec you want to validate, point me to its path."
+
+2. If the user provides a validate-mode path, verify the file exists. If it does not, report the error and fall back to generate mode with an ASK.
+3. Present a structured summary:
+
+```
+API Spec Brief:
+  Mode:         {generate | validate}
+  Format:       {yaml | json}
+  Output:       {path}
+  Scope:        {full | scoped to X}
+  Spec version: {3.1 | 3.0}
+```
+
+**ASK:** "Does this look right? Adjust anything before I scan the codebase."
+
+---
+
+### Step 2: Framework Detection
+
+1. Scan `package.json` dependencies and source patterns to identify the API framework. Supported detections: Express, Fastify, NestJS, tRPC, GraphQL, Hono, Next.js API Routes, Elysia. Assign confidence (high/medium/low) based on signal strength (dependency present + matching code patterns = high).
+
+2. Detect validation/schema libraries: Zod, class-validator, TypeBox, Joi, Ajv/JSON Schema, io-ts, Effect Schema.
+
+3. Check for existing OpenAPI tooling (`zod-to-openapi`, `swagger-jsdoc`, `@nestjs/swagger`, `tsoa`, `fastify-swagger`).
+
+4. Detect auth patterns by scanning middleware, guards, and decorators for JWT, API key, OAuth, or session-based auth.
+
+5. Present detection results:
+
+```
+Framework Detection:
+  Primary framework:  {name} ({confidence})
+  Schema library:     {name | none detected}
+  Existing OAS tools: {name | none detected}
+  Auth patterns:      {JWT / API key / OAuth / session / none detected}
+  Route base path:    {e.g., /api/v1}
+  Files to scan:      {N} files across {M} directories
+```
+
+**ASK:** "I detected the above. Corrections? Additional patterns I should look for (custom middleware, versioned routes, etc.)?"
+
+---
+
+### Step 3: Endpoint Discovery
+
+Spawn the `hatch3r-researcher` sub-agent in `codebase-analysis` mode with the confirmed framework and scope.
+
+**Researcher prompt must include:** the confirmed framework and schema library, the scope, instruction to follow the **hatch3r-researcher agent protocol**, and depth level `standard`.
+
+For each discovered endpoint, extract: HTTP method, path, path/query parameters, request body type, response type(s), status codes, auth requirement, tags/grouping, and description (from JSDoc or decorator metadata).
+
+Present the discovery summary:
+
+```
+Endpoint Discovery:
+  Total endpoints:   {N}
+  Methods:           GET: {n}, POST: {n}, PUT: {n}, PATCH: {n}, DELETE: {n}
+  Auth-protected:    {N} / {total}
+  With response types: {N}
+  Missing types:     {N} endpoints with no extractable request/response types
+  Grouped by:
+    {tag/controller}: {N} endpoints
+    ...
+```
+
+List endpoints with missing or incomplete type information.
+
+**ASK:** "I found {N} endpoints. {M} have incomplete type information (listed above). Options:
+- **Confirm** to proceed (incomplete endpoints get placeholder schemas)
+- **Add missing endpoints** you know exist but I didn't find
+- **Exclude endpoints** from the spec
+- **Provide type hints** for endpoints with missing types"
+
+---
+
+### Step 4: Schema Extraction
+
+For each endpoint with typed request/response shapes, extract the underlying types.
+
+1. **Resolve type references.** Follow one level of imports to capture referenced interfaces, enums, and union types.
+2. **Convert to OpenAPI schemas.** Map TypeScript types, Zod chains, class-validator decorators, TypeBox definitions, and Joi schemas to JSON Schema properties. Preserve descriptions from `.describe()` calls or JSDoc.
+3. **Deduplicate.** Identical types across endpoints become a single `components/schemas` entry referenced via `$ref`.
+4. **Detect shared patterns** — pagination wrappers, error response shapes, envelope patterns.
+
+```
+Schema Extraction:
+  Components extracted: {N} schemas
+  Shared patterns:      {pagination: yes/no, error shape: yes/no, envelope: yes/no}
+  Enums:                {N}
+  Unresolvable types:   {N} (will use empty schema)
+```
+
+No ASK checkpoint unless unresolvable types exceed 30% of total schemas:
+
+**ASK (conditional):** "{N}% of schemas could not be resolved. Continue with empty schemas, or provide type definitions manually?"
+
+---
+
+### Step 5: OpenAPI Assembly
+
+Build the complete OpenAPI document.
+
+1. **`info`** — from `package.json` (title, version, description).
+2. **`servers`** — detect from env config or Docker Compose; default `http://localhost:{port}`.
+3. **`paths`** — one entry per unique path. Each operation includes `operationId`, `summary`, `tags`, `parameters`, `requestBody`, `responses` (with `$ref`), and `security`.
+4. **`components/schemas`** — all extracted types as JSON Schema.
+5. **`components/securitySchemes`** — JWT Bearer, API Key, OAuth 2.0, or cookie/session based on detected auth patterns.
+6. **`tags`** — one per resource group with descriptions.
+
+Present a structural overview (not the full spec):
+
+```
+OpenAPI Spec Structure:
+  info.title:        {title}
+  info.version:      {version}
+  servers:           {N} servers
+  paths:             {N} paths, {M} operations
+  components:
+    schemas:         {N}
+    securitySchemes: {N}
+  tags:              {N}
+  Estimated size:    ~{N} lines
+```
+
+**ASK:** "Here is the spec structure. Review before I write the file to `{output path}`:
+- Confirm to write
+- Preview a specific section (paths, schemas, security)
+- Adjust structure (rename tags, regroup endpoints, change server URLs)"
+
+---
+
+### Step 6: Validation
+
+Run structural and content validation on the assembled spec.
+
+1. **Structural:** all `$ref` pointers resolve, no duplicate `operationId`, no duplicate path+method, required fields present.
+2. **Content quality:** endpoints missing `summary`/`description`, responses without error codes (400, 401, 500), request bodies without `required` fields, undocumented path parameters, security-sensitive endpoints without auth.
+3. **Convention checks** (from `hatch3r-api-design` rule if loaded): naming conventions, consistent error shapes, pagination consistency, versioning alignment.
+4. Run `spectral` or `redocly` CLI if available in the project.
+
+```
+Validation Results:
+  Structural:        {pass / N errors}
+  Descriptions:      {N} operations missing descriptions
+  Error codes:       {N} operations missing standard error responses
+  Security:          {N} sensitive endpoints without auth schemes
+  Conventions:       {N} violations (from hatch3r-api-design)
+  Spectral/Redocly:  {N warnings, M errors / not available}
+```
+
+Fix structural errors automatically. Present convention warnings for user decision.
+
+**ASK (if warnings exist):** "Validation found {N} warnings. Fix these before writing, or write as-is and address later?"
+
+---
+
+### Step 7: Drift Detection (Validate Mode Only)
+
+If mode is `validate`, compare the existing spec against discovered endpoints from Step 3.
+
+1. **Load and parse** the existing spec.
+2. **Classify each endpoint** as Matching (in both, types consistent), Undocumented (in code only), Stale (in spec only), or Drifted (in both, types differ).
+3. **Compare schemas** — fields added/removed in code vs. spec, type changes, optional→required shifts.
+4. **Compare security** — endpoints that gained or lost auth requirements.
+
+```
+Drift Report:
+  Matching:       {N} endpoints — no drift
+  Undocumented:   {N} endpoints in code, missing from spec
+    {method} {path} — {file}:{line}
+  Stale:          {N} endpoints in spec, not found in code
+    {method} {path}
+  Drifted:        {N} endpoints with schema differences
+    {method} {path} — {diff summary}
+  Security drift: {N} endpoints with auth changes
+```
+
+**ASK:** "Drift report above. Options:
+- **Update spec** — merge undocumented, remove stale, update drifted
+- **Report only** — write drift report to `docs/api/drift-report.md`
+- **Selective update** — tell me which changes to apply"
+
+---
+
+### Step 8: Output
+
+After all confirmations:
+
+1. **Write the spec file** to the confirmed output path. Create parent directories if needed.
+2. **Write a summary report** to `docs/api/api-spec-summary.md` containing: generation date, mode, framework, endpoint/schema/tag counts, coverage percentages (descriptions, request types, response types, error responses, auth), endpoints-by-tag breakdown, and unresolved issues.
+3. If validate mode with updates, write the updated spec.
+4. Present final summary:
+
+```
+Files Created/Updated:
+  {output path}                — {N} endpoints, {M} schemas
+  docs/api/api-spec-summary.md — coverage and stats report
+  docs/api/drift-report.md     — drift report (validate mode only, if applicable)
+```
+
+---
+
+## Error Handling
+
+- **No route definitions found:** Report and ASK the user to confirm framework, point to route files, or check scope. Do not generate an empty spec.
+- **Types not extractable (JS without JSDoc):** Warn schemas will be `{}`. Recommend adding JSDoc or TypeScript types. Proceed with placeholders if confirmed.
+- **Multiple API frameworks detected:** Present all with file counts and confidence. ASK which to use as primary, or generate a combined spec with tags separating frameworks.
+- **Existing spec parse failure (validate mode):** Report parse error with line number. ASK whether to regenerate or fix manually first.
+- **Circular type references:** Break cycle with `$ref` to root type and warn the user.
+- **File write failure:** Report error and provide full spec content for manual creation.
+- **Missing `package.json`:** Use placeholders for `info.title`/`info.version`. ASK the user to provide values.
+- **Researcher sub-agent failure:** Retry once. If it fails again, fall back to inline scanning with reduced depth.
+
+## Guardrails
+
+- **Never overwrite an existing spec without confirmation.** Present a diff summary and ASK before writing.
+- **Never skip ASK checkpoints.** Every step with an ASK must pause for user confirmation.
+- **Flag endpoints with no request/response types.** Always surface these rather than silently generating `{}`.
+- **Warn about security endpoints without auth schemes.** Auth, payments, and user data endpoints must have `security` defined.
+- **Do not invent endpoints.** Only document routes that exist in code.
+- **Do not modify application code.** This command reads the codebase — it writes only to spec and documentation files.
+- **Respect existing spec structure in validate mode.** Preserve custom descriptions, examples, and `x-*` extensions.
+- **Schema names must be stable.** Use original TypeScript type/interface names — consumers may depend on name stability.
+- **Respect the project's tooling hierarchy** for knowledge augmentation: project docs → codebase exploration → Context7 MCP → web research.
+- **Spec must be valid.** Never write a spec that fails structural validation. Fix issues before writing.
+
+## Output Templates
+
+### Spec Header
 
-### Validate Mode
+```yaml
+openapi: "3.1.0"
+info:
+  title: "{package name}"
+  version: "{package version}"
+  description: "{package description}"
+servers:
+  - url: "http://localhost:{port}"
+    description: "Local development"
+```
 
-1. **Read the existing spec** from the output path.
-2. **Scan the codebase** for current endpoints (same as generate step 1).
-3. **Compare:** identify endpoints in code but not in spec (undocumented), and endpoints in spec but not in code (stale).
-4. **Schema drift:** check if request/response types in code have diverged from spec schemas.
-5. **Report** discrepancies with file locations and suggested fixes.
+### Drift Report Entry
 
-## Output
+```markdown
+### {METHOD} {path}
 
-- Generated or validated OpenAPI spec file
-- Summary of endpoints documented/missing/stale
-- Validation errors if any schema issues found
+- **Status:** {Undocumented | Stale | Drifted}
+- **File:** `{source file}:{line}`
+- **Details:** {what differs — added/removed fields, type changes}
+- **Suggested fix:** {add to spec / remove from spec / update schema}
+```
 
 ## Related
 
-- **Skill:** `hatch3r-api-spec` — detailed workflow for spec authoring
-- **Rule:** `hatch3r-api-design` — API design conventions to follow
+- **Rule:** `hatch3r-api-design` — API design conventions the generated spec must follow
+- **Command:** `hatch3r-codebase-map` — structural map that can help scope the API scan
+- **Command:** `hatch3r-project-spec` — project-level specification for API info block context
+- **Agent:** `hatch3r-researcher` — performs codebase scan for route definitions
+- **Agent:** `hatch3r-docs-writer` — assembles the final spec document
+- **Agent:** `hatch3r-reviewer` — validates the generated spec for correctness