@torus-engineering/tas-kit 1.14.0 → 2.1.0

package/.tas/tools/tas-github.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""
+TAS GitHub Integration Script
+GitHub PR operations for tas-review-pr command.
+
+Usage: python tools/tas-github.py <command> [arguments]
+
+Commands:
+  pr-get    <pr-id>
+  pr-diff   <pr-id>
+  pr-comment <pr-id> --comment <text>
+  pr-inline  <pr-id> --file <path> --line <n> --comment <text>
+  pr-vote    <pr-id> --vote <approve|reject|wait-for-author|reset>
+
+Prerequisites:
+  - GitHub CLI (gh) installed and authenticated: gh auth login
+  - Python 3.8+
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+# --- Helpers ---
+
+def find_repo_root():
+    path = Path.cwd()
+    while path != path.parent:
+        if (path / ".git").exists():
+            return path
+        path = path.parent
+    print("ERROR: Not inside a git repository.")
+    sys.exit(1)
+
+
+def get_remote_url(root):
+    result = subprocess.run(
+        ["git", "remote", "get-url", "origin"],
+        capture_output=True,
+        cwd=str(root),
+    )
+    if result.returncode != 0:
+        print("ERROR: Cannot get git remote URL. Run inside a git repo with 'origin' remote.")
+        sys.exit(1)
+    return result.stdout.decode("utf-8").strip()
+
+
+def parse_owner_repo(remote_url):
+    """Extract owner/repo from GitHub remote URL (https or ssh)."""
+    # ssh: git@github.com:owner/repo.git
+    m = re.search(r"github\.com[:/](.+?)(?:\.git)?$", remote_url)
+    if m:
+        return m.group(1).rstrip("/")
+    print(f"ERROR: Cannot parse owner/repo from remote URL: {remote_url}")
+    sys.exit(1)
+
+
+def get_github_token():
+    result = subprocess.run(
+        ["gh", "auth", "token"],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        print("ERROR: gh CLI not authenticated. Run: gh auth login")
+        sys.exit(1)
+    return result.stdout.decode("utf-8").strip()
+
+
+def gh_cmd(args):
+    """Run gh CLI command and return parsed JSON output."""
+    cmd = ["gh"] + args + ["--output", "json"] if "--output" not in args else ["gh"] + args
+    result = subprocess.run(cmd, capture_output=True)
+
+    def _decode(b):
+        try:
+            return (b or b"").decode("utf-8")
+        except UnicodeDecodeError:
+            return (b or b"").decode("cp1252", errors="replace")
+
+    if result.returncode != 0:
+        print(f"ERROR: gh command failed:\n{_decode(result.stderr)}")
+        sys.exit(1)
+    stdout = _decode(result.stdout).strip()
+    if not stdout:
+        return {}
+    json_start = re.search(r"[{\[]", stdout)
+    if json_start:
+        try:
+            return json.loads(stdout[json_start.start():])
+        except json.JSONDecodeError:
+            return {}
+    return {}
+
+
+def github_rest(method, path, data, token):
+    """Call GitHub REST API using token auth."""
+    import base64
+    url = f"https://api.github.com{path}"
+    bearer = f"Bearer {token}"
+    body = json.dumps(data).encode("utf-8")
+    req = urllib.request.Request(url, data=body, method=method)
+    req.add_header("Authorization", bearer)
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8")
+        print(f"ERROR: GitHub REST API {method} {path} failed ({e.code}): {err_body}")
+        sys.exit(1)
+
+
+# --- PR Commands ---
+
+def cmd_pr_get(args):
+    root = find_repo_root()
+    remote_url = get_remote_url(root)
+    owner_repo = parse_owner_repo(remote_url)
+
+    result = gh_cmd([
+        "pr", "view", str(args.pr_id),
+        "--repo", owner_repo,
+        "--json", "number,title,body,headRefName,baseRefName,author,state,headRefOid,url",
+    ])
+
+    print(f"PR_ID: {result.get('number', args.pr_id)}")
+    print(f"TITLE: {result.get('title', '')}")
+    print(f"DESCRIPTION: {result.get('body', '')}")
+    print(f"SOURCE_BRANCH: {result.get('headRefName', '')}")
+    print(f"TARGET_BRANCH: {result.get('baseRefName', '')}")
+    author = result.get("author", {})
+    print(f"CREATOR: {author.get('login', '') if isinstance(author, dict) else str(author)}")
+    print(f"STATUS: {result.get('state', '')}")
+    print(f"REPO_ID: {owner_repo}")
+    print(f"REPO_NAME: {owner_repo.split('/')[-1]}")
+    print(f"HEAD_COMMIT: {result.get('headRefOid', '')}")
+    print(f"WORK_ITEMS: ")  # GitHub has no native work item link (use PR body parsing if needed)
+
+
+def cmd_pr_diff(args):
+    root = find_repo_root()
+    remote_url = get_remote_url(root)
+    owner_repo = parse_owner_repo(remote_url)
+
+    result = gh_cmd([
+        "pr", "view", str(args.pr_id),
+        "--repo", owner_repo,
+        "--json", "headRefName,baseRefName,headRefOid",
+    ])
+
+    source_branch = result.get("headRefName", "")
+    target_branch = result.get("baseRefName", "")
+    fetch_head = result.get("headRefOid", "")
+
+    print(f"SOURCE_BRANCH: {source_branch}")
+    print(f"TARGET_BRANCH: {target_branch}")
+
+    fetch_result = subprocess.run(
+        ["git", "fetch", "origin", source_branch],
+        capture_output=True,
+        cwd=str(root),
+    )
+    if fetch_result.returncode != 0:
+        warn = (fetch_result.stderr or b"").decode("utf-8", errors="replace")
+        print(f"WARNING: git fetch failed: {warn}")
+
+    if not fetch_head:
+        head_result = subprocess.run(
+            ["git", "rev-parse", "FETCH_HEAD"],
+            capture_output=True,
+            cwd=str(root),
+        )
+        fetch_head = head_result.stdout.decode("utf-8").strip() if head_result.returncode == 0 else ""
+
+    print(f"FETCH_HEAD: {fetch_head}")
+
+    diff_result = subprocess.run(
+        ["git", "diff", "--name-status", f"origin/{target_branch}...FETCH_HEAD"],
+        capture_output=True,
+        cwd=str(root),
+    )
+    if diff_result.returncode == 0:
+        print("CHANGED_FILES:")
+        print(diff_result.stdout.decode("utf-8", errors="replace").strip())
+    else:
+        warn = (diff_result.stderr or b"").decode("utf-8", errors="replace")
+        print(f"WARNING: git diff failed: {warn}")
+
+
+def cmd_pr_comment(args):
+    root = find_repo_root()
+    remote_url = get_remote_url(root)
+    owner_repo = parse_owner_repo(remote_url)
+
+    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False, encoding="utf-8")
+    tmp.write(args.comment)
+    tmp.close()
+    try:
+        result = subprocess.run(
+            ["gh", "pr", "comment", str(args.pr_id),
+             "--repo", owner_repo,
+             "--body-file", tmp.name],
+            capture_output=True,
+        )
+        if result.returncode != 0:
+            err = (result.stderr or b"").decode("utf-8", errors="replace")
+            print(f"ERROR: gh pr comment failed: {err}")
+            sys.exit(1)
+        print(f"Posted comment on PR #{args.pr_id}")
+    finally:
+        try:
+            os.unlink(tmp.name)
+        except OSError:
+            pass
+
+
+def cmd_pr_inline(args):
+    root = find_repo_root()
+    remote_url = get_remote_url(root)
+    owner_repo = parse_owner_repo(remote_url)
+    token = get_github_token()
+
+    # Get HEAD commit for the PR (required by GitHub inline comment API)
+    result = gh_cmd([
+        "pr", "view", str(args.pr_id),
+        "--repo", owner_repo,
+        "--json", "headRefOid",
+    ])
+    commit_id = result.get("headRefOid", "")
+    if not commit_id:
+        print("ERROR: Could not get PR head commit ID")
+        sys.exit(1)
+
+    file_path = args.file_path.replace("\\", "/").lstrip("/")
+
+    data = {
+        "body": args.comment,
+        "commit_id": commit_id,
+        "path": file_path,
+        "line": args.line,
+        "side": "RIGHT",
+    }
+    resp = github_rest("POST", f"/repos/{owner_repo}/pulls/{args.pr_id}/comments", data, token)
+    comment_id = resp.get("id", "")
+    print(f"Posted inline comment on {file_path}:{args.line} (comment #{comment_id})")
+
+
+def cmd_pr_vote(args):
+    root = find_repo_root()
+    remote_url = get_remote_url(root)
+    owner_repo = parse_owner_repo(remote_url)
+
+    vote = args.vote.lower()
+    if vote == "approve":
+        gh_args = ["pr", "review", str(args.pr_id), "--repo", owner_repo, "--approve"]
+        gh_cmd(gh_args)
+        print(f"Approved PR #{args.pr_id}")
+    elif vote == "reject":
+        gh_args = [
+            "pr", "review", str(args.pr_id), "--repo", owner_repo,
+            "--request-changes",
+            "--body", "AI review found Critical or High severity issues. See inline comments for details.",
+        ]
+        gh_cmd(gh_args)
+        print(f"Requested changes on PR #{args.pr_id}")
+    elif vote in ("wait-for-author", "wait"):
+        gh_args = [
+            "pr", "review", str(args.pr_id), "--repo", owner_repo,
+            "--comment",
+            "--body", "AI review: waiting for author to address review comments.",
+        ]
+        gh_cmd(gh_args)
+        print(f"Posted 'waiting for author' comment on PR #{args.pr_id}")
+    elif vote == "reset":
+        print(f"INFO: GitHub does not support vote reset. No action taken for PR #{args.pr_id}")
+    else:
+        print(f"ERROR: Unknown vote '{vote}'. Use: approve|reject|wait-for-author|reset")
+        sys.exit(1)
+
+
+# --- Main ---
+
+def main():
+    parser = argparse.ArgumentParser(description="TAS GitHub PR Integration")
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    p = subparsers.add_parser("pr-get", help="Get PR metadata")
+    p.add_argument("pr_id", type=int, help="Pull Request number")
+
+    p = subparsers.add_parser("pr-diff", help="Fetch PR branch and list changed files")
+    p.add_argument("pr_id", type=int, help="Pull Request number")
+
+    p = subparsers.add_parser("pr-comment", help="Post summary comment on PR")
+    p.add_argument("pr_id", type=int, help="Pull Request number")
+    p.add_argument("--comment", required=True, help="Comment text (markdown supported)")
+
+    p = subparsers.add_parser("pr-inline", help="Post inline comment on PR diff")
+    p.add_argument("pr_id", type=int, help="Pull Request number")
+    p.add_argument("--file", dest="file_path", required=True, help="File path (e.g. src/api/users.ts)")
+    p.add_argument("--line", type=int, required=True, help="Line number")
+    p.add_argument("--comment", required=True, help="Inline comment text")
+
+    p = subparsers.add_parser("pr-vote", help="Set vote on PR")
+    p.add_argument("pr_id", type=int, help="Pull Request number")
+    p.add_argument("--vote", required=True,
+                   choices=["approve", "reject", "wait-for-author", "reset"],
+                   help="Vote to cast")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "pr-get":
+        cmd_pr_get(args)
+    elif args.command == "pr-diff":
+        cmd_pr_diff(args)
+    elif args.command == "pr-comment":
+        cmd_pr_comment(args)
+    elif args.command == "pr-inline":
+        cmd_pr_inline(args)
+    elif args.command == "pr-vote":
+        cmd_pr_vote(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

package/README.md

@@ -7,17 +7,19 @@ TAS Kit - Turbo Agentic SDLC toolkit for modern AI-first software teams.
 ## Purpose
 
 TAS Kit helps software development teams:
-- **Standardize SDLC process** with clear artifacts (PRD, SAD, ADR, Epic, Feature, Story)
+- **Standardize SDLC process** with clear artifacts (PRD, SAD, ADR, Feature, Feature-Technical)
 - **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
 
+> **Kit v3 — Feature-only flow:** Epic and User Story were removed. Feature is now the single TAS work unit — one complete business flow that may span multiple stacks (`app` | `web` | `service` | `integration`). Per-stack technical breakdown lives in `Feature-{NNN}-Technical.md`. See [Migration](#migration-from-v1v2-epicstory-flow) at the bottom.
+
 ---
 
 ## 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.
+All code starts from spec. Each Feature owns a paired `Feature-{NNN}.md` (business AC) and `Feature-{NNN}-Technical.md` (global: Context Diagram, Data Flow, API Spec, ERD; per-stack: Logic Flow, File Changes, Config, Unit Tests, Tasks). Each implementation session only needs to read CLAUDE.md + the two Feature files — no need to reload PRD/SAD/ADR.
 
 ### Human-Led, AI-Powered
 - **Human-led**: Architecture decisions, design approval, code review
@@ -34,7 +36,7 @@ All code starts from spec. Story.md is "context digest" that has absorbed all in
 
 ### Role-Based & Template-Driven
 - 3 roles: PE (Product Engineer), SE (Software Engineer), DSE (DevOps Engineer)
-- Separate templates for PRD, SAD, ADR, Epic, Feature, Story per team standards
+- Separate templates for PRD, SAD, ADR, Feature, Feature-Technical per team standards
 - Flow configurable via `tas.yaml` file
 
 ### Azure DevOps Compatible
@@ -48,10 +50,13 @@ All code starts from spec. Story.md is "context digest" that has absorbed all in
 :::mermaid
 graph TD
     subgraph Phase1["Phase 1: Discovery"]
+        BRD["/tas-brd"]
         PRD["/tas-prd"]
         SAD["/tas-sad"]
         ADR["/tas-adr"]
         DESIGN["/tas-design"]
+        BRD -->|Product Engineer| BRD_ARTIFACT["BRD.md"]
+        BRD_ARTIFACT -->|Product Engineer| PRD
         PRD -->|Product Engineer| PRD_ARTIFACT["PRD.md"]
         PRD_ARTIFACT -->|Software Engineer| SAD
         PRD_ARTIFACT -->|Software Engineer| ADR
@@ -62,22 +67,25 @@ graph TD
     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
+        PLAN["/tas-plan"]
+        MASTERPLAN["/tas-master-plan"]
+        PRD_ARTIFACT -->|Product Engineer| FEATURE
         FEATURE --> FEATURE_ARTIFACT["Feature-XXX/"]
-        SAD_ARTIFACT --> FEATURE
+        SAD_ARTIFACT --> PLAN
         DESIGN_ARTIFACT --> FEATURE
-        FEATURE_ARTIFACT -->|Product Engineer| STORY
-        STORY --> STORY_ARTIFACT["Story-XXX.md"]
+        FEATURE_ARTIFACT -->|Software Engineer| PLAN
+        PLAN --> TECH_ARTIFACT["Feature-XXX-Technical.md"]
+        PRD_ARTIFACT -->|Tech Lead| MASTERPLAN
+        SAD_ARTIFACT --> MASTERPLAN
+        FEATURE_ARTIFACT -->|All Features created| MASTERPLAN
+        MASTERPLAN --> MP_ARTIFACT["docs/master-plan.md"]
     end
 
     subgraph Phase3["Phase 3: Implementation"]
-        PLAN["/tas-plan"]
+        ORCHESTRATE["/tas-orchestrate"]
         DEV["/tas-dev"]
+        DEBUG["/tas-debug"]
         FIX["/tas-fix"]
         APItest["/tas-apitest"]
         E2E["/tas-e2e"]
@@ -86,18 +94,22 @@ graph TD
         E2E_WEB["/tas-e2e-web"]
         E2E_MOBILE["/tas-e2e-mobile"]
         BUG["/tas-bug"]
-        REVIEW["/tas-review"]
+        REVIEWPR["/tas-review-pr"]
         FUNctest["/tas-functest"]
-        STORY_ARTIFACT -->|Software Engineer| PLAN
-        PLAN --> STORY_ARTIFACT
-        STORY_ARTIFACT -->|AI Agent| DEV
-        DEV --> CODE["Source Code"]
+        MP_ARTIFACT -->|Autonomous| ORCHESTRATE
+        TECH_ARTIFACT -->|Hybrid| DEV
+        ORCHESTRATE --> CODE["Source Code"]
+        DEV --> CODE
+        CODE -->|Build fails| DEBUG
+        DEBUG --> CODE
         CODE -->|Bug found| FIX
         FIX --> CODE
-        CODE -->|Software Engineer| REVIEW
-        REVIEW --> REVIEW_ARTIFACT["Code Review Report"]
-        STORY_ARTIFACT -->|Software Engineer| APItest
+        CODE -->|PR created| REVIEWPR
+        REVIEWPR --> REVIEW_ARTIFACT["PR Comments + Vote"]
+        TECH_ARTIFACT -->|Software Engineer| APItest
         APItest --> APITEST_ARTIFACT["API Testing Script"]
+        FEATURE_ARTIFACT -->|Product Engineer| FUNctest
+        FUNctest --> FUNCTEST_ARTIFACT["Func-Test-Spec.md"]
         FUNCTEST_ARTIFACT -->|Product Engineer| E2E
         E2E --> E2E_ARTIFACT["E2E Test Scenarios"]
         FUNCTEST_ARTIFACT -->|Software Engineer| FUNCTEST_WEB
@@ -110,8 +122,6 @@ graph TD
         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"]
@@ -131,13 +141,17 @@ graph TD
 
     STATUS["/tas-status"] -.->|Track| PRD_ARTIFACT
     STATUS -.->|Track| SAD_ARTIFACT
-    STATUS -.->|Track| STORY_ARTIFACT
+    STATUS -.->|Track| FEATURE_ARTIFACT
+    STATUS -.->|Track| TECH_ARTIFACT
     STATUS -.->|Track| DEPLOY
 
+    style BRD_ARTIFACT fill:#e1f5ff
     style PRD_ARTIFACT fill:#e1f5ff
     style SAD_ARTIFACT fill:#fff4e1
     style DESIGN_ARTIFACT fill:#f3e5f5
-    style STORY_ARTIFACT fill:#e8f5e9
+    style FEATURE_ARTIFACT fill:#e8f5e9
+    style TECH_ARTIFACT fill:#e8f5e9
+    style MP_ARTIFACT fill:#e8f5e9
     style CODE fill:#f3e5f5
     style TEST_REPORT fill:#c8e6c9
     style DEPLOY fill:#c8e6c9
@@ -147,29 +161,35 @@ graph TD
 
 | 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 1: Discovery** | PE, SE | `/tas-brd`, `/tas-prd`, `/tas-sad`, `/tas-adr`, `/tas-design` | BRD.md, PRD.md, SAD.md, ADR-XXX.md, design-spec.md |
+| **Phase 2: Planning** | PE, SE | `/tas-feature`, `/tas-plan`, `/tas-functest`, `/tas-master-plan` | Feature-XXX/, Feature-XXX-Technical.md, Func-Test-Spec.md, docs/master-plan.md |
+| **Phase 3: Implementation** | PE, SE, AI | `/tas-orchestrate`, `/tas-dev`, `/tas-debug`, `/tas-fix`, `/tas-apitest`, `/tas-e2e`, `/tas-functest-web`, `/tas-functest-mobile`, `/tas-e2e-web`, `/tas-e2e-mobile`, `/tas-bug`, `/tas-review-pr` | Source Code, API Testing Script, E2E Test Scenarios, Functional Test Scripts, Bug Report, PR Review Comments |
 | **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`
+- **PE**: Create BRD with `/tas-brd` — business problem, KPIs, stakeholders, scope first
+- **PE**: Create PRD with `/tas-prd` (consumes BRD.md), 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`
+- **PE**: Create Feature with `/tas-feature` — one Feature per business requirement (may span multiple stacks), AC in Given/When/Then
+- **SE**: Generate `Feature-XXX-Technical.md` with `/tas-plan` — global sections (Context Diagram, Data Flow, API Spec, ERD) + per-stack sections (Logic Flow, File Changes, Config, Unit Tests, Tasks)
+- **PE/SE**: Create Func-Test-Spec with `/tas-functest`
+- **Tech Lead**: After all Features are created, run `/tas-master-plan` — reads PRD FR list + SAD, scans Feature files to resolve dependencies, generates `docs/master-plan.md` with detailed strategy + machine-readable execution tracks
 
 #### 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`
+- **AI (Autonomous)**: Run `/tas-orchestrate` — executes master plan by spawning `software-engineer` agents per Feature in track order; supports resume and 24/7 unattended mode
+- **SE (Hybrid)**: Implement with `/tas-dev` (consumes Feature + Feature-Technical), fix with `/tas-fix`
+- **SE (Autonomous)**: `/tas-dev --autonomous=true` or set `autonomy_mode: full` in `tas.yaml` — auto-runs `/tas-plan` if no Technical file exists, implements without interruption, auto-marks Done when review passes; use for Features with clear scope where SE trusts full AI execution
+- **SE**: When build/runtime errors occur, run `/tas-debug` — full build-debug loop until resolved
 - **SE**: Create API Testing Script with `/tas-apitest`
-- **PE**: Create E2E Test Scenarios with `/tas-e2e`
+- **PE**: Create E2E Test Scenarios with `/tas-e2e` (chains multiple Features into a flow)
 - **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`
+- **SE**: Review PR with `/tas-review-pr` — auto-detects ADO/GitHub, posts inline comments + approve/request-changes vote
 
 #### Phase 4: Quality & Deploy
 - **DSE**: Security Review with `/tas-security`
@@ -250,14 +270,13 @@ artifacts:
     status: Approved
     version: "1.0"
 
-epics:
-  Epic-001:
-    status: Active
-    features:
-      Feature-001:
-        stories:
-          Story-001:
-            status: In Progress
+features:
+  Feature-001:
+    path: docs/features/PROJ-Feature-001-checkout/
+    title: "Checkout flow"
+    stack: web
+    status: In Development
+    plan_status: completed
 ```
 
 ### .env
@@ -276,12 +295,12 @@ AZURE_DEVOPS_PROJECT=your_project
 
 ```
 .claude/
-  commands/   22 slash commands (/tas-*, /ado-*)
-  skills/     3 auto-invoked skills
-  agents/     29 specialized subagents
+  commands/   slash commands (/tas-*, /ado-*)
+  skills/     auto-invoked skills
+  agents/     specialized subagents
 .tas/
-  templates/  Markdown templates (PRD, SAD, ADR, Epic, Feature, Story...)
-  rules/      Coding standards + workflow rules (code-review, story-done, security...)
+  templates/  Markdown templates (PRD, SAD, ADR, Feature, Feature-Technical, Bug...)
+  rules/      Coding standards + workflow rules (code-review, feature-done, security...)
   tools/      ADO integration script (tas-ado.py)
 CLAUDE.md     Project context template (edit this for your project)
 tas.yaml      Flow configuration template (edit this for your project)
@@ -296,18 +315,20 @@ tas.yaml      Flow configuration template (edit this for your project)
 |---------|-------------|------|
 | `/tas-init` | Initialize TAS for new project | All |
 | `/tas-status` | Display current project status | All |
-| `/tas-prd` | Create/update Product Requirements Document | PE |
+| `/tas-brd` | Create/update Business Requirements Document (problem, KPIs, stakeholders, scope) | PE |
+| `/tas-prd` | Create/update Product Requirements Document (consumes BRD.md) | 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-feature` | Create/update Feature (single TAS work unit, per stack) | PE |
+| `/tas-plan` | Generate `Feature-XXX-Technical.md` (Context, Logic, Data, ERD, Files, Config) | SE |
+| `/tas-functest` | Create Functional Test Spec (anchored on AC) | SE |
+| `/tas-master-plan` | Read PRD + SAD + Feature files → generate `docs/master-plan.md` (strategy + execution tracks) | Tech Lead |
 | `/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-orchestrate` | Execute master plan — spawn agents per Feature autonomously, supports resume | AI |
+| `/tas-dev` | Implement Feature per Technical Plan. `--autonomous=true` or `autonomy_mode: full` in `tas.yaml` → auto-plan + implement + review end-to-end | AI |
+| `/tas-debug` | Debug and resolve build/runtime/functional errors — full build-debug loop | SE |
+| `/tas-fix` | Quick fix without full Feature 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 |
@@ -316,6 +337,7 @@ tas.yaml      Flow configuration template (edit this for your project)
 | `/tas-e2e-mobile` | Create E2E Test Script for Mobile | PE |
 | `/tas-bug` | Create Bug Report | PE |
 | `/tas-review` | Code Review with checklist | SE |
+| `/tas-review-pr` | Review PR — fetch diff, run agents, post inline comments + vote (ADO/GitHub) | SE |
 | `/tas-brainstorm` | Brainstorm solutions | All |
 | `/tas-security` | Security Review | DSE |
 | `/ado-*` | Azure DevOps integration | All |
@@ -329,8 +351,63 @@ tas.yaml      Flow configuration template (edit this for your project)
 
 ---
 
+## Migration from v1/v2 (Epic/Story flow)
+
+Kit v3 drops Epic and User Story. The single TAS work unit is Feature.
+
+**What was removed:**
+- Slash commands: `/tas-epic`, `/tas-story`
+- Templates: `Epic.md`, `Story.md`
+- Rule: `story-done.md` (replaced by `feature-done.md`)
+- Nested `epics.{ID}.features.{ID}.stories.{ID}` schema in `project-status.yaml` (now flat `features.{ID}` map)
+- ADO `epic` and `story` types in `/ado-*` commands and `tas-ado.py` (legacy work items pulled via `/ado-get` are saved as local `feature-*.md`)
+
+**What was added:**
+- New template `Feature-Technical.md` — generated by `/tas-plan` next to Feature file (`Feature-{NNN}-{slug}-Technical.md`). Has global sections (Context Diagram, Data Flow, API Spec, ERD) + per-stack sections (Logic Flow, File Changes, Config, Unit Tests, Tasks — one section per stack the Feature touches).
+- Test ID convention anchored on AC: `{PROJECT}_F{FEATURE}_AC{N}_{TYPE}_{NUMBER}_{MODIFIER}`
+- E2E ID drops Epic segment: `{PROJECT}_E2E_{NNN}_{MODIFIER}` (single-stack) or `{PROJECT}_XSTACK_E2E_{NNN}_{MODIFIER}` (cross-stack)
+
+**How to migrate an existing project (manual, ~30 min for ~20 Features):**
+1. Move directories: `docs/epics/{*}/Feature-{NNN}-{slug}/` → `docs/features/{CODE}-Feature-{NNN}-{slug}/`. Re-number Features globally if you want a flat sequence.
+2. For each Feature directory:
+   - Pick the existing Feature .md as the new business spec; delete the parent Epic .md.
+   - Convert AC from checkbox style to Given/When/Then.
+   - If Stories had Technical Plan content inline, lift it into a new `Feature-{NNN}-Technical.md` using `.tas/templates/Feature-Technical.md` (fill only the stack sections that apply). Then delete the Story files.
+3. Rewrite `project-status.yaml`: drop `epics:` block, build a flat `features:` map (see `.tas/project-status-example.yaml`).
+4. Rename test IDs: `{PROJ}_E{EPIC}_F{FEAT}_S{STORY}_*` → `{PROJ}_F{FEAT}_AC{N}_*` (regex find/replace per file).
+5. On ADO: there's no API change required — TAS Features map to ADO `Feature` work items directly. Keep existing Epic/Story items as-is or close them; new TAS work uses `/ado-create feature ...` only.
+
+> No automated `tas-migrate` command is shipped — the migration is mechanical and per-project. Run `/tas-status` after to verify.
+
+---
+
 ## Changelog
 
+### v2.1.0 — BRD, Master Plan, Orchestrate, Debug, Review PR
+
+> **⚠️ Breaking change — Feature-first workflow**
+>
+> All work units are **Features**, stored under `docs/features/`. Every SE must start from a Feature file — no ad-hoc coding sessions.
+>
+> **Existing ADO User Stories pulled via `/ado-get`:** you can run `/tas-plan` + `/tas-dev` on those work items as-is — they behave as Features. No migration needed for in-flight work.
+>
+> **New tickets:** always create as Features with `/tas-feature` (or `/tas-master-plan` for full project planning) before running `/tas-plan` and `/tas-dev`. Do not create stories or epics — Feature is the only TAS work unit.
+
+- Add `/tas-brd` — PE creates Business Requirements Document (business problem, KPIs, stakeholders, scope/constraints) before PRD; `/tas-prd` consumes BRD.md for tighter business-to-product alignment
+- Add `/tas-master-plan` — Tech Lead command that reads PRD FR list + SAD + Feature files, resolves dependencies, and generates `docs/master-plan.md` with detailed construction strategy and machine-readable execution tracks (YAML embedded)
+- Add `/tas-orchestrate` — executes master plan by spawning `software-engineer` agents per Feature in stage/track order; supports resume and fully autonomous 24/7 mode
+- `/tas-dev` gains autonomous mode: `--autonomous=true` flag or `autonomy_mode: full` in `tas.yaml` — auto-invokes `/tas-plan` when no Technical file exists, implements without interruption, auto-marks Done if review passes with no Critical/High findings; audit trail written to Feature `## Autonomous Decisions Log`
+- Add `/tas-debug` — runs full build-debug loops to resolve build/runtime/functional errors; complements `/tas-fix` for post-implementation failures
+- Add `/tas-review-pr` — auto-detects ADO or GitHub, fetches PR diff, runs parallel review agents, posts inline comments with approve/request-changes vote
+
+### v2.0.0 — Feature-only flow + Feature-Technical template
+- Remove Epic and User Story. Feature is the only TAS work unit — one complete business flow, may span multiple stacks.
+- Add `Feature-Technical.md` template generated by `/tas-plan` — global sections (Context Diagram, Data Flow, API Spec, ERD, Affect to SAD?, Architecture Decisions) + per-stack sections (Logic Flow, File Changes, Config, Unit Test Cases, Tasks) — fill only stacks the Feature touches.
+- `/tas-feature` infers stacks automatically from PRD + SAD — no manual stack annotation required.
+- Test ID convention: `{PROJECT}_F{FEATURE}_AC{N}_{TYPE}_{NUMBER}_{MODIFIER}` to anchor tests on business AC.
+- Updated project-status.yaml tracking to include Feature-Technical plan_status (pending/completed).
+- E2E ID simplified: `{PROJECT}_E2E_{NNN}_{MODIFIER}` (single-stack) or `{PROJECT}_XSTACK_E2E_{NNN}_{MODIFIER}` (cross-stack).
+
 ### v1.14.0
 - Support 4 Agentic Coding Platforms: Claude Code, Cursor, Codex, Antigravity
 - Compress kit size — refactor commands, skills, rules to only include what's truly necessary