toga-ai 1.0.53 → 1.0.54

package/knowledge/CONVENTIONS.md

@@ -24,10 +24,10 @@ knowledge/
 ├── registry.json          # repo ↔ project ↔ framework ↔ role ↔ dependsOn
 ├── INDEX.md               # auto-generated master index
 ├── 1.0/
-│   ├── apps/<repo>/architecture.md + features/*.md
+│   ├── apps/<repo>/architecture.md + features/*.md + workflows/*.md
 │   └── standards/*.md     # 1.0 coding standards (App_)
 ├── 2.0/
-│   ├── apps/<repo>/architecture.md + features/*.md
+│   ├── apps/<repo>/architecture.md + features/*.md + workflows/*.md
 │   └── standards/*.md     # 2.0 coding standards (_underscore)
 └── clients/<client>/
     ├── profile.md
@@ -83,13 +83,33 @@ declares the files it covers, so the doc indexes into the code.
 
 ## Document types
 
+The knowledge base is organized by **subject** (a capability, a process, a component), never
+by session or ticket. `capture` assigns the type — **developers never classify.**
+
 - **architecture** — how a repo/framework works overall (one per repo). _Elevated._
-- **feature** — a discrete, shared capability or repeatable workflow within a repo.
-- **client-feature** — a client's customization/override of a shared feature; links
-  back to the shared `apps/<repo>/features/<base>.md`.
-- **workflow** — a client business process.
+- **feature** — a capability anchored to specific code in a repo (a model, a class, a set of
+  files). Its template carries a **How it works** section, so the *process* of a feature lives
+  inside the feature doc — most features contain a process, and that does not make them a
+  workflow. Lives in `apps/<repo>/features/`.
+- **workflow** — a standalone, multi-step process that **no single capability owns**; it spans
+  systems/actors/time. Two homes: operational/system processes in `apps/<repo>/workflows/`
+  (e.g. a deploy or reconciliation procedure), and client business processes in
+  `clients/<client>/workflows/`.
+- **client-feature** — a client's customization/override of a shared feature; links back to
+  the shared `apps/<repo>/features/<base>.md`.
 - **standard** — a coding standard for a framework. _Elevated._
 
+**Choosing the type (capture's rule — default to feature):**
+- "Can I point at one capability/model/class that *is* this?" → **feature** (its process goes
+  in the *How it works* section).
+- "Is this a sequence of steps spanning systems/actors that is a *procedure*, not a thing?" →
+  **workflow.**
+- When in doubt → **feature.** Defaulting prevents workflow-file sprawl.
+
+**Bugs are not a type.** A bug fix's durable lesson attaches as a **gotcha** (or a one-line
+*Change history* entry) on the feature/workflow doc that owns the affected code — never a
+standalone doc. Only a recurring/systemic failure class warrants its own record, case by case.
+
 _Elevated_ docs (architecture, standard) are senior-owned; `capture` flags any change
 to them with ⚠ so the developer knows what they're approving.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/skills/capture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: capture
-description: End-of-session knowledge writer for TOGA Technology projects. Run this at the END of a coding session to record what you worked on into the team `claude` knowledge base. It figures out what changed this session, matches it against existing knowledge, and proposes create/update/retire changes for one-tap approval — then writes them, keeping registry.json, frontmatter, and INDEX files consistent. Trigger whenever the user says "capture", "wrap up", "save my work to the knowledge base", "I'm done — record this", or finishes a feature and wants it documented.
+description: End-of-session knowledge writer for TOGA Technology projects. Run this at the END of a coding session to record what you worked on into the team `claude` knowledge base. It figures out what changed this session, matches it against existing knowledge, and proposes create/update/retire changes for one-tap approval — then writes them, keeping registry.json, frontmatter, and INDEX files consistent. Run at the END of EVERY session — not only for finished features but also for small bug fixes and "I just changed the way something works"; capture decides what is durable (usually a small UPDATE to an existing doc, sometimes a NO-OP). Trigger whenever the user says "capture", "wrap up", "save my work to the knowledge base", "I'm done — record this", or ends a session.
 ---
 
 # Capture — record this session's work into the team knowledge base
@@ -110,9 +110,38 @@ node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --file=<to
 node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --q=<keywords>
 ```
 
-Classify each item as **CREATE** (no doc yet), **UPDATE** (a doc exists and needs new
-content / a new `files:` entry / a gotcha), or **DEPRECATE/DELETE** (the doc describes
-something now removed or obsolete).
+Classify each item as **CREATE** (no doc yet), **UPDATE** (a doc exists and needs new content /
+a new `files:` entry / a gotcha / a *Change history* line), **DEPRECATE/DELETE** (the doc
+describes something now removed or obsolete), or **NO-OP** (nothing durable — see below).
+
+### Always run; capture decides what (if anything) is durable
+
+`/capture` runs at the end of **every** session — including small bug fixes and "I just changed
+the way something works," not only finished features. The KB is organized by **subject** (a
+capability, a process, a component), **not** by session or ticket, so capturing small work is
+safe: it almost always **UPDATES one existing subject doc**, and rarely creates one.
+
+**Guardrails against pollution (enforce these):**
+- **One doc per subject** — never one per change, bug, or ticket.
+- **Bias UPDATE over CREATE** — always search for an owning doc first; CREATE only when no
+  subject doc exists. A small "how it works" change UPDATES the feature's *How it works* section
+  and adds a dated one-line *Change history* entry, in place — it does not spawn a new file.
+- **Relevance test** — for every candidate write ask: *"Will a teammate six months from now act
+  differently because this is written?"* If no → **NO-OP**.
+- **NO-OP is a blessed, first-class outcome.** If nothing rises to durable knowledge (typo,
+  formatting, a fix obvious from the code), write nothing and report: "Nothing here is durable
+  team knowledge — KB unchanged." Never manufacture a doc to justify the run.
+
+**Type assignment (you assign it — developers never classify; default to feature):**
+- Anchored to one capability/model/class? → **feature** (its process → the *How it works* section).
+- A standalone multi-step process no single capability owns? → **workflow**
+  (`apps/<repo>/workflows/` for operational/system processes; `clients/<client>/workflows/` for
+  client business processes).
+- A client's override of a shared feature? → **client-feature**.
+- A reversible team-wide rule/decision? → **standard** (⚠ elevated).
+- A bug's durable lesson? → a **gotcha** or *Change history* line on the doc that owns the
+  affected code — **never its own doc.**
+- When in doubt → **feature.**
 
 ## Step 4 — Build the proposal (one-tap approval)
 
@@ -217,27 +246,36 @@ How behavior differs per client (or "none — uniform").
 ## Gotchas / known issues
 The non-obvious things future-you will trip on.
 
+## Change history
+Dated one-liners, newest first — notable behavior changes only. Keep it terse; this is not a
+git log. Cap at ~10 entries; fold older ones away.
+- YYYY-MM-DD — <what changed and why> (<author>)
+
 ## Related docs
 Links.
 ```
 
-### workflow (client business process)
+### workflow (a standalone process — operational OR client business)
+Two homes: `apps/<repo>/workflows/` for operational/system processes (set `repo`,
+`client: shared`); `clients/<client>/workflows/` for client business processes (set the
+`client` slug, omit `repo`).
 ```markdown
 ---
 title: <Workflow Name>
 framework: "<1.0|2.0>"
+repo: <repo>            # for apps/<repo>/workflows/; omit for a pure client workflow
 project: <Project>
-client: <client-slug>
+client: <shared|client-slug>
 type: workflow
 status: active
 updated: <YYYY-MM-DD>
 owners: ["<AUTHOR_USERNAME>"]   # from Step 1b — never empty
-files: []
+files: []               # source files the process touches, if any
 related: []
 ---
 
 ## Summary
-The business process and who it serves.
+The process, who/what it serves, and what triggers it.
 
 ## Steps
 1. …
@@ -247,6 +285,10 @@ Apps/repos, integrations, data.
 
 ## Edge cases & escalation
 What can go wrong and who handles it.
+
+## Change history
+Dated one-liners, newest first. Keep terse; cap at ~10.
+- YYYY-MM-DD — <what changed and why> (<author>)
 ```
 
 ### architecture (one per repo) — ⚠ ELEVATED