@speclife/cli 0.8.0 → 0.9.1

package/templates/commands/release.md

@@ -2,118 +2,23 @@
 name: /speclife-release
 id: speclife-release
 category: SpecLife
-description: Create a release with version bump for manual releases (major versions).
+description: Create a release with version bump (typically for major versions).
 ---
-# /speclife release
-
-Create a release with version bump. Used for manual releases (typically major versions).
-
-## ⚡ Execution
-
-**When this command is invoked, IMMEDIATELY execute the workflow below.**
-
-- Check that we're on the main branch
-- Analyze commits to determine version bump (or use explicit flag)
-- Update version files and changelog
-- Commit and push to trigger release workflow
-
-## Usage
-
-```
-/speclife release              # Auto-detect version bump
-/speclife release --major      # Force major version bump
-/speclife release --minor      # Force minor version bump  
-/speclife release --patch      # Force patch version bump
-```
-
-## When to Use
-
-- **Major releases**: Breaking changes that require manual review
-- **Forced releases**: When auto-release is disabled or skipped
-- **Independent releases**: Creating a release without going through `/speclife land`
-
-## Preconditions
-
-- On `main` branch
-- Working directory clean
-- Changes merged since last release (for auto-detect)
-
-## Steps
-
-1. **Check branch**: Ensure on `main` branch
-   - If not, suggest switching or report error
-
-2. **Analyze commits**: Determine suggested version bump
-   - Get commits since last tag
-   - `feat:` commits → minor
-   - `fix:` commits → patch
-   - `BREAKING CHANGE` or `!` → major
-   - Use explicit flag if provided (--major, --minor, --patch)
-
-3. **Get current version**: Read from package.json (or equivalent)
-
-4. **Calculate new version**: Apply bump to current version
-   - Major: 1.2.3 → 2.0.0
-   - Minor: 1.2.3 → 1.3.0
-   - Patch: 1.2.3 → 1.2.4
-
-5. **Update version file**: Write new version to package.json
-
-6. **Update CHANGELOG**: Add release notes
-   - Group commits by type (Features, Fixes, etc.)
-   - Include commit messages and PR references
-
-7. **Commit**: `git commit -am "chore(release): vX.X.X"`
-   - This commit message triggers the release workflow
-
-8. **Push**: `git push origin main`
-
-9. **Create release PR** (optional, for review):
-   - If major release, create PR for review
-   - If patch/minor with auto-merge, push directly
-
-10. **Report**: Show next steps
-
-## Example
-
-```
-User: /speclife release --major
-
-Agent:
-Analyzing commits since v1.2.3...
-  - feat: add OAuth login (breaking: changes auth API)
-  - fix: correct redirect URL
-  - docs: update API documentation
-
-Current version: 1.2.3
-New version: 2.0.0 (major bump)
-
-✓ Updated package.json to 2.0.0
-✓ Updated CHANGELOG.md
-✓ Committed: "chore(release): v2.0.0"
-✓ Pushed to origin/main
-
-Release workflow triggered. GitHub Actions will:
-  1. Create tag v2.0.0
-  2. Create GitHub Release with notes
-  3. Publish to npm (if configured)
-
-Done! Release v2.0.0 is being created.
-```
-
-## Release Workflow
-
-When the `chore(release): vX.X.X` commit is pushed, the GitHub Actions workflow (`.github/workflows/speclife-release.yml`) automatically:
-
-1. Extracts version from commit message
-2. Creates git tag
-3. Creates GitHub Release with auto-generated notes
-4. Optionally publishes to package registry
-
-## Notes
-
-- For patch/minor releases, prefer using `/speclife land` which handles auto-release
-- Major releases should go through this command for explicit control
-- The release commit message format `chore(release): vX.X.X` is required for the workflow
-
-
+**Guardrails**
+- Execute immediately—must be on main with clean working directory
+- Use for major releases or when auto-release was skipped
+- For patch/minor, prefer `/speclife land` which handles auto-release
+
+**Steps**
+1. Check branch: must be on `main`; error otherwise.
+2. Analyze commits since last tag: `feat:` → minor, `fix:` → patch, `BREAKING CHANGE` or `!` → major; use explicit flag (--major/--minor/--patch) if provided.
+3. Calculate new version from current `package.json`.
+4. Update version: `npm version <bump> --no-git-tag-version` (and workspaces if monorepo).
+5. Update CHANGELOG.md with grouped commits.
+6. Commit: `git commit -am "chore(release): v<version>"`.
+7. Push: `git push origin main`.
+8. Report: version bumped, pushed, GitHub Actions will create tag and release.
+
+**Reference**
+- Commit message format `chore(release): vX.X.X` triggers release workflow
+- Major releases should use this command; patch/minor typically via `/speclife land`

