@gobing-ai/spur 0.3.80 → 0.3.82

package/plugins/sp/skills/taste-refactoring-ui/examples/review-template.md

@@ -0,0 +1,51 @@
+# Reusable UI Review Template
+
+## Diagnosis
+The screen’s main problem is **[hierarchy / density / unclear grouping / inconsistent system / weak typography / noisy color / over-decoration]**. The target direction is **[clear, calm, focused, premium, playful, dense-but-scannable, etc.]**.
+
+## Highest-impact changes
+
+### 1. [Issue]
+**Observation:** …
+**Why it matters:** …
+**Refactor:** …
+**System rule:** …
+
+### 2. [Issue]
+**Observation:** …
+**Why it matters:** …
+**Refactor:** …
+**System rule:** …
+
+### 3. [Issue]
+**Observation:** …
+**Why it matters:** …
+**Refactor:** …
+**System rule:** …
+
+## System decisions
+- Type scale: …
+- Font weights: …
+- Spacing scale: …
+- Content widths: …
+- Radius scale: …
+- Shadow/elevation scale: …
+- Primary/neutral/semantic color ramps: …
+- Icon sizes: …
+
+## Implementation notes
+- Component changes: …
+- Responsive behavior: …
+- Interaction states: …
+- Empty/loading/error handling: …
+- Media constraints: …
+
+## Final quality gate
+- [ ] Primary task obvious
+- [ ] Hierarchy works in grayscale
+- [ ] Grouping is unambiguous
+- [ ] Typography is readable
+- [ ] Colors are systematic and accessible
+- [ ] Borders/shadows are purposeful
+- [ ] States are covered
+- [ ] No decorative fix is hiding a structural issue

package/plugins/sp/skills/taste-refactoring-ui/references/refactoring-ui-playbook.md

