qatools-cli 1.1.6 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qatools-cli",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "CLI for QA Tools — requirements, epics, sprints, sessions, App Context sync, project agenda. The companion to qa-tools.com.",
   "bin": {
     "qatools": "./qatools.js"

package/qatools.js

@@ -419,6 +419,39 @@ program
     process.exit(0);
   });
 
+program
+  .command("sprint-create")
+  .description("Create a new sprint (status auto-derives from dates: planning/active/overdue)")
+  .requiredOption("--name <text>", "Sprint name")
+  .requiredOption("--end <YYYY-MM-DD>", "End date (release date)")
+  .option("--start <YYYY-MM-DD>", "Start date (optional — without it the sprint stays in planning until you set one)")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+
+    const createSprint = httpsCallable(functions, "createSprint");
+    try {
+      const result = await createSprint({
+        projectId,
+        name: options.name,
+        startDate: options.start || "",
+        releaseDate: options.end,
+      });
+      const s = result.data.sprint;
+      console.log(`Created sprint ${s.id}  ${s.name}  [${s.status}]`);
+      console.log(`  Start: ${s.startDate || "(not set)"}    End: ${s.releaseDate}`);
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
 program
   .command("backlog-create")
   .description("Create a new backlog item")
@@ -699,9 +732,11 @@ program
 
     const getCtx = httpsCallable(functions, "getAppContext");
     let ctx;
+    let systemAiRules = [];
     try {
       const result = await getCtx({ projectId });
       ctx = result.data.appContext;
+      systemAiRules = result.data.systemAiRules || [];
     } catch (e) {
       console.error("Failed to fetch App Context:", e.message);
       process.exit(1);
@@ -711,7 +746,7 @@ program
       process.exit(1);
     }
 
-    const md = renderAppContextMarkdown(ctx, projectId);
+    const md = renderAppContextMarkdown(ctx, projectId, systemAiRules);
     const beginMarker = "<!-- BEGIN qatools-context (auto-synced from qa-tools, do not edit by hand) -->";
     const endMarker = "<!-- END qatools-context -->";
     const block = `${beginMarker}\n${md}\n${endMarker}`;
@@ -792,13 +827,21 @@ program
     process.exit(0);
   });
 
