@torus-engineering/tas-kit 1.6.0 → 1.8.0

package/.tas/templates/Story.md

@@ -1,88 +1,90 @@
----
-ado_id:
-ado_type: User Story
-ado_title: "{Title}"
-ado_state: New
-ado_assigned_to:
-ado_created:
-last_ado_sync:
-parent_ado_id:
-plan_status: pending
-plan_date:
----
-# Story-{NNN}: {Title}
-
-> **Status:** New | Committed | In Progress | Deploy Test | Verify Test | Deploy Stag | Verify Stag | Deploy Prod | Verify Prod | Done
-> **Feature:** Feature-{NNN}
-> **Assigned to:** {SE name}
-> **Estimate:** {S/M/L}
-> **Created:** {Date}
-
-## User Story
-As a {role}, I want {goal}, so that {benefit}.
-
----
-## Business Requirements (nếu có)
-*(Yêu cầu nghiệp vụ đặc biệt, business rules, constraints từ stakeholders — chỉ thêm khi cần)*
-
----
-## Design Notes (nếu có)
-*(UI/UX specs, mockup links, design decisions, flow diagrams — chỉ thêm khi cần)*
-
----
-## Prerequisites (nếu có)
-*(Dependencies từ Stories khác hoặc điều kiện phải có trước — chỉ thêm khi cần)*
-
----
-## Acceptance Criteria
-
-### AC-1: {title}
-- **Given** {precondition}
-- **When** {action}
-- **Then** {expected result}
-
-### AC-2: {title}
-- **Given** {precondition}
-- **When** {action}
-- **Then** {expected result}
-
----
-## Unit Test Cases
-*(PE thiết kế happy path + edge cases + negative cases. SE implement trong code.)*
-
-### Happy Path
-| ID | Description | Input | Expected Output |
-|----|-------------|-------|-----------------|
-| UT-1 | {description} | {input} | {expected} |
-
-### Edge Cases
-| ID | Description | Input | Expected Output |
-|----|-------------|-------|-----------------|
-| UT-E1 | {description} | {input} | {expected} |
-
-### Negative Cases
-| ID | Description | Input | Expected Output |
-|----|-------------|-------|-----------------|
-| UT-N1 | {description} | {input} | {expected} |
-
-### Dependencies to Mock
-- {external API, database state, third-party service...}
-
----
-<!-- ═══════════════════════════════════════════════════════════════════
-     TECHNICAL PLAN — generated by /tas-plan, do not edit manually
-     ═══════════════════════════════════════════════════════════════════ -->
-
----
-## Definition of Done
-- [ ] Technical plan completed (`/tas-plan`)
-- [ ] Code implemented
-- [ ] Unit tests pass
-- [ ] Code review passed
-- [ ] Acceptance criteria verified
-- [ ] No regression
-- [ ] Documentation updated (if needed)
-
-## Changelog
-| Date | Changes | Author |
-|------|---------|--------|
+---
+ado_id:
+ado_type: User Story
+ado_title: "{Title}"
+ado_state: New
+ado_assigned_to:
+ado_created:
+last_ado_sync:
+parent_ado_id:
+plan_status: pending
+plan_date:
+---
+# Story-{NNN}: {Title}
+
+> **Status:** New | Committed | In Progress | Deploy Test | Verify Test | Deploy Stag | Verify Stag | Deploy Prod | Verify Prod | Done
+> **Feature:** Feature-{NNN}
+> **Assigned to:** {SE name}
+> **Estimate:** {S/M/L}
+> **Created:** {Date}
+
+## User Story
+As a {role}, I want {goal}, so that {benefit}.
+
+---
+## Business Requirements (nếu có)
+*(Yêu cầu nghiệp vụ đặc biệt, business rules, constraints từ stakeholders — chỉ thêm khi cần)*
+
+---
+## Design Notes (nếu có)
+*(UI/UX specs, mockup links, design decisions, flow diagrams — chỉ thêm khi cần)*
+
+---
+## Prerequisites (nếu có)
+*(Dependencies từ Stories khác hoặc điều kiện phải có trước — chỉ thêm khi cần)*
+
+---
+## Acceptance Criteria
+
+### AC-1: {title}
+- **Given** {precondition}
+- **When** {action}
+- **Then** {expected result}
+- **Functional Tests**: *(điền FT IDs sau khi chạy `/tas-functest` — vd: `{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H`, `FT_002_N`)*
+
+### AC-2: {title}
+- **Given** {precondition}
+- **When** {action}
+- **Then** {expected result}
+- **Functional Tests**: *(điền FT IDs sau khi chạy `/tas-functest`)*
+
+---
+## Unit Test Cases
+*(PE thiết kế happy path + edge cases + negative cases. SE implement trong code.)*
+
+### Happy Path
+| ID | AC Ref | Description | Input | Expected Output |
+|----|--------|-------------|-------|-----------------|
+| UT-1 | AC-1 | {description} | {input} | {expected} |
+
+### Edge Cases
+| ID | AC Ref | Description | Input | Expected Output |
+|----|--------|-------------|-------|-----------------|
+| UT-E1 | AC-1 | {description} | {input} | {expected} |
+
+### Negative Cases
+| ID | AC Ref | Description | Input | Expected Output |
+|----|--------|-------------|-------|-----------------|
+| UT-N1 | AC-1 | {description} | {input} | {expected} |
+
+### Dependencies to Mock
+- {external API, database state, third-party service...}
+
+---
+<!-- ═══════════════════════════════════════════════════════════════════
+     TECHNICAL PLAN — generated by /tas-plan, do not edit manually
+     ═══════════════════════════════════════════════════════════════════ -->
+
+---
+## Definition of Done
+- [ ] Technical plan completed (`/tas-plan`)
+- [ ] Code implemented
+- [ ] Unit tests pass
+- [ ] Code review passed
+- [ ] Acceptance criteria verified
+- [ ] No regression
+- [ ] Documentation updated (if needed)
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

