@speclife/cli 0.9.0 → 0.9.1

package/templates/commands/retrofit.md

@@ -2,307 +2,25 @@
 name: /speclife-retrofit
 id: speclife-retrofit
 category: SpecLife
-description: Formalize ad-hoc changes on main into a proper spec-tracked change for review.
+description: Formalize ad-hoc changes on main into a spec-tracked change for review.
 ---
-# /speclife retrofit
-
-Formalize ad-hoc changes made on main into a spec-tracked change with PR for review and release.
-
-## ⚡ Execution
-
-**When this command is invoked, IMMEDIATELY execute the workflow below.**
-
-- Do NOT skip steps or ask for confirmation before starting
-- If description is missing, prompt the user
-- If no changes detected on main, error and explain
-- Create spec, validate, branch, commit, archive, and create PR
-- **STOP after PR created—do NOT auto-invoke `/speclife land`**
-
-## Usage
-
-```
-/speclife retrofit "<description>"     # Formalize changes with spec
-/speclife retrofit                     # Interactive (prompt for description)
-```
-
-## Goal
-
-Convert ad-hoc changes on main into a proper spec-tracked workflow:
-1. Document the change with a spec (proposal + tasks)
-2. Move changes to a spec branch for review
-3. Archive the spec
-4. Create PR for approval before merging back
-
-This bridges quick ad-hoc work with the spec-driven process.
-
-## When to Use
-
-- Made changes on main without going through `/speclife start`
-- Want to properly document and review ad-hoc changes
-- Need to create a release-worthy PR from untracked work
-
-## Prerequisites
-
-Must be on `main` branch with one of:
-- Uncommitted changes (modified/staged files)
-- Recent commits not yet pushed
-
-```bash
-# Validation
-BRANCH=$(git branch --show-current)
-[[ "$BRANCH" != "main" ]] && error "Must be on main branch"
-
-# Check for changes
-UNCOMMITTED=$(git status --porcelain)
-UNPUSHED=$(git log origin/main..HEAD --oneline 2>/dev/null)
-
-[[ -z "$UNCOMMITTED" && -z "$UNPUSHED" ]] && error "No changes to retrofit"
-```
-
-## Core Steps
-
-### 1. Detect Changes
-
-```bash
-# Show what will be retrofitted
-echo "Changes to retrofit:"
-git status --short              # Uncommitted changes
-git log origin/main..HEAD --oneline  # Unpushed commits (if any)
-```
-
-### 2. Derive change-id
-
-Convert description to kebab-case:
-- "Update ship command to use two commits" → `update-ship-two-commits`
-- Prefix with verb: add-, fix-, update-, remove-, refactor-
-- Keep it short (3-5 words max)
-
-```bash
-CHANGE_ID=<derived-from-description>
-SPEC_DIR="openspec/changes/${CHANGE_ID}"
-```
-
-### 3. Create Spec
-
-Invoke `/openspec-proposal` with the description:
-- Creates `openspec/changes/<change-id>/proposal.md`
-- Creates `openspec/changes/<change-id>/tasks.md`
-- Tasks should reflect what was ALREADY DONE (mark completed)
-
-**Important:** The proposal documents what was implemented, not what needs to be done.
-
-### 4. Validate Spec
-
-```bash
-openspec validate <change-id>
-```
-
-Fix any validation errors before proceeding.
-
-### 5. Create Spec Branch
-
-```bash
-# Create and switch to spec branch (carries uncommitted changes)
-git checkout -b spec/<change-id>
-```
-
-Note: Uncommitted changes automatically move to the new branch.
-
-### 6. Commit Implementation + Spec
-
-Read proposal.md for commit message, then:
-
-```bash
-git add -A
-git commit -m "<type>: <description>"
-```
-
-This commit includes:
-- The ad-hoc implementation changes
-- The spec files (proposal.md, tasks.md)
-
-### 7. Archive Spec
-
-Run `/openspec-archive`:
-- Moves spec to `openspec/changes/archive/<date>-<change-id>/`
-- May require updating `project.md` (follow archive prompts)
-
-### 8. Commit Archive
-
-```bash
-git add -A
-git commit -m "chore: archive <change-id> spec"
-```
-
-### 9. Push and Create PR
-
-```bash
-git push -u origin spec/<change-id>
-gh pr create --fill --base main
-```
-
-### 10. Reset Main (Safety)
-
-After successful PR creation, main should be clean:
-
-```bash
-# Main is already clean because:
-# - Uncommitted changes moved to spec branch
-# - We're now on spec branch, not main
-```
-
-### 11. Report and STOP
-
-```
-✓ Detected changes in: <list of changed files>
-✓ Created spec at openspec/changes/<change-id>/
-✓ Validated spec
-✓ Created branch spec/<change-id>
-✓ Committed: "<type>: <description>"
-✓ Archived spec
-✓ Committed: "chore: archive <change-id> spec"
-✓ Pushed to origin/spec/<change-id>
-✓ Created PR #XX: <url>
-
-Your changes are now on spec/<change-id> (main is unchanged).
-
-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: Examples
-
-**Basic retrofit:**
-```
-User: /speclife retrofit "update ship command workflow"
-
-Agent:
-ℹ️ On main branch
-✓ Detected changes:
-   - openspec/commands/speclife/ship.md (modified)
-✓ Derived change-id: update-ship-workflow
-✓ Created spec at openspec/changes/update-ship-workflow/
-✓ Validated spec
-✓ Created branch spec/update-ship-workflow
-✓ Committed: "docs: update ship command workflow"
-✓ Archived spec
-✓ Committed: "chore: archive update-ship-workflow spec"
-✓ Pushed to origin/spec/update-ship-workflow
-✓ Created PR #47
-
-Next: After approval, run /speclife land
-```
-
-**With unpushed commits:**
-```
-User: /speclife retrofit "add retrofit command"
-
-Agent:
-ℹ️ On main branch
-✓ Detected changes:
-   - 2 unpushed commits
-   - openspec/commands/speclife/retrofit.md (new file)
-✓ Derived change-id: add-retrofit-command
-✓ Created spec at openspec/changes/add-retrofit-command/
-...
-```
-
-**Interactive:**
-```
-User: /speclife retrofit
-
-Agent:
-ℹ️ Detected uncommitted changes:
-   - src/api.ts (modified)
-   - src/utils.ts (modified)
-
-What do these changes do? (describe for the spec)
-
-User: Add rate limiting to API endpoints
-
-Agent:
-✓ Derived change-id: add-rate-limiting
-...
-```
-
-## Appendix: Error Handling
-
-**Not on main:**
-```
-❌ Must be on main branch to retrofit.
-   Current branch: feature/something
-   
-   Either:
-   1. Switch to main: git checkout main
-   2. Use /speclife ship for non-main branches
-```
-
-**No changes to retrofit:**
-```
-❌ No changes to retrofit.
-   
-   Working directory is clean and no unpushed commits.
-   
-   Make some changes first, then run /speclife retrofit
-```
-
-**Spec already exists:**
-```
-❌ Spec 'update-ship-workflow' already exists.
-   
-   Either:
-   1. Choose a different description
-   2. Remove existing: rm -rf openspec/changes/update-ship-workflow/
-   3. Use /speclife start "resume update-ship-workflow" to continue existing
-```
-
-**Validation failed:**
-```
-❌ Spec validation failed:
-   - proposal.md: Missing "What" section
-   
-Fix issues and retry.
-```
-
-## Appendix: Comparison with Other Commands
-
-| Command | Starting Point | Creates Spec? | Flow |
-|---------|---------------|---------------|------|
-| `/speclife start` | Clean main | Yes (before implementation) | Spec → Implement → Ship |
-| `/speclife retrofit` | Main with changes | Yes (after implementation) | Implement → Spec → Ship |
-| `/speclife ship` | Spec branch | No (uses existing) | Ship existing work |
-
-## Appendix: What Gets Committed
-
-**First commit** (implementation + spec):
-```
-<type>: <description>
-
-- Implementation changes (the ad-hoc work)
-- openspec/changes/<change-id>/proposal.md
-- openspec/changes/<change-id>/tasks.md
-```
-
-**Second commit** (archive):
-```
-chore: archive <change-id> spec
-
-- Move spec to archive/
-- Update project.md (if applicable)
-```
-
-## Notes
-
-- Retrofit is for MAIN branch only (ad-hoc changes)
-- For changes on feature branches, use `/speclife ship` instead
-- The spec documents what WAS done, not what NEEDS to be done
-- Tasks in tasks.md should be marked as completed
-- Main branch stays clean (changes move to spec branch)
-
+**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