toga-ai 1.0.46 → 1.0.48

package/knowledge.js

@@ -14,10 +14,13 @@
  *   node /path/to/claude/knowledge.js <command> [--flags]
  *
  * Commands:
- *   search   --framework= --repo= --project= --client= --file= --q=
+ *   search            --framework= --repo= --project= --client= --file= --q=
  *   index
- *   deps     --repo=<repo>
+ *   deps              --repo=<repo>
  *   validate
+ *   manifest
+ *   kickoff-preflight --repos=a,b,c --client=<slug> --layer=<...> --q=<...>
+ *   publish           --msg= --mirror= --branch=
  */
 
 'use strict';
@@ -170,6 +173,142 @@ function cmdManifest() {
     console.log(JSON.stringify({ repos, clients }));
 }
 
+/* ------------------------------------------------------------------ */
+/* command: kickoff-preflight — one JSON bundle for kickoff Steps 3+4.  */
+/* Given the chosen repos (+client, +layer), resolves the dependency    */
+/* load-set, every doc to read (with exists flags), and an ordered      */
+/* `reads` list — so kickoff stops running deps/search/path-probing in  */
+/* context. Prints minified JSON. Flags:                                */
+/*   --repos=a,b,c   (required)  --client=<slug>  --layer=<back-end|     */
+/*   front-end|hybrid>  --q=<keywords to match feature docs>            */
+/* ------------------------------------------------------------------ */
+
+function extractSection(body, heading) {
+    const lines = body.split(/\r?\n/);
+    const want = ('## ' + heading).toLowerCase();
+    const start = lines.findIndex(l => l.trim().toLowerCase() === want);
+    if (start === -1) return '';
+    const out = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i])) break;
+        out.push(lines[i]);
+    }
+    return out.join('\n').trim();
+}
+
+function cmdPreflight(args) {
+    const registry = loadRegistry();
+    const chosen = String(args.repos || '').split(',').map(s => s.trim()).filter(Boolean);
+    if (!chosen.length) {
+        console.log(JSON.stringify({ error: 'PREFLIGHT: --repos=<repo,repo> required' }));
+        process.exitCode = 1;
+        return;
+    }
+    const layer = String(args.layer || 'hybrid').toLowerCase();
+    const q = args.q ? String(args.q).toLowerCase() : null;
+    const unknown = chosen.filter(r => !registry.find(x => x.repo === r));
+
+    // frameworks involved (from the chosen repos)
+    const fwSet = new Set();
+    for (const r of chosen) { const e = registry.find(x => x.repo === r); if (e) fwSet.add(e.framework); }
+    const frameworks = [...fwSet];
+
+    // dependency load-set: framework core(s) first, then transitive dependsOn, then chosen
+    const seen = new Set();
+    const loadSet = [];
+    const visit = (r) => {
+        const e = registry.find(x => x.repo === r);
+        if (!e) return;
+        for (const d of (e.dependsOn || [])) visit(d);
+        if (!seen.has(r)) { seen.add(r); loadSet.push(r); }
+    };
+    for (const fw of frameworks) for (const core of coreReposFor(registry, fw)) visit(core);
+    for (const r of chosen) visit(r);
+
+    const docs = allDocs();
+    const chosenSet = new Set(chosen);
+    const fileInfo = (rel) => ({ path: rel, exists: fs.existsSync(path.join(ROOT, rel.split('/').join(path.sep))) });
+    const matchQ = (d) => !q || (((d.data.title || '') + ' ' + (d.data.files || []).join(' ') + ' ' + d.body).toLowerCase().includes(q));
+
+    // per-repo inventory. Chosen repos load FULL architecture + matched features.
+    // Non-chosen repos (deps, incl. framework core) get their `## Summary` inlined
+    // here so kickoff reads zero extra files for them — full doc lazy on demand.
+    const repoOut = loadSet.map(repo => {
+        const e = registry.find(x => x.repo === repo);
+        const fw = e ? e.framework : '';
+        const repoDir = path.join(ROOT, fw, 'apps', repo);
+        const isChosen = chosenSet.has(repo);
+        const archRel = `${fw}/apps/${repo}/architecture.md`;
+        const archDoc = docs.find(d => d.rel === archRel);
+        let features = [];
+        if (isChosen) {
+            features = docs
+                .filter(d => d.file.startsWith(repoDir + path.sep) && d.data.type !== 'architecture' && matchQ(d))
+                .map(d => ({ path: d.rel, title: d.data.title || '', files: (d.data.files || []).join(', ') }));
+        }
+        const summary = (!isChosen && archDoc) ? (extractSection(archDoc.body, 'Summary') || firstSentence(archDoc.body)) : '';
+        return {
+            repo, framework: fw, project: e ? e.project : '', role: e ? e.role : '', chosen: isChosen,
+            architecture: fileInfo(archRel),
+            summary,
+            features,
+        };
+    });
+
+    // standards per involved framework, filtered by layer
+    const wantBackend = layer === 'back-end' || layer === 'backend' || layer === 'hybrid';
+    const wantFrontend = layer === 'front-end' || layer === 'frontend' || layer === 'hybrid';
+    const standards = [];
+    for (const fw of frameworks) {
+        if (wantBackend) standards.push({ ...fileInfo(`${fw}/standards/backend-php.md`), framework: fw });
+        if (wantFrontend) standards.push({ ...fileInfo(`${fw}/standards/frontend.md`), framework: fw });
+    }
+
+    // client docs (profile + features/workflows filtered to involved frameworks)
+    let client = null;
+    const slug = args.client && args.client !== 'shared' && args.client !== true ? String(args.client) : null;
+    if (slug) {
+        const clientDir = path.join(ROOT, 'clients', slug);
+        const cDocs = docs.filter(d => d.file.startsWith(clientDir + path.sep));
+        const profileDoc = cDocs.find(d => path.basename(d.file) === 'profile.md');
+        const cFeatures = cDocs
+            .filter(d => path.basename(d.file) !== 'profile.md')
+            .filter(d => !frameworks.length || !d.data.framework || frameworks.includes(d.data.framework))
+            .filter(matchQ)
+            .map(d => ({ path: d.rel, title: d.data.title || '', framework: d.data.framework || '', type: d.data.type || '' }));
+        client = {
+            slug,
+            title: (profileDoc && profileDoc.data.title) || slug,
+            profile: fileInfo(`clients/${slug}/profile.md`),
+            docs: cFeatures,
+        };
+    }
+
+    // ordered read list — mirrors kickoff Step 4 precedence (core first, then chosen
+    // repos + features, then standards, then client). Chosen repos → a FULL architecture
+    // read; non-chosen → an inline-`summary` entry the skill should NOT open unless it
+    // needs deeper detail (lazy:true). Core ordering preserved so foundational context
+    // (even when summarized) comes before app context.
+    const reads = [];
+    const pushRepoRead = (r) => {
+        if (r.chosen) {
+            reads.push({ label: 'repo-architecture', repo: r.repo, path: r.architecture.path, exists: r.architecture.exists });
+            for (const f of r.features) reads.push({ label: 'feature', repo: r.repo, path: f.path, exists: true, title: f.title });
+        } else {
+            reads.push({ label: 'architecture-summary', repo: r.repo, role: r.role, path: r.architecture.path, exists: r.architecture.exists, lazy: true, summary: r.summary });
+        }
+    };
+    for (const r of repoOut.filter(r => r.role === 'core')) pushRepoRead(r);
+    for (const r of repoOut.filter(r => r.role !== 'core')) pushRepoRead(r);
+    for (const s of standards) reads.push({ label: 'standard', path: s.path, exists: s.exists });
+    if (client) {
+        reads.push({ label: 'client-profile', path: client.profile.path, exists: client.profile.exists });
+        for (const d of client.docs) reads.push({ label: 'client-doc', path: d.path, exists: true, title: d.title });
+    }
+
+    console.log(JSON.stringify({ frameworks, loadSet, unknown, repos: repoOut, standards, client, reads }));
+}
+
 /* ------------------------------------------------------------------ */
 /* command: publish — capture's deterministic finish (validate, index, */
 /* optional mirror, commit knowledge/, rebase-before-push with retry). */