-function renderAppContextMarkdown(ctx, projectId) {
+function renderAppContextMarkdown(ctx, projectId, systemAiRules) {
   const lines = [];
   const ts = new Date().toISOString();
   lines.push(`<!-- Last synced: ${ts} from project ${projectId} -->`);
   lines.push("");
   lines.push(`## ${ctx.name || "Project Context"}`);
   lines.push("");
+  // System rules first — they apply to every project, inherited from qa-tools itself
+  if (systemAiRules && systemAiRules.length) {
+    lines.push("### qa-tools System Rules (apply to every project)");
+    lines.push("> These rules are inherited by every project that uses qa-tools. They cannot be overridden — they define what qa-tools is. To see them: `qatools context`. To change them: contact the qa-tools team.");
+    lines.push("");
+    systemAiRules.forEach((r, i) => lines.push(`${i + 1}. ${r}`));
+    lines.push("");
+  }
   if (ctx.purpose) { lines.push("### Purpose"); lines.push(ctx.purpose); lines.push(""); }
   if (ctx.domainObjects?.length) {
     lines.push("### Domain Objects");
@@ -1069,6 +1112,54 @@ program
     process.exit(0);
   });
 
+program
+  .command("requirement-delete")
+  .description("Delete a requirement by id or key. Refuses if backlog/tests reference it — use --force to delete anyway.")
+  .option("-i, --id <id>", "Requirement document ID to delete")
+  .option("-k, --key <key>", "Requirement semantic key to delete (resolved to its id)")
+  .option("--force", "Delete even if backlog items or test cases reference the requirement's key (leaves them dangling, not cascade-deleted)")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    if (!options.id && !options.key) { console.error("Provide --id or --key"); process.exit(1); }
+
+    let requirementId = options.id;
+    if (!requirementId) {
+      const listReqs = httpsCallable(functions, "listRequirements");
+      const res = await listReqs({ projectId });
+      const matches = res.data.requirements.filter(r => r.key === options.key);
+      if (matches.length === 0) { console.error(`Requirement with key '${options.key}' not found.`); process.exit(1); }
+      if (matches.length > 1) {
+        console.error(`Key '${options.key}' has ${matches.length} versions — ambiguous. Delete by --id instead:`);
+        for (const m of matches) console.error(`  --id ${m.id}   v${m.version ?? "?"}  [${m.status}]  ${m.title || ""}`);
+        process.exit(1);
+      }
+      requirementId = matches[0].id;
+    }
+
+    const deleteReq = httpsCallable(functions, "deleteRequirement");
+    try {
+      const res = await deleteReq({ projectId, requirementId, force: !!options.force });
+      const d = res.data;
+      console.log(`Deleted requirement${d.key ? ` ${d.key}` : ""}${d.deletedTitle ? `: ${d.deletedTitle}` : ""}`);
+      if (d.orphanedBacklog || d.orphanedTests) {
+        const parts = [];
+        if (d.orphanedBacklog) parts.push(`${d.orphanedBacklog} backlog item(s)`);
+        if (d.orphanedTests) parts.push(`${d.orphanedTests} test case(s)`);
+        console.log(`  ⚠ ${parts.join(" and ")} now have a dangling requirementKey — re-point or clear them.`);
+      }
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
 program
   .command("template-upload")
   .description("Upload a test template JSON to the project")
@@ -1371,8 +1462,8 @@ program
 
 program
   .command("context")
-  .description("Show App Context for the project")
-  .option("-o, --output <path>", "Save to JSON file")
+  .description("Show App Context for the project, including system AI rules that apply to every qa-tools project")
+  .option("-o, --output <path>", "Save to JSON file (project context only — system rules are inherited at runtime)")
   .option("--project <id>", "Target project ID (overrides default; requires access to that project)")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
@@ -1384,10 +1475,16 @@ program
     const getCtx = httpsCallable(functions, "getAppContext");
     const result = await getCtx({ projectId });
     const ctx = result.data.appContext;
-    if (!ctx) { console.log("No App Context defined for this project."); process.exit(0); }
+    const systemRules = result.data.systemAiRules || [];
     if (options.output) {
-      fs.writeFileSync(path.resolve(options.output), JSON.stringify(ctx, null, 2));
-      console.log(`Saved to ${options.output}`);
+      fs.writeFileSync(path.resolve(options.output), JSON.stringify(ctx || {}, null, 2));
+      console.log(`Saved project context to ${options.output}`);
+      if (systemRules.length) console.log(`Note: ${systemRules.length} system AI rules are inherited at runtime, not saved to file.`);
+      process.exit(0);
+    }
+    if (!ctx) {
+      console.log("No App Context defined for this project.");
+      console.log("Run 'qatools context-template -o ctx.json' to start, then 'qatools context-set -f ctx.json' to upload.");
     } else {
       console.log(`\n${ctx.name}`);
       if (ctx.description) console.log(ctx.description);
@@ -1398,8 +1495,16 @@ program
       if (ctx.architecture) console.log(`\nArchitecture: ${ctx.architecture}`);
       if (ctx.constraints?.length) { console.log("\nConstraints:"); ctx.constraints.forEach(c => console.log(`  - ${c}`)); }
       if (ctx.conventions?.length) { console.log("\nConventions:"); ctx.conventions.forEach(c => console.log(`  - ${c.area}: ${c.rule}`)); }
+      if (ctx.aiRules?.length) { console.log("\nProject AI Rules:"); ctx.aiRules.forEach((r, i) => console.log(`  ${i + 1}. ${r}`)); }
       if (ctx.sections?.length) { ctx.sections.forEach(s => console.log(`\n${s.title}:\n  ${s.content}`)); }
     }
+    if (systemRules.length) {
+      console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+      console.log(`qa-tools System Rules (apply to every project — inherited):`);
+      console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+      systemRules.forEach((r, i) => console.log(`  ${i + 1}. ${r}`));
+      console.log(``);
+    }
     process.exit(0);
   });
 
@@ -1735,16 +1840,53 @@ program
 
 program
   .command("init")
-  .description("Initialize QA-Tools in current project (creates skills, CLAUDE.md section)")
+  .description("One command to set up everything: login + skills + sync + agenda. Just run: qatools init --api-key <key>")
   .option("-k, --api-key <key>", "Claude API key (from QA-Tools → Members → Claude AI Integration)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     const cwd = process.cwd();
-    const apiKey = options.apiKey || getCredentials()?.apiKey || "";
 
-    // 1. Create .claude/skills/ directory
+    // Step 0: Login if api-key provided and not already logged in
+    const existingCreds = getCredentials();
+    const apiKey = options.apiKey || existingCreds?.apiKey || "";
+    if (options.apiKey && (!existingCreds?.projectId || existingCreds?.apiKey !== options.apiKey)) {
+      console.log("Step 1/5: Logging in with API key...");
+      try {
+        const authRes = await fetch("https://us-central1-qatools-app.cloudfunctions.net/authenticateWithApiKey", {
+          method: "POST", headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ data: { apiKey: options.apiKey } }),
+        });
+        const authData = await authRes.json();
+        if (authData.result?.customToken) {
+          const { signInWithCustomToken } = require("firebase/auth");
+          const { getAuth } = require("firebase/auth");
+          await signInWithCustomToken(getAuth(), authData.result.customToken);
+          const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
+          const config = { apiKey: options.apiKey, projectId: authData.result.projectId, projectName: authData.result.projectName, email: authData.result.email };
+          fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+          console.log(`  ✓ Logged in: ${authData.result.projectName} (${authData.result.projectId})`);
+        } else {
+          console.error("  ✗ Invalid API key.");
+          process.exit(1);
+        }
+      } catch (e) {
+        console.error("  ✗ Login failed:", e.message);
+        process.exit(1);
+      }
+    } else if (existingCreds?.projectId) {
+      console.log(`Step 1/5: Already logged in: ${existingCreds.projectName || existingCreds.projectId}`);
+      // Ensure Firebase auth is initialized
+      try { await authenticate(options); } catch (e) { /* best effort */ }
+    } else {
+      console.log("Step 1/5: No API key provided. Run: qatools init --api-key <key>");
+      console.log("  Get your key from: qa-tools.com → your project → Members → Claude AI Integration");
+      process.exit(1);
+    }
+
+    console.log("\nStep 2/5: Writing skills...");
     const skillsDir = path.join(cwd, ".claude", "skills");
     fs.mkdirSync(skillsDir, { recursive: true });
