@drawbridge/drawbridge-agents 0.1.2 → 0.1.4

package/.claude-template/settings.json

@@ -25,6 +25,7 @@
       "../drawbridge-redis",
       "../drawbridge-share",
       "../drawbridge-shopify",
+      "../drawbridge-shopify-app",
       "../drawbridge-stripe",
       "../drawbridge-sync",
       "../drawbridge-telemetry",
@@ -32,5 +33,18 @@
       "../drawbridge-webhooks",
       "../drawbridge-website"
     ]
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./node_modules/@drawbridge/drawbridge-agents/hooks/drift-check.js"
+          }
+        ]
+      }
+    ]
   }
 }

package/.root-template/.mcp.json

@@ -3,6 +3,10 @@
     "sentry": {
       "type": "http",
       "url": "https://mcp.sentry.dev/mcp"
+    },
+    "asana": {
+      "type": "sse",
+      "url": "https://mcp.asana.com/sse"
     }
   }
 }

package/README.md

@@ -19,16 +19,17 @@ conventions/                ← canonical, agent-neutral content (@-imported int
 claude/
   CLAUDE.md                 ← aggregator — @-imports every conventions/*.md
 
-.claude-template/           ← mirrored into each consumer repo's .claude/
-  settings.json             ← shared permissions/env
+.claude-template/           ← the complete shared .claude/, mirrored into each consumer repo
+  settings.json             ← permissions, additionalDirectories, drift-check Stop hook
+  skills/                   ← shared skills (drawbridge-ship-feature, -asana-ship-handoff, ...)
   hooks/  agents/  commands/
 
 .root-template/             ← mirrored into each consumer repo's root
-  .mcp.json                 ← project-level MCP servers (e.g. Sentry) — gitignored in consumers
+  .mcp.json                 ← project-level MCP servers (Sentry, Asana)
   .editorconfig             ← family-wide editor defaults (tabs, lf, utf-8)
 
 bin/
-  sync-claude.js            ← drawbridge-agents-sync — mirrors templates + installs hook/skills + graphify preflight
+  sync-claude.js            ← drawbridge-agents-sync — mirrors templates + graphify preflight
   graph.js                  ← drawbridge-agents-graph — builds the merged family knowledge graph
   preflight-graphify.js     ← ensures the graphify runtime is installed (called by sync)
 
@@ -36,13 +37,7 @@ scripts/
   check-doc-links.js        ← drawbridge-agents-check-docs — validates @story/@doc tags resolve
 
 hooks/
-  drift-check.js            ← Stop hook — blocks on unresolved doc tags, nudges on stale graph
-
-skills/                     ← shared skills, installed to user-level ~/.claude/skills on sync
-  drawbridge-asana-ship-handoff/  drawbridge-ship-feature/
-  drawbridge-explore-ecosystem/   drawbridge-record-contract/
-
-graph/                      ← generated (gitignored) merged.json + manifest.json; see graph/README.md
+  drift-check.js            ← Stop hook (wired via .claude-template/settings.json)
 ```
 
 ## Consuming from a drawbridge-* repo
@@ -72,19 +67,23 @@ graph/                      ← generated (gitignored) merged.json + manifest.js
    "sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install && npx drawbridge-agents-sync"
    ```
 
-   On every `npm run sync`, this package mirrors:
-   - `.claude-template/` → consumer's `.claude/`
+   On every `npm run sync`, this package mirrors the single source of truth into the consumer:
+   - `.claude-template/` → consumer's `.claude/` — the **complete** shared setup: `settings.json`
+     (permissions, `additionalDirectories`, the drift-check Stop hook), plus `skills/`,
+     `agents/`, `commands/`, `hooks/`.
    - `.root-template/` → consumer's repo root (`.mcp.json`, `.editorconfig`)
 
-   Paths that exist in the templates are **managed** (overwritten on each sync). Anything else in `.claude/` or at the repo root — including `settings.local.json` and any consumer-only hooks/agents/commands — is left untouched.
+   Paths that exist in the templates are **managed** (overwritten on each sync) — every repo ends
+   up with an identical `.claude/`. Only `settings.local.json` (each dev's personal overrides) and
+   any consumer-only files are left untouched.
 
 Claude Code's `@` imports cascade — one import line resolves the whole tree under `claude/CLAUDE.md`.
 
 ## Ecosystem knowledge, graph, and drift checks
 
 Beyond the conventions, this package gives agents cross-repo visibility and keeps code, docs,
-and the knowledge graph from drifting. Everything below is committed **only in this repo** and
-reaches consumers without committing anything to them (see "Isolation").
+and the knowledge graph from drifting. This package is the single source; each repo gets an
+identical copy via the sync mirror (see "Delivery model").
 
 - **Family knowledge graph (Graphify).** `npx drawbridge-agents-graph` runs code-only AST
   extraction over every `drawbridge-*` repo and writes the merged graph to the committed, shared
@@ -99,24 +98,28 @@ reaches consumers without committing anything to them (see "Isolation").
   reference/<file>#<anchor>` anchors (see `conventions/docs-linkage.md`).
   `npx drawbridge-agents-check-docs` scans every repo and fails if any anchor no longer resolves
   against `drawbridge-docs`.
-- **Drift-check Stop hook.** `hooks/drift-check.js` runs at each task-turn end (installed into the
-  consumer's gitignored `.claude/settings.local.json`). It **blocks** on an unresolved doc
-  anchor, and **nudges** (non-blocking) when the graph looks stale or docs may need updating. It
-  skips plan-mode and turns with no source changes.
-- **Shared skills.** Installed to user-level `~/.claude/skills/` on sync:
+- **Drift-check Stop hook.** `hooks/drift-check.js` runs at each task-turn end, wired via the
+  drift-check `Stop` hook in the mirrored `.claude/settings.json`. It **blocks** on an unresolved
+  doc anchor, and **nudges** (non-blocking) when the graph looks stale or docs may need updating.
+  It skips plan-mode and turns with no source changes.
+- **Shared skills.** Mirrored into every repo's `.claude/skills/` (from `.claude-template/skills/`):
   `drawbridge-ship-feature` (verify → docs → graph → handoff), `drawbridge-asana-ship-handoff`,
   `drawbridge-explore-ecosystem`, `drawbridge-record-contract`.
 
-### Isolation (nothing ships to DigitalOcean)
+### Delivery model
 
-- The package is a **devDependency** → not installed in production.
-- The graph and CLI are per-machine (`~/.graphify/`); nothing graph-related is written into the
-  consumer repo, and `graphify install` (which edits `CLAUDE.md`) is never run.
-- The Stop hook is merged into `.claude/settings.local.json` (gitignored).
-- Skills install to `~/.claude/skills/` (per-machine, outside any repo).
-- The only in-repo footprint in consumers is inert `@story`/`@doc` source comments.
+Every repo has an **identical, normalized** agent setup, all sourced from this one package:
 
-After `npm run sync`, `git status` in a consumer should show **no new tracked files**.
+- **`CLAUDE.md`** → one-line `@import` (live from `node_modules`).
+- **`.claude/`** (settings.json + permissions + hook, skills, agents/commands/hooks) → **mirrored**
+  from `.claude-template/` and committed per repo.
+- **`.mcp.json`, `.editorconfig`** → mirrored from `.root-template/` and committed per repo.
+- Config files (`.claude/`, `.mcp.json`) are copied rather than imported because only markdown
+  (`CLAUDE.md`) supports `@import`; the mirror keeps the copies identical from one source.
+- The package is a **devDependency** → never installed in production / on DigitalOcean.
+- The knowledge graph is committed once in `drawbridge-docs/knowledge/graphs/`; the graphify
+  runtime + build cache are per-machine under `~/.graphify/` (gitignored). `graphify install`
+  (which edits `CLAUDE.md`) is never run.
 
 ## Updating a rule or shared `.claude/` file
 

package/bin/graph.js

@@ -70,7 +70,11 @@ for (const name of repos) {
   )
   // graphify still drops a graphify-out/ in the target repo despite --out; remove it so the
   // build never dirties a source repo (the incremental cache lives under ~/.graphify/build).
-  fs.rmSync(path.join(repoPath, 'graphify-out'), { recursive: true, force: true })
+  const stray = path.join(repoPath, 'graphify-out')
+  if (fs.existsSync(stray)) {
+    if (fs.rmSync) fs.rmSync(stray, { recursive: true, force: true })
+    else fs.rmdirSync(stray, { recursive: true })
+  }
   built.push(name)
 }
 

package/bin/sync-claude.js

@@ -7,6 +7,13 @@ const { execFileSync } = require('child_process')
 const consumerRoot = process.env.INIT_CWD || process.cwd()
 const packageRoot = path.resolve(__dirname, '..')
 
+// Recursive remove that works on Node 12+ (fs.rmSync is 14.14+).
+const rmrf = (p) => {
+  if (!fs.existsSync(p)) return
+  if (fs.rmSync) fs.rmSync(p, { recursive: true, force: true })
+  else fs.rmdirSync(p, { recursive: true })
+}
+
 const copied = []
 
 const mirror = (src, dst) => {
@@ -23,7 +30,9 @@ const mirror = (src, dst) => {
   }
 }
 
-// 1. Mirror the committed template dirs into the consumer (existing behaviour).
+// 1. Mirror the single source of truth into the consumer. .claude-template holds the entire
+//    shared .claude/ setup (settings.json incl. permissions + the drift-check Stop hook, plus
+//    agents/commands/hooks/skills); .root-template holds root files (.mcp.json, .editorconfig).
 const mirrorTemplates = () => {
   const targets = [
     { src: path.join(packageRoot, '.claude-template'), dst: path.join(consumerRoot, '.claude'), required: true },
@@ -40,63 +49,42 @@ const mirrorTemplates = () => {
     mirror(src, dst)
   }
   console.log(`drawbridge-agents-sync: ${ copied.length } file(s) mirrored`)
-  for (const p of copied) console.log(`  ${ p }`)
 }
 
-// 2. Merge the drift-check Stop hook into the consumer's gitignored .claude/settings.local.json,
-//    so nothing is committed to the consumer repo (see conventions/docs-linkage.md).
-const installStopHook = () => {
-  const command = 'node ./node_modules/@drawbridge/drawbridge-agents/hooks/drift-check.js'
-  const settingsPath = path.join(consumerRoot, '.claude', 'settings.local.json')
-
-  let settings = {}
-  if (fs.existsSync(settingsPath)) {
+// 2. Migration cleanup from the previous delivery model: the drift hook used to be merged into
+//    the gitignored settings.local.json and skills installed to user-level ~/.claude/skills.
+//    Both now ship via the mirror above, so remove the old copies to avoid duplicates.
+const migrateOldDelivery = () => {
+  const localSettings = path.join(consumerRoot, '.claude', 'settings.local.json')
+  if (fs.existsSync(localSettings)) {
     try {
-      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'))
+      const settings = JSON.parse(fs.readFileSync(localSettings, 'utf8'))
+      if (settings.hooks && Array.isArray(settings.hooks.Stop)) {
+        settings.hooks.Stop = settings.hooks.Stop.filter((entry) =>
+          !(entry.hooks || []).some((hook) => typeof hook.command === 'string' && hook.command.includes('drawbridge-agents/hooks/drift-check.js'))
+        )
+        if (settings.hooks.Stop.length === 0) delete settings.hooks.Stop
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks
+        fs.writeFileSync(localSettings, JSON.stringify(settings, null, 2) + '\n')
+      }
     } catch (error) {
-      console.warn('drawbridge-agents-sync: could not parse .claude/settings.local.json — leaving Stop hook uninstalled')
-      return
+      // leave settings.local.json untouched on parse trouble
     }
   }
 
-  settings.hooks = settings.hooks || {}
-  settings.hooks.Stop = settings.hooks.Stop || []
-
-  const already = settings.hooks.Stop.some((entry) =>
-    (entry.hooks || []).some((hook) => typeof hook.command === 'string' && hook.command.includes('drawbridge-agents/hooks/drift-check.js'))
-  )
-  if (already) return
-
-  settings.hooks.Stop.push({
-    matcher: '',
-    hooks: [ { type: 'command', command } ]
-  })
-  fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
-  console.log('drawbridge-agents-sync: drift-check Stop hook installed in .claude/settings.local.json')
-}
-
-// 3. Install the shared skills to the user-level ~/.claude/skills/ (per-machine, so nothing is
-//    committed to any consumer repo). Only drawbridge-* skills are managed.
-const installSkills = () => {
-  const src = path.join(packageRoot, 'skills')
-  if (!fs.existsSync(src)) return
-  const dst = path.join(os.homedir(), '.claude', 'skills')
-  let count = 0
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !entry.name.startsWith('drawbridge-')) continue
-    mirror(path.join(src, entry.name), path.join(dst, entry.name))
-    count += 1
+  const userSkills = path.join(os.homedir(), '.claude', 'skills')
+  if (fs.existsSync(userSkills)) {
+    for (const name of fs.readdirSync(userSkills)) {
+      if (name.startsWith('drawbridge-')) rmrf(path.join(userSkills, name))
+    }
   }
-  if (count > 0) console.log(`drawbridge-agents-sync: ${ count } shared skill(s) installed to ~/.claude/skills/`)
 }
 
-// 4. Ensure the graphify runtime is present + MCP registered (hard-fails if it can't be).
+// 3. Ensure the graphify runtime is present + reachable (hard-fails if it can't be).
 const graphifyPreflight = () => {
   execFileSync('node', [ path.join(packageRoot, 'bin', 'preflight-graphify.js') ], { stdio: 'inherit' })
 }
 
 mirrorTemplates()
-installStopHook()
-installSkills()
+migrateOldDelivery()
 graphifyPreflight()

package/conventions/superpowers-docs.md

@@ -1,18 +1,18 @@
 # Superpowers working docs live in drawbridge-docs
 
 All superpowers **plans** and **specs** — the outputs of the brainstorming / writing-plans /
-spec workflows — live in one canonical place:
+spec workflows — live in one canonical place, at the **root** of drawbridge-docs:
 
 ```
-drawbridge-docs/docs/superpowers/plans/YYYY-MM-DD-<slug>.md
-drawbridge-docs/docs/superpowers/specs/YYYY-MM-DD-<slug>.md
+drawbridge-docs/superpowers/plans/YYYY-MM-DD-<slug>.md
+drawbridge-docs/superpowers/specs/YYYY-MM-DD-<slug>.md
 ```
 
 This is the **only** allowed home for these working docs. Rules:
 
-- Do **not** create or keep `docs/superpowers/`, `docs/plans/`, or any plan/spec working docs
+- Do **not** create or keep superpowers plans/specs (or `docs/superpowers/`, `docs/plans/`)
   inside any other repo. When you finalize a plan or spec, write it under
-  `../drawbridge-docs/docs/superpowers/{plans,specs}/`, not the repo you're working in.
+  `../drawbridge-docs/superpowers/{plans,specs}/`, not the repo you're working in.
 - When plan mode or a superpowers skill produces a plan/spec, the finalized document goes into
   drawbridge-docs — regardless of which repo the work targets. Note the target repo in the doc.
 - `.superpowers/` (brainstorm scratch — server state, HTML mockups) is ephemeral. **Never commit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -23,7 +23,6 @@
     "bin",
     "hooks",
     "scripts",
-    "skills",
     "graph",
     "README.md"
   ],