@torus-engineering/tas-kit 1.13.0 → 2.1.0

package/.tas/commands/tas-orchestrate.md

@@ -0,0 +1,159 @@
+---
+model: sonnet
+---
+
+# /tas-orchestrate $ARGUMENTS
+
+Role: Tech Lead — Orchestrator
+Execute the project master plan by spawning `software-engineer` agents per Feature in stage/track order. Blocking stages complete before next stage starts. Parallel stages batch by `max_parallel`. Tracks run concurrently across stacks. Supports resume — skips `done` Features on restart.
+
+`$ARGUMENTS` is optional. If provided, must be a track name (e.g., `service`) to execute only that track.
+`--autonomous=true|false` flag overrides `autonomy_mode` from `tas.yaml` for this run.
+
+**Scope:** Execution coordination only — reads plan, spawns agents, tracks status.
+**Out of scope:** Writing Features, writing Technical Plans, coding.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read `project-status.yaml` on start to skip `done` Features — never re-run completed work |
+| **Always** | Show execution queue and ask for confirmation before spawning agents (manual mode only) |
+| **Always** | In autonomous mode: skip confirmation, auto-spawn, report at end |
+| **Always** | Batch parallel stages by `max_parallel` from `tas.yaml` (default: 3) |
+| **Always** | Update `project-status.yaml` after each Feature completes |
+| **Always** | Pause a blocked/errored track — continue other tracks |
+| **Never** | Spawn next stage until all Features in current stage are `done` |
+| **Never** | Re-run a Feature with status `done` or `skipped` |
+
+## Prerequisites
+- `docs/master-plan.md` exists (run `/tas-master-plan` first if missing)
+- `project-status.yaml` has `master_plan` key
+
+## Steps
+
+**Step 1 — Load plan + current status**
+- Read `docs/master-plan.md` — parse YAML block under `## Execution Plan`
+- Read `project-status.yaml` — read `master_plan.tracks` for all Feature statuses
+- Read `tas.yaml` → `workflow.develop.orchestration.max_parallel` (default: `3` if absent)
+- Resolve autonomy mode (CLI flag wins over yaml):
+  1. Parse `--autonomous=true|false` from `$ARGUMENTS`
+  2. If absent → read `autonomy_mode` from `tas.yaml` (`manual` | `full`, default `manual`)
+  3. `autonomous = true` iff CLI `true` OR (CLI absent AND `autonomy_mode: full`)
+- Update `project-status.yaml`: `master_plan.status: in_progress`
+- If `$ARGUMENTS` contains a track name → filter to that track only; otherwise run all tracks
+
+**Step 2 — Build execution queue**
+
+For each track (in parallel across tracks):
+1. Skip Features already `done` or `skipped`
+2. Find current stage (lowest stage number where not all Features are `done`)
+3. Check blocking constraint: stage N Features only queue if all stage N-1 Features are `done`
+4. Check cross-track `depends_on`: Feature only queues if all listed dependency Features are `done`
+5. Note stage type (`blocking` / `sequential` / `parallel`)
+
+Show queue:
+```
+Execution queue:
+
+Track: service
+  Stage 1 [blocking] → Feature-001 scaffold-service
+Track: web
+  Stage 1 [blocking] → Feature-002 scaffold-web
+
+(Subsequent stages queue as each stage completes per track)
+```
+
+**Manual mode** (`autonomous = false`): show queue, ask `Proceed? (yes / abort)`, wait for user.
+**Autonomous mode** (`autonomous = true`): show queue, skip confirmation, proceed immediately to Step 3.
+
+**Step 3 — Execute features**
+
+Spawn `software-engineer` agents. Pass feature context in prompt.
+
+For each queued Feature:
+```
+Agent({
+  subagent_type: "software-engineer",
+  description: "Feature-{ID} {slug}",
+  prompt: "feature_id: {Feature-ID}
+slug: {slug}
+feature_file: {feature_file_path}
+technical_file: {technical_file_path}"
+})
+```
+
+**Parallel stage batching:**
+- Do NOT spawn all Features in a parallel stage at once
+- Split stage Features into batches of `max_parallel`
+- Batch 1: spawn `max_parallel` agents simultaneously (single message, multiple Agent calls)
+- Wait for all in batch → update status (Step 4) → spawn next batch
+- Only advance to next stage after all batches in current stage are done
+
+Example — `max_parallel: 3`, 7 Features in parallel stage:
+```
+Batch 1: Feature-007, Feature-008, Feature-009  → wait → update
+Batch 2: Feature-010, Feature-011, Feature-012  → wait → update
+Batch 3: Feature-013                            → wait → update
+→ stage done → queue next stage
+```
+
+Sequential stages: always spawn one Feature at a time regardless of `max_parallel`.
+
+**Step 4 — Process results + update status**
+
+After each agent returns, parse result prefix:
+
+- `DONE: Feature-NNN` →
+  - Update `project-status.yaml`:
+    - `master_plan.tracks.{track}.stages.{N}.features.Feature-NNN: done`
+    - `features.Feature-NNN.status: Done`
+    - `features.Feature-NNN.done_date: {today}`
+  - If all Features in stage `done` → set stage status: `done` → queue next stage
+
+- `BLOCKED: Feature-NNN — {reason}` →
+  - Update: `master_plan.tracks.{track}.stages.{N}.features.Feature-NNN: blocked`
+  - Log reason, pause track, continue other tracks
+
+- `ERROR: Feature-NNN — {reason}` →
+  - Update: `master_plan.tracks.{track}.stages.{N}.features.Feature-NNN: error`
+  - Log reason, pause track, continue other tracks
+
+Always update: `master_plan.last_updated: {today}`
+
+**Step 5 — Continue until all tracks exhausted**
+
+Repeat Steps 3–4 until no Features remain to queue across all active tracks.
+
+**Step 6 — Final report**
+
+When all tracks complete:
+- If all `done` → update `project-status.yaml`: `master_plan.status: completed`
+- If any `blocked`/`error` → `master_plan.status: in_progress`
+
+Output:
+```
+Orchestration complete.
+
+✅ Done (N):    Feature-001, Feature-002, Feature-003
+⚠️  Blocked (N): Feature-007 — auth service not responding
+❌ Error (N):   Feature-008 — compilation failed in payment module
+
+project-status.yaml updated.
+Blocked/errored features require manual fix, then re-run /tas-orchestrate to resume.
+```
+
+---
+
+## Resume behavior
+
+On re-run when `master_plan.status: in_progress`:
+1. Read current statuses from `project-status.yaml`
+2. Skip all `done` Features
+3. Features with `in_progress`: re-spawn (previous agent may have died)
+4. Features with `blocked` or `error`: skip unless manually cleared in `project-status.yaml` first
+5. Show updated queue → manual: confirm → continue | autonomous: auto-continue
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/master-plan.md`.

package/.tas/commands/tas-plan.md

@@ -1,198 +1,233 @@
+---
+model: opus
+---
+
 # /tas-plan $ARGUMENTS
 
 Role: SE - Software Engineer
-Bridge between business (Story) and technical (code).
-Analyze Story, create technical plan, break tasks — before implementing.
+Bridge between business (Feature) and technical (code).
+Analyze Feature, generate `Feature-{NNN}-Technical.md` from `.tas/templates/Feature-Technical.md`.
+
+`$ARGUMENTS` may include `--autonomous=true|false` (overrides `autonomy_mode` in `tas.yaml`).
 
-**Required output:** Technical Plan written to Story file + `plan_status: completed`.
+**Required output:** New file `{CODE}-Feature-{NNN}-{slug}-Technical.md` next to the Feature file, plus `plan_status: completed` on the Feature.
 
 ## Always / Ask / Never
 
 | | Action |
 |---|---|
-| **Always** | Read Story file before doing anything |
-| **Always** | Wait for user to approve plan before writing to Story |
-| **Always** | Write Technical Plan to Story file after approval |
-| **Ask** | When need to reference SAD/ADR — confirm with user before reading |
-| **Ask** | When Story scope > 8 hours — suggest splitting Story |
+| **Always** | Read Feature file before doing anything |
+| **Always** | Use `.tas/templates/Feature-Technical.md` as the structure |
+| **Always** | Wait for user approval before writing the technical file (manual mode only) |
+| **Always** | Write `plan_status: completed` + `plan_date` to Feature frontmatter after approval |
+| **Ask** | When need to reference SAD/ADR — confirm before reading (manual mode only) |
 | **Never** | Start implementing in this command |
-| **Never** | Read SAD/ADR without asking user first |
-| **Never** | Write plan to Story without approval |
+| **Never** | Read SAD/ADR without asking user first (manual mode) |
+| **Never** | Write Technical file before user approval (manual mode) |
+| **Never** | Auto-run `/tas-adr` even in autonomous mode — log candidates only |
+| **Never** | Add technical content (schema, SQL, code, migration, data model, API spec) to the Feature file — Feature file is business spec only; all technical output goes to Feature-Technical file |
+
+## Autonomous Mode
+
+Resolve `autonomous` flag at start (CLI flag wins over yaml):
+1. Parse `--autonomous=true|false` from `$ARGUMENTS`
+2. If absent → read `autonomy_mode` from `tas.yaml` (`manual` | `full`, default `manual`)
+3. Final value: `autonomous = true` iff CLI `true` OR (CLI absent AND `autonomy_mode: full`)
+
+When `autonomous = true`:
+- Step 3 (SAD/ADR ask): skip ask. Auto-read SAD section / ADR file when reasoning calls for it. Log paths read in `## Autonomous Decisions Log` on Feature file.
+- Step 5 (multiple feasible approaches): auto-pick simplest that satisfies AC + matches existing patterns from code-explorer survey. Log decision in Technical file `Architecture Decisions` section with `Auto-selected: true` column.
+- Step 6 (wait approval): skip. Write Technical file straight to disk.
+- Re-plan prompt (Step 1): if Technical file already exists → skip ask, overwrite, log entry to `## Autonomous Decisions Log`.
+
+Mandatory audit trail in autonomous mode:
+- Set Feature frontmatter: `autonomous_run: true`, `autonomous_run_date: {datetime}`
+- Append every skipped gate + chosen path to Feature `## Autonomous Decisions Log`
 
 ## Actions
 
