---
name: spec-write
description: Author timeless specification documents under spec/ (top-level or spec/feature/<FEATURE>.md) following the project hierarchy, naming conventions, and templates. Use when the user asks to write, design, or document a DataSpoke feature, component, or architectural decision as a reference spec. Do NOT use for implementation plans — those live in GitHub issues/PRs and are produced by native Plan mode or PRauto.
argument-hint: <topic>
allowed-tools: Read, Write, Edit
---

## Spec Directory Hierarchy

```
spec/
├── MANIFESTO_en.md / _kr.md   ← Highest authority. Product identity, five-feature
│                                 baseline (§2.1), naming. Never modify.
├── ARCHITECTURE.md            ← System-wide architecture: components, tech stack,
│                                 data flows, feature-to-architecture mapping,
│                                 shared services, deployment. Conforms to MANIFESTO.
├── USE_CASE_en.md / _kr.md    ← Conceptual scenarios UC1–UC5.
├── AI_SCAFFOLD.md             ← Goal 2: Claude Code scaffold conventions.
├── TESTING.md                 ← Testing conventions: toolchain, unit/integration/E2E
│                                 workflows, Imazon test data.
├── DATAHUB_INTEGRATION.md     ← DataHub SDK patterns, aspect catalog, GraphQL,
│                                 event subscription, error handling.
├── API_DESIGN_PRINCIPLE_en.md / _kr.md
│                              ← REST API conventions: URI structure, request/response
│                                 format, content/metadata separation, meta-classifiers.
│
└── feature/            ← Deep-dive specs for ALL FIVE BASELINE features
    │                     (Ingestion Control, Validation, Ontology Generation,
    │                     Metadata Generation, Governance) plus cross-cutting
    │                     infrastructure and per-function FRONTEND specs.
    │                     Timeless reference format.
    └── <FEATURE>.md      e.g. BACKEND.md, BACKEND_SCHEMA.md, FRONTEND_BASIC.md,
                          FRONTEND_GOVERNANCE.md, FRONTEND_INGESTION.md,
                          FRONTEND_VALIDATION.md, FRONTEND_ONTOGEN.md,
                          FRONTEND_METAGEN.md, HELM_CHART.md
```

**Routing rules:**
- Top-level `spec/` — project-wide documents only. Do NOT create new top-level files unless the topic affects the whole system and warrants an architectural-level document.
- `spec/feature/` — **all baseline feature deep-dives** (Ingestion Control, Validation, Ontology Generation, Metadata Generation, Governance) plus cross-cutting infrastructure (e.g. `API.md`, `BACKEND.md`, `HELM_CHART.md`) and one FRONTEND spec per function area (`FRONTEND_BASIC.md` for shell/auth/admin, plus `FRONTEND_{GOVERNANCE,INGESTION,VALIDATION,ONTOGEN,METAGEN}.md`). Organization-specific extensions in forks add new files alongside (e.g. `feature/SEARCH.md`); no separate subdirectory is required.

Implementation plans and decision records are tracked via GitHub Issues and PRs, not in the spec directory.

---

## Step 1 — Read context

Always read these before writing:
- `spec/MANIFESTO_en.md` — canonical baseline-feature taxonomy and naming (highest authority)
- `spec/ARCHITECTURE.md` — components, tech stack, data flows, feature-to-architecture mapping, shared services (Ontology Generator, DataHub Client Wrapper), deployment

Additionally, read these when relevant to the topic:
- `spec/DATAHUB_INTEGRATION.md` — when the feature involves DataHub read/write/event patterns
- `spec/API_DESIGN_PRINCIPLE_en.md` — when designing API endpoints
- `spec/USE_CASE_en.md` — for use case context (UC1–UC5)

If writing about a specific feature, also check for an existing `spec/feature/<FEATURE>.md` to extend rather than create a duplicate.

---

## Step 2 — Determine destination and document type from `$ARGUMENTS`

| Destination | When to use | Document type |
|-------------|-------------|---------------|
| `spec/feature/<FEATURE>.md` | A baseline feature (Ingestion Control, Validation, Ontology Generation, Metadata Generation, Governance), a common cross-cutting topic (API, dev environment, shared services), a per-function FRONTEND spec (`FRONTEND_{BASIC,GOVERNANCE,INGESTION,VALIDATION,ONTOGEN,METAGEN}.md`), or an organization-specific extension in a fork (e.g. `SEARCH.md`). | Feature Spec (see template A) |
| `spec/<DOC>.md` (top-level) | Only for project-wide topics that belong alongside MANIFESTO and ARCHITECTURE | Top-level spec (use template A without feature context) |

---

## Step 3 — Write the document

Use the template for the chosen destination. Follow these style rules for both:
- H1 title
- H2 section headings, H3 sub-headings
- ASCII diagrams for component/flow illustrations
- Tables for comparisons and field definitions
- Code blocks for schemas, interfaces, API examples
- Baseline feature names must match the MANIFESTO §2.1 exactly: **Ingestion Control**, **Validation**, **Ontology Generation**, **Metadata Generation**, **Governance**
- Product name is always `DataSpoke` (no space)
- API URIs follow the function-namespace pattern: `/api/v1/spoke/{governance,ingestion,validation,ontogen,metagen}/…` plus `/api/v1/hub/…` (DataHub pass-through)
- For DataHub integration details, reference `DATAHUB_INTEGRATION.md` rather than duplicating SDK patterns or aspect catalogs
- For API convention details, reference `API_DESIGN_PRINCIPLE_en.md` rather than restating URI/response format rules
- When referencing architecture-level concepts (shared services, data flows, tech stack), align with `ARCHITECTURE.md`

---

## Template A — Feature Spec (`spec/feature/<FEATURE>.md`)

No version/date/author metadata block. This is a timeless reference document.

```markdown
# <Feature Name>

## Table of Contents
1. [Overview](#overview)
2. [Goals & Non-Goals](#goals--non-goals)
3. [Design](#design)
4. [Data Model](#data-model)
5. [Interfaces](#interfaces)
6. [Open Questions](#open-questions)

## Overview

## Goals & Non-Goals
### Goals
### Non-Goals

## Design

## Data Model

## Interfaces

## Open Questions
- [ ]
```

---

## Step 4 — Update cross-references if needed

- If a new `spec/feature/` document introduces components or data models that belong in the architecture overview, update `spec/ARCHITECTURE.md`.
- If the document changes how a use case is realized, note it in `spec/USE_CASE_en.md` as a cross-reference.
- Never modify `spec/MANIFESTO_en.md` or `spec/MANIFESTO_kr.md`.
