@drawbridge/drawbridge-agents 0.1.0 → 0.1.2

package/README.md

@@ -86,12 +86,15 @@ Beyond the conventions, this package gives agents cross-repo visibility and keep
 and the knowledge graph from drifting. Everything below is committed **only in this repo** and
 reaches consumers without committing anything to them (see "Isolation").
 
-- **Family knowledge graph (Graphify).** `npx drawbridge-agents-graph` extracts every
-  `drawbridge-*` repo plus `drawbridge-docs` and the shared packages into one queryable graph.
-  Agents query it (via the graphify MCP) instead of grepping. The runtime is a per-machine
-  Python tool — `npm run sync` installs it automatically (`bin/preflight-graphify.js`); set
-  `DRAWBRIDGE_SKIP_GRAPHIFY=1` to skip in CI/headless. First-run note: confirm graphify's exact
-  `extract` / `merge-graphs` / `install` flags against the installed tool (see `bin/graph.js`).
+- **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
+  location `drawbridge-docs/knowledge/graphs/global.json`. Agents query it with the `graphify` CLI
+  (e.g. `graphify query "…" --graph ../drawbridge-docs/knowledge/graphs/global.json`) instead of
+  grepping; refreshing is rebuild + commit in docs + `git pull` (no npm/publish cycle). The
+  runtime is a per-machine Python tool — `npm run sync` installs it
+  (`bin/preflight-graphify.js`); set `DRAWBRIDGE_SKIP_GRAPHIFY=1` to skip in CI/headless. We
+  deliberately do **not** run `graphify install` (it would rewrite `CLAUDE.md`); the optional
+  `graphify-mcp` server is available if you prefer MCP.
 - **Docs linkage + validator.** Feature code carries `@story <domain>/<slug>` / `@doc
   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
@@ -107,7 +110,8 @@ reaches consumers without committing anything to them (see "Isolation").
 ### Isolation (nothing ships to DigitalOcean)
 
 - The package is a **devDependency** → not installed in production.
-- The graphify MCP is delivered via the consumer's `.mcp.json` (already gitignored).
+- 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.

package/bin/graph.js

@@ -1,18 +1,35 @@
 #!/usr/bin/env node
-// Builds the family knowledge graph: extracts every drawbridge-* repo (plus drawbridge-docs and
-// the shared @drawbridge/* packages) into graphify's registry, merges them into
-// graph/merged.json, and writes graph/manifest.json (which the drift hook reads for staleness).
-// Requires the graphify runtime (npm run sync installs it). See conventions/graphify.md.
+// Builds the family knowledge graph: runs graphify's headless AST extraction over every
+// drawbridge-* repo (plus drawbridge-docs and the shared @drawbridge/* packages) into graphify's
+// global graph, then copies it to drawbridge-docs/knowledge/graphs/global.json — the committed,
+// shared graph agents query. Code-only (local AST, no API key). See conventions/graphify.md.
 //
-// NOTE: the exact graphify subcommand flags (extract/merge-graphs) should be confirmed against
-// the installed tool the first time this runs; adjust if graphify's CLI differs.
+// A semantic build (adds doc/paper content + INFERRED edges) needs an LLM backend: drop
+// --code-only and set an API key (e.g. ANTHROPIC_API_KEY) — slower and costs LLM calls.
 const fs = require('fs')
+const os = require('os')
 const path = require('path')
 const { execFileSync } = require('child_process')
 
 const packageRoot = path.resolve(__dirname, '..')
-const graphDir = path.join(packageRoot, 'graph')
-const familyRoot = path.resolve(packageRoot, '..')
+const buildDir = path.join(os.homedir(), '.graphify', 'build')
+const globalGraph = path.join(os.homedir(), '.graphify', 'global-graph.json')
+
+// The family root is the directory that contains drawbridge-docs. Walk up from cwd so this works
+// whether run from the agents repo or via npx from inside a consumer's node_modules.
+const findFamilyRoot = () => {
+  let dir = process.env.INIT_CWD || process.cwd()
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'drawbridge-docs'))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return path.resolve(packageRoot, '..')
+}
+
+const familyRoot = findFamilyRoot()
+const docsGraph = path.join(familyRoot, 'drawbridge-docs', 'knowledge', 'graphs', 'global.json')
 
 // The canonical family list lives in the shared settings template — single source of truth.
 const settings = JSON.parse(fs.readFileSync(path.join(packageRoot, '.claude-template', 'settings.json'), 'utf8'))
@@ -34,7 +51,7 @@ if (!hasGraphify()) {
   process.exit(1)
 }
 
-fs.mkdirSync(graphDir, { recursive: true })
+fs.mkdirSync(buildDir, { recursive: true })
 
 const built = []
 for (const name of repos) {
@@ -44,17 +61,24 @@ for (const name of repos) {
     continue
   }
   console.log(`  extract ${ name }`)
-  execFileSync('graphify', [ 'extract', repoPath, '--global', '--as', name ], { stdio: 'inherit' })
+  // --out redirects the per-repo graphify-out/ away from the repo (keeps it clean);
+  // --global merges the result into ~/.graphify/global-graph.json under the --as tag.
+  execFileSync(
+    'graphify',
+    [ 'extract', repoPath, '--out', path.join(buildDir, name), '--global', '--as', name, '--code-only' ],
+    { stdio: 'inherit' }
+  )
+  // 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 })
   built.push(name)
 }
 
-const mergedPath = path.join(graphDir, 'merged.json')
-console.log('  merge -> graph/merged.json')
-execFileSync('graphify', [ 'merge-graphs', '--global', '--out', mergedPath ], { stdio: 'inherit' })
+// Publish the merged global graph to the committed, shared location in drawbridge-docs.
+fs.mkdirSync(path.dirname(docsGraph), { recursive: true })
+fs.copyFileSync(globalGraph, docsGraph)
 
-const manifest = {
-  builtAt: new Date().toISOString(),
-  repos: built
-}
-fs.writeFileSync(path.join(graphDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
-console.log(`drawbridge-agents-graph: built graph from ${ built.length } repo(s)`)
+console.log(`drawbridge-agents-graph: built cross-repo graph from ${ built.length } repo(s)`)
+console.log(`  written to: ${ docsGraph }`)
+console.log('  commit it in drawbridge-docs so the team shares one graph, then: git pull')
+console.log('  query it:   graphify query "<question>" --graph ' + docsGraph)

package/bin/preflight-graphify.js

@@ -48,11 +48,7 @@ if (!has('graphify')) {
   }
 }
 
-// Register the MCP server with the local assistant (idempotent).
-try {
-  execFileSync('graphify', [ 'install' ], { stdio: 'inherit' })
-} catch (error) {
-  console.warn('drawbridge-agents-sync: `graphify install` (MCP registration) failed — run it manually.')
-}
-
-console.log('drawbridge-agents-sync: graphify runtime ready')
+// Note: we deliberately do NOT run `graphify install` — it writes a graphify section into the
+// repo's CLAUDE.md and a PreToolUse hook, which would mutate a committed file and clash with the
+// shared CLAUDE.md. Agents use the graphify CLI directly (see conventions/graphify.md).
+console.log('drawbridge-agents-sync: graphify runtime ready (run `npx drawbridge-agents-graph` to build the graph)')

package/claude/CLAUDE.md

@@ -13,4 +13,6 @@
 @../conventions/sentry-sdk.md
 @../conventions/app-web-forms.md
 @../conventions/docs-linkage.md
+@../conventions/superpowers-docs.md
+@../conventions/git-branching.md
 @../conventions/graphify.md

package/conventions/git-branching.md

@@ -0,0 +1,19 @@
+# Branch naming (gitflow)
+
+Branches use the **full gitflow prefixes, always spelled out**. Never use abbreviations.
+
+| Prefix | Use |
+| --- | --- |
+| `feature/<name>` | New features / changes (branched from `develop`) |
+| `bugfix/<name>` | Non-urgent bug fixes |
+| `hotfix/<name>` | Urgent production fixes (branched from `main`) |
+| `release/<version>` | Release preparation |
+| `chore/<name>` | Maintenance — dependency bumps, config, cleanup |
+| `support/<name>` | Long-lived support branches |
+
+- **Never** abbreviate: no `feat/`, `fix/`, `ci/`, `docs/`, `refactor/`, etc. Use the full word
+  (`feature/`, `bugfix/`, `chore/`, …).
+- `<name>` is a short kebab-case description (e.g. `feature/ecosystem-knowledge-graphify`,
+  `chore/agents-devdep`).
+- Branch from `develop` for normal work (see the integration-branch convention); `main`-only
+  repos like `drawbridge-docs` branch from `main`.

package/conventions/graphify.md

@@ -6,32 +6,40 @@ shared packages — built by [Graphify](https://github.com/Graphify-Labs/graphif
 ## Query the graph before grepping across repos
 
 When you need to trace behaviour that spans repos (api ↔ sync ↔ stripe ↔ app-web, who emits an
-event, what depends on a package), **query the graph instead of grepping 16 directories**. It
-is exposed as an MCP server; you can also use the CLI:
+event, what depends on a package), **query the graph instead of grepping 16 directories**. The
+cross-repo graph is committed in drawbridge-docs at
+`drawbridge-docs/knowledge/graphs/global.json` — a sibling of every repo, so point the CLI at it:
 
 ```sh