-### Step 1 — Identify Story
+### Step 1 — Identify Feature
 
-`$ARGUMENTS` can be: Story ID (`Story-005`), file path, or Story description.
+`$ARGUMENTS` can be: Feature ID (`Feature-005`), file path, or Feature description.
 
-- If Story ID: find file via glob `docs/epics/**/*-Story-{ID}-*.md`
+- If Feature ID: find file via glob `docs/features/{CODE}-Feature-{ID}-*/{CODE}-Feature-{ID}-*.md` (the file WITHOUT `-Technical` suffix)
 - If file path: read directly
-- If description: ask user for specific Story ID/file
-- Read Story file
+- If description: ask user for specific Feature ID/file
+- Read Feature file
 
-**Check re-plan:** If `plan_status: completed` → ask user:
-> "This Story already has a Technical Plan. Do you want to re-plan?"
-If user confirms → continue. If not → stop.
+**Check re-plan:** If `plan_status: completed` (Technical file already exists):
+- **Manual mode:** ask:
+  > "Feature-{NNN} already has a Technical Plan. Re-plan and overwrite?"
+  If user confirms → continue. If not → stop.
+- **Autonomous mode:** skip ask, overwrite, log entry: `re-plan overwrite | reason: autonomous run`.
 
 ### Step 2 — Parallel Context Gathering
 
 Launch 2 agents SIMULTANEOUSLY:
 
 **Agent 1 — `code-explorer`** (always run):
