spectask-init 0.1.13

No project description provided

spectask-init

CLI tool (Python 3.10+) that bootstraps a Spectask layout into the current working directory — fetches a source (ZIP or Git), copies required paths and IDE-specific files, and optionally merges a spec/extend overlay.

Spectask is the upstream methodology and template repository: spec-driven workflow, directory conventions, and reference files that this tool installs.

Install uv first — it provides uvx (see Running tools).

Run spectask-init:

uvx spectask-init --help
uvx spectask-init --ide cursor

Update the tool on the next uvx run (pick up the latest PyPI release instead of a cached environment):

uvx spectask-init@latest --ide cursor

If resolution metadata for the package looks stale, refresh the cache for it:

uvx --refresh-package spectask-init spectask-init --ide cursor

Requirements:

• Network access (PyPI and template download).
• After the package is published, the command resolves spectask-init from PyPI. 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. With the default --template-url, the concrete IDE keys are cursor, claude-code, qwen-code, qoder, windsurf, and codex. 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. spec/navigation.yaml is updated as well: extend: entries from the extend source are merged with those from the main template so the registry lists every extend path and its description from both sides (paths already present after the main install keep their existing row, including the merged read: required wins if either side is required; otherwise an explicit optional is kept; otherwise the key is omitted).
--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	Skip spec/navigation.yaml from the template’s required list: no copy from the template and no merge of template registry rows into an existing file. 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 and --skip-hla-file only (it does not imply --skip-navigation-file). Add --skip-navigation-file explicitly if you want the older behavior of refreshing IDE-related files without copying the template spec/navigation.yaml. 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.

With a custom --template-url, any IDE name from 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):

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

uvx spectask-init --ide auto

Install files for every IDE defined in the template:

uvx spectask-init --ide all

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

uvx spectask-init --ide cursor claude-code

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

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

Refresh an existing Spectask tree ( --skip-example and --skip-hla-file via --update; spec/navigation.yaml is still copied when the tool would install it unless you add --skip-navigation-file; default IDE = auto):

uvx spectask-init --update

Same refresh but force a specific IDE:

uvx spectask-init --update --ide cursor

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

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

Install from source

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)

pip install spectask-init
spectask-init --ide cursor

Maintainer: tests and publishing

From the repo root, with uv on PATH.

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

uv sync --extra dev
uv run pytest tests

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

uv run pytest tests -m "not integration"

Publish to PyPI — set a PyPI API token and run:

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