@@ -0,0 +1,170 @@
+# Refactoring UI — Operational Playbook
+
+This is a concise operational distillation of the source material, organized by the book’s major sections.
+
+## 1. Starting from scratch
+
+### Start with a feature, not a layout
+Design actual functionality before global shell decisions. The shell should emerge from the needs of the features, not the reverse.
+
+### Detail comes later
+Explore structure in low fidelity. Grayscale is useful because it forces hierarchy to be carried by spacing, size, and contrast. Treat early wireframes as disposable.
+
+### Don’t design too much
+Work in short design → implementation cycles. Build the smallest useful version first. Do not imply functionality that is not ready to ship.
+
+### Choose a personality
+Personality is built from concrete choices: typeface, color, border radius, imagery, and language. Keep these choices coherent.
+
+### Limit your choices
+Predefine scales and tokens. Use process-of-elimination between neighboring values instead of endless micro-adjustment. Systematize recurring low-level choices.
+
+## 2. Hierarchy is everything
+
+### Not all elements are equal
+A polished interface makes relative importance obvious. Primary, secondary, and tertiary elements should not compete equally.
+
+### Size isn’t everything
+Use weight and contrast to create hierarchy so headings do not become oversized and support text does not become unreadably small.
+
+### Don’t use grey text on colored backgrounds
+The real goal is lower contrast, not “grey.” Choose text colors that harmonize with the surface instead of simply applying grey or low opacity.
+
+### Emphasize by de-emphasizing
+If an important item still does not stand out, quiet its competitors before adding more emphasis.
+
+### Labels are a last resort
+Remove labels where format/context already explains the value. Combine label + value into natural language when possible. When labels are necessary, style them according to the user’s scan target.
+
+### Separate visual hierarchy from document hierarchy
+Semantic markup and visual appearance are different concerns. Keep accessible/semantic structure while styling visual importance appropriately.
+
+### Balance weight and contrast
+Heavy visual elements may need lower contrast; low-contrast elements may need more weight. Use these as counterbalances.
+
+### Semantics are secondary
+Buttons, links, and actions do not all need the same visual treatment. Style according to action priority, while preserving correct semantics and interaction behavior.
+
+## 3. Layout and spacing
+
+### Start with too much white space
+It is easier to tighten a spacious design than to rescue a cramped one. Density can be valid, but make it intentional.
+
+### Establish a spacing and sizing system
+Use a scale with perceptible, non-linear jumps. Fine differences matter more at small sizes than large sizes.
+
+### You don’t have to fill the whole screen
+Use max widths and intrinsic content dimensions. Empty space is not wasted space when it improves comprehension.
+
+### Grids are overrated
+Do not force unrelated sections to line up to one universal grid. Use the local structure the content needs.
+
+### Relative sizing doesn’t scale
+Avoid overusing relative percentages for things that need stable emphasis or readable dimensions. Use intentional widths and breakpoints.
+
+### Avoid ambiguous spacing
+Spacing must make relationships obvious. A gap should clearly say whether two things belong together or apart.
+
+## 4. Designing text
+
+### Establish a type scale
+Use a small, predefined scale instead of pixel-by-pixel typography.
+
+### Use good fonts
+For UI, prioritize families designed for legibility at small sizes. Popular, well-tested neutral sans-serifs are safe defaults; use personality faces intentionally.
+
+### Keep your line length in check
+Long lines are hard to read. Limit prose width even on wide screens.
+
+### Baseline, not center
+Text and icons often look more natural when aligned optically/baseline rather than mechanically center-aligned.
+
+### Line-height is proportional
+Small text generally needs more line-height; large headlines can use tighter line-height.
+
+### Not every link needs a color
+Context and interaction styling may be enough. Too many colored links create noise.
+
+### Align with readability in mind
+Left-align most multi-line text. Center alignment is better suited to short isolated blocks.
+
+### Use letter-spacing effectively
+Uppercase text can benefit from added tracking. Large headlines in wide-spaced UI fonts may benefit from tighter tracking. Do not try to turn display faces into body faces by spacing alone.
+
+## 5. Working with color
+
+### Ditch hex for HSL
+Thinking in hue, saturation, and lightness makes relationships between colors easier to reason about.
+
+### You need more colors than you think
+A useful palette needs multiple shades for text, surfaces, borders, hover states, fills, and semantic feedback.
+
+### Define your shades up front
+Create ramps for key colors and neutrals before styling individual elements.
+
+### Don’t let lightness kill your saturation
+Lighter/darker colors often need saturation and sometimes hue adjustments to stay rich and natural.
+
+### Greys don’t have to be grey
+Slightly tinted neutrals can give the interface more character and cohesion.
+
+### Accessible doesn’t have to mean ugly
+Use contrast deliberately and employ multiple tones/weights rather than making everything equally dark.
+
+### Don’t rely on color alone
+Pair color with copy, icons, shapes, borders, or placement so status remains understandable without color perception.
+
+## 6. Creating depth
+
+### Emulate a light source
+Use consistent highlights and shadows so surfaces feel physically coherent.
+
+### Use shadows to convey elevation
+Shadow size and softness should map to distance from the base surface and can help direct focus.
+
+### Shadows can have two parts
+A realistic UI shadow can combine a tight contact shadow with a broader ambient shadow.
+
+### Even flat designs can have depth
+Borders, background shifts, highlights, and overlap can create separation without large shadows.
+
+### Overlap elements to create layers
+Controlled overlap can communicate relationships and produce stronger composition.
+
+## 7. Working with images
+
+### Use good photos
+Source quality matters more than effects.
+
+### Text needs consistent contrast
+Text over images must remain readable regardless of image variation. Use overlays, contrast reduction, colorization, or subtle text glow/shadow as tools.
+
+### Everything has an intended size
+Do not enlarge small-detail icons until they look chunky. Do not shrink dense screenshots until content becomes unreadable. Crop or redesign the presentation.
+
+### Beware user-uploaded content
+Expect arbitrary aspect ratios, colors, and quality. Use fixed frames, cropping, safe contrast regions, and fallbacks.
+
+## 8. Finishing touches
+
+### Supercharge the defaults
+Default controls can often be improved with coherent radius, typography, iconography, spacing, and state styling.
+
+### Add color with accent borders
+Thin, intentional accents can introduce brand color without turning large surfaces into saturated blocks.
+
+### Decorate your backgrounds
+Subtle shapes, patterns, gradients, or illustrations can add personality, but they should remain subordinate to content.
+
+### Don’t overlook empty states
+Use empty states to teach the next action, set expectations, or explain what will appear there.
+
+### Use fewer borders
+When possible, create separation with spacing, surface color, or depth instead of boxing everything in.
+
+### Think outside the box
+Do not default every section to a rectangular card. Allow imagery, backgrounds, overlap, or asymmetrical composition when they better serve the content.
+
+## 9. Leveling up
+
+The larger lesson is to build visual judgment through deliberate observation, comparison, and repetition. Collect good patterns, notice why they work, and turn recurring insights into reusable systems rather than isolated tricks.

