@vectros-ai/blueprints 0.5.0 → 0.6.3

package/guides/agentic-sdlc.md

@@ -0,0 +1,238 @@
+# Guide — the `agentic-sdlc` blueprint
+
+`agentic-sdlc` is a bundled blueprint: a **whole-SDLC system of record**
+for an AI development team. It provisions **nine schemas, split by content vs
+structure** — `decision` (ADRs), `design`, `reference`, `runbook`, and
+`postmortem` as **documents** (the markdown body is the artifact); `control`,
+`convention`, `gotcha`, and `term` (glossary) as **records** (the typed fields are
+the artifact) — linked into a **cross-surface knowledge graph** and recalled by
+hybrid search + grounded `rag_ask`. This guide takes you from bootstrap to a
+populated, queryable KB, and to wiring an agent to use it day-to-day.
+
+> Companion: [`prompts/agentic-sdlc-agent.md`](../prompts/agentic-sdlc-agent.md) —
+> the drop-in agent orientation prompt (the recall-before-acting / capture-after
+> loop). Apply this guide to stand the KB up; apply that prompt to make an agent
+> use it.
+
+## 1. What you get
+
+- **9 schemas, content vs structure.** The prose artifacts — `decision` (ADR),
+  `design`, `reference`, `runbook`, `postmortem` — are **documents** (the markdown
+  body is searched + answered over). The structured artifacts — `control`,
+  `convention`, `gotcha`, `term` — are **records** (typed fields, exact-queryable).
+  Every item has a stable `externalId`, so re-ingesting never duplicates: an
+  unchanged item is returned as-is, and re-ingesting **edited** source with
+  `upsert: true` overwrites it in place — the KB is *rebuildable* and *syncable*.
+- **A cross-surface knowledge graph** — typed `reference` edges where **records
+  point at documents** (`control.verifiedBy` → the `runbook` that proves it;
+  `convention.establishedBy` / `term.relatedDecision` → the `decision` behind them)
+  and **documents point at documents** (`decision.supersedes`,
+  `design.relatedDecision`, `runbook.bornFrom` → a `postmortem`). Provenance is
+  navigable, not just searchable.
+- **A least-privilege key** — `records:r/c/u`, `search:r`, `schemas:r`,
+  `inference:r`, `documents:r/c`, `folders:r/c`. No delete: knowledge is
+  superseded/retired via a status flip, so the audit trail stays intact.
+- **An `editor` role for you, the human** — the same data-plane scope as the key,
+  ready to bind to your user so you can browse and curate the KB in the app (see
+  "Browse it as yourself" below).
+- **Range/sort on every artifact's date**, a governance `control` that records its
+  own evidence, a `convention` with distinct rule/why/howToApply fields, and a
+  glossary `term` with a `unique` exact-lookup.
+
+## 2. Quickstart — install, sign in, provision
+
+Install the public CLI, sign in once (browser), and provision the context + the nine
+schemas + a scoped key (and wire your MCP client). `production` is the default
+environment — add `--env staging` only to target staging.
+
+**Bash (macOS / Linux / Git Bash):**
+
+```bash
+npm i -g @vectros-ai/cli
+vectros login                                          # one-time, browser sign-in
+vectros bootstrap --blueprint agentic-sdlc --no-seed --yes
+vectros whoami                                         # confirm tenant + scoped key
+```
+
+**PowerShell (Windows):**
+
+```powershell
+npm i -g "@vectros-ai/cli"
+vectros login                                          # one-time, browser sign-in
+vectros bootstrap --blueprint agentic-sdlc --no-seed --yes
+vectros whoami
+```
+
+`bootstrap` provisions the context + schemas + a least-privilege `ssk_*` (written
+once to `~/.vectros/agentic-sdlc.key.json`) and safe-merges the Vectros MCP server
+into your **Claude Desktop** config; use `--client code` for **Claude Code**, or
+`--print` to emit the snippet without writing a file. Restart your MCP client to load
+it. (Prefer not to install globally? Prefix each command with `npx -y`, e.g.
+`npx -y @vectros-ai/cli bootstrap …` — on PowerShell quote the spec:
+`npx -y "@vectros-ai/cli" …`.)
+
+Add `--tenant test` to provision into the **test tenant** first (useful for a
+dry-run before committing to your live tenant). Omit for live (the default).
+
+### Browse it as yourself — grant your user access
+
+`bootstrap` provisions the context and a scoped key for your **agent** (the MCP
+server), but it does **not** join **you** — the signed-in human — to the new
+context. So when you open the data-plane app the context switcher won't list it
+yet: the app shows only contexts your user holds access in, and bootstrap grants
+your user none by default. Do this once so you can browse and curate the KB
+yourself. `bootstrap` already provisioned an **`editor`** role in the context
+(read + write, no delete — the same data-plane scope as the agent's key); bind it
+to your user two ways:
+
+- **In the admin app (easiest):** go to **Access → Contexts → `agentic-sdlc` →
+  Profiles → Create profile**, pick **yourself** (users list by email), choose the
+  **`editor`** role, and save.
+- **From the CLI:** `--principal me` resolves to your own user, so no id lookup is
+  needed:
+
+  ```bash
+  vectros access grant --principal me --context agentic-sdlc --role editor
+  ```
+
+  (Prefer an explicit id? `vectros identity list --type user` lists every tenant
+  user's id + email; your principal is `usr_` + the id next to your email.) Reopen
+  the data-plane app and `agentic-sdlc` now appears in the switcher with your data.
+
+### Seeds
+
+This blueprint ships **without bundled seeds** — it provisions the nine schemas +
+the scoped key, and you fill it from your own corpus (next section). So the context
+starts clean; there's no synthetic data to remove. (If you fork a blueprint that
+*does* ship seeds and want a clean production context, `vectros bootstrap
+--no-seed` provisions the schemas + key and skips the seed step.)
+
+## 3. Ingest your corpus
+
+There are two ingest paths, by surface — both driven by the **ingest agent**
+(point it at your source files with the
+[orientation prompt](../prompts/agentic-sdlc-agent.md); an LLM maps your
+semi-structured docs to the right type far better than a brittle parser, and it's
+idempotent by `externalId`).
+
+### Documents — the prose artifacts (ADRs, designs, references, runbooks, post-mortems)
+
+These keep their markdown **body as-is**; the agent fills the typed metadata and
+ingests via `document_ingest` against the matching schema:
+
+```text
+document_ingest:
+  title:    <the document's title — intrinsic; documents don't repeat it as metadata>
+  text:     <the raw markdown file — the body is the artifact>
+  schemaId: <the bound `decision` (or design/reference/runbook/postmortem) schema id>
+  payload:  { summary, status: "accepted", area: "search",
+              tags: ["..."], date: "YYYY-MM-DD" }   # metadata only; + refs, e.g. supersedes
+```
+
+Scope later searches to one type with `contentTypes: ["documents"], typeName:
+"decision"` (the document-type facet), plus `filters` for `area`/`tags`.
+
+### Records — the structured artifacts (controls, conventions, gotchas, terms)
+
+These are typed fields, not prose — the agent extracts the fields and calls
+`record_create` per item (e.g. a `convention`'s distinct rule/why/howToApply, a
+`control`'s evidence + `verifiedBy` runbook, a `term`'s unique key + definition).
+
+A one-shot backfill is that agent looped over your `docs/`/ADRs/memory; an ongoing
+sync re-runs it on change, re-ingesting edited source with `upsert: true` so the
+same `externalId`s overwrite in place (a plain re-create returns the existing item
+unchanged, so use `upsert` to propagate edits). Cross-surface edges (a record's
+reference to a document) resolve by the target's `externalId`, so ingest the
+referenced documents before the records that point at them.
+
+### Throttle the backfill — it's rate-limited
+
+A bulk backfill is exactly the workload that trips the API's **per-minute rate
+limit**. Two things to know:
+
+- The limit is **per tenant**, counts **writes + searches** (read-only `GET`s are
+  exempt), and is **shared across all of a tenant's keys** — so don't try to go
+  faster by running parallel ingests under different keys; they share one bucket.
+- The **free tier allows only tens of writes per minute**; higher plans allow more.
+  Check your plan's exact limit in the API rate-limits documentation.
+
+So pace the ingest: keep writes **well under your plan's per-minute limit** — for
+the free tier, roughly one record every couple of seconds is safe (a plain `sleep`
+between `record_create` calls is enough); go faster on higher tiers. On an HTTP
+**429**, **honor the `Retry-After` header** (seconds until the window resets; the
+response also carries `X-RateLimit-*`); if it's absent, back off exponentially with
+jitter, then resume. Because ingest is idempotent by `externalId`, a backfill that
+pauses or restarts simply converges — it never double-writes.
+
+## 4. Query it
+
+Documents are queried via search (scoped by `typeName`); records via `record_query`.
+
+| You want… | Call |
+|---|---|
+| "Why did we decide X?" (grounded, cited) | `rag_ask "why did we choose X?"` (answers over document bodies) |
+| "Which critical controls are active, and how is each proven?" | `record_query control { kind:"control", criticality:"critical", status:"active" }` → follow `verifiedBy` to the runbook |
+| "What's the active rule for area X?" | `record_query convention { area:"<area>", status:"active" }` |
+| "Have we hit this failure before?" | `hybrid_search "<symptom>" contentTypes:["documents"], typeName:"postmortem"`; plus `record_query gotcha { area:"deploy", status:"active" }` |
+| "Define X" | `record_query term { term:"X" }` (unique lookup) |
+| "Latest decisions / search the designs" | `hybrid_search "<topic>" contentTypes:["documents"], typeName:"decision"` (or `"design"`), `filters:{ area:"<area>" }` |
+| "What supersedes a given decision?" | document lookup on `decision` by `supersedes:"<externalId>"` |
+
+## 5. Customize
+
+This is a starting point — fork it for your org:
+
+- **`area` vocabulary** — swap in your subsystems.
+- **Add/remove schemas** — keep what fits; the format is the same as the bundled
+  source (`src/blueprints/agentic-sdlc.ts`).
+- **Enum vocabularies** — adjust `status`/`severity`/`category` to your lifecycle.
+- **Surface (document vs record)** — content-heavy types belong on the document
+  surface (`allowedSurfaces: ['document']`), structure-heavy types are records. Add
+  a separate type when the *shape* differs, when a distinct first-class type
+  strengthens *references*, or when it's a distinct thing humans **browse** — not
+  for a near-identical clone (use a filterable field for sub-kinds, as `reference`
+  does with `category`).
+- **Lookups are migration-locked** — the equality-vs-range choice and the 7 fast
+  equality slots per schema are fixed once a schema is live; choose deliberately
+  (see the package README § "The format, field by field").
+- **Sensitive fields** — SDLC knowledge generally isn't PHI, so this blueprint
+  marks nothing sensitive; if a field needs redaction (e.g. an internal endpoint in
+  a post-mortem), mark it `sensitive` (see the `clinical-intake` blueprint).
+
+## 6. Bridging your issue tracker — don't mirror it
+
+Your issue tracker (GitLab, Jira, Linear) and this knowledge base are **two planes
+with different jobs** — keep them separate:
+
+- **Tracker = live status** (open/closed, assignee, the board). Volatile; it stays
+  the source of truth for *what's in flight*.
+- **Knowledge base = durable recall** (why/how/lessons). Stable; the source of truth
+  for *what we know*.
+
+Mirroring issues into the KB creates a stale shadow copy and buries your decisions
+under issue churn. Instead, **promote by reference**:
+
+1. **When you close out work that carries durable knowledge**, distill it into the
+   right type — a settled call → `decision`, a trap → `gotcha`, an outage + lesson →
+   `postmortem`, a new rule → `convention`/`control`, a procedure → `runbook`.
+2. **Tag it `issue:<id>`** — e.g. `tags: ["auth", "issue:147"]` (`jira:ENG-12` /
+   `linear:OPS-9` work the same way). This is the link back to the live item.
+3. **Note the `externalId` back in the tracker** ("captured as `adr-token-rotation`")
+   — the return link.
+
+Then recall an issue's knowledge with `filters:{ tags:"issue:147" }`, and jump to its
+live status via the tag. **Be selective** — most issues (a dependency bump, a
+flaky-test fix) promote *nothing*; only the durable why/how/lesson belongs here. That
+selectivity is what keeps recall high-signal instead of drowning your decisions in
+tracker chatter. The KB never stores status (no open/closed/assignee): status lives
+in the tracker, knowledge lives here, and the tag + back-ref are the seam. (No schema
+change — every type already has `tags`.)
+
+## 7. Keep it healthy
+
+- **Record the why** — rationale is the most-recalled field; a statement without it
+  is a log entry, not knowledge.
+- **Supersede, don't delete** — flip `status` so the evolution trail survives.
+- **Re-ingest is keyed on `externalId`** — a backfill never double-writes (an
+  unchanged item returns as-is), re-ingesting edited source with `upsert: true` keeps
+  the KB in sync, and the KB can be rebuilt from source at any time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectros-ai/blueprints",
-  "version": "0.5.0",
+  "version": "0.6.3",
   "description": "Curated Vectros use-case blueprints (schemas + least-privilege AccessProfile + seed) and the Blueprint format + structural validation. Enforcement (the scope gate) lives in @vectros-ai/cli, not here.",
   "license": "Apache-2.0",
   "repository": {
@@ -20,6 +20,8 @@
   },
   "files": [
     "dist",
+    "guides",
+    "prompts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/prompts/agentic-sdlc-agent.md

@@ -0,0 +1,127 @@
+# Agent orientation prompt — `agentic-sdlc` knowledge base
+
+A drop-in preamble that orients a coding/ops agent to **use and feed** an
+`agentic-sdlc` Vectros knowledge base. Paste it into your agent's system prompt
+(Claude Code `CLAUDE.md`, a Cursor/Cline rule, a custom agent's instructions),
+then **customize the bracketed bits** — your `area` vocabulary, which schemas you
+use, and any house conventions. It assumes the `@vectros-ai/mcp-server` is
+connected and bound to your `agentic-sdlc` context (see the guide).
+
+Everything below the line is the prompt.
+
+---
+
+You have a persistent **engineering knowledge base** — your team's whole-SDLC
+memory — available through the Vectros MCP tools. It holds **decisions, designs,
+references, runbooks, and post-mortems** (long-form **documents**) plus
+**controls, conventions, gotchas, and a glossary** (typed **records**), all
+cross-linked into one graph you can recall by meaning. Treat it as the source of
+truth for "why is it shaped this way?" and "how do we do X?".
+
+## The loop: recall before you act, capture after
+
+1. **RECALL first.** Before you propose a change, design something, or debug a
+   failure, query the knowledge base. A cold start is exactly when you most need
+   the decision/convention/gotcha you can't re-derive from the code. Don't
+   re-litigate a settled decision or re-discover a known trap.
+2. **ACT** using what you recalled — follow the conventions and controls, reuse the
+   runbook, respect the supersede chain.
+3. **CAPTURE after.** When you make a durable decision, learn a convention, hit a
+   gotcha, write or revise a runbook, or run a post-mortem, write it back (a
+   document or a record, per below) so the next session inherits it. **Record the
+   *why*, not just the *what*** — the reasoning is the most-recalled content.
+
+Knowledge is **superseded / retired / resolved** via a status flip, never deleted —
+the trail of how the team's thinking evolved is part of the value.
+
+## What's in it (the schemas)
+
+Every item's `externalId` is its stable id (a slug or canonical number) so
+re-writing the same id **updates** instead of duplicating. `[area]` is your
+subsystem label (e.g. `auth`, `search`, `billing`, `governance`).
+
+**Documents** — content is the artifact (the markdown body is what you read/ask;
+written via `document_ingest`):
+
+| Type | Holds | Status |
+|---|---|---|
+| `decision` | an ADR — the settled *why* (body = context/decision/consequences) | proposed · accepted · superseded · deprecated |
+| `design` | a design doc / spec — the explored *how* | draft · active · implemented · superseded |
+| `reference` | a guide / onboarding / API / process doc (`category`, `lastReviewed`) | active · superseded |
+| `runbook` | a step-by-step operational procedure | active · retired |
+| `postmortem` | an incident writeup — what broke + the lesson (`severity`, `occurredOn`) | open · mitigated · resolved |
+
+**Records** — structure is the artifact (typed fields; written via `record_create`):
+
+| Type | Holds | Status |
+|---|---|---|
+| `control` | a policy/standard/control + its `evidence` (`kind`, `criticality`) | draft · active · retired |
+| `convention` | a must-follow rule — distinct `rule` / `why` / `howToApply` | active · retired |
+| `gotcha` | a sharp edge — `symptom` / `cause` / `fix` | active · resolved |
+| `term` | a glossary entry — `term` (unique) → `definition`, `aliases` | — |
+
+The graph **crosses surfaces** (every edge resolves a target by `externalId`):
+`decision.supersedes → decision`, `design.relatedDecision → decision`,
+`runbook.bornFrom → postmortem`, `control.verifiedBy → runbook` (how a control is
+proven), and `control` / `convention` / `term` → `decision` (records pointing at
+documents). Follow these to navigate provenance.
+
+## How to query (MCP tools)
+
+- **Recall by meaning / grounded answer** — `rag_ask` for a cited answer over the
+  document bodies: *"why did we choose X?"*, *"have we hit this before?"*.
+- **Search documents** — `hybrid_search` with `contentTypes: ["documents"]` and
+  `typeName` to scope to one document type (e.g. `typeName: "decision"` or
+  `"runbook"` or `"postmortem"`), plus `filters` (`{ area: "search" }`,
+  `{ tags: "tenant-isolation" }`).
+- **Query records** — `record_query` for exact enumeration:
+  `record_query control { kind: "control", criticality: "critical", status: "active" }`;
+  `record_query term { term: "AccessProfile" }` (unique lookup);
+  `record_query convention { area: "auth", status: "active" }`.
+  Range/sort on a record's date field (`order: "desc"`) for "latest" / "since".
+
+## How to capture (MCP tools)
+
+- **A document** (decision / design / reference / runbook / postmortem) —
+  `document_ingest` with the intrinsic `title` + the markdown **body** (`text`) +
+  `externalId` + the bound schema, plus a metadata `payload`. The title is intrinsic
+  to the document — do **not** repeat it inside `payload`. E.g. a decision:
+  `payload: { summary, status: "accepted", area: "[area]", tags: [...], date: "YYYY-MM-DD" }`
+  (set `supersedes` if it replaces one — write the target first).
+- **A record** (control / convention / gotcha / term) — `record_create` with a
+  stable `externalId` + the typed fields, e.g.:
+  - gotcha: `{ externalId: "gotcha-<slug>", symptom, cause, fix, area: "[area]", status: "active", discoveredOn: "YYYY-MM-DD" }`.
+  - convention: `{ externalId: "<slug>", title, rule, why, howToApply, area: "[area]", status: "active", establishedBy: "<decision-externalId>", updatedOn: "YYYY-MM-DD" }`.
+- **To retire** — re-write with `status` flipped (a decision to `superseded`, a
+  gotcha to `resolved`). Don't delete.
+
+## Conventions
+
+- **Idempotent + upsert:** reuse the same `externalId` so re-runs never duplicate — a
+  plain re-create returns the existing record **unchanged** (`created: false`); to apply
+  edits, send the change with `upsert: true`. Pick stable slugs/numbers.
+- **Write a reference target before the record that points at it.**
+- **Record the why.** A statement without rationale is a log entry, not knowledge.
+- When a decision changes, write the new `decision` and set its `supersedes` — don't
+  edit the old one's meaning away.
+- **Respect the rate limit.** Writes/searches are rate-limited per minute (per
+  tenant, shared across keys; the free tier is low). For a bulk write/backfill, pace
+  yourself (a short sleep between writes); on a `429`, honor the `Retry-After` header
+  (else back off exponentially) and retry — idempotency by `externalId` means a
+  paused/restarted run just converges.
+
+## Bridging an issue tracker
+
+Your tracker (GitLab/Jira/Linear) owns **live status**; this KB owns **durable
+knowledge** — don't mirror issues here. When you close out work that carries durable
+knowledge, **promote by reference**: write the typed document or record
+(decision/postmortem/runbook · convention/gotcha), **tag it `issue:<id>`** (e.g.
+`issue:147`; `jira:ENG-12` works too), and note the `externalId` back in the
+tracker. Recall an issue's
+knowledge with `filters:{ tags:"issue:147" }`; the tag is also your jump-link to live
+status. Be selective — most issues promote nothing; only the durable why/how/lesson
+belongs here. Never store status (open/closed/assignee) in the KB.
+
+[Customize: your `area` vocabulary, which schemas your team uses, naming
+conventions for `externalId`, your tracker tag prefix, and any house rules — e.g.
+"every control names the test that enforces it in `evidence`."]