-> Survey codebase related to Story: "{Story title + AC summary}".
-> Find: entry points, files likely to change, existing patterns, dependencies.
+> Survey codebase related to Feature: "{Feature title + AC summary}".
+> Feature may span multiple stacks — survey all relevant layers (web, service, integration, app).
+> Find: entry points, files likely to change, existing patterns, dependencies across all involved stacks.
 > Read max 10 most relevant files.
-> Return: concise map — what exists, what needs to change, potential conflicts.
+> Return: concise map — what exists per stack, what needs change, potential conflicts.
 
-**Agent 2 — `architect`** (only run if Story shows architectural changes:
-new service/module, data flow changes, external system integration,
-database schema changes, new design pattern):
-> Evaluate architectural implications of Story: "{Story title}".
+**Agent 2 — `architect`** (only if Feature shows architectural changes:
+new service/module, data flow change, external integration, schema change, new design pattern):
+> Evaluate architectural implications of Feature: "{Feature title}".
 > Read `docs/sad.md` (if exists) and files in `docs/adr/`.
 > Read `.tas/rules/common/patterns.md`.
 > Return: which ADRs relate, patterns to follow, architectural risks, constraints.
 
-Wait for ALL agents to finish, synthesize findings.
+Wait for ALL agents to finish, synthesize.
 
 ### Step 3 — Ask about SAD/ADR (if still unclear)
 