package/bin/cli.js

@@ -1,49 +1,56 @@
-#!/usr/bin/env node
-import { install } from '../lib/install.js';
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-function printHelp() {
-  console.log(`
-tas-kit — Torus Agentic SDLC Kit installer
-
-Usage:
-  npx @torus-engineering/tas-kit install [options]
-
-Options:
-  --directory <path>   Target directory (default: current working directory)
-  --yes, -y            Skip confirmation prompts
-  --help, -h           Show this help message
-
-Examples:
-  npx @torus-engineering/tas-kit install
-  npx @torus-engineering/tas-kit install --directory /path/to/my-project
-  npx @torus-engineering/tas-kit install --yes
-  `.trim());
-}
-
-if (!command || command === '--help' || command === '-h') {
-  printHelp();
-  process.exit(0);
-}
-
-if (command !== 'install') {
-  console.error(`Unknown command: "${command}"\n`);
-  printHelp();
-  process.exit(1);
-}
-
-const opts = { directory: process.cwd(), yes: false };
-for (let i = 1; i < args.length; i++) {
-  if ((args[i] === '--directory' || args[i] === '-d') && args[i + 1]) {
-    opts.directory = args[++i];
-  } else if (args[i] === '--yes' || args[i] === '-y') {
-    opts.yes = true;
-  }
-}
-
-install(opts).catch((err) => {
-  console.error('\nInstall failed:', err.message);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { install, update } from '../lib/install.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+tas-kit — Torus Agentic SDLC Kit installer
+
+Usage:
+  npx @torus-engineering/tas-kit <command> [options]
+
+Commands:
+  install   Copy TAS Kit files into a project (first-time setup)
+  update    Overwrite .claude/ and .tas/ with the latest kit version
+            (preserves CLAUDE.md, tas.yaml, .env.example)
+
+Options:
+  --directory <path>   Target directory (default: current working directory)
+  --yes, -y            Skip confirmation prompts
+  --help, -h           Show this help message
+
+Examples:
+  npx @torus-engineering/tas-kit install
+  npx @torus-engineering/tas-kit install --directory /path/to/my-project
+  npx @torus-engineering/tas-kit update
+  npx @torus-engineering/tas-kit update --yes
+  `.trim());
+}
+
+if (!command || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (command !== 'install' && command !== 'update') {
+  console.error(`Unknown command: "${command}"\n`);
+  printHelp();
+  process.exit(1);
+}
+
+const opts = { directory: process.cwd(), yes: false };
+for (let i = 1; i < args.length; i++) {
+  if ((args[i] === '--directory' || args[i] === '-d') && args[i + 1]) {
+    opts.directory = args[++i];
+  } else if (args[i] === '--yes' || args[i] === '-y') {
+    opts.yes = true;
+  }
+}
+
+const runner = command === 'update' ? update : install;
+runner(opts).catch((err) => {
+  console.error(`\n${command === 'update' ? 'Update' : 'Install'} failed:`, err.message);
+  process.exit(1);
+});

package/lib/deleted-files.json

@@ -0,0 +1,33 @@
+{
+  "1.6.0": [
+    ".claude/commands/tas-dev-story.md",
+    ".claude/commands/tas-review-code.md",
+    ".claude/commands/tas-security-check.md"
+  ],
+  "1.8.0": [
+    ".claude/agents/README.md",
+    ".claude/agents/ado-agent.md",
+    ".claude/agents/code-architect.md",
+    ".claude/agents/code-simplifier.md",
+    ".claude/agents/comment-analyzer.md",
+    ".claude/agents/conversation-analyzer.md",
+    ".claude/agents/docs-lookup.md",
+    ".claude/agents/harness-optimizer.md",
+    ".claude/agents/loop-operator.md",
+    ".claude/agents/performance-optimizer.md",
+    ".claude/agents/pr-test-analyzer.md",
+    ".claude/agents/pytorch-build-resolver.md",
+    ".claude/agents/refactor-cleaner.md",
+    ".claude/agents/seo-specialist.md",
+    ".claude/agents/silent-failure-hunter.md",
+    ".claude/agents/type-design-analyzer.md",
+    ".claude/rules/common/agents.md",
+    ".claude/rules/common/coding-style.md",
+    ".claude/rules/common/development-workflow.md",
+    ".claude/rules/common/git-workflow.md",
+    ".claude/rules/common/performance.md",
+    ".claude/skills/agent-harness-construction/SKILL.md",
+    ".claude/skills/agent-introspection-debugging/SKILL.md",
+    ".claude/skills/backend-patterns/SKILL.md"
+  ]
+}

package/lib/install.js

@@ -1,114 +1,213 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import readline from 'node:readline';
-import { fileURLToPath } from 'node:url';
-
-const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-async function confirm(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(`${question} [y/N] `, (answer) => {
-      rl.close();
-      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
-    });
-  });
-}
-
-async function exists(p) {
-  return fs.access(p).then(() => true).catch(() => false);
-}
-
-async function copyDir(src, dest) {
-  await fs.cp(src, dest, { recursive: true });
-}
-
-export async function install({ directory, yes }) {
-  const target = path.resolve(directory);
-
-  // Ensure target directory exists
-  await fs.mkdir(target, { recursive: true });
-
-  console.log(`\nInstalling TAS Kit into: ${target}\n`);
-
-  // Warn if .claude/ or .tas/ already exist
-  const claudeExists = await exists(path.join(target, '.claude'));
-  const tasExists = await exists(path.join(target, '.tas'));
-
-  if ((claudeExists || tasExists) && !yes) {
-    const existing = [claudeExists && '.claude/', tasExists && '.tas/'].filter(Boolean).join(', ');
-    console.warn(`  WARNING: ${existing} already exist in target directory.`);
-    console.warn(`  Existing files with the same names will be overwritten.\n`);
-    const ok = await confirm('Continue?');
-    if (!ok) {
-      console.log('Installation cancelled.');
-      process.exit(0);
-    }
-    console.log();
-  }
-
-  // Copy .claude/
-  await copyDir(
-    path.join(PACKAGE_DIR, '.claude'),
-    path.join(target, '.claude')
-  );
-  console.log('  [ok] .claude/');
-
-  // Copy .tas/
-  await copyDir(
-    path.join(PACKAGE_DIR, '.tas'),
-    path.join(target, '.tas')
-  );
-  console.log('  [ok] .tas/');
-
-  // Copy CLAUDE-Example.md as CLAUDE.md (only if absent)
-  const claudeMdTarget = path.join(target, 'CLAUDE.md');
-  if (!(await exists(claudeMdTarget))) {
-    await fs.copyFile(
-      path.join(PACKAGE_DIR, 'CLAUDE-Example.md'),
-      claudeMdTarget
-    );
-    console.log('  [ok] CLAUDE.md (from CLAUDE-Example.md)');
-  } else {
-    console.log('  [--] CLAUDE.md already exists, skipped');
-  }
-
-  // Copy .env.example
-  await fs.copyFile(
-    path.join(PACKAGE_DIR, '.env.example'),
-    path.join(target, '.env.example')
-  );
-  console.log('  [ok] .env.example');
-
-  // Copy tas-example.yaml as tas.yaml (only if absent)
-  const tasYamlTarget = path.join(target, 'tas.yaml');
-  if (!(await exists(tasYamlTarget))) {
-    await fs.copyFile(
-      path.join(PACKAGE_DIR, '.tas', 'tas-example.yaml'),
-      tasYamlTarget
-    );
-    console.log('  [ok] tas.yaml (from .tas/tas-example.yaml)');
-  } else {
-    console.log('  [--] tas.yaml already exists, skipped');
-  }
-
-  // Set executable bit on tas-ado.py (Unix/macOS)
-  if (process.platform !== 'win32') {
-    const adoPy = path.join(target, '.tas', 'tools', 'tas-ado.py');
-    if (await exists(adoPy)) {
-      await fs.chmod(adoPy, 0o755);
-    }
-  }
-
-  console.log(`
-TAS Kit installed successfully!
-
-Next steps:
-  1. Edit CLAUDE.md     — add your project's tech stack and conventions
-  2. Edit tas.yaml      — set project name, team and ADO config
-  3. Create .env        — add AZURE_DEVOPS_PAT (see .env.example)
-  4. Open Claude Code   — run /tas-init to initialize your project
-
-Docs: .tas/README.md
-  `);
-}
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+
+async function getDeletedFiles() {
+  try {
+    const manifest = require('./deleted-files.json');
+    return Object.values(manifest).flat();
+  } catch {
+    return [];
+  }
+}
+
+async function removeDeletedFiles(target, deletedFiles) {
+  const removed = [];
+  const skipped = [];
+  for (const relPath of deletedFiles) {
+    const fullPath = path.join(target, relPath);
+    try {
+      await fs.rm(fullPath, { force: false });
+      removed.push(relPath);
+    } catch {
+      skipped.push(relPath);
+    }
+  }
+  return { removed, skipped };
+}
+
+async function confirm(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+async function exists(p) {
+  return fs.access(p).then(() => true).catch(() => false);
+}
+
+async function copyDir(src, dest) {
+  await fs.cp(src, dest, { recursive: true });
+}
+
+export async function update({ directory, yes }) {
+  const target = path.resolve(directory);
+
+  // Must already have .claude/ or .tas/ — otherwise suggest install
+  const claudeExists = await exists(path.join(target, '.claude'));
+  const tasExists = await exists(path.join(target, '.tas'));
+  if (!claudeExists && !tasExists) {
+    console.error(`  ERROR: No TAS Kit found in: ${target}`);
+    console.error(`  Run "install" first to set up TAS Kit.`);
+    process.exit(1);
+  }
+
+  console.log(`\nUpdating TAS Kit in: ${target}\n`);
+
+  if (!yes) {
+    console.warn(`  This will overwrite .claude/ and .tas/ with the latest kit files.`);
+    console.warn(`  Your CLAUDE.md, tas.yaml, and .env.example will NOT be touched.\n`);
+    const ok = await confirm('Continue?');
+    if (!ok) {
+      console.log('Update cancelled.');
+      process.exit(0);
+    }
+    console.log();
+  }
+
+  // Overwrite .claude/
+  await copyDir(
+    path.join(PACKAGE_DIR, '.claude'),
+    path.join(target, '.claude')
+  );
+  console.log('  [ok] .claude/ (updated)');
+
+  // Overwrite .tas/
+  await copyDir(
+    path.join(PACKAGE_DIR, '.tas'),
+    path.join(target, '.tas')
+  );
+  console.log('  [ok] .tas/ (updated)');
+
+  // Remove files deleted from the kit in previous versions
+  const deletedFiles = await getDeletedFiles();
+  if (deletedFiles.length > 0) {
+    const { removed } = await removeDeletedFiles(target, deletedFiles);
+    if (removed.length > 0) {
+      for (const f of removed) {
+        console.log(`  [rm] ${f} (removed in this version)`);
+      }
+    }
+  }
+
+  // Set executable bit on tas-ado.py (Unix/macOS)
+  if (process.platform !== 'win32') {
+    const adoPy = path.join(target, '.tas', 'tools', 'tas-ado.py');
+    if (await exists(adoPy)) {
+      await fs.chmod(adoPy, 0o755);
+    }
+  }
+
+  console.log(`  [--] CLAUDE.md, tas.yaml, .env.example — not touched`);
+
+  console.log(`
+TAS Kit updated successfully!
+
+If this version added new settings or templates, check the changelog
+and manually merge changes into your CLAUDE.md and tas.yaml if needed.
+  `);
+}
+
+export async function install({ directory, yes }) {
+  const target = path.resolve(directory);
+
+  // Ensure target directory exists
+  await fs.mkdir(target, { recursive: true });
+
+  console.log(`\nInstalling TAS Kit into: ${target}\n`);
+
+  // Warn if .claude/ or .tas/ already exist
+  const claudeExists = await exists(path.join(target, '.claude'));
+  const tasExists = await exists(path.join(target, '.tas'));
+
+  if ((claudeExists || tasExists) && !yes) {
+    const existing = [claudeExists && '.claude/', tasExists && '.tas/'].filter(Boolean).join(', ');
+    console.warn(`  WARNING: ${existing} already exist in target directory.`);
+    console.warn(`  Existing files with the same names will be overwritten.\n`);
+    const ok = await confirm('Continue?');
+    if (!ok) {
+      console.log('Installation cancelled.');
+      process.exit(0);
+    }
+    console.log();
+  }
+
+  // Copy .claude/
+  await copyDir(
+    path.join(PACKAGE_DIR, '.claude'),
+    path.join(target, '.claude')
+  );
+  console.log('  [ok] .claude/');
+
+  // Copy .tas/
+  await copyDir(
+    path.join(PACKAGE_DIR, '.tas'),
+    path.join(target, '.tas')
+  );
+  console.log('  [ok] .tas/');
+
+  // Copy CLAUDE-Example.md as CLAUDE.md (only if absent)
+  const claudeMdTarget = path.join(target, 'CLAUDE.md');
+  if (!(await exists(claudeMdTarget))) {
+    await fs.copyFile(
+      path.join(PACKAGE_DIR, 'CLAUDE-Example.md'),
+      claudeMdTarget
+    );
+    console.log('  [ok] CLAUDE.md (from CLAUDE-Example.md)');
+  } else {
+    console.log('  [--] CLAUDE.md already exists, skipped');
+  }
+
+  // Copy .env.example (only if absent)
+  const envExampleTarget = path.join(target, '.env.example');
+  if (!(await exists(envExampleTarget))) {
+    await fs.copyFile(
+      path.join(PACKAGE_DIR, '.env.example'),
+      envExampleTarget
+    );
+    console.log('  [ok] .env.example');
+  } else {
+    console.log('  [--] .env.example already exists, skipped');
+  }
+
+  // Copy tas-example.yaml as tas.yaml (only if absent)
+  const tasYamlTarget = path.join(target, 'tas.yaml');
+  if (!(await exists(tasYamlTarget))) {
+    await fs.copyFile(
+      path.join(PACKAGE_DIR, '.tas', 'tas-example.yaml'),
+      tasYamlTarget
+    );
+    console.log('  [ok] tas.yaml (from .tas/tas-example.yaml)');
+  } else {
+    console.log('  [--] tas.yaml already exists, skipped');
+  }
+
+  // Set executable bit on tas-ado.py (Unix/macOS)
+  if (process.platform !== 'win32') {
+    const adoPy = path.join(target, '.tas', 'tools', 'tas-ado.py');
+    if (await exists(adoPy)) {
+      await fs.chmod(adoPy, 0o755);
+    }
+  }
+
+  console.log(`
+TAS Kit installed successfully!
+
+Next steps:
+  1. Edit CLAUDE.md     — add your project's tech stack and conventions
+  2. Edit tas.yaml      — set project name, team and ADO config
+  3. Create .env        — add AZURE_DEVOPS_PAT (see .env.example)
+  4. Open Claude Code   — run /tas-init to initialize your project
+
+Docs: .tas/README.md
+  `);
+}