package/templates/commands/retrofit.md

@@ -0,0 +1,26 @@
+---
+name: /speclife-retrofit
+id: speclife-retrofit
+category: SpecLife
+description: Formalize ad-hoc changes on main into a spec-tracked change for review.
+---
+**Guardrails**
+- Execute immediately—must be on `main` with uncommitted changes or unpushed commits
+- Generate spec from actual changes (retrospective), not speculation
+- STOP after PR created—do NOT auto-invoke `/speclife land`
+
+**Steps**
+1. Detect changes: `git status --short` and `git log origin/main..HEAD --oneline`; error if no changes.
+2. Analyze diffs to understand what was done; infer change type (feat, fix, refactor, docs).
+3. Derive change-id: kebab-case with verb prefix (add-, fix-, update-, remove-, refactor-).
+4. Review context: `openspec list --specs`, `cat openspec/project.md`.
+5. Create retrospective spec: `proposal.md` (past tense), `tasks.md` (all `[x]` completed), spec deltas if applicable.
+6. Validate and branch: `openspec validate <id>`, `git checkout -b spec/<id>`.
+7. Commit, archive, push, PR: commit changes, run `openspec archive <id> --yes`, commit archive, push, create PR with `gh pr create --title "<type>: <description>" --body "<body>"`.
+8. Report: change-id, spec created, PR URL. Next: `/speclife land` after approval.
+
+**Reference**
+- Proposal documents what was done (reality), not aspirations
+- Uncommitted changes move to the new branch automatically
+- PR title: use conventional commit format (`<type>: <meaningful description>`)
+- PR body: if `.github/pull_request_template.md` exists, read it and fill in each section based on the change context

package/templates/commands/setup.md

@@ -4,295 +4,23 @@ id: speclife-setup
 category: SpecLife
 description: Discover project configuration and populate openspec/speclife.md.
 ---
