devos-change-docs

Generate or sync change-oriented docs artifacts without allowing arbitrary repository writes.

Use this skill when a change needs:

• openspec/changes/<change>/blackbox-test.md
• openspec/changes/<change>/api-doc.md
• docs/reference/api.md

The caller owns final validation and writeback. This skill should return a structured result rather than directly editing repository files.

Workflow

1. Receive input — caller provides the mode, changeId (if change-scoped), and relevant artifacts.
2. Select mode and gather sources — determine which mode applies (change-blackbox, change-api, or project-api-sync) and collect the required source documents.
3. Generate content — produce the documentation following the mode-specific requirements below.
4. Return structured result — output a single JSON object with the generated content, or return needs-clarification if sources are insufficient.
5. Caller validates before writeback — the caller checks the result against the validation expectations and writes the file only after approval.

Modes

• mode=change-blackbox
• mode=change-api
• mode=project-api-sync

Input

The caller should provide:

• active changeId when the mode is change-scoped
• current change artifacts such as proposal.md, design.md, tasks.md, and relevant specs/**
• relevant implementation changes when request, response, compatibility, or error details need confirmation
• project artifact language policy when available
• existing docs/reference/api.md content for mode=project-api-sync

For mode=change-api, treat the current change artifacts as the primary source for scope. Use implementation changes to confirm and enrich details, not to silently redefine the change.

Structured Result

Return a single object:

{
  "schemaVersion": 1,
  "changeId": "add-auth",
  "mode": "change-api",
  "path": "openspec/changes/add-auth/api-doc.md",
  "content": "# ...",
  "sources": [
    "openspec/changes/add-auth/proposal.md",
    "openspec/changes/add-auth/design.md"
  ]
}