---
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

   - **Multiple project touchpoints (cross-cutting)**  
     When the target resource has **multiple places** in the project where it must be created, registered, or wired (e.g. source files + a registration/config entry + a packaging or manifest so the artifact is included in distribution), the 闭环描述 must explicitly list **all** such touchpoints. Otherwise the design is incomplete and implementers may miss one (e.g. the feature works in dev but fails when installed, or exists but is not discoverable). For each touchpoint, the 闭环描述 should state where and what must be done. When designing the TODO_LIST, include at least one concrete TODO (or a 闭环 clause) per touchpoint so the implementation phase does not skip any.

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

   - **TODO design guidelines (important)**:
     - Each TODO should be a **concrete, executable engineering action** that answers “who does what in which context”, and is typically small enough to be done in 1–2 hours.
     - Avoid putting **long-running observation/monitoring items** or overly abstract goals (e.g. “keep watching metric X”, “ensure long-term stability”) directly into TODO_LIST. Instead, prefer:
       - Creating a separate task dedicated to monitoring/stability, or
       - Recording such context in `task_records/log/`, design docs, or change logs, rather than leaving it as an open TODO forever.
     - Prefer a **bottom-up decomposition style**: write the “next concrete step” first, rather than a distant milestone. After one concrete step is done, add the next step as a new TODO.
     - When a TODO is too large or vague, **split it into multiple smaller, more specific TODOs** that replace the original entry, instead of keeping a vague “virtual TODO” that never closes.

### 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 清空）

- [ ] Survey the existing code and documentation most related to this task's target resource, and capture key findings under `task_records/log/`.
- [ ] Based on the current state, refine the “closed-loop” section above with concrete Create/Read/Update/Delete touch points in the codebase or docs.
- [ ] Break this task into 3–5 concrete engineering subtasks that can each be done in 1–2 hours, and replace these example TODOs with those actionable items.
```

## TODO design examples (anti-patterns vs better versions)

- **Anti-pattern (not recommended)**:
  - `- [ ] Keep watching whether production error rate looks abnormal`
  - Problem: this is a long-running, open-ended observation with no clear completion criteria.
- **Improved examples (recommended)**:
  - `- [ ] Add error-rate monitoring and alert thresholds for endpoints A/B/C, and document the linkage in README`
  - `- [ ] Run a X-minute load test in test_env, capture the error-rate curve, and record conclusions under task_records/log/`
  - Rationale: each TODO is a concrete action that can be completed; once done, the state naturally closes.

- **Anti-pattern (not recommended)**:
  - `- [ ] Ensure the system is stable in the long run`
- **Improved examples (recommended)**:
  - `- [ ] Add three regression tests covering key edge cases for the critical path, and wire them into CI`
  - `- [ ] Document heartbeat and restart policies for worker processes and update the operations runbook`
  - Rationale: instead of writing a grand goal into TODO_LIST, decompose it into specific engineering changes that move the system toward that goal.

## 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`.
- `zsc` stands for **zig slice code**.
