Instruction:
# Repository Guidelines

## 项目结构与模块组织
- 仓库目前处于初始化阶段，建议约定目录：`src/` 放核心源码或脚本；`tests/` 放单元与集成用例；`scripts/` 放自动化脚本（格式化、发布等）；`docs/` 存放设计与决策记录；`assets/` 存放示例数据或静态资源；`tmp/`（如需）用于本地运行产物且应在 `.gitignore` 中排除。
- 在提交前确保新增模块自带简要 README 或注释，描述职责、入口文件与主要依赖，以便后续贡献者快速定位。

## 构建、测试与本地开发
- 推荐在根目录提供 `Makefile` 或 `justfile` 统一命令。建议约定：`make init` 安装依赖；`make lint` 运行静态检查；`make test` 运行全部测试；`make dev` 以默认配置启动本地开发（如适用）。若暂未创建这些脚本，请先补充后再提交功能代码。
- 运行任何生成产物（构建、压缩、代码生成）时，将输出定向到 `build/` 或 `dist/`，并确保可通过 `make clean` 清理。

## 代码风格与命名约定
- 统一使用 UTF-8 编码，行宽上限 100，换行使用 LF。缩进优先 2 空格；如语言/工具强制 4 空格，请在对应目录的配置文件中显式声明。
- 文件命名：目录与通用脚本使用 `kebab-case`，测试文件以 `.spec` 或 `.test` 结尾；类/类型用 PascalCase，变量与函数用 camelCase，常量使用 UPPER_SNAKE_CASE。
- 建议为主语言引入格式化与静态检查（如 Prettier、ESLint、ruff、gofmt 等），并将配置置于仓库内（如 `.editorconfig`、`.eslintrc.*`），避免依赖全局默认。

## 测试准则
- 为每个可测试模块提供最小单元测试与一条端到端或集成路径，目标覆盖率≥80%，并在 CI 中强制检查。
- 测试命名遵循 Given-When-Then 或行为导向描述；保持测试数据最小化且可重复。需要外部服务时，优先使用本地 mock/fixture。
- 新增或修改行为时同步更新回归用例，并在 PR 描述中列出已执行的测试命令（如 `make test`、`make lint`）。

## 提交与 Pull Request 准则
- 推荐使用 Conventional Commits（如 `feat: ...`、`fix: ...`、`chore: ...`），单次提交聚焦单一变更集，并在提交信息中注明动机或关联问题编号。
- PR 需包含：变更概要、动机/背景、测试结果、风险与回滚策略。涉及界面或输出的改动请附截图或示例日志。
- 在评审前确保分支可干净合并（rebase 优先），并避免提交构建产物或本地环境文件（如 `.env`、`node_modules/`）。

## 安全与配置
- 不要提交任何密钥、令牌或真实数据。使用 `.env.example` 提供占位，并在 README/脚本中说明所需变量。
- 如需访问外部服务，优先提供可在本地自托管或模拟的方案，并记录最小权限策略与旋转流程。


# AGENTS.md instructions for /Users/iriver/workspace/toolkit

<INSTRUCTIONS>
# Repository Guidelines

## 项目结构与模块组织
- 仓库目前处于初始化阶段，建议约定目录：`src/` 放核心源码或脚本；`tests/` 放单元与集成用例；`scripts/` 放自动化脚本（格式化、发布等）；`docs/` 存放设计与决策记录；`assets/` 存放示例数据或静态资源；`tmp/`（如需）用于本地运行产物且应在 `.gitignore` 中排除。
- 在提交前确保新增模块自带简要 README 或注释，描述职责、入口文件与主要依赖，以便后续贡献者快速定位。

## 构建、测试与本地开发
- 推荐在根目录提供 `Makefile` 或 `justfile` 统一命令。建议约定：`make init` 安装依赖；`make lint` 运行静态检查；`make test` 运行全部测试；`make dev` 以默认配置启动本地开发（如适用）。若暂未创建这些脚本，请先补充后再提交功能代码。
- 运行任何生成产物（构建、压缩、代码生成）时，将输出定向到 `build/` 或 `dist/`，并确保可通过 `make clean` 清理。

## 代码风格与命名约定
- 统一使用 UTF-8 编码，行宽上限 100，换行使用 LF。缩进优先 2 空格；如语言/工具强制 4 空格，请在对应目录的配置文件中显式声明。
- 文件命名：目录与通用脚本使用 `kebab-case`，测试文件以 `.spec` 或 `.test` 结尾；类/类型用 PascalCase，变量与函数用 camelCase，常量使用 UPPER_SNAKE_CASE。
- 建议为主语言引入格式化与静态检查（如 Prettier、ESLint、ruff、gofmt 等），并将配置置于仓库内（如 `.editorconfig`、`.eslintrc.*`），避免依赖全局默认。

## 测试准则
- 为每个可测试模块提供最小单元测试与一条端到端或集成路径，目标覆盖率≥80%，并在 CI 中强制检查。
- 测试命名遵循 Given-When-Then 或行为导向描述；保持测试数据最小化且可重复。需要外部服务时，优先使用本地 mock/fixture。
- 新增或修改行为时同步更新回归用例，并在 PR 描述中列出已执行的测试命令（如 `make test`、`make lint`）。

## 提交与 Pull Request 准则
- 推荐使用 Conventional Commits（如 `feat: ...`、`fix: ...`、`chore: ...`），单次提交聚焦单一变更集，并在提交信息中注明动机或关联问题编号。
- PR 需包含：变更概要、动机/背景、测试结果、风险与回滚策略。涉及界面或输出的改动请附截图或示例日志。
- 在评审前确保分支可干净合并（rebase 优先），并避免提交构建产物或本地环境文件（如 `.env`、`node_modules/`）。

## 安全与配置
- 不要提交任何密钥、令牌或真实数据。使用 `.env.example` 提供占位，并在 README/脚本中说明所需变量。
- 如需访问外部服务，优先提供可在本地自托管或模拟的方案，并记录最小权限策略与旋转流程。

</INSTRUCTIONS>