-After seeing agent findings, if need to reference specific SAD or ADR:
-> "I need to read [SAD / ADR-XXX] to clarify [reason]. OK?"
+If need to reference specific SAD section or ADR:
+- **Manual mode:** ask
+  > "I need to read [SAD section X / ADR-XXX] to clarify [reason]. OK?"
+  Only read after user confirms.
+- **Autonomous mode:** auto-read. Log path + reason to Feature `## Autonomous Decisions Log`.
 
-Only read after user confirms.
+### Step 4 — API Design (if Feature involves backend API)
 
-### Step 4 — API Design (if Story involves backend API)
-
-**If Story shows API design** (new endpoint, API contract change, exposing service):
-Read `.tas/rules/common/api-design.md` for REST API conventions, then design API Spec before planning:
+If Feature shows API design (new endpoint, contract change, exposing service):
+Read `.tas/rules/common/api-design.md` for REST conventions, then design API Spec:
 - URL structure, HTTP methods, status codes
-- Request/response payload shape
+- Request/response payload shape (JSON schema examples)
 - Pagination, filtering if needed
-- Error response format
-
-Attach API Spec to **Technical Plan → API Contract** section in Story.
-If Story not API-related → skip this step.
-
-### Step 5 — Technical Analysis
-
-Based on Story + agent findings, list clearly:
+- Error codes + response format
 
-**Files to change:**
-| File | What change | Why |
+This API Spec goes into the Technical file's **API Spec** section.
 
-**Files to create** (if any):
-| File | Purpose |
+### Step 4.5 — Estimate Size + Choose Split Mode
 
-**Database changes** (if any): migration, schema changes, seed data
+Before drafting full content, estimate plan size from agent survey findings:
 
-**Config/Infrastructure changes** (if any): env vars, feature flags, new dependencies
+- Count stacks involved
+- Estimate tasks per stack (1 task ≈ 1–2h AI coding time)
 
-**Need to update SAD?** Yes/No + brief reason
+**Choose `split_mode`:**
 
-**Need new ADR?** Yes/No + brief reason
-
-### Step 6 — Propose approach
-
-If multiple feasible approaches, list 2-3 options:
-```
-Option A: [short description]
-  + [pro]
-  - [con]
+| Condition | split_mode |
+|---|---|
+| ≤ 2 stacks AND total tasks ≤ 4 | `single` |
+| 2–3 stacks OR any stack total tasks > 4, stacks independently implementable | `stack-split` |
+| 3+ stacks OR sub-flows that cut across stacks (one part touches multiple stacks together) | `sub-feature-split` |
 
-Option B: [short description]
-  + [pro]
-  - [con]
-```
-Recommend best option and reason. If only 1 approach → present directly.
+State chosen mode explicitly before drafting:
+> "Chosen `split_mode: {mode}`. Reason: {N stacks, ~X total tasks, Y condition}."
 
-### Step 7 — Break Tasks
+### Step 5 — Draft Technical Plan (in-conversation, NOT yet written to file)
 
-Break down into implementation-order tasks. Each task ~1-2 hours:
-```
-- [ ] Task 1: [specific action — which file, what change]
-- [ ] Task 2: [specific action]
-- [ ] Task 3: Write unit tests for [AC-1, AC-2...]
-- [ ] Task 4: [if needed] Create ADR / update SAD
-```
+Read `.tas/templates/Feature-Technical.md` for structure. Read `.tas/rules/common/sad-impact.md` for SAD Impact Matrix trigger list. Draft based on chosen `split_mode`.
 
