--- model: opus --- # /tas-master-plan $ARGUMENTS Role: Tech Lead — Master Plan Architect Generate full project execution plan from PRD FRs: propose scaffold Features, order all Features into dependency tracks, write machine-readable plan. Orchestration Agent reads this plan to auto-execute via `/tas-dev`. **Scope:** Planning only — reads PRD FRs, proposes scaffolds, writes plan file. **Out of scope:** Writing business Feature content (that's `/tas-feature`), coding, testing. ## Always / Ask / Never | | Action | |---|---| | **Always** | Read PRD FR list as source of truth — not `docs/features/` | | **Always** | Propose one scaffold Feature per stack before business Features | | **Always** | Run the feature-completeness gap pass (read SAD §8–12, apply lenses) after FR mapping; PE approves implicit Features before tracks are built | | **Always** | Order tracks by SAD dependency: `service` → `integration` → `web` → `app` | | **Always** | Write YAML plan block in `docs/master-plan.md` for Orchestration Agent | | **Always** | Sync plan to root/`project-status.yaml` under `master_plan` key | | **Always** | On resume: read root/`project-status.yaml` to skip `done` Features — never re-run completed work | | **Never** | Plan Features not in PRD without PE approval | | **Never** | Skip scaffold phase | | **Never** | Assign Feature IDs without scanning `docs/features/` for existing max NNN | ## Prerequisites - `tas.yaml` at project root - `docs/prd.md` with FR list - SAD file (path from `tas.yaml` or `docs/sad.md`) — for stack/dependency info ## Steps ### CREATE mode (no existing master plan) **Step 1 — Read context** - Read `project.code` from `tas.yaml` - Read `docs/prd.md` — extract full FR list: ID, title, brief description - Read SAD — extract stacks present + dependency order between stacks - Read root/`project-status.yaml` — check for existing `master_plan` key If `master_plan` key exists with `status: in_progress` → announce resume mode and go to **RESUME mode** below. **Step 2 — Scaffold proposal** For each stack found in SAD (`service` → `integration` → `web` → `app`, only stacks present), propose one scaffold Feature. Show in-conversation: ``` Scaffold Features (Phase 1 — blocking — must complete before business Features in each track): [ ] scaffold-service Service foundation: DI, DB setup, error handling, logging, auth middleware base [ ] scaffold-web Web foundation: routing, DI, error handling, API client base, logging [ ] scaffold-app App foundation: navigation, DI, error handling, theme, logging Approve all scaffolds? (yes / customize / skip) ``` - Approved → Step 3 - Customize → adjust list, then Step 3 - Skip → warn: "⚠️ Scaffold features skipped. Foundation setup must be handled manually before coding." → Step 4 **Step 3 — Create scaffold Feature docs (inline)** For each approved scaffold: - Scan `docs/features/` for max existing NNN → assign next sequential IDs (scaffold Features first) - Create `docs/features/{CODE}-Feature-{NNN}-scaffold-{stack}/` - Create Feature file using `.tas/templates/Feature.md` - Fill content using **Scaffold Content Guide** (section below) - Add each scaffold Feature to `project-status.yaml` per `.tas/rules/common/project-status.md` **Step 4 — Extract the design inventory, then map to Feature IDs and stacks** First **extract the full design inventory** from PRD + SAD — the complete list of every tracked ID that must be realized (this is the master checklist nothing may fall off): - Components `MOD-NN.C#` (SAD §7 component tables) · Entities `E-NNN` (§8.1) · Contracts `IC-NN` (§9.2) · NFRs `NFR-NNN` (§11) · Security `SEC-NN` (§10) · FRs `FR-NNN` (PRD §5) Then, for each FR in PRD: - Infer which stacks it touches (cross-reference SAD layer responsibilities) - Map via the SAD §7 component tables (the `FRs` column) — which `MOD-NN.C#` components realize this FR (these become the Feature's `Builds`); also note the entities it owns (§8.1), contracts it produces (§9.2), and NFR/SEC items that apply - Assign tentative Feature ID (continuing from scaffold max NNN + 1) - Note inter-FR dependencies (e.g., auth FR must precede profile FR) - Primary stack = the stack owning the core logic of this FR Result: ordered list of `{Feature-ID, FR-title, primary-stack, touches-stacks[], builds[component IDs], owns[E-NNN], produces[IC-NN], nfrs[NFR-NNN], security[SEC-NN], depends-on[]}` **Step 4.5 — Design-item coverage pass (the "nothing missed" gate)** Run the gap analysis from `.tas/rules/common/feature-completeness.md`: - **Design-item coverage (Step 1.5 of the rule):** take the inventory from Step 4 and assert **every item of every tracked type is claimed by ≥1 Feature** — components via `Builds`, entities via `Entities (owns)` (exactly one owner each), contracts via `Contracts (produces)` (one producer each), NFRs via `NFRs`, security controls via `Security`. Any unclaimed item → propose/extend a Feature (buildable) or route to a constraint/dedicated Feature (cross-cutting NFR/SEC), so no designed piece is left unbuilt. `infra` items may be owned by a scaffold Feature. - **Functional lenses:** read SAD §8–12, walk the 11 lenses against the full FR set. - **Route** each candidate (→ Feature / → NFR / → SAD) and present the rule's approval table. - **Gate:** if any `origin: feature` tracked item is still unclaimed after routing → block when `tas.yaml workflow.gate_enforcement: true` (list the orphans); warn + continue in solo mode. **Skip `origin: baseline` items** (pre-existing brownfield code seeded by `/tas-init`) — they are Covered without a Feature. - **Feature Planning coverage gate — run the `coverage-auditor` agent** (see `.tas/agents/coverage-auditor.md`): besides design-item coverage it asserts every FR is claimed by ≥1 Feature, every Feature traces to ≥1 FR, and the **derived Product-Goal check** — a Feature serves `PG-X` when any of its `implements_frs` references a `BR-NNN` that `PG-X` serves; a Feature whose FRs serve no Product Goal is flagged as gold-plating for the PE. Surface its report for approval. Approved `→ Feature` rows fold into the Step 4 mapping (assign IDs continuing the sequence) before tracks are built; `→ SAD` candidates are reported as architecture gaps, not planned here. **Compute each Feature's Product-Goal contribution** (used for ordering in Step 5): map Feature → `implements_frs` → `BR-NNN` → the `PG-NNN` serving those BRs. A Feature inherits the priority of the highest-priority PG it serves. This is derived, not stored. **Step 5 — Build execution tracks** Group Features by primary stack → one track per stack. Within each track, assign stages (each stage = one execution wave — all Features in a stage can start simultaneously): - **Stage 1 — blocking**: scaffold Feature only. No other Feature in track starts until scaffold is `done`. - **Stage N — sequential**: single Feature with dependency on previous stage outcome. One Feature per stage. - **Stage N — parallel**: multiple Features with no dependencies on each other, but all depend on previous stage. Orchestration Agent batches by `max_parallel`. Rule: if Feature A and Feature B both depend only on Stage N-1, they belong in the same stage. If Feature B depends on Feature A, they belong in separate sequential stages. **Product-Goal ordering (within the dependency constraint):** dependencies always win — never reorder across a real `depends_on`. But when Features are otherwise free to order (same parallel stage, or independent sequential candidates), rank the higher **Product-Goal contribution** first (from Step 4.5). The Master Plan takes `PRD.Product Goal` as its priority axis, so the feature that pushes the top goal ships earlier. Note the driving `PG-NNN` next to each stage for traceability. Cross-track dependencies (e.g., web Feature depends on service auth Feature): mark as `depends_on: [Feature-NNN]` — Orchestration Agent enforces before spawning. **Step 6 — Write `docs/master-plan.md`** ```markdown # Master Plan — {CODE} _Generated: {date} | Status: ready_ ## Overview {N} FRs → {N} Features across {N} tracks: service, web, app ## Tracks ### Track: service **Stage 1 [blocking]:** Feature-001 scaffold-service **Stage 2 [sequential]:** Feature-003 auth **Stage 3 [sequential]:** Feature-005 user-management **Stage 4 [parallel]:** Feature-007 notifications | Feature-008 audit-log ### Track: web ... ## Execution Plan ```yaml tracks: service: stages: - stage: 1 type: blocking features: - id: Feature-001 slug: scaffold-service depends_on: [] status: pending - stage: 2 type: sequential features: - id: Feature-003 slug: auth depends_on: [Feature-001] status: pending - stage: 3 type: sequential features: - id: Feature-005 slug: user-management depends_on: [Feature-003] status: pending - stage: 4 type: parallel features: - id: Feature-007 slug: notifications depends_on: [Feature-003] status: pending - id: Feature-008 slug: audit-log depends_on: [Feature-003] status: pending web: stages: - stage: 1 type: blocking features: - id: Feature-002 slug: scaffold-web depends_on: [] status: pending - stage: 2 type: parallel features: - id: Feature-004 slug: login-ui depends_on: [Feature-002, Feature-003] status: pending ``` **Step 7 — Update `project-status.yaml`** Add `master_plan` key: ```yaml master_plan: file: docs/master-plan.md status: ready # ready | in_progress | completed last_updated: YYYY-MM-DD tracks: service: current_stage: 1 stages: 1: type: blocking status: pending # pending | in_progress | done features: Feature-001: pending # pending | in_progress | done | blocked | error 2: type: sequential status: pending features: Feature-003: pending 3: type: sequential status: pending features: Feature-005: pending 4: type: parallel status: pending features: Feature-007: pending Feature-008: pending web: current_stage: 1 stages: 1: type: blocking status: pending features: Feature-002: pending ``` **Step 7.5 — Write `depends_on_features` back to each Feature** For every Feature in the plan, write its dependency list into the Feature's frontmatter `depends_on_features: [Feature-NNN]` (the Feature Dependency sub-artifact). This mirrors the plan's `depends_on` into the Feature file so the dependency is readable without opening the master plan. Keep the two in sync on AMEND. **Step 8 — Notify** > "Master plan ready at `docs/master-plan.md`. > - Execute automatically: run Orchestration Agent (`/orchestrate` or start agent `orchestrator`) > - Execute manually: follow track order in master plan, run `/tas-plan {Feature-ID}` then `/tas-dev {Feature-ID}` per Feature" --- ### RESUME mode (existing master plan with `status: in_progress`) 1. Read `docs/master-plan.md` YAML block — load tracks and stages 2. Read `project-status.yaml` `master_plan.tracks` — load current Feature statuses 3. Show resume summary: ``` Resuming master plan. ✅ Done: Feature-001, Feature-003 ⏳ In progress: Feature-005 ⏸ Pending: Feature-007, Feature-008, Feature-002, Feature-004 ``` 4. Update `project-status.yaml`: `master_plan.status: in_progress` 5. Notify: > "Resume from current state — run Orchestration Agent to continue auto-execution, or proceed manually." --- ### AMEND mode (invoked after ad-hoc Feature creation) Triggered when called with `AMEND` argument, or invoked inline by `/tas-feature`. **Step 1 — Read current plan state** - Read `docs/master-plan.md` YAML block — load existing tracks, stages, Feature IDs, stacks, and depends_on - Read `project-status.yaml` — get `master_plan.status` and all Feature statuses in `master_plan.tracks` - Read SAD — confirm stack dependency order **Step 2 — Collect unplanned Features** - Scan `docs/features/` directory names → extract Feature IDs from folder names - Compare against Feature IDs already in `master-plan.md` YAML block - Collect IDs not yet in plan → these are new unplanned Features - Read **only those new Feature files** — extract primary stack and AC for dependency inference - Do NOT re-read all Feature files — `master-plan.md` already has full context for planned Features **Step 3 — Determine case and re-plan** **Case A — Plan not started** (`master_plan.status: pending` or `ready`): - Collect ALL Features: existing pending + new unplanned - Re-sort by SAD dependency + inter-feature dependencies (same ordering logic as CREATE Step 5) - Rewrite full `docs/master-plan.md` YAML block - Rebuild `project-status.yaml` `master_plan.tracks` from re-sorted plan **Case B — Plan in progress** (`master_plan.status: in_progress`): - Lock `done` and `in_progress` Features in place — do not move them - Collect all `pending` Features + new unplanned Features - Re-sort pending group by SAD dependency + inter-feature dependencies - Determine insertion point per stack track based on primary stack of each new Feature - Append new stage(s) or merge into existing pending stages where dependency allows - Update `docs/master-plan.md` — replace pending stages sections only - Update `project-status.yaml` `master_plan.tracks` for affected tracks only **Step 4 — Report result** ``` Master plan updated (AMEND): + Added: Feature-{NNN} → Track: {stack}, Stage: {N} (depends_on: Feature-{X}) Pending re-sorted: {N} features across {N} tracks ``` Return to caller — do not end turn. --- ## Scaffold Content Guide When filling scaffold Feature docs in Step 3: **Description**: "[Stack] layer foundation — base project structure and cross-cutting concerns, so all business Features in [stack] share consistent structure and patterns (the foundation's value)" **Actor**: Development team **Foundation Concerns** (replaces User Flow) — ask PE via `AskUserQuestion` multiSelect: > "Which foundation concerns for [stack]?" Options: `DI container setup` / `Error handling pattern` / `Logging framework` / `Auth middleware base` / `Base configs (env, secrets)` / `Folder/module structure` / `Database connection` / `API client base` **Foundation Rules** (replaces Business Rules): patterns all business Features in [stack] must follow — naming, error shape, log format, auth contract **Design Reference**: skip for `service`/`integration`; ask for `web`/`app` **NFR**: performance baselines, security baseline applicable across all Features in stack **AC** (Given/When/Then): one AC per selected Foundation Concern. Examples: - "Given app starts, When any unhandled exception occurs, Then error handler returns `{error, message, traceId}` shape" - "Given any request, When response is 401, Then auth middleware redirects to login" ## Final Step — Token Log Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/master-plan.md`.