Metadata-Version: 2.4
Name: spectask-init
Version: 0.1.7
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# spectask-init

**[Spectask](https://github.com/noant/spectask)** is the upstream methodology and template repository. This repo publishes the **`spectask-init`** CLI (Python 3.10+): it bootstraps Spectask-style files into the **current working directory**—fetch a template (ZIP or Git), copy required paths and IDE-specific files, and optionally merge a `spec/extend` overlay.

The PyPI project and console command are **`spectask-init`**. Run it from the directory that should receive the files (the tool uses your shell’s current working directory).

## Use with uvx (recommended)

[`uvx`](https://docs.astral.sh/uv/guides/tools/) runs the tool from PyPI without a permanent install. Install [**uv**](https://docs.astral.sh/uv/getting-started/installation/) first (it includes `uvx`).

```bash
uvx spectask-init --help
uvx spectask-init --ide cursor
```

**Requirements:**

- Network access (PyPI and template download).
- After the package is published, the command resolves **`spectask-init`** from [PyPI](https://pypi.org/project/spectask-init/). Until then, install from this repo (see below).
- For **Git** URLs (template or extend) that are **not** `.zip` archives, `git` must be on your `PATH`.

## CLI options

| Option | Purpose |
|--------|---------|
| **`--ide`** | Which IDE(s) to install files for. Each value picks paths from the template’s `.metadata/skills-map.json`. You can pass **several** keys to merge lists (order preserved, duplicates dropped). **`auto`** uses `.metadata/ide-detection.json` and markers in the **current directory**: every IDE entry that matches is included (in file order), and their path lists are merged the same way as passing those keys explicitly (must be used alone). **`all`** installs the union of every IDE’s files (must be used alone). **Required** unless you pass **`--update`** (then it defaults to `auto`). |
| **`--template-url`** | Where to fetch the template from: **`.zip` URL** (download + extract) or **Git** URL (clone). Default is the official Spectask repo (`.git`). A **ZIP** avoids needing `git` for the template step. |
| **`--template-branch`** | Git branch for **`--template-url`** when it is **not** a ZIP (default: `main`). Ignored for ZIP URLs. |
| **`--extend`** | Optional second source (ZIP or Git) merged into **`spec/extend/`** after the main template. |
| **`--extend-branch`** | Git branch for **`--extend`** when it is **not** a ZIP (default: `main`). |
| **`--skip-example`** | Do not copy paths listed in the template’s example list (keeps the tree minimal). |
| **`--skip-navigation-file`** | Do not copy **`spec/navigation.md`**. For advanced workflows; a normal Spectask tree usually keeps this file. |
| **`--skip-hla-file`** | Do not copy **`spec/design/hla.md`**. For advanced workflows; a normal Spectask tree usually keeps this file. |
| **`--update`** | Shorthand for **`--skip-example`**, **`--skip-navigation-file`**, and **`--skip-hla-file`**. If you **omit** **`--ide`**, it behaves like **`--ide auto`** (detection from the template + your cwd). If you pass **`--ide`**, only the skip behavior is combined with your IDE choice. |

If **`spec/navigation.md`** or **`spec/design/hla.md`** already exists in the current directory, a normal run **refuses to overwrite** it and prints a hint to use **`--update`** or the matching **`--skip-navigation-file`** / **`--skip-hla-file`** flag.

With the **default** **`--template-url`**, **`--ide`** must be one of: **`cursor`**, **`claude-code`**, **`qwen-code`**, **`qoder`**, **`windsurf`**, **`auto`**, or **`all`**. With a **custom** template URL, any IDE name present in that template’s **`skills-map.json`** is allowed (and **`auto`** / **`all`** follow the same rules if the template supports them).

## Examples

**New project, explicit IDE (default template over Git):**

```bash
uvx spectask-init --ide cursor
```

**Detect IDE from the current folder** (template ships marker rules; your project should match one IDE, e.g. a `.cursor` directory for Cursor on the official template):

```bash
uvx spectask-init --ide auto
```

**Install files for every IDE defined in the template:**

```bash
uvx spectask-init --ide all
```

**Merge paths from two IDE keys** (e.g. Cursor + Claude Code):

```bash
uvx spectask-init --ide cursor claude-code
```

**Use a ZIP template** (no `git` for the template fetch):

```bash
uvx spectask-init --template-url https://github.com/noant/spectask/archive/refs/heads/main.zip --ide cursor
```

**Refresh an existing Spectask tree** (skip example tasks, navigation file, and HLA file; default IDE = `auto`):

```bash
uvx spectask-init --update
```

Same refresh but force a specific IDE:

```bash
uvx spectask-init --update --ide cursor
```

**Add the main template and an extend overlay** (extend can be Git or ZIP):

```bash
uvx spectask-init --ide cursor \
  --extend https://github.com/noant/spectask-my-extend.git --extend-branch main
```

## Install from source

```bash
git clone <this-repo-url>
cd spectask-cli
pip install .
spectask-init --ide cursor
# or: python -m spectask_init --ide cursor
```

## pip install (global / venv)

```bash
pip install spectask-init
spectask-init --ide cursor
```

## Installing uv (quick reference)

| Platform | Command |
|----------|---------|
| **Windows** (PowerShell) | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
| **macOS / Linux** | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |

More options: [uv installation](https://docs.astral.sh/uv/getting-started/installation/).

## Docs

- Architecture: [`spec/design/hla.md`](spec/design/hla.md)
- Spec methodology: [`spec/main.md`](spec/main.md)

## Maintainer: tests and publishing

From the repo root, with [uv](https://docs.astral.sh/uv/) on `PATH`.

**Tests** — install dev dependencies (includes pytest), then run the suite:

```bash
uv sync --extra dev
uv run pytest tests
```

Skip integration tests (no network or `git clone`; unit tests only):

```bash
uv run pytest tests -m "not integration"
```

**Publish to PyPI** — set a [PyPI API token](https://pypi.org/manage/account/) and run:

```bash
export spectask_publish_pypi_token=pypi-...   # or: python scripts/publish.py --token pypi-...
python scripts/publish.py
```

Do not commit tokens. See [uv publish](https://docs.astral.sh/uv/guides/publish/).
