@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/speckit.plan.md

@@ -0,0 +1,223 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 语言要求
+
+- 与用户的阶段汇报、阻塞说明、结论汇总全部使用简体中文。
+- 实际写入仓库的 `plan.md`、`research.md`、`architecture.md`、`product-readiness.md`、`design-readiness.md`、`data-model.md`、`quickstart.md` 以及相关说明文档必须使用简体中文。
+- 即使模板原文是英文，实际落盘时也要把标题、说明、表格内容、占位文本改写成中文，但保持原有章节顺序。
+- 保留不能随意翻译的机器敏感标记与技术标识，例如 `[NEEDS CLARIFICATION]`、需求编号、路径、命令、协议名、库名、接口路径。
+
+## Outline
+
+1. **Setup**: Run `.agents/.specify/scripts/powershell/setup-plan.ps1 -Json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.agents/.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Delivery Mode Gate and confirm it matches `spec.md`
+   - Fill OSS Reuse Matrix for every requirement/capability that depends on a predefined OSS stack, existing platform, or third-party system
+   - Fill Integration Blockers & Evidence with machine-readable `TBD-*` rows and statuses
+   - Fill Connector & Adapter Strategy, including sample-vs-real adapter separation
+   - Fill Requirement Completion Gates and Verification Layers
+   - Generate testing left-shift truth sources: `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, and `test-manifest.json`
+   - Fill Truth Sources table
+   - Fill Product & Design Readiness gate table
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate architecture.md and verify module boundaries, data flow, integration points, irreversible decisions, and rule impact
+   - Phase 2: Generate product-readiness.md and verify product truth sources, including requirement-interface mapping and difficulty research
+   - Phase 3: Generate testing truth sources and machine-readable `test-manifest.json`
+   - Phase 4: Generate design-readiness.md and verify design-to-code truth sources, including AI image generation/review and image-to-frontend spec for UI work
+   - Phase 5: Generate data-model.md, contracts/, quickstart.md
+   - Phase 6: Update project rule files and agent context so downstream tasks consume current rules
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after planning artifacts are generated. Report branch, IMPL_PLAN path, readiness status, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+   - For each predefined OSS / external system → reuse-vs-build task
+   - For each missing environment / endpoint / RBAC / dashboard / panel / webhook prerequisite → blocker evidence task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Architecture
+
+**Prerequisites:** `research.md` complete
+
+1. Generate `architecture.md` from confirmed spec, existing codebase patterns, and best practices:
+   - Module boundaries and ownership
+   - Data flow and integration points
+   - Connector boundaries and interface-to-adapter layering
+   - Real adapter vs sample/mock adapter separation
+   - Irreversible or expensive decisions
+   - Concurrency, migration, contract, and coupling risks
+   - Smallest defensible architecture and rejected alternatives
+
+2. Verify architecture-to-rule impact:
+   - Which project rules become stale after this architecture
+   - Which `AGENTS.md`, `docs/harness/*`, `docs/context/*` entries must be updated
+
+**Output**: `architecture.md`
+
+### Phase 2: Product Readiness
+
+**Prerequisites:** `architecture.md` complete
+
+1. Verify or generate product artifacts:
+   - `docs/product/prd-lite.md`
+   - `docs/product/page-inventory.md`
+   - `docs/product/state-matrix.yaml`
+   - `docs/product/acceptance-criteria.md`
+   - `docs/product/requirement-interface-matrix.md`
+   - `docs/product/difficulty-research.md`
+
+2. Check required product coverage:
+   - Goals and non-goals
+   - Scope boundary
+   - Delivery mode and prototype/integration boundary
+   - Roles and permissions
+   - Page inventory
+   - Requirement-to-interface traceability for every P0/P1 requirement
+   - Upfront difficulty research for all high-risk unknowns
+   - Required states
+   - Measurable acceptance criteria
+
+**Output**: product-readiness.md
+
+### Phase 3: Testing Readiness
+
+**Prerequisites:** Product readiness complete
+
+1. Generate or verify `acceptance-examples.md`:
+   - Map every P0/P1 requirement to at least one scenario ID such as `AE-001`
+   - Include Given, When, Then, negative or edge case, observable oracle, and evidence path
+   - Do not use vague pass criteria such as "looks normal"
+
+2. Generate or verify `requirements-testability-review.md`:
+   - Mark every requirement as `Ready`, `Blocked`, `Needs Clarification`, or `Prototype Only`
+   - Record missing endpoint, RBAC, credential, dashboard/panel ID, webhook target, fixture, environment, or downstream evidence as a blocker
+   - For `integration` / `production`, keep related formal `FR-*` blocked while a linked blocker remains open
+
+3. Generate or verify `verify-matrix.md`:
+   - Map requirement IDs to acceptance examples, required test layers, test files, commands, evidence paths, and status
+   - Mark missing test files or commands as `TEST-GAP` instead of leaving cells blank
+   - Ensure `integration` / `production` requirements are not covered by unit tests alone
+
+4. Generate or verify `test-strategy.md`:
+   - Detect stack and list baseline command candidates
+   - Define affected-test selection strategy
+   - Define blocking failure rules and evidence directory
+
+5. Generate or verify `test-manifest.json`:
+   - Mirror delivery mode, baseline commands, requirement testability, layers, files, commands, evidence paths, blockers, and gaps
+   - Keep the JSON valid and minimal because stop hooks and verify workflows read it
+
+**Output**: `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, `test-manifest.json`
+
+### Phase 4: Design Readiness
+
+**Prerequisites:** Product and testing readiness complete
+
+1. Verify or generate design artifacts:
+   - `docs/design/design-brief.md`
+   - `docs/design/component-map.md`
+   - `docs/design/screen-states.md`
+   - `docs/design/design-tokens.json`
+   - `docs/design/ai-image-brief.md`
+   - `docs/design/ui-image-review.md`
+   - `docs/design/image-to-frontend-spec.md`
+
+2. Check required design-to-code coverage:
+   - Information architecture
+   - Layout and component rules
+   - Required screen states
+   - Responsive behavior
+   - Accessibility expectations
+   - Story / e2e / visual mapping
+   - CSS/token requirements for AI image generation
+   - Generated UI images reviewed against requirements and states
+   - Approved images translated into frontend implementation specs
+
+**Output**: design-readiness.md
+
+### Phase 5: Data & Contracts
+
+**Prerequisites:** Product, testing, and design readiness complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+3. **Resolve integration blockers**:
+   - Verify every `TBD-*` row has an evidence path
+   - For `integration` / `production` work, unresolved blockers must keep related requirements in planned/blocked state
+   - Record environment smoke, downstream connectivity, and failure-path evidence locations in `quickstart.md` or companion notes
+
+### Phase 6: Rules & Context Sync
+
+**Prerequisites:** `architecture.md`, product readiness, testing readiness, and design readiness complete
+
+1. Update project rule files affected by the final spec and architecture:
+   - Project root `AGENTS.md`
+   - `docs/harness/*` long-lived workflow/rule files
+   - `docs/context/*` architecture/dev-plan context files when present
+
+2. Remove stale assumptions so downstream tasks do not inherit outdated rules.
+
+3. **Agent context update**:
+   - Run `.agents/.specify/scripts/powershell/update-agent-context.ps1 -AgentType gemini`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: updated project rules, data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
+- Do not replace a real integration requirement with local mock/sample implementation unless the user explicitly accepts downgrade and the plan records formal FRs as still incomplete
+
+## Next Steps
+
+- `/speckit.tasks` - Break the plan into tasks
+- `/speckit.checklist` - Create a checklist for the domain

package/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/speckit.specify.md

@@ -0,0 +1,228 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 语言要求
+
+- 与用户的交互、澄清问题、推荐选项、完成汇报全部使用简体中文。
+- 实际写入仓库的 `spec.md` 及相关检查清单内容必须使用简体中文。
+- 即使模板原文是英文，实际落盘时也要把标题、说明、表格内容、占位文本改写成中文，但保持原有章节顺序。
+- 保留不能随意翻译的机器敏感标记与技术标识，例如 `[NEEDS CLARIFICATION]`、`FR-001`、`NFR-001`、`SC-001`、路径、命令、协议名、库名、接口路径。
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{{args}}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing branches before creating new one**:
+
+   a. First, fetch all remote branches to ensure we have the latest information:
+
+      ```bash
+      git fetch --all --prune
+      ```
+
+   b. Find the highest feature number across all sources for the short-name:
+      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
+      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
+      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+
+   c. Determine the next available number:
+      - Extract all numbers from all three sources
+      - Find the highest number N
+      - Use N+1 for the new branch number
+
+   d. Run the script `.agents/.specify/scripts/powershell/create-new-feature.ps1 -Json "{{args}}"` with the calculated number and short-name:
+      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+      - Bash example: `.agents/.specify/scripts/powershell/create-new-feature.ps1 -Json "{{args}}" --json --number 5 --short-name "user-auth" "Add user authentication"`
+      - PowerShell example: `.agents/.specify/scripts/powershell/create-new-feature.ps1 -Json "{{args}}" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
+   - Only match branches/directories with the exact short-name pattern
+   - If no existing branches/directories found with this short-name, start with number 1
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.agents/.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints, pages/views, states, permissions, success metrics
+    3. Before writing FRs, lock the delivery posture:
+       - Determine whether the request is `prototype`, `spike`, `integration`, or `production`
+       - If the user mentions a predefined OSS stack, existing platform, dashboard system, metrics stack, webhook target, or real external environment, default to `integration` unless the user explicitly approves prototype downgrade
+       - If delivery posture is not clear, spend one of the allowed clarifications on this decision first
+    4. Run the requirement enrichment gate before drafting FRs:
+       - Build a three-column inventory: `Explicit`, `Inferred`, and `Decision Required`
+       - `Explicit`: preserve requirements directly stated by the user
+       - `Inferred`: add details that can be safely derived from domain norms, engineering best practices, official documentation, existing project constraints, or local code conventions
+       - `Decision Required`: mark choices that affect business scope, pricing, compliance, brand promise, real external dependencies, or the primary UX path
+       - For every P0/P1 candidate requirement, fill or block: actor, trigger, success result, failure result, boundary case, permission behavior, required data, observable oracle, evidence path, and release impact
+       - For UI-facing work, automatically add default, loading, empty, error, permission_denied, disabled, long_content, and mobile state requirements, or write why a state is not applicable
+       - For API/backend work, automatically add validation, error code, permission, idempotency or side-effect/no-side-effect, lifecycle/state-machine, audit, and observability requirements when relevant
+       - For all production-like work, evaluate performance, security, privacy, accessibility, compatibility, availability, observability, data consistency, backup/recovery, deployment, and operations constraints; write "not applicable because ..." instead of leaving blanks
+       - Write the enrichment result to `specs/<feature>/requirements-enrichment.md`
+       - If any P0/P1 item lacks acceptance criteria, test data, oracle, evidence path, or executable verification, mark it `Needs Clarification` or `Blocked`; do not mark it `Ready`
+    5. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    6. Fill Overview, goals, non-goals, scope boundary, and delivery/integration boundary
+       Non-goals are mandatory; write explicit exclusions rather than leaving them implicit
+    7. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    8. Fill Testability & Acceptance Evidence
+       - For every P0/P1 `FR-*` and relevant `NFR-*`, define:
+         - observable result
+         - positive Given/When/Then example
+         - negative or edge example
+         - required test data
+         - evidence path
+         - `Ready` / `Needs Clarification` / `Blocked` / `Prototype Only`
+       - If a real integration depends on missing environment, endpoint, RBAC, dashboard, webhook, fixture, credential, or downstream system, create a `TBD-TEST-*` or linked `TBD-*` precondition instead of treating the requirement as testable
+       - If the work is `prototype` / `spike`, record demo evidence boundaries and do not imply that formal `FR-*` will close
+    9. Fill Pages, States & Permissions for UI-facing features
+       Required states: default, empty, loading, error, permission_denied, disabled, long_content, mobile
+       If a state is not applicable, write why
+    10. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+       If the current work is only `prototype` or `spike`, do not use demo-only deliverables to imply formal `FR-*` closure; put them in the optional `PROTO-*` / `SPIKE-*` section instead
+    11. Generate business rules, data dictionary, non-functional requirements, and external dependency preconditions when relevant
+    12. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    13. Identify Key Entities (if data involved)
+    14. Fill Risks, Assumptions & Open Questions
+    15. Map every P0/P1 requirement to interfaces:
+       - Each requirement must reference page/view IDs, UI states, fields, operations, APIs, and acceptance criteria
+       - Each page/view/modal/drawer must have a requirement source
+       - If a requirement has no interface/API/test mapping, mark it as a gap or BLOCKED
+    16. Identify upfront difficulties:
+       - Research-heavy implementation, UI, data, integration, performance, permission, or interaction issues
+       - For each high-risk difficulty, create a research item with alternatives and validation approach
+       - Do not defer core feasibility research to implementation
+    17. If integrations exist, enumerate the external systems, existing OSS stack, and any known `TBD-*` blocker placeholders that the plan must resolve before implementation
+    18. Map the spec to product and testing artifacts:
+       - `docs/product/prd-lite.md`
+       - `docs/product/page-inventory.md`
+       - `docs/product/state-matrix.yaml`
+       - `docs/product/acceptance-criteria.md`
+       - `docs/product/requirement-interface-matrix.md`
+       - `docs/product/difficulty-research.md`
+       - `specs/<feature>/requirements-enrichment.md`
+       - `specs/<feature>/acceptance-examples.md`
+       - `specs/<feature>/requirements-testability-review.md`
+       - `specs/<feature>/verify-matrix.md`
+       - `specs/<feature>/test-strategy.md`
+       - `specs/<feature>/test-manifest.json`
+    19. Return: SUCCESS (spec ready for clarification or planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order. The final written headings and prose must be in Simplified Chinese.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md`
+
+   b. **Run Validation Check**: Review the spec against each checklist item
+
+   c. **Required quality dimensions**:
+      - Goals and non-goals are explicit
+      - Scope boundary is clear
+      - User stories are independently testable
+      - Page inventory and state coverage are complete for UI-facing work
+      - Requirement-to-interface mapping covers every P0/P1 requirement
+      - Every interface element has a requirement source
+      - Delivery mode is explicit and matches the intended acceptance boundary
+      - Requirement enrichment has separated `Explicit`, `Inferred`, and `Decision Required` items
+      - Automatically inferred requirements are recorded as assumptions with validation methods and impact if false
+      - P0/P1 requirements are not marked `Ready` when acceptance criteria, test data, oracle, evidence path, or executable verification are missing
+      - Non-functional requirements cover performance, security/privacy, accessibility, compatibility, availability, observability, data consistency, deployment/operations, or state why a category is not applicable
+      - Features mentioning existing OSS/external systems do not silently downgrade to local mock behavior
+      - Prototype / spike deliverables are not masquerading as completed formal `FR-*`
+      - High-risk difficulties have research items before implementation
+      - Permission differences are represented
+      - Functional requirements are testable
+      - P0/P1 requirements have observable results, positive examples, negative or edge examples, required test data, and evidence paths
+      - Testability status is not `Ready` when required external evidence is missing
+      - Prototype / spike evidence does not close formal integration or production requirements
+      - Acceptance criteria are measurable
+      - Risks, assumptions, and open questions are documented
+
+   d. **Handle Validation Results**:
+      - **If all items pass**: Mark checklist complete and proceed
+      - **If items fail (excluding [NEEDS CLARIFICATION])**: Update spec and re-validate (max 3 iterations)
+      - **If [NEEDS CLARIFICATION] markers remain**: Present options to user with suggested answers
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+## General Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+
+## Next Steps
+
+- `/speckit.clarify` - Clarify specification requirements
+- `/speckit.plan` - Create a technical plan for the spec

package/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/speckit.tasks.md

@@ -0,0 +1,186 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 语言要求
+
+- 与用户的生成汇报、任务摘要、MVP 建议全部使用简体中文。
+- 实际写入仓库的 `tasks.md` 必须使用简体中文。
+- 即使模板原文是英文，实际落盘时也要把 Phase 标题、Goal、Independent Test、Checkpoint、说明文字改写成中文。
+- 保留不能随意翻译的机器敏感标记与技术标识，例如 `_Requirements: ..._`、`FR-001`、任务 ID、HTML `<!-- id: XX -->`、路径、命令。
+
+## Outline
+
+1. **Setup**: Run `.agents/.specify/scripts/powershell/check-prerequisites.ps1 -Json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Testing truth sources**: acceptance-examples.md, requirements-testability-review.md, verify-matrix.md, test-strategy.md, test-manifest.json when present
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map endpoints to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - If test-manifest.json or verify-matrix.md exists: Map requirement testability, test layers, test files, commands, blockers, gaps, and evidence paths into task fields
+   - If requirements-testability-review.md marks a requirement as `Blocked`, do not generate a task that closes that formal `FR-*`; generate blocker/evidence work first
+   - If the feature mentions predefined OSS stacks or real external systems: schedule environment/blocker/integration tasks before UI or BFF tasks
+   - If a story is `integration` / `production` and spans external systems, connectors, BFF/API, or UI, decompose it into acceptance-sized slices instead of one epic-style task
+   - Prefer 4-6 tasks for an integration-heavy story: blocker/evidence readiness, contract projection, real connector path, bridge/policy metadata, upper-layer aggregation or UI consumption, final integration transcript
+   - If one candidate task would simultaneously close blockers, implement real connectors, add BFF/API/UI, and write final evidence, split it before continuing
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+   - If a story still collapses into a single oversized task, regenerate it with finer acceptance boundaries before writing `tasks.md`
+
+4. **Generate tasks.md**: Use `.agents/.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - **📚 文档引用索引**: 列出 FEATURE_DIR 中实际存在的文档
+   - **🛠️ 技术栈速查**: 从 plan.md 提取技术栈到表格
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: Goal, Independent Test, implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict task format (see Task Format Rules below), including testing fields for behavior/integration work
+   - Dependencies section with ASCII dependency graph + User Story dependency table
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Stories intentionally kept as a single task (with explicit justification)
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the required format
+
+## Task Format Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**CRITICAL**: Default to one clear task boundary per round. Do not generate tasks that implicitly require the implementation agent to read the entire feature and finish everything in one pass.
+
+**CRITICAL**: For `integration` / `production` stories, do not collapse the whole story into one giant `T001`-style task. A task should usually correspond to one acceptance checkpoint and be small enough to split into 3-7 flat Plan mode substeps.
+
+**Testing is left-shifted**: Do not wait until `/speckit.implement` or `/speckit.verify` to invent test scope. Use `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, and `test-manifest.json` when they exist.
+
+**Tests are contextual, not optional by default**:
+- Documentation-only tasks may use documentation validation such as `git -c core.safecrlf=false diff --check`.
+- Behavior-changing tasks should include test file / command mapping or explicitly mark `TEST-GAP`.
+- Bugfix tasks must include a failing test, failure transcript, or reproducible failure evidence.
+- `integration` / `production` tasks must include evidence paths and at least one non-unit verification layer when applicable.
+
+### 集成型 Story 拆分规则
+
+- 如果一个故事同时涉及 `TBD-*` 阻塞、真实 connector、BFF/API 聚合、页面消费和最终证据，必须拆成多个任务，不要压成一个 epic 任务。
+- 推荐拆分顺序是：环境或 blocker 证据 -> contract projection / schema mapping -> real connector / read-write path -> bridge / policy / metadata / RBAC -> BFF/API/UI 消费 -> 联调 transcript / 失败态证据。
+- 如果一个任务同时承担 3 类以上职责，默认视为粒度过粗，应继续拆分。
+- 如果某个故事最终只保留 1 个任务，必须在任务说明或生成汇报里给出明确理由，例如“本轮只做 blocker note”或“当前切片仅包含单文件修复”。
+
+### Task Item Format (REQUIRED)
+
+Every task MUST strictly follow this structure:
+
+```markdown
+- [ ] **T00X [P?] [USn?] 任务描述** <!-- id: XX -->
+  - 📋 **规格参考**: document.md → Section
+  - _Requirements: FR-XXX, FR-YYY_
+  - ✅ **验收标准**: 可验证的完成条件
+  - 📁 **创建文件**: `path/to/file` (或 **修改文件**)
+  - 📝 **执行内容**:
+    - 具体步骤 1
+    - 具体步骤 2
+```
+
+**Format Components**:
+
+1. **Checkbox + Bold**: `- [ ] **T00X ...** <!-- id: XX -->`
+2. **Task ID**: Sequential (T001, T002, T003...) in execution order, **bold**
+3. **HTML Comment ID**: `<!-- id: XX -->` for task tracking (Phase×10 + seq)
+4. **[P] marker**: Include ONLY if parallelizable (different files, no dependencies)
+5. **[USn] label**: REQUIRED for user story phase tasks only (US1, US2, ...)
+6. **📋 规格参考**: Link to source document and section
+7. **_Requirements_**: Italic, list of FR/NFR codes from spec.md
+8. **✅ 验收标准**: Measurable acceptance criteria
+9. **📁 文件清单**: Files to create/modify (with full paths)
+10. **🧪 测试文件**: Required for behavior-changing tasks, or `TEST-GAP` with reason
+11. **🔴 RED 命令**: Required for bugfix/TDD tasks; recommended for behavior-changing tasks
+12. **🟢 GREEN 命令**: Command expected to pass after implementation
+13. **📌 受影响测试**: Affected tests or regression commands
+14. **📎 证据文件**: Evidence path for integration/production tasks
+15. **🧪 验证层**: unit / component / contract / integration / e2e / visual / downstream
+16. **🔍 自检命令**: Minimal executable task completion proof
+17. **📝 执行内容**: Detailed implementation steps or method list
+
+**Icons reference**:
+- 📋 = 规格参考 (spec reference)
+- 📁 = 文件清单 (file list)
+- 📝 = 执行内容/方法清单 (implementation details)
+- ✅ = 验收标准/一致性检查/验证场景 (acceptance criteria)
+
+**Examples**:
+
+- ✅ CORRECT:
+```markdown
+- [ ] **T005 [US1] 实现 AuthService 业务逻辑** <!-- id: 24 -->
+  - 📋 **规格参考**: spec.md → FR-001~FR-005
+  - _Requirements: FR-001, FR-002, FR-003_
+  - 📁 **创建文件**: `service/AuthService.java`
+  - 📝 **方法清单**:
+    - `register()`: BCrypt 加密、手机号去重
+    - `login()`: 密码校验、签发 JWT
+```
+
+- ✅ CORRECT:
+```markdown
+- [ ] **T012 [P] [US3] 创建 Flyway 迁移** <!-- id: 32 -->
+  - 📋 **规格参考**: data-model.md → Script
+  - _Requirements: FR-006_
+  - 📁 **创建文件**: `db/migration/V1__create_script.sql`
+  - ✅ **字段检查**: 14 个字段，含 type/difficulty
+```
+
+- ❌ WRONG: `- [ ] T001 Create project structure` (missing bold, missing HTML id, missing 📋/📁/✅)
+- ❌ WRONG: `- [ ] **T005 [US1] 描述**` (missing HTML comment id, missing sub-items)
+
+### Phase Structure
+
+Each Phase MUST have:
+- Phase title with `<!-- id: X0 -->` HTML comment
+- **Goal**: Brief description
+- **Independent Test**: How to verify independently
+- Tasks following the format above
+- **Checkpoint**: Completion criteria at phase end
+
+Phase ordering:
+- **Phase 1**: Setup (project initialization and infrastructure)
+- **Phase 2+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Structure → Data → Logic → Interface → Verification
+  - For `integration` / `production` stories, prefer: blocker/evidence → connector → logic/aggregation → interface → verification
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
+
+### Dependencies Section (REQUIRED)
+
+Must include:
+1. **ASCII dependency graph** showing Phase relationships
+2. **User Story dependency table** (Story | 依赖 | 所在 Phase)
+3. **并行机会** listing which Phases/tasks can run in parallel
+
+## Next Steps
+
+- `/speckit.analyze` - Run a project analysis for consistency
+- `/speckit.implement` - Start the implementation in phases
+- `/speckit.verify` - Run feature-level verification after implementation completes