@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/brainstorm/references/workflows.md

@@ -0,0 +1,255 @@
+---
+name: brainstorm-workflows
+description: "Detailed 3-phase workflow for sp:brainstorm - Input, Ideation, Output with delegation pointers"
+---
+
+# Brainstorm 3-Phase Workflow
+
+Detailed guidance for the sp:brainstorm ideation workflow.
+
+## Phase 1: Input Processing
+
+**Goal:** Parse and validate input, extract context
+
+### Input Type Detection
+
+```
+IF input contains "/" or "\" AND ends with ".md":
+    → Treat as file path
+ELSE:
+    → Treat as issue description
+```
+
+### Reading Task Files
+
+When a file path is detected:
+
+1. **Resolve path** — Convert relative paths to absolute
+2. **Read content** — Use Read tool
+3. **Parse frontmatter** — Extract YAML fields:
+   - `status`: Current task status
+   - `wbs`: Work breakdown structure number
+   - `name`: Task identifier
+   - `description`: Brief summary
+4. **Extract sections** — Parse markdown body:
+   - Background context
+   - Requirements
+   - Existing solutions (if any)
+
+### Validation Checklist
+
+- [ ] Input is not empty
+- [ ] File exists (if path provided)
+- [ ] YAML frontmatter is valid
+- [ ] Required fields present
+- [ ] Content has meaningful length (>50 characters)
+
+### Clarification via AskUserQuestion
+
+**When to clarify:**
+- Input < 20 characters
+- Background section empty or missing key context
+- Requirements vague or incomplete
+- Technical terms undefined
+- Multiple valid interpretations
+
+**Example:**
+```yaml
+AskUserQuestion:
+  - question: "What type of authentication do you need?"
+    header: "Auth Type"
+    options:
+      - label: "JWT tokens"
+        description: "Stateless, good for APIs, requires careful key management"
+      - label: "Session-based"
+        description: "Server-managed, simpler, good for traditional web apps"
+      - label: "OAuth2/OIDC"
+        description: "Third-party login (Google, GitHub), more complex setup"
+    multiSelect: false
+```
+
+---
+
+## Phase 2: Ideation (Delegated)
+
+**Goal:** Generate 2-3 solution approaches with trade-offs
+
+### Research Delegation
+
+DO NOT implement research directly. Delegate to specialized skills:
+
+```
+1. Invoke sp:source-driven-development for verification
+   - Use for any external claims
+   - Follow source-first protocol
+
+2. Delegate research + synthesis inline by default
+   - Run in the current session; escalate to `spur agent run` only on a subprocess trigger
+   - Request confidence scoring
+```
+
+### Approach Generation
+
+**Structure:**
+```markdown
+### Approach 1: [Descriptive Name] ⭐ Recommended
+
+**Description:** 2-3 sentences explaining the approach
+
+**Trade-offs:**
+- **Pros:**
+  - Advantage 1
+  - Advantage 2
+- **Cons:**
+  - Disadvantage 1
+  - Disadvantage 2
+
+**Implementation Notes:**
+- Key technical considerations
+- Dependencies or prerequisites
+
+**Confidence:** HIGH/MEDIUM/LOW
+**Sources:** [Citations with dates]
+```
+
+### Source Citation Format
+
+```markdown
+**Sources:**
+- [Title](URL) | **Verified**: YYYY-MM-DD
+- [Title](URL) | **Verified**: YYYY-MM-DD
+```
+
+### Confidence Scoring
+
+| Level | Range | Criteria |
+|-------|-------|----------|
+| **HIGH** | >90% | Direct quote from official docs (2025+) |
+| **MEDIUM** | 70-90% | Synthesized from multiple sources |
+| **LOW** | <70% | Uncertain, flag for review |
+
+---
+
+## Phase 3: Structured Output
+
+**Goal:** Format and deliver results
+
+### Section Generation
+
+1. **Overview** (100-150 words)
+   - Context and problem summary
+   - Why this matters
+   - Current state
+
+2. **Approaches** (200-300 words each)
+   - 2-3 options with trade-offs
+   - Implementation considerations
+   - Confidence levels
+
+3. **Recommendations** (100-150 words)
+   - Recommended approach with reasoning
+   - Key factors in decision
+   - When to consider alternatives
+
+4. **Next Steps** (bulleted list)
+   - Potential task items
+   - Research needs
+   - Implementation prerequisites
+
+### Output Template
+
+```markdown
+# Brainstorm: [Topic]
+
+**Date:** YYYY-MM-DD
+
+## Overview
+
+[Context and problem summary]
+
+## Approaches
+
+### Approach 1: [Name] ⭐ Recommended
+
+**Description:** [2-3 sentences]
+
+**Trade-offs:**
+- **Pros:**
+  - [Advantage 1]
+- **Cons:**
+  - [Disadvantage 1]
+
+**Implementation Notes:**
+- [Technical considerations]
+
+**Confidence:** HIGH/MEDIUM/LOW
+**Sources:** [Citations]
+
+### Approach 2: [Name]
+
+[Same structure]
+
+## Recommendations
+
+[Recommended approach with reasoning]
+
+## Next Steps
+
+1. [Task item 1]
+2. [Task item 2]
+
+---
+
+**Generated by:** sp:brainstorm
+**Research delegation:** sp:source-driven-development, spur agent run
+```
+
+---
+
+## Task Creation Delegation
+
+When user confirms approach, delegate to sp:spur-dev:
+
+```
+// Pseudocode: Delegate breakdown to sp:spur-dev
+Skill(skill="sp:spur-dev", args="plan <recommended_approach>")
+
+// Receive structured JSON output, then create tasks via sp:spur-cli
+Bash: spur task batch-create --file decomposition.json   # bare JSON array (see sp:spur-cli)
+```
+
+### Task Extraction Criteria
+
+**Task-worthy:**
+- Concrete and executable
+- Clear completion condition
+- Can be assigned to someone
+- Estimated effort >30 minutes
+
+**Not task-worthy:**
+- "Consider performance implications" (too vague)
+- "Research options" (already done)
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Empty input | Prompt for issue description or file path |
+| File not found | Provide clear error with path |
+| Invalid YAML | Report parsing error |
+| Missing fields | List missing fields, ask if incomplete |
+| Research unavailable | Continue, note reduced confidence |
+| Save fails | Display output, suggest manual save |
+
+---
+
+## Graceful Degradation
+
+When tools unavailable:
+
+1. **Continue** with available tools
+2. **Note** reduced confidence
+3. **Suggest** manual fallback
+4. **Save** intermediate state

