devos-change-docs

name	devos-change-docs
description	Generate blackbox test docs, API docs, or sync API references for OpenSpec changes. Use when a change needs documentation artifacts like blackbox-test.md, api-doc.md, or stable API reference updates.
license	MIT
compatibility	Designed for OpenSpec-linked change flows and project-level API reference sync.
metadata	{"author":"praxis-devos","version":"0.1"}

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"
  ]
}

When the current change artifacts and implementation do not provide enough aligned evidence to produce a trustworthy result, return a clarification result instead:

{
  "schemaVersion": 1,
  "changeId": "add-auth",
  "mode": "change-api",
  "status": "needs-clarification",
  "reason": "design.md does not clearly identify affected external APIs"
}

The caller validates this structured result before writeback.

Allowed Write Targets

• mode=change-blackbox:
  • openspec/changes/<change>/blackbox-test.md
• mode=change-api:
  • openspec/changes/<change>/api-doc.md
• mode=project-api-sync:
  • docs/reference/api.md

No other repository paths are valid output targets for this skill.

Required Content

mode=change-blackbox

The document should cover:

• test objectives
• scope
• prerequisites
• request or operation constraints
• core blackbox scenarios
• pass criteria
• regression focus

mode=change-api

The document should cover:

• API overview
• API description
• request parameters
• response parameters
• business rules
• error cases
• example calls
• implementation locations
• compatibility notes and warnings when the change is breaking, migration-sensitive, or caller-visible

Scope discipline:

• use the current change artifacts to identify which external APIs belong to this change
• use implementation changes to fill in request, response, error, and compatibility details
• if the artifacts and implementation clearly conflict, return needs-clarification
• do not treat existing docs/reference/api.md as the source of truth for deciding the current change scope
• when no API change exists, this mode should not be selected by the caller

mode=project-api-sync

The document should update the stable API reference and cover:

• API overview
• endpoint catalog
• request/response summary
• compatibility notes
• contracts and implementation locations

When updating an existing docs/reference/api.md, prefer a non-destructive managed section strategy:

• replace only the managed section
• preserve user-authored content outside the managed section
• remove deleted endpoints from the managed inventory when they are no longer part of the stable API
• leave compatibility notes when a removal is breaking or migration-sensitive

Managed section markers:

• <!-- PRAXIS_API_REFERENCE_START -->
• <!-- PRAXIS_API_REFERENCE_END -->

Language Policy

Honor the current artifact language policy when it is provided.

The first implementation must support heading aliases for at least:

• zh-CN
• en

Keep code identifiers, commands, file paths, and capability names in their original form.

Validation Expectations

The caller validates:

• schemaVersion === 1
• mode is one of the supported values
• path matches the mode-specific allowlist
• content is non-empty
• changeId matches the active change when supplied for change-scoped modes
• required headings are present using the artifact-language alias set
• sources is an array when present
• status=needs-clarification includes a non-empty reason

Quality Bar

• write for humans reviewing a change, not for generic marketing copy
• stay tightly scoped to the current change or the stable API inventory
• prefer concrete request/response, rules, examples, and verification cues over vague summaries
• do not drift into codemap-style repository overviews; that remains the job of devos-docs