## zsc

**zsc** (short for **zig slice code**) is a CLI for multi-IDE/AI Coding tools that initializes a unified AI Agents task structure in your project.

Language / 语言: **English** | [中文](README.md)

---

### Installation

You can install `zsc` with **pip** or **uv tool**:

```bash
# 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:

```bash
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:

```bash
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:

```bash
zsc -V
# or
zsc --version
```

---

### Upgrading with `zsc -U`

In any terminal, you can upgrade `zsc` with:

```bash
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 -U` will try `pip install -U zsc` once as a fallback; if that also fails, it prints copy-pastable manual commands so you can decide between `pip install -U zsc` and `uv 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.