-If total estimate > 8 hours → suggest splitting Story before continuing.
+**Filling SAD Impact Matrix:** For each of the 8 categories in `sad-impact.md`, scan plan content (Tech Stack additions in Config tables, ERD `New tables`, Diagram new nodes, API Spec changes, Architecture Decisions rows) → mark `Detected: Yes` if any signal applies, fill SAD section ref + change summary + ADR candidate flag. Set Technical-file frontmatter `sad_impact: true` if any row Yes.
 
-### Step 8 — Wait for approval
+**Stack-specific scaffolding rules** (read only when applicable, before drafting Execution Plan):
+- **.NET / C# backend AND target dir has no `*.sln`** → Read `.tas/rules/csharp/torus-core-framework.md`. Pin exact `torus-bootstrap create ...` command (with all chosen flags) as the first step in Execution Plan.
 
-**STOP.** Display entire plan and ask:
-> "Does the Technical Plan above look OK? Any adjustments?"
+**Global sections (always in index/main file, regardless of split_mode):**
+- **Context Diagram** — all containers involved, callers, DBs touched, external systems (Mermaid)
+- **Data Flow** — end-to-end data journey across all stacks (Mermaid)
+- **API Spec** — (only if Feature exposes new/changed interfaces) contracts between stacks
+- **ERD** — tables involved; new tables/columns/indexes (Mermaid)
+- **SAD Impact Matrix** — fill per `.tas/rules/common/sad-impact.md` (8 categories). Set frontmatter `sad_impact: true` if any row `Detected: Yes`. Auto-invoke `/tas-sad` happens in `/tas-dev` Step 5, not here.
+- **Architecture Decisions** — document all significant design decisions + rationale; mark candidates for ADR review (human decides)
+- **Execution Plan** — table of parts/stacks with file refs, dependency order, parallel-safe flag, est. time
 
-- If user approves → Step 9
-- If user has feedback → update plan, ask again
-- DO NOT write anything to Story before approval
+**Per-stack / per-part detail sections — location depends on split_mode:**
 
-### Step 9 — Write Technical Plan to Story
+| split_mode | Where to put Logic Flow / File Changes / Config / Unit Tests / Tasks |
+|---|---|
+| `single` | In main file, one section per stack (classic format) |
+| `stack-split` | In child files `Feature-{NNN}-Technical-{stack}.md` — use `Feature-Technical-Stack.md` template. Main file has NO stack detail. |
+| `sub-feature-split` | In child files `Feature-{NNN}-Technical-{part-slug}.md` — use `Feature-Technical-Part.md` template. Main file has NO part detail. |
 
-After approval, update Story file:
+For `stack-split` / `sub-feature-split`: draft both the index content AND child file content in-conversation (all visible in one response for review), clearly labeled.
 
-**1. Add section `## Technical Plan`** to Story (replace comment placeholder):
+If multiple feasible approaches:
+- **Manual mode:** list 2–3 options with pros/cons and recommend one.
+- **Autonomous mode:** auto-pick simplest path that satisfies AC + matches existing patterns from code-explorer. Document in `Architecture Decisions` section with `Auto-selected: true`. Mark high-impact decisions as ADR candidates (still human-triggered).
 
