@shawaze/agentspace 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawaze Ahmer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# agentspace
+
+[![CI](https://github.com/irucsS-9/agentspace/actions/workflows/ci.yml/badge.svg)](https://github.com/irucsS-9/agentspace/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![npm](https://img.shields.io/npm/v/@shawaze/agentspace.svg)](https://www.npmjs.com/package/@shawaze/agentspace)
+
+**Scaffold an agent-native multi-repo workspace** — a coordination layer that sits
+above your sibling repositories and keeps them coherent for AI coding agents.
+
+```bash
+npx @shawaze/agentspace init     # interactive wizard → scaffold the workspace
+npx @shawaze/agentspace doctor   # mechanical health checks on a workspace
+```
+
+> Status: **v0.3.** Workspace reconstruction, the memory-bank wiki, the
+> enforcement pack, and the cross-repo contract layer all work today.
+
+---
+
+## Why this exists
+
+If you run a product as **several separate repositories** (a backend, a web app, a
+mobile client, shared libraries) — a *polyrepo*, not a monorepo — AI coding agents
+have a blind spot: an agent that changes an API in one repo can't see the consumers
+it just broke in another, and every session re-derives the same cross-repo context
+from scratch.
+
+`agentspace` is **not** a monorepo tool (Nx, Turborepo, pnpm workspaces). Those
+unify repos under one build. agentspace does the opposite: it leaves your repos
+independent and adds a thin **coordination layer above them** — a declarative
+manifest, an LLM-curated knowledge wiki, cross-repo contracts, and
+boundary-enforced agents — so the *set* of repos stays coherent for an agent
+without a human babysitting drift.
+
+It is the generalization of a hand-built workspace methodology into a reusable tool.
+
+## The four pillars
+
+| Pillar | What it gives you | Status |
+|---|---|---|
+| **Workspace reconstruction** | A declarative `manifest.yaml` + an idempotent `clone-repos.sh` that rebuilds the whole workspace on any machine. | ✅ v0.1 |
+| **LLM Wiki** (`memory-bank/`) | A [Karpathy-pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) knowledge base the agent curates as it works — citation discipline, staleness/size budgets, ingest/query/lint operations. | ✅ v0.1 (structure) |
+| **Cross-app contracts** (`openspec/`) | A prescriptive contract layer + propose/apply/archive lifecycle that fights contract drift across repos. | ✅ v0.3 |
+| **Agents + enforcement** | Boundary-enforced per-repo agents, a warm-until-warm Stop hook, a read-only cross-app reviewer. | ✅ v0.2 |
+
+The point isn't any single pillar — it's the **integrated discipline** where they
+reinforce each other.
+
+## Topology-aware by design
+
+`agentspace init` asks your **workspace shape** and only emits artifacts that shape
+warrants. A single repo, four peer microservices, a library + consumers, and a
+one-product/backend+clients workspace all get *different* output:
+
+- A **one-product** workspace gets cross-app contract scaffolding and a
+  product-scoped wiki.
+- A **single repo** or set of **unrelated repos** does **not** get a cross-app
+  contract layer, a cross-app reviewer, or a blocking hook — because none of that
+  applies.
+
+You never get a pile of cork-shaped scaffolding that doesn't fit your project.
+
+## What `init` generates today (v0.3)
+
+- `manifest.yaml` + a resilient `clone-repos.sh`
+- a `.gitignore` (sub-repos are independent git repos, ignored by the workspace)
+- a root `CLAUDE.md` router + `README.md`
+- a shape-aware `memory-bank/` wiki: numbered priority folders, a conventions
+  README, and seeded overview/contract stubs appropriate to your shape
+- (enforcement pillar, opt-in) a `.claude/` pack: per-repo boundary-enforced
+  agents, `/ingest` `/query` `/lint` commands, a warm-until-warm Stop hook, and
+  a cross-app reviewer (contract-linked shapes).
+- (contracts pillar, opt-in) an `openspec/` cross-repo contract layer — a
+  shape-aware `project.md` + `specs/`/`changes/`; the `/opsx:*` commands come
+  from the external `openspec` CLI (`openspec update`).
+
+## Quick start
+
+```bash
+npx @shawaze/agentspace init
+# answer: workspace name → shape → repos (name, remote, stack, role) → pillars
+./clone-repos.sh         # pull any sub-repos that aren't on disk yet
+npx @shawaze/agentspace doctor    # check workspace health (size budgets, staleness, manifest)
+```
+
+## Roadmap
+
+- More tool adapters (Cursor, Windsurf, …) via the same intent seam.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). The per-stack agent library is designed
+so adding support for a new stack is a single markdown file — issues and PRs welcome.
+
+## Development
+
+```bash
+npm install
+npm test          # vitest
+npm run typecheck
+npm run build     # tsup → dist/cli.js
+```
+
+## License
+
+[MIT](./LICENSE) © Shawaze Ahmer

package/assets/memory-bank-stop.cjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * agentspace Stop hook — keeps the memory bank current on cross-repo work.
+ * Dep-free (runs with bare node). Reads .claude/agentspace-hook.json for config.
+ * Pure helpers are exported when required (for tests); the file runs when executed.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MUTATING_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+const SEED_PAGES = new Set(['README.md', 'index.md', 'log.md', 'projectOverview.md', 'crossAppContracts.md']);
+
+/** Pure decision: allow | warn | block. */
+function decideStop({ mode, warm, crossAppMutation, memoryBankUpdated }) {
+  if (!crossAppMutation || memoryBankUpdated) return 'allow';
+  if (mode === 'warn') return 'warn';
+  if (mode === 'block') return 'block';
+  return warm ? 'block' : 'warn'; // auto
+}
+
+/** Pure: warm when pages OR sessions cross their thresholds. */
+function isWarm({ pages, sessions, warmPages, warmSessions }) {
+  return pages > warmPages || sessions >= warmSessions;
+}
+
+/** Count real (non-seed) memory-bank .md pages, recursively. */
+function countRealPages(mbDir) {
+  let count = 0;
+  function walk(dir) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.name.endsWith('.md') && !SEED_PAGES.has(e.name)) count++;
+    }
+  }
+  walk(mbDir);
+  return count;
+}
+
+function readState(stateFile) {
+  try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch { return { sessions: 0 }; }
+}
+
+function writeState(stateFile, state) {
+  try {
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+    fs.writeFileSync(stateFile, JSON.stringify(state));
+  } catch { /* best effort */ }
+}
+
+function main() {
+  let input = {};
+  try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }
+  if (input.stop_hook_active) process.exit(0);
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const mbDir = path.join(projectDir, 'memory-bank');
+  if (!fs.existsSync(mbDir)) process.exit(0);
+
+  const configFile = path.join(projectDir, '.claude', 'agentspace-hook.json');
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(configFile, 'utf8')); } catch { process.exit(0); }
+  const subRepos = Array.isArray(cfg.subRepos) ? cfg.subRepos : [];
+  const mode = (cfg.mode === 'warn' || cfg.mode === 'block') ? cfg.mode : 'auto';
+  const warmPages = typeof cfg.warmPages === 'number' ? cfg.warmPages : 5;
+  const warmSessions = typeof cfg.warmSessions === 'number' ? cfg.warmSessions : 10;
+
+  // Count this session (every Stop on a configured workspace).
+  const stateFile = path.join(projectDir, '.agentspace', 'state.json');
+  const state = readState(stateFile);
+  state.sessions = (state.sessions || 0) + 1;
+  writeState(stateFile, state);
+
+  // Inspect the transcript for mutating tool uses.
+  let mutationCount = 0;
+  const touched = new Set();
+  let memoryBankUpdated = false;
+  const tp = input.transcript_path;
+  let transcriptLines = [];
+  try {
+    if (tp && fs.existsSync(tp)) transcriptLines = fs.readFileSync(tp, 'utf8').split('\n');
+  } catch { /* best effort — treat as no transcript, fail open */ }
+  if (transcriptLines.length) {
+    for (const line of transcriptLines) {
+      if (!line.trim()) continue;
+      let evt; try { evt = JSON.parse(line); } catch { continue; }
+      const content = evt && evt.message && evt.message.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (!block || block.type !== 'tool_use' || !MUTATING_TOOLS.has(block.name)) continue;
+        mutationCount++;
+        const raw = (block.input && (block.input.file_path || block.input.notebook_path)) || '';
+        const rel = raw.startsWith(projectDir) ? raw.slice(projectDir.length + 1) : raw;
+        if (rel.startsWith('memory-bank/')) memoryBankUpdated = true;
+        for (const sub of subRepos) { if (rel.startsWith(sub + '/')) { touched.add(sub); break; } }
+      }
+    }
+  }
+
+  const crossAppMutation = mutationCount > 0 && touched.size >= 2;
+  const warm = isWarm({
+    pages: countRealPages(mbDir),
+    sessions: state.sessions,
+    warmPages,
+    warmSessions,
+  });
+  const decision = decideStop({ mode, warm, crossAppMutation, memoryBankUpdated });
+
+  if (decision === 'allow') process.exit(0);
+
+  const list = [...touched].sort().join(', ');
+  const reason = [
+    `Cross-repo activity detected (${list}) — update the memory bank before ending.`,
+    '1. Refresh memory-bank/01-active/currentWork.md (date + status).',
+    '2. Append one line to memory-bank/log.md: `## [YYYY-MM-DD] <action> | <slug>`.',
+    '3. If a cross-repo contract was touched, record it in memory-bank/00-core/crossAppContracts.md (cite `file:line`).',
+  ].join('\n');
+
+  if (decision === 'block') {
+    process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  } else {
+    // warn: surface a note but allow the stop.
+    process.stdout.write(JSON.stringify({ systemMessage: reason }));
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  try { main(); } catch { process.exit(0); }
+} else {
+  module.exports = { decideStop, isWarm, countRealPages, readState, writeState };
+}