<environment_context>
  <cwd>/Users/iriver/workspace/toolkit</cwd>
  <approval_policy>on-request</approval_policy>
  <sandbox_mode>workspace-write</sandbox_mode>
  <network_access>restricted</network_access>
  <shell>zsh</shell>
</environment_context>


## User Input

```text
这是一个工具集网站，提供各种工具给用户使用，页面要尽量精致优美，用户体验良好，项目同时包含管理后台和前端展示页面，要有统一的 ui 规范，前端代码要遵守规范，不要做太多无用的测试，技术用 react + typescript + tailwindcss + shadcn/ui + vite
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.

Follow this execution flow:

1. Load the existing constitution template at `.specify/memory/constitution.md`.
   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.

2. Collect/derive values for placeholders:
   - If user input (conversation) supplies a value, use it.
   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
     - MINOR: New principle/section added or materially expanded guidance.
     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
   - If version bump type ambiguous, propose reasoning before finalizing.

3. Draft the updated constitution content:
   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.

4. Consistency propagation checklist (convert prior checklist into active validations):
   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.

5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
   - Version change: old → new
   - List of modified principles (old title → new title if renamed)
   - Added sections
   - Removed sections
   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
   - Follow-up TODOs if any placeholders intentionally deferred.

6. Validation before final output:
   - No remaining unexplained bracket tokens.
   - Version line matches report.
   - Dates ISO format YYYY-MM-DD.
   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).

7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).

8. Output a final summary to the user with:
   - New version and bump rationale.
   - Any files flagged for manual follow-up.
   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).

Formatting & Style Requirements:

- Use Markdown headings exactly as in the template (do not demote/promote levels).
- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
- Keep a single blank line between sections.
- Avoid trailing whitespace.

If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.

If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.

Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.


Summary: auto


**Preparing to inspect files**


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
AGENTS.md


**Requesting file list**


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
.
..
.codex
.git
.specify
AGENTS.md


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
memory
scripts
templates


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->

## Core Principles

### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->

### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->

### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->

### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->

### [PRINCIPLE_5_NAME]
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->

## [SECTION_2_NAME]
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->

[SECTION_2_CONTENT]
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->

## [SECTION_3_NAME]
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->

[SECTION_3_CONTENT]
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->

## Governance
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->

[GOVERNANCE_RULES]
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->

**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->


**Identifying need for template specs**

I need to locate and review the specification or templates directory to gather instructions or plans related to templates. Next, I'll list and examine the contents in the .specify/templates folder.


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
agent-file-template.md
checklist-template.md
plan-template.md
spec-template.md
tasks-template.md


**Identifying missing command files**

The templates/commands directory needs command files, so next I'll create or locate the appropriate command implementations to populate this folder.


Output:
Exit code: 1
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
ls: .specify/templates/commands: No such file or directory


**Noticing no commands in templates**

The commands directory inside templates is empty, so no commands to process there; next I'll read task and checklist templates for relevant content.


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
# Implementation Plan: [FEATURE]

**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

## Summary

[Extract from feature spec: primary requirement + technical approach from research]

## Technical Context

<!--
  ACTION REQUIRED: Replace the content in this section with the technical details
  for the project. The structure here is presented in advisory capacity to guide
  the iteration process.
-->

**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
**Project Type**: [single/web/mobile - determines source structure]
**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

[Gates determined based on constitution file]

## Project Structure

### Documentation (this feature)

```text
specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

### Source Code (repository root)
<!--
  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
  for this feature. Delete unused options and expand the chosen structure with
  real paths (e.g., apps/admin, packages/something). The delivered plan must
  not include Option labels.
-->

```text
# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]

ios/ or android/
└── [platform-specific structure: feature modules, UI flows, platform tests]
```

**Structure Decision**: [Document the selected structure and reference the real
directories captured above]

## Complexity Tracking

> **Fill ONLY if Constitution Check has violations that must be justified**

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |


**Identifying need for additional templates**


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
# Feature Specification: [FEATURE NAME]

**Feature Branch**: `[###-feature-name]`
**Created**: [DATE]
**Status**: Draft
**Input**: User description: "$ARGUMENTS"

## User Scenarios & Testing *(mandatory)*

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
  you should still have a viable MVP (Minimum Viable Product) that delivers value.

  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
  Think of each story as a standalone slice of functionality that can be:
  - Developed independently
  - Tested independently
  - Deployed independently
  - Demonstrated to users independently
-->

### User Story 1 - [Brief Title] (Priority: P1)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value and why it has this priority level]

**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### User Story 2 - [Brief Title] (Priority: P2)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value and why it has this priority level]