-# /speclife setup
-
-Discover project configuration and populate `openspec/speclife.md`.
-
-## ⚡ Execution
-
-**When this command is invoked, IMMEDIATELY execute the workflow below.**
-
-- Scan project files to detect build system and commands
-- Check for existing workflows and context files
-- Update `openspec/speclife.md` with discovered configuration
-- Offer to create publish workflow if missing (ask first)
-
-## Goal
-
-Auto-detect project commands (test, build, lint), publishing configuration, and context files to configure speclife for this project.
-
-## Steps
-
-1. **Read current config**: Check if `openspec/speclife.md` exists and what's already configured
-
-2. **Detect build system**: Look for project configuration files:
-   - `package.json` → Node.js (npm/yarn/pnpm)
-   - `Cargo.toml` → Rust (cargo)
-   - `go.mod` → Go
-   - `Makefile` → Make-based
-   - `pyproject.toml` or `setup.py` → Python
-   - `build.gradle` or `pom.xml` → Java
-
-3. **Extract commands**: From the detected build system, find:
-   - **Test command**: e.g., `npm test`, `cargo test`, `make test`
-   - **Build command**: e.g., `npm run build`, `cargo build`, `make build`
-   - **Lint command**: e.g., `npm run lint`, `cargo clippy`, `make lint`
-
-4. **Detect publish configuration**: Based on project type:
-
-   | Project Type | Detection | Registry | Secret Required |
-   |--------------|-----------|----------|-----------------|
-   | Node.js | `package.json` with `name` (not private) | npm | `NPM_TOKEN` |
-   | Node.js monorepo | `workspaces` in package.json | npm | `NPM_TOKEN` |
-   | Rust | `Cargo.toml` with `[package]` | crates.io | `CARGO_REGISTRY_TOKEN` |
-   | Python | `pyproject.toml` with `[project]` | PyPI | `PYPI_TOKEN` |
-   | Go | `go.mod` | N/A (no central registry) | None |
-   | Internal/private | `"private": true` in package.json | N/A | None |
-
-5. **Check for existing workflows**: Look in `.github/workflows/` for:
-   - `publish.yml` or similar publish workflow
-   - `release.yml` - release workflow
-
-6. **Identify context files**: Look for common documentation:
-   - `openspec/project.md` - project context
-   - `openspec/AGENTS.md` - agent guidelines
-   - `README.md` - project overview
-   - `CONTRIBUTING.md` - contribution guidelines
-
-7. **Update speclife.md**: Write discovered values to `openspec/speclife.md`
-
-8. **Offer to create publish workflow** (if missing):
-   - If no publish workflow exists AND project is publishable (not private, not Go):
-     - Ask: "No publish workflow found. Would you like me to create `.github/workflows/publish.yml`?"
-     - If user agrees, create the appropriate workflow from the templates below
-     - Remind user to add the required secret in repo settings
-   - If project is private (`"private": true`) or Go (no central registry):
-     - Skip this step (no publish workflow needed)
-
-9. **Report**: Tell the user what was configured and any next steps
-
-## Publish Workflow Templates
-
-Use these templates when creating publish workflows:
-
-### Node.js (single package)
-```yaml
-# .github/workflows/publish.yml
-name: Publish to npm
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm test
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-### Node.js (monorepo with workspaces)
-```yaml
-# .github/workflows/publish.yml
-name: Publish to npm
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm run build
-      - run: npm test
-      # Publish each workspace package
-      - run: npm publish -w packages/<package-name> --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-### Rust
-```yaml
-# .github/workflows/publish.yml
-name: Publish to crates.io
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - run: cargo test
-      - run: cargo publish
-        env:
-          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-```
-
-### Python
-```yaml
-# .github/workflows/publish.yml
-name: Publish to PyPI
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-      - run: pip install build twine
-      - run: python -m build
-      - run: twine upload dist/*
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
-```
-
-## Output
-
-Update `openspec/speclife.md` with discovered configuration:
-
-```markdown
-# SpecLife Configuration
-
-## Commands
-
-- **Test:** `<detected-test-command>`
-- **Build:** `<detected-build-command>`
-- **Lint:** `<detected-lint-command>`
-
-## Release Policy
-
-- **Auto-release:** patch and minor versions
-- **Manual release:** major versions (breaking changes)
-
-## Publish
-
-- **Registry:** npm / PyPI / crates.io / None
-- **Workflow:** .github/workflows/publish.yml (exists / TODO)
-- **Secret:** NPM_TOKEN / PYPI_TOKEN / CARGO_REGISTRY_TOKEN
-
-## Context Files
-
-When implementing changes, always read:
-- `openspec/project.md` - project context and conventions
-- `openspec/AGENTS.md` - agent guidelines
-- `README.md` - project overview
-```
-
-## Example Output
-
-### When publish workflow exists:
-```
-User: /speclife setup
-
-Agent:
-Detecting project configuration...
-
-✓ Project type: Node.js monorepo (npm workspaces)
-✓ Packages: @speclife/core, @speclife/cli, @speclife/mcp-server
-
-Commands detected:
-  ✓ Test: npm test
-  ✓ Build: npm run build
-  ✓ Lint: npm run lint
-
-Workflows:
-  ✓ Release: .github/workflows/release.yml
-  ✓ Publish: .github/workflows/publish.yml
-
-Context files:
-  ✓ openspec/project.md
-  ✓ openspec/AGENTS.md
-  ✓ README.md
-
-✓ Updated openspec/speclife.md
-```
-
-### When publish workflow is missing:
-```
-User: /speclife setup
-
-Agent:
-Detecting project configuration...
-
-✓ Project type: Node.js (single package)
-✓ Package: my-awesome-lib
-
-Commands detected:
-  ✓ Test: npm test
-  ✓ Build: npm run build
-  ✓ Lint: npm run lint
-
-Workflows:
-  ✓ Release: .github/workflows/release.yml
-  ⚠ Publish: Not found
-
-This package appears to be publishable to npm. Would you like me to create 
-`.github/workflows/publish.yml`?
-
-User: yes
-
-Agent:
-✓ Created .github/workflows/publish.yml
-
-⚠️ Remember to add NPM_TOKEN to your repository secrets:
-   GitHub → Settings → Secrets and variables → Actions → New repository secret
-   
-   Get your token from: https://www.npmjs.com/settings/~/tokens
-
-✓ Updated openspec/speclife.md
-
-Done! Your project is configured for automated releases and publishing.
-```
-
-### When project is private:
-```
-User: /speclife setup
-
-Agent:
-Detecting project configuration...
-
-✓ Project type: Node.js (private package)
-
-Commands detected:
-  ✓ Test: npm test
-  ✓ Build: npm run build
-
-Workflows:
-  ✓ Release: .github/workflows/release.yml
-  ℹ Publish: Not needed (private package)
-
-✓ Updated openspec/speclife.md
-```
-
-## Notes
-
-- If a command can't be detected, leave it as a TODO for the user
-- Don't overwrite user customizations if speclife.md already exists
-- This command is idempotent - safe to run multiple times
-- Always ask before creating publish workflow (don't auto-create)
-- Remind about secrets after creating publish workflow
-
-
+**Guardrails**
+- Execute immediately—scan project to auto-detect configuration
+- Don't overwrite existing user customizations in speclife.md
+- Ask before creating publish workflow (don't auto-create)
+
+**Steps**
+1. Read existing `openspec/speclife.md` if present.
+2. Detect build system: package.json (Node), Cargo.toml (Rust), go.mod (Go), pyproject.toml (Python), etc.
+3. Extract commands: test, build, lint from detected system (e.g., `npm test`, `cargo test`).
+4. Detect publish config: registry (npm/crates.io/PyPI), required secret, private flag.
+5. Check `.github/workflows/` for existing release/publish workflows.
+6. Identify context files: `openspec/project.md`, `openspec/AGENTS.md`, `README.md`.
+7. Update `openspec/speclife.md` with discovered values.
+8. If publishable and no publish workflow exists: ask user, create if agreed, remind about secrets.
+9. Report: project type, detected commands, workflow status, what was configured.
+
+**Reference**
+- Publish workflow templates: Node.js, Rust, Python (standard patterns)
+- Private packages (`"private": true`) skip publish workflow
+- Go has no central registry—skip publish step

package/templates/commands/ship.md

@@ -4,149 +4,20 @@ id: speclife-ship
 category: SpecLife
 description: Commit changes, push to remote, and create a PR for review.
 ---
-# /speclife ship
-
-Create a PR from your current branch. Works with spec branches and ad-hoc branches.
-
-## ⚡ Execution
-
-**When this command is invoked, IMMEDIATELY execute the workflow below.**
-
-- Do NOT skip steps or ask for confirmation before starting
-- Detect branch type first, then follow the appropriate flow
-- If there are uncommitted changes, proceed to stage and commit them
-- Create or update PR as the final step
-- **STOP after PR created—do NOT auto-invoke `/speclife land`**
-
-## TL;DR
-
-```
-/speclife ship           # Ship current branch
-/speclife ship --draft   # Create as draft PR
-```
-
-**Quick flow:**
-1. Detect branch type (spec vs ad-hoc)
-2. For spec branches: validate + archive spec
-3. Stage, commit, push
-4. Create/update PR
-
-## Mode Detection
-
-```bash
-BRANCH=$(git branch --show-current)
-```
-
-| Branch | Type | Behavior |
-|--------|------|----------|
-| `spec/*` | **Spec** | Full workflow with OpenSpec (validate, archive) |
-| Any other non-main | **Ad-hoc** | Simplified (skip spec steps) |
-| `main` | **Error** | Cannot ship from main |
-
-Note: Spec mode is determined by branch name prefix (`spec/`), not worktree existence. Works identically whether you're in a worktree or the main repo.
-
-## Core Steps
-
-### 1. Spec Branch Only
-If spec branch detected:
-- Run `openspec validate <change-id>`
-- Run `openspec archive <change-id>`
-- Read proposal.md for commit message
-
-### 2. Ad-hoc Branch Only
-- Infer commit type from branch name (`fix/*` → `fix:`, `feat/*` → `feat:`)
-- Ask user for commit message if needed
-
-### 3. All Branches
-```bash
-git add -A
-git commit -m "<type>: <description>"  # if uncommitted changes
-git push -u origin <branch>
-```
-
-### 4. Create PR
-```bash
-# Check if PR exists
-gh pr view --json url 2>/dev/null
-
-# If not, create
-gh pr create --fill --base main
-# Or: gh pr create --fill --base main --draft
-```
-
-### 5. Report and STOP
-```
-✓ Committed: "feat: description"
-✓ Pushed to origin/<branch>
-✓ Created PR #42: <url>
-
-Next: After approval, run /speclife land
-```
-
-**⛔ STOP HERE.** Do NOT proceed to merge. Wait for:
-1. PR review and approval
-2. User to invoke `/speclife land`
-
----
-
-<!-- REFERENCE SECTIONS - Read only when needed -->
-
-## Appendix: Commit Type Inference
-
-| Branch Pattern | Commit Type |
-|----------------|-------------|
-| `fix/*`, `bugfix/*`, `hotfix/*` | `fix:` |
-| `feat/*`, `feature/*` | `feat:` |
-| `docs/*` | `docs:` |
-| `refactor/*` | `refactor:` |
-| `chore/*` | `chore:` |
-| Other | Ask user |
-
-## Appendix: Error Handling
-
-**Cannot ship from main:**
-```
-❌ Cannot ship from main. Create a branch first.
-```
-
-**No changes:**
-```
-❌ No changes to ship. Working directory clean.
-```
-
-**Spec validation failed:**
-```
-❌ Spec validation failed:
-   - proposal.md: Missing "What" section
-Fix issues and retry, or use --skip-validation
-```
-
-**PR already exists:**
-```
-ℹ️ PR #43 already exists. Pushing updates...
-✓ Updated PR #43
-```
-
-## Appendix: Examples
-
-**Spec branch:**
-```
-User: /speclife ship
-
-Agent:
-ℹ️ Spec branch: spec/add-oauth-login
-✓ Validated spec
-✓ Archived to openspec/changes/archive/
-✓ Committed: "feat: add OAuth login"
-✓ Created PR #42
-```
-
-**Ad-hoc branch:**
-```
-User: /speclife ship
-
-Agent:
-ℹ️ Ad-hoc branch: fix/login-bug
-✓ Committed: "fix: resolve login redirect"
-✓ Created PR #43
-```
+**Guardrails**
+- Execute immediately—do not ask for confirmation
+- Detect branch type: `spec/*` = full OpenSpec workflow, other non-main = ad-hoc, `main` = error
+- STOP after PR created—do NOT auto-invoke `/speclife land`
+
+**Steps**
+1. For spec branches: run `openspec validate <id>`, commit changes, run `openspec archive <id> --yes`, commit archive.
+2. For ad-hoc branches: infer commit type from branch name (`fix/*` → `fix:`, `feat/*` → `feat:`), ask if ambiguous.
+3. Push branch: `git push -u origin <branch>`.
+4. Create/update PR: `gh pr create --title "<type>: <description>" --body "<body>" --base main` (add `--draft` if requested).
+5. Report: commits made, branch pushed, PR URL. Next: `/speclife land` after approval.
+
+**Reference**
+- Commit type inference: fix/bugfix/hotfix → `fix:`, feat/feature → `feat:`, docs → `docs:`, refactor → `refactor:`, chore → `chore:`
+- If PR exists, push updates it automatically
+- PR title: use conventional commit format (`<type>: <meaningful description>`)
+- PR body: if `.github/pull_request_template.md` exists, read it and fill in each section based on the change context