@use-the-fork/spindle 0.0.0-stage → 0.0.2

package/build/Assets/Blueprints/skills/int-writing-skills/references/persuasion-principles.md

@@ -0,0 +1,220 @@
+# Persuasion Principles for Skill Design
+
+## Overview
+
+LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
+
+**Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% → 72%, p < .001).
+
+## The Seven Principles
+
+### 1. Authority
+
+**What it is:** Deference to expertise, credentials, or official sources.
+
+**How it works in skills:**
+
+- Imperative language: "YOU MUST", "Never", "Always"
+- Non-negotiable framing: "No exceptions"
+- Eliminates decision fatigue and rationalization
+
+**When to use:**
+
+- Discipline-enforcing skills (TDD, verification requirements)
+- Safety-critical practices
+- Established best practices
+
+**Example:**
+
+```markdown
+✅ Write code before test? Delete it. Start over. No exceptions.
+❌ Consider writing tests first when feasible.
+```
+
+### 2. Commitment
+
+**What it is:** Consistency with prior actions, statements, or public declarations.
+
+**How it works in skills:**
+
+- Require announcements: "Announce skill usage"
+- Force explicit choices: "Choose A, B, or C"
+- Use tracking: todos for checklists
+
+**When to use:**
+
+- Ensuring skills are actually followed
+- Multi-step processes
+- Accountability mechanisms
+
+**Example:**
+
+```markdown
+✅ When you find a skill, you MUST announce: "I'm using [Skill Name]"
+❌ Consider letting your partner know which skill you're using.
+```
+
+### 3. Scarcity
+
+**What it is:** Urgency from time limits or limited availability.
+
+**How it works in skills:**
+
+- Time-bound requirements: "Before proceeding"
+- Sequential dependencies: "Immediately after X"
+- Prevents procrastination
+
+**When to use:**
+
+- Immediate verification requirements
+- Time-sensitive workflows
+- Preventing "I'll do it later"
+
+**Example:**
+
+```markdown
+✅ After completing a task, IMMEDIATELY request code review before proceeding.
+❌ You can review code when convenient.
+```
+
+### 4. Social Proof
+
+**What it is:** Conformity to what others do or what's considered normal.
+
+**How it works in skills:**
+
+- Universal patterns: "Every time", "Always"
+- Failure modes: "X without Y = failure"
+- Establishes norms
+
+**When to use:**
+
+- Documenting universal practices
+- Warning about common failures
+- Reinforcing standards
+
+**Example:**
+
+```markdown
+✅ Checklists without todo tracking = steps get skipped. Every time.
+❌ Some people find a todo list helpful for checklists.
+```
+
+### 5. Unity
+
+**What it is:** Shared identity, "we-ness", in-group belonging.
+
+**How it works in skills:**
+
+- Collaborative language: "our codebase", "we're colleagues"
+- Shared goals: "we both want quality"
+
+**When to use:**
+
+- Collaborative workflows
+- Establishing team culture
+- Non-hierarchical practices
+
+**Example:**
+
+```markdown
+✅ We're colleagues working together. I need your honest technical judgment.
+❌ You should probably tell me if I'm wrong.
+```
+
+### 6. Reciprocity
+
+**What it is:** Obligation to return benefits received.
+
+**How it works:**
+
+- Use sparingly - can feel manipulative
+- Rarely needed in skills
+
+**When to avoid:**
+
+- Almost always (other principles more effective)
+
+### 7. Liking
+
+**What it is:** Preference for cooperating with those we like.
+
+**How it works:**
+
+- **DON'T USE for compliance**
+- Conflicts with honest feedback culture
+- Creates sycophancy
+
+**When to avoid:**
+
+- Always for discipline enforcement
+
+## Principle Combinations by Skill Type
+
+| Skill Type           | Use                                   | Avoid               |
+| -------------------- | ------------------------------------- | ------------------- |
+| Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity |
+| Guidance/technique   | Moderate Authority + Unity            | Heavy authority     |
+| Collaborative        | Unity + Commitment                    | Authority, Liking   |
+| Reference            | Clarity only                          | All persuasion      |
+
+## Why This Works: The Psychology
+
+**Bright-line rules reduce rationalization:**
+
+- "YOU MUST" removes decision fatigue
+- Absolute language eliminates "is this an exception?" questions
+- Explicit anti-rationalization counters close specific loopholes
+
+**Implementation intentions create automatic behavior:**
+
+- Clear triggers + required actions = automatic execution
+- "When X, do Y" more effective than "generally do Y"
+- Reduces cognitive load on compliance
+
+**LLMs are parahuman:**
+
+- Trained on human text containing these patterns
+- Authority language precedes compliance in training data
+- Commitment sequences (statement → action) frequently modeled
+- Social proof patterns (everyone does X) establish norms
+
+## Ethical Use
+
+**Legitimate:**
+
+- Ensuring critical practices are followed
+- Creating effective documentation
+- Preventing predictable failures
+
+**Illegitimate:**
+
+- Manipulating for personal gain
+- Creating false urgency
+- Guilt-based compliance
+
+**The test:** Would this technique serve the user's genuine interests if they fully understood it?
+
+## Research Citations
+
+**Cialdini, R. B. (2021).** _Influence: The Psychology of Persuasion (New and Expanded)._ Harper Business.
+
+- Seven principles of persuasion
+- Empirical foundation for influence research
+
+**Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania.
+
+- Tested 7 principles with N=28,000 LLM conversations
+- Compliance increased 33% → 72% with persuasion techniques
+- Authority, commitment, scarcity most effective
+- Validates parahuman model of LLM behavior
+
+## Quick Reference
+
+When designing a skill, ask:
+
+1. **What type is it?** (Discipline vs. guidance vs. reference)
+2. **What behavior am I trying to change?**
+3. **Which principle(s) apply?** (Usually authority + commitment for discipline)
+4. **Am I combining too many?** (Don't use all seven)
+5. **Is this ethical?** (Serves user's genuine interests?)

package/build/Assets/Blueprints/skills/int-writing-skills/references/reference-skills.md

@@ -0,0 +1,20 @@
+# Reference skills
+
+Use this branch when the skill primarily supplies knowledge for lookup and application: a plugin, library, API, syntax, or reusable concept. Short procedures may support the knowledge without turning it into an end-to-end workflow.
+
+## Structure and disclosure
+
+For a new skill, load and fill the [Reference template](../assets/reference.md). For an existing skill, apply it only to the relevant edit.
+
+- State the covered subject, applicability, and version or environment constraints that affect correctness.
+- Organize by the questions the agent needs to answer. Keep each contract, its constraints, and its caveats together.
+- Keep common facts inline. When a lookup depends on a particular feature or environment, put its detail behind a pointer naming that condition.
+- Supply precise inputs, outputs, error behavior, and compatibility boundaries where relevant. Identify authoritative sources; avoid caching facts cheaply available from the environment.
+- Include one valid, adaptable application example when useful. Clearly distinguish real API syntax from illustrative pseudocode.
+- Add a lookup table or pitfalls only when they improve retrieval rather than repeat the same facts.
+
+A Reference skill does not need ordered authoring-style phases, per-topic completion gates, or a flowchart. A focused procedure belongs beside the topic it supports.
+
+## Completion
+
+The agent can locate and correctly apply the relevant fact, including its constraints and failure behavior, without loading unrelated topics. Use [Testing skills](./testing-skills.md) for a retrieval-and-application scenario that verifies this.

package/build/Assets/Blueprints/skills/int-writing-skills/references/testing-skills.md

@@ -0,0 +1,48 @@
+# Testing skills
+
+Skill-specific scenario selection and failure diagnosis live here. **REQUIRED:** use `int-testing-agent-guidance` for the shared execution procedure, baseline capture, fresh-context retest, and expanded testing. This reference does not replace that procedure.
+
+## Select an observable scenario
+
+Choose the scenario by primary type, then by the capability it teaches:
+
+| Primary type | Capability | Focused scenario                             | Success criterion                                              |
+| ------------ | ---------- | -------------------------------------------- | -------------------------------------------------------------- |
+| Interactive  | Discipline | A realistic choice involving the target rule | The agent takes the required action under pressure             |
+| Interactive  | Technique  | Apply the technique to a concrete variation  | Actions and completion criteria are met                        |
+| Interactive  | Pattern    | A case and a counterexample                  | The agent chooses the right branch in both                     |
+| Reference    | Knowledge  | Retrieve and apply a relevant fact           | The agent finds the fact and correctly applies its constraints |
+
+For a structural rewrite, exercise finding the first action and its completion criterion, selecting the correct branch, and loading only its required resources. For a flowchart change, exercise decision results, loop re-entry, and any parent/child hand-off.
+
+When arguments are supported, exercise their declared contract: equivalent aliases, omitted optional inputs, required inputs, value validation, conflicting flags, `--`, and task text containing flag-like content. Include explicit caller inputs as well as user invocation when both are supported.
+
+Freeze the prompt and observable criterion before the baseline. Use the current guidance for an edit or no guidance for a new skill. Record behavior verbatim; a statement that the rule is understood is not evidence that it is followed.
+
+## Diagnose the baseline gap
+
+| Observed failure                       | Guidance form                                          |
+| -------------------------------------- | ------------------------------------------------------ |
+| A known rule is skipped under pressure | A hard rule and counters for observed rationalizations |
+| Output has the wrong shape             | A positive recipe or output contract                   |
+| A required element is omitted          | A required field or slot in the structure              |
+| Behavior depends on a condition        | A conditional keyed to an observable predicate         |
+
+If the baseline meets the target, leave that behavior unchanged. Limit the edit to the observed gap and requested capability.
+
+For discipline-enforcing guidance, consult [Persuasion principles](./persuasion-principles.md) when selecting counters. Apply authority and commitment sparingly; use clarity rather than persuasion for reference material.
+
+## Retest and close
+
+Rerun the same prompt and criterion with the full revised guidance in a fresh context. Check actual choices, resource loads, and artifacts. Correct remaining failures narrowly, then rerun after each wording change.
+
+Run expanded testing only when explicitly requested or when `--test` is present, using `int-testing-agent-guidance`. It adds coverage rather than replacing the focused baseline and retest.
+
+| Testing pitfall                         | Required evidence                                               |
+| --------------------------------------- | --------------------------------------------------------------- |
+| "It is clear" or "it is just reference" | Application or retrieval behavior, not author confidence        |
+| "I will test if problems emerge"        | Baseline before drafting and retest before delivery             |
+| "There is no time"                      | Recorded validation or an explicit blocker, not claimed success |
+| "The output is close enough"            | The unchanged observable criterion passes                       |
+
+**Complete when:** the final focused scenario passes without unresolved failures, requested expanded testing is complete, or remaining failures and validation limits are explicitly reported.

package/build/Assets/Blueprints/skills/retrospective/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: retrospective
+description: "Assess a coding session and apply individually approved improvements."
+disable-model-invocation: true
+metadata:
+  spindle:
+    version: 1.1.2
+---
+
+Assess the selected coding session and help the maintainer improve future runs.
+
+## Required skill
+
+Before acting, load and follow **REQUIRED:** `int-retrospective`.
+
+Identify this invocation as a `maintainer` retrospective in the calling context, forwarding the user's session selection and any proposal-report pointer as task context. With no session selection, the internal skill uses the current session. It owns evidence selection, assessment, approval, application, and verification.

package/build/Assets/Blueprints/skills/setup-project/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: setup-project
+description: "Use after spindle init to document project tooling and establish domain glossaries."
+disable-model-invocation: false
+user-invocable: true
+metadata:
+  spindle:
+    version: 1.5.0
+---
+
+# Setup Project
+
+Curate the commands agents should use and establish project domain documentation. Project tooling varies by repository; register only commands that have been inspected and verified. The tooling registry in `.github/spindle.json` is authoritative, and Spindle regenerates `docs/agents/tooling.md` from it. These entries document commands; Spindle does not execute them.
+
+## Prerequisite
+
+The user must have completed `spindle init` before running this skill. This skill
+does not initialize the project. If the required project guidance or tooling
+registry is missing, report the prerequisite and stop.
+
+## Workflow
+
+Announce `Step <node ID> - <node label>` before acting on each node, including resumed steps and loop re-entries. After each decision, state its result and selected branch before entering the target node.
+
+```mermaid
+flowchart TD
+    B[Explore the project and its conventions] --> C[Update and verify tooling]
+    C --> G{Existing project?}
+    G -- Yes --> H[Populate domain glossaries]
+    G -- No --> I[Report setup outcome]
+    H --> I
+```
+
+### B. Explore the project and its conventions
+
+Read `docs/agents/domain.md`, the relevant glossary and ADRs, and existing project guidance. Inspect the repository's package manifests, task runner configuration, and test/build configuration to identify candidate commands. Do not treat discovery as registration: decide which commands are useful to agents and verify their names and argument forms against their configuration.
+
+Also inspect the source to determine whether this is an existing project: it contains substantive application or library code, not merely scaffold files or manifests. Ask the user if the evidence is ambiguous.
+
+**Complete when:** each candidate command selected for the guide has a verified invocation and a clear documentation section, and the existing-project classification is established, selecting C.
+
+### C. Update and verify tooling
+
+Load and follow the `update-tooling` skill. Supply the verified candidate commands and relevant configuration paths found in B as explicit context, and request a full registry comparison for initial setup. That skill owns the proposal, explicit approval, revision loop, `spindle tool` registry mutations, and generated-guide verification; do not duplicate or bypass its approval gate.
+
+**Complete when:** the delegated workflow has returned with the registry and guide verified, selecting G. If approval is pending, wait; if it reports failures or discrepancies, report the blocker and stop rather than claiming setup is complete.
+
+### G. Existing project?
+
+Use the classification established in B. Only an existing project with substantive application or library code proceeds to domain modeling. A new project containing only scaffold files or manifests skips it; do not create empty glossary files or invent a domain model.
+
+**Complete when:** an existing project selects H or a new project selects I.
+
+### H. Populate domain glossaries
+
+Load and follow the `int-domain-modeling` skill. Use the existing code and user input to establish domain terms and context boundaries. Resolve ambiguities and conflicts with the user rather than treating implementation names as authoritative terminology. Preserve existing definitions unless a change is agreed, and capture resolved terms as they become clear.
+
+For a single context, populate or refine the root `GLOSSARY.md`. For multiple contexts, populate or refine the context glossaries and `GLOSSARY-MAP.md`, including links to the glossaries and the relationships between contexts. Create the map only when multiple contexts are established. Keep glossaries free of implementation details and create files only when there are resolved terms to record.
+
+**Complete when:** resolved domain terms are recorded in the appropriate glossaries, multiple established contexts are mapped with valid links, and any unresolved questions are explicitly identified, selecting I.
+
+### I. Report setup outcome
+
+Summarize tooling changes applied or declined, guide verification, and domain documentation populated or skipped with the reason. Identify unresolved questions or blockers without claiming they are complete.
+
+**Complete when:** the user has an accurate setup outcome and any remaining actions.

package/build/Assets/Blueprints/skills/to-spec/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: to-spec
+description: "Turn an agreed feature request or approved design into a spec in its SDD feature workspace, then publish it to the configured ticket tracker."
+argument-hint: "[design file path]"
+disable-model-invocation: true
+metadata:
+  spindle:
+    version: 1.1.1
+---
+
+# To Spec
+
+Turn an agreed feature request or an approved design into a codebase-grounded spec, then publish it to the configured ticket tracker. A design is optional; when one exists, it must be completed and approved before the spec, and tickets follow the spec.
+
+Use the ticket-tracker conventions in project guidance when available. If tracker or publication status is unclear, ask the user before publishing; do not assume labels or invent status values.
+
+## Argument
+
+An optional design file path may be supplied. Read the entire file before drafting. Without a path, use the already-agreed requirements in the conversation; do not restart requirements discovery.
+
+## Workflow
+
+1. **Select the requirements source.**
+   - With a design path, treat that complete design as the requirements source. Older conversation cannot override it; apply only explicit user-requested changes and use other conversation as non-conflicting context.
+   - Without a design path, reuse an existing SDD feature workspace from the task context and treat its `design.md`, when present, as the requirements source. If no workspace design exists, use the agreed conversation. Do not require a design or create one automatically.
+   - If the supplied path is missing, unreadable, or ambiguous, explain the problem and ask for a corrected reference. Do not fall back to chat.
+   - Preserve unresolved decisions as open questions in Further Notes. Resolve gaps that block a ready-for-agent spec before publishing.
+
+   **Complete when:** the source is unambiguous and every supplied design has been read in full.
+
+2. **Select or create the SDD feature workspace.**
+   - Reuse the existing numbered `.scratch/<feature-id>-<slug>/` workspace when the selected design or spec belongs to one. Use its `spec.md`; do not create a second workspace for the same feature.
+   - Otherwise, derive a concise feature title from the agreed request and choose an author identity for this run. Run `spindle sdd create --title "<feature title>" --author "<author>"`; add `--with-design` when the selected design must be retained in the new workspace. If using a design outside `.scratch`, copy that approved source into the newly created `design.md`, replacing only the fresh template. Save the returned `spec` path and continue in that workspace.
+   - When the workspace has `design.md`, read it fully and use it as the requirements source. If it still contains `[PLACEHOLDER]` markers or has not been approved, pause and ask the user to finish or approve the design before drafting the spec.
+   - The selected SDD workspace's pre-created `spec.md` is the output. Replace its template content with the completed spec; do not create a dated folder or a second spec.
+
+   **Complete when:** one numbered SDD feature workspace is selected, its spec path is known, and any present design is complete and approved.
+
+3. **Explore and confirm the test seams.**
+   - Explore the repo to understand the current state if it has not already been explored. Use the relevant domain glossary and ADRs.
+   - Sketch the highest useful seams at which the feature should be tested. Prefer existing seams. If new seams are needed, propose them at the highest practical boundary.
+   - Ask the user to confirm the proposed seams before drafting. If the user corrects them, update the seam proposal and confirm the revision.
+
+   **Complete when:** the codebase context and user-confirmed test seams are recorded.
+
+4. **Write and publish the spec.**
+   - Fill the sections in the SDD-created `spec.md`: Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, and Further Notes.
+   - Give each important user story a concise, observable acceptance outcome or example scenario focused on user-visible behavior. Leave implementation-slice completion criteria to tickets; no fixed scenario format is required.
+   - Use domain glossary terms. Do not include file paths or code snippets unless a prototype captures a decision more clearly than prose.
+   - Publish the completed spec according to the configured ticket-tracker guidance. Ask before publishing if the destination or status is unclear.
+   - Once the spec is published, ask the user to invoke `/to-tickets` for planning. Do not invoke it automatically or start implementation here.
+
+   **Complete when:** the spec is published at the feature workspace's `spec.md` path, tracker publication is resolved, and no blocking ambiguity is hidden.

package/build/Assets/Blueprints/skills/to-tickets/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: to-tickets
+description: "Break an approved feature spec into tracer-bullet tickets with explicit blockers, then publish them to the configured ticket tracker."
+argument-hint: "[spec path or tracker reference]"
+disable-model-invocation: true
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# To Tickets
+
+Break an approved feature spec into **tickets**: independently actionable vertical slices with explicit blocking dependencies.
+
+An optional argument is one spec path or tracker reference. Read the full spec and its comments before planning. Without an argument, use the approved spec already in context. If the source is missing or ambiguous, ask for a usable reference before proceeding.
+
+## Process
+
+1. **Select the feature and confirm sequence.**
+   - Use the spec's existing feature workspace. In Spindle's local tracker, this is a numbered `.scratch/<feature-id>-<slug>/` directory containing `spec.md`, `sdd.json`, and `tickets/`. Never create a dated folder or a second workspace for the same feature.
+   - If `design.md` exists in the feature workspace, read it and confirm it was completed and approved before the spec. If the spec is not approved or a present design is unfinished, stop and resolve that before ticket planning.
+   - A design is optional. Do not require or create one when the approved spec was intentionally written without a design.
+   - For local SDD tracker work, use the feature's `spec.md` path with `spindle sdd` ticket commands. Otherwise follow the configured tracker's documented conventions.
+
+   **Complete when:** one approved spec and its tracker destination are identified; any existing design precedes it and is approved.
+
+2. **Gather context.** Use the conversation and spec as the requirements source. If the user supplies a tracker reference, read its full body and comments. Explore the codebase when needed, using its glossary vocabulary and relevant ADRs. Look for useful prefactoring that reduces implementation difficulty.
+
+   **Complete when:** requirements, relevant project context, and tracker rules are understood.
+
+3. **Draft vertical slices.** Break the approved work into tracer-bullet tickets:
+   - Each slice is a narrow, complete path through the relevant layers and is verifiable on its own.
+   - Each slice fits a fresh context window.
+   - Identify only genuine blockers and list tickets in dependency order.
+   - A wide mechanical refactor may use expand–migrate–contract sequencing when no vertical slice can remain green.
+
+   **Complete when:** every requirement is covered, each ticket is independently actionable, and blocking relationships are explicit.
+
+4. **Get approval.** Present the proposed breakdown as a numbered list. For each ticket, show its title, blockers, and end-to-end behavior. Ask whether the granularity and dependency edges are right and whether anything should be merged or split. Iterate until the user approves. Do not publish before approval.
+
+   **Complete when:** the user approves the ticket breakdown and blocker relationships.
+
+5. **Publish the tickets.**
+   - For a local Spindle SDD tracker, create each ticket in dependency order with `spindle sdd ticket create --spec <absolute-spec-path>`. Supply its title, reporter, category (`bug` or `enhancement`), and author. Fill the generated ticket's Requirements and Acceptance Criteria using the tracker guidance. After creation, use `spindle sdd ticket update --spec <absolute-spec-path> --ticket <id> --blocked-by <blocker-ids...> --author <author>` to record each dependency; omit `--blocked-by` when there are no blockers. Keep the approved spec and feature ledger authoritative.
+   - For an external ticket tracker, create one ticket per approved ticket in dependency order and use native blocking relationships when available; otherwise record blockers in each ticket. If the source was an existing ticket, create sub-tickets as required by the tracker.
+   - Apply a status only when the project documents it or the user requests it. Do not close or modify a parent ticket.
+   - Publishing ends here. Tell the user that delivery begins through the project's documented implementation workflow; do not start implementation.
+
+   **Complete when:** every approved ticket exists in the configured tracker with its acceptance criteria and blockers, and no implementation work has started.

package/build/Assets/Blueprints/skills/update-tooling/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: update-tooling
+description: "Use when tooling commands are added, changed, or removed, or when refreshing the tooling registry and generated guide."
+argument-hint: "[change description or tooling paths]"
+disable-model-invocation: false
+user-invocable: true
+metadata:
+  spindle:
+    version: 1.1.0
+---
+
+# Update Tooling
+
+Keep the tooling registry in `.github/spindle.json` and generated `docs/agents/tooling.md` aligned with verified project commands. These entries document commands; Spindle does not execute them. Do not install tools, change tooling configuration, initialize project guidance, or update glossaries.
+
+## Input
+
+Optional free-form text identifies the tooling changes or configuration paths to inspect. Treat all supplied text as context, not flags. A calling skill supplies this context explicitly. With no supplied target, compare the full registry against the project's tooling configuration; do not infer a target from unrelated conversation.
+
+## Workflow
+
+Announce `Step <node ID> - <node label>` before acting on each node, including resumed steps and loop re-entries. After each decision, state its result and selected branch before entering the target node.
+
+```mermaid
+flowchart TD
+    A[Inspect tooling and registry] --> B[Propose tooling changes]
+    B --> C{Changes approved?}
+    C -- Revise --> B
+    C -- Approve --> D[Apply approved changes]
+    C -- Decline or no changes needed --> E[Verify registry and guide]
+    D --> E
+    E --> F[Report outcome]
+```
+
+### A. Inspect tooling and registry
+
+Read project guidance and run `spindle tool list` from the target Git working tree. Inspect package manifests, task runner configuration, and test/build configuration for the supplied target, or the whole project when no target is supplied. Verify command names, argument forms, and working-directory requirements against configuration. Preserve unrelated registry entries; absence from a targeted inspection is not evidence that an entry is obsolete.
+
+Do not execute project commands merely to document them if execution could install dependencies, mutate data, or have side effects without authorization. If the registry is missing or invalid, report the prerequisite and stop; do not run initialization or silently repair it.
+
+**Complete when:** the inspection scope, current entries, and verified candidate changes are known, selecting B; otherwise stop with the blocker.
+
+### B. Propose tooling changes
+
+Present the complete proposed additions, updates, and removals, including each entry's stable kebab-case key, section, exact command text, and optional description. Show current and proposed values for updates and identify entries being removed. Include relevant working-directory or usage limitations. Do not register every discovered command or propose speculative invocations.
+
+If the user requests revisions, inspect any additional relevant configuration before presenting the revised change set.
+
+**Complete when:** the exact change set is available for user review, or no changes are needed, selecting C.
+
+### C. Changes approved?
+
+Ask for explicit approval of the complete change set and wait. Approval applies only to the presented changes; revisions require a new proposal and approval. Declining leaves the registry unchanged. If no changes are needed, state that result and skip mutation without requesting approval.
+
+**Complete when:** approval selects D, revisions select B, or declining or having no changes selects E. Without a response to a pending approval request, wait here.
+
+### D. Apply approved changes
+
+Apply only approved changes through Spindle, not by directly editing the registry or generated Markdown. Add one entry per approved command:
+
+```sh
+spindle tool add \
+  --key test-unit \
+  --section Testing \
+  --command "pnpm test -- --run" \
+  --description "Run the focused unit tests."
+```
+
+Use `spindle tool update <key>` with the approved `--section`, `--command`, or `--description` fields; `--clear-description` explicitly removes a description. Use `spindle tool remove <key>` for approved removals. Each successful mutation regenerates the guide, grouped by section with empty sections omitted.
+Run project scripts with `{{ computed.spindle_package_manager }} <script>`, such as `{{ computed.spindle_package_manager }} lint`.
+
+If the inspected registry or relevant configuration has changed since approval, stop and return to A, then obtain approval for a refreshed proposal. If a command fails, stop and report the failure and any already-applied changes; do not claim atomicity or completion.
+
+**Complete when:** all approved changes succeed with no unapproved changes, selecting E; otherwise report the blocker.
+
+### E. Verify registry and guide
+
+Run `spindle tool list` again and inspect `docs/agents/tooling.md`. Confirm entries, sections, commands, descriptions, and limitations agree, approved changes are reflected, and unrelated entries remain unchanged. After a decline or no-op, verify the existing state without mutating it. Report mismatches; any corrective changes require a new proposal and approval rather than direct Markdown edits.
+
+**Complete when:** verification results and any discrepancies are known, selecting F.
+
+### F. Report outcome
+
+Summarize the inspected scope, changes applied or declined, and registry/guide verification. Explicitly identify failures, partial application, mismatches, and remaining actions; do not describe an unverified or inconsistent state as complete.
+
+**Complete when:** the user or calling skill receives the outcome and any blockers.

package/build/Assets/Templates/Catalog.js

@@ -0,0 +1,12 @@
+export const templateCatalog = {
+    project: [
+        { source: "project/copilot-instructions.md", destination: ".github/copilot-instructions.md" },
+        { source: "project/domain.md", destination: "docs/agents/domain.md" },
+        { source: "project/ticket-tracker.md", destination: "docs/agents/ticket-tracker.md" },
+    ],
+    sdd: {
+        spec: "sdd/spec.md",
+        design: "sdd/design.md",
+        ticket: "sdd/ticket.md",
+    },
+};

package/build/Assets/Templates/Catalog.ts

@@ -0,0 +1,17 @@
+export interface TemplateAsset {
+  readonly source: string;
+  readonly destination: string;
+}
+
+export const templateCatalog = {
+  project: [
+    { source: "project/copilot-instructions.md", destination: ".github/copilot-instructions.md" },
+    { source: "project/domain.md", destination: "docs/agents/domain.md" },
+    { source: "project/ticket-tracker.md", destination: "docs/agents/ticket-tracker.md" },
+  ] satisfies readonly TemplateAsset[],
+  sdd: {
+    spec: "sdd/spec.md",
+    design: "sdd/design.md",
+    ticket: "sdd/ticket.md",
+  },
+} as const;

package/build/Assets/Templates/project/copilot-instructions.md

@@ -0,0 +1,17 @@
+## Agent skills
+
+### Issue tracker
+
+Repository triage requests are tracked as local Markdown under `.scratch/YYYY-MM-DD-<feature-slug>/`; SDD specs and tickets live in numbered `.scratch/<feature-id>-<feature-slug>/` workspaces. See `docs/agents/issue-tracker.md` and `docs/agents/ticket-tracker.md` for their conventions.
+
+### Triage labels
+
+Use `Category: bug|enhancement` and the five canonical state values in `Status:`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+This is a multi-context repo; use `GLOSSARY-MAP.md` to find the relevant context glossary and consult `docs/adr/` for cross-context decisions. See `docs/agents/domain.md`.
+
+## Project Tooling
+
+Run project commands with pnpm. Before running commands, read [Project tooling](../docs/agents/tooling.md) for available commands and usage.