AGENT SKILL

blueprint-authoring

Draft, refine, and tidy a multi-file project blueprint under blueprint/ as the exploratory pre-foundation draft, before any docs or specification work.

License 许可
MIT
最近更新
2026-07-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
blueprint-authoring
metadata
{ "version": "1.0.0" }
description
Draft, refine, and tidy a multi-file project blueprint under blueprint/ as the exploratory pre-foundation draft, before any docs or specification work.
compatibility
Codex and OpenCode

03 SKILL.md 正文

Blueprint Authoring

Create and maintain the project blueprint under blueprint/: the earliest, exploratory draft that captures product intent, technical direction, scope, and open questions before they are promoted into the docs/ foundation or into specs/. This is the draft stage. It is allowed to be tentative and to propose options, but every open decision must be marked as open, not silently resolved.

The blueprint is upstream of everything: docs-author later transcribes the approved blueprint into docs/, and spec-writer turns its buildable features into specs/.

Inputs

  • The operator's product idea, notes, or an existing blueprint to refine.
  • The current blueprint/ files, if any, and blueprint/README.md for the format.
  • Do not read or depend on docs/ or specs/; the blueprint precedes them.

Blueprint format

Follow the multi-file convention documented in blueprint/README.md:

  • blueprint/README.md is the index: metadata blockquote (working title, tagline, type, stack, architecture summary, estimate, status), reading order, a file-list table with section numbers, a one-paragraph summary, and an explicit status marker.
  • Each section file starts with a # §n — Title heading and a navigation line linking the previous and next sections, then cross-references other sections as [§n](file).
  • Code blocks that state a binding contract or algorithm are marked as binding; illustrative snippets are marked as illustration.
  • Version history is accumulative: append a new version row, never rewrite past decisions. A newer version may supersede conflicting detail, but the record of the older decision stays.

Procedure

  1. If starting fresh, scaffold from the template files under blueprint/, filling bracketed placeholders. If refining, read the existing blueprint in full first.
  2. Capture, in the right section files: pitch, mental model, feature scope (MVP / stretch / later / out of scope), tech stack, architecture, data model, technical deep dives, access control, folder structure, roadmap, notable challenges, positioning, and — for anything with a user interface — UX and design intent in §16.
  3. Keep the README.md index, reading order, and file-list table in sync with the files that actually exist.
  4. Record every unresolved product or technical decision explicitly as an open question rather than inventing an answer. Tentative choices must be labelled tentative.
  5. When tidying, preserve exact numbers, version pins, thresholds, and binding contracts the source already states; do not paraphrase a precise value.
  6. Update the version history and the status marker to reflect the current state.

Stop conditions

Stop and ask the operator when: the product goal itself is undefined, two sources conflict on a decision that changes scope, or the request would require promoting the draft into docs/ or specs/ (that is downstream work for docs-author and spec-writer).

Scope limits

  • Modify only files under blueprint/.
  • Never create or edit docs/, specs/, application code, tests, agent configuration, policies, scripts, or CI.
  • Never present a tentative or invented decision as settled; open questions stay visible.
  • Never rewrite version history to erase a past decision.

Output

Report the exact blueprint/ files changed, the current status marker, and the list of open questions the operator must resolve before the blueprint is promoted to docs/ and specs/.

04 同仓库更多 Skills