@shawaze/agentspace 0.3.0 → 0.3.1

package/README.md

@@ -8,16 +8,13 @@
 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 init     # interactive wizard → scaffold a 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
+## Why agentspace
 
 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
@@ -25,76 +22,149 @@ have a blind spot: an agent that changes an API in one repo can't see the consum
 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
+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.
+## What it gives you
+
+| Pillar | What it does |
+|---|---|
+| **Workspace reconstruction** | A declarative `manifest.yaml` + an idempotent `clone-repos.sh` that rebuilds the whole workspace on any machine. |
+| **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, and `/ingest` `/query` `/lint` operations. |
+| **Cross-repo contracts** (`openspec/`) | A prescriptive contract layer with a propose → apply → archive lifecycle that fights contract drift across repos. |
+| **Agents & enforcement** (`.claude/`) | Boundary-enforced per-repo agents, a read-only cross-app reviewer, and a Stop hook that nudges you to keep the wiki current. |
+
+The value isn't any single pillar — it's the **integrated discipline** where they
+reinforce each other. Pick the ones you want; the manifest is always included and
+the wiki is on by default.
 
-## The four pillars
+## Topology-aware
 
-| 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 |
+`init` asks your **workspace shape** and only emits artifacts that shape warrants.
+A single repo, four peer microservices, a library + consumers, and a
+backend-plus-clients product all get *different* output:
 
-The point isn't any single pillar — it's the **integrated discipline** where they
-reinforce each other.
+- A **one-product** workspace gets the cross-repo contract layer, a cross-app
+  reviewer, and a blocking Stop hook.
+- A **single repo** or set of **unrelated repos** does **not** — because none of
+  that applies.
 
-## Topology-aware by design
+You never get a pile of scaffolding that doesn't fit your project.
 
-`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:
+## Requirements
 
-- 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.
+- **Node.js 18+** (to run the CLI).
+- **[Claude Code](https://claude.ai/code)** — to use the generated `.claude/`
+  enforcement pack (agents, hook, slash commands). The other pillars are plain
+  files usable with any agent or none.
+- **[OpenSpec CLI](https://github.com/Fission-AI/OpenSpec)** *(optional)* — only
+  if you enable the contracts pillar and want the `/opsx:*` slash commands and
+  validation. agentspace scaffolds the `openspec/` structure either way.
 
-You never get a pile of cork-shaped scaffolding that doesn't fit your project.
+## Usage
 
-## What `init` generates today (v0.3)
+### `agentspace init`
 
-- `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`).
+Runs an interactive wizard, then writes the workspace into the current directory.
+It asks:
 
-## Quick start
+1. **Workspace name**
+2. **Shape** — single-repo · one product (backend + clients) · peer services ·
+   library + consumers · unrelated
+3. **Per repo** — directory name, git remote (or local-only), stack, and role
+4. **Dependency order** — for ordered shapes (which repo defines contracts others
+   consume)
+5. **Pillars** — the wiki, the enforcement pack, and the contract layer are each
+   opt-in (the manifest is always written)
 
 ```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)
+./clone-repos.sh   # clone any sub-repos not yet on disk (idempotent)
+```
+
+It refuses to write into a non-empty directory unless you pass `--force`, and
+`--dry-run` prints what it would write without touching disk.
+
+### `agentspace doctor`
+
+Mechanical health checks on a generated workspace — manifest validity,
+memory-bank size budgets, `_Last verified:_` staleness, and (when the contracts
+pillar is present) whether the `openspec` CLI is installed.
+
+```bash
+npx @shawaze/agentspace doctor          # human-readable
+npx @shawaze/agentspace doctor --lint    # machine-readable JSON (used by /lint)
 ```
 
-## Roadmap
+## What gets generated
 
-- More tool adapters (Cursor, Windsurf, …) via the same intent seam.
+A full-featured workspace looks like this:
+
+```
+my-workspace/
+├── manifest.yaml            # source of truth for the repos
+├── clone-repos.sh           # rebuild the workspace anywhere
+├── CLAUDE.md · README.md    # routers/overview
+├── .gitignore               # sub-repos are independent git repos, ignored here
+├── memory-bank/             # the LLM wiki (numbered priority folders + conventions)
+├── openspec/                # contracts pillar — project.md + specs/ + changes/
+└── .claude/                 # enforcement pillar
+    ├── agents/              # one <repo>-engineer per repo + cross-app-reviewer
+    ├── commands/            # /ingest /query /lint
+    ├── hooks/               # the Stop hook
+    └── settings.json
+```
+
+Each generated `<repo>-engineer` agent has a **hard path boundary** (it may only
+edit its own repo) and stack-tailored guidance, with a "project specifics" section
+for you to fill in. The cross-app reviewer is read-only.
+
+## Configuring the Stop hook
+
+When the enforcement pillar is on, the Stop hook keeps your wiki current on
+genuine cross-repo work. It is configured in `manifest.yaml`:
+
+```yaml
+enforcement:
+  mode: auto        # auto | warn | block
+  warmPages: 5      # "warm" once the wiki has more than N real pages …
+  warmSessions: 10  # … OR after M sessions
+```
+
+It only acts when a session edits **two or more** contract-linked repos **without**
+updating `memory-bank/`. In `auto` mode it **warns** until the workspace is "warm"
+(you've invested in the wiki), then **blocks**. `warn` always warns; `block`
+always blocks. It fails open — a misconfigured or missing setup never blocks you.
+
+## The contract layer
+
+If you enable the contracts pillar, agentspace writes a shape-aware
+`openspec/project.md` (scope rules, your repo table, the contract lifecycle, and a
+dependency order when one applies) plus empty `specs/` and `changes/`. The
+`/opsx:*` slash commands and validation come from the external `openspec` CLI:
+
+```bash
+openspec update     # installs the /opsx:* commands into .claude/
+openspec validate   # check specs/changes
+```
 
-## Contributing
+## The stack-agent library
 
-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.
+Generated engineer agents are built from a library of stack templates
+(`stack-agents/`): Rails, Next.js, Expo, Go, Django, Spring Boot, plus a generic
+fallback for anything else. Adding support for a new stack is **one markdown file +
+one registry row** — see [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and PRs
+welcome.
 
 ## Development
 
 ```bash
+git clone https://github.com/irucsS-9/agentspace.git
+cd agentspace
 npm install
 npm test          # vitest
 npm run typecheck

package/dist/cli.js

@@ -1030,7 +1030,7 @@ async function doctorCommand(workspaceDir, today, opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.3.1";
 
 // src/cli.ts
 function parseArgs(argv) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shawaze/agentspace",
   "publishConfig": { "access": "public" },
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Scaffold an agent-native multi-repo workspace — keep sibling repos coherent for AI coding agents",
   "type": "module",
   "bin": { "agentspace": "dist/cli.js" },