-graphify query "what connects sync change streams to the billing meter?"
-graphify path "drawbridge-app-web" "drawbridge-stripe"
-graphify explain "closeDraw"
+graphify query "what connects sync change streams to the billing meter?" --graph ../drawbridge-docs/knowledge/graphs/global.json
+graphify path "drawbridge-app-web" "drawbridge-stripe" --graph ../drawbridge-docs/knowledge/graphs/global.json
+graphify explain "closeDraw" --graph ../drawbridge-docs/knowledge/graphs/global.json
+graphify affected "closeDraw" --graph ../drawbridge-docs/knowledge/graphs/global.json
 ```
 
-The graph spans all sibling repos plus `drawbridge-docs` and the `@drawbridge/*` packages, so a
-query resolves across the code **and** the specs/contracts layer.
+`git pull` in drawbridge-docs gets you the current shared graph. It spans all sibling repos
+(code, via local AST); a semantic build additionally pulls in doc prose and richer INFERRED
+edges — see "Refreshing it".
 
 ## Refreshing it
 
-The graph is as fresh as the last build. After a change that alters cross-repo structure,
-rebuild it:
+The graph is as fresh as the last committed build. After a change that alters cross-repo
+structure, rebuild and commit it:
 
 ```sh
-npx drawbridge-agents-graph
+npx drawbridge-agents-graph                       # rebuilds -> drawbridge-docs/knowledge/graphs/global.json
+cd ../drawbridge-docs && git add knowledge/graphs && git commit -m "chore: refresh knowledge graph"
 ```
 
-This re-extracts every repo and rebuilds the merged graph. The drift-check hook will remind you
-when tracked source has changed since the last build.
+Other developers just `git pull` drawbridge-docs. The drift-check hook nudges when tracked
+source has changed since the committed graph was last built. For a semantic build that also
+indexes docs, run `graphify extract <repo> --global --as <repo>` with an LLM backend / API key
+set (slower, costs LLM calls).
 
 ## Runtime
 
 Graphify is a per-machine Python tool; `npm run sync` installs it automatically (see the sync
-preflight). If it is ever missing, the drift hook blocks with install instructions — the runtime
-is required, not optional (set `DRAWBRIDGE_SKIP_GRAPHIFY=1` only in CI/headless environments).
+preflight — `uv tool install graphifyy`). Set `DRAWBRIDGE_SKIP_GRAPHIFY=1` to skip in CI/headless
+environments. The MCP server (`graphify-mcp <graph.json>`) is available if you prefer it, but is
+**not** auto-registered — `graphify install` would rewrite CLAUDE.md, which we keep managed by
+this package.

package/conventions/superpowers-docs.md

@@ -0,0 +1,19 @@
+# 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:
+
+```
+drawbridge-docs/docs/superpowers/plans/YYYY-MM-DD-<slug>.md
+drawbridge-docs/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
+  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.
+- 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
+  it**; it belongs in `.gitignore`.

package/graph/README.md

@@ -1,13 +1,14 @@
 # Family knowledge graph
 
-Generated artifacts — do not edit by hand. Produced by `npx drawbridge-agents-graph`
-(`bin/graph.js`), which extracts every `drawbridge-*` repo plus `drawbridge-docs` and the shared
-`@drawbridge/*` packages into a single [Graphify](https://github.com/Graphify-Labs/graphify)
-knowledge graph.
+The cross-repo knowledge graph is built by `npx drawbridge-agents-graph` (`bin/graph.js`), which
+runs [Graphify](https://github.com/Graphify-Labs/graphify) headless AST extraction over every
+`drawbridge-*` repo and writes the merged graph to the **committed, shared** location:
 
-- `merged.json` — the merged, queryable graph (served via the graphify MCP).
-- `manifest.json` — `{ builtAt, repos }`; the drift-check hook reads `builtAt` to tell when the
-  graph is stale relative to changed source.
+```
+drawbridge-docs/knowledge/graphs/global.json
+```
 
-Both are regenerated by the build script; they are gitignored until the first build populates
-them. See `conventions/graphify.md` for how agents query and refresh the graph.
+That committed file is what agents query (`--graph ../drawbridge-docs/knowledge/graphs/global.json`)
+and is shared via `git pull` — see `conventions/graphify.md`. There are no graph artifacts in
+this package directory; per-repo extraction output is redirected to `~/.graphify/build/` so it
+never litters the source repos.

package/hooks/drift-check.js

@@ -69,14 +69,13 @@ const run = () => {
   // 2. Graph freshness (non-blocking nudge) — a full re-extract is expensive, so alert rather
   //    than block on every edit turn. Flip to block() if you want it enforced hard.
   if (!skipGraph) {
-    const manifestPath = path.join(packageRoot, 'graph', 'manifest.json')
+    // The shared graph is committed in drawbridge-docs (a sibling of this repo).
+    const docsGraph = path.join(path.dirname(cwd), 'drawbridge-docs', 'knowledge', 'graphs', 'global.json')
     let builtAt = 0
-    if (fs.existsSync(manifestPath)) {
-      try {
-        builtAt = Date.parse(JSON.parse(fs.readFileSync(manifestPath, 'utf8')).builtAt) || 0
-      } catch (error) {
-        builtAt = 0
-      }
+    try {
+      builtAt = fs.statSync(docsGraph).mtimeMs
+    } catch (error) {
+      builtAt = 0
     }
     const stale = changedSource.some((file) => {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {