toga-ai 1.0.4 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "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/scripts/install.js

@@ -462,17 +462,17 @@ function main() {
   console.log('toga-ai — TOGA Technology Claude harness');
   console.log('═════════════════════════════════════════════');
 
-  // Step 1: npm bundle is always the baseline source
-  let sourceDir = PACKAGE_ROOT;
-  let sourceLabel = 'npm bundle v' + bundleVersion;
+  // Harness components (skills/agents/rules/hooks) ALWAYS come from the npm bundle.
+  // The git repo is ONLY used to pull newer knowledge docs on top — it never
+  // replaces harness components, so a stale local clone can't break the install.
+  const harnessDir = PACKAGE_ROOT;
+  let knowledgeDir = PACKAGE_ROOT;  // overridden below if git repo found
   let gitUpdateLine = null;
 
-  // Step 2: find or try to clone git repo for updates
   if (repoFlag) {
     const resolved = path.resolve(repoFlag);
     if (isValidClone(resolved)) {
-      sourceDir = resolved;
-      sourceLabel = 'git repo (--repo flag)';
+      knowledgeDir = resolved;
     } else {
       console.error('  ERROR: --repo path is not a valid clone: ' + resolved);
       process.exit(1);
@@ -481,40 +481,37 @@ function main() {
     let repoDir = findExistingClone();
 
     if (!repoDir && !isPostInstall) {
-      // Try to clone silently — no error if it fails
       repoDir = tryCloneRepo(path.join(os.homedir(), 'toga-tech'));
     }
 
     if (repoDir) {
-      // Pull latest — silent on failure, just use bundle
       const pullResult = tryGitPull(repoDir);
       saveRepoPathCache(repoDir);
 
       if (pullResult.pulled) {
-        sourceDir = repoDir;
-        sourceLabel = 'npm bundle v' + bundleVersion;
+        knowledgeDir = repoDir;
         if (pullResult.newDocs > 0) {
           gitUpdateLine = 'git update: pulled ' + pullResult.newDocs + ' new knowledge doc' + (pullResult.newDocs !== 1 ? 's' : '') + ' from TOGATechnology/claude';
-        } else {
+        } else if (pullResult.message !== 'already up to date') {
           gitUpdateLine = 'git update: ' + pullResult.message;
         }
       } else if (isValidClone(repoDir)) {
-        // Pull failed but repo exists — still use it as source
-        sourceDir = repoDir;
-        sourceLabel = 'git repo (offline, using cached)';
+        // Pull failed but repo exists — use cached knowledge only
+        knowledgeDir = repoDir;
       }
-      // else: pull failed and can't use repo — silently stick with bundle
     }
-    // No git access at all — silently use bundle
   }
 
-  console.log('  Source: ' + sourceLabel);
-  if (gitUpdateLine) {
+  console.log('  Harness: npm bundle v' + bundleVersion);
+  if (knowledgeDir !== PACKAGE_ROOT) {
+    console.log('  Knowledge: git repo' + (gitUpdateLine ? ' (' + gitUpdateLine.replace('git update: ', '') + ')' : ' (cached)'));
+  }
+  if (gitUpdateLine && knowledgeDir === PACKAGE_ROOT) {
     console.log('  ↳ ' + gitUpdateLine);
   }
   console.log('');
 
-  if (isPostInstall && sourceDir === PACKAGE_ROOT && !repoFlag) {
+  if (isPostInstall && !repoFlag) {
     console.log('  First-time setup: run `toga-ai` from your project to');
     console.log('  install the harness into your .claude/ directory.');
     console.log('');
@@ -535,7 +532,7 @@ function main() {
   const errors = [];
 
   // Skills
-  const skillsSrc = path.join(sourceDir, 'skills');
+  const skillsSrc = path.join(harnessDir, 'skills');
   const skillsDest = path.join(claudeDir, 'skills');
   fs.mkdirSync(skillsDest, { recursive: true });
   const skillNames = fs.existsSync(skillsSrc)
@@ -552,7 +549,7 @@ function main() {
   console.log('  ✓ Skills    (' + skillNames.length + '): ' + fmtStats(skillStats));
 
   // Rules — update if content changed (team standards should always be current)
-  const rulesSrc = path.join(sourceDir, 'rules');
+  const rulesSrc = path.join(harnessDir, 'rules');
   const rulesDest = path.join(claudeDir, 'rules', 'toga');
   let rulesStats = { added: 0, updated: 0, unchanged: 0 };
   if (fs.existsSync(rulesSrc)) {
@@ -562,7 +559,7 @@ function main() {
   console.log('  ✓ Rules     (' + countMd(rulesDest) + '): ' + fmtStats(rulesStats));
 
   // Agents — update if content changed
-  const agentsSrc = path.join(sourceDir, 'agents');
+  const agentsSrc = path.join(harnessDir, 'agents');
   const agentsDest = path.join(claudeDir, 'agents', 'toga');
   let agentsStats = { added: 0, updated: 0, unchanged: 0 };
   if (fs.existsSync(agentsSrc)) {
@@ -573,7 +570,7 @@ function main() {
   console.log('  ✓ Agents    (' + agentsCount + '): ' + fmtStats(agentsStats));
 
   // Hook scripts — always overwrite so paths stay up to date
-  const hooksSrc = path.join(sourceDir, 'scripts', 'hooks');
+  const hooksSrc = path.join(harnessDir, 'scripts', 'hooks');
   const hooksDest = path.join(claudeDir, 'hooks', 'toga');
   let hooksCount = 0;
   if (fs.existsSync(hooksSrc)) {
@@ -584,18 +581,18 @@ function main() {
   }
 
   // knowledge.js CLI — always overwrite so it stays current
-  const knowledgeJsSrc = path.join(sourceDir, 'knowledge.js');
+  const knowledgeJsSrc = path.join(harnessDir, 'knowledge.js');
   if (fs.existsSync(knowledgeJsSrc)) {
     try { fs.copyFileSync(knowledgeJsSrc, path.join(claudeDir, 'knowledge.js')); }
     catch (e) { errors.push('knowledge.js: ' + e.message); }
   }
 
   // Settings — merge (additive only, never removes existing hooks or permissions)
-  const ok = mergeSettings(claudeDir, sourceDir);
+  const ok = mergeSettings(claudeDir, harnessDir);
   console.log('  ' + (ok ? '✓' : '✗') + ' Hooks     (' + hooksCount + ' scripts in .claude/hooks/toga/, settings.json merged)');
 
   // MCP example — skip if already present
-  const mcpSrc = path.join(sourceDir, 'mcp-configs', 'mcp-servers.json');
+  const mcpSrc = path.join(harnessDir, 'mcp-configs', 'mcp-servers.json');
   const mcpDest = path.join(claudeDir, 'mcp-servers.example.json');
   if (fs.existsSync(mcpSrc) && !fs.existsSync(mcpDest)) {
     try { fs.copyFileSync(mcpSrc, mcpDest); }
@@ -603,8 +600,9 @@ function main() {
     console.log('  ✓ MCP       (.claude/mcp-servers.example.json — merge into .mcp.json to enable)');
   }
 
-  // Knowledge — skipExisting: user-grown docs are never overwritten by the bundle
-  const knowledgeSrc = path.join(sourceDir, 'knowledge');
+  // Knowledge — git repo if available (has team-captured docs), else npm bundle
+  // skipExisting: user-grown docs are never overwritten
+  const knowledgeSrc = path.join(knowledgeDir, 'knowledge');
   const knowledgeDest = path.join(claudeDir, 'knowledge');
   let knowledgeStats = { added: 0, updated: 0, unchanged: 0 };
   if (fs.existsSync(knowledgeSrc)) {
@@ -614,7 +612,7 @@ function main() {
   console.log('  ✓ Knowledge (' + countMd(knowledgeDest) + ' docs): ' + fmtStats(knowledgeStats));
 
   // CLAUDE.md
-  const action = updateClaudeMd(projectRoot, skillNames, sourceDir, sourceLabel);
+  const action = updateClaudeMd(projectRoot, skillNames, harnessDir, 'npm bundle v' + bundleVersion);
   console.log('  ✓ CLAUDE.md ' + action);
 
   // ECC global integration — detect and report

package/skills/capture/SKILL.md

@@ -100,39 +100,33 @@ report success on an inconsistent knowledge base.
 
 ## Step 7 — Auto-push to share with teammates
 
-After validate + index succeed, stage and push only `knowledge/` changes to a
-**personal branch** so a maintainer can review before merging to main.
+After validate + index succeed, stage and push only `knowledge/` changes directly to
+`feature/ai-harness-improvements`. CI picks up the push and publishes a new npm version
+automatically — teammates get it on their next `npx toga-ai`.
 
 ```bash
-# Derive branch name from git user — e.g. knowledge/john-smith
-BRANCH="knowledge/$(git -C "<TEAM_REPO>" config user.name | tr ' ' '-' | tr '[:upper:]' '[:lower:]')"
-
-# Stage only knowledge/ — never stages source code
+# Stage only knowledge/ — never stage source code
 git -C "<TEAM_REPO>" add knowledge/
 git -C "<TEAM_REPO>" diff --cached --quiet || git -C "<TEAM_REPO>" commit -m "knowledge: <brief description of what was captured>"
 
-# Push to personal branch — does not touch main
-git -C "<TEAM_REPO>" push origin HEAD:"$BRANCH"
+# Push directly to the active development branch
+git -C "<TEAM_REPO>" push origin HEAD:feature/ai-harness-improvements
 ```
 
-Replace `<brief description of what was captured>` with a one-line summary of the docs
-written this capture (e.g. `"knowledge: add clickup-deploy feature doc for worker2"`).
+Replace `<brief description of what was captured>` with a one-line summary
+(e.g. `"knowledge: add clickup-deploy feature doc for worker2"`).
 
 **If push succeeds:** report
-> "✓ Knowledge pushed to branch `knowledge/<your-name>` — a maintainer will review and merge to main"
+> "✓ Knowledge pushed to `feature/ai-harness-improvements` — CI will publish a new npm version. Teammates get it on their next `npx toga-ai`."
 
-**If push fails** (offline, no credentials, diverged branch, or any other error): do
-**NOT** error out. Report:
-> "⚠ Could not push — run `git -C <TEAM_REPO> push origin HEAD:knowledge/<your-name>` when ready"
+**If push fails** (offline, no credentials, diverged): do **NOT** error out. Report:
+> "⚠ Could not push — run `git -C <TEAM_REPO> push origin HEAD:feature/ai-harness-improvements` when ready"
 and still consider the capture session successful.
 
 Never stage anything outside `knowledge/`. If `git diff --cached` would include files
 outside `knowledge/`, abort the commit and warn: "Unexpected staged files outside
 `knowledge/` — push skipped. Review and push manually."
 
-**Devs do not need write access to main.** They only need permission to push to
-`knowledge/*` branches. A maintainer reviews the branch and merges via PR.
-
 ## Step 8 — Report
 
 List exactly what changed (clickable relative paths), and note any ⚠ ELEVATED docs the

package/skills/kickoff/SKILL.md

@@ -150,32 +150,89 @@ If they have already run `/session-resume` and are now running `/kickoff`, proce
 normally — the session context they loaded will complement the framework knowledge
 loaded here.
 
-## Step 5 — Surface ECC power-ups for the work type
+## Step 5 — Propose a multi-agent workflow plan
 
-After loading TOGA context, tell the developer which ECC specialist capabilities are available for this session's work type:
+After loading context, analyze what the developer said they're building and **propose a
+concrete agent plan before writing a single line of code**. This gives them visibility
+into how the work will be done and a chance to adjust scope.
 
-**For PHP development:**
-- `/code-review` — ECC php-reviewer + TOGA pattern overlay (use after writing any PHP)
-- ECC security-reviewer fires automatically on security-sensitive code
+The developer does not know what "sub-agents" or "loops" are — do not use that jargon.
+Frame everything in plain terms: "Here's my plan."
 
-**For feature implementation:**
-- `/code-review` triggers ecc:planner with your loaded TOGA architecture context
-- The php-reviewer agent runs automatically after every PHP file edit
+### Plan template
 
-**For debugging / build errors:**
-- ecc:build-error-resolver + TOGA framework context = fast diagnosis
+```
+Here's how I'll approach this:
+
+1. [First step — e.g. "Map the existing code and create a phased plan"]
+2. [Build step — e.g. "Write the worker class and controller method"]
+3. [Verify step — e.g. "Run specialist reviewers on the PHP and SQL before showing you the result"]
+
+To do this well, I'll use specialist reviewers that run automatically as I write —
+they catch framework violations and security issues without you needing to ask.
 
-**For SQL/DB work:**
-- sql-reviewer agent fires automatically on PHP files with DB patterns
-- ecc:database-reviewer provides deep query analysis
+**I'll need access to:**
+- Read: [list relevant repo paths]
+- Write/edit: [list the specific files or folders I plan to create or modify]
+- Shell: [any commands I'll run, e.g. "php -l to lint files"]
 
-**For documentation:**
-- `knowledge-writer` agent writes correct TOGA frontmatter automatically
+Claude Code will ask you to approve each action as I go. If you'd rather I just
+proceed without interrupting you, say "go ahead" and I'll work through it and
+show you the finished result.
 
-End the kickoff with:
+Ready to proceed?
 ```
-Context loaded for <repo> (Framework <fw>). 
-ECC agents active: php-reviewer, database-reviewer, security-reviewer, planner, build-error-resolver.
-Run /kickoff again if you switch to a different repo or client.
-What are you building?
+
+**Always wait for a yes before starting.** If the developer says "go ahead", "just do it",
+or "you have full access" — proceed without further permission prompts, but still flag any
+write outside the expected scope.
+
+---
+
+### Agent selection (how to build the plan internally)
+
+Spawn specialists via the `Agent` tool. Grant only the tools the agent needs.
+
+| Work type | Agent to spawn | Tools to grant |
+|-----------|---------------|----------------|
+| New feature design | `ecc:planner` with TOGA context prefix | Read, Grep, Glob |
+| Write/edit PHP | `ecc:php-reviewer` after each file written | Read, Grep, Glob |
+| SQL / DB queries | `ecc:database-reviewer` with TOGA DB context | Read, Grep, Glob |
+| PHP errors / build broken | `ecc:build-error-resolver` with TOGA error patterns | Read, Write, Edit, Bash, Grep, Glob |
+| Security audit | `ecc:security-reviewer` | Read, Grep, Glob |
+| Document a feature | `knowledge-writer` TOGA agent | Read, Write, Bash, Grep, Glob |
+| Large refactor | `ecc:code-reviewer` then `ecc:planner` | Read, Grep, Glob |
+
+Always inject the TOGA context prefix when spawning any ECC agent. The prompts in
+`.claude/agents/toga/php-reviewer.md` and `planner.md` show the exact prefix format.
+
+---
+
+### When to use an iterative loop
+
+Run an agent, review findings, fix, repeat — when:
+- Build errors are present (keep looping until output is clean)
+- The developer says "make sure this is right" or "check everything"
+- You're creating more than 3 PHP files in one task
+
+Tell the developer when you enter a loop:
 ```
+I'll write the code, then run it through the PHP reviewer. If issues are found
+I'll fix them automatically before showing you the final result. This may take
+a few passes — I'll let you know when it's clean.
+```
+
+---
+
+### End-of-kickoff output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Context: <repo> · Framework <fw> · Client: <client>
+Specialists on standby: php-reviewer, database-reviewer, security-reviewer, planner
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+What are you building today?
+```
+
+After the developer describes the task, present the plan (template above) and wait
+for confirmation. Then begin immediately — do not ask "shall I start?" a second time.