Skip to content

setup-lifecycle.md

Latest commit

 

History

History
147 lines (97 loc) · 7.97 KB

setup-lifecycle.md

File metadata and controls

147 lines (97 loc) · 7.97 KB
Raw

CLI lifecycle

Use this guide only after installing the devspec CLI through uvx, uv tool, pipx, WinGet, or Homebrew. It covers CLI initialization, validation, upgrades, canonical-artifact synchronization, and profile changes. Manual copying has its own manual-copy lifecycle and does not require this CLI flow.

Lifecycle at a glance

CLI installation and maintenance flow

The terminal CLI is devspec. After initialization, the installed agent wrappers expose the devspec.* workflow commands. They are intentionally different interfaces.

Command map

Goal Use Notes
Install the CLI uvx, uv tool, pipx, WinGet, or Homebrew Choose one package-manager route below.
Check version devspec --version Confirms the installed CLI. devspec version prints the same output.
Initialize devspec init --target <path> --profile <profile> --repo-state <new|existing> Copies canonical artifacts and selected wrappers. --profile defaults to all.
Validate devspec doctor --target <path> --profile <profile> Read-only check of contracts, protocols, templates, and wrappers. Exits 1 on errors.
Compare installed framework files devspec diff --target <path> Read-only drift report. Exits 1 when files are missing, modified, stale, obsolete, or recorded under another profile.
Synchronize canonical artifacts devspec sync --target <path> --profile <profile> --dry-run Preview, then run without --dry-run; use --force only for reviewed framework-owned edits.
Run delivery work Agent command such as devspec.story or devspec.quickfix Use after initialization; see the workflow guide.

sync requires --profile. doctor and diff use the profile recorded in devspec/.install-manifest.json when you omit it, or all when there is no manifest.

devspec upgrade is not a CLI command; upgrade the package with its package manager, then use diff and sync to update the installed framework files.

1. Install devspec

Choose one supported CLI route:

Platform or preference Example
One-off, any OS uvx devspec --help
Persistent Python install uv tool install devspec or pipx install devspec
Windows package manager winget install --id SpecLabs.Devspec --exact
Homebrew tap brew install speclabs/tap/devspec

For a no-installer setup, use manual copy from main.

2. Initialize a repository

Use existing when source code already exists:

devspec init --target D:\Code\orders --profile all --repo-state existing
devspec doctor --target D:\Code\orders --profile all

Use new before the first foundation workflow in a blank repository:

devspec init --target D:\Code\orders --profile copilot --repo-state new
devspec doctor --target D:\Code\orders --profile copilot

all installs every supported wrapper. Use copilot, codex, claude, cursor, gemini, or antigravity when the repository uses only that agent host.

Commit the installed files, including devspec/.install-manifest.json. sync compares against that manifest to tell a stale packaged file from a local edit.

3. Validate the CLI installation

Run Doctor after CLI initialization, after an upgrade, and before reporting a CLI setup problem:

devspec doctor --target D:\Code\orders --profile all

Doctor checks that each canonical contract, XML protocol, and selected adapter wrapper exists and that wrappers point to their matching contract. It does not modify repository code.

4. Upgrade the CLI

Upgrade using the same installation method:

# uvx: use the latest package for the next command
uvx devspec@latest --help

# uv tool
uv tool upgrade devspec

# pipx
pipx upgrade devspec

# WinGet
winget upgrade --id SpecLabs.Devspec --exact

# Homebrew
brew update
brew upgrade devspec

After upgrading, synchronize and validate the target repository.

5. Compare and synchronize canonical framework files

Preview the exact upgrade first, then apply it:

devspec diff --target D:\Code\orders
devspec sync --target D:\Code\orders --profile all --dry-run
devspec sync --target D:\Code\orders --profile all
devspec doctor --target D:\Code\orders --profile all

sync adds missing files and replaces packaged files that have not been locally edited. It never overwrites a locally modified framework-owned file unless --force is supplied, never overwrites project-owned artifacts, and never deletes retained obsolete wrappers. It also updates work-item meta.md stage and next values that a renamed command left behind; doctor reports any that remain. When sync reports a conflict it writes nothing at all, so review every listed file before using --force, which replaces all of them.

6. Change or add a profile

The install manifest records one profile: the one used by the latest init or sync. To add an agent host, re-run init with a profile that covers every host the repository uses, which is usually all:

devspec init --target D:\Code\orders --profile all --repo-state existing
devspec doctor --target D:\Code\orders --profile all

Re-running init is safe: it skips unchanged files and never overwrites project-owned files. Do not add a host with its single profile. For example, init --profile codex in a Copilot repository adds AGENTS.md but records only codex, so diff then reports the Copilot wrappers as retained obsolete files and later sync --profile codex stops updating them.

Changing to a narrower profile does not delete wrappers from other agents. diff lists them as retained obsolete files. Remove them manually only after confirming no team member needs them.

7. Start using the workflow

For a new repository, start with devspec.projectcontext. For an existing repository, start with devspec.extract. Then follow the route in the workflow guide. Use devspec.quickfix only for one localized, low-risk change.

Upgrade from devspec 0.2.x

devspec 0.3.0 replaced the 0.2.x framework. Commands are now contracts in devspec/contracts/ that load shared devspec/protocols/, every wrapper was regenerated, the CLI reports its version with devspec --version (the 0.2.x devspec version still works as an alias), and the core profile no longer exists. A 0.2.x installation upgrades in place:

  1. Upgrade the CLI with its package manager, and confirm devspec --version reports 0.3.0 or later.

  2. From a clean Git working tree in the target repository, preview the upgrade:

    devspec diff --target .
devspec sync --target . --profile all --dry-run

    Use the profile the repository needs. A core installation has no direct equivalent: use all, or copilot if the repository does not rely on AGENTS.md. Untouched 0.2.x framework files are reported as stale and will be replaced, and work-item meta.md values left by the devspec.grooming to devspec.refine rename will be rewritten.

  3. Apply the upgrade and validate it:

    devspec sync --target . --profile all
devspec doctor --target . --profile all

  4. Review the retained obsolete files that sync lists; it never deletes them. They are framework files that 0.3.0 no longer ships, such as devspec/adapters/, GEMINI.md, .agents/rules/, .github/skills/exploration-recovery/, .github/prompts/README.md, and .github/prompts/PATTERNS.md. Delete them once nothing references them. Project records that 0.2.x tracked, such as devspec/foundation/*.md outside _template/ and your work items, stay in place and are not reported.

  5. Commit the result, including devspec/.install-manifest.json.

If sync reports a conflict, that file differs from what 0.2.x installed. devspec/glossary.md was project-owned in 0.2.x and is framework-owned now, so a customized glossary conflicts: copy your terms aside, resolve every other listed conflict the same way, run sync --force, and merge your terms back.