---
model: opus
---

# /tas-plan $ARGUMENTS

Role: SE - Software Engineer
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:** 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 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 (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 4.5 (effort baseline): set `metrics.human_time: N/A` — no human to estimate.
- 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 Feature

`$ARGUMENTS` can be: Feature ID (`Feature-005`), file path, or Feature description.

- 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 Feature ID/file
- Read Feature file

**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`.
- **On re-plan, read the current Technical file in full first and preserve human edits** — do not blindly overwrite. Regenerate the derived content but keep any SE hand-tuning (e.g. Execution Plan adjustments), merging rather than clobbering.

### Step 1.5 — Gate

If `workflow.gate_enforcement: true` in `tas.yaml` (default true): require BOTH the Feature file AND `docs/sad.md` frontmatter `artifact-status: approved` — grep only the `artifact-status:` line of each. Any fail → **STOP** naming which one and how to fix (set it to `approved`, or set `workflow.gate_enforcement: false`). If `false` → skip. In autonomous mode a failing gate still stops the run and surfaces the reason.

### Step 2 — Parallel Context Gathering

Launch 2 agents SIMULTANEOUSLY:

**Agent 1 — `code-explorer`** (always run):
> 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 per stack, what needs change, potential conflicts.

**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}".
> Do NOT read full `docs/sad.md`. Grep its headings first (`^#{1,4} `), pick only sections relevant to this Feature, Read those sections by line range. Same for `docs/adr/` — list files, read only ADRs whose title relates.
> Read `.tas/rules/common/patterns.md`.
> Return: which ADRs relate, patterns to follow, architectural risks, constraints — AND the exact SAD/ADR heading paths you read (for Context Refs).

Wait for ALL agents to finish, synthesize.

**Doc-reading rule (applies to every SAD/PRD/Design-Spec access in this command):** never Read a full doc. Grep headings (`^#{1,4} `) → choose relevant sections → Read only those by line range. Capture the heading paths you used — they become the Feature's **Context Refs**.

**Impact Analysis (if `docs/architecture-map.yaml` exists):** for the modules this Feature builds/touches, run the Impact procedure in `.tas/rules/common/architecture-map.md` (section C) — invert `depends_on` to find dependent modules + their `built_by` Features. Note the blast radius in the Technical file's Architecture Decisions / risks so regression and tech-debt are visible before coding.

### Step 3 — Ask about SAD/ADR (if still unclear)

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`.

### Step 4 — API Design (if Feature involves backend API)

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 (JSON schema examples)
- Pagination, filtering if needed
- Error codes + response format

This API Spec goes into the Technical file's **API Spec** section.

### Step 4.5 — Estimate Size + Effort Baseline + Choose Split Mode

Before drafting full content, estimate plan size from agent survey findings:

- Count stacks involved
- Estimate tasks per stack (1 task ≈ 1–2h AI coding time)

**Choose `split_mode`:**

| 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` |

State chosen mode explicitly before drafting:
> "Chosen `split_mode: {mode}`. Reason: {N stacks, ~X total tasks, Y condition}."

**Capture effort baseline** (per `.tas/rules/common/metrics.md`) — feeds the Agentic-SDLC effectiveness measurement:

- **Manual mode:** estimate `human_time` — hours this Feature would take built the **traditional way (no AI)**: full hand-coding + manual tests + review + debug + docs. Use reference-class / 3-point PERT. **LOCKED** once set. SE skips → `N/A`.
- **Autonomous mode:** set `human_time: N/A` (no human to estimate).
- Written to the Feature frontmatter `metrics.human_time` in Step 7 (not now).

### Step 5 — Draft Technical Plan (in-conversation, NOT yet written to file)

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`.

**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.

**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.
- **Web / App (UI) stack** → Read `.tas/rules/common/locator-naming.md`. Seed the `### Locator Map` table for that stack: from the AC + Logic Flow + planned components, list the interactive elements a test would target and name each `data-testid` (web) / `testID` (app) per the convention (`{prefix}_{domain}_{functional_name}`). Mark every row `Origin: plan`. **Best-effort** — list what you can confidently infer; do NOT block on completeness. `/tas-dev` back-fills any element you miss (`Origin: dev`). This Map is the SSoT later consumed by `/tas-dev` (inject) and `/tas-functest*` (consume).

**Global sections (always in index/main file, regardless of split_mode):**
- **Context Refs** — fill the table with the exact PRD/SAD/UI-UX-Design/Design-Spec/ADR heading paths gathered in Step 2–3 (the only sections relevant to this Feature). This is the contract that lets `/tas-dev` and reviewers avoid re-reading full docs. **If the Feature touches web/app UI, both the UI-UX-Design row (the `SCR-NNN` + Screen Content Map for the Feature's screens) and the Design-Spec row are MANDATORY** — the Design-Spec row points to the token system (Colors/Typography/Layout/Shapes) plus the relevant `## Components`; this is what `/tas-dev` enforces verbatim (token-refs, no inline literals) and `/tas-review` checks.
- **Modules** — fill ALL claim lines from the SAD (grep the relevant §, do not read the whole SAD). These claims feed the coverage gate, so be exact:
  - `Builds` / `Connects` from the §7 component tables — `Builds` = the **component IDs** (`MOD-03.C1, MOD-03.C2`) this Feature constructs; `Connects` = components / modules / containers it calls + protocol. Every §7 component must end up in some Feature's `Builds`.
  - `Entities (owns / uses)` from §8 — the `E-NNN` this Feature creates schema for (**owns**, one owner per entity) vs only reads (**uses**).
  - `Contracts (produces)` from §9.2 — the `IC-NN` whose Producer (MOD) this Feature builds (consumed contracts go in DO NOT CHANGE, not here).
  - `NFRs` from §11 — the `NFR-NNN` that apply to / are enforced by this Feature.
  - `Security` from §10 — the `SEC-NN` controls this Feature implements.
- **Context Diagram** — all containers involved, callers, DBs touched, external systems (Mermaid)
- **Data Flow** — end-to-end data journey across all stacks (Mermaid)
- **DO NOT CHANGE** — copy the `IC-NN` contracts this Feature **consumes** verbatim from SAD §9.2 (signatures the coding agent must not alter). Contracts it *produces* go under `## Modules > Contracts (produces)`, not here.
- **API Spec** — (only if Feature exposes new/changed interfaces) contracts between stacks
- **ERD Delta** — the schema delta vs SAD §8, referencing entities by `E-NNN`; new tables/columns/indexes for the entities this Feature **owns** (Mermaid)
- **UI Binding** *(web/app UI only — else `N/A`)* — from `Feature Spec.Design Reference` + `UI/UX Design.Generated Screens`: list each `SCR-NNN`, its reuse mode (`pixel-perfect` → the Generated Screen file to copy | `build`), and the component/token/breakpoint **IDs** that apply. **Re-validate the Feature Spec's Reuse choice — do not carry it forward blindly.** `pixel-perfect` is the default; `build` is justified only when the Generated Screen truly cannot render a state this Feature needs. **A data/API-contract mismatch (mock fields/roles differ from the real schema) does NOT justify `build`** — the real data is wired in regardless of Reuse mode, so the layout still gets copied and only the data-wiring code differs. If the Feature Spec set `build` for a data-mismatch reason, correct it to `pixel-perfect` here and note the override in `Architecture Decisions`. Carry **selection + IDs only** — never restate token/component definitions (those live once in `docs/design-spec.md` and are built once into the codebase design system by `/tas-dev`; code references by ID). **Asset check:** for each `SCR-NNN`, confirm every brand asset its tokens/HTML reference (font files, logo/SVG) has a corresponding File Changes task to bundle it into the app (e.g. `@font-face`/`next/font` load, logo component) — a token that names an asset nobody bundles is a gap `/tas-dev` must not repeat.
- **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

**Per-stack / per-part detail sections — location depends on split_mode:**

| 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. |

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.

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).

### Step 6 — Wait for approval

- **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.

### Step 7 — Write Technical file

After approval:

**1. Write Technical file(s)** in same directory as Feature file:

**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`, `artifact-status: draft`, `split_mode: single`
- Fill all global sections + all involved stack sections

**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

**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 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}`
- `features.{FEATURE_ID}.plan_status: completed`
- `features.{FEATURE_ID}.technical_file: {path}`
- `features.{FEATURE_ID}.builds: [component IDs]` — the components (`MOD-NN.C#`) this Feature constructs (from the `## Modules > Builds` line), so done-time coverage (`/tas-status`) can roll up without reopening the Technical file

**4. Update `docs/architecture-map.yaml`** per `.tas/rules/common/architecture-map.md` — record this Feature as the claimant for every design item it owns, so the coverage ledger closes:
- **Components:** for each `MOD-NN.C#` in `Builds`, add this Feature to that component's `built_by` (and the module's roll-up).
- **Entities:** for each `E-NNN` in `Entities (owns)`, set that entity's `owner: {FEATURE_ID}` in the `entities` ledger.
- **Contracts:** for each `IC-NN` in `Contracts (produces)`, set that contract's `producer: {FEATURE_ID}` in the `contracts` ledger.
- **NFRs:** for each `NFR-NNN` in `NFRs`, add this Feature to that NFR's `addressed_by` in the `nfrs` ledger.
- **Security:** for each `SEC-NN` in `Security`, add this Feature to that control's `addressed_by` in the `security` ledger.
- (As-built fields — `code_anchor`, `provides`, `status: built`, `tests` — are filled by `/tas-dev` write-back, not here.)

**5. 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

**6. Write Feature metrics** (per `.tas/rules/common/metrics.md`):
- Set `metrics.human_time` in the Feature frontmatter (the locked value from Step 4.5, or `N/A` in autonomous mode). Leave `metrics.ai_time` empty — `/tas-dev` accumulates it.
- Mirror into `project-status.yaml`: `features.{FEATURE_ID}.metrics.human_time`.

### 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)

For: solo dev, prototype, spike, urgent hotfix.

- `/tas-dev` will NOT require running `/tas-plan` first
- `/tas-plan` can still be run voluntarily when Feature is complex
- Trade-off: higher speed, lower traceability

## Principles
- **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 Feature file.