@speclife/cli 0.5.0 → 0.6.1

package/templates/commands/setup.md

@@ -0,0 +1,292 @@
+# /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
+
+

package/templates/commands/ship.md

@@ -0,0 +1,154 @@
+---
+name: /speclife/ship
+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>`
+- **⚡ Required:** Invoke `/openspec-archive <change-id>` command
+  - Do NOT manually `mv` files—the command updates project.md and specs
+  - Wait for archive confirmation before proceeding
+- 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
+```

package/templates/commands/start.md

@@ -0,0 +1,145 @@
+---
+name: /speclife/start
+id: speclife-start
+category: SpecLife
+description: Create a new branch for a change, optionally in a worktree for parallel work.
+---
+# /speclife start
+
+Create a new branch for a change, optionally in a worktree for parallel work.
+
+## ⚡ Execution
+
+**When this command is invoked, IMMEDIATELY execute the workflow below.**
+
+- Do NOT skip steps or jump straight to implementation
+- If mid-conversation, treat the invocation as "start fresh with this workflow"
+- If required inputs are missing (description), prompt the user
+- If user says "based on context", derive the description from recent discussion
+- **STOP after scaffolding proposal—do NOT auto-invoke `/openspec-apply`**
+
+## Usage
+
+```
+/speclife start <description>               # Worktree (default)
+/speclife start <description> in a branch   # Branch-only
+/speclife start                             # Interactive
+```
+
+## Goal
+
+Set up a workspace for a new change with proper git branch.
+
+## Mode Detection
+
+Parse the input for workflow hints:
+
+| Phrase in input | Mode |
+|-----------------|------|
+| "in a branch", "branch only", "no worktree", "simple" | **Branch-only** |
+| "in a worktree", "with worktree", "parallel" | **Worktree** |
+| Neither | **Worktree** (default) |
+
+Strip workflow hints from the description before deriving change-id.
+
+## Steps
+
+### 1. Derive change-id
+
+Convert description to kebab-case:
+- "Add user authentication" → `add-user-auth`
+- Prefix with verb: add-, fix-, update-, remove-, refactor-
+- Keep it short (3-5 words max)
+
+### 2. Create branch/worktree
+
+**Branch-only mode:**
+```bash
+git checkout -b spec/<change-id>
+```
+- Works in current directory
+- One change at a time (switch branches to context-switch)
+
+**Worktree mode (default):**
+```bash
+speclife worktree create <change-id>
+```
+- Creates `worktrees/<change-id>/`
+- Creates branch `spec/<change-id>`
+- Parallel changes possible
+
+### 3. Scaffold proposal
+
+Invoke `/openspec-proposal` with the description (minus workflow hints)
+- Creates `openspec/changes/<change-id>/proposal.md`
+- Creates `openspec/changes/<change-id>/tasks.md`
+
+### 4. Report and STOP
+
+**Branch-only:**
+```
+✓ Derived change-id: add-oauth-login
+✓ Created branch spec/add-oauth-login
+✓ Scaffolded proposal at openspec/changes/add-oauth-login/
+
+Next: Review the proposal, then run `/openspec-apply` to implement.
+```
+
+**Worktree:**
+```
+✓ Derived change-id: add-oauth-login
+✓ Created worktree at worktrees/add-oauth-login/
+✓ Created branch spec/add-oauth-login
+✓ Scaffolded proposal at openspec/changes/add-oauth-login/
+
+Next: cd worktrees/add-oauth-login/ then run `/openspec-apply`.
+```
+
+**⛔ STOP HERE.** Do NOT proceed to implementation. Wait for user to:
+1. Review the proposal
+2. Invoke `/openspec-apply` or `/speclife implement`
+
+## Examples
+
+```
+User: /speclife start "Add OAuth login support"
+→ Creates worktree (default)
+
+User: /speclife start "Add OAuth login" in a branch
+→ Creates branch only, no worktree
+
+User: /speclife start "fix login bug" branch only
+→ Creates branch only
+
+User: /speclife start
+→ Prompts: "Describe your change" then "Worktree (default) or branch-only?"
+```
+
+## Tradeoffs
+
+| Aspect | Worktree | Branch-only |
+|--------|----------|-------------|
+| Parallel changes | ✓ Multiple worktrees | One at a time |
+| IDE support | May need reload | Seamless |
+| Setup complexity | More dirs | Simpler |
+| Context switching | cd to worktree | git checkout |
+
+## Naming Conventions
+
+- Use kebab-case for change-id
+- Prefix with action verb: `add-`, `fix-`, `update-`, `remove-`, `refactor-`
+- Keep it descriptive but concise
+- Examples:
+  - `add-user-auth`
+  - `fix-login-redirect`
+  - `update-api-docs`
+  - `remove-deprecated-endpoint`
+  - `refactor-database-layer`
+
+## Notes
+
+- Branch name is always `spec/<change-id>` regardless of mode
+- If branch exists, error and suggest using existing
+- Branch-only: uncommitted changes carry over (stash if needed)
+- Worktree: clean checkout from main
+- To switch modes later, use `/speclife convert`