**Independent Test**: [Describe how this can be tested independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### User Story 3 - [Brief Title] (Priority: P3)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value and why it has this priority level]

**Independent Test**: [Describe how this can be tested independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

[Add more user stories as needed, each with an assigned priority]

### Edge Cases

<!--
  ACTION REQUIRED: The content in this section represents placeholders.
  Fill them out with the right edge cases.
-->

- What happens when [boundary condition]?
- How does system handle [error scenario]?

## Requirements *(mandatory)*

<!--
  ACTION REQUIRED: The content in this section represents placeholders.
  Fill them out with the right functional requirements.
-->

### Functional Requirements

- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
- **FR-005**: System MUST [behavior, e.g., "log all security events"]

*Example of marking unclear requirements:*

- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

### Key Entities *(include if feature involves data)*

- **[Entity 1]**: [What it represents, key attributes without implementation]
- **[Entity 2]**: [What it represents, relationships to other entities]

## Success Criteria *(mandatory)*

<!--
  ACTION REQUIRED: Define measurable success criteria.
  These must be technology-agnostic and measurable.
-->

### Measurable Outcomes

- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]


**Identifying missing tasks-template**


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
---

description: "Task list template for feature implementation"
---

# Tasks: [FEATURE NAME]

**Input**: Design documents from `/specs/[###-feature-name]/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

## Format: `[ID] [P?] [Story] Description`

- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions

## Path Conventions

- **Single project**: `src/`, `tests/` at repository root
- **Web app**: `backend/src/`, `frontend/src/`
- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
- Paths shown below assume single project - adjust based on plan.md structure

<!--
  ============================================================================
  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.

  The /speckit.tasks command MUST replace these with actual tasks based on:
  - User stories from spec.md (with their priorities P1, P2, P3...)
  - Feature requirements from plan.md
  - Entities from data-model.md
  - Endpoints from contracts/

  Tasks MUST be organized by user story so each story can be:
  - Implemented independently
  - Tested independently
  - Delivered as an MVP increment

  DO NOT keep these sample tasks in the generated tasks.md file.
  ============================================================================
-->

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Project initialization and basic structure

- [ ] T001 Create project structure per implementation plan
- [ ] T002 Initialize [language] project with [framework] dependencies
- [ ] T003 [P] Configure linting and formatting tools

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented

**⚠ CRITICAL**: No user story work can begin until this phase is complete

Examples of foundational tasks (adjust based on your project):

- [ ] T004 Setup database schema and migrations framework
- [ ] T005 [P] Implement authentication/authorization framework
- [ ] T006 [P] Setup API routing and middleware structure
- [ ] T007 Create base models/entities that all stories depend on
- [ ] T008 Configure error handling and logging infrastructure
- [ ] T009 Setup environment configuration management

**Checkpoint**: Foundation ready - user story implementation can now begin in parallel

---

## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP

**Goal**: [Brief description of what this story delivers]

**Independent Test**: [How to verify this story works on its own]

### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py

### Implementation for User Story 1

- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
- [ ] T016 [US1] Add validation and error handling
- [ ] T017 [US1] Add logging for user story 1 operations

**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently

---

## Phase 4: User Story 2 - [Title] (Priority: P2)

**Goal**: [Brief description of what this story delivers]

**Independent Test**: [How to verify this story works on its own]

### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠

- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py

### Implementation for User Story 2

- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
- [ ] T021 [US2] Implement [Service] in src/services/[service].py
- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
- [ ] T023 [US2] Integrate with User Story 1 components (if needed)

**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently

---

## Phase 5: User Story 3 - [Title] (Priority: P3)

**Goal**: [Brief description of what this story delivers]

**Independent Test**: [How to verify this story works on its own]

### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠

- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py

### Implementation for User Story 3

- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
- [ ] T027 [US3] Implement [Service] in src/services/[service].py
- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py

**Checkpoint**: All user stories should now be independently functional

---

[Add more user story phases as needed, following the same pattern]

---

## Phase N: Polish & Cross-Cutting Concerns

**Purpose**: Improvements that affect multiple user stories

- [ ] TXXX [P] Documentation updates in docs/
- [ ] TXXX Code cleanup and refactoring
- [ ] TXXX Performance optimization across all stories
- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
- [ ] TXXX Security hardening
- [ ] TXXX Run quickstart.md validation

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies - can start immediately
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
- **User Stories (Phase 3+)**: All depend on Foundational phase completion
  - User stories can then proceed in parallel (if staffed)
  - Or sequentially in priority order (P1 → P2 → P3)
- **Polish (Final Phase)**: Depends on all desired user stories being complete

### User Story Dependencies

- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable

### Within Each User Story

- Tests (if included) MUST be written and FAIL before implementation
- Models before services
- Services before endpoints
- Core implementation before integration
- Story complete before moving to next priority

### Parallel Opportunities

- All Setup tasks marked [P] can run in parallel
- All Foundational tasks marked [P] can run in parallel (within Phase 2)
- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
- All tests for a user story marked [P] can run in parallel
- Models within a story marked [P] can run in parallel
- Different user stories can be worked on in parallel by different team members

---

## Parallel Example: User Story 1

```bash
# Launch all tests for User Story 1 together (if tests requested):
Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
Task: "Integration test for [user journey] in tests/integration/test_[name].py"

# Launch all models for User Story 1 together:
Task: "Create [Entity1] model in src/models/[entity1].py"
Task: "Create [Entity2] model in src/models/[entity2].py"
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 1: Setup
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
3. Complete Phase 3: User Story 1
4. **STOP and VALIDATE**: Test User Story 1 independently
5. Deploy/demo if ready

### Incremental Delivery

1. Complete Setup + Foundational → Foundation ready
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
3. Add User Story 2 → Test independently → Deploy/Demo
4. Add User Story 3 → Test independently → Deploy/Demo
5. Each story adds value without breaking previous stories

### Parallel Team Strategy

With multiple developers:

1. Team completes Setup + Foundational together
2. Once Foundational is done:
   - Developer A: User Story 1
   - Developer B: User Story 2
   - Developer C: User Story 3
3. Stories complete and integrate independently

---

## Notes

- [P] tasks = different files, no dependencies
- [Story] label maps task to specific user story for traceability
- Each user story should be independently completable and testable
- Verify tests fail before implementing
- Commit after each task or logical group
- Stop at any checkpoint to validate story independently
- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence


**Considering agent-file and checklist**


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
# [PROJECT NAME] Development Guidelines

Auto-generated from all feature plans. Last updated: [DATE]

## Active Technologies

[EXTRACTED FROM ALL PLAN.MD FILES]

## Project Structure

```text
[ACTUAL STRUCTURE FROM PLANS]
```

## Commands

[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]

## Code Style

[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]

## Recent Changes

[LAST 3 FEATURES AND WHAT THEY ADDED]

<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->


**Considering checklist template removal**


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
# [CHECKLIST TYPE] Checklist: [FEATURE NAME]

**Purpose**: [Brief description of what this checklist covers]
**Created**: [DATE]
**Feature**: [Link to spec.md or relevant documentation]

**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.

<!--
  ============================================================================
  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.

  The /speckit.checklist command MUST replace these with actual items based on:
  - User's specific checklist request
  - Feature requirements from spec.md
  - Technical context from plan.md
  - Implementation details from tasks.md

  DO NOT keep these sample items in the generated checklist file.
  ============================================================================
-->

## [Category 1]

- [ ] CHK001 First checklist item with clear action
- [ ] CHK002 Second checklist item
- [ ] CHK003 Third checklist item

## [Category 2]

- [ ] CHK004 Another category item
- [ ] CHK005 Item with specific criteria
- [ ] CHK006 Final item in this category

## Notes

- Check items off as completed: `[x]`
- Add comments or findings inline
- Link to relevant resources or documentation
- Items are numbered sequentially for easy reference


**Listing full project root**

I'm planning to list all root files and folders beyond AGENTS to find README or other context files that might clarify the project.


Output:
Exit code: 0
Wall time: 0.6 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
./.codex/version.json
./.codex/auth.json
./.codex/config.toml
./.codex/history.jsonl
./AGENTS.md
./.git/config
./.git/HEAD
./.git/description
./.git/FETCH_HEAD


**Drafting initial constitution details**

The repo appears new with no version or ratification date set, so I'll establish version 1.0.0 and use today's date for ratification and amendment, noting this as initial adoption. I'll define five principles aligned with the user's React/TypeScript/Tailwind/shadcn stack and minimal testing goals, and plan to update plan-template gating to reflect these principles.


Output:
Exit code: 0
Wall time: 0.5 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
2025-12-11


**Outlining constitution content and sync report**

I'm defining project principles with declarative, testable rules, organizing sections for technology, workflow, and governance, and drafting a Sync Impact Report comment marking initial version 1.0.0. Next, I'll finalize constitution text and update related templates to align test guidance and gating with these principles before applying patches.


Input:
*** Begin Patch
*** Update File: .specify/memory/constitution.md
@@
-# [PROJECT_NAME] Constitution
-<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
-
-## Core Principles
-
-### [PRINCIPLE_1_NAME]
-<!-- Example: I. Library-First -->
-[PRINCIPLE_1_DESCRIPTION]
-<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
-
-### [PRINCIPLE_2_NAME]
-<!-- Example: II. CLI Interface -->
-[PRINCIPLE_2_DESCRIPTION]
-<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
-
-### [PRINCIPLE_3_NAME]
-<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
-[PRINCIPLE_3_DESCRIPTION]
-<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
-
-### [PRINCIPLE_4_NAME]
-<!-- Example: IV. Integration Testing -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
-
-### [PRINCIPLE_5_NAME]
-<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
-[PRINCIPLE_5_DESCRIPTION]
-<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
-
-## [SECTION_2_NAME]
-<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
-
-[SECTION_2_CONTENT]
-<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
-
-## [SECTION_3_NAME]
-<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
-
-[SECTION_3_CONTENT]
-<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
-
-## Governance
-<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
-
-[GOVERNANCE_RULES]
-<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
-
-**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+<!--
+Sync Impact Report
+- Version change: none → 1.0.0
+- Modified principles: Initial set (Delightful UX & Accessibility; Unified Design System & Visual Consistency; React + Type-Safe Stack Discipline; Lean Quality Gates; Build & Documentation Discipline)
+- Added sections: Technology & Structure Constraints; Workflow & Review
+- Removed sections: None
+- Templates requiring updates: ✅ .specify/templates/plan-template.md; ✅ .specify/templates/tasks-template.md
+- Follow-up TODOs: None
+-->
+
+# Toolkit Constitution
+
+## Core Principles
+
+### Delightful UX & Accessibility
+- Public tools and admin views must present a polished, responsive experience with keyboard navigation, focus states, and WCAG AA contrast; initial load for primary pages should stay within a fast-perceived threshold (<2s on broadband reference data).
+- Rationale: Trustworthy, smooth interactions keep users productive across the tool catalogue and admin controls.
+
+### Unified Design System & Visual Consistency
+- Ship a single Tailwind + shadcn/ui design system shared by the public site and admin; define tokens (colors, spacing, typography, radii) once and reuse components instead of ad-hoc styling.
+- Rationale: Consistency lowers maintenance cost and keeps both surfaces coherent and elegant.
+
+### React + Type-Safe Stack Discipline
+- Frontend and admin experiences MUST be built with React + TypeScript + Vite; enforce strict typing for API contracts and component props, and keep build tooling aligned (ESLint/Prettier configs checked in).
+- Rationale: A single, typed stack accelerates delivery and reduces regressions across the toolkit.
+
+### Lean Quality Gates
+- Run lint/format in CI and gate merges; add tests only where they protect critical flows (core tool execution paths, billing/roles, design-system regressions) instead of blanket coverage; favor integration or component interaction tests over redundant unit noise.
+- Rationale: Purposeful coverage keeps quality high without wasting time on low-value tests.
+
+### Build & Documentation Discipline
+- Provide Makefile targets (`make init|lint|test|dev|clean`) and keep build artifacts in `build/` or `dist/`; each new module or package includes a short README explaining scope, entry points, and dependencies; environment variables live in `.env.example`.
+- Rationale: Predictable commands and lightweight docs make onboarding and maintenance fast.
+
+## Technology & Structure Constraints
+- Repository layout follows: `src/` for core code, `tests/` for targeted coverage, `scripts/` for automation, `docs/` for design/decisions, `assets/` for static data, and `tmp/` (gitignored) for local outputs; publish build outputs only to `build/` or `dist/`.
+- Both public site and admin should share base styles, themes, and utilities rather than diverging stacks; avoid introducing alternative frameworks or CSS systems.
+- Keep configuration under version control (`.editorconfig`, ESLint/Prettier/Tailwind configs) with UTF-8, LF line endings, and 2-space indentation unless toolchain forces otherwise.
+- No secrets committed; provide `.env.example` with the minimal required variables and document usage in README or module docs.
+
+## Workflow & Review
+- Feature work starts with a spec and implementation plan referencing this constitution; plans must pass the Constitution Check before research/implementation.
+- Tasks are organized by user story and only include tests when requested in the spec or needed for critical flows; avoid filler tasks and redundant coverage.
+- Code review verifies adherence to the shared design system, stack discipline, lint/format gates, Makefile commands, and documentation expectations before merge.
+- Release or demo checkpoints must validate UX polish (visual consistency, accessibility behaviors) and stack conformity (React + TS + Vite, Tailwind/shadcn usage).
+
+## Governance
+- This constitution supersedes other practice docs for frontend/admin work in this repository; deviations require explicit, documented approval in the feature plan and PR.
+- Amendments require: proposed text, rationale, impact assessment, and alignment updates to templates; maintain semantic versioning (MAJOR for breaking/removals, MINOR for new principles/sections, PATCH for clarifications).
+- Compliance is reviewed at plan approval and in PR reviews; violations must be recorded in plan/task Complexity Tracking with justification and mitigation.
+- Constitution and templates are stored in-repo; runtime guidance belongs in README/docs linked from specs and plans to keep contributors aligned.
+
+**Version**: 1.0.0 | **Ratified**: 2025-12-11 | **Last Amended**: 2025-12-11
*** End Patch


Output: {"output":"Success. Updated the following files:\nM .specify/memory/constitution.md\n","metadata":{"exit_code":0,"duration_seconds":0.0}}


**Updating Constitution Check section**

I'm drafting a replacement for the Constitution Check section to clearly list key points about the UI design system, tech stack, quality gating, and build outputs, preparing to apply the patch carefully.


Input:
*** Begin Patch
*** Update File: .specify/templates/plan-template.md
@@
 ## Constitution Check

 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

-[Gates determined based on constitution file]
+- Shared UI: Public and admin experiences must use the same Tailwind + shadcn/ui design system; specify shared tokens/components to be reused.
+- Stack lock: Plan adheres to React + TypeScript + Vite with committed lint/format configs and Makefile targets (`make init|lint|test|dev|clean`).
+- Lean quality: Identify critical flows that require tests; avoid filler coverage while ensuring lint/format gate CI and accessibility expectations are met.
+- Build hygiene: Outputs constrained to `build/` or `dist/`, module/docs locations defined (README per module, docs/ for decisions), and environment keys captured in `.env.example`.
*** End Patch


Output: {"output":"Success. Updated the following files:\nM .specify/templates/plan-template.md\n","metadata":{"exit_code":0,"duration_seconds":0.0}}


**Updating tests section wording**

I'm refining the Tests section to clarify that tests are optional and should be included only if explicitly requested or needed to protect critical flows such as core tool execution, roles, and design system. I'll apply this wording update to the tasks-template.


Input:
*** Begin Patch
*** Update File: .specify/templates/tasks-template.md
@@

 **Input**: Design documents from `/specs/[###-feature-name]/`
 **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

-**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - include them only when the spec requests them or when needed to guard constitution-critical flows (core tool journeys, roles/billing, design-system stability).
*** End Patch


Output: {"output":"Success. Updated the following files:\nM .specify/templates/tasks-template.md\n","metadata":{"exit_code":0,"duration_seconds":0.0}}


**Verifying no placeholders remain**

I'm confirming that all placeholders in the constitution file have been replaced, ensuring completeness before proceeding.


Output:
Exit code: 0
Wall time: 0.6 seconds
Output:
/opt/homebrew/Library/Homebrew/cmd/shellenv.sh: line 18: /bin/ps: Operation not permitted
mkdir: /Users/iriver/.cache/oh-my-zsh: Operation not permitted
/Users/iriver/.oh-my-zsh/oh-my-zsh.sh:129: nice(5) failed: operation not permitted
<!--
Sync Impact Report
- Version change: none → 1.0.0
- Modified principles: Initial set (Delightful UX & Accessibility; Unified Design System & Visual Consistency; React + Type-Safe Stack Discipline; Lean Quality Gates; Build & Documentation Discipline)
- Added sections: Technology & Structure Constraints; Workflow & Review
- Removed sections: None
- Templates requiring updates: ✅ .specify/templates/plan-template.md; ✅ .specify/templates/tasks-template.md
- Follow-up TODOs: None
-->

# Toolkit Constitution

## Core Principles

### Delightful UX & Accessibility
- Public tools and admin views must present a polished, responsive experience with keyboard navigation, focus states, and WCAG AA contrast; initial load for primary pages should stay within a fast-perceived threshold (<2s on broadband reference data).
- Rationale: Trustworthy, smooth interactions keep users productive across the tool catalogue and admin controls.

### Unified Design System & Visual Consistency
- Ship a single Tailwind + shadcn/ui design system shared by the public site and admin; define tokens (colors, spacing, typography, radii) once and reuse components instead of ad-hoc styling.
- Rationale: Consistency lowers maintenance cost and keeps both surfaces coherent and elegant.

### React + Type-Safe Stack Discipline
- Frontend and admin experiences MUST be built with React + TypeScript + Vite; enforce strict typing for API contracts and component props, and keep build tooling aligned (ESLint/Prettier configs checked in).
- Rationale: A single, typed stack accelerates delivery and reduces regressions across the toolkit.

### Lean Quality Gates
- Run lint/format in CI and gate merges; add tests only where they protect critical flows (core tool execution paths, billing/roles, design-system regressions) instead of blanket coverage; favor integration or component interaction tests over redundant unit noise.
- Rationale: Purposeful coverage keeps quality high without wasting time on low-value tests.

### Build & Documentation Discipline
- Provide Makefile targets (`make init|lint|test|dev|clean`) and keep build artifacts in `build/` or `dist/`; each new module or package includes a short README explaining scope, entry points, and dependencies; environment variables live in `.env.example`.
- Rationale: Predictable commands and lightweight docs make onboarding and maintenance fast.

## Technology & Structure Constraints
- Repository layout follows: `src/` for core code, `tests/` for targeted coverage, `scripts/` for automation, `docs/` for design/decisions, `assets/` for static data, and `tmp/` (gitignored) for local outputs; publish build outputs only to `build/` or `dist/`.
- Both public site and admin should share base styles, themes, and utilities rather than diverging stacks; avoid introducing alternative frameworks or CSS systems.
- Keep configuration under version control (`.editorconfig`, ESLint/Prettier/Tailwind configs) with UTF-8, LF line endings, and 2-space indentation unless toolchain forces otherwise.
- No secrets committed; provide `.env.example` with the minimal required variables and document usage in README or module docs.

## Workflow & Review
- Feature work starts with a spec and implementation plan referencing this constitution; plans must pass the Constitution Check before research/implementation.
- Tasks are organized by user story and only include tests when requested in the spec or needed for critical flows; avoid filler tasks and redundant coverage.
- Code review verifies adherence to the shared design system, stack discipline, lint/format gates, Makefile commands, and documentation expectations before merge.
- Release or demo checkpoints must validate UX polish (visual consistency, accessibility behaviors) and stack conformity (React + TS + Vite, Tailwind/shadcn usage).

## Governance
- This constitution supersedes other practice docs for frontend/admin work in this repository; deviations require explicit, documented approval in the feature plan and PR.
- Amendments require: proposed text, rationale, impact assessment, and alignment updates to templates; maintain semantic versioning (MAJOR for breaking/removals, MINOR for new principles/sections, PATCH for clarifications).
- Compliance is reviewed at plan approval and in PR reviews; violations must be recorded in plan/task Complexity Tracking with justification and mitigation.
- Constitution and templates are stored in-repo; runtime guidance belongs in README/docs linked from specs and plans to keep contributors aligned.

**Version**: 1.0.0 | **Ratified**: 2025-12-11 | **Last Amended**: 2025-12-11


**Summarizing version bump and changes**

Version bump to 1.0.0 reflects the first major release with real content, including updates to constitution, plan-template, and tasks-template files. No tests were run as changes are documentation-focused; no follow-ups are planned. I'll provide a concise commit message and a structured summary outlining key changes and rationale.


Updated the constitution to v1.0.0 with a concrete governance baseline: defined UX/accessibility, shared design system, React+TS+Vite stack discipline, lean testing, and build/docs requirements, plus tech structure, workflow, and governance rules (`.specify/memory/constitution.md`). Synced templates so Constitution Check now enforces design-system, stack, lean-quality, and build hygiene gates (`.specify/templates/plan-template.md`) and task generation only adds tests when requested or critical (`.specify/templates/tasks-template.md`).

New version: 1.0.0 (initial ratification and amendment on 2025-12-11) because this is the first concrete constitution content.

Suggested commit message: `docs: establish constitution v1.0.0 and align planning templates`.


重新生成, 内容要用简体中文表示


Summary: auto


**Translating and updating constitution to Simplified Chinese**

I'm regenerating the constitution fully in Simplified Chinese with translated section names and principles, bumping version from 1.0.0 to 1.0.1, keeping ratification date unchanged, and updating the sync impact report comment accordingly while leaving templates in English as aligned previously.


Input:
*** Begin Patch
*** Update File: .specify/memory/constitution.md
@@
-<!--
-Sync Impact Report
-- Version change: none → 1.0.0
-- Modified principles: Initial set (Delightful UX & Accessibility; Unified Design System & Visual Consistency; React + Type-Safe Stack Discipline; Lean Quality Gates; Build & Documentation Discipline)
-- Added sections: Technology & Structure Constraints; Workflow & Review
-- Removed sections: None
-- Templates requiring updates: ✅ .specify/templates/plan-template.md; ✅ .specify/templates/tasks-template.md
-- Follow-up TODOs: None
--->
-
-# Toolkit Constitution
-
-## Core Principles
-
-### Delightful UX & Accessibility
-- Public tools and admin views must present a polished, responsive experience with keyboard navigation, focus states, and WCAG AA contrast; initial load for primary pages should stay within a fast-perceived threshold (<2s on broadband reference data).
-- Rationale: Trustworthy, smooth interactions keep users productive across the tool catalogue and admin controls.
-
-### Unified Design System & Visual Consistency
-- Ship a single Tailwind + shadcn/ui design system shared by the public site and admin; define tokens (colors, spacing, typography, radii) once and reuse components instead of ad-hoc styling.
-- Rationale: Consistency lowers maintenance cost and keeps both surfaces coherent and elegant.
-
-### React + Type-Safe Stack Discipline
-- Frontend and admin experiences MUST be built with React + TypeScript + Vite; enforce strict typing for API contracts and component props, and keep build tooling aligned (ESLint/Prettier configs checked in).
-- Rationale: A single, typed stack accelerates delivery and reduces regressions across the toolkit.
-
-### Lean Quality Gates
-- Run lint/format in CI and gate merges; add tests only where they protect critical flows (core tool execution paths, billing/roles, design-system regressions) instead of blanket coverage; favor integration or component interaction tests over redundant unit noise.
-- Rationale: Purposeful coverage keeps quality high without wasting time on low-value tests.
-
-### Build & Documentation Discipline
-- Provide Makefile targets (`make init|lint|test|dev|clean`) and keep build artifacts in `build/` or `dist/`; each new module or package includes a short README explaining scope, entry points, and dependencies; environment variables live in `.env.example`.
-- Rationale: Predictable commands and lightweight docs make onboarding and maintenance fast.
-
-## Technology & Structure Constraints
-- Repository layout follows: `src/` for core code, `tests/` for targeted coverage, `scripts/` for automation, `docs/` for design/decisions, `assets/` for static data, and `tmp/` (gitignored) for local outputs; publish build outputs only to `build/` or `dist/`.
-- Both public site and admin should share base styles, themes, and utilities rather than diverging stacks; avoid introducing alternative frameworks or CSS systems.
-- Keep configuration under version control (`.editorconfig`, ESLint/Prettier/Tailwind configs) with UTF-8, LF line endings, and 2-space indentation unless toolchain forces otherwise.
-- No secrets committed; provide `.env.example` with the minimal required variables and document usage in README or module docs.
-
-## Workflow & Review
-- Feature work starts with a spec and implementation plan referencing this constitution; plans must pass the Constitution Check before research/implementation.
-- Tasks are organized by user story and only include tests when requested in the spec or needed for critical flows; avoid filler tasks and redundant coverage.
-- Code review verifies adherence to the shared design system, stack discipline, lint/format gates, Makefile commands, and documentation expectations before merge.
-- Release or demo checkpoints must validate UX polish (visual consistency, accessibility behaviors) and stack conformity (React + TS + Vite, Tailwind/shadcn usage).
-
-## Governance
-- This constitution supersedes other practice docs for frontend/admin work in this repository; deviations require explicit, documented approval in the feature plan and PR.
-- Amendments require: proposed text, rationale, impact assessment, and alignment updates to templates; maintain semantic versioning (MAJOR for breaking/removals, MINOR for new principles/sections, PATCH for clarifications).
-- Compliance is reviewed at plan approval and in PR reviews; violations must be recorded in plan/task Complexity Tracking with justification and mitigation.
-- Constitution and templates are stored in-repo; runtime guidance belongs in README/docs linked from specs and plans to keep contributors aligned.
-
-**Version**: 1.0.0 | **Ratified**: 2025-12-11 | **Last Amended**: 2025-12-11
+<!--
+同步影响报告
+- 版本变更：1.0.0 → 1.0.1
+- 修改的原则：全量翻译（极致体验与可访问性；统一设计系统与视觉一致性；React + 类型安全栈纪律；精益质量闸门；构建与文档纪律）
+- 新增章节：无
+- 移除章节：无
+- 模板更新：✅ .specify/templates/plan-template.md; ✅ .specify/templates/tasks-template.md
+- 后续待办：无
+-->
+
+# Toolkit 宪章
+
+## 核心原则
+
+### 极致体验与可访问性
+- 公共工具和管理端都必须提供精致、响应迅速的体验，具备键盘可达性、焦点状态和 WCAG AA 对比度；主要页面首屏加载需控制在感知快速的范围（参考宽带环境 <2s）。
+- 理由：平滑可信的交互让用户在工具目录与管理控制中保持高效。
+
+### 统一设计系统与视觉一致性
+- 仅使用一套 Tailwind + shadcn/ui 设计系统，公域与管理端共享；统一定义色彩、间距、排版、圆角等设计令牌，复用组件而非临时样式。
+- 理由：一致性降低维护成本，保持两端优雅且同源。
+
+### React + 类型安全栈纪律
+- 前台与后台必须基于 React + TypeScript + Vite；严格类型覆盖 API 契约与组件 props，构建链路统一并提交 ESLint/Prettier 配置。
+- 理由：单一且类型安全的栈能加速交付并减少回归。
+
+### 精益质量闸门
+- 在 CI 中运行 lint/format 并作为合并闸门；仅为关键路径（核心工具调用、计费/角色、设计系统回归）添加测试，避免泛滥覆盖；优先集成或组件交互测试而非重复的碎片单测。
+- 理由：聚焦价值的覆盖保持质量，同时不浪费时间在低收益测试上。
+
+### 构建与文档纪律
+- 提供 Makefile 目标（`make init|lint|test|dev|clean`），构建产物仅落在 `build/` 或 `dist/`；新模块需附简短 README 说明职责、入口与依赖；环境变量放在 `.env.example`。
+- 理由：可预期的命令与轻量文档让上手与维护更高效。
+
+## 技术与结构约束
+- 仓库结构：`src/` 核心代码，`tests/` 定向测试，`scripts/` 自动化，`docs/` 设计与决策，`assets/` 静态/示例，`tmp/`（忽略）用于本地输出；构建产物只发布到 `build/` 或 `dist/`。
+- 公域与管理端共用基础样式、主题与工具函数，避免引入其他框架或 CSS 体系造成分裂。
+- 配置需入库（如 `.editorconfig`、ESLint/Prettier/Tailwind），使用 UTF-8、LF、2 空格缩进（若工具强制则显式声明）。
+- 禁止提交密钥；提供 `.env.example`，并在 README 或模块文档说明变量用途。
+
+## 流程与评审
+- 功能工作以规范和实施计划为起点，并引用本宪章；计划须通过 Constitution Check 后再进入调研/实现。
+- 任务按用户故事组织，只在规格要求或关键路径需要时加入测试；避免填充性任务与冗余覆盖。
+- 代码评审需核验设计系统复用、技术栈一致性、lint/format 闸门、Makefile 命令与文档要求。
+- 发布或演示前必须验证体验精致度（视觉一致性、可访问性行为）及栈合规性（React+TS+Vite，Tailwind/shadcn 使用）。
+
+## 治理
+- 本宪章优先于仓库内其他前端/管理端实践文档；偏离需在实施计划与 PR 中明示并获批准。
+- 修订需包含：拟议文本、动机、影响评估及模板同步；版本遵循语义化：MAJOR（破坏性变更/移除原则）、MINOR（新增原则或扩展章节）、PATCH（澄清或措辞优化）。
+- 在计划评审与 PR 评审中执行合规检查；若存在偏离，需在计划/任务的 Complexity Tracking 中记录原因与缓解。
+- 宪章与模板存于仓库；运行时指导应放在 README/文档，并在规格与计划中链接，确保贡献者一致。
+
+**Version**: 1.0.1 | **Ratified**: 2025-12-11 | **Last Amended**: 2025-12-11
*** End Patch


Output: {"output":"Success. Updated the following files:\nM .specify/memory/constitution.md\n","metadata":{"exit_code":0,"duration_seconds":0.0}}


**Summarizing final version bump**

The update involves a patch-level version bump to 1.0.1 due to translation changes in the constitution file only, with no other template or modification impact. I'll confirm no further follow-up is needed and provide a concise commit message in Chinese reflecting this.


已用简体中文重写宪章，保持原则和治理内容不变，同时将版本提升为 1.0.1 以标记语言更新。主要内容：精致可访问体验、统一 Tailwind + shadcn/ui 设计系统、React+TS+Vite 技术栈纪律、精益质量闸门、构建与文档规范；技术结构约束与流程/评审要求均以中文呈现并与现有模板保持一致。更新文件：`.specify/memory/constitution.md`（含同步影响报告）。

新版本：1.0.1（理由：文本翻译/澄清）。暂无待办。

建议提交信息：`docs: 更新宪章为中文版 v1.0.1`


## User Input

```text
/constitution 这是一个工具集网站，提供各种工具给用户使用，页面要尽量精致优美，用户体验良好，项目同时包含管理后台和前端展示页面，要有统一的 ui 规范，前端代码要遵守规范，不要做太多无用的测试，技术用 react + typescript + tailwindcss + shadcn/ui + vite
```

You **MUST** consider the user input before proceeding (if not empty).

## 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 `/constitution 这是一个工具集网站，提供各种工具给用户使用，页面要尽量精致优美，用户体验良好，项目同时包含管理后台和前端展示页面，要有统一的 ui 规范，前端代码要遵守规范，不要做太多无用的测试，技术用 react + typescript + tailwindcss + shadcn/ui + vite` 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 `.specify/scripts/bash/create-new-feature.sh --json "/constitution 这是一个工具集网站，提供各种工具给用户使用，页面要尽量精致优美，用户体验良好，项目同时包含管理后台和前端展示页面，要有统一的 ui 规范，前端代码要遵守规范，不要做太多无用的测试，技术用 react + typescript + tailwindcss + shadcn/ui + vite"` with the calculated number and short-name:
      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
      - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "/constitution 这是一个工具集网站，提供各种工具给用户使用，页面要尽量精致优美，用户体验良好，项目同时包含管理后台和前端展示页面，要有统一的 ui 规范，前端代码要遵守规范，不要做太多无用的测试，技术用 react + typescript + tailwindcss + shadcn/ui + vite" --json --number 5 --short-name "user-auth" "Add user authentication"`
      - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "/constitution 这是一个工具集网站，提供各种工具给用户使用，页面要尽量精致优美，用户体验良好，项目同时包含管理后台和前端展示页面，要有统一的 ui 规范，前端代码要遵守规范，不要做太多无用的测试，技术用 react + typescript + tailwindcss + shadcn/ui + vite" -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 `.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
    3. 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
    4. Fill User Scenarios & Testing section
       If no clear user flow: ERROR "Cannot determine user scenarios"
    5. Generate Functional Requirements
       Each requirement must be testable
       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
    6. 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
    7. Identify Key Entities (if data involved)
    8. Return: SUCCESS (spec ready for 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 and headings.

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` using the checklist template structure with these validation items:

      ```markdown
      # Specification Quality Checklist: [FEATURE NAME]

      **Purpose**: Validate specification completeness and quality before proceeding to planning
      **Created**: [DATE]
      **Feature**: [Link to spec.md]

      ## Content Quality

      - [ ] No implementation details (languages, frameworks, APIs)
      - [ ] Focused on user value and business needs
      - [ ] Written for non-technical stakeholders
      - [ ] All mandatory sections completed

      ## Requirement Completeness

      - [ ] No [NEEDS CLARIFICATION] markers remain
      - [ ] Requirements are testable and unambiguous
      - [ ] Success criteria are measurable
      - [ ] Success criteria are technology-agnostic (no implementation details)
      - [ ] All acceptance scenarios are defined
      - [ ] Edge cases are identified
      - [ ] Scope is clearly bounded
      - [ ] Dependencies and assumptions identified

      ## Feature Readiness

      - [ ] All functional requirements have clear acceptance criteria
      - [ ] User scenarios cover primary flows
      - [ ] Feature meets measurable outcomes defined in Success Criteria
      - [ ] No implementation details leak into specification

      ## Notes

      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
      ```

   b. **Run Validation Check**: Review the spec against each checklist item:
      - For each item, determine if it passes or fails
      - Document specific issues found (quote relevant spec sections)

   c. **Handle Validation Results**:

      - **If all items pass**: Mark checklist complete and proceed to step 6

      - **If items fail (excluding [NEEDS CLARIFICATION])**:
        1. List the failing items and specific issues
        2. Update the spec to address each issue
        3. Re-run validation until all items pass (max 3 iterations)
        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user

      - **If [NEEDS CLARIFICATION] markers remain**:
        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
        3. For each clarification needed (max 3), present options to user in this format:

           ```markdown
           ## Question [N]: [Topic]

           **Context**: [Quote relevant spec section]

           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]

           **Suggested Answers**:

           | Option | Answer | Implications |
           |--------|--------|--------------|
           | A      | [First suggested answer] | [What this means for the feature] |
           | B      | [Second suggested answer] | [What this means for the feature] |
           | C      | [Third suggested answer] | [What this means for the feature] |
           | Custom | Provide your own answer | [Explain how to provide custom input] |

           **Your choice**: _[Wait for user response]_
           ```

        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
           - Use consistent spacing with pipes aligned
           - Each cell should have spaces around content: `| Content |` not `|Content|`
           - Header separator must have at least 3 dashes: `|--------|`
           - Test that the table renders correctly in markdown preview
        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
        6. Present all questions together before waiting for responses
        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
        9. Re-run validation after all clarifications are resolved

   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status

7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).

**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.

## General Guidelines

## Quick 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. That will be a separate command.

### 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")

### For AI Generation

When creating this spec from a user prompt:

1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
2. **Document assumptions**: Record reasonable defaults in the Assumptions section
3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
   - Significantly impact feature scope or user experience
   - Have multiple reasonable interpretations with different implications
   - Lack any reasonable default
4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
6. **Common areas needing clarification** (only if no reasonable default exists):
   - Feature scope and boundaries (include/exclude specific use cases)
   - User types and permissions (if multiple conflicting interpretations possible)
   - Security/compliance requirements (when legally/financially significant)

**Examples of reasonable defaults** (don't ask about these):

- Data retention: Industry-standard practices for the domain
- Performance targets: Standard web/mobile app expectations unless specified
- Error handling: User-friendly messages with appropriate fallbacks
- Authentication method: Standard session-based or OAuth2 for web apps
- Integration patterns: RESTful APIs unless specified otherwise

### 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)
- "React components render efficiently" (framework-specific)
- "Redis cache hit rate above 80%" (technology-specific)