@torus-engineering/tas-kit 1.9.0 → 1.11.1

package/README.md

@@ -1,6 +1,182 @@
 # TAS Kit
 
-**Torus Agentic SDLC Kit** — Claude Code commands, skills and templates for modern AI-assisted SDLC.
+**Torus Agentic SDLC Kit** — AI-assisted SDLC toolkit, designed following Spec-Driven Development philosophy and Context-Aware Architecture.
+
+---
+
+## Purpose
+
+TAS Kit helps software development teams:
+- **Standardize SDLC process** with clear artifacts (PRD, SAD, ADR, Epic, Feature, Story)
+- **Optimize token usage** through Context Layer — invest in design phase, save in code phase
+- **Support multiple workflows**: from solo developer to full team with PE/SE/DSE roles
+- **Automate** with Hybrid and Autonomous agents operating 24/7
+
+---
+
+## Design Philosophy
+
+### Spec-Driven Development
+All code starts from spec. Story.md is "context digest" that has absorbed all information from PRD, SAD, ADR, Feature. Each implementation session only needs to read CLAUDE.md + Story.md — no need to reload all artifacts.
+
+### Human-Led, AI-Powered
+- **Human-led**: Architecture decisions, design approval, code review
+- **AI-assisted**: Draft creation, implementation per spec, test execution, bug detection
+
+### Dual Mode Operation
+- **Hybrid Mode**: Developer and AI work together in session
+- **Autonomous Mode**: AI automatically develops 24/7, reports results when done
+
+### Lightweight & Context-Aware
+- Each skill < 3KB, total kit < 50KB
+- Context Layer: invest tokens in design phase to save many times in code phase
+- When coding: MUST start new session (don't reuse old session that loaded PRD/SAD to avoid Window Context bloat)
+
+### Role-Based & Template-Driven
+- 3 actual roles at Torus: PE (Product Engineer), SE (Software Engineer), DSE (DevOps Engineer)
+- Separate templates for PRD, SAD, ADR, Epic, Feature, Story per Torus standards
+- Flow configurable via `tas.yaml` file
+
+### Azure DevOps Compatible
+- Markdown output compatible with Azure DevOps Wiki
+- Mermaid diagrams don't use `()` characters (avoid conflict with ADO syntax)
+
+---
+
+## SDLC Workflow
+
+:::mermaid
+graph TD
+    subgraph Phase1["Phase 1: Discovery"]
+        PRD["/tas-prd"]
+        SAD["/tas-sad"]
+        ADR["/tas-adr"]
+        DESIGN["/tas-design"]
+        PRD -->|Product Engineer| PRD_ARTIFACT["PRD.md"]
+        PRD_ARTIFACT -->|Software Engineer| SAD
+        PRD_ARTIFACT -->|Software Engineer| ADR
+        SAD --> SAD_ARTIFACT["SAD.md"]
+        ADR --> ADR_ARTIFACT["ADR-XXX.md"]
+        PRD_ARTIFACT -->|Product Engineer| DESIGN
+        DESIGN --> DESIGN_ARTIFACT["design-spec.md"]
+    end
+
+    subgraph Phase2["Phase 2: Planning"]
+        EPIC["/tas-epic"]
+        FEATURE["/tas-feature"]
+        STORY["/tas-story"]
+        PRD_ARTIFACT -->|Product Engineer| EPIC
+        EPIC --> EPIC_ARTIFACT["Epic-XXX/"]
+        EPIC_ARTIFACT -->|Product Engineer| FEATURE
+        FEATURE --> FEATURE_ARTIFACT["Feature-XXX/"]
+        SAD_ARTIFACT --> FEATURE
+        DESIGN_ARTIFACT --> FEATURE
+        FEATURE_ARTIFACT -->|Product Engineer| STORY
+        STORY --> STORY_ARTIFACT["Story-XXX.md"]
+    end
+
+    subgraph Phase3["Phase 3: Implementation"]
+        PLAN["/tas-plan"]
+        DEV["/tas-dev"]
+        FIX["/tas-fix"]
+        APItest["/tas-apitest"]
+        E2E["/tas-e2e"]
+        FUNCTEST_WEB["/tas-functest-web"]
+        FUNCTEST_MOBILE["/tas-functest-mobile"]
+        E2E_WEB["/tas-e2e-web"]
+        E2E_MOBILE["/tas-e2e-mobile"]
+        BUG["/tas-bug"]
+        REVIEW["/tas-review"]
+        FUNctest["/tas-functest"]
+        STORY_ARTIFACT -->|Software Engineer| PLAN
+        PLAN --> STORY_ARTIFACT
+        STORY_ARTIFACT -->|AI Agent| DEV
+        DEV --> CODE["Source Code"]
+        CODE -->|Bug found| FIX
+        FIX --> CODE
+        CODE -->|Software Engineer| REVIEW
+        REVIEW --> REVIEW_ARTIFACT["Code Review Report"]
+        STORY_ARTIFACT -->|Software Engineer| APItest
+        APItest --> APITEST_ARTIFACT["API Testing Script"]
+        FUNCTEST_ARTIFACT -->|Product Engineer| E2E
+        E2E --> E2E_ARTIFACT["E2E Test Scenarios"]
+        FUNCTEST_ARTIFACT -->|Software Engineer| FUNCTEST_WEB
+        FUNCTEST_WEB --> FUNCTEST_WEB_ARTIFACT["Functional Test Web Script"]
+        FUNCTEST_ARTIFACT -->|Software Engineer| FUNCTEST_MOBILE
+        FUNCTEST_MOBILE --> FUNCTEST_MOBILE_ARTIFACT["Functional Test Mobile Script"]
+        FUNCTEST_ARTIFACT -->|Product Engineer| E2E_WEB
+        E2E_WEB --> E2E_WEB_ARTIFACT["E2E Web Test Script"]
+        FUNCTEST_ARTIFACT -->|Product Engineer| E2E_MOBILE
+        E2E_MOBILE --> E2E_MOBILE_ARTIFACT["E2E Mobile Test Script"]
+        CODE -->|Bug found| BUG
+        BUG --> BUG_ARTIFACT["Bug Report"]
+        FEATURE_ARTIFACT -->|Product Engineer| FUNctest
+        FUNctest --> FUNCTEST_ARTIFACT["Functional-Testing-Spec-FeatureXXX.md"]
+    end
+
+    subgraph Phase4["Phase 4: Quality & Deploy"]
+        SECURITY["/tas-security"]
+        PIPELINE["Pipeline / CLI"]
+        CODE -->|DevOps Engineer| SECURITY
+        SECURITY --> SECURITY_ARTIFACT["Security Report"]
+        APITEST_ARTIFACT -->|Product Engineer| PIPELINE
+        FUNCTEST_WEB_ARTIFACT --> PIPELINE
+        FUNCTEST_MOBILE_ARTIFACT --> PIPELINE
+        E2E_WEB_ARTIFACT --> PIPELINE
+        E2E_MOBILE_ARTIFACT --> PIPELINE
+        PIPELINE --> TEST_REPORT["Test Report"]
+        SECURITY_ARTIFACT -->|DevOps Engineer| DEPLOY["Production"]
+        TEST_REPORT --> DEPLOY
+    end
+
+    STATUS["/tas-status"] -.->|Track| PRD_ARTIFACT
+    STATUS -.->|Track| SAD_ARTIFACT
+    STATUS -.->|Track| STORY_ARTIFACT
+    STATUS -.->|Track| DEPLOY
+
+    style PRD_ARTIFACT fill:#e1f5ff
+    style SAD_ARTIFACT fill:#fff4e1
+    style DESIGN_ARTIFACT fill:#f3e5f5
+    style STORY_ARTIFACT fill:#e8f5e9
+    style CODE fill:#f3e5f5
+    style TEST_REPORT fill:#c8e6c9
+    style DEPLOY fill:#c8e6c9
+:::
+
+### Phase Summary
+
+| Phase | Role | Commands | Artifacts |
+|-------|------|----------|-----------|
+| **Phase 1: Discovery** | PE, SE | `/tas-prd`, `/tas-sad`, `/tas-adr`, `/tas-design` | PRD.md, SAD.md, ADR-XXX.md, design-spec.md |
+| **Phase 2: Planning** | SE | `/tas-epic`, `/tas-feature`, `/tas-story`, `/tas-functest` | Epic-XXX/, Feature-XXX/, Story-XXX.md, Functional-Testing-Spec-FeatureXXX.md |
+| **Phase 3: Implementation** | PE, SE, AI | `/tas-plan`, `/tas-dev`, `/tas-fix`, `/tas-apitest`, `/tas-e2e`, `/tas-functest-web`, `/tas-functest-mobile`, `/tas-e2e-web`, `/tas-e2e-mobile`, `/tas-bug`, `/tas-review` | Plan.md, Source Code, API Testing Script, E2E Test Scenarios, Functional Test Scripts, Bug Report, Code Review Report |
+| **Phase 4: Quality & Deploy** | PE, DSE | `/tas-security`, Pipeline/CLI | Security Report, Test Report, Production |
+
+### Phase Details
+
+#### Phase 1: Discovery
+- **PE**: Create PRD with `/tas-prd`, create design-spec with `/tas-design`
+- **SE**: Create SAD with `/tas-sad`, create ADR with `/tas-adr`
+
+#### Phase 2: Planning
+- **PE**: Breakdown Epic with `/tas-epic`, Feature with `/tas-feature`, Story with `/tas-story`
+
+#### Phase 3: Implementation
+- **SE**: Create Plan with `/tas-plan`, Implement with `/tas-dev`, Fix bug with `/tas-fix`
+- **SE**: Review code with `/tas-review`
+- **PE**: Create Functional Testing Spec with `/tas-functest`
+- **SE**: Create API Testing Script with `/tas-apitest`
+- **PE**: Create E2E Test Scenarios with `/tas-e2e`
+- **SE**: Create Functional Test Scripts with `/tas-functest-web`, `/tas-functest-mobile`
+- **PE**: Create E2E Test Scripts with `/tas-e2e-web`, `/tas-e2e-mobile`
+- **PE**: Create Bug Report with `/tas-bug`
+
+#### Phase 4: Quality & Deploy
+- **DSE**: Security Review with `/tas-security`
+- **PE**: Run Pipeline/CLI to execute Automation Tests
+- **DSE**: Deploy to Production
+
+---
 
 ## Quick Start
 
@@ -8,13 +184,94 @@
 npx @torus-engineering/tas-kit install
 ```
 
-## Options
+### Options
 
 ```bash
 npx @torus-engineering/tas-kit install --directory /path/to/my-project
 npx @torus-engineering/tas-kit install --yes    # skip confirmation prompts
 ```
 
+---
+
+## Important Setup
+
+### CLAUDE.md
+
+Most important configuration file — Claude reads this file first in every session.
+
+**Structure:**
+```markdown
+# Project Name
+
+## Tech Stack
+- Backend: .NET / Node.js / Python
+- Frontend: React / Next.js
+- Database: PostgreSQL / MySQL
+- Infrastructure: AWS / Azure
+
+## Conventions
+- Coding standards
+- Architecture patterns
+- Testing requirements
+```
+
+### tas.yaml
+
+Controls TAS Kit flow per project.
+
+**Structure:**
+```yaml
+project:
+  name: "My Project"
+  team: "Team Name"
+
+azure_devops:
+  enabled: true
+  organization: "org"
+  project: "project"
+
+flow:
+  mode: "greenfield"  # or "brownfield"
+  use_tdd: true
+  auto_review: true
+```
+
+### project-status.yaml
+
+Project status index — automatically updated after each artifact change.
+
+**Structure:**
+```yaml
+last_updated: 2025-01-15
+
+artifacts:
+  prd:
+    file: docs/prd.md
+    status: Approved
+    version: "1.0"
+
+epics:
+  Epic-001:
+    status: Active
+    features:
+      Feature-001:
+        stories:
+          Story-001:
+            status: In Progress
+```
+
+### .env
+
+Environment variables for Azure DevOps integration.
+
+```bash
+AZURE_DEVOPS_PAT=your_pat_here
+AZURE_DEVOPS_ORG=your_org
+AZURE_DEVOPS_PROJECT=your_project
+```
+
+---
+
 ## What gets installed
 
 ```
@@ -31,52 +288,47 @@ tas.yaml      Flow configuration template (edit this for your project)
 .env.example  Environment variable template
 ```
 
-## After install
-
-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
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `/tas-init` | Initialize TAS for a new project |
-| `/tas-status` | Show current project state |
-| `/tas-prd` | Create/update Product Requirements Document |
-| `/tas-sad` | Create/update Solution Architecture Document |
-| `/tas-epic` | Create/update Epic |
-| `/tas-feature` | Create/update Feature |
-| `/tas-story` | Create/update Story |
-| `/tas-spec` | Lightweight spec (solo / prototype) |
-| `/tas-plan` | Plan technical implementation |
-| `/tas-dev` | Implement a story (agentic) |
-| `/tas-fix` | Quick fix without full story flow |
-| `/tas-review` | Code review with checklist |
-| `/tas-brainstorm` | Brainstorm solutions |
-| `/tas-bug` | Create bug report |
-| `/tas-security` | Security review |
-| `/tas-verify` | Verify feature on staging |
-| `/ado-*` | Azure DevOps integration |
+---
 
-## Requirements
+## Commands Reference
 
-- Node.js 18+
-- [Claude Code](https://claude.ai/code)
+| Command | Description | Role |
+|---------|-------------|------|
+| `/tas-init` | Initialize TAS for new project | All |
+| `/tas-status` | Display current project status | All |
+| `/tas-prd` | Create/update Product Requirements Document | PE |
+| `/tas-sad` | Create/update Solution Architecture Document | SE |
+| `/tas-adr` | Create Architecture Decision Record | SE |
+| `/tas-design` | Create Design Specification | SE |
+| `/tas-epic` | Create/update Epic | SE |
+| `/tas-feature` | Create/update Feature | SE |
+| `/tas-story` | Create/update Story | SE |
+| `/tas-functest` | Create Functional Testing Specification | SE |
+| `/tas-spec` | Lightweight spec (solo / prototype) | SE |
+| `/tas-plan` | Create technical implementation plan | SE |
+| `/tas-dev` | Implement story (agentic) | AI |
+| `/tas-fix` | Quick fix without full story flow | SE |
+| `/tas-apitest` | Create API Testing Script automatically | SE |
+| `/tas-e2e` | Create E2E Test Scenarios | PE |
+| `/tas-functest-web` | Create Functional Test Script for Web | SE |
+| `/tas-functest-mobile` | Create Functional Test Script for Mobile | SE |
+| `/tas-e2e-web` | Create E2E Test Script for Web | PE |
+| `/tas-e2e-mobile` | Create E2E Test Script for Mobile | PE |
+| `/tas-bug` | Create Bug Report | PE |
+| `/tas-review` | Code Review with checklist | SE |
+| `/tas-brainstorm` | Brainstorm solutions | All |
+| `/tas-security` | Security Review | DSE |
+| `/ado-*` | Azure DevOps integration | All |
 
-## Publishing to npm
+---
 
-```bash
-# Bump version (patch / minor / major)
-npm version patch
+## Requirements
 
-# Publish to npm registry
-npm publish --access=public --auth-type=web
-```
+- Node.js 18+
+- [Claude Code](https://claude.ai/code)
 
-`--auth-type=web` mở trình duyệt để xác thực nếu chưa login. Chạy `npm whoami` để kiểm tra đang đăng nhập với account nào trước khi publish.
+---
 
 ## Documentation
 
-See `.tas/README.md` after install for full kit documentation.
+See `.tas/README.md` after install for detailed documentation.

package/bin/cli.js

@@ -17,15 +17,20 @@ Commands:
             (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
+  --directory <path>          Target directory (default: current working directory)
+  --yes, -y                   Skip confirmation prompts (uses native hook by default)
+  --security-hook <mode>      Pre-commit hook mode: husky | native | none
+                              Default: interactive prompt on install,
+                                       no-op on update unless specified.
+  --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 --security-hook=husky
+  npx @torus-engineering/tas-kit install --security-hook=none
   npx @torus-engineering/tas-kit update
-  npx @torus-engineering/tas-kit update --yes
+  npx @torus-engineering/tas-kit update --yes --security-hook=native
   `.trim());
 }
 