@@ -481,9 +620,10 @@ function main() {
         case 'deps': return cmdDeps(args);
         case 'validate': return cmdValidate();
         case 'manifest': return cmdManifest();
+        case 'kickoff-preflight': return cmdPreflight(args);
         case 'publish': return cmdPublish(args);
         default:
-            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest|publish> [--flags]');
+            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest|kickoff-preflight|publish> [--flags]');
             process.exitCode = 1;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "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/kickoff/SKILL.md

@@ -128,33 +128,63 @@ and silently truncates a 7-repo / 5-client list. Render the full list as a numbe
 list and have the developer reply with numbers (e.g. "1, 3, 5") — no cap, supports
 multi-select. Framework (q1) and layer (q2) have ≤4 options, so chips are fine there.
 
-## Step 3 — Resolve the repos this work needs (local paths, lazily)
+## Step 3 — Preflight: resolve the load-set and the exact read list (one call)
 
-Compute the load set with `node "<TEAM_REPO>/knowledge.js" deps --repo=<chosen-repo>`
-(returns the framework core + chosen repo + transitive `dependsOn`, in load order). For
-**both** frameworks, run it for each chosen repo and union the results.
+Run **one** command — it does the dependency resolution, feature-doc matching, standards
+selection, and client-doc filtering that used to be several `deps`/`search` calls plus
+in-context path-probing:
 
-For **each** repo in the load set, get its local path so you can navigate the actual code:
+```bash
+node "<TEAM_REPO>/knowledge.js" kickoff-preflight \
+  --repos=<comma-separated chosen repos> \
+  --client=<slug | omit if shared/internal> \
+  --layer=<back-end | front-end | hybrid> \
+  --q=<2-4 keywords from the developer's task sentence>
+```
+
+It prints minified JSON:
+- `loadSet` — framework core(s) + chosen repos + transitive `dependsOn`, in load order.
+- `repos[]` — each with `architecture` `{path,exists}`, `role`, `chosen`, an inline
+  `summary` (for non-chosen repos), and matched `features[]` (features returned only for the
+  repos the developer chose, not deps).
+- `standards[]` and `client` `{title, profile, docs[]}` — both `{path,exists}`-flagged.
+- `reads[]` — **the ordered work list** (see Step 4). Full-read entries carry `{label, path,
+  exists}`; non-chosen repos instead carry `{label:'architecture-summary', summary, lazy:true}`
+  with the Summary text inlined so no file read is needed.
+- `unknown[]` — any `--repos` value not in the registry (run New-repo onboarding for each).
+
+**Do not run `deps` or `search` separately, and do not probe the filesystem for these docs.**
+The preflight already resolved everything; trust `reads[]`.
+
+Then, for **each repo in `loadSet`**, get its local code path (so you can navigate the actual
+source — this is the one thing preflight can't know):
 - Look for a Claude `reference` memory named `repo-path-<repo>` (e.g. `repo-path-worker2`).
 - If absent, **ask**: "What is the path to the `<repo>` repository?" Validate it exists,
   then **write a `repo-path-<repo>` memory** (+ MEMORY.md pointer).
 
-Never ask for a repo the session doesn't touch.
+Never ask for a repo not in `loadSet`.
 
 ## Step 4 — Load the knowledge
 
-Read and internalize, in this order:
-1. **Framework core architecture** — `<TEAM_REPO>/knowledge/<fw>/apps/<core-repo>/architecture.md`
-   (e.g. `2.0/apps/_underscore/architecture.md`). Always load this first.
-2. **The chosen repo's** `architecture.md`, then feature docs matched to the description:
-   `node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --q=<keywords>`.
-3. **Coding standards** for the framework(s): `<fw>/standards/backend-php.md` and/or
-   `frontend.md` per the layer answer (plus any others that exist). Load whichever exist.
-4. **Client knowledge** (if a real client): `clients/<client>/profile.md` and that client's
-   `features/`/`workflows/` filtered to the selected framework(s)
-   (`search --client=<client> --framework=<fw>`).
-
-For **both** frameworks, union across `1.0/` and `2.0/`.
+Walk the preflight `reads[]` array **in order**. Each entry is one of:
+
+- **`lazy:true` (label `architecture-summary`)** — a repo the developer did NOT choose as
+  focus (a dependency or framework core). The entry already carries an inline `summary`
+  string — **use that summary as your context for this repo; do NOT open the file.** Only
+  open its `path` later, on demand, if a task actually requires that repo's deep internals.
+  This is the token-saving default: foundational orientation without loading the full doc.
+- **Any other entry (no `lazy` flag)** — the chosen repos' architecture + matched feature
+  docs, standards, and client docs. **Read these in full**, resolving `path` against
+  `<TEAM_REPO>/knowledge/`.
+- **`exists:false`** — skip; that doc isn't written yet. Note it in the Step 5 summary as
+  "no knowledge captured yet."
+
+The `reads[]` order already encodes the correct precedence (core first, then chosen-repo
+architecture + matched features, then standards, then client profile + client docs) and
+already unions across `1.0/` and `2.0/`. Do not re-derive this order or run further `search`.
+
+If, while working, you find you need the full architecture of a summarized (`lazy`) repo,
+just read its `path` then — that's the intended lazy-load, not a kickoff failure.
 
 **Do NOT create or modify any `CLAUDE.md` stub** — kickoff only reads. A blank session is a
 valid choice; this skill is opt-in.