-    console.log("Created .claude/skills/");
 
     // 2. Write skills files
     const skills = {
@@ -1879,6 +2021,7 @@ qatools requirements
 qatools requirements --status approved -o reqs.json
 qatools requirement-keys
 qatools requirement-create -f requirements.json
+qatools requirement-delete -k <key>          # Delete a wrong requirement (refuses if linked; --force to override)
 
 # Build & backlog
 qatools backlog
@@ -1900,6 +2043,7 @@ qatools upload-analysis -s <id> -f analysis.json
 # Sprints
 qatools sprints
 qatools sprint-items --sprint <id>
+qatools sprint-create --name "Release 3.2" --start 2026-05-01 --end 2026-05-28
 \`\`\`
 
 ## Key rules
@@ -2136,6 +2280,9 @@ You manage sprints, backlog, and verify release readiness.
 1. Review sprints:
    \`qatools sprints\`
    \`qatools sprint-items --sprint <id> -o sprint.json\`
+   Create a new one when starting a cycle:
+   \`qatools sprint-create --name "Release 3.2" --start 2026-05-01 --end 2026-05-28\`
+   (status auto-derives from dates: planning → active → overdue → completed)
 
 2. Break down requirements into stories/tasks:
    \`qatools backlog-create -d "Implement login flow" -t story --requirement-key auth.login-trial\`
@@ -2283,7 +2430,8 @@ If the verification fails: do NOT mark tested. Go back to step 1, find the discr
     console.log("  ✓ qa-evidence-first.md");
     console.log("  ✓ qa-numerical-verification.md");
 
-    // 4. Generate app context skill from API
+    // 4. Save built-in skills to App Context skills[] so they become editable per project.
+    // Only adds skills that don't already exist in ctx.skills[] (respects user edits).
     try {
       await authenticate(options);
       const creds = getCredentials();
@@ -2292,22 +2440,49 @@ If the verification fails: do NOT mark tested. Go back to step 1, find the discr
         const ctxResult = await getCtx({ projectId: creds.projectId });
         const ctx = ctxResult.data.appContext;
         if (ctx) {
-          let ctxSkill = `---\ndescription: App-specific context for ${ctx.name}. Auto-generated from QA-Tools App Context.\n---\n\n# ${ctx.name}\n\n`;
-          if (ctx.purpose) ctxSkill += `## Purpose\n${ctx.purpose}\n\n`;
-          if (ctx.domainObjects?.length) ctxSkill += `## Domain Objects\n${ctx.domainObjects.map(d => '- ' + d).join('\n')}\n\n`;
-          if (ctx.actors?.length) ctxSkill += `## Actors\n${ctx.actors.map(a => '- ' + a).join('\n')}\n\n`;
-          if (ctx.stack?.length) ctxSkill += `## Tech Stack\n${ctx.stack.map(s => '- **' + s.layer + ':** ' + s.technology + (s.version ? ' ' + s.version : '') + (s.notes ? ' — ' + s.notes : '')).join('\n')}\n\n`;
-          if (ctx.architecture) ctxSkill += `## Architecture\n${ctx.architecture}\n\n`;
-          if (ctx.security?.length) ctxSkill += `## Security\n${ctx.security.map(s => '- ' + s).join('\n')}\n\n`;
-          if (ctx.aiRules?.length) ctxSkill += `## AI Rules\n${ctx.aiRules.map(r => '- ' + r).join('\n')}\n\n`;
-          if (ctx.conventions?.length) ctxSkill += `## Design Principles\n${ctx.conventions.map(c => '- **' + c.area + ':** ' + c.rule).join('\n')}\n\n`;
-          if (ctx.constraints?.length) ctxSkill += `## Constraints\n${ctx.constraints.map(c => '- ' + c).join('\n')}\n\n`;
+          const existingSkills = ctx.skills || [];
+          const existingNames = new Set(existingSkills.map(s => s.filename?.replace(/\.md$/, '')));
+          let added = 0;
+          for (const [filename, content] of Object.entries(skills)) {
+            const name = filename.replace(/\.md$/, '');
+            if (existingNames.has(name)) continue; // respect user edits
+            // Extract title from first # heading in the content
+            const titleMatch = content.match(/^#\s+(.+)$/m);
+            const title = titleMatch ? titleMatch[1].trim() : name;
+            existingSkills.push({ filename: name, title, content });
+            added++;
+          }
+          if (added > 0) {
+            ctx.skills = existingSkills;
+            const saveCtx = httpsCallable(functions, "saveAppContext");
+            await saveCtx({ projectId: creds.projectId, context: ctx });
+            console.log(`\n  ✓ ${added} built-in skills saved to App Context (now editable via qatools skill add/remove)`);
+          } else {
+            console.log(`\n  ✓ All built-in skills already in App Context (editable)`);
+          }
+        }
+
+        // Generate app context skill + deploy custom skills from context
+        // Re-fetch to get updated skills[]
+        const ctxRefresh = await getCtx({ projectId: creds.projectId });
+        const ctxFinal = ctxRefresh.data.appContext;
+        if (ctxFinal) {
+          let ctxSkill = `---\ndescription: App-specific context for ${ctxFinal.name}. Auto-generated from QA-Tools App Context.\n---\n\n# ${ctxFinal.name}\n\n`;
+          if (ctxFinal.purpose) ctxSkill += `## Purpose\n${ctxFinal.purpose}\n\n`;
+          if (ctxFinal.domainObjects?.length) ctxSkill += `## Domain Objects\n${ctxFinal.domainObjects.map(d => '- ' + d).join('\n')}\n\n`;
+          if (ctxFinal.actors?.length) ctxSkill += `## Actors\n${ctxFinal.actors.map(a => '- ' + a).join('\n')}\n\n`;
+          if (ctxFinal.stack?.length) ctxSkill += `## Tech Stack\n${ctxFinal.stack.map(s => '- **' + s.layer + ':** ' + s.technology + (s.version ? ' ' + s.version : '') + (s.notes ? ' — ' + s.notes : '')).join('\n')}\n\n`;
+          if (ctxFinal.architecture) ctxSkill += `## Architecture\n${ctxFinal.architecture}\n\n`;
+          if (ctxFinal.security?.length) ctxSkill += `## Security\n${ctxFinal.security.map(s => '- ' + s).join('\n')}\n\n`;
+          if (ctxFinal.aiRules?.length) ctxSkill += `## AI Rules\n${ctxFinal.aiRules.map(r => '- ' + r).join('\n')}\n\n`;
+          if (ctxFinal.conventions?.length) ctxSkill += `## Design Principles\n${ctxFinal.conventions.map(c => '- **' + c.area + ':** ' + c.rule).join('\n')}\n\n`;
+          if (ctxFinal.constraints?.length) ctxSkill += `## Constraints\n${ctxFinal.constraints.map(c => '- ' + c).join('\n')}\n\n`;
           fs.writeFileSync(path.join(skillsDir, "app-context.md"), ctxSkill);
           console.log("  ✓ app-context.md (from project)");
 
           // Generate custom skills from App Context
-          if (ctx.skills?.length) {
-            for (const skill of ctx.skills) {
+          if (ctxFinal.skills?.length) {
+            for (const skill of ctxFinal.skills) {
               const fname = skill.filename.endsWith('.md') ? skill.filename : skill.filename + '.md';
               const content = `---\ndescription: ${skill.title}\n---\n\n# ${skill.title}\n\n${skill.content}\n`;
               fs.writeFileSync(path.join(skillsDir, fname), content);
@@ -2344,6 +2519,7 @@ export QATOOLS_API_KEY=${apiKey || "<din-nyckel>"}
 - \`qatools upload-analysis -s <id> -f analysis.json\` — upload analysis
 - \`qatools requirement-create -f file.json\` — create requirements
 - \`qatools requirement-update -i <id> --status tested --evidence "..."\` — mark verified (evidence required)
+- \`qatools requirement-delete -k <key>\` — delete a wrong requirement (refuses if backlog/tests link it; --force to override)
 - \`qatools template-upload -f file.json\` — upload test template
 - \`qatools backlog-create -d "..." -t bug\` — create backlog item
 - \`qatools backlog-update -i <id> --status resolved --evidence "..."\` — mark resolved (evidence required)
@@ -2366,41 +2542,420 @@ See \`.claude/skills/\` for role-specific instructions. Start with \`qa-purpose.
       console.log("\n✓ Created CLAUDE.md with QA-Tools section");
     }
 
-    // 5. Final purpose-first banner — check App Context state and tell the AI/user what to do
-    let contextStateMessage = "";
+    // Step 4/5: Sync App Context into CLAUDE.md
+    console.log("\nStep 4/5: Syncing App Context into CLAUDE.md...");
     try {
       const creds = getCredentials();
       if (creds?.projectId) {
-        const getCtx = httpsCallable(functions, "getAppContext");
-        const ctxResult = await getCtx({ projectId: creds.projectId });
-        const ctx = ctxResult.data.appContext;
-        if (!ctx || (!ctx.purpose && !(ctx.stack || []).length && !(ctx.aiRules || []).length)) {
-          contextStateMessage = "\n⚠ App Context is empty for this project.\n   Without it, the AI has no basis for substituting for you.\n   First step: open https://qa-tools.com and define App Context (purpose, stack, conventions, AI rules)\n   or upload a JSON via: qatools context-set -f context.json\n";
+        const getCtx2 = httpsCallable(functions, "getAppContext");
+        const syncResult = await getCtx2({ projectId: creds.projectId });
+        const syncCtx = syncResult.data.appContext;
+        const systemRules = syncResult.data.systemAiRules || [];
+        if (syncCtx) {
+          // Use the same sync logic as qatools sync
+          const syncMd = renderAppContextMarkdown(syncCtx, creds.projectId, systemRules);
+          const beginMarker = "<!-- BEGIN qatools-context (auto-synced from qa-tools, do not edit by hand) -->";
+          const endMarker = "<!-- END qatools-context -->";
+          const block = `${beginMarker}\n${syncMd}\n${endMarker}`;
+          const syncPath = fs.existsSync(path.join(cwd, ".claude", "CLAUDE.md")) ? path.join(cwd, ".claude", "CLAUDE.md") : claudeMdPath;
+          let existing = fs.existsSync(syncPath) ? fs.readFileSync(syncPath, "utf8") : "";
+          const beginIdx = existing.indexOf(beginMarker);
+          const endIdx = existing.indexOf(endMarker);
+          if (beginIdx >= 0 && endIdx > beginIdx) {
+            existing = existing.slice(0, beginIdx) + block + existing.slice(endIdx + endMarker.length);
+          } else {
+            existing = existing + (existing && !existing.endsWith("\n") ? "\n\n" : "\n") + block + "\n";
+          }
+          fs.writeFileSync(syncPath, existing);
+          console.log(`  ✓ Synced to ${path.relative(cwd, syncPath)}`);
+
+          // App Context state
+          if (!syncCtx.purpose && !(syncCtx.stack || []).length) {
+            console.log("\n  ⚠ App Context is empty for this project.");
+            console.log("    Without it, the AI has no basis for substituting for you.");
+            console.log("    Run: qatools context-template -o ctx.json → edit → qatools context-set -f ctx.json");
+          } else {
+            const lastSync = syncCtx.updatedAt?._seconds ? new Date(syncCtx.updatedAt._seconds * 1000).toISOString().split('T')[0] : 'unknown';
+            console.log(`  ✓ App Context loaded (last updated: ${lastSync})`);
+          }
         } else {
-          const lastSync = ctx.updatedAt?._seconds ? new Date(ctx.updatedAt._seconds * 1000).toISOString().split('T')[0] : 'unknown';
-          contextStateMessage = `\n✓ App Context loaded (last updated: ${lastSync})\n`;
+          console.log("  ⚠ No App Context defined. Create one: qatools context-template -o ctx.json → edit → qatools context-set -f ctx.json");
         }
       }
     } catch (e) {
-      // Best-effort — don't block init on this check
+      console.log(`  ⚠ Sync skipped (${e.message})`);
+    }
+
+    // Step 5/5: Show agenda
+    console.log("\nStep 5/5: Project agenda\n");
+    try {
+      const creds = getCredentials();
+      if (creds?.projectId) {
+        const getAgenda = httpsCallable(functions, "getProjectAgenda");
+        const agendaResult = await getAgenda({ projectId: creds.projectId });
+        const data = agendaResult.data;
+        const sections = [];
+        if (data.agenda.pendingSessions?.length) {
+          sections.push(`  🔴 ${data.agenda.pendingSessions.length} session(s) waiting for analysis`);
+        }
+        if (data.agenda.approvedNoCoverage?.length) {
+          sections.push(`  🟡 ${data.agenda.approvedNoCoverage.length} approved requirement(s) without test coverage`);
+        }
+        if (data.agenda.draftReqs?.length) {
+          sections.push(`  ⚪ ${data.agenda.draftReqs.length} draft requirement(s) need acceptance criteria / approval`);
+        }
+        if (data.agenda.accessModelMissing) {
+          sections.push(`  ⚪ No access model defined — run: qatools access show`);
+        }
+        if (sections.length === 0) {
+          console.log("  ✓ Nothing on the agenda. The project is in a clean state.");
+        } else {
+          for (const s of sections) console.log(s);
+          console.log(`\n  ${data.totalCount} thing(s) on the agenda.`);
+        }
+      }
+    } catch (e) {
+      console.log(`  Could not load agenda (${e.message}). Run: qatools next`);
     }
 
     console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🎉 QA-Tools initialized!
 
 ⚠ READ THIS FIRST: .claude/skills/qa-purpose.md
 
-   qa-tools exists to let anyone build production-quality apps with AI
-   that follow their own rules — as if you built it yourself, just faster.
-   The AI is not an assistant. It is a substitute for the developer.
-   Read qa-purpose.md before doing anything else in this project.
-${contextStateMessage}
-Next steps for the AI in this project:
-  1. qatools context     — read the project's rule book
-  2. qatools epics       — see what capabilities exist
-  3. qatools next        — see what's on the agenda
+   qa-tools exists to let anyone build production-quality apps
+   with AI that follow their own rules — as if you built it
+   yourself, just faster.
+
+   The AI is not an assistant. It is a substitute.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `);
-    if (!apiKey) console.log("⚠ No API key set. Add it to CLAUDE.md: export QATOOLS_API_KEY=<key>\n");
+    process.exit(0);
+  });
+
+program
+// Skill library metadata — names and descriptions of the built-in skills shipped by qatools init.
+// The full content lives in the init action above (huge template literals). This is just metadata
+// for `qatools skill list` and `qatools skill add` to reference by name.
+const BUILTIN_SKILLS = [
+  { name: "qa-purpose", description: "Read this BEFORE anything else. The purpose of qa-tools and what it expects from you as AI." },
+  { name: "qa-loop", description: "Overview of the QA-Tools delivery loop — from requirement to verified release." },
+  { name: "qa-requirement-analyst", description: "Analyze the codebase and define requirements that are testable, traceable, and complete." },
+  { name: "qa-developer", description: "Implement features based on approved requirements. Use when building new functionality." },
+  { name: "qa-test-generator", description: "Generate test protocols from approved requirements." },
+  { name: "qa-test-analyst", description: "Analyze test results, identify root causes, create backlog items." },
+  { name: "qa-release-manager", description: "Sprint planning and release verification." },
+  { name: "qa-evidence-first", description: "Core principle — never speculate, always cite evidence. Applies to ALL work." },
+  { name: "qa-numerical-verification", description: "How to verify algorithmic and numerical bug fixes." },
+];
+
+const skillCmd = program
+  .command("skill")
+  .description("Manage skills — the instruction files Claude reads in .claude/skills/");
+
+// --- Library subcommands (global, not per-project) ---
+
+const libraryCmd = skillCmd
+  .command("library")
+  .description("Manage the global skill library (shared across all projects)");
+
+libraryCmd
+  .command("list")
+  .description("List all skills in the global library")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const listSkills = httpsCallable(functions, "listSkillLibrary");
+    try {
+      const result = await listSkills({});
+      const skills = result.data.skills;
+      if (skills.length === 0) {
+        console.log("Skill library is empty. Seed it with: qatools skill library add -f <file.md>");
+        process.exit(0);
+      }
+      console.log(`\nSkill Library (${skills.length} skills):\n`);
+      for (const s of skills) {
+        console.log(`  ${s.name.padEnd(30)} v${s.version}  ${s.title}`);
+        if (s.description) console.log(`  ${''.padEnd(30)}      ${s.description}`);
+      }
+      console.log("");
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+libraryCmd
+  .command("show")
+  .description("Show the full content of a skill from the library")
+  .requiredOption("-n, --name <name>", "Skill name (e.g. qa-purpose)")
+  .option("-o, --output <path>", "Save to file instead of stdout")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const getSkill = httpsCallable(functions, "getLibrarySkill");
+    try {
+      const result = await getSkill({ name: options.name });
+      const skill = result.data.skill;
+      if (!skill) { console.error(`Skill '${options.name}' not found in library.`); process.exit(1); }
+      if (options.output) {
+        fs.writeFileSync(path.resolve(options.output), skill.content);
+        console.log(`Saved to ${options.output}`);
+      } else {
+        console.log(skill.content);
+      }
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+libraryCmd
+  .command("add")
+  .description("Add or update a skill in the global library from a .md file")
+  .requiredOption("-f, --file <path>", "Path to .md file")
+  .option("-n, --name <name>", "Skill name (default: filename without .md)")
+  .option("-d, --description <text>", "Short description")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const filePath = path.resolve(options.file);
+    if (!fs.existsSync(filePath)) { console.error(`File not found: ${filePath}`); process.exit(1); }
+    const content = fs.readFileSync(filePath, "utf8");
+    const name = options.name || path.basename(filePath, ".md");
+    // Extract title from frontmatter or first heading
+    let title = name;
+    const descMatch = content.match(/^description:\s*(.+)$/m);
+    if (descMatch) title = descMatch[1].trim();
+    else {
+      const headingMatch = content.match(/^#\s+(.+)$/m);
+      if (headingMatch) title = headingMatch[1].trim();
+    }
+    const saveSkill = httpsCallable(functions, "saveLibrarySkill");
+    try {
+      const result = await saveSkill({ name, title, description: options.description || "", content });
+      console.log(`Skill '${name}' saved to library (v${result.data.version})`);
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+libraryCmd
+  .command("remove")
+  .description("Remove a skill from the global library")
+  .requiredOption("-n, --name <name>", "Skill name to remove")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const deleteSkill = httpsCallable(functions, "deleteLibrarySkill");
+    try {
+      await deleteSkill({ name: options.name });
+      console.log(`Removed '${options.name}' from library.`);
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+// --- Per-project skill subcommands ---
+
+skillCmd
+  .command("list")
+  .description("List skills: global library + what this project has selected")
+  .option("--project <id>", "Target project ID")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    // 1. Show global library
+    try {
+      const listSkills = httpsCallable(functions, "listSkillLibrary");
+      const libResult = await listSkills({});
+      const libSkills = libResult.data.skills;
+      if (libSkills.length) {
+        console.log(`\nGlobal Skill Library (${libSkills.length}):\n`);
+        for (const s of libSkills) console.log(`  ${s.name.padEnd(30)} v${s.version}  ${s.title}`);
+      } else {
+        console.log("\nGlobal Skill Library: empty. Seed with: qatools skill library add -f <file.md>");
+      }
+    } catch (e) {
+      console.log("\nGlobal Skill Library: could not load (" + e.message + ")");
+    }
+    // 2. Show project skills
+    try {
+      const creds = getCredentials();
+      const projectId = options.project || creds?.projectId;
+      if (projectId) {
+        const getCtx = httpsCallable(functions, "getAppContext");
+        const result = await getCtx({ projectId });
+        const custom = result.data.appContext?.skills || [];
+        if (custom.length) {
+          console.log(`\nProject skills (${custom.length}):\n`);
+          for (const s of custom) console.log(`  ${(s.filename || '').padEnd(30)} ${s.title || ''}`);
+        } else {
+          console.log(`\nProject skills: none. Add from library: qatools skill add <name>`);
+        }
+      }
+    } catch (e) {
+      // best effort
+    }
+    console.log("");
+    process.exit(0);
+  });
+
+skillCmd
+  .command("add")
+  .description("Add a skill to the project — from the global library (by name) or from a local .md file")
+  .option("-n, --name <name>", "Skill name from the global library (e.g. qa-purpose)")
+  .option("-f, --file <path>", "Path to a local .md skill file")
+  .option("--project <id>", "Target project ID")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    if (!options.name && !options.file) { console.error("Provide --name <library-skill> or --file <path>"); process.exit(1); }
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured."); process.exit(1); }
+
+    let filename, title, content;
+
+    if (options.name) {
+      // Fetch from global library
+      const getSkill = httpsCallable(functions, "getLibrarySkill");
+      const skillResult = await getSkill({ name: options.name });
+      const skill = skillResult.data.skill;
+      if (!skill) { console.error(`Skill '${options.name}' not found in the global library. Run 'qatools skill library list' to see available skills.`); process.exit(1); }
+      filename = skill.name;
+      title = skill.title;
+      content = skill.content;
+      console.log(`Fetched '${filename}' v${skill.version} from global library.`);
+    } else {
+      // From local file
+      const filePath = path.resolve(options.file);
+      if (!fs.existsSync(filePath)) { console.error(`File not found: ${filePath}`); process.exit(1); }
+      content = fs.readFileSync(filePath, "utf8");
+      filename = path.basename(filePath, ".md");
+      title = filename;
+      const descMatch = content.match(/^description:\s*(.+)$/m);
+      if (descMatch) title = descMatch[1].trim();
+      else {
+        const headingMatch = content.match(/^#\s+(.+)$/m);
+        if (headingMatch) title = headingMatch[1].trim();
+      }
+    }
+
+    // Load context, add to skills[], save
+    const getCtx = httpsCallable(functions, "getAppContext");
+    const result = await getCtx({ projectId });
+    const ctx = result.data.appContext || {};
+    const skills = ctx.skills || [];
+    const existing = skills.findIndex(s => s.filename === filename);
+    if (existing >= 0) {
+      skills[existing] = { filename, title, content };
+      console.log(`Updated existing project skill: ${filename}`);
+    } else {
+      skills.push({ filename, title, content });
+      console.log(`Added to project: ${filename}`);
+    }
+    ctx.skills = skills;
+    const saveCtx = httpsCallable(functions, "saveAppContext");
+    await saveCtx({ projectId, context: ctx });
+    console.log(`Saved. Deploy with: qatools skill deploy`);
+    process.exit(0);
+  });
+
+skillCmd
+  .command("remove")
+  .description("Remove a custom skill from the project's App Context")
+  .requiredOption("-n, --name <filename>", "Skill filename (without .md)")
+  .option("--project <id>", "Target project ID")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured."); process.exit(1); }
+    const getCtx = httpsCallable(functions, "getAppContext");
+    const result = await getCtx({ projectId });
+    const ctx = result.data.appContext;
+    if (!ctx) { console.error("No App Context for this project."); process.exit(1); }
+    const skills = ctx.skills || [];
+    const idx = skills.findIndex(s => s.filename === options.name || s.filename === options.name + '.md');
+    if (idx < 0) { console.error(`Skill "${options.name}" not found in project skills.`); process.exit(1); }
+    const removed = skills.splice(idx, 1)[0];
+    ctx.skills = skills;
+    const saveCtx = httpsCallable(functions, "saveAppContext");
+    await saveCtx({ projectId, context: ctx });
+    console.log(`Removed: ${removed.filename} ("${removed.title}")`);
+    console.log(`Deploy with: qatools skill deploy`);
+    process.exit(0);
+  });
+
+skillCmd
+  .command("deploy")
+  .description("Write all skills (built-in + project custom) to .claude/skills/ in the current directory")
+  .option("--project <id>", "Target project ID")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    const cwd = process.cwd();
+    const skillsDir = path.join(cwd, ".claude", "skills");
+    fs.mkdirSync(skillsDir, { recursive: true });
+    // 1. Deploy built-in skills from init (run init logic for skills only)
+    // We re-use the init action's skill writing. For now, tell user to run init for built-ins.
+    console.log("Deploying skills to .claude/skills/\n");
+    // 2. Deploy project custom skills from App Context
+    let customCount = 0;
+    try {
+      await authenticate(options);
+      const creds = getCredentials();
+      const projectId = options.project || creds?.projectId;
+      if (projectId) {
+        const getCtx = httpsCallable(functions, "getAppContext");
+        const result = await getCtx({ projectId });
+        const ctx = result.data.appContext;
+        if (ctx?.skills?.length) {
+          for (const skill of ctx.skills) {
+            const fname = skill.filename.endsWith('.md') ? skill.filename : skill.filename + '.md';
+            const content = `---\ndescription: ${skill.title}\n---\n\n# ${skill.title}\n\n${skill.content}\n`;
+            fs.writeFileSync(path.join(skillsDir, fname), content);
+            console.log(`  ✓ ${fname} (project custom)`);
+            customCount++;
+          }
+        }
+        // Also deploy app-context skill
+        if (ctx) {
+          let ctxSkill = `---\ndescription: App-specific context for ${ctx.name}. Auto-generated from QA-Tools App Context.\n---\n\n# ${ctx.name}\n\n`;
+          if (ctx.purpose) ctxSkill += `## Purpose\n${ctx.purpose}\n\n`;
+          if (ctx.domainObjects?.length) ctxSkill += `## Domain Objects\n${ctx.domainObjects.map(d => '- ' + d).join('\n')}\n\n`;
+          if (ctx.actors?.length) ctxSkill += `## Actors\n${ctx.actors.map(a => '- ' + a).join('\n')}\n\n`;
+          if (ctx.stack?.length) ctxSkill += `## Tech Stack\n${ctx.stack.map(s => '- **' + s.layer + ':** ' + s.technology + (s.version ? ' ' + s.version : '') + (s.notes ? ' — ' + s.notes : '')).join('\n')}\n\n`;
+          if (ctx.architecture) ctxSkill += `## Architecture\n${ctx.architecture}\n\n`;
+          if (ctx.security?.length) ctxSkill += `## Security\n${ctx.security.map(s => '- ' + s).join('\n')}\n\n`;
+          if (ctx.aiRules?.length) ctxSkill += `## AI Rules\n${ctx.aiRules.map(r => '- ' + r).join('\n')}\n\n`;
+          if (ctx.conventions?.length) ctxSkill += `## Design Principles\n${ctx.conventions.map(c => '- **' + c.area + ':** ' + c.rule).join('\n')}\n\n`;
+          if (ctx.constraints?.length) ctxSkill += `## Constraints\n${ctx.constraints.map(c => '- ' + c).join('\n')}\n\n`;
+          fs.writeFileSync(path.join(skillsDir, "app-context.md"), ctxSkill);
+          console.log(`  ✓ app-context.md (from project)`);
+        }
+      }
+    } catch (e) {
+      console.error(`  Note: could not load project context (${e.message}). Only local files written.`);
+    }
+    console.log(`\nDone. ${customCount} project skill(s) deployed.`);
+    console.log(`Built-in skills are deployed by 'qatools init'. Run init if they're missing.`);
     process.exit(0);
   });