AgentSkillsCN

docs-first

适用于当一项任务需要以规范驱动的工作流程时：起草/更新 PRD + TECH_SPEC + ACTION_PLAN + 任务，在 tasks/index.json 中链接 TECH_SPEC，并在实施前进行文档审查。

SKILL.md
--- frontmatter
name: docs-first
description: "Use when a task requires a spec-driven workflow: draft/refresh PRD + TECH_SPEC + ACTION_PLAN + tasks, link TECH_SPEC in tasks/index.json, and run docs-review before implementation."

Docs-First (Spec-Driven)

Overview

Use this skill when a task needs a spec-driven workflow. The objective is to create or refresh PRD + TECH_SPEC + ACTION_PLAN + the task checklist before editing code or docs, capture a brief translation of the user’s request in the PRD for context retention, and keep task mirrors and review evidence in sync as understanding evolves.

Workflow

  1. •Draft or refresh PRD + TECH_SPEC + ACTION_PLAN
  • •PRD: capture intent and user-request translation (use .agent/task/templates/prd-template.md).
  • •TECH_SPEC: capture technical requirements (use .agent/task/templates/tech-spec-template.md; stored under tasks/specs/<id>-<slug>.md).
  • •ACTION_PLAN: capture sequencing/milestones (use .agent/task/templates/action-plan-template.md).
  • •Depth scales with scope, but all three docs are required.
  1. •Register the TECH_SPEC and task
  • •Add the TECH_SPEC to tasks/index.json (including last_review).
  • •Create/refresh the task checklist (tasks/tasks-*.md) and mirror to .agent/task/.
  • •Update docs/TASKS.md with the snapshot entry.
  • •When you need machine-readable artifacts, use a consistent template or structured output format.
  1. •Run docs-review before implementation
  • •npx codex-orchestrator start docs-review --format json --no-interactive --task <task-id>
  • •Link the manifest path in the checklists.
  1. •Implement and validate
  • •Keep PRD/TECH_SPEC/ACTION_PLAN, checklists, and manifests aligned.
  • •Update PRD/TECH_SPEC/ACTION_PLAN when new constraints, risks, or scope changes are discovered during implementation.
  • •If docs are missing or stale, stop and request approval before proceeding.

Output expectations

  • •PRD + TECH_SPEC + ACTION_PLAN + task checklist created/refreshed.
  • •TECH_SPEC linked in task registry and mirrors updated.
  • •Docs-review evidence captured before implementation.

Related docs

  • •docs/AGENTS.md
  • •docs/guides/instructions.md