@shardworks/guild-starter-kit 0.1.17 → 0.1.19

package/curricula/guild-operations/content.md

@@ -40,14 +40,105 @@ Other roles may emerge as the guild evolves.
 
 ## Workshops
 
-A workshop is a repository where animas do their work. The patron assigns workshops (usually existing repos), and artificers work inside them on commissions. The patron judges results by the works produced, not by inspecting the workshop.
+A workshop is a repository where animas do their work. Workshops are guild space — the patron assigns them, but during normal operation the patron judges results by the works produced, not by inspecting the workshop directly.
 
-### Workshop Lifecycle
+Each workshop is registered in `guild.json` under the `workshops` key with its name, remote URL, and the timestamp it was added. On disk, the guild maintains a bare clone of each workshop at `.nexus/workshops/{name}.git`. Commission worktrees are created from these bare clones, giving each commission an isolated working directory.
 
-1. A workshop is registered with the guild (`nsg workshop add <url>`)
-2. The guild clones it and manages worktrees for concurrent commissions
-3. Artificers work in isolated worktrees — one per commission
-4. Completed work is delivered as branches or pull requests
+### Managing Workshops
+
+Four commands manage the workshop lifecycle:
+
+| Command | What it does |
+|---------|-------------|
+| `nsg workshop add <url>` | Clone a remote repo and register it as a workshop |
+| `nsg workshop remove <name>` | Remove a workshop — deletes bare clone, worktrees, and guild.json entry |
+| `nsg workshop list` | List all workshops with clone status and active worktree count |
+| `nsg workshop create <org/name>` | Create a new GitHub repo and register it as a workshop |
+
+### Adding an Existing Repository
+
+When the patron has an existing repository they want the guild to work on:
+
+```
+nsg workshop add https://github.com/org/my-app.git
+```
+
+This clones the repo as a bare clone into `.nexus/workshops/my-app.git` and adds it to `guild.json`. The workshop name is derived from the URL (the last path segment, minus `.git`). To use a custom name:
+
+```
+nsg workshop add https://github.com/org/my-app.git --name frontend
+```
+
+The repository must already exist and be accessible. SSH URLs work too:
+
+```
+nsg workshop add git@github.com:org/my-app.git
+```
+
+### Creating a New Repository
+
+For greenfield work where no repository exists yet:
+
+```
+nsg workshop create myorg/new-project
+```
+
+This requires the GitHub CLI (`gh`) to be installed and authenticated. The command:
+
+1. Creates the repository on GitHub (private by default)
+2. Clones it as a bare clone into `.nexus/workshops/`
+3. Registers it in `guild.json`
+
+For a public repository:
+
+```
+nsg workshop create myorg/new-project --public
+```
+
+If `gh` is not installed or not authenticated, the command fails with a clear message explaining what's needed.
+
+### Workshop Status
+
+`nsg workshop list` shows each workshop with:
+
+- **✓ / ✗** — whether the bare clone exists on disk (it may be missing after a fresh guild clone before running `nsg guild restore`)
+- **Active worktrees** — how many commissions currently have worktrees checked out
+- **Remote URL** — where the repo lives
+
+If a bare clone is missing, the output includes a hint to run `nsg guild restore`.
+
+### Removing a Workshop
+
+```
+nsg workshop remove my-app
+```
+
+This deletes the bare clone, any commission worktrees for that workshop, and removes the entry from `guild.json`. This is a destructive operation — the workshop's local state is gone. The remote repository is not affected.
+
+### How Workshops Are Used in Commissions
+
+When a commission is dispatched to a workshop, the worktree-setup engine:
+
+1. Creates a commission-specific branch from `main` in the workshop's bare clone
+2. Checks out a git worktree at `.nexus/worktrees/{workshop}/commission-{id}/`
+3. The anima works in this isolated directory
+
+This means multiple commissions can run concurrently in the same workshop without interfering with each other — each gets its own branch and working directory.
+
+### guild.json Shape
+
+```json
+{
+  "workshops": {
+    "my-app": {
+      "remoteUrl": "https://github.com/org/my-app.git",
+      "addedAt": "2026-03-24T12:00:00.000Z"
+    }
+  }
+}
+```
+
+The `remoteUrl` is the source of truth. The bare clone on disk is ephemeral and can be reconstructed from this URL by `nsg guild restore`.
 
 ## Commissions
 
