@ifrankwang/openspec-agents 0.133.2 → 0.135.0

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/schema.yaml

@@ -0,0 +1,466 @@
+name: spec-driven-standard
+version: 1
+description: Spec-driven workflow with clarify gate, related-surface survey, tiered authoring (orchestrator or single subagent) and review loop - clarify → proposal → specs → design → tasks
+artifacts:
+  - id: clarify
+    generates: clarify.md
+    description: Requirement and architecture clarification record
+    template: clarify.md
+    instruction: |
+      **Orchestration contract (addressed to YOU, the orchestrating agent)**:
+      Duties are split into three phases. You personally run Phase 1 and
+      Phase 3. Phase 2 is TIERED by change complexity: for SIMPLE changes
+      you write proposal/specs/design/tasks yourself; for COMPLEX changes a
+      single fresh generation subagent writes them. No subagent ever writes
+      clarify.md - you write it yourself as the interview record.
+
+      Phase 1 - Interview (you): investigate the codebase and existing
+      openspec/specs/ first, then interview the user in rounds over a
+      decision tree using the frontier mechanics (methodology below),
+      recording questions and answers directly into <changeRoot>/clarify.md
+      as you go (sections below) - there is no separate interview file.
+      HARD-GATE: the interview is over only when every branch of the decision
+      tree has been visited, no doubt is left open, nothing is silently
+      assumed; then first present a simple, direct plan summary to the user
+      and get an explicit confirmation of the direction - do NOT start
+      Phase 2 (authoring) until the user has confirmed it (details in
+      methodology below).
+
+      Phase 2 - Authoring (TIERED): only after the user has explicitly
+      confirmed the plan summary (HARD-GATE above), decide the tier using
+      the complexity criteria below, record the decision and one-line
+      rationale in clarify.md, then
+      follow the matching mode:
+      - SIMPLE tier: you personally produce the remaining artifacts
+        (proposal → specs → design → tasks) in dependency order. For each
+        artifact run `openspec instructions <artifact-id> --change
+        "<name>" --json` yourself, read the project's AGENTS.md and
+        openspec/config.yaml rules plus the dependency artifacts (starting
+        from the clarify.md you wrote), and write to the resolved output
+        path. Do not dispatch any subagent for authoring.
+      - COMPLEX tier: dispatch a single fresh general-purpose subagent
+        with the change name. It produces the remaining artifacts in one
+        session: for each it runs
+        `openspec instructions <artifact-id> --change "<name>" --json`
+        itself, reads the project's AGENTS.md and openspec/config.yaml
+        rules plus the dependency artifacts, and writes to the resolved
+        output path. It may only read/write inside the change directory
+        (openspec/changes/<name>/). It must not dispatch further
+        subagents, and its final report MUST end by telling you to start
+        Phase 3.
+
+      Complexity criteria - COMPLEX if ANY applies, otherwise SIMPLE:
+      - touches 2+ capabilities or 2+ task groups with cross-group
+        dependencies;
+      - significant data-model change (new tables, many columns, or any
+        data migration);
+      - new external dependency, new architectural pattern, or notable
+        security/performance/migration complexity;
+      - expected total artifact size would push your context near the
+        window limit if you wrote them yourself (large DDL, long task
+        lists, multi-spec changes).
+      When in doubt, choose COMPLEX: it keeps the orchestrating agent's
+      context lean and is the safer default.
+
+      Phase 3 - Review loop (you, once authoring is complete):
+      1. Dispatch an independent review subagent (fresh general-purpose
+         session — never reuse the generation subagent). It must:
+         - run `openspec validate "<name>" --strict` for structural checks
+           (note: validate takes the change name as a positional argument,
+           no --change flag);
+         - check every artifact against the openspec/config.yaml rules for
+           its stage, the schema templates/instructions, and cross-document
+           consistency (clarify direction ↔ proposal capabilities ↔ specs
+           requirements ↔ design decisions ↔ tasks with [spec:...]
+           traceability tags);
+         - read openspec/specs/ main specs (read-only) and cross-check:
+           proposal capabilities actually exist there, and delta
+           requirements/contracts (e.g. error codes, rate-limit semantics,
+           existing implementations) do not conflict with what the main
+           specs already establish;
+         - write findings to <changeRoot>/.review/issues.md, one block per
+           issue with fields: severity | file | problem | suggested fix;
+           write "PASS" when clean. The .review/ directory exists only for
+           this working file during the loop - never use it to record
+           anything else.
+      2. If issues.md is not "PASS", YOU fix every issue yourself
+         (change-directory documents only; you must not modify issues.md
+         itself, and you must not delegate fixes to a subagent — fixing
+         in your own context is the token-saving design).
+      3. Re-dispatch the review subagent for a fresh full review; loop
+         until "PASS" or 3 review rounds. After 3 rounds with remaining
+         issues, stop and present the leftover issues to the user.
+      4. On "PASS", delete the .review/ directory.
+
+      Do NOT hand over to the apply workflow before Phase 3 ends with
+      "PASS" (or with leftover issues explicitly accepted by the user).
+
+      Create the clarify document that records the requirement clarification and
+      architecture direction exploration BEFORE any proposal is written. This
+      artifact is MANDATORY for every change - it captures the think-before-build
+      phase, grounded in the actual codebase and existing specs.
+
+      Methodology:
+      - Investigate the codebase and existing openspec/specs/ first. Ground every
+        question in real code; do not theorize without reading the relevant modules.
+      - Surface unknowns across these dimensions and resolve them with the
+        user by interviewing in rounds over a decision tree (every decision
+        branches into the decisions that hang off it):
+        * Problem & intent: what problem is being solved? what is the success criteria?
+        * Scope: what is in/out of bounds? is the change decomposable into sub-changes?
+        * Related-surface survey (关联场景清点): enumerate every consumer of the
+          capability being changed, grounded in real code — functional entry points
+          (API endpoints, import/export entries, scheduled jobs, message consumers,
+          frontend calls), shared processing logic reused by multiple entry points,
+          and downstream data consumers (readers/writers of the tables, fields,
+          events, or export artifacts involved). Record each finding with code
+          evidence (file/class/method) in clarify.md's Related-Surface Survey
+          section. When shared processing logic changes, every consuming entry
+          point must be adapted within the SAME change; splitting into separate
+          changes requires an explicit boundary rationale confirmed by the user.
+        * Data model: which entities/tables/fields are involved? any new tables or columns?
+        * Business rules: which are deterministic vs non-deterministic, per the
+          project's conventions (see AGENTS.md)?
+        * Integration boundaries: external systems, APIs, ports/adapters?
+        * Architecture direction: propose 2-3 approaches with tradeoffs and a recommendation.
+      - Round mechanics: each round asks every question whose prerequisites
+        are already settled (the whole frontier at once) via the question
+        tool, numbered, each with your recommended answer; then wait for
+        the user's answers before the next round. A question whose answer
+        depends on one still open in this round belongs to a later round.
+        Facts are yours to find (codebase, specs, tools) - never ask the
+        user for anything you can look up yourself; the decisions are the
+        user's. Rounds continue until the frontier is empty: every branch
+        visited, no doubt left unresolved, nothing silently assumed.
+      - Challenge assumptions (yours and the user's). Reframe the problem when needed.
+      - Plan confirmation gate (HARD-GATE): once the interview rounds have
+        exhausted every open doubt (frontier empty) and before starting
+        Phase 2 (authoring — whether by you or
+        by a generation subagent), present a simple, direct plan summary to
+        the user and stop for confirmation. The summary must state: what the
+        change does in one sentence; whether it touches contracts (API
+        parameters or DDL); the chosen approach and its key trade-offs
+        versus the alternatives; the capabilities affected. Interview
+        answers do NOT count as confirmation — the confirmation must be a
+        direct user response to this summary. If the user requests changes,
+        revise the summary and re-present; loop until the user explicitly
+        confirms. Record the confirmed summary in clarify.md's Architecture
+        Direction section. "Too simple to need clarification" is not a
+        valid reason to skip; the clarify record may be short but must
+        exist, and this confirmation step is still mandatory.
+
+      Sections (see template):
+      - **Open Questions**: the unknowns surfaced, one per bullet.
+      - **User Answers**: the user's responses, captured verbatim or summarized.
+      - **Related-Surface Survey**: the related-surface survey output (关联场景清点) —
+        every consuming entry point / shared processing logic / downstream
+        consumer with code evidence, and the scoping verdict for each. Shared
+        processing logic changes must be covered together with all their
+        consuming entry points in the same change.
+      - **Architecture Direction**: the crystallized approach, key decisions,
+        alternatives considered, and the confirmed plan summary with
+        the user's explicit confirmation. This is the HARD-GATE output.
+      - **Initial Capabilities**: preliminary guess of which specs will be touched
+        (kebab-case). Finalized in proposal.md.
+
+      This is the foundation for proposal, specs, design, and tasks. All later
+      artifacts must stay consistent with the direction recorded here.
+    requires: []
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create the proposal document that establishes WHY this change is needed.
+
+      Sections:
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+      - **Related Surface (关联场景)**: the survey conclusions from clarify.md —
+        every consuming entry point / shared processing logic / downstream
+        consumer with code evidence and its scoping verdict (adapted in this
+        change, or explicitly justified out). When shared processing logic
+        changes, every consuming entry point must be adapted in THIS change;
+        splitting into separate changes requires a boundary rationale section
+        confirmed by the user. A bare "no related impact" without search
+        evidence counts as an incomplete proposal.
+      - **Capabilities**: Identify which specs will be created or modified:
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
+      - **Impact**: Affected code, APIs, dependencies, or systems.
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract between
+      proposal and specs phases. Research existing specs before filling this in.
+      Each capability listed here will need a corresponding spec file.
+
+      Every change must either declare at least one capability (new or
+      modified) or explicitly opt out of specs: `openspec validate` rejects a
+      change with zero deltas unless the change's `.openspec.yaml` sets
+      `skip_specs: true`. Use `skip_specs: true` only when no spec-level
+      behavior changes (pure refactor, tooling, docs) - specs describe
+      behavior, so if behavior does not change, no spec should change either.
+      Do not invent a requirement just to satisfy validation.
+
+      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+      implementation details belong in design.md. Stay consistent with
+      clarify.md's architecture direction; if the proposal drifts from clarify,
+      update clarify first and get user confirmation.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    requires:
+      - clarify
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create specification files that define WHAT the system should do.
+
+      A spec is a behavior contract, not an implementation plan.
+
+      Good spec content:
+      - Observable behavior users or downstream systems rely on
+      - Inputs, outputs, and error conditions
+      - External constraints (security, privacy, reliability, compatibility)
+      - Scenarios that can be tested or explicitly validated
+
+      Avoid in specs:
+      - Internal class/function names
+      - Library or framework choices
+      - Step-by-step implementation details
+      - Detailed execution plans (those belong in design.md or tasks.md)
+
+      Quick test: if the implementation can change without changing externally
+      visible behavior, it likely does not belong in the spec.
+
+      Create one spec file per capability listed in the proposal's Capabilities section.
+      `<capability-path>` is the spec directory relative to `specs/` (for example,
+      `user-auth` or `identity/user-auth`). Preserve the full path:
+      - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
+      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
+
+      There must be at least one spec file unless the change's `.openspec.yaml`
+      sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
+      rejects a zero-delta change without that marker. If the proposal lists no
+      capabilities and `skip_specs` is not set, revisit the proposal first.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+
+      New capabilities only: start the delta spec with a `## Purpose` section -
+      one or two sentences (50+ characters, or `openspec validate --strict`
+      reports it as too brief) describing what the capability is for. Archive
+      copies it into the main spec it creates; without it the new main spec is
+      left with a `TBD ... Update Purpose after archive` placeholder to fill in
+      by hand. Do NOT add `## Purpose` to a delta for an existing capability -
+      that spec already has one and the delta's is ignored. To change an
+      existing capability's Purpose - including a leftover `TBD` placeholder -
+      edit `openspec/specs/<capability-path>/spec.md` directly.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in openspec/specs/<capability-path>/spec.md
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+      If adding new concerns without changing existing behavior, use ADDED instead.
+
+      Specs should be testable - each scenario is a potential test case.
+    requires:
+      - proposal
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create the design document that explains HOW to implement the change.
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Data Model**: MANDATORY when the change involves persistence. Complete
+        DDL (CREATE TABLE with columns, types, constraints), field descriptions,
+        indexes, and audit fields. Follow the project's persistence conventions
+        (see AGENTS.md / openspec/config.yaml rules). If the change does not
+        involve persistence, state that explicitly ("本变更不涉及持久化" or the
+        project's equivalent phrasing).
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Unknowns that can safely be answered later without
+        changing the specs, the approach, or the task breakdown. Omit if none.
+
+      Open questions are for genuinely deferrable unknowns, not decisions you
+      skipped. If a question would change the specs, the chosen approach, or
+      the task breakdown, resolve it now - ask the user instead of guessing.
+
+      Focus on architecture and approach, not line-by-line implementation.
+      The proposal covers why and what; design covers how. Reference the
+      proposal for motivation and, once written, the specs for requirements -
+      if a section would only restate them, point to them instead.
+
+      Good design docs explain the "why" behind technical decisions.
+    requires:
+      - proposal
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create the task list that breaks down the implementation work.
+
+      Before writing tasks, check design.md for Open Questions. If any of them
+      would change what gets built, resolve them with the user first - do not
+      bake an unstated assumption into the task list.
+
+      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+
+      Guidelines:
+      - Group related tasks under `## N. <Task Group Name>` numbered headings
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Each task SHOULD end with a traceability tag `[spec:<capability>#<requirement>]`
+        (or `[infra]` for pure cross-cutting infrastructure tasks). Business tasks
+        without a spec target are out of scope - remove them or add the spec
+        requirement first.
+      - **Related-surface coverage (关联场景覆盖)**: the task groups must cover
+        every consuming entry point that the proposal's Related Surface section
+        scopes into this change; an in-scope entry point without an adaptation
+        task counts as an incomplete task list.
+      - **Each task group = one independent iteration.** Every group MUST contain:
+        implementation + tests + a quality gate (the project's quality gate per
+        openspec/config.yaml rules / AGENTS.md). No standalone QA group - quality
+        is embedded in every iteration. Groups must be independently implementable:
+        when a group is done, the code compiles and tests pass.
+      - **No verification group, pure or mixed.** Pure verification work —
+        quality-gate runs (e.g. a final full build verification), end-to-end / integration /
+        regression / smoke verification, residual-search sweeps (旧键残留检索),
+        regression confirmation — must never form a task group of its own:
+        neither standalone, nor as a "wrap-up" group that mixes them with
+        doc/script/config sync tasks (e.g. 「阶段二收尾：文档、脚本与全量验证」).
+        Fold verification tasks into the functional group they verify. Doc/script/
+        config sync tasks are functional work and join the functional group they
+        accompany — their presence does not legitimize a wrap-up group. Group
+        titles name the delivered business value; 收尾/验证/回归 must never be a
+        group's identity.
+      - **Minimum substance per group.** Every group's body must be substantive
+        change content: at least one task that changes behavior-bearing code or
+        config (implementation + its tests). Doc/script/deploy-doc sync,
+        verification, regression and quality-gate tasks are accompaniment —
+        they may join a functional group but never constitute its substance,
+        and task count does not substitute for substance (a 6-task group of
+        only sync + verification work still violates this rule). The last
+        group of a change is the typical decay spot: when the work remaining
+        for a would-be group is only sync + verification, fold it into the
+        preceding functional group instead of opening a tail group.
+      - Grouping priority (in order):
+        1. **Implementation order**: groups follow the project's layer dependency
+           order (see AGENTS.md / config.yaml rules). Earlier groups define
+           interfaces/models that later groups consume.
+        2. **Coherent scope**: each group delivers a complete, verifiable business
+           value — a feature, a sub-feature, or a set of closely related capabilities.
+        3. **Group size balance**: aim for 4-8 tasks per group. Groups with < 4
+           tasks → merge into an adjacent group. Groups with > 8 tasks → split
+           into focused sub-groups (each with its own tests and quality gate).
+      - Task ordering within a group: dependency chain — define → implement →
+        test → quality gate.
+      - Tasks should be small enough to complete in one session (~5-10 min coding).
+        Implementation details exceeding 10 lines belong in actual code, not as
+        separate sub-tasks.
+
+      Reference specs for what needs to be built, design for how to build it.
+      Each task should be verifiable - you know when it's done.
+
+      **Final report (process constraint)**: When this artifact is written,
+      every artifact of the change exists and the authoring session ends
+      here. You must NOT dispatch any subagent yourself. If you are the
+      generation subagent (COMPLEX tier), your final report MUST end by
+      telling the orchestrating agent to start the review loop (Phase 3 of
+      the clarify artifact's orchestration contract) - without that handoff
+      the review never happens. If you are the orchestrating agent (SIMPLE
+      tier), go straight to Phase 3 yourself and dispatch the independent
+      review subagent.
+    requires:
+      - specs
+      - design
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Follow the project's implementation conventions (AGENTS.md, openspec/config.yaml
+    rules, and any orchestration workflow the project uses).
+    Pause if you hit blockers or need clarification.

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/templates/clarify.md

@@ -0,0 +1,54 @@
+## Open Questions
+
+<!-- Unknowns surfaced during clarification. One per bullet. Cover: problem & intent,
+     scope, related-surface survey, data model, business rules, integration
+     boundaries, architecture approaches. Resolve them with the user by
+     interviewing in rounds over a decision tree: each round asks every currently
+     answerable question (numbered, each with a recommended answer); keep going
+     until no doubt is left unresolved and nothing is silently assumed. -->
+
+- <!-- question -->
+
+## User Answers
+
+<!-- The user's responses, captured verbatim or summarized. -->
+
+- <!-- answer -->
+
+## Related-Surface Survey
+
+<!-- 关联场景清点：every consumer of the capability being changed, grounded in
+     code evidence (file/class/method): functional entry points (API endpoints,
+     import/export entries, scheduled jobs, message consumers, frontend calls),
+     shared processing logic reused by multiple entry points, and downstream
+     data consumers (readers/writers of the tables, fields, events, or export
+     artifacts involved). When shared processing logic changes, every consuming
+     entry point must be adapted in the SAME change; splitting into separate
+     changes requires an explicit boundary rationale confirmed by the user. -->
+
+- <!-- entry point / shared logic / downstream consumer + code evidence + scoping verdict -->
+
+## Architecture Direction
+
+<!-- The crystallized approach: chosen direction, key decisions, 2-3 alternatives
+     considered with tradeoffs, and the plan summary the user explicitly confirmed
+     (interview answers alone do not count as confirmation). This is the HARD-GATE
+     output — proposal, specs, design, and tasks must stay consistent with what is
+     recorded here. -->
+
+## Authoring Tier
+
+<!-- SIMPLE or COMPLEX, with a one-line rationale (criteria in the clarify
+     instruction's Phase 2). SIMPLE: orchestrating agent writes proposal →
+     specs → design → tasks itself. COMPLEX: one generation subagent writes
+     them. Recorded here for auditability before Phase 2 starts. -->
+
+- Tier: <!-- SIMPLE / COMPLEX -->
+- Rationale: <!-- one line -->
+
+## Initial Capabilities
+
+<!-- Preliminary guess of which specs will be created or modified (kebab-case names).
+     Finalized in proposal.md Capabilities section. -->
+
+- `<name>`: <!-- what this capability covers -->

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/templates/design.md

@@ -0,0 +1,31 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale. For each: the choice, why, and alternatives considered. -->
+
+## Data Model
+
+<!-- MANDATORY when the change involves persistence. Complete DDL: CREATE TABLE with
+     columns, types, constraints; field descriptions; indexes; audit fields.
+     Follow the project's persistence conventions (AGENTS.md / openspec/config.yaml
+     rules: table prefix, primary key strategy, logical delete, audit columns).
+     If no persistence, state that explicitly. -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs. Format: [Risk] → Mitigation -->
+
+## Open Questions
+
+<!-- Outstanding decisions or unknowns to resolve -->

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/templates/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Related Surface
+
+<!-- 关联场景：survey conclusions from clarify.md — each entry point / shared
+     processing logic / downstream consumer with code evidence and its scoping
+     verdict (adapted in this change, or explicitly justified out with a boundary
+     rationale confirmed by the user). Shared processing logic changes must cover
+     all consuming entry points in this change. A bare "no related impact"
+     without search evidence counts as an incomplete proposal. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
+- `<existing-name>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/templates/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/templates/tasks.md

@@ -0,0 +1,41 @@
+<!--
+  模板说明：每个 ## N. 是一个独立迭代（task group），编排工具会逐个处理。
+  每个迭代必须自带质量保证：实现代码 + 测试 + 项目质量门（见 AGENTS.md）。
+  每组必须以实质变更为主体：至少一个任务承载真实的代码/配置行为变更（实现 + 测试）。
+  任务组划分必须覆盖 proposal「关联场景」小节划入本 change 的全部消费入口。
+  禁止把纯验证工作（质量门、端到端/回归/冒烟/残留检索）设为独立
+  任务组——无论单独成组还是混入文档/脚本同步拼成「收尾验证组」；文档/脚本同步
+  与验证只是功能组的随行任务，末位剩余工作只剩同步与验证时并入前一个功能组，
+  禁止新开收尾组，组标题以交付的业务价值命名。
+
+  > **各组**可独立实施，组内全部完成后编译通过、可启动、测试通过。
+  > **序号**即实施顺序——跨组依赖确保上游组提交后下游组可对接。
+  > 每个源文件在 tasks.md 中最多出现**一次**（避免跨组并行修改冲突）。
+-->
+
+> **前置 change：** 本 change 依赖 <name> change 完成后才可开始。参见 openspec/changes/<name>/。
+
+## 1. <迭代名称：业务价值或功能名称>
+
+<!-- 本组 4-8 个任务。独立迭代：实现 + 测试 + 质量门。
+     组内任务按依赖链排列：定义 → 实现 → 测试 → 质量门。
+     每个任务以 [spec:<capability>#<requirement>] 标注追溯（纯横切基础设施任务标 [infra]）。 -->
+
+- [ ] 1.1 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 1.2 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 1.3 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 1.4 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 1.5 <!-- 测试：UT + IT --> [spec:<capability>]
+- [ ] 1.6 <!-- 质量门：项目质量门通过（见 AGENTS.md） --> [infra]
+
+## 2. <迭代名称：业务价值或功能名称>
+
+<!-- 本组 4-8 个任务。独立迭代：实现 + 测试 + 质量门。
+     组内任务按依赖链排列：定义 → 实现 → 测试 → 质量门。 -->
+
+- [ ] 2.1 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 2.2 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 2.3 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 2.4 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 2.5 <!-- 测试 --> [spec:<capability>]
+- [ ] 2.6 <!-- 质量门 --> [infra]