zsc 0.2.5

AI Agents-driven project task CLI for initializing .agents task structure and skills.

zsc

zsc is a CLI for multi-IDE/AI Coding tools that initializes a unified AI Agents task structure in your project.

Language / 语言: English | 中文

---

Installation

You can install zsc with pip or uv tool:

# pip (when uv is not installed or you prefer pip)
pip install -U zsc

# uv tool (recommended when uv is available)
uv tool install zsc
uv tool install zsc --upgrade

For local development from this repo, you can use an editable install:

uv pip install -e .[test]

The commands above are examples; adjust to your environment and uv version.

---

Features

• Initialize .agents task layout: Creates .agents/ and .agents/tasks/ as the single entry point for project-level task lifecycle and TODOs.
• Install zsc-* skills for multiple AI Coding tools: Each subcommand maps to a skill (for example, zsc-create-task ↔ zsc task new). zsc init installs these skills under .cursor/skills/, .codex/skills/, and .claudecode/skills/ so each tool can understand and maintain the task system.
• Idempotent behavior: Re-running commands does not destroy existing structure or overwrite user-customized skill files.

---

Usage

From your project root, run:

zsc init .

zsc init . will:

• Create .agents/ and .agents/tasks/ directories if they do not exist.
• Create the following AI tool skill directories if they do not exist:
  • .cursor/skills/
  • .codex/skills/
  • .claudecode/skills/
• Copy the zsc-* skills bundled in zsc into those directories, e.g.:
  • .cursor/skills/zsc-help/SKILL.md (usage overview; can be triggered as /zsc-help in an AI environment)
  • .cursor/skills/zsc-create-task/SKILL.md (corresponds to zsc task new)
  • .cursor/skills/zsc-task-list/SKILL.md (corresponds to zsc task list)
  • .cursor/skills/zsc-task-status/SKILL.md (corresponds to zsc task status)
  • And similarly-named paths under .codex/skills/ and .claudecode/skills/.
  • SKILL.md files are overwritten on each run so that re-running zsc init . (e.g. after changing --lang or .agents/zsc-lang) keeps all skills in the chosen language.

Running zsc init . again is safe: existing directories are kept; skill files are re-written from the current language template.

To see the installed zsc version:

zsc -V
# or
zsc --version

---

Upgrading with zsc -U

In any terminal, you can upgrade zsc with:

zsc -U

This attempts to upgrade zsc to the latest version:

• If uv is available and the project’s .venv is not broken, zsc -U prefers uv tool install zsc --upgrade (equivalent to running that command directly).
• If the Python interpreter inside .venv is a broken symlink (for example .venv/bin/python3 no longer exists), zsc -U skips the uv-based upgrade and falls back to pip install -U zsc, printing a hint that you may want to recreate the virtualenv (e.g. via uv venv).
• If uv is available but the upgrade fails (including errors like No virtual environment found; run \uv venv` to create an environment, or pass `--system` to install into a non-virtual environment), zsc -Uwill trypip install -U zsconce as a fallback; if that also fails, it prints copy-pastable manual commands so you can decide betweenpip install -U zscanduv tool install zsc --system`.
• The actual behavior is independent of your shell type (bash/zsh/fish, etc.), but depends on which zsc binary is on your PATH. If a given shell picks up a different zsc installed inside a virtualenv, then zsc -U in that shell will follow that environment.

---

Task commands

zsc provides a set of subcommands around .agents/tasks:

• zsc task list: list tasks under .agents/tasks and their basic status (open/completed).
• zsc task new <feat_name> [path]: create a new task_{no}_{feat_name} directory and task_{no}_{feat_name}.md template in the given project root (default: current directory).
• zsc task status: summarize counts of tasks and their states, as a project-level health indicator.

Together with zsc init ., you can first initialize the task system and then use zsc task commands to maintain and browse the lifecycle.

Note: zsc task new creates the directory and same-named .md template. In AI Coding tools, triggering the zsc-create-task skill (e.g. /zsc-create-task in Cursor) can run zsc task new <feat_name> or create the files from a template and then help you refine the “closed-loop description” and TODO_LIST. If you previously used the old skill name zsc-new-task, run zsc init . again to install zsc-create-task.

---

Skills (AI-side “CLI”)

Besides traditional terminal subcommands (such as zsc init . and zsc task list), zsc also installs a set of skills (named zsc-*) for various AI Coding tools. In an AI environment, these behave like a second command line, where the model executes actions in your local project on your behalf.

• Traditional CLI: you type commands in a terminal, such as:
  • zsc init .
  • zsc task list
• Skills (AI-side): you trigger skills from your IDE/AI tool, for example:
  • In Cursor, type /zsc-help, /zsc-create-task, /zsc-run-task, etc., and let the AI perform the corresponding operations.

Core skills (by installed skill name):

Skill	Role	Trigger example	Related CLI
zsc-help	Explain what zsc does, how CLI and skills map to each other, and provide quick-start examples.	/zsc-help	zsc --help, README
zsc-create-task	Create and design tasks (closed-loop description and TODO_LIST) under .agents/tasks; does not execute TODOs.	/zsc-create-task @task_xx.md	zsc task new
zsc-run-task	Execute and advance an existing task, modifying code/docs according to TODO_LIST and rewriting TODO_LIST when done.	/zsc-run-task @task_02_xxx.md	—
zsc-run-task-to-complete	In a safe environment, try to automatically run as many TODOs as possible in one go, rewriting TODO_LIST with the same completion rules.	/zsc-run-task-to-complete @task_06_...md	—
zsc-task-list	List tasks under .agents/tasks and their status from the AI side.	/zsc-task-list	zsc task list
zsc-task-status	Summarize project-level task health (open/completed/unknown counts).	/zsc-task-status	zsc task status
zsc-update-task	Update task design only (closed-loop description, TODO_LIST, etc.); does not run TODOs.	/zsc-update-task @task_03_xxx.md	—

Maintenance: when adding or removing zsc-* skills, keep this section in sync with what is actually installed under .cursor/skills/ and similar directories.

---

TODO design: actionable and closable

• Each TODO should be a concrete, executable engineering action that roughly answers “who does what in which context” and can typically be completed within 1–2 hours.
• Avoid long-running observation/monitoring items or overly abstract goals in TODO_LIST (for example, “keep watching error rate”, “ensure long-term stability”). Those are better expressed as separate tasks (e.g. dedicated monitoring/stability tasks) or recorded in task_records/log/, design docs, or ops docs, rather than left as open TODOs forever.
• Prefer a bottom-up decomposition style: write the next concrete step first; after completing one concrete step, add a new TODO for the next step. When a TODO is too large or vague, split it into multiple smaller, more specific TODOs that replace the original entry.