@drawbridge/drawbridge-agents 0.1.1 → 0.1.3

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

@@ -87,13 +87,14 @@ and the knowledge graph from drifting. Everything below is committed **only in t
 reaches consumers without committing anything to them (see "Isolation").
 
 - **Family knowledge graph (Graphify).** `npx drawbridge-agents-graph` runs code-only AST
-  extraction over every `drawbridge-*` repo and merges them into the cross-repo graph at
-  `~/.graphify/global-graph.json`. Agents query it with the `graphify` CLI (e.g.
-  `graphify query "…" --graph ~/.graphify/global-graph.json`) instead of grepping. 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.
+  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

package/bin/graph.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // Builds the family knowledge graph: runs graphify's headless AST extraction over every
-// drawbridge-* repo (plus drawbridge-docs and the shared @drawbridge/* packages) and merges
-// each into the global cross-repo graph at ~/.graphify/global-graph.json — which is what agents
-// query. Code-only (local AST, no API key). See conventions/graphify.md.
+// 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.
 //
 // 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.
@@ -12,8 +12,24 @@ const path = require('path')
 const { execFileSync } = require('child_process')
 
 const packageRoot = path.resolve(__dirname, '..')
-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'))
@@ -52,10 +68,17 @@ for (const name of repos) {
     [ '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 globalGraph = path.join(os.homedir(), '.graphify', 'global-graph.json')
+// Publish the merged global graph to the committed, shared location in drawbridge-docs.
+fs.mkdirSync(path.dirname(docsGraph), { recursive: true })
+fs.copyFileSync(globalGraph, docsGraph)
+
 console.log(`drawbridge-agents-graph: built cross-repo graph from ${ built.length } repo(s)`)
-console.log(`  global graph: ${ globalGraph }`)
-console.log('  query it:     graphify query "<question>" --graph ' + globalGraph)
+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/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

@@ -7,31 +7,34 @@ shared packages — built by [Graphify](https://github.com/Graphify-Labs/graphif
 
 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**. The
-cross-repo graph lives at `~/.graphify/global-graph.json`; point the CLI at it with `--graph`:
+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?" --graph ~/.graphify/global-graph.json
-graphify path "drawbridge-app-web" "drawbridge-stripe" --graph ~/.graphify/global-graph.json
-graphify explain "closeDraw" --graph ~/.graphify/global-graph.json
-graphify affected "closeDraw" --graph ~/.graphify/global-graph.json
+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 (code, via local AST). A semantic build additionally pulls in
-`drawbridge-docs` and richer INFERRED edges — see "Refreshing it".
+`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 (code-only, no API key) and merges them into the global graph. The
-drift-check hook nudges when tracked source has changed since the last build. 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).
+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
 

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, at the **root** of drawbridge-docs:
+
+```
+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 superpowers plans/specs (or `docs/superpowers/`, `docs/plans/`)
+  inside any other repo. When you finalize a plan or spec, write it under
+  `../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
+  it**; it belongs in `.gitignore`.

package/graph/README.md

@@ -2,9 +2,13 @@
 
 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 merges each into the **global** graph at
-`~/.graphify/global-graph.json` (per machine, not committed).
+`drawbridge-*` repo and writes the merged graph to the **committed, shared** location:
 
-That global graph is what agents query — see `conventions/graphify.md`. There are no committed
-artifacts in this directory; it holds this README only. Per-repo extraction output is redirected
-to `~/.graphify/build/` so it never litters the source repos.
+```
+drawbridge-docs/knowledge/graphs/global.json
+```
+
+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

@@ -3,7 +3,6 @@
 // Blocks (must fix) on unresolved @story/@doc tags; nudges (non-blocking) on a stale graph or
 // likely doc drift. Gated so it never fires on trivial turns. See conventions/docs-linkage.md.
 const fs = require('fs')
-const os = require('os')
 const path = require('path')
 const { execFileSync } = require('child_process')
 
@@ -70,10 +69,11 @@ 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 globalGraph = path.join(os.homedir(), '.graphify', 'global-graph.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
     try {
-      builtAt = fs.statSync(globalGraph).mtimeMs
+      builtAt = fs.statSync(docsGraph).mtimeMs
     } catch (error) {
       builtAt = 0
     }

package/package.json

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