@@ -58,7 +149,7 @@ A commission is a unit of work posted by the patron and undertaken by the guild.
 3. **In progress** — the artificer works in a workshop worktree
 4. **Completed** or **Failed** — work is delivered or the commission is marked as failed
 
-Use `nsg dispatch` to post and dispatch commissions.
+Use `nsg commission` to post commissions. The Clockworks handles the rest via standing orders.
 
 ## Tools
 
@@ -68,7 +159,7 @@ Tools that animas wield during work. Each tool ships with instructions delivered
 
 - **install-tool** — install new tools, engines, or bundles into the guild
 - **remove-tool** — remove installed tools
-- **dispatch** — post and dispatch commissions
+- **commission** — post commissions to the guild
 - **instantiate** — create new animas with assigned training and roles
 - **nexus-version** — report the installed Nexus framework version
 - **signal** — signal a custom guild event for the Clockworks
@@ -86,6 +177,9 @@ Automated mechanical processes with no AI involvement. Two kinds:
 
 **Clockwork engines** — purpose-built to respond to events via standing orders. Use the `engine()` SDK factory from `@shardworks/nexus-core`. The Clockworks runner calls them automatically when matching events fire.
 
+- **workshop-prepare** — creates a worktree when a commission is posted (`commission.posted` → `commission.ready`)
+- **workshop-merge** — merges a commission branch after the session ends (`commission.session.ended` → `commission.completed` or `commission.failed`)
+
 ## The Codex
 
 The guild's institutional body of policy and procedure — the employee handbook. Lives in `codex/` in the guildhall. Every anima receives the codex when manifested. The codex defines how the guild operates: standards, procedures, policies, and environmental facts.
@@ -240,6 +334,36 @@ Named, versioned, immutable personality templates. A temperament defines who an
 
 Training content lives in `training/curricula/` and `training/temperaments/` in the guildhall, organized as `{name}/{version}/`.
 
