@zhuan-ai/zhuanspec 1.3.0

package/dist/utils/shell-detection.js

@@ -0,0 +1,41 @@
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export function detectShell() {
+    // Try SHELL environment variable first (Unix-like systems)
+    const shellPath = process.env.SHELL;
+    if (shellPath) {
+        const shellName = shellPath.toLowerCase();
+        if (shellName.includes('zsh')) {
+            return { shell: 'zsh', detected: 'zsh' };
+        }
+        if (shellName.includes('bash')) {
+            return { shell: 'bash', detected: 'bash' };
+        }
+        if (shellName.includes('fish')) {
+            return { shell: 'fish', detected: 'fish' };
+        }
+        // Shell detected but not supported
+        // Extract shell name from path (e.g., /bin/tcsh -> tcsh)
+        const match = shellPath.match(/\/([^/]+)$/);
+        const detectedName = match ? match[1] : shellPath;
+        return { shell: undefined, detected: detectedName };
+    }
+    // Check for PowerShell on Windows
+    // PSModulePath is a reliable PowerShell-specific environment variable
+    if (process.env.PSModulePath || process.platform === 'win32') {
+        const comspec = process.env.COMSPEC?.toLowerCase();
+        // If PSModulePath exists, we're definitely in PowerShell
+        if (process.env.PSModulePath) {
+            return { shell: 'powershell', detected: 'powershell' };
+        }
+        // On Windows without PSModulePath, we might be in cmd.exe
+        if (comspec?.includes('cmd.exe')) {
+            return { shell: undefined, detected: 'cmd.exe' };
+        }
+    }
+    return { shell: undefined, detected: undefined };
+}
+//# sourceMappingURL=shell-detection.js.map

package/dist/utils/task-progress.d.ts

@@ -0,0 +1,8 @@
+export interface TaskProgress {
+    total: number;
+    completed: number;
+}
+export declare function countTasksFromContent(content: string): TaskProgress;
+export declare function getTaskProgressForChange(changesDir: string, changeName: string): Promise<TaskProgress>;
+export declare function formatTaskStatus(progress: TaskProgress): string;
+//# sourceMappingURL=task-progress.d.ts.map

package/dist/utils/task-progress.js

@@ -0,0 +1,36 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+export function countTasksFromContent(content) {
+    const lines = content.split('\n');
+    let total = 0;
+    let completed = 0;
+    for (const line of lines) {
+        if (line.match(TASK_PATTERN)) {
+            total++;
+            if (line.match(COMPLETED_TASK_PATTERN)) {
+                completed++;
+            }
+        }
+    }
+    return { total, completed };
+}
+export async function getTaskProgressForChange(changesDir, changeName) {
+    const tasksPath = path.join(changesDir, changeName, 'tasks.md');
+    try {
+        const content = await fs.readFile(tasksPath, 'utf-8');
+        return countTasksFromContent(content);
+    }
+    catch {
+        return { total: 0, completed: 0 };
+    }
+}
+export function formatTaskStatus(progress) {
+    if (progress.total === 0)
+        return 'No tasks';
+    if (progress.completed === progress.total)
+        return '✓ Complete';
+    return `${progress.completed}/${progress.total} tasks`;
+}
+//# sourceMappingURL=task-progress.js.map

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@zhuan-ai/zhuanspec",
+  "version": "1.3.0",
+  "description": "AI-native system for spec-driven development",
+  "keywords": [
+    "zhuanspec",
+    "specs",
+    "cli",
+    "ai",
+    "development"
+  ],
+  "homepage": "https://github.com/Fission-AI/OpenSpec",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fission-AI/OpenSpec"
+  },
+  "license": "MIT",
+  "author": "ZhuanSpec Contributors",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "zhuanspec": "./bin/zhuanspec.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "schemas",
+    "scripts/postinstall.js",
+    "!dist/**/*.test.js",
+    "!dist/**/__tests__",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.7",
+    "@types/node": "^24.2.0",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@inquirer/core": "^10.2.2",
+    "@inquirer/prompts": "^7.8.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "ora": "^8.2.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.0.17"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
+  }
+}