@@ -40,15 +45,27 @@ if (command !== 'install' && command !== 'update') {
   process.exit(1);
 }
 
-const opts = { directory: process.cwd(), yes: false };
+const opts = { directory: process.cwd(), yes: false, securityHook: null };
+
 for (let i = 1; i < args.length; i++) {
-  if ((args[i] === '--directory' || args[i] === '-d') && args[i + 1]) {
+  const a = args[i];
+  if ((a === '--directory' || a === '-d') && args[i + 1]) {
     opts.directory = args[++i];
-  } else if (args[i] === '--yes' || args[i] === '-y') {
+  } else if (a === '--yes' || a === '-y') {
     opts.yes = true;
+  } else if (a.startsWith('--security-hook=')) {
+    opts.securityHook = a.slice('--security-hook='.length).toLowerCase();
+  } else if (a === '--security-hook' && args[i + 1]) {
+    opts.securityHook = args[++i].toLowerCase();
   }
 }
 
+if (opts.securityHook && !['husky', 'native', 'none'].includes(opts.securityHook)) {
+  console.error(`Invalid --security-hook value: "${opts.securityHook}"`);
+  console.error(`Expected one of: husky, native, none`);
+  process.exit(1);
+}
+
 const runner = command === 'update' ? update : install;
 runner(opts).catch((err) => {
   console.error(`\n${command === 'update' ? 'Update' : 'Install'} failed:`, err.message);