package/plugins/sp/skills/branch-workflow/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: branch-workflow
+description: "Branch lifecycle discipline: create, worktree, commit, self-review, merge, cleanup."
+disable-model-invocation: true
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - create-branch
+    - worktree
+    - merge-prep
+    - cleanup
+see_also:
+  - sp:spur-dev
+---
+
+# sp:branch-workflow — Branch Lifecycle & Worktrees
+
+The branch-lifecycle discipline: create → worktree (optional) → commit → self-review → merge → cleanup. This skill teaches the agent how to manage git branches cleanly alongside the Spur task lifecycle.
+
+## The branch lifecycle
+
+### 1. Create
+
+```bash
+git checkout -b feature/<slug>   # or fix/<slug>, refactor/<slug>
+```
+
+Branch naming: `feature/`, `fix/`, `refactor/`, `docs/`, `chore/` — match the conventional commit type. Slug is the task title, lowercased, hyphenated, ≤50 chars.
+
+### 2. Worktree (optional — parallel branches)
+
+A git worktree gives you an isolated working directory for a branch without stashing or switching:
+
+```bash
+git worktree add ../<project>-<branch> <branch>
+cd ../<project>-<branch>
+```
+
+**When to use worktrees:**
+- Two parallel features that you switch between frequently
+- Hotfix isolation — fix on `main` while feature work stays on its branch
+- Review-in-progress — keep the review branch available while starting new work
+
+**When NOT to use:**
+- Single-branch workflow (overhead isn't worth it)
+- Disk-space constrained environments (each worktree is a full checkout)
+- CI/CD environments (ephemeral checkouts already handle this)
+
+### 3. Commit
+
+Atomic, conventional commits. One concern per commit.
+
+```bash
+git add <files for one concern>
+git commit -m "feat(scope): summary"
+```
+
+### 4. Self-review
+
+Run `sp:code-review`'s pre-commit self-review checklist before pushing. Fix findings before requesting review.
+
+### 5. Merge
+
+```bash
+git checkout main
+git pull --rebase
+git merge --no-ff feature/<slug> -m "chore(<scope>): merge feature/<slug> into main"
+git push
+```
+
+**Merge commit message.** The `commit-msg` hook runs `cog verify`, which rejects git's default `Merge branch 'x'` message *and* a `merge:` type — cocogitto's default type set has no `merge`. Always pass an explicit conventional `-m`. A rejected message leaves the merge staged but uncommitted; complete it with `git commit -m "chore(<scope>): …"`. Do not reach for `--no-verify` — the merge is valid, only the message token is not.
+
+### 6. Cleanup
+
+```bash
+git branch -d feature/<slug>        # Delete merged branch
+git worktree remove ../<project>-feature-<slug>  # Remove worktree if used
+git worktree prune                  # Clean up stale worktree references
+```
+
+## When to use
+
+- Starting new work on a feature or fix.
+- Managing parallel branches with git worktrees.
+- Preparing to merge and cleaning up afterward.
+- The operator says "start a branch", "create a worktree", or "merge this."
+
+Do **not** use this skill for:
+- Task lifecycle management — that is `sp:spur-dev`.
+- Commit message generation — that is `/sp:dev-gitmsg`.
+- Code review — that is `sp:code-review`.
+
+## References
+
+| Reference | Covers |
+|-----------|--------|
+| [branch-lifecycle.md](references/branch-lifecycle.md) | Full lifecycle with per-phase git commands, naming conventions, merge strategies |
+| [worktree-patterns.md](references/worktree-patterns.md) | Worktree creation, parallel-branch strategies, cleanup, disk-space awareness |
+
+## See also
+
+- **`sp:spur-dev`** — the task lifecycle that runs alongside branch lifecycle.
+- **`sp:code-review`** — pre-merge self-review workflow.

package/plugins/sp/skills/branch-workflow/references/branch-lifecycle.md

@@ -0,0 +1,69 @@
+---
+name: branch-lifecycle
+description: "Full branch lifecycle with per-phase git commands, branch-naming conventions, and merge-strategy guidance."
+see_also:
+  - branch-workflow
+---
+
+# Branch Lifecycle — Full Reference
+
+## Naming conventions
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| Feature | `feature/` | `feature/oauth-callback-handler` |
+| Bug fix | `fix/` | `fix/null-check-login-session` |
+| Refactor | `refactor/` | `refactor/extract-auth-middleware` |
+| Documentation | `docs/` | `docs/api-endpoint-guide` |
+| Chore | `chore/` | `chore/update-dependencies` |
+
+Slug rules: lowercase, hyphenated, ≤50 chars, derived from task title. No WBS numbers in branch names — they're neither stable nor descriptive.
+
+## Per-phase commands
+
+### Create
+
+```bash
+git checkout main && git pull --rebase    # Start from latest main
+git checkout -b feature/my-feature        # Create and switch
+```
+
+### Commit
+
+```bash
+git add <files>                           # Stage one concern at a time
+git commit -m "feat(auth): add OAuth callback handler"  # Conventional commit
+```
+
+### Self-review
+
+Run `sp:code-review` pre-commit checklist. Fix issues. Amend or add follow-up commits.
+
+### Push
+
+```bash
+git push -u origin feature/my-feature     # First push sets upstream
+```
+
+### Merge
+
+```bash
+git checkout main && git pull --rebase    # Update main
+git merge --no-ff feature/my-feature -m "chore(<scope>): merge feature/my-feature into main"  # Merge with conventional message
+git push                                  # Push the merge commit
+```
+
+**Merge strategy:** `--no-ff` (no fast-forward) always — it preserves the feature branch as a visible unit in history, making it easy to revert the entire feature if needed. Squash merges lose per-commit granularity; rebase merges rewrite history. `--no-ff` is the safe default.
+
+**Merge commit message.** The `commit-msg` hook runs `cog verify`, which rejects git's default `Merge branch 'x'` message *and* a `merge:` type — cocogitto's default type set has no `merge`. Always pass an explicit conventional `-m`. A rejected message leaves the merge staged but uncommitted; complete it with `git commit -m "chore(<scope>): …"`. Do not reach for `--no-verify` — the merge is valid, only the message token is not.
+
+### Cleanup
+
+```bash
+git branch -d feature/my-feature          # Delete local (safe — refuses if unmerged)
+git push origin --delete feature/my-feature  # Delete remote
+```
+
+## Worktree integration
+
+See [worktree-patterns.md](worktree-patterns.md) for the full parallel-branch workflow.

package/plugins/sp/skills/branch-workflow/references/worktree-patterns.md

@@ -0,0 +1,100 @@
+---
+name: worktree-patterns
+description: "Git worktree patterns — when to use worktrees, creation/cleanup, parallel-branch strategies, and disk-space awareness."
+see_also:
+  - branch-workflow
+  - branch-lifecycle
+---
+
+# Git Worktree Patterns
+
+A git worktree gives you an isolated working directory linked to the same repository. Each worktree has its own checked-out branch — no stashing, no `git switch` churn.
+
+## When to use worktrees
+
+| Scenario | Worktree? | Why |
+|----------|-----------|-----|
+| Two parallel features | ✅ Yes | Switch instantly between isolated directories |
+| Hotfix while feature in progress | ✅ Yes | Fix on main worktree, feature stays untouched |
+| Review in progress | ✅ Yes | Keep review branch available while starting new work |
+| Single-branch workflow | ❌ No | Overhead of managing extra directory isn't worth it |
+| CI/CD | ❌ No | Ephemeral checkouts already handle isolation |
+| Disk-constrained (<2GB free) | ❌ No | Each worktree costs ~500MB–2GB |
+
+## Commands
+
+### Create
+
+```bash
+git worktree add ../project-hotfix hotfix/critical-fix
+cd ../project-hotfix && bun install --frozen-lockfile
+```
+
+The worktree directory is created alongside the main project. Name it `<project>-<branch>` for clarity.
+
+A fresh worktree has no `node_modules` (gitignored), so the first `bun test` or typecheck fails on the first workspace import. Run `bun install --frozen-lockfile` immediately after creation so the worktree matches `bun.lock`.
+
+### List
+
+```bash
+git worktree list
+```
+
+Shows all worktrees with their branches and paths.
+
+### Remove (when done)
+
+```bash
+git worktree remove ../project-hotfix
+```
+
+### Prune (clean up stale references)
+
+```bash
+git worktree prune
+```
+
+Removes references to worktrees whose directories were manually deleted.
+
+## Parallel-branch strategy
+
+When running two branches in parallel:
+
+```
+~/projects/my-project/           (main branch, feature A work in progress)
+~/projects/my-project-feature-b/ (feature B in isolated worktree)
+```
+
+1. Create feature B worktree.
+2. Work on feature B in its isolated directory.
+3. Commit and push from the worktree.
+4. When switching back to feature A: `cd ~/projects/my-project` — no stash, no switch.
+5. Remove worktree when feature B is merged.
+
+## Disk-space awareness
+
+Each worktree is a full checkout (~500MB–2GB depending on project size). Check disk space before creating:
+
+```bash
+df -h .   # Check available space
+```
+
+After removing a worktree, run `git worktree prune` and `git gc` to reclaim space:
+
+```bash
+git worktree remove ../old-worktree
+git worktree prune
+git gc --aggressive
+```
+
+## `spur` on PATH is not this checkout
+
+`spur` (`~/.bun/bin/spur`) resolves to a *published* bundle in `~/node_modules/`, not to the repo you are standing in and not to the worktree. `resolveSpurBin()` propagates whichever binary you entered through into `vars.spurBin`, which the `task-lifecycle.yaml` guards run as `$spurBin task check` — so one wrong entry point silently gate-checks against the published bundle.
+
+Inside a worktree, and in the monorepo whenever CLI behavior is under test, invoke the tree's own source:
+
+```bash
+cd "<worktree>" && bun apps/cli/src/index.ts task check <wbs> --json
+```
+
+Confirm isolation by making a distinctive change in the worktree and checking that the command reflects it.