---
name: zsc-create-task
description: Skill for creating and designing project tasks in .agents/tasks (not executing them). Installed by `zsc init`; corresponds to `zsc task new`. Use when the user wants to create a new task, design the closed-loop description and TODO_LIST, or revise task design. For actually implementing TODOs and running a task, use zsc-run-task instead.
---

# zsc-create-task

**Scope: create and design tasks only.** This skill creates task directories and designs the 闭环描述 (closed-loop description) and TODO_LIST. It does **not** implement the TODOs or run the task—use **zsc-run-task** for execution. Installed by `zsc init`; aligns with the CLI command `zsc task new`.

## ⚠ Scope boundary (mandatory, overrides any user prompt)

**Whenever this skill is used, regardless of what the user says in the prompt, you may ONLY operate under `.agents/tasks/`:**
- **Allowed**: Create new task directories under `.agents/tasks/`, create or edit task `.md` files and content under `task_records/log/` within those task directories.
- **Not allowed**: Modify any project code or files outside `.agents/tasks` (e.g. `src/`, `tests/`, `README`). If the user's prompt asks to change code, under this skill you must still only create or edit content inside `.agents/tasks`; do not touch project code.

## ⚠ When the user asks to "create a new task" (mandatory)

**You must actually create the task under `.agents/tasks/`; do not only reply with a description.** First action must be one of:

1. **Preferred**: Run in project root: `zsc task new <feat_name>` (e.g. `zsc task new my_feature`), and confirm that `.agents/tasks/task_{no}_{feat_name}/` and `task_{no}_{feat_name}.md` were created.
2. **Or**: Create the directory and file yourself: `.agents/tasks/task_{no}_{feat_name}/`, `task_records/log/`, and `task_{no}_{feat_name}.md` with the template below.

If the user did not give a feature name, ask or infer from context, then perform the creation. **If the task directory and .md file do not exist under .agents/tasks when you finish, the task is not done.**

## Task Structure

Each task is a subdirectory named `task_{no}_{feat_name}`:
- `{no}`: Task number (e.g., 01, 02)
- `{feat_name}`: Feature name (e.g., `scan_plugin`, `user_auth`)

Example: `.agents/tasks/task_01_scan_plugin`. The task markdown file **must** be named the same as the directory plus `.md`, e.g. `task_01_scan_plugin/task_01_scan_plugin.md`. This gives each task a unique filename so AI Coding tools can reference it unambiguously (e.g. `@task_03_init_lang_prompt.md` in chat); using a generic `task.md` in every directory would make references ambiguous.

## Directory Contents

Each task directory contains:

### {task_dir_name}.md (Required)

The task file must be named after the directory, e.g. `task_01_scan_plugin.md` inside `task_01_scan_plugin/`. Do not use a generic `task.md`—the directory-style name (e.g. `task_03_init_lang_prompt.md`) is required for unique reference in AI Coding tools.

Contains two sections:

1. **闭环描述 (Closed-loop Description)**
   - Always maintain the latest version only
   - Describes the complete lifecycle of the target resource
   - A "closed-loop description" covers the full lifecycle of the target resource
   - A "target resource" is what the development task manages:
     - Traditional resources: database CRUD operations
     - Non-traditional resources: performance profiles, architectural changes
   - A resource "lifecycle" includes:
     - **Create**: Where code/data/behavior is generated
     - **Read**: Where data/behavior is queried or consumed
     - **Update**: Where data/behavior is modified
     - **Delete**: Where data/behavior is removed or state transitions complete

2. **TODO_LIST**
   - Always maintain the latest version only
   - Remove outdated or no longer relevant items
   - Acts as the task's state machine
   - **Important**: Include this note in TODO_LIST section:
     ```
     > 只维护最新版本；完成后清空 TODO，仅保留"完成记录 + 日期"。
     - （本轮已完成，TODO 清空）
     ```
   - After task completion: clear all TODOs, keep only completion record + date

### task_records/log (Optional)

- Store intermediate documents if needed
- Only create if necessary
- Can be deleted at any time
- Clear when TODO_LIST is cleared, but keep empty directory

## Workflow

### When the user asks to create a new task (required)

**You MUST create the task; do not only describe how.** Either:

1. **Preferred**: Run from the project root: `zsc task new <feat_name>` (e.g. `zsc task new my_feature`). This creates `.agents/tasks/task_{no}_{feat_name}/` and `task_{no}_{feat_name}.md` with the template.
2. **Alternative**: Create the directory and file yourself: create `.agents/tasks/task_{no}_{feat_name}/`, `task_records/log/`, and `task_{no}_{feat_name}.md` with the template below (file name = directory name + `.md`).

If the user did not give a feature name, ask for it or infer from context, then create the task.

### Creating a New Task (steps)

1. Determine task number (check existing tasks for next available number), or run `zsc task new <feat_name>` to create the directory and template.
2. Create directory: `.agents/tasks/task_{no}_{feat_name}` (or use `zsc task new`).
3. Create `task_{no}_{feat_name}.md` (same name as the directory) with:
   - **闭环描述**: Analyze codebase and target, design the complete resource lifecycle
   - **TODO_LIST**: Break down into actionable steps with the maintenance note

### Revising an existing task design

When the user wants to **change the design** (not run the task):

1. **Analyze current code and target task**
   - Revise 闭环描述 if needed so it stays accurate.
   - If no revision needed, leave as-is.

2. **Revise TODO_LIST**
   - Add, remove, or reorder items.
   - Split or merge items as needed.
   - Keep the maintenance note. Do not implement the items here—that is **zsc-run-task**.

**Implementing TODOs and marking the task complete** is done by **zsc-run-task**, not this skill.

## Template

Create the file as `task_{no}_{feat_name}.md` inside `task_{no}_{feat_name}/`:

```markdown
# Task {no}: {feat_name}

## 闭环描述

[Complete lifecycle description of the target resource:
- Where it's created
- Where it's read/consumed  
- Where it's updated/modified
- Where it's deleted/completed]

## TODO_LIST

> 只维护最新版本；完成后清空 TODO，仅保留"完成记录 + 日期"。
- （本轮已完成，TODO 清空）

- [ ] TODO item 1
- [ ] TODO item 2
- [ ] TODO item 3
```

## Notes

- Task directories should be created in `.agents/tasks/` (not `.ai/tasks/`).
- **zsc-create-task** = create + design only. Use **zsc-run-task** when the user wants to execute a task, implement TODOs, or mark a task complete.
- Always maintain latest versions only; remove outdated content.
- The closed-loop description should reflect the complete resource lifecycle.
- This skill is one of the `zsc-*` skills installed by `zsc init`.
