@torus-engineering/tas-kit 1.10.0 → 1.12.0

package/.tas/commands/tas-prd.md

@@ -0,0 +1,37 @@
+# /tas-prd $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update Product Requirements Document.
+
+## Actions
+1. Need context from root/tas.yaml for project context
+2. Check if docs/prd.md already exists:
+
+### CREATE mode (file doesn't exist):
+3. Need context from .tas/templates/PRD.md
+4. If $ARGUMENTS has content, use as product description input
+5. If no $ARGUMENTS, ask user:
+   - What problem does the product solve?
+   - Who are the main users?
+   - What are core features?
+   - Any technical/business constraints?
+6. Create file docs/prd.md per template
+7. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add `artifacts.prd`.
+
+### UPDATE mode (file exists):
+3. Need context from current docs/prd.md
+4. $ARGUMENTS is change description. If not provided, ask user which section to update.
+5. Update file, keep unchanged sections as-is
+6. Add line to Changelog section at end: date, change description
+7. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `artifacts.prd`.
+
+## Principles
+- Write at sufficient detail for SE to understand and design architecture
+- Classify requirements by MoSCoW: Must/Should/Could/Won't
+- Each requirement has unique ID: FR-001, NFR-001
+- Always include Non-Goals section to limit scope
+- Mermaid diagrams must use :::mermaid wrapper, NO () characters
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/prd.md`.

package/.tas/commands/tas-review.md

@@ -0,0 +1,113 @@
+# /tas-review $ARGUMENTS
+
+Review recently changed code or a specific file/PR.
+Includes hygiene scan, test run, and parallel multi-agent review.
+
+## Stack Detection
+Read `.tas/rules/common/stack-detection.md`.
+
+## Actions
+
+### Step 1 — Determine review scope
+`$ARGUMENTS` can be: file path, Story ID, or empty (review git diff).
+- If empty: get `git diff HEAD` (staged + unstaged) or last commit
+- If Story ID: find corresponding Story file to get changed files list
+- If file path: review that file directly
+
+### Step 2 — Pre-checks (MUST pass before continuing)
+
+**Hygiene scan** — quick scan of files in scope:
+- Debug code leftovers: `console.log`, `print(`, `Debug.WriteLine`, `debugger`
+- Hardcoded secrets: password/key/token/secret assigned as string literal
+- Large commented-out code blocks (>5 lines) without reason comment
+
+→ If blockers found: list immediately, require fix before continuing.
+
+**Run tests** — detect from project structure:
+- `package.json` → `yarn test --ci` or `npm test`
+- `*.csproj` / `*.sln` → `dotnet test`
+- `pytest.ini` / `pyproject.toml` → `python -m pytest`
+
+→ If **FAIL**: add finding **"Unit Test Failure"** severity **Critical**, stop, DO NOT continue review.
+→ If **PASS**: note "Unit Tests: ✓ PASS" in Review Summary.
+→ If cannot detect: note "No test runner detected" and continue.
+
+### Step 3 — Review
+
+**Inline general review** (main session, always run):
+Read `.tas/rules/common/code-review.md`. Apply review criteria priority order, output format from rule. Story context (CLAUDE.md, SAD, ADRs) already in session — don't re-read.
+
+**Specialized agents** — launch SIMULTANEOUSLY (don't wait for each other):
+
+**Agent 1 — `security-reviewer`** (always run):
+> Security audit [scope]. Read `.tas/rules/common/security.md`.
+> If stack identified, also read `.tas/rules/[stack]/security.md`.
+> Focus: OWASP Top 10, injection, hardcoded secrets, auth/authz, data exposure.
+> Format: findings grouped by Critical / High / Medium / Low, each with file:line and remediation.
+
+**Agent 2 — Language reviewer** (per `lang_agent` from stack detection):
+> Language-specific review [scope].
+> Read `.tas/rules/[stack]/coding-style.md`, `.tas/rules/[stack]/patterns.md`, `.tas/rules/[stack]/testing.md`.
+> If stack has React: also read `.tas/rules/web/design-quality.md`, `.tas/rules/web/testing.md`, `.tas/rules/web/performance.md`.
+> Focus: async/await patterns, null handling, type safety, stack-specific anti-patterns.
+> Format: findings by Critical / High / Medium / Low with file:line.
+
+**Agent 3 — `database-reviewer`** (only when `db_agent = database-reviewer`, and scope touches schema/migrations/queries):
+> Database review [scope]. Focus: schema correctness, migration safety, missing indexes, N+1 patterns, unsafe queries, data integrity.
+> Format: findings by Critical / High / Medium / Low with file:line.
+
+**Agent 4 — `aws-reviewer`** (only when `infra_agent = aws-reviewer`):
+> AWS infrastructure review [scope].
+> Focus: IAM policies, secrets in env/config, S3 permissions, Lambda security.
+> Format: findings by Critical / High / Medium / Low.
+
+Wait for ALL agents to complete, then synthesize.
+
+### Step 4 — Synthesize results
+
+Combine inline review findings + agent findings, deduplicate (same file:line → merge), sort by severity:
+
+```
+## Review Summary
+
+### Critical (must fix before merge)
+- [file:line] Issue — Fix: ...
+
+### High (should fix before merge)
+- [file:line] Issue — Fix: ...
+
+### Medium (consider fixing)
+- [file:line] Issue — Fix: ...
+
+### Low / Info (optional)
+- [file:line] Issue — Fix: ...
+```
+
+## After review
+
+**If Critical/High present:**
+→ List clearly, require human fix. DO NOT continue flow.
+
+**If only Medium/Low:**
+→ List suggestions, ask if human wants to fix, then continue.
+
+**When human confirms fixed:**
+1. Tick `- [x] Code review passed` in Story's `## Definition of Done` section
+2. Ask: "Have you tested locally again? If OK, want to move ticket to Deploy Test?"
+3. If Yes:
+   a. Update Story `Status:` → `Deploy Test`
+   b. Add Changelog line in Story: date, "Code review passed, moved to Deploy Test"
+   c. Update parent Feature `Status:` → `In Progress`, update Stories table
+   d. Add Changelog in Feature
+   e. Update `project-status.yaml`
+   f. Suggest: run `/ado-update story <ado-id> --status "Deploy Test"` if using ADO
+
+## Principles
+- Objective review — point to specific file:line and reason
+- Propose specific fix, don't just say "code is bad"
+- Check if code violates any ADR (read from Story's Technical Notes)
+- DO NOT auto-change status without human confirmation
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to Story file being reviewed (if any).

package/.tas/commands/tas-sad.md

@@ -0,0 +1,43 @@
+# /tas-sad $ARGUMENTS
+
+Role: SE - Software Engineer
+Create or update Solution Architecture Document.
+
+## Prerequisite
+- docs/prd.md must exist. If not, notify user to run /tas-prd first.
+
+## Actions
+1. Need context from root/tas.yaml for project info, workflow config
+2. Need context from docs/prd.md to understand requirements
+3. If brownfield: need context from docs/codebase-overview.md if available
+4. Check if docs/sad.md already exists:
+
+### CREATE mode (file doesn't exist):
+5. Need context from .tas/templates/SAD.md
+6. Create file docs/sad.md per Torus SAD template
+7. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add `artifacts.sad`.
+
+### UPDATE mode (file exists):
+5. Need context from current docs/sad.md
+6. $ARGUMENTS is change description. If not provided, ask user which section to update.
+7. Update file, keep unchanged sections as-is
+8. Add line to Changelog section at end
+9. If change is important architectural decision, suggest user run /tas-adr
+10. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `artifacts.sad`.
+
+## Mermaid Rules
+- C4 diagrams MUST use Mermaid flow diagram
+- Start with :::mermaid, end with :::
+- DO NOT use () in node labels, use [] instead
+- Example: A["Web App"] --> B["API Gateway"]
+- Include views: System Context, Container, Component, Data, Deployment
+
+## Principles
+- SAD must align with tech stack in CLAUDE.md
+- Each important architectural decision should reference ADR
+- ERD must use Mermaid erDiagram
+- Sequence diagram uses Mermaid sequenceDiagram
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/sad.md`.

package/.tas/commands/tas-security.md

@@ -0,0 +1,87 @@
+# /tas-security $ARGUMENTS
+
+Check codebase security, save report to docs/security-report.md.
+
+## Stack Detection
+Read `.tas/rules/common/stack-detection.md`.
+
+## Actions
+
+### Step 1 — Determine scope
+`$ARGUMENTS` can be:
+- File path or directory → scan specified scope only
+- Empty → scan entire codebase
+- `--staged` → only scan staged files (like pre-commit hook), fast + used to self-test before commit
+
+With `--staged`: get list from `git diff --cached --name-only --diff-filter=ACM` and only review those files. Use same regex patterns as `.tas/hooks/security-scan.js` then supplement with deep review by agents below.
+
+Read `.tas/rules/common/security.md` for general checks. If stack identified, also read `.tas/rules/[stack]/security.md` for stack-specific items.
+
+### Step 2 — Parallel Security Scan
+
+Launch agents SIMULTANEOUSLY based on stack:
+
+**Agent 1 — `security-reviewer`** (always run):
+> Security audit [scope].
+> Read `.tas/rules/common/security.md`.
+> If stack identified, also read `.tas/rules/[stack]/security.md`.
+> Check OWASP Top 10: injection, broken auth, XSS, IDOR, security misconfiguration,
+> sensitive data exposure, insecure deserialization, vulnerable components, logging/monitoring.
+> Also check: hardcoded secrets, CORS config, anti-forgery tokens, rate limiting.
+> Format: findings by Critical / High / Medium / Low with file:line and specific remediation.
+> Each finding has: status = Open.
+
+**Agent 2 — `database-reviewer`** (only when `db_agent = database-reviewer`):
+> Database security review [scope].
+> Focus: parameterized queries vs string concatenation, ORM raw query usage,
+> sensitive data stored in plaintext, missing field-level encryption, excessive permissions.
+> Format: findings by Critical / High / Medium / Low with file:line and remediation.
+
+**Agent 3 — `aws-reviewer`** (only when `infra_agent = aws-reviewer`):
+> AWS infrastructure security review [scope].
+> Focus: IAM overpermission, S3 public access, secrets in env/config/code,
+> Lambda environment variables, API Gateway auth, VPC security groups.
+> Format: findings by Critical / High / Medium / Low with file:line and remediation.
+
+Wait for ALL agents to complete.
+
+### Step 3 — Synthesize and save report
+
+Combine findings from all agents, deduplicate (same file:line → merge), sort by severity.
+
+Check `docs/security-report.md`:
+- **Doesn't exist**: create new per template `.tas/templates/Security-Report.md`
+- **Exists**: append new report, update old findings status if fixed
+
+Report content includes:
+- Scan date, scope, stack
+- Findings by Critical / High / Medium / Low
+- Each finding: file:line, description, remediation, status (Open / Fixed / Accepted Risk)
+- Summary: total findings per severity, fixed vs open counts
+
+### Step 4 — Update project-status.yaml
+
+```yaml
+artifacts:
+  security_report:
+    file: docs/security-report.md
+    status: [Critical findings present | Clean]
+    last_updated: [today's date]
+```
+
+### Step 5 — Next actions
+
+If **Critical findings**:
+→ List clearly, require fix immediately before deploying to any environment.
+
+If **High findings**:
+→ List, recommend fixing before merging to main.
+
+If only **Medium/Low**:
+→ Summarize, suggest fixing in priority order.
+
+## Principles
+- Classification: Critical / High / Medium / Low
+- Each finding must have specific recommended fix
+- Finding has status: Open | In Progress | Fixed | Accepted Risk
+- DO NOT hardcode fix — propose remediation pattern, don't write replacement code

package/.tas/commands/tas-spec.md

@@ -0,0 +1,50 @@
+# /tas-spec $ARGUMENTS
+
+Create lightweight spec before coding — for solo dev, prototype, spike, internal tool.
+Differs from `/tas-fix`: has spec document, suitable for tasks > 2 hours or needs AC tracking.
+
+## Steps
+
+### 1 — Gather information
+`$ARGUMENTS` is task description. If not clear enough, ask max 3 questions:
+- **Goal**: What to build? What problem to solve?
+- **AC**: What does done look like? (2-5 specific, testable criteria)
+- **Constraints**: Tech constraints, out of scope?
+
+Don't ask if $ARGUMENTS is already clear enough.
+
+### 2 — Create SPEC.md
+Create file `SPEC.md` at project root:
+
+```markdown
+# {Title}
+> {one-line summary}
+
+**Status:** Draft | **Date:** {today}
+
+## Goal
+{Problem to solve — not solution}
+
+## Acceptance Criteria
+- [ ] {Given/When/Then or testable statement}
+- [ ] ...
+
+## Out of Scope
+- {What won't be done}
+
+## Constraints
+{Tech constraints, patterns to follow — omit if none}
+
+## Open Questions
+{Unanswered questions — omit if none}
+```
+
+### 3 — Next step
+> "SPEC.md created.
+> - Plan in detail: `/tas-plan SPEC.md`
+> - Code immediately: `/tas-dev` (requires `require_plan: false` in tas.yaml)"
+
+## Principles
+- SPEC.md is single source of truth — don't create additional files
+- Keep short: target < 1 page
+- If AC > 8 items or task > 1 day → suggest using `/tas-story` instead

package/.tas/commands/tas-status.md

@@ -0,0 +1,16 @@
+# /tas-status
+
+Check current status of TAS project.
+
+## Actions
+1. Need context from root/project-status.yaml (ONLY read this file, DO NOT scan docs/ directory)
+2. Need context from root/tas.yaml to know workflow config
+3. Based on project-status.yaml, summarize:
+   - Number of artifacts created and their status
+   - Number of epics/features/stories by each status
+   - Current phase based on aggregated status
+4. Display phase status table and story details by status.
+
+## Notes
+- This is read-only command, does not change anything
+- If project-status.yaml seems out of sync, user can run /tas-init to rescan and sync

package/.tas/commands/tas-story.md

@@ -0,0 +1,91 @@
+# /tas-story $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update User Story document.
+
+**Scope:** Business logic, user experience, acceptance criteria, test cases.
+**Out of scope:** Technical implementation, files to modify, database schema — that's `/tas-plan`'s job.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Write AC in Given/When/Then format |
+| **Always** | Set `plan_status: pending` for new Story |
+| **Ask** | When Story > 8h — suggest splitting |
+| **Never** | Read SAD, ADR — technical is `/tas-plan`'s job |
+
+## Prerequisite
+- At least one Feature must exist
+
+## Actions
+
+### CREATE mode ($ARGUMENTS is new Story description, or no $ARGUMENTS)
+
+**Step 1 — Identify Feature**
+- Read `project.code` from root/`tas.yaml`
+- Prioritize in order:
+  1. If `$ARGUMENTS` contains Feature ID → use it
+  2. If context has `parent_id` → use it
+  3. Ask user: "Which Feature does this Story belong to?" — no directory scan
+
+**Step 2 — Gather business context**
+- Read identified Feature file (get business context, scope, existing Stories list)
+- Read PRD (if exists) — only business requirements, user goals
+
+**Step 3 — Determine Story ID**
+- Read Stories section in Feature file → determine next index from that list
+- DO NOT scan directory
+
+**Step 4 — Draft Story with user**
+
+Discuss to fill in:
+
+a) **User Story**: "As a [role], I want [goal], so that [benefit]"
+
+b) **Business Requirements** (if any): specific business rules, stakeholder constraints
+
+c) **Design Notes** (if any): UI/UX specs, mockup links, flow diagrams
+
+d) **Prerequisites** (if any): other Stories that must be done first
+
+e) **Acceptance Criteria**: each AC is a clear Given/When/Then scenario
+
+**Step 5 — Test Case Prompting**
+
+After AC confirmed, ask more:
+- "Besides happy path, any edge cases to test?" (empty input, boundary values, concurrent)
+- "Any negative cases to cover?" (unauthorized, invalid data, timeout, not found)
+- "Any external dependencies to mock when testing?" (external APIs, database state)
+
+Write all to `## Unit Test Cases` section.
+
+**Step 6 — Create file**
+- Read `.tas/templates/Story.md` for format
+- Create `docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/{code}-Story-{NNN}-{slug}.md`
+- Frontmatter: `plan_status: pending`, `plan_date:` left empty
+
+**Step 7 — Update project-status.yaml**
+Per `.tas/rules/common/project-status.md` — add entry to `epics.{EPIC_ID}.features.{FEATURE_ID}.stories`.
+
+**Step 8 — Notify next step**
+> "Story created. Before SE starts coding, run `/tas-plan {Story-ID}` for technical planning."
+
+---
+
+### UPDATE mode ($ARGUMENTS is Story ID, e.g., "Story-005")
+
+1. Find file via glob `docs/epics/**/{code}-Story-{ID}-*.md`
+2. Read current Story file
+3. Ask user what needs changing (update AC, change status, add test cases, fix business rule...)
+4. Update file, add entry to Changelog
+5. Update `project-status.yaml` per `.tas/rules/common/project-status.md`.
+
+## Principles
+- Story must be small enough to complete in **4-8 hours**; if larger → split into multiple Stories
+- Story file = **product artifact**: describes *what* and *why*, not *how*
+- Story status: New → Committed → In Progress → Deploy Test → Verify Test → Deploy Stag → Verify Stag → Deploy Prod → Verify Prod → Done
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working Story file.

package/.tas/platforms.json

@@ -0,0 +1,5 @@
+{
+  "platforms": [
+    "claude-code"
+  ]
+}

package/.tas/project-status-example.yaml

@@ -1,17 +1,17 @@
-# .tas/project-status-example.yaml - Reference template cho root/project-status.yaml
-# /tas-init sẽ tạo file root/project-status.yaml từ template này.
-# Human có thể sửa tay. Chạy /tas-init để đồng bộ lại nếu lệch.
-last_updated: ""
-
-artifacts:
-  prd: {}
-  design_spec: {}
-  sad: {}
-  security_report: {}
-  performance_report: {}
-
-adrs: {}
-
-bugs: {}
-
-epics: {}
+# .tas/project-status-example.yaml - Reference template for root/project-status.yaml
+# /tas-init will create root/project-status.yaml from this template.
+# Human can edit manually. Run /tas-init to re-sync if drifted.
+last_updated: ""
+
+artifacts:
+  prd: {}
+  design_spec: {}
+  sad: {}
+  security_report: {}
+  performance_report: {}
+
+adrs: {}
+
+bugs: {}
+
+epics: {}

package/.tas/rules/ado-integration.md

@@ -0,0 +1,65 @@
+# ADO Integration Rules
+
+Bidirectional sync between .md files in repo and work items on Azure DevOps.
+ADO sync is **intentional operation** — not automatic after each file edit.
+
+## When to Apply
+
+- User runs `/ado-create`, `/ado-update`, `/ado-status`, `/ado-get`, `/ado-delete`
+- DO NOT apply when: user only edits .md file normally without mentioning ADO
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read `tas.yaml` and check `ado.enabled` before any operation |
+| **Always** | Display ADO ID and URL after each successful create/update |
+| **Always** | Update frontmatter `ado_id`, `ado_state`, `last_ado_sync` in .md file after sync |
+| **Ask** | When syncing multiple items at once — confirm list before running |
+| **Ask** | When detecting conflict between .md file and ADO item (which is source of truth?) |
+| **Ask** | When deleting work item — this is irreversible operation |
+| **Never** | Auto-sync whenever .md file is edited (too aggressive, creates noise) |
+| **Never** | Delete ADO item without clear user confirmation |
+| **Never** | Create duplicate work item if `ado_id` already exists in frontmatter |
+
+## First Step — Check ADO Enabled
+
+Before performing any operation, read `tas.yaml` at root and check `ado.enabled`:
+- If `ado.enabled: false` or field doesn't exist: notify "ADO integration is disabled in tas.yaml (`ado.enabled: false`). Enable if project uses ADO." then stop.
+- If `ado.enabled: true`: continue normally.
+
+## Prerequisites
+
+- Azure CLI + azure-devops extension: `az extension add --name azure-devops --upgrade`
+- Python 3.8+ with pyyaml: `pip install pyyaml`
+- PAT in .env file: `AzureDevops_Personal_AccessToken=your-pat-here`
+
+## Commands
+
+All ADO commands run via: `python .tas/tools/tas-ado.py <command> [args]`
+
+Or use slash commands:
+- `/ado-create <type> <temp-id> [--parent-id <id>]`
+- `/ado-get <ado-id>`
+- `/ado-update <type> <ado-id> [--assign <name>] [--status <state>]`
+- `/ado-status <ado-id> --status <state>`
+- `/ado-delete <type> <ado-id>`
+
+## File Convention
+
+- Filename: `{type}-{ado_id}-{slug-title}.md`
+- Each file has YAML frontmatter: `ado_id`, `ado_type`, `ado_state`, `last_ado_sync`
+- .md file is single source of truth, sync to ADO when needed
+
+## Red Flags
+
+- File has `ado_id` but state in file differs from ADO → confirm with user before overwriting
+- PAT expired → guide to rotate, don't log token to stdout
+- `ado.enabled: true` but project hasn't set up Azure CLI → check prerequisites first
+
+## Anti-Rationalization
+
+| Rationalization | Counter |
+|---|---|
+| "Auto-sync is more convenient, no need to remember" | Hook auto-sync causes unintended pushes when editing draft — sync must be intentional |
+| "Delete is OK, I know what I'm doing" | ADO delete has no undo — always confirm, even if user seems confident |