+## Guild Restore
+
+When the guildhall repository is cloned fresh onto a new machine (or by a new developer), the `.nexus/` directory does not exist — it is gitignored. The guild's configuration and code are all tracked in git, but runtime state needs to be reconstructed.
+
+```
+nsg guild restore
+```
+
+This command reconstructs all ephemeral runtime state from the tracked guild configuration:
+
+1. **Workshops** — re-clones all workshop bare repos from their `remoteUrl` in `guild.json`. Skips any that are already present.
+2. **npm dependencies** — runs `npm install` to restore packages from `package.json`.
+3. **On-disk tools** — reinstalls tools that have full source tracked in the guildhall.
+4. **Reports linked tools** — lists any tools that were npm-linked and need manual re-linking (since symlinks don't survive a clone).
+
+The command is idempotent — safe to run at any time. If everything is already in place, it reports "Nothing to restore."
+
+### When to Run Restore
+
+- After cloning the guildhall repo for the first time
+- After pulling changes that added new workshops
+- If a bare clone is corrupted or accidentally deleted
+- When `nsg workshop list` shows ✗ (missing bare clone) for any workshop
+
+### What Restore Does NOT Do
+
+- It does not create the Ledger (that's done by `nsg init` and the ledger-migrate engine)
+- It does not re-create animas or commissions — those live in the Ledger
+- It does not push or pull workshop repos — it only clones them fresh if missing
+
 ## CLI Reference
 
 The primary interface is the `nsg` command:
@@ -247,9 +371,14 @@ The primary interface is the `nsg` command:
 | Command | Purpose |
 |---------|---------|
 | `nsg init` | Create a new guild |
-| `nsg dispatch <content>` | Post and dispatch a commission |
+| `nsg commission <spec> --workshop <name>` | Post a commission |
 | `nsg tool install <source>` | Install a tool or bundle |
 | `nsg tool remove <name>` | Remove an installed tool |
+| `nsg workshop add <url>` | Clone a remote repo and register it as a workshop |
+| `nsg workshop remove <name>` | Remove a workshop |
+| `nsg workshop list` | List workshops with status |
+| `nsg workshop create <org/name>` | Create a new GitHub repo and register as a workshop |
+| `nsg guild restore` | Restore runtime state after a fresh clone |
 | `nsg anima create` | Instantiate a new anima |
 | `nsg anima manifest <name>` | Generate an anima's full instructions |
 | `nsg status` | Show guild status |

package/migrations/003-commission-status-reason.sql

@@ -0,0 +1,5 @@
+-- Add status_reason to commissions for tracking why each state transition happened.
+-- Every status change should include a reason: "posted by patron", "merged to main",
+-- "merge conflict in src/foo.ts", etc.
+
+ALTER TABLE commissions ADD COLUMN status_reason TEXT;

package/nexus-bundle.json

@@ -3,7 +3,7 @@
   "tools": [
     { "package": "@shardworks/tool-install@0.x", "name": "install-tool" },
     { "package": "@shardworks/tool-remove@0.x", "name": "remove-tool" },
-    { "package": "@shardworks/tool-dispatch@0.x", "name": "dispatch" },
+    { "package": "@shardworks/tool-commission@0.x", "name": "commission" },
     { "package": "@shardworks/tool-instantiate@0.x", "name": "instantiate" },
     { "package": "@shardworks/tool-nexus-version@0.x", "name": "nexus-version" }
   ],
@@ -11,15 +11,20 @@
     { "package": "@shardworks/engine-manifest@0.x", "name": "manifest" },
     { "package": "@shardworks/engine-mcp-server@0.x", "name": "mcp-server" },
     { "package": "@shardworks/engine-worktree-setup@0.x", "name": "worktree-setup" },
+    { "package": "@shardworks/engine-workshop-prepare@0.x", "name": "workshop-prepare" },
+    { "package": "@shardworks/engine-workshop-merge@0.x", "name": "workshop-merge" },
     { "package": "@shardworks/engine-ledger-migrate@0.x", "name": "ledger-migrate" }
   ],
   "temperaments": [
-    { "path": "temperaments/guide" }
+    { "path": "temperaments/guide" },
+    { "path": "temperaments/artisan" }
   ],
   "curricula": [
     { "path": "curricula/guild-operations" }
   ],
   "migrations": [
-    { "path": "migrations/001-initial-schema.sql" }
+    { "path": "migrations/001-initial-schema.sql" },
+    { "path": "migrations/002-clockworks.sql" },
+    { "path": "migrations/003-commission-status-reason.sql" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/guild-starter-kit",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Default bundle for new Nexus guilds — tools, training, and migrations",
   "repository": {
     "type": "git",

package/temperaments/artisan/content.md

@@ -0,0 +1,23 @@
+# Artisan Temperament
+
+You are an artisan — methodical, resourceful, and focused on delivering solid work. You take pride in craft, not in flash.
+
+## Disposition
+
+- **Pragmatic.** Favor working solutions over elegant abstractions. Get something real running, then refine. Don't gold-plate.
+- **Self-directed.** Once you have a clear brief, work independently. Make decisions within scope without asking permission for every detail. Use your judgment — that's why you were commissioned.
+- **Thorough.** Test your work. Check edge cases. Read the error messages. Don't declare something done until you've verified it works, not just that it compiles.
+- **Honest about problems.** If something isn't working, say so early. If the brief is unclear or contradictory, surface it rather than guessing. A well-timed question saves more time than a wrong assumption.
+
+## Communication Style
+
+- Be concise. Commit messages and code comments are your primary output — make them clear and useful for the next anima who reads them.
+- When reporting status, lead with what's done and what's blocked. Skip the preamble.
+- If you encounter a design decision outside your brief, flag it and move on. Don't block on decisions that aren't yours to make.
+
+## Work Ethic
+
+- Commit early and often. Small, atomic commits that tell a clear story.
+- Leave the workshop cleaner than you found it. No dead code, no dangling TODOs, no mystery files.
+- Respect the scope of your commission. Do the work you were asked to do. If you see adjacent improvements, note them — don't chase them.
+- When sage advice is provided, follow it. The sage planned the work; you execute the plan. If you believe the plan has a flaw, record your concern, but do not contradict it unilaterally.

package/temperaments/artisan/nexus-temperament.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "content": "content.md"
+}