package/plugins/sp/skills/wayfinder/SKILL.md

@@ -128,7 +128,7 @@ Invoked when the operator has a loose idea and the destination itself is foggy.
 
 ### Work Through the Map
 
-Invoked when a map already exists (operator provides the feature ID). A ticket is **optional** — without one, pick the next frontier ticket, not the operator's preference.
+Invoked when a map already exists (operator provides the feature ID). A ticket is **optional** — without one, pick the next frontier ticket, not the operator's preference. Pipeline runs: `references/pipeline-resolution.md`.
 
 0. **Branch first.** `git checkout -b wayfind/<wbs>-<slug>`, for the same reason as charting: steps 6 and 7 below remove fog from the map, and the gate that checks the removal was paid for measures the branch, not the commit. On the default branch the check silently passes no matter what you delete.
 1. **Load the map** — the feature description (the low-res view), not every task body. Read the destination and Decisions-so-far to orient.
@@ -266,7 +266,7 @@ The operator invokes this skill directly: `Skill(skill="sp:wayfinder", args="<lo
 
 ## Reference Files
 
-- **`../spur-dev/references/decision-brief.md`** — Decision-brief format for HITL choices during charting
+- **`../spur-dev/references/decision-brief.md`** — Decision-brief format for HITL choices during charting.
 - **`../spur-dev/references/cross-cutting.md`** — Verification-before-completion rule (one-ticket-per-session discipline)
 - **`../spur-dev/references/execution-batch.md`** — Batch execution model (pairs with one-ticket-per-session loop)
 

package/plugins/sp/skills/wayfinder/references/pipeline-resolution.md

@@ -0,0 +1,30 @@
+# Wayfinder resolution-pipeline authoring contract
+
+Reference for the `wayfinder-resolution` workflow's `investigate` hop. The pipeline passes a
+bounded pointer prompt; this page carries the full authoring contract the hop must follow.
+Context variables (`${vars.wbs}`, `${vars.resolutionMode}`, `${vars.evidencePolicy}`) are
+resolved by the engine before the hop runs.
+
+## Research boundary (preserve the research boundary)
+
+- Work only from the prepared local bundle `.spur/run/<runId>-wayfinder-input.json`, local
+  shell/file reads, and the `spur` CLI. Do not use network search or MCP tools.
+- Do not invoke `task-pipeline.yaml`, `/sp:dev-run`, `/sp:dev-runall`, or any code
+  implementation pipeline. This hop authors research/specification sections — it never
+  implements.
+
+## Procedure
+
+1. Read the task file for `<wbs>` and map its existing Requirements and Acceptance Criteria
+   onto the existing Design/Plan/References sections.
+2. Author concise Solution, Testing, and Review sections through
+   `spur task update --section --from-file` (write each section to a file, then pass it).
+3. Finish with a short summary and stop.
+
+## Evidence-anchor contract (mandatory — 0299 R1 line-anchor rule)
+
+When the task's evidence lives in a shared evidence file, anchor every Solution/Testing
+`file:line` citation truthfully — resolve the section's real start line with
+`grep -n "^## <wbs> " <evidence-file>` and cite that exact line. NEVER copy a line number
+from another ticket's example; each WBS anchors to its own section. Before finishing, re-read
+each cited line and confirm it names the requirement's subject.

package/schemas/spur-config.schema.json

@@ -173,6 +173,62 @@
                         }
                     }
                 },
+                "fleet": {
+                    "type": "object",
+                    "description": "The project's agent fleet (G65 / 0858): the single declaration of composition, the on/off switch, and the dispatch strategy. PROJECT LAYER ONLY — a global-layer agent.fleet fails the load. Replaces the retired .spur/fleet.json (0835) and agent.team (0857). Mirrors @gobing-ai/spur-config AgentFleetSchema (Zod is SSOT).",
+                    "properties": {
+                        "enabled": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "The single fleet switch. `spur serve` materializes and autostarts the roster only when true; an absent or disabled fleet starts nothing."
+                        },
+                        "strategy": {
+                            "type": "string",
+                            "enum": ["rest", "gtd"],
+                            "default": "rest",
+                            "description": "Dispatch strategy, reconciled into project_strategy at serve start (0859). One name is added by a typed code change, not by config."
+                        },
+                        "orchestrator": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "memberLocalId of the one planner-role member carrying purpose: orchestrator. Absent = no orchestrator declared (never inferred)."
+                        },
+                        "members": {
+                            "type": "array",
+                            "default": [],
+                            "description": "The roster. Each member declares a role or an executor. `enabled: false` keeps the member's derived <role>-<n> id index but does not materialize it.",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "id": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Explicit stable id; wins over the derived <role>-<n> form."
+                                    },
+                                    "role": {
+                                        "type": "string",
+                                        "enum": ["scribe", "coder", "reviewer", "planner"],
+                                        "description": "Layer-1 role id (closed vocabulary)."
+                                    },
+                                    "executor": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Executor profile name or a raw canonical agent type."
+                                    },
+                                    "purpose": {
+                                        "type": "string",
+                                        "description": "Free-form member purpose; `orchestrator` is the value the orchestrator pointer binds to."
+                                    },
+                                    "enabled": {
+                                        "type": "boolean",
+                                        "description": "Default true. False preserves the member's derived id index without materializing it."
+                                    }
+                                },
+                                "anyOf": [{ "required": ["role"] }, { "required": ["executor"] }]
+                            }
+                        }
+                    }
+                },
                 "roles": {
                     "type": "object",
                     "description": "Per-role tier/stage overrides over DEFAULT_AGENT_ROLES (0572 / ADR-061). Keys are the closed role vocabulary (scribe, coder, reviewer, planner); a present field replaces the default for that role, an omitted field keeps it. Mirrors @gobing-ai/spur-config AgentRoleConfigSchema (Zod is SSOT).",
@@ -192,91 +248,6 @@
                             }
                         }
                     }
-                },
-                "team": {
-                    "type": "object",
-                    "description": "Declarative agent teams keyed by team id (the map key is the teamId). Each team materializes a roster of agent specs (feature M). Mirrors @gobing-ai/spur-config TeamConfigSchema (Zod is SSOT).",
-                    "additionalProperties": {
-                        "type": "object",
-                        "required": ["name", "work_dir", "members"],
-                        "properties": {
-                            "name": {
-                                "type": "string",
-                                "minLength": 1,
-                                "description": "Human-readable team label."
-                            },
-                            "work_dir": {
-                                "type": "string",
-                                "minLength": 1,
-                                "description": "Default member workspace. A leading `~` is tilde-expanded at load."
-                            },
-                            "autostart": {
-                                "type": "boolean",
-                                "description": "Team-wide autostart default; per-member autostart overrides (effective = member.autostart ?? team.autostart ?? false)."
-                            },
-                            "members": {
-                                "type": "array",
-                                "minItems": 1,
-                                "description": "Roster of member references (>= 1). A bare string is shorthand for { executor: <string> }; the composed agent id is <teamId>-<id ?? executor>.",
-                                "items": {
-                                    "oneOf": [
-                                        {
-                                            "type": "string",
-                                            "minLength": 1
-                                        },
-                                        {
-                                            "type": "object",
-                                            "properties": {
-                                                "executor": {
-                                                    "type": "string",
-                                                    "minLength": 1,
-                                                    "description": "Executor name \u2014 resolved against agent.executors first, else a raw canonical agent type. Optional since 0543: a role-only member (no executor) resolves one through the tier ladder at materialization; at least one of role or executor is required."
-                                                },
-                                                "id": {
-                                                    "type": "string",
-                                                    "minLength": 1,
-                                                    "description": "Local member id; composed id is <teamId>-<id ?? executor> (must match ^[a-z][a-z0-9_-]{1,63}$)."
-                                                },
-                                                "purpose": {
-                                                    "type": "string"
-                                                },
-                                                "role": {
-                                                    "type": "string",
-                                                    "enum": ["scribe", "coder", "reviewer", "planner"],
-                                                    "description": "Layer-1 role id (0538 R3): typed routing field carried onto the materialized spec; purpose stays prose."
-                                                },
-                                                "workspace": {
-                                                    "type": "string",
-                                                    "minLength": 1,
-                                                    "description": "Per-member workspace override. A leading `~` is tilde-expanded at load."
-                                                },
-                                                "model": {
-                                                    "type": "string",
-                                                    "minLength": 1
-                                                },
-                                                "autonomy": {
-                                                    "type": "string"
-                                                },
-                                                "systemPrompt": {
-                                                    "type": "string"
-                                                },
-                                                "command": {
-                                                    "type": "array",
-                                                    "items": {
-                                                        "type": "string",
-                                                        "minLength": 1
-                                                    }
-                                                },
-                                                "autostart": {
-                                                    "type": "boolean"
-                                                }
-                                            }
-                                        }
-                                    ]
-                                }
-                            }
-                        }
-                    }
                 }
             }
         },
@@ -333,6 +304,55 @@
                 }
             }
         },
+        "builder": {
+            "type": "object",
+            "description": "Builder noun configuration. Currently hosts the release plumbing knobs for `spur builder bump-ver` / `drop-tags`; every field defaults to the built-in release convention, so an absent builder section keeps default behavior.",
+            "properties": {
+                "bump-ver": {
+                    "type": "object",
+                    "description": "Release knobs for bump-ver/drop-tags. Defaults: -v separator, publish.yml workflow, chore(release) commit, gh run list limit 5.",
+                    "properties": {
+                        "tagVersionSeparator": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "Release tag format: <package><separator><version>. Default \"-v\"."
+                        },
+                        "publishWorkflow": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "GitHub Actions workflow file the pushed release tag triggers. Default \"publish.yml\"."
+                        },
+                        "releaseCommitType": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "Conventional commit type for the release commit. Default \"chore\"."
+                        },
+                        "releaseCommitScope": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "Conventional commit scope for the release commit. Default \"release\"."
+                        },
+                        "ghRunListLimit": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "gh run list --limit used to point at the triggered publish run. Default 5."
+                        },
+                        "versionCarriers": {
+                            "type": "array",
+                            "description": "Extra version carriers beyond workspace package.json files. Default: none. Types are registered in apps/cli/src/version-carriers.ts (registerCarrierType), which validates instances at release time; registering a new type extends this description in the same commit.",
+                            "items": {
+                                "type": "object",
+                                "description": "One carrier instance. Required field: type (string). Built-ins: plugin-manifest { paths: [..] } — repo-wide manifests synced to the release version (e.g. per-platform plugin.json mirrors); ts-literal { file?, identifier? } — version constant in a package source file (defaults src/config.ts / binaryVersion).",
+                                "properties": {
+                                    "type": { "type": "string", "minLength": 1 }
+                                },
+                                "required": ["type"]
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "tasks": {
             "type": "object",
             "description": "Task-folder registration (design \u00a79). Absorbs the legacy docs/.tasks/config.json folders + baseCounter concepts. Mirrors @gobing-ai/spur-config tasksConfigSchema (Zod is SSOT).",