package/schemas/spec-driven/schema.yaml

@@ -0,0 +1,205 @@
+name: spec-driven
+version: 1
+description: 默认 OpenSpec 工作流 - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: 概述变更的初始提案文档
+    template: proposal.md
+    instruction: |
+      **强制澄清检查点（必须首先执行）**：
+      
+      **重要原则：先查阅后询问，避免过度询问，使用选项式交互**
+      
+      在创建 proposal.md 之前，必须首先：
+      1. **查阅现有来源**：查阅现有规范（`zhuanspec/specs/`）、项目约定（`zhuanspec/project.md`）、代码库结构、上下文文件等，尝试从这些来源获取所需信息
+      2. **分析用户请求**：识别所有不确定或模糊的方面，但排除那些可以从现有来源确定的方面
+      
+      需要检查的方面（仅在无法从现有来源确定时询问）：
+      - 范围是否明确？（边界、包含/排除的内容）
+      - 技术选择是否明确？（框架、库、架构模式）
+      - 优先级是否明确？（如果有多需求）
+      - 验收标准是否明确？（如何判断完成）
+      - 上下文信息是否充分？（背景、约束、依赖）
+      - **实现细节是否明确**：代码改动位置、代码分层架构、实现方式、依赖关系等（仅在无法从代码库分析或现有规范中确定时询问）
+      
+      如果发现任何模糊之处，且无法从现有来源确定：
+      - **必须使用选项式交互**：调用编辑器的结构化问答工具（如 Cursor 的 `AskQuestion`），将每个澄清问题转化为带预设选项的选择题
+      - 每个问题提供 2-5 个预设选项，末尾包含"其他"选项
+      - 尽量将多个问题合并到一次交互中（一次性展示）
+      - 必须等待用户选择答案，不能继续
+      - 如果用户选择"其他"，再针对性追问细节
+      - **严禁**在不确定的情况下自行推测、假设或创建提案文件
+      - **严禁**要求用户手动输入大段文字来回答澄清问题
+      
+      **何时不需要询问**：
+      - 信息已明确：用户请求中已经明确说明
+      - 可从规范获取：可以从现有规范中获取
+      - 可从项目约定获取：可以从项目约定中获取
+      - 可从代码库分析获取：可以通过分析代码库结构、现有模式获取
+      - 可从上下文获取：可以从上下文文件、相关变更中获取
+      
+      只有在所有必要的模糊点都明确后，才能继续创建 proposal.md。
+
+      创建建立此变更原因的提案文档。
+
+      章节：
+      - **Why**：关于问题或机会的 1-2 句话。它解决了什么问题？为什么是现在？
+      - **What Changes**：变更的要点列表。具体说明新功能、修改或移除。用 **BREAKING** 标记破坏性更改。
+      - **Capabilities**：确定将创建或修改哪些规范：
+        - **New Capabilities**：列出正在引入的功能。每个都会成为新的 `specs/<name>/spec.md`。使用 kebab-case 名称（例如，`user-auth`、`data-export`）。
+        - **Modified Capabilities**：列出其 REQUIREMENTS 正在更改的现有功能。仅当规范级行为更改时（不仅仅是实现细节）才包含。每个都需要一个增量规范文件。检查 `openspec/specs/` 以获取现有规范名称。如果没有要求更改，则留空。
+      - **Skill Mapping**：运行 `zhuanspec skills list` 发现可用 skill，基于 skill description 进行语义匹配：
+        1. 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
+        2. 只有当实现区域的实际功能与 skill description 明确匹配时才关联
+        3. 简单的代码修改（如枚举值增删）应匹配通用编码规范 skill，而非架构级 skill
+        4. 避免仅因模块名称或文件路径中的关键词而错误匹配
+        5. 在表格中说明匹配理由，确保映射合理性
+        此映射将在 tasks.md 中用于 @skill 标注。如果没有匹配 skill 则留空。
+      - **Impact**：受影响的代码、API、依赖项或系统。
+
+      重要提示：Capabilities 部分至关重要。它在提案和规范阶段之间创建契约。在填写之前，请研究现有规范。
+      此处列出的每个功能都需要一个相应的规范文件。
+
+      保持简洁（1-2 页）。专注于"为什么"而不是"如何" -
+      实现细节属于 design.md。
+
+      这是基础 - 规范、设计和任务都建立在此基础上。
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: 变更的详细规范
+    template: spec.md
+    instruction: |
+      创建定义系统应该做什么的规范文件。
+
+      在 specs/<name>/spec.md 中为每个功能/特性区域创建一个规范文件。
+
+      增量操作（使用 ## 标题）：
+      - **ADDED Requirements**：新功能
+      - **MODIFIED Requirements**：更改的行为 - 必须包含完整的更新内容
+      - **REMOVED Requirements**：已弃用的功能 - 必须包含 **Reason** 和 **Migration**
+      - **RENAMED Requirements**：仅名称更改 - 使用 FROM:/TO: 格式
+
+      格式要求：
+      - 每个要求：`### Requirement: <name>` 后跟描述
+      - 对规范性要求使用 SHALL/MUST（避免使用 should/may）
+      - 每个场景：`#### Scenario: <name>` 使用 WHEN/THEN 格式
+      - **关键**：场景必须使用恰好 4 个井号（`####`）。使用 3 个井号或项目符号将静默失败。
+      - 每个要求必须至少有一个场景。
+
+      MODIFIED 要求工作流：
+      1. 在 openspec/specs/<capability>/spec.md 中找到现有要求
+      2. 复制整个要求块（从 `### Requirement:` 到所有场景）
+      3. 粘贴到 `## MODIFIED Requirements` 下并编辑以反映新行为
+      4. 确保标题文本完全匹配（忽略空白）
+
+      常见陷阱：使用部分内容的 MODIFIED 会在归档时丢失详细信息。
+      如果在不更改现有行为的情况下添加新关注点，请改用 ADDED。
+
+      示例：
+      ```
+      ## ADDED Requirements
+
+      ### Requirement: 用户可导出数据
+      系统 SHALL 允许用户以 CSV 格式导出其数据。
+
+      #### Scenario: 成功导出
+      - **WHEN** 用户点击"导出"按钮
+      - **THEN** 系统下载包含所有用户数据的 CSV 文件
+
+      ## REMOVED Requirements
+
+      ### Requirement: 旧版导出
+      **Reason**: 已被新的导出系统替代
+      **Migration**: 使用新的导出端点 /api/v2/export
+      ```
+
+      规范应该是可测试的 - 每个场景都是一个潜在的测试用例。
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: 包含实现细节的技术设计文档
+    template: design.md
+    instruction: |
+      创建解释如何实现变更的设计文档。
+
+      何时包含 design.md（仅在以下任何情况适用时创建）：
+      - 横切变更（多个服务/模块）或新的架构模式
+      - 新的外部依赖或重要的数据模型更改
+      - 安全性、性能或迁移复杂性
+      - 在编码之前从技术决策中受益的模糊性
+
+      章节：
+      - **Context**：背景、当前状态、约束、利益相关者
+      - **Goals / Non-Goals**：此设计实现的内容和明确排除的内容
+      - **Decisions**：关键的技术选择及其理由（为什么选择 X 而不是 Y？）。包括为每个决策考虑的替代方案。
+      - **Risks / Trade-offs**：已知的限制，可能出错的事情。格式：[Risk] → Mitigation
+      - **Migration Plan**：部署步骤、回滚策略（如果适用）
+      - **Open Questions**：待解决的决定或未知数
+
+      专注于架构和方法，而不是逐行实现。
+      参考提案了解动机，参考规范了解要求。
+
+      好的设计文档解释了技术决策背后的"原因"。
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: 从规范和设计派生的实施任务
+    template: tasks.md
+    instruction: |
+      创建分解实施工作的任务列表。
+
+      指导原则：
+      - 在 ## 编号标题下对相关任务进行分组
+      - 每个任务是一个复选框：- [ ] X.Y 任务描述
+      - 任务应该足够小，可以在一次会话中完成
+      - 按依赖关系排序任务（必须先做什么？）
+
+      技能标注（@skill 标签）：
+      - 在创建 tasks.md 之前，先运行 `zhuanspec skills list --json` 获取当前环境中可用的 skill 列表及其 description
+      - **匹配原则**：仔细阅读每个 skill 的 description，基于任务的具体功能内容进行语义匹配
+        - 精确匹配：任务功能应与 skill description 明确对应
+        - 避免过度匹配：简单的代码修改（如增删枚举值、修改常量）只需通用编码规范 skill
+        - 避免关键词匹配：不要仅因文件名或路径包含某些词就匹配相关 skill
+      - 格式：在任务描述末尾添加 `@skill:<real-skill-name>`
+      - 支持多个 skill：`@skill:skill-1,skill-2`
+      - 使用 skill 的真实名称（即 SKILL.md 中的 name 字段），而非类别名
+      - 如果任务不需要特定 skill 或没有匹配的 skill，可以省略标签
+      - 在 apply 阶段，AI 应根据 @skill 标签直接调用对应的 skill
+
+      示例（假设环境中安装了 java-db-schema-standards、java-dao-standards 等 skill）：
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Create database schema @skill:java-db-schema-standards
+      - [ ] 2.2 Implement DAO layer @skill:java-dao-standards,kf-backend-coding-standards
+      - [ ] 2.3 Implement RPC interface @skill:java-scf-rpc-usage-skill
+
+      ## 3. Testing
+
+      - [ ] 3.1 Write unit tests @skill:generate-mockito-unit-test-skill
+      ```
+
+      参考规范了解需要构建的内容，参考设计了解如何构建。
+      每个任务应该是可验证的 - 您知道何时完成。
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    阅读上下文文件，处理待处理的任务，在完成时标记为完成。
+    如果遇到阻碍或需要澄清，请暂停。

package/schemas/spec-driven/templates/design.md

@@ -0,0 +1,19 @@
+## Context
+
+<!-- 背景和当前状态 -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- 此设计旨在实现的目标 -->
+
+**Non-Goals:**
+<!-- 明确不在范围内的内容 -->
+
+## Decisions
+
+<!-- 关键设计决策和理由 -->
+
+## Risks / Trade-offs
+
+<!-- 已知风险和权衡 -->

package/schemas/spec-driven/templates/proposal.md

@@ -0,0 +1,43 @@
+## Why
+
+<!-- 解释此变更的动机。它解决了什么问题？为什么是现在？ -->
+
+## What Changes
+
+<!-- 描述将要更改的内容。具体说明新功能、修改或移除。 -->
+
+## Capabilities
+
+### New Capabilities
+<!-- 正在引入的功能。将 <name> 替换为 kebab-case 标识符（例如，user-auth、data-export、api-rate-limiting）。每个都会创建 specs/<name>/spec.md -->
+- `<name>`: <此功能涵盖内容的简要描述>
+
+### Modified Capabilities
+<!-- 其 REQUIREMENTS 正在更改的现有功能（不仅仅是实现）。
+     仅当规范级行为更改时，才在此处列出。每个都需要一个增量规范文件。
+     使用 zhuanspec/specs/ 中的现有规范名称。如果没有要求更改，则留空。 -->
+- `<existing-name>`: <正在更改的要求>
+
+## Skill Mapping
+
+<!-- 重要：运行 `zhuanspec skills list` 查看可用 skill，基于 skill description 进行语义匹配。
+     匹配原则：
+     1. 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
+     2. 只有当实现区域的实际功能与 skill description 明确匹配时才关联
+     3. 比如简单的代码修改（如枚举值增删）应匹配通用编码规范 skill，而非架构级 skill
+     4. 避免仅因模块名称或文件路径中的关键词而错误匹配
+     
+     示例：
+     - 修改枚举值 → kf-backend-coding-standards（编码规范）
+     - 定义 RPC 接口 → java-scf-rpc-usage-skill（RPC 调用规范）
+     - 数据库建表 → java-db-schema-standards（数据库规范）
+     
+     此映射将用于 tasks.md 中的 @skill 标注。如果没有匹配 skill 则留空。 -->
+
+| 实现区域 | 实际功能 | 关联 Skill | 匹配理由 |
+|---------|---------|-----------|---------|
+| <!-- 模块/文件 --> | <!-- 具体功能 --> | <!-- skill 名称 --> | <!-- 为什么匹配 --> |
+
+## Impact
+
+<!-- 受影响的代码、API、依赖项、系统 -->

package/schemas/spec-driven/templates/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- 要求名称 -->
+<!-- 要求文本 -->
+
+#### Scenario: <!-- 场景名称 -->
+- **WHEN** <!-- 条件 -->
+- **THEN** <!-- 预期结果 -->

package/schemas/spec-driven/templates/tasks.md

@@ -0,0 +1,25 @@
+## 1. <!-- 任务组名称 -->
+
+<!-- 
+  @skill 标注指南：
+  1. 首先运行 `zhuanspec skills list --json` 获取可用 skill 列表及其 description
+  2. 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
+  3. 基于任务的具体功能内容，匹配最相关的 skill
+  4. 匹配原则：
+     - 精确匹配：任务功能应与 skill description 明确对应
+     - 避免过度匹配：简单的代码修改（如增删枚举值、修改常量）只需通用编码规范 skill
+     - 避免关键词匹配：不要仅因文件名或路径包含某些词就匹配相关 skill
+  
+  示例：
+  - [ ] 1.1 新增 AssBusinessDataEnum 枚举值 ASSEMBLY_MACHINE_FLAG → @skill:kf-backend-coding-standards
+  - [ ] 1.2 定义 SCF 接口 IAssQueryService → @skill:java-scf-rpc-usage-skill
+  - [ ] 1.3 创建数据库表 ass_order → @skill:java-db-schema-standards
+-->
+
+- [ ] 1.1 <!-- 任务描述 --> <!-- @skill:real-skill-name -->
+- [ ] 1.2 <!-- 任务描述 -->
+
+## 2. <!-- 任务组名称 -->
+
+- [ ] 2.1 <!-- 任务描述 -->
+- [ ] 2.2 <!-- 任务描述 -->

package/schemas/tdd/schema.yaml

@@ -0,0 +1,213 @@
+name: tdd
+version: 1
+description: Test-driven development workflow - tests → implementation → docs
+artifacts:
+  - id: spec
+    generates: spec.md
+    description: Feature specification defining requirements
+    template: spec.md
+    instruction: |
+      Create the feature specification that defines WHAT to build.
+
+      Sections:
+      - **Feature**: Name and high-level description of the feature's purpose and user value
+      - **Requirements**: List of specific requirements. Use SHALL/MUST for normative language.
+      - **Acceptance Criteria**: Testable criteria in WHEN/THEN format
+
+      Format requirements:
+      - Each requirement should be specific and testable
+      - Use `#### Scenario: <name>` with WHEN/THEN format for acceptance criteria
+      - Define edge cases and error scenarios explicitly
+      - Every requirement MUST have at least one scenario
+
+      Example:
+      ```
+      ## Feature: User Authentication
+
+      Users can securely log into the application.
+
+      ## Requirements
+
+      ### Requirement: Password validation
+      The system SHALL validate passwords meet minimum security requirements.
+
+      #### Scenario: Valid password accepted
+      - **WHEN** password has 8+ chars, uppercase, lowercase, and number
+      - **THEN** password is accepted
+
+      #### Scenario: Weak password rejected
+      - **WHEN** password is less than 8 characters
+      - **THEN** system displays "Password too short" error
+      ```
+
+      This spec drives test creation - each scenario becomes a test case.
+    requires: []
+
+  - id: tests
+    generates: "tests/*.test.ts"
+    description: Test files written before implementation
+    template: test.md
+    instruction: |
+      Write tests BEFORE implementation (TDD red phase).
+
+      File naming:
+      - Create test files as `tests/<feature>.test.ts`
+      - One test file per feature/capability
+      - Use descriptive names matching the spec
+
+      Test structure:
+      - Use Given/When/Then format matching spec scenarios
+      - Group related tests with `describe()` blocks
+      - Each scenario from spec becomes at least one `it()` test
+
+      Coverage requirements:
+      - Cover each requirement from the spec
+      - Include happy path (success cases)
+      - Include edge cases (boundary conditions)
+      - Include error scenarios (invalid input, failures)
+      - Tests should fail initially (no implementation yet)
+
+      Example:
+      ```typescript
+      describe('Password validation', () => {
+        it('accepts valid password with all requirements', () => {
+          // GIVEN a password meeting all requirements
+          const password = 'SecurePass1';
+          // WHEN validating
+          const result = validatePassword(password);
+          // THEN it should be accepted
+          expect(result.valid).toBe(true);
+        });
+
+        it('rejects password shorter than 8 characters', () => {
+          // GIVEN a short password
+          const password = 'Short1';
+          // WHEN validating
+          const result = validatePassword(password);
+          // THEN it should be rejected with message
+          expect(result.valid).toBe(false);
+          expect(result.error).toBe('Password too short');
+        });
+      });
+      ```
+
+      Follow the spec requirements exactly - tests verify the spec.
+    requires:
+      - spec
+
+  - id: implementation
+    generates: "src/*.ts"
+    description: Implementation code to pass the tests
+    template: implementation.md
+    instruction: |
+      Implement the feature to make tests pass (TDD green phase).
+
+      TDD workflow:
+      1. Run tests - confirm they fail (red)
+      2. Write minimal code to pass ONE test
+      3. Run tests - confirm that test passes (green)
+      4. Refactor if needed while keeping tests green
+      5. Repeat for next failing test
+
+      Implementation guidelines:
+      - Write minimal code to pass each test - no more, no less
+      - Run tests frequently to verify progress
+      - Keep functions small and focused
+      - Use clear, descriptive names
+
+      Code organization:
+      - Create source files in `src/<feature>.ts`
+      - Export public API clearly
+      - Keep implementation details private
+      - Add JSDoc comments for public functions
+
+      Example structure:
+      ```typescript
+      /**
+       * Validates a password meets security requirements.
+       * @param password - The password to validate
+       * @returns Validation result with valid flag and optional error
+       */
+      export function validatePassword(password: string): ValidationResult {
+        if (password.length < 8) {
+          return { valid: false, error: 'Password too short' };
+        }
+        // ... additional checks
+        return { valid: true };
+      }
+      ```
+
+      Don't over-engineer - implement only what tests require.
+    requires:
+      - tests
+
+  - id: docs
+    generates: "docs/*.md"
+    description: Documentation for the implemented feature
+    template: docs.md
+    instruction: |
+      Document the implemented feature.
+
+      Sections:
+      - **Overview**: What the feature does and why it exists (1-2 paragraphs)
+      - **Getting Started**: Quick start guide to use the feature immediately
+      - **Examples**: Code examples showing common use cases
+      - **Reference**: Detailed API documentation, configuration options
+
+      Guidelines:
+      - Write for the user, not the developer
+      - Start with the most common use case
+      - Include copy-pasteable code examples
+      - Document all configuration options with defaults
+      - Note any limitations, edge cases, or gotchas
+      - Link to related features or specs
+
+      Example structure:
+      ```markdown
+      ## Overview
+
+      Password validation ensures user passwords meet security requirements
+      before account creation or password changes.
+
+      ## Getting Started
+
+      Import and use the validation function:
+
+      ```typescript
+      import { validatePassword } from './password';
+
+      const result = validatePassword('MySecurePass1');
+      if (!result.valid) {
+        console.error(result.error);
+      }
+      ```
+
+      ## Examples
+
+      ### Basic validation
+      ...
+
+      ### Custom error handling
+      ...
+
+      ## Reference
+
+      ### validatePassword(password)
+
+      | Parameter | Type | Description |
+      |-----------|------|-------------|
+      | password | string | The password to validate |
+
+      **Returns**: `{ valid: boolean, error?: string }`
+      ```
+
+      Reference the spec for requirements, implementation for details.
+    requires:
+      - implementation
+
+apply:
+  requires: [tests]
+  tracks: null
+  instruction: |
+    Run tests to see failures. Implement minimal code to pass each test.
+    Refactor while keeping tests green.