devos-docs

Generate or refresh project docs contract artifacts for a user project.

Write for AI readers first. Optimize for fast orientation during feature work and debugging, not prose elegance or exhaustive human onboarding.

Treat the AI-first skill path as canonical. Do not optimize for non-AI fallback consumers when choosing content shape.

End-to-End Workflow

1. Receive input (mode, repository context, optional artifact_language)
2. Gather evidence following the Repository Interrogation Order
3. Check Evidence Completeness checkpoints
4. Assemble JSON result contract (see Required Outputs)
5. Run Validation checks
6. Return validated contract (caller writes files)

Input

The caller must provide:

• mode=init or mode=refresh
• repository context sufficient to identify the primary external surface
• existing docs artifacts when running in mode=refresh
• a docs context pack when docs consumption is routed intentionally

Optional:

• artifact_language — language preference for generated content (e.g., zh-CN); defaults to en when not provided

For deterministic routing, the docs context pack should follow this order:

1. docs/surfaces.yaml
2. docs/codemaps/project-overview.md
3. docs/codemaps/module-map.md when the project is multi-module
4. docs/codemaps/modules/<artifactId>.md only when module routing can be determined

When mode=refresh is invoked from an OpenSpec-linked flow, the caller should also provide a change-aware refresh context containing:

• changeId
• relevant OpenSpec artifact paths
• changed paths
• optional target module hints
• existing docs artifacts

Required Outputs

Return a structured result contract rather than writing arbitrary files directly.

Minimum contract shape:

{
  "schemaVersion": 1,
  "mode": "init",
  "artifact_language": "en",
  "surfacesYaml": "primary_surface: ...",
  "codemaps": [
    {
      "path": "docs/codemaps/project-overview.md",
      "content": "...",
      "action": "upsert"
    }
  ]
}