-```markdown
-## Technical Plan
-> **Plan by:** {SE name} | **Date:** {current date}
+### Step 6 — Wait for approval
 
-### Approach
-{Brief description of chosen approach and reason}
+- **Manual mode: STOP.** Display the entire draft and ask:
+  > "Technical Plan above OK? Any adjustments before I write it to file?"
+  - If user approves → Step 7
+  - If user has feedback → update draft, ask again
+  - DO NOT write any file before approval
+- **Autonomous mode:** skip wait. Continue Step 7 directly. Log skipped-approval entry.
 
-### Files to Change
-| File | Change | Reason |
-|------|--------|--------|
+### Step 7 — Write Technical file
 
-### Files to Create
-| File | Purpose |
-|------|---------|
+After approval:
 
-### Database Changes
-{If none: "None"}
+**1. Write Technical file(s)** in same directory as Feature file:
 
-### Config Changes
-{If none: "None"}
+**If `split_mode: single`:**
+- Create `{CODE}-Feature-{NNN}-{slug}-Technical.md` using `.tas/templates/Feature-Technical.md`
+- Fill frontmatter: `feature_id`, `feature_file`, `plan_by`, `plan_date`, `status: Draft`, `split_mode: single`
+- Fill all global sections + all involved stack sections
 
-### Architecture Notes
-- SAD update needed: Yes/No
-- New ADR needed: Yes/No — {title if Yes}
+**If `split_mode: stack-split`:**
+- Create index `{CODE}-Feature-{NNN}-{slug}-Technical.md`:
+  - Fill frontmatter with `split_mode: stack-split`
+  - Global sections + Execution Plan only — NO stack detail sections
+- For each involved stack, create `{CODE}-Feature-{NNN}-{slug}-Technical-{stack}.md` using `.tas/templates/Feature-Technical-Stack.md`:
+  - Fill `parent_technical_file` pointing to index file
+  - Fill Logic Flow, File Changes, Config, Unit Tests, Tasks for that stack only
 
-### Tasks
-- [ ] Task 1: ...
-- [ ] Task 2: ...
-- [ ] Task 3: Write unit tests
-```
+**If `split_mode: sub-feature-split`:**
+- Create index `{CODE}-Feature-{NNN}-{slug}-Technical.md`:
+  - Fill frontmatter with `split_mode: sub-feature-split`
+  - Global sections + Execution Plan only — NO part detail
+- For each part, create `{CODE}-Feature-{NNN}-{slug}-Technical-{part-slug}.md` using `.tas/templates/Feature-Technical-Part.md`:
+  - Fill `parent_technical_file`, `part_id`, `part_title`, `stacks_involved`
+  - Fill stack sections only for stacks this part touches
 
-**2. Update frontmatter:**
+**2. Update Feature frontmatter:**
 - `plan_status: completed`
 - `plan_date: {current datetime}`
+- If autonomous run: also set `autonomous_run: true` + `autonomous_run_date: {datetime}` (preserve if already true from prior step)
 
 **3. Update `project-status.yaml`:**
 - `last_updated: {current date}`
-- `epics.{EPIC_ID}.features.{FEATURE_ID}.stories.{STORY_ID}.plan_status: completed`
+- `features.{FEATURE_ID}.plan_status: completed`
+- `features.{FEATURE_ID}.technical_file: {path}`
 
-**4. If ADR needed:** run `/tas-adr "{Decision title}"` immediately after writing plan.
+**4. Document architectural decisions in Technical file — ADR creation is human-triggered:**
+- Significant decisions go in "Architecture Decisions" section
+- Mark candidates for ADR review (`Yes` in ADR Candidate column)
+- **Do NOT auto-run `/tas-adr`** — human will review and decide
 
-### Step 10 — Notify next step
-> "Technical Plan written to Story. SE can start implementing with `/tas-dev {Story-ID}`."
+### Step 8 — Notify next step
+- **Manual mode:**
+  > "Technical Plan written: `{path-to-Technical.md}`. SE can start implementing with `/tas-dev {Feature-ID}`."
+- **Autonomous mode (when invoked inline by `/tas-dev`):** Output **zero text**. Do NOT print any message, summary, or status to the user — any text output ends the turn and forces a manual "ok". After file writes complete, execution returns automatically to the calling `tas-dev` Step 2. Silence is required.
 
 ---
 
-## Quick Mode (require_plan: false in tas.yaml)
+## Quick Mode (`require_plan: false` in tas.yaml)
 
 For: solo dev, prototype, spike, urgent hotfix.
 
 - `/tas-dev` will NOT require running `/tas-plan` first
-- `/tas-plan` can still be run voluntarily when Story is complex
+- `/tas-plan` can still be run voluntarily when Feature is complex
 - Trade-off: higher speed, lower traceability
 
 ## Principles
-- Technical Plan lives in Story file — no separate plan file
-- Each task ~1-2 hours; whole Story ~4-8 hours
-- If estimate > 8 hours → split Story
-- If task affects architecture → suggest ADR
-- Keep plan concise, actionable — don't write essays
+- **Feature file = business spec only.** Never add sections beyond the template structure. No schema, SQL, code, data model, or technical diagrams in Feature file — all technical output belongs in Feature-Technical file.
+- Technical Plan lives in **separate file(s)** next to the Feature — always start with `Feature-{NNN}-Technical.md` as index
+- Each Task ~1–2 hours; break into smaller tasks if work block is unclear
+- Only fill stack sections that this Feature actually touches — omit the rest
+- Document all significant architectural decisions in "Architecture Decisions" section; mark candidates for ADR review
+- **ADR creation requires human approval** — SE documents decision + rationale, human decides if formal ADR needed
+- Keep plan concise, actionable — no essays
+- **Split mode rules:** `single` when ≤ 2 stacks + ≤ 4 tasks total; `stack-split` when stacks are independently implementable; `sub-feature-split` when sub-flows cut across stacks
+- Child files contain implementation detail only — global context (ERD, API Spec, etc.) lives in index, child references it by link, no duplication
+- Execution Plan in index is the orchestration contract for `tas-dev` — must be accurate and complete before writing files
 
 ## Final Step — Token Log
 
-Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working Story file.
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working Feature file.

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

@@ -1,37 +1,57 @@
-# /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`.
+---
+model: opus
+---
+
+# /tas-prd $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update Product Requirements Document.
+
+## Actions
+1. Read root/tas.yaml for project context
+2. Check if docs/brd.md exists — store result as HAS_BRD (yes/no)
+3. Check if docs/prd.md already exists:
+
+### CREATE mode (file doesn't exist):
+4. Read .tas/templates/PRD.md
+5. If HAS_BRD = yes: read docs/brd.md for business context
+6. If $ARGUMENTS has content, use as product description input
+7. If no $ARGUMENTS, ask user:
+   - What product or feature does this PRD cover?
+   - Who are the primary users / personas?
+   - What are the core features (P0 must-haves)?
+   - Any technical or integration constraints?
+   - (Skip business goal questions if HAS_BRD = yes — read from BRD instead)
+8. Create file docs/prd.md per template:
+   - **If HAS_BRD = yes:** Fill Business Context using "WITH BRD" format — summary (2-3 sentences from BRD Problem Statement) + link to brd.md + Business Goals bullets copied from BRD. Remove STANDALONE format blocks.
+   - **If HAS_BRD = no:** Fill Business Context using "STANDALONE" format — fill all sub-sections (Why Now, User Research, Market Analysis, Business Goals, User Goals). Remove WITH BRD format blocks.
+9. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add `artifacts.prd`
+
+### UPDATE mode (file exists):
+4. Read current docs/prd.md
+5. If HAS_BRD = yes: read docs/brd.md to stay aligned with business context
+6. $ARGUMENTS is change description. If not provided, ask user which section to update.
+7. Update file, keep unchanged sections as-is
+8. If HAS_BRD = yes and Business Context section is in STANDALONE format: offer to collapse it to WITH BRD format
+9. Add line to Changelog section at end: date, change description
+10. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `artifacts.prd`
+
+## Principles
+- **Two sections:** Business Context (problem, goals, research) + Product Specification (features, AC, flows)
+- Business Context adapts to BRD presence — never duplicate full business analysis when BRD exists
+- Write Acceptance Criteria in Given/When/Then format — each AC generates test ID + automated test
+- 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
+
+## Flow Context
+- Upstream: BRD (optional) → **PRD** → Feature → Feature-Technical
+- `/tas-brd` creates `docs/brd.md` (business level: why, goals, stakeholders, constraints)
+- `/tas-prd` creates `docs/prd.md` (product level: features, AC, UX, NFR)
+- `/tas-feature` uses PRD as input to create Feature files
+
+## Final Step — Token Log
+
+Apply `.tas/rules/common/token-logging.md` to `docs/prd.md` NOW (do not defer, do not leave placeholder text). Estimate input/output tokens from this session per the rule, then fill the `## AI Usage Log` table row and Total. The PRD template already includes the skeleton — replace `~{N}k` with actual estimates.